AIRI 聊天模型Chat Model接入指南从 Provider 配置到 Consciousness 模块启用【免费下载链接】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聊天模型Chat Model是 AIRI 的“大脑”决定了它能否理解你的话并生成文字回复。本篇指南基于 AIRI 官方手册的 llm.md 整理系统讲解云端与本地两种模型的完整接入路径从在Settings → Providers → Chat填入凭据、通过自动校验到在Settings → Modules → Consciousness选中 Provider 与模型最后用一条测试消息确认端到端可用。读完本文你将掌握 AIRI 模型接入的完整操作流程、常见字段含义、验证机制的底层原理以及三类高频故障的排查方法。聊天模型在 AIRI 中的角色要生成文字回复AIRI 必须能访问一个“会说话”的模型。它有两种选择云端 Provider你拥有一个带聊天模型访问权限的账号并提供 API Key。本地模型服务设备上运行着 Ollama 等本地模型服务无需云端账号。无论哪种方式配置本质上都分为两步先在Providers中登记“服务商”再在Modules → Consciousness中告诉 AIRI“用哪个服务商、哪个模型来思考”。这两步缺一不可——保存了 Provider 凭据并不会自动启用该 Provider这正是新手最容易踩的坑。前置条件开始配置前请确认以下三点AIRI 已安装并正在运行。使用云端 Provider 时已创建 API Key并确认账号可以使用所选聊天模型。使用本地 Provider 时本地模型服务已运行且从运行 AIRI 的设备可以访问到该服务。配置流程总览完整的配置链路如下打开Settings → Providers → Chat选择要使用的 Provider。填入 API Key除非 Provider 文档明确要求其他地址否则保持默认 Base URL 不变。查看 Provider 页面上的自动校验结果。Provider 字段在编辑时即自动保存校验方式因 Provider 而异可能只检查字段是否填写、会拉取模型列表或提供Ping API按钮做一次小流量在线请求。打开Settings → Modules → Consciousness选择刚才配置好的 Provider 和模型。回到聊天界面发送一条短消息如 “Hello”。收到回复即说明 Provider 和模型已正常工作。最小可用配置来自配置指南手册的 Provider 配置指南 给出了更精简的最小步骤适合先打通链路、验证基础环境打开Settings → Providers。在Chat分类中选择一个 Provider填写凭据并完成可用校验。打开Settings → Modules → Consciousness选择刚配置的 Provider 和模型。发送一条消息确认 AIRI 能回复。提示如果你想先验证基础配置请优先配置 Chat。之后再添加 TTS语音输出与 ASR语音输入这样可以把语音相关的问题隔离出来便于排查。第一步在 Providers → Chat 配置服务商如何选择 Provider如果不确定选哪个手册建议从以下四个入手完整说明见对应页面场景推荐 Provider文档想用一个 Key 访问多家模型厂商OpenRouteropenrouter.md想直接使用 DeepSeek 模型或已有其 KeyDeepSeekdeepseek.md使用 OpenAI 官方接口或兼容接口OpenAI / OpenAI Compatibleopenai.md本地运行模型、不依赖云 APIOllamaollama.md其他聊天 Provider如 302.AI、Azure OpenAI、Google Gemini、Anthropic、Groq、xAI 等均列在Providers → Chat下完整清单可查看 consciousness 目录。AIRI 的 Provider 注册表位于 packages/stage-ui/src/stores/providers/provider.ts设置页会按注册表顺序渲染所有 Provider。常见字段含义根据 common.mdProvider 表单中的常见字段含义与填写建议如下字段含义填写建议API KeyProvider 签发的访问令牌粘贴完整 Key不要添加引号或空格。Base URLProvider API 的根地址仅在 Provider 文档要求时修改必须包含完整的https://或http://。Model聊天/语音/识别所用的模型 ID优先从 AIRI 的模型列表中选择若列表加载失败且字段支持自定义输入填入 Provider 文档中的精确 ID。Voice语音合成所用的音色 ID先选模型再选择该模型支持的音色。Region部分云服务的部署区域与 Provider 控制台中显示的项目/资源区域保持一致。注意凭据与 Provider 设置保存在当前设备的本地设置中。切勿在截图、日志、Issue 或聊天消息中泄露 API Key 等凭据。四个推荐 Provider 的默认 Base URLProvider默认 Base URL关键注意事项OpenRouterhttps://openrouter.ai/api/v1/一个 Key 一张账单即可切换多家模型无需逐个配置上游 Provider可用性取决于区域、网络、支付方式与厂商策略。DeepSeekhttps://api.deepseek.com/提供兼容 OpenAI 格式的 Chat API。OpenAI / Compatiblehttps://api.openai.com/v1官方兼容服务请填写文档给出的 API 根地址不要拼接/chat/completions路径仅地址以/v1结尾或 Key 以sk-开头并不能保证接口兼容。Ollama本地http://localhost:11434/v1/默认无需 API KeyOllama 在其他设备时填写 AIRI 设备可达的地址。云端 Provider 的 Key 获取与安全以 OpenRouter 为例其 专属页面 给出的 Key 获取流程是打开 OpenRouter API Keys 页面 → 创建新 Key → 设置合适的名称、有效期与配额 → 复制并妥善保存。DeepSeek、302.AI 等 Provider 的流程类似均在各自控制台的 API Keys 页面创建。所有 Provider 页都包含同一条安全警告不要将 API Key 提交到代码仓库、放进截图或分享给任何人一旦 Key 泄露立即在控制台吊销并重新创建。本地 ProviderOllama 的安装与模型下载如果选择本地方案手册的 Ollama 指南 给出了完整命令# 验证 Ollama 是否安装成功 ollama --version # 下载并启动一个模型以 qwen2 为例 ollama run qwen2要换模型把qwen2替换为目标模型 ID 即可首次下载耗时取决于模型大小与网速。然后在Settings → Providers → Chat → Ollama保持默认 Base URL进入Settings → Modules → Consciousness选择 Ollama 和已下载的模型。Ollama 的 CORS 陷阱如果 Ollama 正在运行但 AIRI 报 CORS 错误需要把 AIRI 的确切源地址加入OLLAMA_ORIGINS环境变量并重启 Ollama。不要用通配符也不要为了图省事把 Ollama 暴露到公网。若 AIRI 与 Ollama 不在同一设备应使用 AIRI 设备可达的局域网地址并且只在可信网络内开放服务。配置验证机制自动校验与 Ping API验证到底做了什么AIRI 的校验由 provider.ts 中的validateProviderConfig驱动它根据 Provider 定义生成一份验证计划ProviderValidationPlan逐项检查配置字段configValidators与连通性providerValidators。校验结果分为三种粒度仅检查字段校验必填项是否齐全如 Base URL 必填。拉取模型列表向 Provider 请求可用的模型目录。Ping API 在线探测发送一次真实的小请求验证连通性可能消耗少量额度。在源码中真正的在线 Ping 对应CHAT_COMPLETIONS_VALIDATOR_ID标识的校验器。值得注意的实现细节是后台/自动校验默认会跳过 Ping 探测skipChatPingCheck: true因为这类请求会消耗 API 额度只有用户主动点击Ping API按钮等明确意图才会触发在线探测。此外校验结果会以配置内容的哈希值validatedCredentialHash做缓存——配置未变化时不会重复发起校验请求。校验失败时的排查顺序根据 common.md当验证失败时按以下顺序排查确认账号有服务访问权限且存在可用额度或配额。重新复制 API Key确认没有混入首尾空格或换行。恢复默认 Base URL或与 Provider 官方文档逐字符核对。确认网络、代理与防火墙允许访问该 Provider。选择 Provider 明确支持的模型不要用显示名称当作模型 ID。第二步在 Modules → Consciousness 选择 Provider 与模型当 Provider 支持时AIRI 会自动加载模型列表。如果列表无法加载且字段支持自定义输入则需在Consciousness页面手动填入 Provider 官方文档中的精确模型 ID——ID 必须与 Provider 文档完全一致不能使用显示名称。从源码看模型列表的加载由 listProviderModels 完成其优先级为若 Provider 定义了extraMethods.listModels直接调用其自定义拉取逻辑否则若 Provider 实例实现了模型枚举接口isModelProvider调用标准listModels兜底方案是用配置中的baseURL直接请求 Provider 的/models端点。拉取到的结果会经过normalizeProviderModels归一化提取id、name、contextLength、deprecated等字段并缓存到运行时状态状态标记为idle / loading / ready / error四态。凭据发生变化时refreshModelsForChangedCredentials 会先释放缓存的 Provider 实例再重新拉取模型列表——所以修改 API Key 后无需手动清缓存模型列表会自动刷新。第三步发送消息验证端到端可用配置完成后回到聊天界面发送一条简短消息如 “Hello”。收到回复即表明 Provider 与模型链路已打通。若你已用 OpenRouter / DeepSeek 等 Provider 完成配置其页面上通常还有Select Model →快捷按钮校验成功后点击它可直接跳转到Settings → Modules → Consciousness选择可用模型。故障排查手册场景一校验通过但没有可用模型先确认该 Provider 是否支持列出模型。部分 Provider 不返回模型列表或 API Key 缺少相应权限。这种情况下请在Settings → Modules → Consciousness手动输入模型 ID且必须与 Provider 文档完全一致。场景二验证失败或请求超时依次检查API Key重新复制排除首尾空格。Base URL恢复默认或与官方文档核对。账号配额余额或额度是否充足。网络连接代理、防火墙是否拦截。本地服务对于本地模型服务确认其正在运行且 AIRI 能访问配置的地址如 Ollama 的localhost:11434注意 CORS 配置。场景三AIRI 不回复确认Settings → Modules → Consciousness中已同时选中 Provider 和模型。再次强调保存 Provider 凭据不会自动启用该 Provider——注册与启用是两个独立步骤必须在 Consciousness 模块中显式选择。下一步让 AIRI “说”起来聊天打通后可继续阅读 配置语音输入与输出为 AIRI 增加 TTS 语音输出或麦克风语音输入ASR/STT。语音功能是可选项可独立配置在Modules → Speech启用语音输出、在Modules → Hearing启用语音识别。此外手册还提供了 视觉理解配置 与 联网搜索配置可按需扩展 AIRI 的能力边界。【免费下载链接】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），仅供参考 
长河君 · 2026/9/10 15:36:30 · 阅读 1.2k AIRI 聊天模型（Chat Model）接入指南：从 Provider 配置到 Consciousness 模块启用
AIRI 聊天模型Chat Model接入指南从 Provider 配置到 Consciousness 模块启用【免费下载链接】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聊天模型Chat Model是 AIRI 的“大脑”决定了它能否理解你的话并生成文字回复。本篇指南基于 AIRI 官方手册的 llm.md 整理系统讲解云端与本地两种模型的完整接入路径从在Settings → Providers → Chat填入凭据、通过自动校验到在Settings → Modules → Consciousness选中 Provider 与模型最后用一条测试消息确认端到端可用。读完本文你将掌握 AIRI 模型接入的完整操作流程、常见字段含义、验证机制的底层原理以及三类高频故障的排查方法。聊天模型在 AIRI 中的角色要生成文字回复AIRI 必须能访问一个“会说话”的模型。它有两种选择云端 Provider你拥有一个带聊天模型访问权限的账号并提供 API Key。本地模型服务设备上运行着 Ollama 等本地模型服务无需云端账号。无论哪种方式配置本质上都分为两步先在Providers中登记“服务商”再在Modules → Consciousness中告诉 AIRI“用哪个服务商、哪个模型来思考”。这两步缺一不可——保存了 Provider 凭据并不会自动启用该 Provider这正是新手最容易踩的坑。前置条件开始配置前请确认以下三点AIRI 已安装并正在运行。使用云端 Provider 时已创建 API Key并确认账号可以使用所选聊天模型。使用本地 Provider 时本地模型服务已运行且从运行 AIRI 的设备可以访问到该服务。配置流程总览完整的配置链路如下打开Settings → Providers → Chat选择要使用的 Provider。填入 API Key除非 Provider 文档明确要求其他地址否则保持默认 Base URL 不变。查看 Provider 页面上的自动校验结果。Provider 字段在编辑时即自动保存校验方式因 Provider 而异可能只检查字段是否填写、会拉取模型列表或提供Ping API按钮做一次小流量在线请求。打开Settings → Modules → Consciousness选择刚才配置好的 Provider 和模型。回到聊天界面发送一条短消息如 “Hello”。收到回复即说明 Provider 和模型已正常工作。最小可用配置来自配置指南手册的 Provider 配置指南 给出了更精简的最小步骤适合先打通链路、验证基础环境打开Settings → Providers。在Chat分类中选择一个 Provider填写凭据并完成可用校验。打开Settings → Modules → Consciousness选择刚配置的 Provider 和模型。发送一条消息确认 AIRI 能回复。提示如果你想先验证基础配置请优先配置 Chat。之后再添加 TTS语音输出与 ASR语音输入这样可以把语音相关的问题隔离出来便于排查。第一步在 Providers → Chat 配置服务商如何选择 Provider如果不确定选哪个手册建议从以下四个入手完整说明见对应页面场景推荐 Provider文档想用一个 Key 访问多家模型厂商OpenRouteropenrouter.md想直接使用 DeepSeek 模型或已有其 KeyDeepSeekdeepseek.md使用 OpenAI 官方接口或兼容接口OpenAI / OpenAI Compatibleopenai.md本地运行模型、不依赖云 APIOllamaollama.md其他聊天 Provider如 302.AI、Azure OpenAI、Google Gemini、Anthropic、Groq、xAI 等均列在Providers → Chat下完整清单可查看 consciousness 目录。AIRI 的 Provider 注册表位于 packages/stage-ui/src/stores/providers/provider.ts设置页会按注册表顺序渲染所有 Provider。常见字段含义根据 common.mdProvider 表单中的常见字段含义与填写建议如下字段含义填写建议API KeyProvider 签发的访问令牌粘贴完整 Key不要添加引号或空格。Base URLProvider API 的根地址仅在 Provider 文档要求时修改必须包含完整的https://或http://。Model聊天/语音/识别所用的模型 ID优先从 AIRI 的模型列表中选择若列表加载失败且字段支持自定义输入填入 Provider 文档中的精确 ID。Voice语音合成所用的音色 ID先选模型再选择该模型支持的音色。Region部分云服务的部署区域与 Provider 控制台中显示的项目/资源区域保持一致。注意凭据与 Provider 设置保存在当前设备的本地设置中。切勿在截图、日志、Issue 或聊天消息中泄露 API Key 等凭据。四个推荐 Provider 的默认 Base URLProvider默认 Base URL关键注意事项OpenRouterhttps://openrouter.ai/api/v1/一个 Key 一张账单即可切换多家模型无需逐个配置上游 Provider可用性取决于区域、网络、支付方式与厂商策略。DeepSeekhttps://api.deepseek.com/提供兼容 OpenAI 格式的 Chat API。OpenAI / Compatiblehttps://api.openai.com/v1官方兼容服务请填写文档给出的 API 根地址不要拼接/chat/completions路径仅地址以/v1结尾或 Key 以sk-开头并不能保证接口兼容。Ollama本地http://localhost:11434/v1/默认无需 API KeyOllama 在其他设备时填写 AIRI 设备可达的地址。云端 Provider 的 Key 获取与安全以 OpenRouter 为例其 专属页面 给出的 Key 获取流程是打开 OpenRouter API Keys 页面 → 创建新 Key → 设置合适的名称、有效期与配额 → 复制并妥善保存。DeepSeek、302.AI 等 Provider 的流程类似均在各自控制台的 API Keys 页面创建。所有 Provider 页都包含同一条安全警告不要将 API Key 提交到代码仓库、放进截图或分享给任何人一旦 Key 泄露立即在控制台吊销并重新创建。本地 ProviderOllama 的安装与模型下载如果选择本地方案手册的 Ollama 指南 给出了完整命令# 验证 Ollama 是否安装成功 ollama --version # 下载并启动一个模型以 qwen2 为例 ollama run qwen2要换模型把qwen2替换为目标模型 ID 即可首次下载耗时取决于模型大小与网速。然后在Settings → Providers → Chat → Ollama保持默认 Base URL进入Settings → Modules → Consciousness选择 Ollama 和已下载的模型。Ollama 的 CORS 陷阱如果 Ollama 正在运行但 AIRI 报 CORS 错误需要把 AIRI 的确切源地址加入OLLAMA_ORIGINS环境变量并重启 Ollama。不要用通配符也不要为了图省事把 Ollama 暴露到公网。若 AIRI 与 Ollama 不在同一设备应使用 AIRI 设备可达的局域网地址并且只在可信网络内开放服务。配置验证机制自动校验与 Ping API验证到底做了什么AIRI 的校验由 provider.ts 中的validateProviderConfig驱动它根据 Provider 定义生成一份验证计划ProviderValidationPlan逐项检查配置字段configValidators与连通性providerValidators。校验结果分为三种粒度仅检查字段校验必填项是否齐全如 Base URL 必填。拉取模型列表向 Provider 请求可用的模型目录。Ping API 在线探测发送一次真实的小请求验证连通性可能消耗少量额度。在源码中真正的在线 Ping 对应CHAT_COMPLETIONS_VALIDATOR_ID标识的校验器。值得注意的实现细节是后台/自动校验默认会跳过 Ping 探测skipChatPingCheck: true因为这类请求会消耗 API 额度只有用户主动点击Ping API按钮等明确意图才会触发在线探测。此外校验结果会以配置内容的哈希值validatedCredentialHash做缓存——配置未变化时不会重复发起校验请求。校验失败时的排查顺序根据 common.md当验证失败时按以下顺序排查确认账号有服务访问权限且存在可用额度或配额。重新复制 API Key确认没有混入首尾空格或换行。恢复默认 Base URL或与 Provider 官方文档逐字符核对。确认网络、代理与防火墙允许访问该 Provider。选择 Provider 明确支持的模型不要用显示名称当作模型 ID。第二步在 Modules → Consciousness 选择 Provider 与模型当 Provider 支持时AIRI 会自动加载模型列表。如果列表无法加载且字段支持自定义输入则需在Consciousness页面手动填入 Provider 官方文档中的精确模型 ID——ID 必须与 Provider 文档完全一致不能使用显示名称。从源码看模型列表的加载由 listProviderModels 完成其优先级为若 Provider 定义了extraMethods.listModels直接调用其自定义拉取逻辑否则若 Provider 实例实现了模型枚举接口isModelProvider调用标准listModels兜底方案是用配置中的baseURL直接请求 Provider 的/models端点。拉取到的结果会经过normalizeProviderModels归一化提取id、name、contextLength、deprecated等字段并缓存到运行时状态状态标记为idle / loading / ready / error四态。凭据发生变化时refreshModelsForChangedCredentials 会先释放缓存的 Provider 实例再重新拉取模型列表——所以修改 API Key 后无需手动清缓存模型列表会自动刷新。第三步发送消息验证端到端可用配置完成后回到聊天界面发送一条简短消息如 “Hello”。收到回复即表明 Provider 与模型链路已打通。若你已用 OpenRouter / DeepSeek 等 Provider 完成配置其页面上通常还有Select Model →快捷按钮校验成功后点击它可直接跳转到Settings → Modules → Consciousness选择可用模型。故障排查手册场景一校验通过但没有可用模型先确认该 Provider 是否支持列出模型。部分 Provider 不返回模型列表或 API Key 缺少相应权限。这种情况下请在Settings → Modules → Consciousness手动输入模型 ID且必须与 Provider 文档完全一致。场景二验证失败或请求超时依次检查API Key重新复制排除首尾空格。Base URL恢复默认或与官方文档核对。账号配额余额或额度是否充足。网络连接代理、防火墙是否拦截。本地服务对于本地模型服务确认其正在运行且 AIRI 能访问配置的地址如 Ollama 的localhost:11434注意 CORS 配置。场景三AIRI 不回复确认Settings → Modules → Consciousness中已同时选中 Provider 和模型。再次强调保存 Provider 凭据不会自动启用该 Provider——注册与启用是两个独立步骤必须在 Consciousness 模块中显式选择。下一步让 AIRI “说”起来聊天打通后可继续阅读 配置语音输入与输出为 AIRI 增加 TTS 语音输出或麦克风语音输入ASR/STT。语音功能是可选项可独立配置在Modules → Speech启用语音输出、在Modules → Hearing启用语音识别。此外手册还提供了 视觉理解配置 与 联网搜索配置可按需扩展 AIRI 的能力边界。【免费下载链接】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），仅供参考