企业官网建设流程全解析

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 SDK（The 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 Key：

ZAI_API_KEY=your-api-key

API 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、自定义网关地址或拦截请求时，使用createZai：

import { createZai } from '@ai-sdk/zai'; const zai = createZai({ apiKey: process.env.ZAI_API_KEY, });

createZai接受以下可选配置（定义见 zai-provider.ts）：

值得注意的实现细节：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：

类型定义为(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 参数总览

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 请求体映射原理

这些参数并非原样透传。模型类中的transformZaiRequestBody（zai-chat-language-model.ts）会将 AI SDK 风格命名转换为 Z.AI API 的 snake_case 字段：

• doSample→do_sample
• thinking.type→thinking.type，thinking.clearThinking→thinking.clear_thinking
• toolStream→tool_stream
• requestId→request_id
• userId→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-call（input: '{"city":"Paris"}'），并以tool-calls作为结束原因。

6.3 工具选择（toolChoice）的处理策略

zai-chat-language-model.ts 展示了 Z.AI 在工具选择上的两个特殊处理：

• toolChoice: { type: 'none' }：直接移除tools与toolChoice，确保模型不会调用任何工具；
• 其他非auto的toolChoice（如required）：Z.AI 目前仅支持自动工具选择，因此会发出unsupported警告并降级为自动选择。

七、标准参数的兼容性边界

使用过程中需要注意：以下 AI SDK 标准参数在 Z.AI 提供者中不受支持，传入时会被移除并产生unsupported类型警告（而非报错）：

• frequencyPenalty
• presencePenalty
• seed

上述行为由prepareCallOptions（zai-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.AI：

• url：${baseURL}${path}，即默认打到https://api.z.ai/api/paas/v4/chat/completions；
• errorStructure：使用 Z.AI 专属错误结构；
• transformRequestBody：前述命名转换；
• supportedUrls：URL 图像/视频输入。

8.2 错误结构解析

Z.AI 的错误响应可能有两种形态：直接形如{ code, message }，或包裹在{ error: { code, message } }中。 zai-error.ts 用 zod 联合 Schema 覆盖这两种形态，并统一提取message。测试（zai-chat-language-model.test.ts）验证了 400 响应会被转换为AI_APICallError，statusCode为 400，错误消息为响应中的message。

8.3 Finish Reason 归一化

Z.AI 特有的结束原因会被映射为 AI SDK 统一语义（mapZaiFinishReason，zai-chat-language-model.ts）：

8.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 覆盖了以下关键契约：

1. 默认端点https://api.z.ai/api/paas/v4/chat/completions、Bearer 认证与 User-Agent 后缀；
2. ZAI_API_KEY环境变量回退机制；
3. 自定义baseURL（去尾部斜杠）、自定义请求头；
4. Provider Options 的命名映射、非法值校验与未知字段剔除；
5. 文本、推理、工具调用、缓存 token 用量（cacheRead/noCache）与结束原因的解析；
6. 流式事件序列与增量工具参数流。

生产环境中建议：优先使用环境变量管理 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