AIRI 接入 Atlas CloudOpenAI 兼容 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-samas 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在 Atlas Cloud 官方网站注册账号并进入控制台创建一个 API Key。复制生成的 Key妥善保存在本地安全位置例如密码管理器后续配置时需要粘贴到 AIRI 中。API Key 安全警告不要把 API Key 提交到 Git 仓库、不要出现在截图里、也不要分享给任何人。一旦 Key 疑似泄露请立即在 Atlas Cloud 控制台吊销并重新生成新的 Key。在 AIRI 中配置 Atlas Cloud配置入口打开Settings → Providers → Chat → Atlas Cloud进入提供方配置页。该入口对应 AIRI 的提供方目录与配置界面Atlas Cloud 在目录中的定义如下节选自 atlascloud/index.tsexport const providerAtlasCloud defineProviderAtlasCloudConfig({ 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.tsconst 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), })字段是否必填说明默认值apiKey是Atlas Cloud 的 API Key界面中按密码框type: password展示输入内容不可见无baseUrl否API 端点地址保持默认即可https://api.atlascloud.ai/v1操作步骤将 API Key 粘贴到基础设置basic settings的 API Key 输入框中Base URL 保持默认值https://api.atlascloud.ai/v1保存配置。值得注意的是validationRequiredWhen的实现atlascloud/index.tsvalidationRequiredWhen(config) { return !!config.apiKey?.trim() },也就是说只有当 API Key 非空且去空格后仍有内容时AIRI 才会触发自动校验未填写 Key 时配置状态停留在unconfigured不会发起任何网络请求。验证配置Ping API 的底层原理三项内置检查Atlas Cloud 复用了 AIRI 的 OpenAI 兼容验证器createOpenAICompatibleValidators并启用了连通性、模型列表、Chat 补全三项运行时检查atlascloud/index.tsvalidators: { ...createOpenAICompatibleValidators({ checks: [ProviderValidationCheck.Connectivity, ProviderValidationCheck.ModelList, ProviderValidationCheck.ChatCompletions], }), },这三项检查在 types.ts 中定义Connectivity连通性向{baseUrl}/models发起轻量 GET 请求确认网络可达、服务端未返回 5xxModelList模型列表拉取模型列表并确认非空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.tsAPI 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 检查失败请按以下顺序排查API Key 是否正确重新核对复制的 Key注意前后空格确认没有误粘贴其他内容账户额度/配额检查 Atlas Cloud 账户是否有可用余额credit或 quota欠费/限流会导致请求被拒速率限制rate limits若短时间内请求过多被限流可稍后重试或查看控制台的用量情况网络连接确认本机可正常访问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 URLpackages/stage-ui/src/libs/providers/providers/atlascloud/index.tsOpenAI 兼容验证器实现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-samas altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported.项目地址: https://gitcode.com/GitHub_Trending/ai/airi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考