企业官网建设流程全解析

在 AIRI 中接入 MiniMax 中国大陆版：OpenAI 兼容聊天提供者的配置与校验实战

【免费下载链接】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-sama's altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported.项目地址: https://gitcode.com/GitHub_Trending/ai/airi

本篇指南围绕 AIRI 项目中"意识（consciousness）"模块的聊天提供者配置展开，完整讲解如何将中国大陆版 MiniMax 平台的 API Key 接入 AIRI，使其在意识模块中调用 MiniMax 的聊天模型。读完本文，你将掌握 MiniMax 中国大陆版与 Global 版的选型区别、API Key 申请与安全规范、提供者配置与自动校验机制，以及常见连接问题的排查思路。

MiniMax 提供者在 AIRI 中的定位

AIRI 的"意识"模块承载着聊天（chat）能力，而聊天能力由可插拔的提供者（provider）驱动。MiniMax 作为提供者之一，其定位在源码中非常明确：

• 在中国大陆版与 Global 版两个入口中，tasks均声明为['chat']，即该提供者只承担聊天任务（见 providers/minimax/index.ts）；
• MiniMax 提供与 OpenAI 格式兼容的聊天 API，因此 AIRI 复用了统一的 OpenAI 兼容校验器体系；
• 两个平台（中国大陆版与 Global）的 API Key、计费方式与 Base URL 彼此独立，不可混用。

选择中国大陆版还是 MiniMax Global？

这是配置前必须先回答的问题，判定依据只有一个：你的 API Key 是在哪个平台生成的。

具体对照可参考同目录下的 MiniMax Global 配置文档，两个平台规则相同，仅端点和 Key 归属不同。

第一步：在中国大陆 MiniMax 平台申请 API Key

1. 打开 MiniMax 控制台（platform.minimaxi.com）。
2. 进入 API Keys 页面，创建一个新的 API Key。
3. 复制 Key 并妥善保存在安全位置——该 Key 之后不会再完整展示。

安全警告：切勿将 API Key 提交到版本库、包含在截图中或分享给任何人。一旦发现 Key 泄露，应立即作废并在 MiniMax 控制台重新生成新 Key。

第二步：在 AIRI 中配置 MiniMax 提供者

1. 打开设置 → 提供者 → 聊天 → MiniMax。
2. 在默认配置项中粘贴 API Key。
3. 保持默认 Base URL 不变：https://api.minimaxi.com/v1/。

底层实现：默认值从何而来

从源码看，中国大陆版与 Global 版的配置结构均基于 zod schema 定义，关键差异就在默认 Base URL 与底层工厂函数（见 providers/minimax/index.ts）：

const minimaxCnConfigSchema = z.object({ apiKey: z.string('API Key'), baseUrl: z.string('Base URL').optional().default('https://api.minimaxi.com/v1/'), }) const minimaxGlobalConfigSchema = z.object({ apiKey: z.string('API Key'), baseUrl: z.string('Base URL').optional().default('https://api.minimax.io/v1/'), })

当createProvider被调用时，中国大陆版走createMinimaxCn(config.apiKey, config.baseUrl)，Global 版走createMinimax(config.apiKey, config.baseUrl)。因此，只要你的 Key 属于中国大陆版平台，就无需改动 Base URL，保持默认值即可正常发起请求。

注意：中国大陆版与海外平台的 API Key、计费账户与 Base URL 不能混用。例如把中国大陆版的 Key 配到api.minimax.io端点下，通常会得到鉴权类错误（文档中 Global 版明确指出401往往正是两地 Key 与端点错配所致）。

第三步：设置校验与模型选择

自动校验机制

AIRI 会在你编辑设置的过程中自动对提供者配置进行校验。其底层实现是复用的 OpenAI 兼容校验器createOpenAICompatibleValidators，MiniMax 提供者显式声明了三个校验项（见 providers/minimax/index.ts）：

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

这三项校验各自做了什么（实现见 validators/openai-compatible.ts）：

1. Connectivity（连通性）：向{baseUrl}/models发起 GET 请求，超时时间为 10 秒；若返回 HTTP 5xx 或请求失败（网络错误、超时），则判定连通性校验失败；
2. ModelList（模型列表）：拉取模型列表并检查其非空；拉取失败或无模型时给出"Model list check failed"提示；
3. ChatCompletions（聊天补全）：真正向模型发送一条内容为ping的用户消息，使用max_tokens: 16的最小请求体验证 Chat Completions 是否可用。只有连通且能收到模型回复，聊天校验才算通过。

此外，配置编辑时还有一个前置的check-config校验：API Key 为空、Base URL 为空或 Base URL 不是合法绝对 URL 时都会直接报错。

使用 Ping API 按钮做实测

当界面中出现Ping API按钮时，说明配置已达到可发起真实请求的状态，你可以用它做一次实测连通性测试。如果校验结果有异常，错误提示会直接呈现在设置页中，方便定位问题。

选择模型进入意识模块

• 校验通过后，点击模型选择 →按钮，打开设置 → 模块 → 意识；
• 在意识页面中，选择提供者为MiniMax，并挑选要使用的模型；
• 完成后发送一条短消息，验证 AIRI 是否正常返回 MiniMax 模型的回复。

问题排查清单

若 API 校验失败或模型无法正常使用，按以下顺序逐项检查：

1. API Key 是否正确：确认 Key 确实来自中国大陆版平台（platform.minimaxi.com），且已完整粘贴、无多余空格；
2. 账户积分与配额：确认 MiniMax 账户还有可用积分（credit）或配额（quota）；
3. 请求限制：确认当前请求没有触发平台的速率限制（rate limit）；
4. 网络连接：确认运行 AIRI 的设备可以正常访问https://api.minimaxi.com/，没有防火墙或代理阻断；
5. 模型列表加载失败：如果 AIRI 无法从 MiniMax 拉取模型列表，可以在意识页面中直接手动输入 MiniMax 提供的准确模型 ID——这是绕过列表拉取问题的可靠兜底方案。

延伸：MiniMax 在 AIRI 中的其他形态

除聊天提供者外，AIRI 中还定义了minimax-speech提供者（id 为minimax-speech），承担 text-to-speech 任务，其默认端点为https://api.minimax.io，内置speech-2.8-hd与speech-2.8-turbo两个模型（见 providers/minimax-speech/index.ts）。本指南聚焦的聊天配置与之相互独立，二者可分别配置使用。

提供者的本地化文案（含minimaxi.com/minimax.io的描述）维护在 settings.yaml 中，各语言版本同步维护，配置界面会自动按界面语言展示对应名称。

小结

接入 MiniMax 中国大陆版只需三步：在 platform.minimaxi.com 申请 Key → 在设置 → 提供者 → 聊天 → MiniMax中粘贴 Key（保持默认 Base URL）→ 通过校验后在设置 → 模块 → 意识中选定提供者与模型。AIRI 的自动校验机制会替你完成连通性、模型列表与真实聊天请求三项检查，配合 Ping 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-sama's altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported.项目地址: https://gitcode.com/GitHub_Trending/ai/airi