zai-rs 0.5.0

一个 Rust SDK, 用于调用 智谱AI API
Documentation

zai-rs

一个简洁、类型安全的 Zhipu AI Rust SDK。专注提升 Rust 开发者的接入效率：更少样板代码、更一致的错误处理、可读的请求/响应类型，以及开箱即用的示例。

0.5 release candidate — main 分支包含 0.5 的 breaking release candidate。crates.io 当前公开版本为 0.2.0。安装 main 分支版本：zai-rs = { git = "https://github.com/AnlangA/zai-rs", branch = "main" }。迁移指南见 docs/MIGRATING-0.5.md。

快速开始

  1. 准备环境
    • Rust 1.88+（edition 2024）
    • 设置环境变量：ZHIPU_API_KEY="<your_api_key>"
  2. 构建
    • cargo build
  3. 运行示例（examples/ 目录内）
    • cargo run --example chat_loop

更多设计和维护说明见 架构说明，完整使用文档见 docs/。

支持的模型

文本模型

模型 结构体 Thinking ReasoningEffort Async ToolStream
glm-5.2 GLM5_2 ✓ ✓ ✓ ✓
glm-5.1 GLM5_1 ✓ ✗ ✓ ✓
glm-5 GLM5 ✓ ✗ ✓ ✓
glm-5-turbo GLM5_turbo ✓ ✗ ✓ ✓
glm-4.7 GLM4_7 ✓ ✗ ✓ ✓
glm-4.7-flash GLM4_7_flash ✓ ✗ ✓ ✗
glm-4.7-flashx GLM4_7_flashx ✓ ✗ ✓ ✗
glm-4.6 GLM4_6 ✓ ✗ ✓ ✓
glm-4.5 GLM4_5 ✓ ✗ ✓ ✗
glm-4.5-X GLM4_5_x ✓ ✗ ✓ ✗
glm-4.5-air GLM4_5_air ✓ ✗ ✓ ✗
glm-4.5-airx GLM4_5_airx ✓ ✗ ✓ ✗
glm-4.5-flash GLM4_5_flash ✓ ✗ ✓ ✗

文本视觉模型

模型 结构体
autoglm-phone autoglm_phone
glm-5v-turbo GLM5V_turbo
glm-4.6v GLM4_6v
glm-4.6v-flash GLM4_6v_flash
glm-4.6v-flashx GLM4_6v_flashx
glm-4.5v GLM4_5v

语音模型

模型 结构体
glm-4-voice GLM4_voice

示例（examples/）

可用示例

示例 描述
chat_text 基础文本对话
chat_stream 流式响应
chat_loop 多轮对话循环
chat_coding_plan 编程辅助对话（coding 专属端点）
coding_plan_usage Coding Plan 余量 / 额度查询
chat_vision 视觉模型对话（图片/视频）
chat_voice 语音模型对话
async_chat_text 异步对话任务提交与轮询
glm45_thinking_mode 深度思考模式
glm52_reasoning_effort GLM-5.2 推理深度控制（reasoning_effort）
tool_stream_min 流式工具调用
function_call 函数调用
function_call_with_toolkits 工具集调用
translation_bot 翻译机器人
ocr OCR 手写文字识别
gen_image 图像生成
gen_video 视频生成
text_to_audio 文本转语音
audio_to_text 语音转文字
voice_clone 音色复刻
embedding 文本嵌入
files_upload 文件上传
knowledge_create 知识库创建
web_search 网络搜索
batches_create 批处理任务创建
batches_cancel 批处理任务取消

运行方式

# Windows PowerShell
$Env:ZHIPU_API_KEY = "<your_api_key>"
cargo run --example chat_loop

# macOS/Linux
export ZHIPU_API_KEY="<your_api_key>"
cargo run --example chat_loop

API 覆盖度

模型 API

  • POST 对话补全（同步/异步/流式）
  • GLM-5.2 / GLM-5.1 / GLM-5 / GLM-4.7 / GLM-4.6 / GLM-4.5 系列支持
  • 思考模式（Thinking Mode），支持 clear_thinking 保留式思考
  • 推理深度控制（Reasoning Effort，GLM-5.2+：max/xhigh/high/medium/low/minimal/none）
  • 流式工具调用（Tool Stream）
  • 图像生成
  • 视频生成（异步）
  • 语音转文本
  • 文本转语音
  • 音色复刻/列表/删除
  • 文本嵌入/重排序/分词
  • OCR 手写识别

工具 API

  • POST 网络搜索
  • POST 内容安全
  • POST 文件解析
  • GET 解析结果

文件 API

  • GET 文件列表
  • POST 上传文件
  • DELETE 删除文件
  • GET 文件内容

批处理 API

  • GET 列出批处理任务
  • POST 创建批处理任务
  • GET 检索批处理任务
  • POST 取消批处理任务

知识库 API

  • GET 知识库列表
  • POST 创建知识库
  • GET 知识库详情
  • PUT 编辑知识库
  • DELETE 删除知识库
  • GET 知识库使用量
  • GET 文档列表
  • POST 上传文件文档
  • POST 上传 URL 文档
  • GET 文档详情
  • DELETE 删除文档
  • POST 重新向量化

Coding Plan API

  • POST 编程辅助对话（/api/coding/paas/v4，专属端点）
  • GET 余量 / 额度查询（/api/monitor/usage/quota/limit，5 小时窗口 + 每周窗口）
use zai_rs::usage::CodingPlanUsageRequest;

# async fn go(key: String) -> zai_rs::ZaiResult<()> {
let resp = CodingPlanUsageRequest::new(key).send().await?;
if let Some(window) = resp.time_limit() {
    println!("5h 余量: {}/{}", window.remaining(), window.number);
}
# Ok(())
# }

实时 API

  • WebSocket 类型定义
  • 会话管理框架（RealtimeClient / SessionBuilder）
  • Bearer / JWT 双鉴权
  • 完整 client/server 事件（ClientEvent / ServerEvent）
  • 音视频通话高级封装（待完善）