AIRI 通用 Provider 配置指南设置流程、字段说明与验证排查【免费下载链接】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 配置工作的总入口。AIRI 将文本回复Chat/Consciousness、视觉理解Vision、语音合成Speech、语音识别Transcription与绘画生成Artistry统一抽象为服务提供方Provider模型所有 Provider 的配置都遵循同一套流程、共享同一组核心字段并通过自动验证与 Ping API 确认连通性。读完本文你将掌握Provider 配置的标准操作步骤、API Key / Base URL / Model / Voice / Region 等通用字段的含义与填写规范、验证结果的解读方法以及一套可复用的故障排查顺序。本文以 common.md 为骨架并结合仓库源码补充字段的底层实现细节。配置流程五步接入一个 Provider无论你接入的是云端服务商还是本地模型服务如 Ollama、LM Studio配置路径都是统一的打开Settings → Providers在Chat对话、Vision视觉、Speech语音合成、Transcription语音识别或Artistry绘画中选择一项能力。选择一个 Provider并在其设置页面填写该服务商要求的凭据。如有必要展开高级设置Advanced Settings按服务商文档填写 Base URL 或其他参数。等待自动校验结果若该 Provider 提供Ping API可发起一次真实请求进行实测可能消耗少量额度。到Settings → Modules下对应的页面如Consciousness、Speech、Hearing选择已配置好的 Provider 与模型或音色。这个流程在源码中的落地形态很直观Provider 设置页由ProviderBasicSettings基础设置含 API Key 输入框、ProviderAdvancedSettings高级设置含 Base URL 输入框与ProviderValidationAlerts校验结果提示区三块组成见 chat provider 设置页。[providerId]动态路由意味着 Chat / Vision 等不同能力共享同一套通用设置页组件这正是所有 Provider 统一配置体验的实现基础。⚠️凭据安全凭据与 Provider 设置保存在当前设备的本地设置中。切勿在截图、日志、Issue 或聊天消息中泄露 API Key、AccessKey Secret 等敏感信息。通用字段详解下表是各 Provider 设置页共同的核心字段字段含义填写建议API Key服务商签发的访问令牌粘贴完整密钥不要额外加引号或空格。Base URLProvider API 的根地址仅当服务商文档要求其他地址时才修改必须包含完整的https://或http://前缀。Model用于对话、语音或识别的模型 ID优先选择 AIRI 内置列表中的模型若列表无法加载且字段支持自定义输入则按服务商文档填入精确的模型 ID。Voice语音合成使用的音色 ID先选择模型再选择该模型支持的音色。Region部分云服务的部署区域与服务商控制台中显示的项目/资源区域保持一致。这些字段的存储与校验在源码中有明确对应Provider 配置通过useLocalStorage持久化到浏览器本地存储键settings/providers/configured见 config.ts也就是说AIRI 的凭据只保存在运行 AIRI 的这台设备上不会上传到项目服务器——这与文档中凭据保存在当前设备本地设置的说明完全吻合。在通用设置页组件中API Key 与 Base URL 是典型的一对 computed 属性直接读写providers[providerId].apiKey与providers[providerId].baseUrl见 providerId.vue。值得注意的细节包括API Key 输入框的占位符如sk-...并非写死而是从 Provider 定义通过createProviderConfig生成的 zod schema 中读取apiKey字段的placeholderLocalized元数据动态获得见 providerId.vue。Base URL 输入框的占位符取自该 Provider 的默认配置providerMetadata?.defaultConfig.baseUrl因此不同服务商默认地址各不相同例如 DeepSeek 的默认配置即为https://api.deepseek.com/见 config-defaults.test.ts。部分 Provider 还有额外的高级字段例如 DeepSeek 支持Thinking Mode思考模式取值可为auto/disable/enable见 providerId.vue。这说明通用字段 服务商专属字段是 AIRI Provider 配置体系的完整结构。验证方式与结果解读验证分为两类自动校验Chat Provider 的表单会自动校验必填字段如 API Key 格式、Base URL 是否为合法 URL。校验随编辑实时触发Provider 字段在编辑过程中即被保存。主动测试支持Ping API的 Provider 可发送一次真实请求验证 Key 与地址的连通性注意可能消耗少量额度Speech Provider 的 Playground 可实测语音合成与播放转写能力可在Settings → Modules → Hearing页选择麦克风后实测。校验结果区由ProviderValidationAlerts组件渲染其状态由useProviderValidationcomposable 统一管理包含isValidating校验中、isValid是否通过、validationMessage校验消息、hasManualValidators是否有手动校验器、manualTestPassed/manualTestMessage手动测试结果与runManualTest发起手动测试等状态见 providerId.vue。校验通过后页面会提供Select Model快捷入口直接跳转到Settings → Modules → Consciousness选择模型。故障排查按顺序排除五个环节当验证失败时按下述顺序排查账户状态确认账户有权访问该服务且余额或配额充足。API Key 复制重新复制 API Key确保开头和结尾没有混入空格或换行。Base URL恢复默认值或与官方文档逐字比对。网络环境确认网络、代理与防火墙允许访问该服务商。模型 ID选择服务商明确支持的模型不要拿显示名称当模型 ID 使用。这套排查顺序在 Provider 专属指南中也有呼应。例如 OpenRouter 的接入指南在Troubleshooting一节给出完全一致的建议校验失败时依次核查 API Key、可用余额或配额、速率限制与网络连接若模型列表无法加载则在Consciousness页面手动填入 OpenRouter 文档中的精确模型 ID见 openrouter.md。关于校验通过但没有模型还有一种常见情形需要区分有些 Provider 的接口不返回模型列表或当前 API Key 缺少列表权限。此时在Settings → Modules → Consciousness手动输入模型 ID 即可但模型 ID 必须与服务商文档完全一致。与专属指南、模块配置的关系本文是配置手册的总纲它与同目录下的其他文档构成完整闭环配置文本回复对话模型阅读 配置 Chat 模型。它强调 chat 模型是 AIRI 的大脑并详细说明了从 Provider 配置到Modules → Consciousness选择模型、再到发送一条消息验证的完整链路同时点明仅保存 Provider 凭据并不会自动启用该 Provider最终必须在模块页完成选择。配置语音输入与输出阅读 配置语音输入输出。TTS 链路为 Providers → Speech 配置凭据 → Playground 试听 →Modules → Speech选择 Provider/模型/音色ASR 链路为 Providers → Transcription 配置凭据 →Modules → Hearing选择模型 → 选择麦克风并Start Monitoring实测。各能力均有独立的 Provider 专属指南位于 docs/content/en/docs/manual/config/providers 目录下按Chat / Vision / Speech / Transcription / Artistry分类组织涵盖 OpenRouter、DeepSeek、OpenAI、Ollama、Anthropic、Azure 等大量服务商以及浏览器本地 / 桌面本地等离线方案。以 OpenRouter 为例可以看到完整闭环的实操形态先在 OpenRouter 控制台。这个例子完整覆盖了本文描述的配置流程 → 通用字段 → 验证 → 选模型全链路。结语AIRI 的 Provider 配置体系将五大 AI 能力统一在一处填凭据、模块页选模型的模式之下凭据只存本地设备通用字段少而稳定验证手段自动校验 Ping API Playground覆盖从格式检查到真实连通性的全层级且每个 Provider 都有配套的专属指南可查。掌握本文的通用流程与排查顺序后无论接入哪个服务商你都能按同一套方法论完成配置与问题定位。【免费下载链接】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），仅供参考