AIRI 接入 AIHubMix 聊天模型完全指南：从 API Key 到「意识」模块启用

AIHubMix 是 AIRI 官方文档中列出的聊天模型提供商之一，它通过一个 API Key 即可访问账户内的多种模型，并由 AIRI 自动拉取可用模型列表。本文基于仓库中的官方配置文档，完整讲解在 AIRI 中接入 AIHubMix 的全流程——从申请 API Key、填写服务商配置、验证连通性，到最终在「意识」模块中启用模型并完成一次真实对话测试，同时结合仓库源码解释底层兼容机制与排查思路。

为什么选择 AIHubMix

根据 AIRI 官方文档（docs/content/ko/docs/manual/config/providers/consciousness/aihubmix.md）的说明：

• AIHubMix 在 AIRI 中提供聊天模型，并且能够列出当前账户下可用的模型清单；
• 如果你的目标是通过一个 API Key 使用 AIHubMix 账户中提供的模型，就可以选择该服务商；
• 在项目 README 的提供商清单中，AIHubMix 也被标记为推荐选项（参见 docs/README.zh-CN.md）。

也就是说，AIHubMix 适合那些希望在单一账户内聚合多种模型、并通过统一密钥管理的用户。它走的是 OpenAI 兼容的 Chat Completions 协议（默认 Base URL 以 /v1/ 结尾），因此 AIRI 中处理 OpenAI 兼容网关的底层机制同样适用于它。

前置准备

在开始配置前，请先确认以下前提（对应 docs/content/ko/docs/manual/config/llm.md 中的「사전 준비 사항」）：

1. AIRI 已安装并正在运行；
2. 已在 AIHubMix 创建 API Key，并确认账户中已开通你打算使用的聊天模型；
3. 运行 AIRI 的设备可以正常访问 AIHubMix 的 API 服务（无网络/防火墙拦截）。

提示：AIRI 的聊天模型是它的"大脑"。要产生文本回复，必须至少配置一个可用的聊天服务商并选择模型。TTS、ASR 等语音能力是可选且彼此独立的，建议先把聊天链路打通，再逐步添加其他模块（详见 docs/content/ko/docs/manual/config/index.md）。

第一步：获取 API Key

1. 打开并登录 AIHubMix 官网；
2. 在控制台（Console）中创建 API Key；
3. 复制密钥并妥善保存在安全的地方，后续填入 AIRI。

⚠️ API Key 安全警告（原文强调，务必遵守）

• 不要将 API Key 提交（commit）到任何仓库；
• 不要在截图、日志、聊天消息或 Issue 中暴露 API Key；
• 不要与任何人分享你的密钥。

这是所有服务商配置的通用底线。AIRI 的通用配置指南（docs/content/ko/docs/manual/config/common.md）同样提醒：凭据与服务商设置保存在当前设备的本地配置中，请勿在任何渠道泄露。

第二步：在 AIRI 中配置 AIHubMix

在 AIRI 中按以下路径操作：

设置 → 服务商（Providers）→ 聊天（Chat）→ AIHubMix

打开后填写 API Key，默认 Base URL 为：

https://aihubmix.com/v1/

这是文档给出的默认值，通常无需修改。下面结合 AIRI 通用字段说明（docs/content/ko/docs/manual/config/common.md）梳理各字段含义：

字段	含义	填写建议
API Key	服务商签发的访问令牌	粘贴完整密钥，不要添加引号、首尾空格或换行
Base URL	服务商 API 的根地址	仅在服务商文档要求其他地址时才修改；需填写包含 https:// 或 http:// 的完整地址
模型	聊天/语音/识别使用的模型 ID	优先使用 AIRI 拉取到的模型列表；列表不可用时可手动输入服务商文档中的精确 ID
语音	语音合成使用的语音 ID	先选模型，再选该模型支持的语音
区域	部分云服务使用的部署区域	与服务商控制台显示的项目/资源区域保持一致

对于 AIHubMix 这类以 /v1/ 结尾的 OpenAI 兼容服务，可以参考 OpenAI 兼容 API 配置文档 中的一条重要提示：仅凭 API 地址以 /v1 结尾或密钥以 sk- 开头，并不能保证服务完全兼容；在兼容服务中应填写服务商文档给出的 API 根地址，而不要在后面追加 /chat/completions 路径。因此除非 AIHubMix 官方文档另行要求，请保持默认 Base URL 不变。

底层兼容机制的源码印证

