AIRI 接入 Z.ai 聊天服务商全指南：从 API Key 到意识模块模型选择-平芜编程栈

AIRI 接入 Z.ai 聊天服务商全指南：从 API Key 到意识模块模型选择

【免费下载链接】airi💖🧸 Self hosted, you-owned Grok Companion, a container of souls of waifu, cyber livings to bring them into our worlds, wishing to achieve Neuro-sama's altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported.项目地址: https://gitcode.com/GitHub_Trending/ai/airi

Z.ai 提供与 OpenAI 格式完全兼容的聊天 API，借助这一特性，AIRI 无需任何定制适配即可将其接入“意识”（Consciousness）模块作为大模型服务商。本文基于仓库中 Z.ai 的官方配置文档（韩文原版、英文版、简体中文版）展开，并结合 Z.ai 服务商定义源码与 OpenAI 兼容验证器实现，完整讲解 API Key 获取、基础配置、自动校验原理、模型选择与问题排查，读完即可在 AIRI 中跑通 Z.ai 模型。

Z.ai 是什么：为什么能无缝接入 AIRI

Z.ai 提供的聊天 API 与 OpenAI 格式兼容，这意味着它遵循 OpenAI 的请求/响应协议（包括端点路径、鉴权头与消息结构）。AIRI 的文档体系中用一个 frontmatter 字段标记这类服务商——is_openai_compatible: true，Z.ai 的文档即属于这一类。因此 AIRI 无需为 Z.ai 编写专属协议实现，只需提供 API Key 和 Base URL 两个参数，就能在“意识”模块中调用其模型。

从源码看，Z.ai 服务商的完整定义位于 packages/stage-ui/src/libs/providers/providers/zai/index.ts，其关键属性包括：

id: 'zai'、name: 'Z.ai'，在设置界面中显示为Z.ai（本地化标题来自 packages/i18n/src/locales/en/settings.yaml）；
tasks: ['chat']，表明它是一个聊天（Chat）类型服务商，出现在设置 → 服务商 → 聊天分类下；
图标使用i-lobe-icons:zai。

文档中“为什么选择 Z.ai”一节明确指出：如果你希望直接在 AIRI 中使用 Z.ai 模型，或者已经持有 Z.ai 的 API Key，就可以直接选择这一服务商，无需中转或代理。

第一步：获取 Z.ai API Key

在 AIRI 中配置 Z.ai 之前，需要先在 Z.ai 平台申请 API Key，步骤如下：

打开 Z.ai 的 API Keys 管理页面（z.ai控制台的 API Key 列表页）；
点击创建，生成一个新的 API Key；
复制该 Key 并妥善保存到安全位置——出于安全考虑，页面只会完整展示一次，丢失后需重新创建。

::: warning API Key 安全红线 API Key 相当于账户的资金凭证与访问凭证，请务必遵守以下原则：

不要将 API Key 提交到 Git 仓库（包括配置文件、.env、日志）；
不要在截图、录屏、问题反馈或聊天消息中露出完整 Key；
不要与任何人共享 Key；
一旦发现 Key 泄露，立即在 Z.ai 控制台撤销（revoke）该 Key 并创建新 Key。

AIRI 的通用配置说明（docs/content/en/docs/manual/config/common.md）也强调：凭证与服务商设置保存在当前设备的本地设置中，切勿在截图、日志、Issue 或聊天消息中泄露 API Key 等敏感凭证。 :::

第二步：在 AIRI 中配置 Z.ai 服务商

拿到 API Key 后，在 AIRI 设置界面按以下步骤完成配置：

打开设置 → 服务商 → 聊天 → Z.ai；
在基础设置（Basic Settings）中，将 API Key 粘贴到API Key输入框；
保留默认 Base URL：https://api.z.ai/api/paas/v4。

两个核心配置字段解析

Z.ai 服务商只有两个配置字段，由zaiConfigSchema定义（见 packages/stage-ui/src/libs/providers/providers/zai/index.ts）：

字段	类型	默认值	说明
`apiKey`	string（必填）	无	Z.ai 签发的访问令牌，在输入框类型为`password`，不显示明文
`baseUrl`	string（可选）	`https://api.z.ai/api/paas/v4`	Z.ai API 根地址，一般无需修改

注意 Base URL 是一个根地址，不是/chat/completions之类的完整请求路径。OpenAI 兼容类服务商的文档中都有类似约定：只需填写 API 根地址，AIRI 会在其基础上拼接模型列表、聊天补全等端点。

关于 Base URL 的中西差异提醒

