AIRI 配置聊天模型实战指南:从服务商接入、Ping 验证到模型选择
AIRI 配置聊天模型实战指南:从服务商接入、Ping 验证到模型选择
在 AIRI(moeru-ai/airi)中,聊天模型是角色“意识”的“大脑”:完成本页所述的配置后,AIRI 才能生成文字回复。本文基于仓库中的官方手册 配置聊天模型 展开,完整覆盖前提条件、设置页操作步骤、Ping API 验证、模型选择与三类常见故障的排查方法,并结合 服务商设置页、验证组合式函数 与 意识状态存储 等源码,解释这些操作在 AIRI 内部的实际执行链路,帮助读者不仅“会配置”,还能理解“为什么这么配、失败时从哪里查”。
前提条件
开始配置前,请确认以下条件均已满足:
- 已安装并启动 AIRI。
- 云端服务商:已创建 API Key,并确认账户可以使用聊天模型(即账户有可用额度或订阅)。
- 本地服务:模型服务(如 Ollama、LM Studio)已经启动,且 AIRI 所在设备可以访问它的网络地址。
从源码结构看,AIRI 把“凭据是否合法”与“凭据是否可用”区分对待:自动校验只检查配置本身的完整性(例如 Base URL 是否填写),而真正会发起网络请求的聊天 Ping 只在你手动点击按钮时执行,以避免后台校验意外消耗 API 额度。这一设计直接对应下文“Ping API”一步。
操作步骤
第一步:选择聊天服务商
打开 设置 → 服务商 → 聊天,选择你要使用的服务商。不确定选哪个时,可先从仓库文档中已有的详细指南选择:
- OpenRouter:聚合式 API,一个 API Key 跨多个模型;
- DeepSeek;
- OpenAI 兼容 API:适用于 OpenAI 官方或任何提供 OpenAI Chat Completions 兼容接口的第三方服务;
- Ollama:本地运行模型,默认无需 API Key。
其他聊天服务商可从侧栏“服务商 → 聊天服务商”展开查看。
服务商列表由静态注册表驱动:设置页通过 listDefinedProviders() 枚举全部已定义服务商,并按分类生成元数据(见 provider store 中的 providerMetadataState)。每个服务商页面渲染后,会先调用 initializeProvider(providerId) 用该服务商的 zod 配置 schema 生成默认配置——也就是说,页面上看到的默认 Base URL 并非写死的界面文案,而是来自各服务商定义中的 schema 默认值。
第二步:填写 API Key 与 Base URL
在基础设置中填写 API Key。若服务商提供了专用的 API 地址,再在高级设置中填写 Base URL;否则保留默认值。常见默认值(来自各服务商文档页):
| 服务商 | 默认 Base URL | 备注 |
|---|---|---|
| OpenRouter | https://openrouter.ai/api/v1 |
保留默认即可 |
| OpenAI 官方 | https://api.openai.com/v1 |
兼容服务请填服务商文档的根地址,不要附加 /chat/completions 路径 |
| Ollama(本地) | http://localhost:11434/v1/ |
若 Ollama 运行在其他设备,填写该设备可访问的地址 |
在 服务商聊天设置页 的实现中,apiKey 与 baseUrl 分别绑定到该服务商的凭据对象;Base URL 输入框的占位符正是服务商元数据里的 defaultConfig.baseUrl,即“默认值从哪里来”在界面上有直观呈现。当 Base URL 缺失导致校验失败时,错误提示会自动附带 Default to <默认地址> 的提示(见 validateProviderConfig 中对 Base URL is required 的处理),方便直接补全。
第三步:Ping API 验证
点击 Ping API,测试网络是否连通以及 API Key 是否填写正确。对应的界面文案来自 英文语言包 中的 testGeneration: Ping API(中文界面为“Ping 测试”,失败时提示 Ping 测试失败)。
这一步值得结合源码理解,因为它与“自动校验”是两条不同的路径(见 use-provider-validation.ts):
- 自动校验(页面加载、凭据变化后防抖 500ms 触发):调用
validateProviderConfig(providerId, config, { skipChatPingCheck: true }),只验证配置项本身,不发起真实对话请求,注释明确说明这是为了避免后台校验意外消耗 API token; - 手动 Ping(点击按钮触发
runManualTest):调用validateProviderConfig(providerId, config, { onlyChatPingCheck: true }),即只保留包含CHAT_COMPLETIONS_VALIDATOR_ID的校验器与步骤,实际向聊天接口发起一次探测。
因此“Ping API”通过,意味着网络可达、Key 有效、接口协议匹配;而页面顶部的自动校验状态只反映配置完整性,两者通过与否的含义不同。此外,若自动校验无法判定(例如某些本地服务无法远程探测),页面上还提供“强制视为有效”(forceValid)的兜底操作,它会调用 store 的 forceProviderConfigured(providerId) 直接置为 configured 状态。
第四步:选择模型
网络通畅后,点击 选择模型;也可以打开 设置 → 意识,选择刚配置的聊天服务商和模型。
两个入口最终落到同一个状态:
- 服务商设置页的“选择模型”按钮执行
goToModelSelection():把activeProvider设为当前服务商,然后跳转到/settings/modules/consciousness(见 设置页源码); - 在 意识模块设置页 切换服务商时,
watch(activeProvider)会触发loadModelsForProvider(provider),由 provider store 的fetchModelsForProvider拉取并规范化模型目录(按id去重、补齐name、description、contextLength等字段)。
AIRI 会在服务商支持时加载模型列表。模型目录的获取在 listProviderModels 中按优先级回退:先尝试服务商自定义的 listModelCatalog / listModels 扩展方法;再尝试 xsAI 的 listModels;最后对仅有 baseUrl(可选 apiKey)的 OpenAI 兼容端点直接请求其模型列表。列表无法加载时,可根据服务商官方文档在“意识”页面手动输入精确的模型 ID——对应存储中的 activeCustomModelName(持久化键 settings/consciousness/active-custom-model,见 consciousness store)。
从源码结构看,还有一个容易踩坑的细节:切换 activeProvider 时会同步清空已选模型与自定义模型名(watch(activeProvider, ..., { flush: 'sync' })),原因是模型 ID 只在其来源服务商的目录中有效,沿用旧模型会在上游报 model_not_found(源码注释中引用了上游问题 #1761)。所以“先切服务商、再选模型”是唯一安全的顺序。
第五步:发送测试消息
返回聊天界面,发送一条简短消息,例如“你好”。收到回复即表示配置成功。
聊天界面能否发送,取决于 consciousness store 中的 chatReady 计算属性:必须同时存在 activeProvider 和 activeModel(特例是 prompt-api 服务商可以不带模型)。这也正是下一节“没有回复”排查项的底层依据——仅保存服务商凭据不会自动启用它。
排查
验证通过,但没有可选模型
先确认服务商允许列出模型。部分服务商不提供模型列表,或该 API Key 没有相应权限;这时在“意识”页面手动输入模型 ID 即可。模型 ID 必须与服务商文档完全一致。
从源码结构看,模型拉取失败时 store 会把 modelStatus 置为 error 并记录 modelError(见 fetchModelsForProvider 的 catch 分支),意识页会展示对应的加载错误信息;而“验证通过”只是 configured 状态,与模型目录是否可枚举相互独立,因此这两者不一致是正常现象,手动输入模型 ID 是官方支持的路径。
验证失败或请求超时
检查 API Key、Base URL、账户额度和网络连接。对于本地服务,确认服务正在运行,并且 Base URL 不是只允许其他设备访问的地址(典型错误是把 Base URL 写成 127.0.0.1,但 Ollama 实际运行在局域网另一台机器上)。
针对 OpenAI 兼容端点,手册 OpenAI 与兼容 API 额外提醒:仅凭 API 地址以 /v1 结尾或密钥以 sk- 开头,不能保证服务兼容,需确认其明确支持 OpenAI Chat Completions API,且 Base URL 是服务商文档指定的根地址。针对本地 Ollama,Ollama 文档页 指出:若 Ollama 正在运行但 AIRI 报网络或 CORS 错误,应按 Ollama 的启动方式设置 OLLAMA_ORIGINS 允许 AIRI 的来源后再重启服务,切勿将本地服务直接暴露到公网。
另外,对于连接类校验失败,错误提示会自动附带服务商定义中的 troubleshooting 文案(validateProviderConfig 在 openai-compatible:check-connectivity 步骤失败时追加),即界面里看到的排查提示本身就来自各服务商的静态定义,而非泛用文案。
AIRI 没有回复
确认“意识”页面同时选中了服务商和模型。仅保存服务商凭据不会自动启用它。
对应源码逻辑:availableProviders 只收录状态为 configured 的服务商,而聊天是否就绪由 chatReady 判定(需同时有 activeProvider 与 activeModel)。常见原因是完成第二步后没有执行第四步,或切换过服务商导致模型选择被自动清空——按上一节说明重新选择模型即可。
下一步
聊天功能正常后,可继续配置语音输入与输出,让 AIRI 说话并使用麦克风输入。配置入口同在 设置 → 服务商 下的语音/转写分类中,配置模式与本文的聊天服务商一致:填写凭据、Ping 验证、在对应模块页面选择生效实例。