企业官网建设流程全解析

• 人工智能
• AI Agent
• MCP 服务
• 工具调用
• GUI 自动化
• 语音
• 数字人
• 交互助手

本篇技术指南以 AIRI 官方手册中 Moonshot AI 服务商配置文档为核心，系统讲解如何在 AIRI 中将 Moonshot（月之暗面）配置为聊天模型提供者，包括 API Key 的获取、Base URL 的正确选择、配置自动校验与 Ping API 的用法，以及最终在「意识（Consciousness）」模块中启用模型的完整流程。读完本文，你将能够独立完成 Moonshot 与 AIRI 的对接，并理解 AIRI 服务商验证机制在源码层面的工作原理，便于在接入失败时快速定位问题。

为什么选择 Moonshot？

Moonshot AI 提供与 OpenAI 格式兼容的聊天 API。在 AIRI 中，Moonshot 被内置为聊天（chat）任务的云端服务商，这意味着：

• 如果你希望在 AIRI 中使用 Moonshot 模型，可以直接在服务商目录中选中它，无需手动填写 OpenAPI 兼容的通用配置；
• 如果你已经拥有 Moonshot API Key，可以跳过模型服务商的注册环节，直接粘贴密钥完成接入；
• 从源码定义看，Moonshot 提供者还支持推理模式（reasoning）的开启与关闭，详见下文「推理能力」一节。

官方手册中 Moonshot 配置文档存在多语言版本，除本文依据的韩文版外，还可在仓库中查阅 英文版 与 简体中文版。

第一步：获取 API Key

在开始配置 AIRI 之前，需要先到 Moonshot 控制台申请 API Key：

1. 打开 Moonshot 官方控制台（全球版platform.moonshot.ai；中国大陆用户使用platform.moonshot.cn）。
2. 进入API Keys页面，创建一个新的 API Key。
3. 复制该密钥，并妥善保存在安全位置（如密码管理器）。

API Key 安全警告：切勿将 API Key 提交到 Git 仓库、放入截图或分享给任何人。一旦密钥泄露，应立即在 Moonshot 控制台将其撤销（revoke），并重新生成新密钥。

第二步：在 AIRI 中配置 Moonshot

完成密钥申请后，按以下步骤在 AIRI 中配置服务商：

1. 打开设置 → 服务商（Providers）→ 聊天（Chat）→ Moonshot AI。
2. 在基础设置中粘贴 API Key。
3. 保留全局默认的 Base URL：https://api.moonshot.ai/v1/。

在服务商编辑界面的 API Key 输入框中，AIRI 会展示ms-...格式的占位提示，帮助识别 Moonshot 密钥的典型形态，相关逻辑见 服务商配置引导组件。

Base URL 与地区端点：一个容易被忽略的坑

手册中特别强调了一个关键约束：凭据（credentials）与端点（endpoint）不能跨地区混用。

• 在platform.moonshot.ai（全球版）申请的 API Key，必须使用全局端点https://api.moonshot.ai/v1/；
• 在platform.moonshot.cn（中国大陆版）申请的 API Key，则必须改用该控制台文档所指引的中国区端点（简体中文版手册给出的默认值为https://api.moonshot.cn/v1）。

如果混用不同地区的 Key 与端点，API 校验会失败。

源码视角：Moonshot 提供者的定义

AIRI 将 Moonshot 封装为独立的提供者定义，位于 提供者实现。其核心结构如下：

• 提供者 ID：moonshot-ai，显示名称Moonshot AI（简体中文界面中本地化显示为「月之暗面」，见 zh-Hans 设置文案）；
• 任务类型：tasks: ['chat']，即仅作为聊天模型提供者；
• 配置模式：使用 zod 定义配置，其中apiKey为必填字符串，baseUrl为可选字符串，默认值即为https://api.moonshot.ai/v1/（对应源码 moonshot-ai/index.ts）；
• 能力声明：chat.reasoning.modes支持['enabled', 'disabled']，表示聊天请求可携带推理模式开关；
• 创建提供者：通过createMoonshotai(config.apiKey, config.baseUrl)生成实例，并对chat()方法做了包装——当请求选项带reasoning时，会向请求注入thinking: { type: options.reasoning }，从而实现推理模式的透传（对应源码 moonshot-ai/index.ts）。

