AIRI 意识模块接入指南OpenAI 官方与兼容 API 配置详解【免费下载链接】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/airiAIRI 的意识Consciousness模块负责承载聊天模型是语音对话、游戏陪伴等上层能力的大脑。本指南围绕官方文档 OpenAI 与兼容 API 展开讲解如何在 AIRI 中接入 OpenAI 官方服务或任意 OpenAI 兼容服务商的聊天模型覆盖 API Key 获取、Base URL 填写、Ping API 验证、模型选择与故障排查的完整闭环。读完本文你将能独立完成意识模块的服务商配置并理解 AIRI 在源码层面如何对服务进行四步自动校验。为什么选择 OpenAI 或兼容 API如果满足以下任一条件就可以通过本指南完成配置你已经拥有 OpenAI 官方 API Key你使用的第三方服务商明确提供 OpenAI 兼容的聊天接口OpenAI Chat Completions API。需要特别警惕的是仅凭API 地址以/v1结尾或密钥以sk-开头并不能保证服务真正兼容。是否兼容要看服务商文档是否声明实现了 OpenAI Chat Completions 协议AIRI 在验证阶段也会用真实请求去探测这一点见下文验证背后的源码实现。AIRI 在源码中把这两种场景建模为两个独立的服务商定义providers/index.ts 统一注册服务商provider id适用场景OpenAIopenai使用 OpenAI 官方https://api.openai.com/v1地址OpenAI 兼容 APIopenai-compatible使用第三方服务商提供的兼容地址两个服务商的tasks均标记为[chat]见 openai/index.ts 与 openai-compatible/index.ts即它们只服务于意识的聊天能力不会被误用于语音合成或转写。第一步获取 API 密钥使用 OpenAI 官方服务时登录 OpenAI 平台进入 API Keys 页面创建 API Key使用兼容服务时打开对应服务商的管理控制台在API 密钥或开发者设置页面创建 API Key复制密钥并妥善保存后续粘贴到 AIRI 的基础设置中。::: warning API Key 安全 不要将 API Key 提交到仓库、放入截图或发送给他人。密钥一旦泄露请立即在服务商控制台撤销它并创建新密钥。 :::AIRI 在配置表单中将 API Key 字段声明为密码类型输入type: password见 openai/index.ts界面上的占位符为sk-……见 settings.yaml避免明文展示。在配置校验阶段未填写 API Key 会被直接判定为配置错误源码逻辑见 openai-compatible.ts。第二步在 AIRI 中配置打开设置 → 服务商 → 聊天选择OpenAI或OpenAI 兼容 API聊天分类的界面定义见 providers/index.vue将 API Key 粘贴到基础设置的 API 密钥输入框填写 Base URL使用OpenAI 官方服务时保留默认值https://api.openai.com/v1使用兼容服务时填写服务商文档提供的 API根地址不要附加/chat/completions路径。Base URL 之所以必须是根地址是因为 AIRI 会在其后拼接/models连通性检查、/chat/completions聊天补全等路径来组织请求见 openai-compatible.ts。如果填写了完整接口路径这些拼接就会产生双重路径导致请求失败。从源码看两个服务商对 Base URL 的默认值完全一致// 来自 packages/provider-inference/src/providers/cloud/openai/index.ts const openAICompatibleConfigSchema z.object({ apiKey: z.string(API Key), baseUrl: z .string(Base URL) .optional() .default(https://api.openai.com/v1), // 官方默认根地址 })二者唯一的结构差异是OpenAI 官方服务商的apiKey为必填openai/index.ts而 OpenAI 兼容 API 服务商的apiKey为可选openai-compatible/index.ts这为某些不需要鉴权的本地或内网兼容服务留出了空间。Base URL 必须是一个合法的绝对 URL源码的配置校验器会先尝试new URL(baseUrl)解析无主机名或解析失败都会报错Base URL is not absolute / invalid见 openai-compatible.ts。关于 Base URL 的补充说明服务商文档通常给出形如https://api.example.com/v1的地址直接复制即可常见本地推理服务如 Ollama的 OpenAI 兼容端点形如http://localhost:11434/v1界面帮助文案中亦以此为例见 settings.yaml如果服务商要求自定义请求头如额外鉴权字段可在高级设置中添加自定义 HTTP 标头界面文案见 settings.yaml。第三步验证配置配置完成后按以下顺序验证Ping API点击此按钮测试网络连通性以及 API Key 是否填写正确选择模型测试成功后点击模型选择区域从服务商返回的模型列表中挑选要使用的具体模型。界面上的验证步骤名称与源码中的校验器一一对应。中文文案settings.yaml展示了完整的验证面板验证步骤中文文案校验器 id配置openai-compatible:check-config连通性openai-compatible:check-connectivity能够列出模型openai-compatible:check-model-list能够处理 Chat Completion聊天补全请求openai-compatible:check-chat-completions验证过程中的状态文案为验证中…… / 通过 / 错误见 settings.yaml。验证背后的源码实现AIRI 的 OpenAI 系服务商复用了同一套校验器工厂createOpenAICompatibleValidators实现见 openai-compatible.ts并按服务商能力开关具体检查项OpenAI 官方开启Connectivity、ModelList、ChatCompletions三项且聊天探测使用较新的max_completion_tokens参数openai/index.ts适配 gpt-5 等新模型OpenAI 兼容 API同样开启三项检查聊天探测使用兼容性更广的max_tokens参数openai-compatible/index.ts。各检查项的真实行为如下均有单测覆盖见 openai-compatible.test.ts连通性检查向${baseUrl}/models发起一次轻量GET请求携带Authorization: Bearer apiKey超时 10 秒AbortControllersetTimeout仅当服务端返回 5xx 或发生网络错误时才判定失败openai-compatible.ts。测试用例明确断言该步骤不会调用generateTextopenai-compatible.test.ts因此它不消耗任何 Token模型列表检查调用模型列表接口过滤掉embed、tts、models/gemini-2.5-pro等非聊天模型后取第一个可用模型用于后续探测openai-compatible.tsChat Completions 检查向chat/completions发送一条内容为ping的用户消息输出 token 上限固定为 16部分兼容服务商拒绝低于 16 的输出上限见代码注释 openai-compatible.ts。返回 400 状态会被视为连通正常但模型不可用而非网络失败openai-compatible.ts避免把模型侧的错误误报为密钥问题。该检查结果带缓存与互斥锁同一轮验证中只探测一次openai-compatible.ts。OpenAI 官方服务商的额外能力推理模式映射官方 OpenAI 服务商在创建 provider 时对chat()做了一层包装当界面开启深度思考reasoning时将请求中的推理级别映射为reasoningEffort—— 开启映射为medium关闭映射为noneopenai/index.ts并声明capabilities.chat.reasoning.modes [enabled, disabled]openai/index.ts。也就是说官方 OpenAI 服务商明确支持推理开关而通用兼容服务商则保持原样透传请求。如果你使用的兼容服务也支持推理如 DeepSeek、Qwen 系请优先选用对应厂商在 AIRI 中的专用服务商定义。排查如果 Ping API 失败按以下顺序排查检查 API Key确认密钥已完整复制、没有多余空格且未过期或被撤销检查账户额度OpenAI 及多数兼容服务商在余额不足或额度耗尽时会返回 401/402/429 等错误码检查网络连接确认当前设备可以访问服务商域名部分地区访问 OpenAI 官方地址需要代理此时可在系统层面配置代理确认服务兼容性使用兼容服务时确认服务商明确支持 OpenAI Chat Completions API而非只有名称相似的自有协议检查 Base URL确认填写的是服务商文档指定的根地址未附加/chat/completions路径且格式为绝对 URL。源码层面的判定逻辑可以帮你更快定位问题配置校验器会先分别检查 API Key 是否为空、Base URL 是否合法连通性检查只对 5xx 或网络错误报错Chat Completions 检查只对非 400 的失败报错openai-compatible.ts 与 openai-compatible.ts。因此报错信息包含Connectivity check failed→ 网络或 Base URL 问题报错信息包含Chat completions check failed→ 服务商协议不兼容或所选模型不可用报错信息包含No model available for validation→ 模型列表为空或全被过滤需要在界面上手动配置模型后重试openai-compatible.ts。另外界面验证面板提供仍然继续continueAnyway的出口settings.yaml当个别检查项如模型列表对特定服务商不适用时可以在确认服务可用的前提下跳过部分验证继续使用。延伸阅读完整的官方配置文档OpenAI 与兼容 API服务商注册清单provider-inference/src/providers/index.tsOpenAI 官方服务商实现provider-inference/src/providers/cloud/openai/index.ts通用兼容服务商实现provider-inference/src/providers/cloud/openai-compatible/index.ts校验器工厂与四步检查实现provider-inference/src/validators/openai-compatible.ts校验器单元测试含连通性轻量探测、输出上限 16、max_completion_tokens切换等关键断言provider-inference/src/validators/openai-compatible.test.ts设置页聊天服务商分类stage-pages/src/pages/settings/providers/index.vue【免费下载链接】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），仅供参考