AIRI 接入 Xiaomi MiMo 聊天模型：从 API Key 获取到「意识」模块启用的完整配置指南

本文围绕 AIRI 官方文档 docs/content/ko/docs/manual/config/providers/consciousness/mimo.md（同步维护的英文版位于 docs/content/en/docs/manual/config/providers/consciousness/mimo.md，简体中文版位于 docs/content/zh-Hans/docs/manual/config/providers/consciousness/mimo.md）展开。AIRI 是一款自托管的陪伴型 AI 助手（支持实时语音聊天、Web / macOS / Windows 多端运行），Xiaomi MiMo 是其中内置的聊天模型提供者。读完本文，你将掌握：如何申请 MiMo API Key、如何在 AIRI 设置面板中完成提供者配置、AIRI 的自动校验与 Ping API 背后执行了哪些底层检查，以及如何在「意识」模块中选定模型并解决常见故障。

Xiaomi MiMo 在 AIRI 中的定位

Xiaomi MiMo 在 AIRI 中作为聊天（chat）模型提供者出现，同时拥有独立的 TTS（语音合成）与 STT（语音识别）服务商页面。也就是说，MiMo 的能力在 AIRI 中被拆分为三块配置入口：

• 聊天模型：配置于 设置 → 提供者 → 聊天 → Xiaomi MiMo；
• TTS：配置于独立的语音（Speech）服务商页面（详见 docs/content/ko/docs/manual/config/providers/speech/mimo.md）；
• STT：配置于独立的转写（Transcription）服务商页面（详见 docs/content/ko/docs/manual/config/providers/transcription/mimo.md）。

为什么选择 Xiaomi MiMo？ 如果你希望使用同一个 MiMo 账户同时覆盖聊天与音频能力（TTS / STT），可以优先选择该提供者，从而避免为不同能力分别申请、维护多套密钥。

从源码结构看，这三类能力也确实由独立的 provider 定义支撑（见 packages/stage-ui/src/libs/providers/providers/index.ts 中的 ./mimo 与 ./mimo-audio 两个注册项）：

• providerMimo：任务类型为 chat，即本文要配置的聊天模型提供者（packages/stage-ui/src/libs/providers/providers/mimo/index.ts）；
• providerMimoAudioSpeech：任务类型为 text-to-speech；
• providerMimoAudioTranscription：任务类型为 speech-to-text / asr / stt。

三者共用同一个云端域名 api.xiaomimimo.com，且在 packages/stage-ui/src/libs/providers/attributes.ts 中均被标记为 paid（付费）与 cloud（云端）属性，用于设置页的提供者目录筛选。

第一步：获取 API Key

1. 登录小米 MiMo 开放平台（platform.xiaomimimo.com），在控制台中创建 API Key；
2. 将生成的 Key 复制并妥善保存，后续在 AIRI 中直接填入。

::: warning API Key 安全 不要把 API Key 提交到代码仓库、不要包含在截图里，也不要分享给任何人。它等同于你账户的访问凭证，泄露后可能导致额度被盗用。 :::

在 AIRI 源码中，apiKey 字段的表单元数据被标记为 type: 'password'（见 packages/stage-ui/src/libs/providers/providers/mimo/index.ts），即配置界面以密码框形式录入，且该字段为必填项（z.string('API Key')，见同文件 第 10-17 行）。

第二步：在 AIRI 中配置 Xiaomi MiMo

1. 打开 设置 → 提供者 → 聊天 → Xiaomi MiMo；
2. 在 API Key 输入框中填入上一步申请的 Key；
3. Base URL 使用默认值 https://api.xiaomimimo.com/v1/，一般无需修改。

配置项解析

从 mimo/index.ts 的配置 Schema 可以看到两个核心字段及其默认行为：

字段	类型	必填	默认值	说明
apiKey	string	是	无	MiMo 平台签发的 API Key
baseUrl	string	否	https://api.xiaomimimo.com/v1/	云端 API 端点，一般保持默认

baseUrl 在 Schema 层直接以 .default('https://api.xiaomimimo.com/v1/') 兜底，因此即使界面留空也会回落到官方端点。只有当小米调整端点地址时才有必要修改该值——这也与官方文档「排查」一节中「确认 Base URL 保持为默认值」的建议相互印证。

底层提供者构造

配置保存后，AIRI 会通过 createProvider 构造实际的调用实例（mimo/index.ts）：

createProvider(config) {
  const provider = createXiaomi(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 } }
    },
  }
}

这里有两个值得注意的实现细节：

1. 底层直接复用 @xsai-ext/providers/create 的 createXiaomi 工厂，说明 MiMo 走的是与 OpenAI 兼容的 HTTP 协议封装；
2. 聊天请求支持 reasoning（推理）开关：当请求携带 options.reasoning 时，会在请求体中加入 thinking: { type: ... } 字段。对应的能力声明为 capabilities: { chat: { reasoning: { modes: ['enabled', 'disabled'] } } }（见 mimo/index.ts），即 MiMo 在 AIRI 中支持显式开启或关闭思考模式。该开关由「意识」设置中的 reasoning 选项控制，持久化在本地存储键 settings/consciousness/reasoning（见 packages/stage-ui/src/stores/modules/consciousness-settings.ts）。

第三步：验证配置

AIRI 会在编辑配置的过程中自动进行有效性验证，无需手动触发。验证逻辑由 validationRequiredWhen 决定：只要 apiKey 非空白（!!config.apiKey?.trim()，见 mimo/index.ts），配置即进入自动校验流程。

自动校验执行的三类检查

MiMo 的校验器由 createOpenAICompatibleValidators 生成，并显式声明了三项检查（mimo/index.ts）：

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