仓库中 Z.ai 服务商的默认 Base URL 是https://api.z.ai/api/paas/v4（韩文/英文文档与源码一致）。而简体中文文档中“智谱 AI”一节给出的地址为https://open.bigmodel.cn/api/paas/v4/，对应智谱 AI 的国内平台。接入时请以你所持有的 API Key 所属平台为准，保留该服务商条目预置的默认地址即可，切勿混用。通用配置指南也强调：尽量使用服务商文档中的默认地址与模型名，不要猜测 Base URL、模型 ID 或区域参数（见 docs/content/en/docs/manual/config/index.md）。

第三步：验证配置与 Ping API

AIRI 在服务商配置页提供了一套自动校验机制，不需要手动点击“保存并测试”之类的按钮。

自动校验是如何触发的

从源码看，Z.ai 服务商通过validationRequiredWhen(config)决定何时进入可校验状态：

validationRequiredWhen(config) { return !!config.apiKey?.trim() },

即只要 API Key 非空（去除首尾空白后），配置页就会自动开始校验。填写过程中校验结果实时刷新，这是“AIRI 会在编辑配置时自动校验”这一文档描述的源码依据。

Ping API 与三类校验检查

Z.ai 复用了 AIRI 的 OpenAI 兼容验证器createOpenAICompatibleValidators，并显式启用了三项检查（zai/index.ts）：

validators: { ...createOpenAICompatibleValidators({ checks: [ProviderValidationCheck.Connectivity, ProviderValidationCheck.ModelList, ProviderValidationCheck.ChatCompletions], }), },

这三项检查的语义在 packages/stage-ui/src/libs/providers/types.ts 中定义，具体实现位于 packages/stage-ui/src/libs/providers/validators/openai-compatible.ts：

Connectivity（连通性检查）：向{baseUrl}/models发起一次轻量 GET 请求，携带Authorization: Bearer <apiKey>头，超时时间为 10 秒。服务端返回 HTTP 5xx 或请求失败（网络错误、超时）时判定失败，用于确认网络可达与服务端状态。
ModelList（模型列表检查）：拉取GET /models的模型列表，确认返回非空。该检查决定 AIRI 能否在“意识”模块中自动填充模型下拉选项。
ChatCompletions（聊天补全检查）：真正向聊天端点发送一次最小请求——以generateText发送一条内容为ping的用户消息，并设置max_tokens: 16（某些兼容服务商拒绝低于 16 的输出上限）。这一项就是文档中所说的Ping API：点击后发送一次真实的小额请求，会消耗少量额度。实现中会对同一次校验的聊天检查做缓存与互斥（Mutex），避免重复请求。

此外还有一个配置级校验check-config：检查 API Key 是否为空、Base URL 是否为空、是否为合法的绝对 URL。

校验通过后的下一步：选择模型

校验通过后，点击选择模型 →（Select Model →）按钮，会跳转到设置 → 模块 → 意识（Consciousness），在这里选择刚刚配置的服务商（Z.ai）以及具体的模型 ID。

AIRI 能否自动列出模型取决于模型列表检查是否成功。如果模型列表加载失败，可在“意识”页面手动输入 Z.ai 官方文档给出的精确模型 ID——这是文档明确提供的兜底方案。

Z.ai 的推理模式（reasoning）能力

值得一提的细节是，Z.ai 服务商声明了capabilities: { chat: { reasoning: { modes: ['enabled', 'disabled'] } } }（见 zai/index.ts），并在createProvider中做了专门处理：当请求携带推理选项时，会附加thinking: { type: options.reasoning }字段（zai/index.ts）。也就是说，Z.ai 模型在 AIRI 中支持开启/关闭思考模式，具体能力以所选模型实际支持情况为准。

问题排查：从文档建议到源码级判断

Z.ai 文档的排查章节给出了四条核心检查线索，结合验证器源码我们可以进一步理解每条线索对应的失败场景：

排查线索	对应验证器失败特征	处置建议
API Key 错误	聊天补全检查返回 401/403 类状态，或模型列表/连通性检查鉴权失败	重新复制 Key，确认无多余空格或换行（源码校验会先`trim()`，但粘贴时仍应避免携带空白）
额度或配额不足	服务端返回 402/429 等状态码，连通性正常但聊天补全失败	登录 Z.ai 控制台检查账户余额与配额，充值或等待限额刷新
请求速率限制	高频校验时收到 429 Too Many Requests	降低校验频率，避免短时间重复点击 Ping API
网络连接问题	连通性检查抛出网络错误（`is-network-error`命中）或在 10 秒内超时	检查本机网络、代理与防火墙是否能访问`api.z.ai`