RustGLM - 智谱 AI 自然语言大模型 Zhipu ChatGLM Rust SDKRustGLM 是面向智谱 AI 开放平台的优秀高效的非官方异步 Rust SDK提供强类型 GLM-5 请求、SSE 和 ToolStream 聚合、双向 Realtime WebSocket 会话、Batch API 操作、知识库管理以及基于官方 Rust MCP SDK 的 MCP 客户端。RustGLM 项目面向生产后端。网络策略、持久化、凭据、重试和客户端生命周期均由应用显式控制。已废弃旧RustGLM 0.1.x的版本目前最新的 RustGLM 1.0.0 已发表至Crates.io上。快速开始添加默认 SDK 与 Tokio 运行时[dependencies] rustglm 1.0.0 tokio { version 1, features [macros, rt-multi-thread] }设置凭据并运行补全示例$env:ZHIPU_API_KEY key_id.secretcargo run--example chat_completionuse rustglm::{ChatCompletionRequest, ChatMessage, ZhipuClient}; # async fn run() - rustglm::Result() { let client ZhipuClient::new(key_id.secret)?; let request ChatCompletionRequest::new(glm-5.2) .message(ChatMessage::user(用一段话解释 Rust 所有权。)); let response client.chat_completion(request).await?; println!({}, response.text().unwrap_or_default()); # Ok(()) # }要求Rust 1.88 或更高版本Rust 2024 Edition用于异步执行的 Tokio智谱 API Key或已签发的智谱 Bearer tokenCargo 包名和 Rust crate 名均为rustglm。副作用契约RustGLM 不会进行隐式磁盘 I/O。库不会创建目录、查找配置文件、写入日志、缓存响应、持久化对话或保存音视频。文件与 RAG 上传 API 接收调用方拥有的字节数据内部绝不打开文件路径。响应、SSE 帧、Realtime 媒体、内存快照和工具事件始终保留在内存或异步流中。库不会从环境变量读取 API Key凭据由构造函数传入。EnvironmentSecretResolver是显式启用的 Agent 工具。库从不访问 NTP、元数据、遥测或模型发现服务JWT 签名仅使用本机系统时钟。HTTP 默认重试次数为零MCP SSE 重试和过期会话自动初始化默认关闭。构造配置值不产生网络 I/O。智谱请求只会在等待端点方法时发出MCP 或 Realtime 连接只会在等待connect时建立。examples 示例演示文件夹 里面的方法可能显式读取环境变量或本地文件。这些属于应用层行为并非 SDK 执行。Feature flags默认 feature 保留广泛的智谱 API 能力同时使独立 MCP 协议客户端保持按需启用。Feature默认启用API 能力agents是官方 Agent、Assistant 端点和本地 Agent 运行时audio是GLM-4-Voice、转录、语音和音色操作batch是强类型 Batch API 创建、列表、查询和取消files是文件上传、下载、删除、解析、OCR 和版面分析images是图像生成mcp否基于rmcp的独立 Streamable HTTP MCP 客户端rag是Retrieval Agent、知识库与文档管理realtime是强类型双向 WebSocket 客户端tools是托管工具类型、Web 操作和 ToolStream 聚合video是视频生成full否启用包括mcp在内的全部 feature最小 HTTP 聊天客户端[dependencies] rustglm { version 1.0.0, default-features false } tokio { version 1, features [macros, rt-multi-thread] }选择部分企业 API[dependencies] rustglm { version 1.0.0, default-features false, features [batch, mcp, rag, realtime, tools] } tokio { version 1, features [macros, rt-multi-thread] }全部 API[dependencies] rustglm { version 1.0.0, features [full] }认证ZhipuClient::new、ZhipuConfig::new和RealtimeConfig::new均直接接收凭据。key_id.secret被视为智谱组合 API Key并签名为 HS256 JWT。任何其他非空值均被视为不透明 Bearer token。自动选择不合适时可使用ZhipuAuthentication::jwt或ZhipuAuthentication::bearer。请勿提交凭据。应用应自行从进程环境、密钥管理器或工作负载身份提供方读取密钥。强类型 GLM-5 聊天标记类型、封闭能力 trait 和请求 typestate 会阻止通过强类型 API 发送不支持的操作。请求在包含用户或工具输入前无法传给强类型补全方法。use rustglm::{Glm52, ReasoningEffort, Thinking, TypedChatRequest, ZhipuClient}; # async fn run() - rustglm::Result() { let client ZhipuClient::new(key_id.secret)?; let request TypedChatRequest::Glm52::new() .system(Answer with evidence.) .thinking(Thinking::enabled()) .reasoning_effort(ReasoningEffort::High) .user(Summarize the incident report.); let response client.typed_chat_completion(request).await?; println!({}, response.text().unwrap_or_default()); # Ok(()) # }支持的聊天模型下表描述编译期强类型 API。新发布或私有模型 ID 仍可通过原始ChatCompletionRequest使用。文本模型标记类型ThinkingReasoning effortToolStreamglm-5.2Glm52是是是glm-5.1Glm51是否是glm-5.1-highspeedGlm51Highspeed是否是glm-5-turboGlm5Turbo是否是glm-5Glm5是否是glm-4.7Glm47是否是glm-4.7-flashGlm47Flash是否否glm-4.7-flashxGlm47FlashX是否否glm-4.6Glm46是否是glm-4.5-airGlm45Air是否否glm-4.5-airxGlm45AirX是否否glm-4.5-flashGlm45Flash是否否glm-4-flash-250414Glm4Flash250414否否否glm-4-flashx-250414Glm4FlashX250414否否否视觉模型标记类型ThinkingToolStreamglm-5v-turboGlm5vTurbo是否autoglm-phoneAutoGlmPhone否否glm-4.6vGlm46v是否glm-4.6v-flashGlm46vFlash是否glm-4.6v-flashxGlm46vFlashX是否glm-4v-flashGlm4vFlash否否glm-4.1v-thinking-flashGlm41vThinkingFlash是否glm-4.1v-thinking-flashxGlm41vThinkingFlashX是否ReasoningEffort、Thinking、ToolStream、工具和视觉输入只会暴露给声明相应能力的标记类型从而阻止不受支持的字段通过强类型 API 到达传输层。当新发布字段尚未获得强类型 builder 时ChatCompletionRequest仍可作为前向兼容的原始请求使用。ToolStreamToolStream 将碎片化 SSE 函数调用增量合并为完整的强类型调用同时保留文本、推理、用量和流错误。use futures_util::StreamExt; use rustglm::{Glm52, ToolStreamEvent, TypedChatRequest, ZhipuClient}; # async fn run() - rustglm::Result() { let client ZhipuClient::new(token)?; let request TypedChatRequest::Glm52::new().tool_stream().user(Check the deployment status.); let mut stream client.typed_chat_tool_stream(request).await?; while let Some(event) stream.next().await { if let ToolStreamEvent::ToolCallCompleted(call) event? { println!({} {}, call.name, call.arguments); } } # Ok(()) # }Batch APIbatchfeature 提供强类型补全窗口和状态。Batch 输入文件通过filesAPI 显式上传。use rustglm::{BatchCreateRequest, ZhipuClient}; # async fn run() - rustglm::Result() { let client ZhipuClient::new(token)?; let request BatchCreateRequest::new(input-file-id, /v4/chat/completions); let batch client.create_batch(request).await?; let current client.batch(batch.id).await?; println!({:?}, current.status); # Ok(()) # }可用方法为create_batch、batches、batch和cancel_batch。不在1..100范围内的列表限制会在网络 I/O 前返回BatchError::InvalidLimit。知识库与 RAGragfeature 遵循官方知识库 OpenAPI 路径涵盖知识库 CRUD、容量、检索、文档列表和详情、内存文件上传、URL 摄取、删除、文档图片和重新嵌入。RagDocumentUpload::from_bytes有意不提供基于路径的构造函数调用方控制文件读取、大小限制、加密、租户边界和保留策略。use rustglm::{KnowledgeCreateRequest, KnowledgeEmbeddingModel, ZhipuClient}; # async fn run() - rustglm::Result() { let client ZhipuClient::new(token)?; let created client.create_knowledge_base(KnowledgeCreateRequest::new( engineering-runbooks, KnowledgeEmbeddingModel::Embedding3Pro, )).await?; println!({}, created.data.expect(successful response).id); # Ok(()) # }MCP 客户端mcpfeature 是独立的 Model Context Protocol 客户端与在模型请求中配置托管 MCP 工具的McpTool不同。协议帧、初始化、工具、资源、提示词和 Streamable HTTP 传输由官方 Rust MCP SDKrmcp提供。use rustglm::McpClientConfig; # async fn run() - rustglm::Result() { let mut client McpClientConfig::new(https://mcp.example.com/mcp) .bearer_token(tenant-token).header(x-tenant-id, acme)?.connect().await?; for tool in client.list_tools().await? { println!({}, tool.name); } client.close().await?; # Ok(()) # }安全默认值仅接受绝对http和https端点授权显式配置并从Debug输出中脱敏SDK 创建的 HTTP 客户端禁用重定向SSE 重试和过期会话自动初始化默认关闭可注入调用方配置的reqwest::Client控制代理、TLS、DNS、超时和策略。Realtime WebSocketrealtimefeature 通过双向 WebSocket 提供强类型客户端请求和服务器事件。音视频作为调用方拥有的字节切片传入并在内存中编码。use rustglm::{RealtimeConfig, RealtimeRequest, TypedRealtimeSession}; # async fn run() - rustglm::Result() { let mut connection RealtimeConfig::new(token).connect().await?; let session TypedRealtimeSession::default().instructions(Be concise.).server_vad(); connection.send_request(RealtimeRequest::session_update(session)?).await?; connection.send_request(RealtimeRequest::append_audio([0_u8; 320])?).await?; while let Some(event) connection.next_typed_event().await { if let Some(text) event?.delta_text() { print!({text}); } } # Ok(()) # }该 API 还支持强类型会话工具、函数调用输出、响应选项、转录会话、客户端/服务端 VAD、取消、音频提交/清空、视频帧和显式关闭连接。错误SdkError是RustGLM重要的一个部分其公共错误封装。领域错误是显式枚举可直接匹配无需解析展示字符串。userustglm::{BatchError,SdkError};fnclassify(error:SdkError){matcherror{SdkError::Batch(BatchError::InvalidLimit(limit))eprintln!(invalid batch limit: {limit}),SdkError::Api(api)eprintln!(HTTP {} request_id{:?},api.status,api.request_id),othereprintln!({other}),}}该封装区分配置、校验、传输、超时、API、解码、流、WebSocket、不支持能力、Agent、工具、Batch、RAG 和 MCP 失败。ApiError保留 HTTP 状态、厂商代码、消息、请求 ID 和原始响应体。HTTP 策略HttpConfig控制请求超时、连接超时、连接池空闲超时、user agent、默认请求头、重试策略以及可选的调用方构建reqwest::Client。重试默认关闭。启用RetryPolicy是应用的显式决定只有配置的状态码及连接/超时失败会被重试。API 覆盖范围下表是公开 SDK 操作的索引依据公开客户端接口整理而非假定服务商能力。接受serde_json::Value的方法有意保留与快速变化的服务商 Schema 的兼容性。能力领域Feature公开方法聊天与流核心ToolStream 需toolschat_completion、chat_completion_stream、chat_tool_stream、typed_chat_completion、typed_chat_completion_stream、typed_chat_tool_stream异步与向量 API核心async_chat、async_result、embedding、rerank、tokenizer图像与视频images、videocreate_image、create_image_async、create_video音频与音色audioglm_4_voice、transcribe、speech、clone_voice、voices、delete_voice托管工具toolsweb_search、read_web_page、moderate文件与文档处理filesupload_file、files、file_content、delete_file、create_file_parse_task、file_parse_result、parse_file_sync、ocr、parse_layoutBatchbatchcreate_batch、batches、batch、cancel_batch官方 Agent 与 Assistantagentsofficial_agent、official_agent_stream、official_agent_async_result、official_agent_conversation、assistant、assistants、assistant_conversations知识库与检索ragcreate_knowledge_base、knowledge_bases、knowledge_base、update_knowledge_base、delete_knowledge_base、knowledge_capacity、retrieve_knowledge、knowledge_documents、upload_knowledge_document、upload_knowledge_urls、knowledge_document、delete_knowledge_document、knowledge_document_images、reembed_knowledge_document、retrieval_agent_stream通用协议入口核心ZhipuClient与OpenAiCompatibleClient上的request_json独立 MCPmcpMcpClientConfig::connect以及由rmcp提供的强类型工具、资源、提示词和 Streamable HTTP 操作RealtimerealtimeRealtimeConfig::connect、强类型请求/事件、VAD、媒体缓冲、函数调用输出、取消与显式关闭服务商已发布字段尚未获得强类型 builder 时使用ChatCompletionRequest。只有在配置好的服务商 Base URL 下需要新相对路径时才使用request_json它会拒绝绝对 URL 与父级路径段。RustGLM 则提供服务商无关的本地 Agent 运行时、OpenAI 兼容客户端、通用rmcp协议客户端和支持视频的 Realtime 会话。示例仓库包含 36 个可运行 rust examples 示例。当前每个 HTTP 端点领域都有聚焦示例通常一起使用的操作会放进同一个生命周期示例。cargo check --all-targets --all-features可在不联系服务商的情况下编译检查全部示例。聊天、模型与向量示例演示的公开 APIchat_completionchat_completionchat_streamchat_completion_streamtyped_chattyped_chat_completion、Thinking、推理强度multimodal_chat视觉内容片段与图片 URL 输入function_calling函数 Schema 与Tool::functiontool_streamtyped_chat_tool_stream与聚合后的函数调用增量async_chatasync_chat、async_resultembeddingEmbeddingRequest、embeddingrerankRerankRequest、reranktokenizerTokenizerRequest、tokenizeropenai_compatibleOpenAiCompatibleConfig、ChatProvider媒体、文件与文档处理示例演示的公开 APIimage_generationcreate_image、create_image_asyncvideo_generationcreate_video、异步任务 IDspeechSpeechRequest、speechtranscriptionTranscriptionRequest、transcribeglm_4_voiceGLM-4-Voice 输入与 WAV 输出voice_managementclone_voice、voices、delete_voicefile_managementupload_file、files、file_content、delete_filefile_parsingcreate_file_parse_task、file_parse_result、parse_file_syncdocument_understandingocr、parse_layoutBatch、托管工具与 RAG示例演示的公开 APIweb_searchweb_searchhosted_toolsread_web_page、moderatefile_batch上传 JSONL 并调用create_batchbatch_managementBatch 创建、列表、查询和取消knowledge_basecreate_knowledge_baseknowledge_management知识库列表、详情、更新、容量与删除knowledge_documents文档列表、上传、URL 导入、详情、图片、重嵌入与删除knowledge_retrievalretrieve_knowledgeretrieval_agentretrieval_agent_streamAgent、MCP 与 Realtime示例演示的公开 APIofficial_agent强类型官方 Agent v1 调用official_agent_lifecycleAgent 流、异步结果与会话操作assistantsAssistant 调用、列表与会话custom_agent带应用工具的本地 Agent 运行时interactive_chat多轮运行时与可选语义记忆mcp_clientMCP 工具、资源、提示词与关闭连接realtime_audio_videoRealtime PCM/WAV、可选 JPEG 帧与强类型事件通过cargo run --example name -- 参数运行示例。MCP 客户端为按需 feature请使用cargo run --example mcp_client --features mcp -- endpoint。大多数智谱示例需要ZHIPU_API_KEYopenai_compatible使用OPENAI_COMPATIBLE_BASE_URL与OPENAI_COMPATIBLE_API_KEY。运行示例可能消耗额度、创建远程资源或删除命令行中明确指定的资源。CI 与发布CI 工作流 验证格式化将警告视为错误的 Clippy无默认 feature、默认 feature、全部 feature 和单独企业 feature 构建测试和 doctest将警告视为错误的文档构建从已提交 lockfile 构建包全 feature 行覆盖率不低于 90%并上传 LCOV 与文本摘要。发布工作流会在v*tag 推送时运行。手动运行时请在 Actions 页面选择要发布的提交或分支并在tag输入中填写vCargo.toml version。工作流会检出页面所选版本不再假定 tag 已经存在它会拒绝版本不匹配执行全部发布门禁构建.crate、写入SHA256SUMS然后创建缺失的附注 tag。已有 tag 只有在指向本次验证的提交时才会被接受。最后工作流会在配置CARGO_REGISTRY_TOKEN时可选发布到 crates.io并创建或更新 GitHub Release。发布步骤# 请先更新 Cargo.toml 与发布说明Cargo.toml 当前版本为 1.0.0。gittag-sv1.0.0-mRustGLM v1.0.0gitpush origin v1.0.0也可以在main分支上手动运行Release工作流并将tag填为v1.0.0无需预先创建 tag。tag 使用普通的v1.0.0格式而不是RustGLM v1.0.0。仓库中不保存 API Key 或 registry token。仅在需要发布 crates.io 时将CARGO_REGISTRY_TOKEN配置为 GitHub Actions secret。测试与覆盖率cargofmt--all----checkcargotest--all-targets --no-default-featurescargotest--all-targetscargotest--all-targets --all-featurescargoclippy --all-targets --all-features ---DwarningsRUSTDOCFLAGS-D warningscargodoc --all-features --no-depscargopackage--locked仓库提供统一覆盖率命令并由 CI 强制执行最低门槛cargocoverage# 输出摘要并检查 90% 行覆盖率门槛cargocoverage-lcov# 生成 target/rustglm-lcov.info并检查相同门槛最近一次工作区实测快照2026-07-24测试RegionsFunctionsLines行覆盖率门槛94 个通过、2 个真实服务测试忽略92.72%88.33%94.02%90.00%全 feature 测量包含所有库模块包括可选的 MCP 与 Realtime。知识库/RAG 行覆盖率为 96.63%成功的 MCP 协议操作需要已初始化的对端因此其离线行覆盖率为 51.60%。完整模块表、指标解释与 HTML 报告命令见 COVERAGE.md。覆盖率命令会运行离线单元测试与集成测试并编译全部 36 个示例但不会执行示例的main函数也不会运行被忽略的真实服务测试。请显式运行需要凭据的检查$env:ZHIPU_API_KEY key_id.secretcargo test--test live_zhipu----ignored--nocapture cargo test--test live_realtime----ignored--nocaptureCI 会重新生成数据并将lcov.info与coverage-summary.txt发布为构建产物评估具体提交时应以该产物为准不应把上面的快照视为永久承诺。官方 API 参考快速开始错误码许可证Apache License 2.0。参见 LICENSE。