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），僅供參考