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-samas altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported.项目地址: https://gitcode.com/GitHub_Trending/ai/airiZ.ai 提供与 OpenAI 格式完全兼容的聊天 API借助这一特性AIRI 无需任何定制适配即可将其接入“意识”Consciousness模块作为大模型服务商。本文基于仓库中 Z.ai 的官方配置文档韩文原版、英文版、简体中文版展开并结合 Z.ai 服务商定义源码 与 OpenAI 兼容验证器实现完整讲解 API Key 获取、基础配置、自动校验原理、模型选择与问题排查读完即可在 AIRI 中跑通 Z.ai 模型。Z.ai 是什么为什么能无缝接入 AIRIZ.ai 提供的聊天 API 与 OpenAI 格式兼容这意味着它遵循 OpenAI 的请求/响应协议包括端点路径、鉴权头与消息结构。AIRI 的文档体系中用一个 frontmatter 字段标记这类服务商——is_openai_compatible: trueZ.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.yamltasks: [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 URLhttps://api.z.ai/api/paas/v4。两个核心配置字段解析Z.ai 服务商只有两个配置字段由zaiConfigSchema定义见 packages/stage-ui/src/libs/providers/providers/zai/index.ts字段类型默认值说明apiKeystring必填无Z.ai 签发的访问令牌在输入框类型为password不显示明文baseUrlstring可选https://api.z.ai/api/paas/v4Z.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 APIAIRI 在服务商配置页提供了一套自动校验机制不需要手动点击“保存并测试”之类的按钮。自动校验是如何触发的从源码看Z.ai 服务商通过validationRequiredWhen(config)决定何时进入可校验状态validationRequiredWhen(config) { return !!config.apiKey?.trim() },即只要 API Key 非空去除首尾空白后配置页就会自动开始校验。填写过程中校验结果实时刷新这是“AIRI 会在编辑配置时自动校验”这一文档描述的源码依据。Ping API 与三类校验检查Z.ai 复用了 AIRI 的 OpenAI 兼容验证器createOpenAICompatibleValidators并显式启用了三项检查zai/index.tsvalidators: { ...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.tsConnectivity连通性检查向{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源码对“网络错误”与“HTTP 状态错误”做了明确区分openai-compatible.ts网络不可达判为连通性失败而 HTTP 400 与 2xx 都被视为服务端已响应——这解释了为什么“能收到服务端报错”与“网络根本不通”会显示不同的校验结果。如果模型列表无法加载文档给出的最终手段是在意识页面手动输入 Z.ai 提供的精确模型 ID。模型 ID 必须与官方文档逐字一致不能使用界面展示名代替这一规则同样见 docs/content/en/docs/manual/config/common.md 的公共字段表。从 Z.ai 到完整的聊天链路完成 Z.ai 服务商配置后你就走通了 AIRI 聊天的核心链路服务商页保存凭证 → 校验通过 → 意识模块选择模型 → 发送消息验证回复。这条链路的完整说明参见 配置聊天模型指南 与 服务商配置总览。几点收尾提醒保存服务商凭证不等于启用服务商必须在设置 → 模块 → 意识中同时选定服务商与模型AIRI 才会实际使用它回复见 llm.md配置完成后回到聊天界面发送一句“你好”之类的短消息能收到回复即代表 Z.ai 接入成功若之后还要启用语音输入输出可继续参考 语音输入输出配置。相关文档与源码索引Z.ai 官方配置文档韩文 英文 简体中文Z.ai 服务商定义packages/stage-ui/src/libs/providers/providers/zai/index.tsOpenAI 兼容验证器实现packages/stage-ui/src/libs/providers/validators/openai-compatible.ts校验检查枚举与服务商类型定义packages/stage-ui/src/libs/providers/types.tsZ.ai 界面文案i18npackages/i18n/src/locales/en/settings.yaml服务商通用配置流程docs/content/en/docs/manual/config/common.md聊天模型配置指南docs/content/en/docs/manual/config/llm.md【免费下载链接】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-samas altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported.项目地址: https://gitcode.com/GitHub_Trending/ai/airi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考