企业官网建设流程全解析

AIRI 接入 Atlas Cloud：OpenAI 兼容 Chat 提供方配置与源码级验证机制解析

【免费下载链接】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 中接入 Atlas Cloud——一个兼容 OpenAI Chat 格式的云端模型服务。读完本文你将掌握：获取并安全保管 Atlas Cloud API Key、在Settings → Providers中完成提供方配置、理解 AIRI 自动校验（Ping API）的底层原理，以及在Settings → Modules → Consciousness中为角色"意识"模块选定模型并完成故障排查。文中所有配置项与校验流程均以仓库源码为据，可直接对照复现。

为什么选择 Atlas Cloud

如果你已经持有 Atlas Cloud 的 API Key，或者希望直接使用它提供的模型，就可以把 Atlas Cloud 作为 AIRI 的对话（chat）提供方接入。从提供方目录的角度看，Atlas Cloud 在 AIRI 中被归类为付费云端服务（paid / cloud）——这一点可以在提供方属性表 attributes.ts 中看到'atlascloud': paidCloud的登记。

与本地运行模型（如 Ollama、LM Studio）不同，Atlas Cloud 是远程托管服务，无需本地 GPU，只需网络可达即可使用，适合希望开箱即用地获得云端模型能力的场景。

获取 API Key

1. 在 Atlas Cloud 官方网站注册账号，并进入控制台创建一个 API Key。
2. 复制生成的 Key，妥善保存在本地安全位置（例如密码管理器），后续配置时需要粘贴到 AIRI 中。

API Key 安全警告不要把 API Key 提交到 Git 仓库、不要出现在截图里、也不要分享给任何人。一旦 Key 疑似泄露，请立即在 Atlas Cloud 控制台吊销并重新生成新的 Key。

在 AIRI 中配置 Atlas Cloud

配置入口

打开Settings → Providers → Chat → Atlas Cloud，进入提供方配置页。该入口对应 AIRI 的提供方目录与配置界面，Atlas Cloud 在目录中的定义如下（节选自 atlascloud/index.ts）：

