★ FEATURED ARTICLE 人工智能AI AgentMCP 服务工具调用GUI 自动化语音数字人交互助手【免费下载链接】airi 自托管、归你拥有的 Grok 风格 AI 伴侣与 waifu / 赛博生命灵魂容器目标是接近 Neuro-sama 的高度支持实时语音聊天、Minecraft 和 Factorio 游玩支持 Web / macOS / Windows。项目地址https://gitcode.com/moeru-ai/airi点击查看免费下载本篇指南面向希望让 AIRI 的Consciousness角色心智/对话能力跑在智谱 Z.ai 模型上的用户完整覆盖从获取 API Key、在设置页配置提供商到通过内置校验连通性、模型列表、Chat Completions确认配置生效的全过程并结合 Z.ai 提供商源码 解释每一项配置与校验背后的实际实现。Z.ai 提供商在 AIRI 中的定位AIRI 将各家对话大模型统一抽象为提供商Provider注册在 provider-inference 包 中。Z.ai 是其中专门针对智谱开放平台z.ai端点定义的提供商提供商id为zai显示名称为Z.ai见 zai/index.ts#L21-L29tasks: [chat]即它只提供 Chat对话能力不承担语音合成或转写capabilities.chat.reasoning.modes声明为[enabled, disabled]表示 AIRI 可以向 Z.ai 请求开启或关闭推理thinking模式该定义被加入 portableProviderDefinitions 注册表providerZai位于第 137 行因此 Web 端与桌面端都可用不依赖 Electron 运行时。文档中声明的 frontmatter 字段is_openai_compatible: true见 zhipu.md也印证了这一点Z.ai 的 Chat API 兼容 OpenAI 格式AIRI 正是通过通用的 OpenAI 兼容校验器来完成它的连通性检测。界面文案来自 settings.yaml#L1813-L1815zai: description: z.ai title: Z.ai获取 API Key打开 Z.ai 控制台的API Keys管理页面manage-apikey页面创建一个新 API Key复制密钥并妥善保存。API Key 安全警告不要把 API Key 提交到代码仓库、放进截图或分享给任何人。一旦密钥泄露请立即在 Z.ai 控制台吊销旧密钥并创建新密钥。在 AIRI 中配置操作路径为Settings → Providers → Chat → Z.ai需要填写两个字段字段是否必填说明apiKey是Z.ai 控制台创建的 API Key界面以密码形式type: password输入baseUrl否有默认值默认保持https://api.z.ai/api/paas/v4这两个字段的定义是一个 Zod schema可直接在源码中确认默认值与必填性zai/index.ts#L10-L17const zaiConfigSchema z.object({ apiKey: z .string(API Key), baseUrl: z .string(Base URL) .optional() .default(https://api.z.ai/api/paas/v4), })也就是说apiKey缺失时会直接报API Key错误而baseUrl省略时自动回落到 Z.ai 官方端点https://api.z.ai/api/paas/v4。只有当你使用 Z.ai 兼容网关的自建地址时才需要手动覆盖它。在配置表单中两个字段还会挂载本地化的标签与占位符文案createProviderConfig分别对应field.api-key与field.base-url两组通用文案与其他 OpenAI 兼容提供商共用同一套表单规范。校验机制AIRI 如何确认你的配置可用原文档提到AIRI 在你编辑时自动校验配置如果界面上出现Ping API按钮可以用它发起一次真实请求测试。从源码看这套行为由 createOpenAICompatibleValidators 提供而 Z.ai 明确启用了全部三项运行时检查zai/index.ts#L58-L65validationRequiredWhen(config) { return !!config.apiKey?.trim() }, validators: { ...createOpenAICompatibleValidators({ checks: [ProviderValidationCheck.Connectivity, ProviderValidationCheck.ModelList, ProviderValidationCheck.ChatCompletions], }), },注意validationRequiredWhen只有当apiKey非空trim 后时设置页状态才会从未配置进入开始校验流程空 key 状态下界面不会反复发起网络请求。1. 配置级校验check-config纯本地、不发网络请求检查openai-compatible.ts#L229-L260apiKey是否为空字符串——为空报API key is required.baseUrl是否为空、是否为合法的绝对 URL——分别报Base URL is required./Base URL is not absolute. Check your input./Base URL is invalid. It must be an absolute URL.。这正是编辑时自动变红/变绿的来源你每改一个字段这组校验都会重新执行。2. 连通性检查Connectivity向${baseUrl}/models发起一次带Authorization: Bearer apiKey的GET请求超时时间为10 秒openai-compatible.ts#L262-L311响应状态码 500判定为Server error: HTTP status请求抛出网络异常DNS、超时、被防火墙拦截等判定为连通性失败状态码2xx/3xx以及4xx均被视为网络已通具体错误留给下面的模型列表检查去解释。排查网络不通类问题时可以据此确认该检查要求你的运行环境能直连api.z.ai的 443 端口且请求头中携带了 Bearer Token。3. 模型列表检查ModelList调用listModels拉取 Z.ai 当前可用的模型清单要求列表非空否则报Model list check failed: no models foundopenai-compatible.ts#L340-L369。这一步失败通常意味着密钥无效、欠费或权限不足而不再是网络问题。4. Chat Completions 检查即界面中的 Ping API这是最接近真实使用场景的探测AIRI 会自动挑选一个模型若你在配置中显式填了model则优先用它否则取模型列表中第一个可用项发送一条内容为ping的 user 消息并把输出上限压到 16 个 token 以控制成本runChatCheckawait generateText({ apiKey: config.apiKey, baseURL: config.baseUrl!, headers: additionalHeaders, model: normalizedModel, messages: message.messages(message.user(ping)), // 部分 OpenAI 兼容提供商拒绝小于 16 的输出上限 ...(options?.chatCompletionTokenParameter max_completion_tokens ? { max_completion_tokens: 16 } : { max_tokens: 16 }), })从源码结构看该检查对错误的归类比较细致网络错误会同时判定连通性与 Chat 失败而若拿到 HTTP 400 或 2xx 响应说明服务端已正常应答Chat 检查视为通过。此外同一编辑会话内该结果会通过validationCache 互斥锁缓存避免多个校验项重复触发同一次真实请求。对应到文档中的操作说明Validate configuration是上述校验的自动执行当界面出现Ping API按钮时点击它才会真正向 Z.ai 发送一次ping请求做端到端验证。推理thinking模式的透传机制Z.ai 提供商在createProvider中对 chat 请求做了一层增强zai/index.ts#L44-L56createProvider(config) { const provider createZai(config.apiKey, config.baseUrl) return { ...provider, chat(model: string, options?: ChatRequestOptions) { const request provider.chat(model) if (!options?.reasoning) return request return { ...request, thinking: { type: options.reasoning } } }, } }即当 AIRI 上层Consciousness 的对话管线在ChatRequestOptions.reasoning中传入enabled或disabled类型定义见 types.ts#L396-L409时Z.ai 请求会被附加thinking: { type: ... }字段从而在 Z.ai 的 API 层开启/关闭深度思考不传则完全使用底层xsai-ext的默认行为。这使得 Z.ai 的推理开关能力成为 AIRI 统一 reasoning 抽象的一部分而无需在 Consciousness 侧为 Z.ai 写特殊逻辑。选择模型并接入 Consciousness配置校验通过后按文档流程点击设置页的Select Model →按钮它会打开Settings → Modules → Consciousness在该页面选择提供商Z.ai并指定具体模型完成后 AIRI 的对话Consciousness即通过你配置的端点调用 Z.ai 模型。如果 AIRI 无法自动加载模型列表例如 Z.ai 侧接口临时异常文档给出的兜底方案是在Consciousness页面手动输入 Z.ai 提供的精确模型 ID。这一点与校验器设计一致——pickValidationModel允许配置中显式指定model手动填写的模型 ID 同样会被优先采信openai-compatible.ts#L89-L105。故障排查文档给出的排查清单为检查 API Key、可用额度或配额、速率限制rate limits、网络连接。结合源码中的检查实现可以更精准地定位现象可能原因依据配置项直接标红、无网络请求apiKey为空或baseUrl不是合法绝对 URLcheck-config 本地校验连通性失败Server error: HTTP 5xxZ.ai 服务端异常Connectivity 检查仅把 ≥500 判为失败连通性失败且为网络错误DNS/代理/防火墙无法访问api.z.aiisNetworkError分支模型列表为空密钥无效、欠费、账户无模型权限ModelList 检查PingChat失败密钥无对话权限、模型 ID 不存在、限流ChatCompletions 检查含ping请求与max_tokens: 16限制若 AIRI 无法加载模型列表回到Consciousness页面手动填写 Z.ai 文档中的精确模型 ID 即可绕过自动发现。参考文件内容路径本指南对应的官方文档zhipu.mdZ.ai 提供商定义schema、默认值、thinking 透传、校验项zai/index.tsOpenAI 兼容校验器实现openai-compatible.ts提供商注册表portableProviderDefinitionsproviders/index.ts界面文案Z.ai 标题/描述、Ping API 按钮settings.yaml同类配置文档可对照阅读openai.md、deepseek.md赞分享人工智能AI AgentMCP 服务工具调用GUI 自动化语音数字人交互助手【免费下载链接】airi 自托管、归你拥有的 Grok 风格 AI 伴侣与 waifu / 赛博生命灵魂容器目标是接近 Neuro-sama 的高度支持实时语音聊天、Minecraft 和 Factorio 游玩支持 Web / macOS / Windows。项目地址https://gitcode.com/moeru-ai/airi点击查看免费下载相关推荐AIRI 接入 LM Studio本地大模型配置、自动校验与 Consciousness 模块联动解析AIRI 接入 LM Studio本地大模型配置、自动校验与 Consciousness 模块联动解析 本文基于 AIRI 仓库的官方文档 docs/cont人工智能AI AgentMCP 服务工具调用GUI 自动化语音数字人交互助手后端AIRI 接入 Novita AI 聊天模型OpenAI 兼容提供者配置与校验机制详解AIRI 接入 Novita AI 聊天模型OpenAI 兼容提供者配置与校验机制详解 本文是一份面向 AIRI 用户的实操指南讲解如何将 Novita A人工智能AI 应用大模型AI Agent交互助手语音数字人后端前端桌面应用移动开发GUI 自动化MCP 服务AIRI 接入 Cerebras 聊天模型完整配置指南与校验机制源码解析AIRI 接入 Cerebras 聊天模型完整配置指南与校验机制源码解析 Cerebras 是 AIRI 中内置的聊天模型提供商之一通过其 OpenAI 兼人工智能AI 应用大模型AI Agent交互助手语音数字人后端前端桌面应用移动开发GUI 自动化MCP 服务上一篇5分钟上手Activepieces从0到1搭建你的第一个自动化工作流下一篇最完整DB-GPT RAG框架解析零基础构建企业级知识库应用创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
阅读完成 · 觉得有帮助？
