AI SDK 集成 Z.AI GLM 模型：@ai-sdk/zai 提供者完整实战指南

AI SDK 集成 Z.AI GLM 模型ai-sdk/zai 提供者完整实战指南【免费下载链接】aiThe AI Toolkit for TypeScript. From the creators of Next.js, the AI SDK is a free open-source library for building AI-powered applications and agents项目地址: https://gitcode.com/GitHub_Trending/ai/ai本指南围绕 AI SDKThe AI Toolkit for TypeScript中的 Z.AI 官方提供者ai-sdk/zai展开讲解如何通过该包接入 Z.AI 的 GLM 系列语言与视觉模型覆盖安装配置、Provider 实例化、语言模型调用、Z.AI 专属 Provider Options、流式工具调用等完整链路并结合仓库源码与测试用例揭示底层请求转换与参数映射原理。读完本文你将能够在 TypeScript 项目中直接调用zai(glm-5.3)完成文本生成、流式输出、推理reasoning、函数调用与图像/视频理解。一、Z.AI Provider 是什么ai-sdk/zai是 AI SDK 官方维护的 Z.AI 提供者包为 Z.AI 的 GLM 语言模型提供开箱即用的 AI SDK 接入能力。它遵循 AI SDK 统一的 Provider 抽象让你可以用与 OpenAI、Anthropic 等提供者完全一致的generateText、streamText、generateObjectAPI 来调用 GLM 模型而不必手写 HTTP 请求与流式解析逻辑。在仓库中该包位于 packages/zai核心说明文档为 packages/zai/README.md官方 Provider 文档位于 content/providers/01-ai-sdk-providers/200-zai.mdx。此外AI SDK 还为 Vercel 部署场景提供了 AI Gateway 方案可在不安装额外 Provider 包的情况下访问 Z.AI 及数百家模型。二、安装与 API Key 配置2.1 安装依赖在项目中安装 Z.AI 提供者npm i ai-sdk/zai安装后同时需要确保项目中存在 AI SDK 核心包ai提供generateText、streamText等高层 API。从 packages/zai/package.json 可以看到该包的运行时依赖为ai-sdk/openai-compatible、ai-sdk/provider、ai-sdk/provider-utils并以zod^3.25.76 || ^4.1.8作为 peer dependency 用于 Provider Options 的运行时校验。2.2 设置环境变量默认情况下Provider 会从ZAI_API_KEY环境变量读取 API KeyZAI_API_KEYyour-api-keyAPI Key 可在 Z.AI 的 API Key 控制台中创建。源码层面Key 的加载由 zai-provider.ts 中的loadApiKey完成它优先使用createZai显式传入的apiKey否则回退到ZAI_API_KEY环境变量读取后以Bearer令牌形式放入Authorization请求头并自动追加ai-sdk/zai/${VERSION}的 User-Agent 后缀。三、创建 Provider 实例3.1 使用默认实例ai-sdk/zai导出了一个默认实例zai直接导入即可使用import { zai } from ai-sdk/zai;该默认实例等价于createZai()见 zai-provider.ts因此它会读取ZAI_API_KEY环境变量。3.2 使用 createZai 自定义配置当需要显式配置 API Key、自定义网关地址或拦截请求时使用createZaiimport { createZai } from ai-sdk/zai; const zai createZai({ apiKey: process.env.ZAI_API_KEY, });createZai接受以下可选配置定义见 zai-provider.ts配置项类型默认值说明apiKeystringZAI_API_KEY环境变量用于Authorization请求头的 API KeybaseURLstringhttps://api.z.ai/api/paas/v4API 请求的 URL 前缀可用于对接代理或网关headersRecordstring, string无追加到每次请求的自定义请求头fetchFetchFunction全局fetch自定义 fetch 实现可在中间件中拦截请求值得注意的实现细节createZai内部会调用withoutTrailingSlash去除baseURL末尾的斜杠见 zai-provider.ts随后把路径拼接交给语言模型层完成。该行为在 zai-provider.test.ts 中有明确测试传入https://example.com/zai/后最终请求地址为https://example.com/zai/chat/completions。3.3 Provider 的能力边界从 zai-provider.ts 的类型定义与 zai-provider.test.ts 的测试可以看出支持zai(model-id)函数式调用以及等价的zai.languageModel(model-id)、zai.chat(model-id)specificationVersion为v4即实现 AI SDK 的 LanguageModelV4 规范不支持embedding 模型与 image 生成模型调用embeddingModel、textEmbeddingModel、imageModel会抛出NoSuchModelError。四、语言模型调用4.1 文本生成将模型 ID 传给 Provider 即可获得语言模型实例配合 AI SDK 的generateText使用import { zai } from ai-sdk/zai; import { generateText } from ai; const { text } await generateText({ model: zai(glm-5.3), prompt: Explain why the sky is blue., }); console.log(text);4.2 支持的模型 ID仓库 zai-chat-options.ts 根据 Z.AI 官方 OpenAPI 1.0.0 规范2026-08-26 获取收录了以下模型 ID模型系列模型 IDGLM 5 系列glm-5.3、glm-5.3-flash、glm-5.2、glm-5.1、glm-5-turbo、glm-5GLM 4.7 系列glm-4.7、glm-4.7-flash、glm-4.7-flashxGLM 4.6 系列glm-4.6GLM 4.5 系列glm-4.5、glm-4.5-air、glm-4.5-x、glm-4.5-airx、glm-4.5-flashGLM 4 兼容glm-4-32b-0414-128kGLM 视觉模型glm-5v-turbo、glm-4.6v、glm-4.6v-flash、glm-4.6v-flashx、glm-4.5v多语言语音模型autoglm-phone-multilingual类型定义为(string {})联合意味着字符串类型的模型 ID 也能通过类型检查便于接入官方目录中的新模型。实际可用的模型目录会随时间变化以 Z.AI 官方模型文档为准。4.3 支持的能力从 README、官方 Provider 文档以及模型实现类 zai-chat-language-model.ts 可以确认Provider 支持文本生成与流式输出generateText/streamText推理输出reasoning与推理历史保留函数调用function calling包括增量式工具调用参数流式传输JSON 对象输出可与generateObject配合兼容 GLM 视觉模型上基于 URL 的图像与视频输入。其中 URL 图像/视频输入的底层支持来自 zai-chat-language-model.ts 的supportedUrls配置image/*与video/*类型的媒体均允许https?://开头的远程 URL。五、Z.AI Provider Options 详解Z.AI 特有参数通过 AI SDK 的providerOptions.zai传入Schema 定义见 zai-chat-language-model-options.ts这些参数会在请求发出前经过 zod 校验不合法时会抛出invalid zai provider options错误见 zai-chat-language-model.test.ts。5.1 参数总览参数类型说明doSampleboolean是否启用采样。禁用时temperature、topP不生效thinking{ type?: enabled \| disabled; clearThinking?: boolean }控制模型思考模式clearThinking: false时保留此前助手消息中的推理内容reasoningEffortnone \| minimal \| low \| medium \| high \| xhigh \| max控制推理强度适用于 GLM-5.2 及更新模型toolStreamboolean在支持的模型上启用函数调用参数的增量流式输出requestIdstring664 字符调用方提供的请求标识userIdstring6128 字符非敏感的用户标识用于跟踪与审计5.2 完整示例import { zai } from ai-sdk/zai; import { generateText } from ai; const result await generateText({ model: zai(glm-5.3), prompt: Compare two approaches to implementing a rate limiter., providerOptions: { zai: { thinking: { type: enabled, clearThinking: true }, reasoningEffort: high, requestId: request-123456, userId: user-123456, }, }, });5.3 请求体映射原理这些参数并非原样透传。模型类中的transformZaiRequestBodyzai-chat-language-model.ts会将 AI SDK 风格命名转换为 Z.AI API 的 snake_case 字段doSample→do_samplethinking.type→thinking.typethinking.clearThinking→thinking.clear_thinkingtoolStream→tool_streamrequestId→request_iduserId→user_id这一映射在 zai-chat-language-model.test.ts 中有完整验证最终请求体同时包含reasoning_effort字段由标准参数reasoning透传而来。六、流式输出与增量工具调用6.1 流式文本与推理streamText与doStream的配合由模型类的doStream方法zai-chat-language-model.ts处理它在 AI SDK 的流式结果上挂接一个TransformStream用于在stream-start阶段注入兼容性警告、在finish阶段统一映射结束原因。测试zai-chat-language-model.test.ts验证了流中包含reasoning-start、reasoning-delta、text-delta、raw、finish等完整事件序列且流式场景不发送stream_options字段。6.2 流式工具调用toolStream当工具参数较长时逐块增量到达能显著改善首 token 延迟体验。启用方式import { zai } from ai-sdk/zai; import { streamText, tool } from ai; import { z } from zod; const result streamText({ model: zai(glm-5.3), prompt: What is the weather in San Francisco?, tools: { weather: tool({ description: Get the weather for a city, inputSchema: z.object({ city: z.string() }), }), }, providerOptions: { zai: { toolStream: true }, }, }); for await (const part of result.fullStream) { console.log(part); }开启toolStream后请求体会携带tool_stream: true。底层测试zai-chat-language-model.test.ts模拟了工具参数{city与:Paris}分两块到达的场景验证流会依次产出tool-input-start、tool-input-delta、tool-input-end最终合并为完整的tool-callinput: {city:Paris}并以tool-calls作为结束原因。6.3 工具选择toolChoice的处理策略zai-chat-language-model.ts 展示了 Z.AI 在工具选择上的两个特殊处理toolChoice: { type: none }直接移除tools与toolChoice确保模型不会调用任何工具其他非auto的toolChoice如requiredZ.AI 目前仅支持自动工具选择因此会发出unsupported警告并降级为自动选择。七、标准参数的兼容性边界使用过程中需要注意以下 AI SDK 标准参数在 Z.AI 提供者中不受支持传入时会被移除并产生unsupported类型警告而非报错frequencyPenaltypresencePenaltyseed上述行为由prepareCallOptionszai-chat-language-model.ts实现并在 zai-chat-language-model.test.ts 中验证最终请求体不包含frequency_penalty、presence_penalty、seed字段且result.warnings中带有对应的警告条目。八、底层实现与错误处理8.1 基于 OpenAI 兼容基类ZaiChatLanguageModel继承自OpenAICompatibleChatLanguageModel来自ai-sdk/openai-compatible见 zai-chat-language-model.ts因此复用了一套成熟的 OpenAI 兼容请求/响应解析管线并通过以下定制点适配 Z.AIurl${baseURL}${path}即默认打到https://api.z.ai/api/paas/v4/chat/completionserrorStructure使用 Z.AI 专属错误结构transformRequestBody前述命名转换supportedUrlsURL 图像/视频输入。8.2 错误结构解析Z.AI 的错误响应可能有两种形态直接形如{ code, message }或包裹在{ error: { code, message } }中。 zai-error.ts 用 zod 联合 Schema 覆盖这两种形态并统一提取message。测试zai-chat-language-model.test.ts验证了 400 响应会被转换为AI_APICallErrorstatusCode为 400错误消息为响应中的message。8.3 Finish Reason 归一化Z.AI 特有的结束原因会被映射为 AI SDK 统一语义mapZaiFinishReasonzai-chat-language-model.tsZ.AI 原始值统一值sensitivecontent-filtermodel_context_window_exceededlengthnetwork_errorerror其余原样透传如stop、tool_calls8.4 Workflow 序列化支持模型类实现了WORKFLOW_SERIALIZE/WORKFLOW_DESERIALIZE符号方法zai-chat-language-model.ts可将模型 ID 与配置不含 fetch 函数序列化并在 Workflow 场景中恢复测试见 zai-chat-language-model.test.ts。九、从测试到生产验证要点仓库为ai-sdk/zai提供了 node 与 edge 双环境测试配置vitest.node.config.js/vitest.edge.config.js核心测试文件 zai-provider.test.ts 与 zai-chat-language-model.test.ts 覆盖了以下关键契约默认端点https://api.z.ai/api/paas/v4/chat/completions、Bearer 认证与 User-Agent 后缀ZAI_API_KEY环境变量回退机制自定义baseURL去尾部斜杠、自定义请求头Provider Options 的命名映射、非法值校验与未知字段剔除文本、推理、工具调用、缓存 token 用量cacheRead/noCache与结束原因的解析流式事件序列与增量工具参数流。生产环境中建议优先使用环境变量管理 API Key通过createZai的fetch参数接入日志/监控中间件并在调用前确认目标模型 ID 在当前 Z.AI 目录中可用。十、总结ai-sdk/zai让 Z.AI 的 GLM 模型无缝接入 AI SDK 生态安装一个包、设置ZAI_API_KEY、传入模型 ID即可获得与 AI SDK 其他提供者一致的文本生成、流式输出、推理、函数调用与 JSON 输出体验。通过providerOptions.zai可以精细控制采样、思考模式、推理强度与增量工具流式输出而源码层面的命名映射、结束原因归一化、错误结构解析与 Workflow 序列化支持则保证了它在真实生产与自动化场景中的可靠性。如需深入了解实现细节可继续阅读 packages/zai/src 下的源码与测试文件。【免费下载链接】aiThe AI Toolkit for TypeScript. From the creators of Next.js, the AI SDK is a free open-source library for building AI-powered applications and agents项目地址: https://gitcode.com/GitHub_Trending/ai/ai创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考