在 AIRI 中接入 Atlas CloudOpenAI 兼容聊天提供者的配置、验证与排障指南【免费下载链接】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 提供者」一篇展开讲解如何将 Atlas Cloud 的 OpenAI 格式兼容聊天 API 接入 AIRI 的「意识Consciousness」模块使 AIRI 能够调用 Atlas Cloud 托管的模型参与对话与人格运转。读完本文你将掌握 API Key 的获取与安全保管、提供者的图形化配置路径、内置的三级自动校验机制连通性 / 模型列表 / 对话补全的底层实现以及校验失败时的系统性排查方法。Atlas Cloud 是什么面向 AIRI 的 OpenAI 兼容聊天提供者Atlas Cloud 是一家提供 OpenAI 格式兼容聊天 API 的服务商。对 AIRI 而言它属于内置的「OpenAI 兼容」类提供者其定义位于源码 packages/stage-ui/src/libs/providers/providers/atlascloud/index.ts核心事实如下任务类型tasks: [chat]即仅承担聊天对话补全职责默认 Base URLhttps://api.atlascloud.ai/v1与手册中「保持默认 Base URL」的指引一一对应运行时构造通过createOpenAI(config.apiKey, config.baseUrl)创建符合 OpenAI 协议的客户端实例注册方式使用提供者注册表中的defineProvider完成注册见 registry.tsid: atlascloudorder: 5控制其在提供者目录中的展示顺序导入语句出现在 providers/index.ts确保应用启动时完成注册。因此在什么场景下选择 Atlas Cloud官方文档给出明确答案当你已经持有 Atlas Cloud 的 API Key或希望直接使用 Atlas Cloud 提供的模型时无需额外配置自定义 OpenAI 兼容端点直接选择内置提供者即可。第一步获取并妥善保管 API Key获取流程访问 Atlas Cloud 官网https://www.atlascloud.ai/注册账户在控制台中创建 API Key复制生成的 Key 并保存到安全位置密码管理器或环境变量文件。安全红线官方手册对此有明确警告请务必遵守不要将 API Key 提交进版本库commit不要把 Key 截进截图或与他人共享一旦 Key 疑似泄露立即在 Atlas Cloud 控制台作废旧 Key 并签发新 Key。从源码角度看Air UI 层将 API Key 字段设计为密码输入框type: password见 atlascloud/index.ts 中的meta配置避免 Key 明文显示在设置界面上。第二步在 AIRI 中配置 Atlas Cloud配置入口与步骤来自官方手册打开设置 → 提供者 → 聊天 → Atlas Cloud在基本设置中粘贴 API Key保持默认 Base URL 不变https://api.atlascloud.ai/v1。配置字段的源码级说明Atlas Cloud 的配置结构由 zod 模式定义atlascloud/index.ts共两个字段字段类型必填默认值说明apiKeystring是无Atlas Cloud 控制台签发的 API Key界面以密码框呈现baseUrlstring否https://api.atlascloud.ai/v1API 端点留空时自动回落到默认值手册要求「保持默认 Base URL」与源码中.default(ATLASCLOUD_DEFAULT_BASE_URL)的回落逻辑完全一致——即使你在界面上清空该字段校验时也会按默认值处理。测试用例 inference-service-providers.test.ts 对此有直接验证仅传入{ apiKey: test-key }时解析结果即为{ apiKey: test-key, baseUrl: ATLASCLOUD_DEFAULT_BASE_URL }。配置保存后Atlas Cloud 即成为一个status: unconfigured的本地提供者实例等待后续输入校验。第三步配置校验与模型选择自动校验与 Ping API手册指出AIRI 在编辑配置时会自动进行校验若界面出现Ping API按钮即可点击发起一次真实请求测试。这背后是提供者定义中挂载的校验器validatorsAtlas Cloud 启用了三类检查atlascloud/index.tsvalidators: { ...createOpenAICompatibleValidators({ checks: [ ProviderValidationCheck.Connectivity, // 连通性 ProviderValidationCheck.ModelList, // 模型列表 ProviderValidationCheck.ChatCompletions // 对话补全 ], }), }三个检查项在 openai-compatible.ts 中均有可验证的实现配置检查check-config校验 API Key 非空trim()后、Base URL 非空且为合法的绝对 URLopenai-compatible.ts#L213-L244连通性检查check-connectivity向baseUrl/models发起带Authorization: Bearer apiKey的 GET 请求10 秒超时仅当返回 5xx 或网络异常时才判定失败openai-compatible.ts#L246-L295对话补全检查check-chat-completions先拉取模型列表并自动挑选一个非跳过模型跳过embed、tts等非对话 ID再以该模型发送一条ping消息的真实补全请求max_tokens固定为 16结果按校验缓存与互斥锁复用避免同一配置反复触发重复请求openai-compatible.ts#L117-L206。另外提供者定义了validationRequiredWhen: (config) !!config.apiKey?.trim()atlascloud/index.ts#L48-L50只有粘贴了非空 API Key 后配置状态才会从unconfigured进入自动校验流程。模型选择校验通过后点击选择模型 →按钮进入设置 → 模块 → 意识页面选择 Atlas Cloud 作为提供者并挑选具体模型 ID。该页面用于激活 AIRI 的「意识」能力即对话与人格层的运行时提供者。问题排查若 API 校验失败官方手册建议按以下顺序排查API Key确认粘贴的 Key 完整、无多余空格、未过期或作废余额 / 配额确认 Atlas Cloud 账户存在可用额度未被限流或欠费停用请求限制确认当前用量未触及账户的速率限制rate limit网络连接确认本机到api.atlascloud.ai的网络可达未被防火墙、代理或地区策略阻断。从源码可进一步定位故障表现与根因的对应关系若连通性检查返回 5xx说明服务端异常报错形如Server error: HTTP status若检查抛出网络错误如 DNS 失败、超时、连接被拒会直接判定为连通性失败若 Base URL 非法会在配置检查阶段被拦截提示Base URL is invalid. It must be an absolute URL.。手册还特别说明一种常见场景AIRI 无法自动加载模型列表例如模型列表接口被限流或返回为空。此时可在「意识」页面手动输入 Atlas Cloud 提供的精确模型 ID绕过模型列表依赖直接指定模型进行对话。总结Atlas Cloud 接入 AIRI 的路径非常清晰获取并安全保管 API Key → 在「设置 → 提供者 → 聊天」选择 Atlas Cloud 并粘贴 Key、保留默认 Base URL → 借助内置的自动校验连通性、模型列表、对话补全三级检查确认配置可用 → 在「设置 → 模块 → 意识」中选择模型激活。整个过程完全图形化无需手写配置文件若需更深层定制可参考 atlascloud/index.ts 与其底层校验实现 openai-compatible.ts 理解每个检查项的判定逻辑从而在故障时快速定位是 Key、配额、限流还是网络层面的问题。【免费下载链接】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），仅供参考 在 AIRI 中接入 Atlas Cloud：OpenAI 兼容聊天提供者的配置、验证与排障指南
在 AIRI 中接入 Atlas CloudOpenAI 兼容聊天提供者的配置、验证与排障指南【免费下载链接】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 提供者」一篇展开讲解如何将 Atlas Cloud 的 OpenAI 格式兼容聊天 API 接入 AIRI 的「意识Consciousness」模块使 AIRI 能够调用 Atlas Cloud 托管的模型参与对话与人格运转。读完本文你将掌握 API Key 的获取与安全保管、提供者的图形化配置路径、内置的三级自动校验机制连通性 / 模型列表 / 对话补全的底层实现以及校验失败时的系统性排查方法。Atlas Cloud 是什么面向 AIRI 的 OpenAI 兼容聊天提供者Atlas Cloud 是一家提供 OpenAI 格式兼容聊天 API 的服务商。对 AIRI 而言它属于内置的「OpenAI 兼容」类提供者其定义位于源码 packages/stage-ui/src/libs/providers/providers/atlascloud/index.ts核心事实如下任务类型tasks: [chat]即仅承担聊天对话补全职责默认 Base URLhttps://api.atlascloud.ai/v1与手册中「保持默认 Base URL」的指引一一对应运行时构造通过createOpenAI(config.apiKey, config.baseUrl)创建符合 OpenAI 协议的客户端实例注册方式使用提供者注册表中的defineProvider完成注册见 registry.tsid: atlascloudorder: 5控制其在提供者目录中的展示顺序导入语句出现在 providers/index.ts确保应用启动时完成注册。因此在什么场景下选择 Atlas Cloud官方文档给出明确答案当你已经持有 Atlas Cloud 的 API Key或希望直接使用 Atlas Cloud 提供的模型时无需额外配置自定义 OpenAI 兼容端点直接选择内置提供者即可。第一步获取并妥善保管 API Key获取流程访问 Atlas Cloud 官网https://www.atlascloud.ai/注册账户在控制台中创建 API Key复制生成的 Key 并保存到安全位置密码管理器或环境变量文件。安全红线官方手册对此有明确警告请务必遵守不要将 API Key 提交进版本库commit不要把 Key 截进截图或与他人共享一旦 Key 疑似泄露立即在 Atlas Cloud 控制台作废旧 Key 并签发新 Key。从源码角度看Air UI 层将 API Key 字段设计为密码输入框type: password见 atlascloud/index.ts 中的meta配置避免 Key 明文显示在设置界面上。第二步在 AIRI 中配置 Atlas Cloud配置入口与步骤来自官方手册打开设置 → 提供者 → 聊天 → Atlas Cloud在基本设置中粘贴 API Key保持默认 Base URL 不变https://api.atlascloud.ai/v1。配置字段的源码级说明Atlas Cloud 的配置结构由 zod 模式定义atlascloud/index.ts共两个字段字段类型必填默认值说明apiKeystring是无Atlas Cloud 控制台签发的 API Key界面以密码框呈现baseUrlstring否https://api.atlascloud.ai/v1API 端点留空时自动回落到默认值手册要求「保持默认 Base URL」与源码中.default(ATLASCLOUD_DEFAULT_BASE_URL)的回落逻辑完全一致——即使你在界面上清空该字段校验时也会按默认值处理。测试用例 inference-service-providers.test.ts 对此有直接验证仅传入{ apiKey: test-key }时解析结果即为{ apiKey: test-key, baseUrl: ATLASCLOUD_DEFAULT_BASE_URL }。配置保存后Atlas Cloud 即成为一个status: unconfigured的本地提供者实例等待后续输入校验。第三步配置校验与模型选择自动校验与 Ping API手册指出AIRI 在编辑配置时会自动进行校验若界面出现Ping API按钮即可点击发起一次真实请求测试。这背后是提供者定义中挂载的校验器validatorsAtlas Cloud 启用了三类检查atlascloud/index.tsvalidators: { ...createOpenAICompatibleValidators({ checks: [ ProviderValidationCheck.Connectivity, // 连通性 ProviderValidationCheck.ModelList, // 模型列表 ProviderValidationCheck.ChatCompletions // 对话补全 ], }), }三个检查项在 openai-compatible.ts 中均有可验证的实现配置检查check-config校验 API Key 非空trim()后、Base URL 非空且为合法的绝对 URLopenai-compatible.ts#L213-L244连通性检查check-connectivity向baseUrl/models发起带Authorization: Bearer apiKey的 GET 请求10 秒超时仅当返回 5xx 或网络异常时才判定失败openai-compatible.ts#L246-L295对话补全检查check-chat-completions先拉取模型列表并自动挑选一个非跳过模型跳过embed、tts等非对话 ID再以该模型发送一条ping消息的真实补全请求max_tokens固定为 16结果按校验缓存与互斥锁复用避免同一配置反复触发重复请求openai-compatible.ts#L117-L206。另外提供者定义了validationRequiredWhen: (config) !!config.apiKey?.trim()atlascloud/index.ts#L48-L50只有粘贴了非空 API Key 后配置状态才会从unconfigured进入自动校验流程。模型选择校验通过后点击选择模型 →按钮进入设置 → 模块 → 意识页面选择 Atlas Cloud 作为提供者并挑选具体模型 ID。该页面用于激活 AIRI 的「意识」能力即对话与人格层的运行时提供者。问题排查若 API 校验失败官方手册建议按以下顺序排查API Key确认粘贴的 Key 完整、无多余空格、未过期或作废余额 / 配额确认 Atlas Cloud 账户存在可用额度未被限流或欠费停用请求限制确认当前用量未触及账户的速率限制rate limit网络连接确认本机到api.atlascloud.ai的网络可达未被防火墙、代理或地区策略阻断。从源码可进一步定位故障表现与根因的对应关系若连通性检查返回 5xx说明服务端异常报错形如Server error: HTTP status若检查抛出网络错误如 DNS 失败、超时、连接被拒会直接判定为连通性失败若 Base URL 非法会在配置检查阶段被拦截提示Base URL is invalid. It must be an absolute URL.。手册还特别说明一种常见场景AIRI 无法自动加载模型列表例如模型列表接口被限流或返回为空。此时可在「意识」页面手动输入 Atlas Cloud 提供的精确模型 ID绕过模型列表依赖直接指定模型进行对话。总结Atlas Cloud 接入 AIRI 的路径非常清晰获取并安全保管 API Key → 在「设置 → 提供者 → 聊天」选择 Atlas Cloud 并粘贴 Key、保留默认 Base URL → 借助内置的自动校验连通性、模型列表、对话补全三级检查确认配置可用 → 在「设置 → 模块 → 意识」中选择模型激活。整个过程完全图形化无需手写配置文件若需更深层定制可参考 atlascloud/index.ts 与其底层校验实现 openai-compatible.ts 理解每个检查项的判定逻辑从而在故障时快速定位是 Key、配额、限流还是网络层面的问题。【免费下载链接】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），仅供参考