此外，在服务商目录筛选层面，Moonshot 被归类为paid（付费）＋ cloud（云端）属性（见 提供者属性表），因此在设置页的「来源」筛选中会出现在付费云端服务商分组下。

第三步：验证配置

配置完成后，AIRI 会主动帮你确认一切是否就绪，手册给出的验证路径有两步：

1. 配置自动验证（Validate configuration）：AIRI 会在你编辑配置的过程中自动进行有效性校验。当界面出现Ping API按钮时，说明可以发起一次真实的请求测试。
2. 选择模型 →（Select Model →）：校验通过后，点击该按钮可直接跳转到设置 → 模块（Modules）→ 意识（Consciousness），在这里选择服务商与具体模型。

源码视角：验证器到底检查了什么

Moonshot 提供者复用了 OpenAI 兼容验证器，启用了三类检查：Connectivity（连通性）、ModelList（模型列表）、ChatCompletions（聊天补全），见 moonshot-ai/index.ts。这三项检查在 openai-compatible 验证器实现 中分别对应：

• check-config：校验apiKey非空、baseUrl为绝对 URL（必须包含主机名），不满足则直接报错；
• check-connectivity：向{baseUrl}/models发起带Authorization: Bearer <apiKey>的轻量 GET 请求，并设置10 秒超时；只有 HTTP 5xx 服务端错误才判定连通性失败（openai-compatible.ts）；
• check-model-list：拉取模型列表并校验其非空；
• check-chat-completions：发送一条内容为ping的最小聊天请求（max_tokens: 16），验证服务商确实能返回聊天补全结果，而非仅仅接口可达（openai-compatible.ts）。

从 ProviderValidationCheck 枚举定义 可以看到，这三类检查被设计为可组合的校验单元，AIRI 中绝大多数 OpenAI 兼容服务商（OpenAI、DeepSeek、Minimax、xAI 等）都复用同一套机制，Moonshot 属于校验最完整的一档（连通性＋模型列表＋真实对话三合一）。

手动触发校验的条件

源码还揭示了一个细节：validationRequiredWhen(config)表明只有填写了非空apiKey时，验证才会被触发（见 moonshot-ai/index.ts）。因此，若尚未粘贴密钥就看不到 Ping API 按钮，属于正常现象。

第四步：在「意识」模块中选用 Moonshot 模型

验证通过后，进入设置 → 模块 → 意识，即可从服务商列表中选择 Moonshot AI，并挑选具体模型。AIRI 会自动拉取 Moonshot 提供的模型清单供选择。

需要说明的是：如果由于网络、额度或服务商侧原因导致模型列表加载失败，不必卡在这一步——你可以在「意识」页面手动输入 Moonshot 官方提供的精确模型 ID（例如kimi-k2-0711-preview之类的 Moonshot 模型标识），AIRI 仍可正常发起对话请求。这也是手册「排查」一节给出的官方兜底方案。

问题排查速查表

手册将 Moonshot 接入的常见问题归纳如下，结合源码可以给出更精确的排查顺序：

关联文档与源码路径

便于你继续深入阅读的仓库路径：

• 手册原文（本文依据）：docs/content/ko/docs/manual/config/providers/consciousness/moonshot.md
• 英文与简体中文手册：英文版、简体中文版
• 提供者核心实现：packages/provider-inference/src/providers/cloud/moonshot-ai/index.ts
• 验证器实现：packages/provider-inference/src/validators/openai-compatible.ts
• 校验项类型定义：packages/provider-inference/src/types.ts
• 服务商注册机制：packages/provider-inference/src/providers/registry.ts
• 服务商目录属性：packages/stage-ui/src/libs/providers/attributes.ts

完成上述配置后，你的 AIRI 便可以在「意识」中通过 Moonshot 模型进行对话了；若后续需要调整推理模式，可直接在聊天请求选项中开启或关闭reasoning，AIRI 会通过thinking字段将其透传给 Moonshot API。

• 人工智能
• AI Agent
• MCP 服务
• 工具调用
• GUI 自动化
• 语音
• 数字人
• 交互助手