从源码结构看，AIRI 的聊天运行时对 OpenAI 兼容网关做了专门的兼容处理。packages/core-agent/src/runtime/llm-service.ts 中的 sanitizeMessages 函数会在请求发出前对消息做归一化：

• 将 AIRI 内部使用的 role: 'error' 消息改写为 user 角色的叙述文本，避免服务商拒绝；
• 当服务商不接受 messages[].content 的数组形式时，会把内容数组强制压平为纯字符串。

其注释明确说明：部分 OpenAI 兼容网关（尤其是基于 Rust/serde 严格反序列化的网关）只接受 content 为字符串，收到数组会返回类似 Failed to deserialize the JSON body... expected a string 的 HTTP 400 错误。为此，packages/core-agent/src/types/llm.ts 定义了 contentArrayCompatibility 按模型缓存该能力，并在运行期自动降级重试。这意味着即便某兼容网关实现不完整，AIRI 也能尽量保证对话可用。

第三步：验证配置

配置完成后，AIRI 会提供两层验证：

1. 自动有效性检查（Validate configuration）：编辑配置的过程中，AIRI 会自动校验必填字段；服务商字段修改后即自动保存。
2. Ping API：当该按钮出现时，点击即可发送一次真实的请求测试，验证网络连通性与 API Key 是否正确。注意：此操作可能消耗少量账户额度（参考 docs/content/ko/docs/manual/config/common.md 的说明）。

验证通过后：

3. 点击 选择模型（Select Model）→ 按钮，会直接跳转到 设置 → 模块（Modules）→ 意识（Consciousness）；
4. 在「意识」页面选择刚刚配置的 AIHubMix 服务商 以及你想使用的具体模型；
5. 返回聊天界面，发送一句类似 Hello 的短消息。如果收到回复，说明服务商与模型已正常工作。

重要：保存服务商凭据并不会自动激活服务商，必须回到「意识」模块完成服务商与模型的双重选择，AIRI 才会真正使用该模型（见 docs/content/ko/docs/manual/config/llm.md）。

关于模型列表与手动输入模型 ID

AIRI 在服务商支持的前提下会自动拉取模型列表（docs/content/ko/docs/manual/config/llm.md 明确说明"제공자가 지원하는 경우 AIRI가 모델 목록을 불러옵니다"）。

但存在两种常见例外：

• 某些服务商不提供模型列表接口，或当前 API Key 缺少查询权限；
• 模型列表拉取超时或失败。

此时处理方式如下（对应 AIHubMix 文档的排查段落）：

1. 确认 Base URL 未被改动，仍为 https://aihubmix.com/v1/；
2. 如果字段允许直接输入，则在 「意识」页面手动输入 AIHubMix 官方文档给出的精确模型 ID；
3. 模型 ID 必须与服务商文档完全一致，不能使用界面显示名替代真实 ID（参考 docs/content/ko/docs/manual/config/common.md）。

问题排查清单

如果 API 检查失败，请按下述顺序排查（综合 AIHubMix 文档与 docs/content/ko/docs/manual/config/common.md）：

1. API Key：确认账户可访问服务、额度/配额充足；重新复制密钥，检查是否混入首尾空格或换行；
2. 账户余额：AIHubMix 是按量计费服务，余额不足会导致请求失败；
3. Base URL：恢复默认值，或与服务商官方文档逐字比对；
4. 网络连接：确认本机网络、代理、防火墙允许访问 AIHubMix；
5. 模型选择：确认「意识」页面中服务商和模型都已选中，且模型 ID 精确无误；
6. 验证通过但无可用模型：可能是服务商不支持模型列表查询，回到「意识」页面手动输入模型 ID；
7. 请求超时：检查网络与服务端状态，必要时重试。

延伸阅读

• AIHubMix 配置文档（韩文原版）、中文版、英文版
• 服务商配置总览：了解最小必需配置与模块关系
• 通用配置指南：字段含义、验证方式与通用排查顺序
• 聊天模型配置：服务商选择、模型启用与连通性测试
• OpenAI 兼容 API 配置：同类兼容服务的配置要点
• 聊天运行时兼容处理源码：消息归一化与兼容降级逻辑
• LLM 流式选项与兼容缓存类型：contentArrayCompatibility 等运行期能力缓存

按上述流程完成配置后，AIRI 即可通过 AIHubMix 正常生成聊天回复；在此基础上，你还可以进一步配置语音合成（TTS）与语音识别（ASR/STT）等模块，让对话体验更加完整。