其具体实现位于 packages/stage-ui/src/libs/providers/validators/openai-compatible.ts：

检查项	校验器 ID	底层动作
配置检查	openai-compatible:check-config	校验 API Key 非空、Base URL 非空且为绝对 URL
连通性检查	openai-compatible:check-connectivity	带 Authorization: Bearer <apiKey> 请求 {baseUrl}/models，10 秒超时，HTTP 5xx 判为失败
模型列表检查	openai-compatible:check-model-list	拉取模型列表并确认非空
聊天补全检查	openai-compatible:check-chat-completions	以用户消息 ping 发起一次真实的 generateText 请求（max_tokens: 16），验证端到端可用性

也就是说，文档中的 Ping API 按钮对应的正是 check-chat-completions 这一类真实请求测试——它不仅验证网络连通，还会实际发送一条最小化的聊天补全请求（消息体为 ping，输出上限 16 token），以确认该账户、该 Key 真正具备生成能力。为避免重复请求，该检查结果会在一次校验会话内通过缓存与互斥锁（Mutex）复用（见 openai-compatible.ts）。

校验状态机共五档（见 packages/stage-ui/src/libs/providers/types.ts）：unconfigured（未配置）→ validating（校验中）→ configured（已配置）→ invalid（无效）/ bypassed（跳过）。只有当校验通过（configured）后，后续的模型选择入口才会开放。

选择模型

校验通过后，点击 选择模型 → 按钮，即可跳转到 设置 → 模块 → 意识（Consciousness）页面，在此处选定提供者与具体模型。

从 packages/stage-pages/src/pages/settings/modules/consciousness.vue 的实现可以看到「意识」页面的核心交互逻辑：

• 页面顶部以单选卡片（RadioCardSimple）横向列出所有已配置的聊天提供者，切换提供者时通过 watch(activeProvider, ...) 自动调用 loadModelsForProvider 拉取该提供者的模型列表（见 consciousness.vue）；
• 模型列表加载失败时，页面会展示错误容器，并回退到手动模型 ID 输入框（manual_model_name），这正是官方文档「排查」一节所述「手动输入模型 ID」的界面入口（见 consciousness.vue）；
• 校验失败的提供者卡片会显示 health_check_failed（健康检查失败）角标，便于快速定位问题提供者（见 consciousness.vue）。

切换模型时还会触发埋点 trackModelSwitched，并在 AIRI Card 中同步更新当前的 consciousness 配置（见 consciousness.vue）。

第四步：TTS / STT 同账户复用（延伸）

如果你希望同一个 MiMo 账户同时承担语音合成与语音识别，可分别在对应的服务商页面填入同一个 API Key。三个提供者的默认 Base URL 均为 https://api.xiaomimimo.com/v1/，而音频能力在底层请求中使用的鉴权头为 api-key（而非 Bearer），并复用 /chat/completions 端点（见 packages/stage-ui/src/libs/providers/providers/mimo-audio/index.ts）。

关于音频侧可选的模型与音色，源码给出了明确清单（可作为「意识」之外的能力参考）：

• TTS 模型（默认 mimo-v2.5-tts）：另含 mimo-v2.5-tts-voicedesign（按自然语言描述设计新音色）、mimo-v2.5-tts-voiceclone（基于 base64 音频样本克隆音色），默认格式为 wav（见 mimo-audio/index.ts）；
• STT 模型（默认 mimo-v2-omni）：另含 mimo-v2.5，标注上下文长度为 1M（见 mimo-audio/index.ts）。

这些细节说明：MiMo 在 AIRI 中是一整套「聊天 + 语音 + 转写」的多模态提供者族，配置聊天模型只是第一步。

常见问题排查

官方文档给出了三条基础排查路径，结合源码可以进一步细化：

1. API 校验（Ping）失败：先确认 API Key 是否复制完整（源码要求非空白才触发校验，见 mimo/index.ts）；再确认 MiMo 账户状态是否正常（额度、是否被禁用）；最后确认网络能否访问 api.xiaomimimo.com——连通性检查对 HTTP 5xx 一律判为失败（见 openai-compatible.ts），若该端点返回 5xx 说明是服务端或网络问题，而非 Key 问题。

2. 模型列表无法加载：确认 Base URL 未被改动（默认 https://api.xiaomimimo.com/v1/），因为模型列表通过 {baseUrl}/models 拉取；若 BASE_URL 正确仍拉取失败，可按官方建议在「意识」页面的手动输入框直接填写小米 MiMo 官方文档给出的精确模型 ID（该回退输入框实现在 consciousness.vue）。

3. 提示「未配置提供者」：当「意识」页面没有任何聊天提供者卡片时，说明尚未在 设置 → 提供者 → 聊天 中成功添加并保存 MiMo（或校验未通过），页面会显示引导链接跳转到提供者目录（见 consciousness.vue）。

总结

在 AIRI 中使用 Xiaomi MiMo 的完整链路为：

1. 在小米 MiMo 开放平台创建 API Key；
2. 在 设置 → 提供者 → 聊天 → Xiaomi MiMo 中填入 API Key（Base URL 保持默认 https://api.xiaomimimo.com/v1/）；
3. 等待自动校验（连通性 / 模型列表 / 真实聊天补全三项检查）通过，必要时用 Ping API 手动测试；
4. 点击 选择模型 → 进入 设置 → 模块 → 意识，选定 MiMo 提供者与模型；
5. 如需语音能力，用同一账户在 TTS / STT 服务商页面完成对应配置。

通过 mimo/index.ts 与 openai-compatible.ts 等源码可以看到，MiMo 在 AIRI 中是一套完整的 OpenAI 兼容接入实现，并额外封装了 reasoning 开关与多模态音频能力，适合希望用单一账户统一聊天与语音体验的用户。