export const providerAtlasCloud = defineProvider<AtlasCloudConfig>({ id: 'atlascloud', order: 5, name: 'Atlas Cloud', tasks: ['chat'], icon: 'i-lobe-icons:openai', // ... })

• id: 'atlascloud'：提供方的稳定标识，用于注册表索引与持久化配置关联；
• tasks: ['chat']：声明该提供方仅承担对话（Chat）任务，因此在Settings → Providers → Chat分类下可见；
• icon: 'i-lobe-icons:openai'：由于 Atlas Cloud 兼容 OpenAI 协议，界面沿用了 OpenAI 风格图标。

配置项与默认值

在配置页中需要填写两个字段，其 schema 定义在同一文件 atlascloud/index.ts：

const ATLASCLOUD_DEFAULT_BASE_URL = 'https://api.atlascloud.ai/v1' const atlasCloudConfigSchema = z.object({ apiKey: z.string('API Key'), baseUrl: z.string('Base URL').optional().default(ATLASCLOUD_DEFAULT_BASE_URL), })

操作步骤：

1. 将 API Key 粘贴到基础设置（basic settings）的 API Key 输入框中；
2. Base URL 保持默认值https://api.atlascloud.ai/v1；
3. 保存配置。

值得注意的是validationRequiredWhen的实现（atlascloud/index.ts）：

validationRequiredWhen(config) { return !!config.apiKey?.trim() },

也就是说，只有当 API Key 非空（且去空格后仍有内容）时，AIRI 才会触发自动校验；未填写 Key 时配置状态停留在unconfigured，不会发起任何网络请求。

验证配置：Ping API 的底层原理

三项内置检查

Atlas Cloud 复用了 AIRI 的 OpenAI 兼容验证器（createOpenAICompatibleValidators），并启用了连通性、模型列表、Chat 补全三项运行时检查（atlascloud/index.ts）：

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

这三项检查在 types.ts 中定义：

• Connectivity（连通性）：向{baseUrl}/models发起轻量 GET 请求，确认网络可达、服务端未返回 5xx；
• ModelList（模型列表）：拉取模型列表并确认非空；
• ChatCompletions（对话补全）：发送一条真实的generateText探测消息，确认能完成一次对话生成。

Ping API 实际做了什么

配置编辑过程中 AIRI 会自动校验，校验通过后界面上会出现Ping API按钮，点击即可对当前配置发起一次实时请求测试。从验证器实现看（openai-compatible.ts），连通性检查的流程是：

const modelsUrl = baseUrl.endsWith('/') ? `${baseUrl}models` : `${baseUrl}/models` const controller = new AbortController() const timeout = setTimeout(() => controller.abort(), 10_000) const response = await fetch(modelsUrl, { method: 'GET', headers: { ...(config.apiKey ? { Authorization: `Bearer ${config.apiKey}` } : {}), }, signal: controller.signal, })

• 请求地址为https://api.atlascloud.ai/v1/models；
• 通过Authorization: Bearer <apiKey>携带凭证；
• 内置10 秒超时，超时自动中断请求；
• 仅当服务端返回 5xx 或网络错误时才判定连通性失败。

而 Chat 补全检查（openai-compatible.ts）会先自动挑选一个模型，然后发送user('ping')消息，并以max_tokens: 16的极小输出上限完成一次真实对话请求。校验结果会缓存并在同一校验周期内共享，避免重复探测。

此外，界面还提供 "skip chat ping check"（跳过对话 ping 检查）选项（见 step-provider-configuration.vue），以及校验失败后的重试按钮（见 provider-validation-alerts.vue），方便在网络波动时重试。

本地预校验：格式检查

除了运行时探测，配置保存前还会执行本地格式校验（openai-compatible:check-config，见 openai-compatible.ts）：

• API Key 不能为空（除非显式跳过该检查）；
• Base URL 不能为空；
• Base URL 必须是绝对 URL（解析后必须包含 host），否则报错Base URL is not absolute。

选择模型：接入 Consciousness 模块

校验成功后，点击界面上的Select Model →按钮，会跳转到Settings → Modules → Consciousness，在这里选择 Atlas Cloud 提供的具体模型。

Consciousness（意识）是 AIRI 中驱动角色对话行为的核心模块，其状态由consciousnessstore 统一管理（activeProvider/activeModel，见 consciousness store）。模型选择流程通过loadModelsForProvider拉取当前提供方的模型列表并渲染到选择器中（见 onboarding.vue 与 step-model-selection.vue）。

选择完成后，角色的对话请求将由 Atlas Cloud 通过 OpenAI 兼容接口（createOpenAI(config.apiKey, config.baseUrl)，见 atlascloud/index.ts）完成生成。

Troubleshooting：常见问题排查

如果 API 检查失败，请按以下顺序排查：

1. API Key 是否正确：重新核对复制的 Key，注意前后空格；确认没有误粘贴其他内容；
2. 账户额度/配额：检查 Atlas Cloud 账户是否有可用余额（credit）或 quota，欠费/限流会导致请求被拒；
3. 速率限制（rate limits）：若短时间内请求过多被限流，可稍后重试，或查看控制台的用量情况；
4. 网络连接：确认本机可正常访问https://api.atlascloud.ai/v1，企业网络/代理可能需要放行；若服务端返回 5xx，则是服务端临时故障，可等待后重试（见连通性检查的 5xx 判定逻辑）。

无法加载模型列表时：如果 AIRI 无法从 Atlas Cloud 拉取模型清单（例如服务端暂不支持模型列表接口），可以直接在Consciousness页面的模型输入框中手动输入 Atlas Cloud 官方给出的确切模型 ID，绕开模型列表拉取环节。

附：验证机制在测试中的体现

仓库的单元测试 inference-service-providers.test.ts 直接验证了 Atlas Cloud 提供方的关键行为：

it('lists Atlas Cloud as a built-in OpenAI-compatible provider', async () => { const schema = await providerAtlasCloud.createProviderConfig({ t: (key: string) => key }) expect(providerAtlasCloud.name).toBe('Atlas Cloud') expect(parseSchema(schema, { apiKey: 'test-key' })).toEqual({ apiKey: 'test-key', baseUrl: ATLASCLOUD_DEFAULT_BASE_URL, }) })

• 确认 Atlas Cloud 是内置的 OpenAI 兼容提供方（由 providers/index.ts 的import './atlascloud'注册）；
• 确认仅填写apiKey时，baseUrl会被自动补全为默认值https://api.atlascloud.ai/v1。

你可以通过pnpm vitest run inference-service-providers在本地复现这些断言，进一步验证配置解析逻辑。

关键文件速查

• 提供方定义与默认 Base URL：packages/stage-ui/src/libs/providers/providers/atlascloud/index.ts
• OpenAI 兼容验证器实现：packages/stage-ui/src/libs/providers/validators/openai-compatible.ts
• 校验检查类型定义：packages/stage-ui/src/libs/providers/types.ts
• 提供方注册机制：packages/stage-ui/src/libs/providers/providers/registry.ts
• 提供方目录属性（付费/云端分类）：packages/stage-ui/src/libs/providers/attributes.ts
• 提供方相关单元测试：packages/stage-ui/src/services/inference-service-providers.test.ts

【免费下载链接】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