AIRI 接入 Google Gemini 聊天模型：OpenAI 兼容端点配置、验证与排障实战-平芜编程栈

AIRI 接入 Google Gemini 聊天模型：OpenAI 兼容端点配置、验证与排障实战

【免费下载链接】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-sama's altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported.项目地址: https://gitcode.com/GitHub_Trending/ai/airi

本文面向希望在 AIRI 中使用 Google Gemini 系列模型作为"意识（Consciousness）"模块聊天大脑的用户，完整讲解 Gemini API Key 的创建、在设置 → 提供者 → 聊天 → Google Gemini中的配置步骤、AIRI 自动校验机制的工作方式，以及常见权限与模型可用性问题的排查方法。读完本文，你将能独立完成 Google Gemini 聊天提供者的接入、验证与模型切换，并理解其底层校验逻辑，方便自行排障。

为什么选择 Google Gemini 提供者

AIRI 将 Google Gemini 封装为一个标准的聊天服务提供者，其核心实现位于 google-generative-ai/index.ts。它并不直接调用 Gemini 的原生 SDK，而是通过Google Generative Language API 的 OpenAI 兼容端点（https://generativelanguage.googleapis.com/v1beta/openai/）接入，因此可以在 AIRI 统一的提供者体系中无缝工作。

适合选择该提供者的典型场景：

你已经持有 Gemini API Key，希望直接在 AIRI 中复用它；
你希望在 AIRI 的聊天链路中使用 Gemini 模型（该提供者的tasks声明为['chat']，专用于对话生成）；
你希望利用 AIRI 对 OpenAI 兼容生态的成熟校验、模型列表与参数透传能力。

从提供者注册入口 providers/index.ts 可以看到，Gemini 聊天提供者（google-generative-ai）与 Gemini 语音合成提供者（google-gemini-audio-speech，对应文档见 google-gemini-audio-speech/index.ts）被同时注册，前者服务于"意识/聊天"，后者服务于 TTS 语音输出，二者共用同一个 Google API Key 体系，但 Base URL 与任务类型不同。

第一步：创建 Gemini API Key

配置之前，需要先在 Google 侧准备好 API Key：

登录 Google AI Studio 的 API Keys 页面（aistudio.google.com/app/apikey），创建一个 Gemini API Key；
确认该 Key 所属的 Google Cloud 项目已启用 Gemini API，并且你要使用的目标模型在当前区域可用；
复制生成的 API Key，进入下一步。

API Key 安全提醒一旦 Key 泄露，请立即在 Google AI 开发者控制台中吊销并重新生成。不要将 Key 写入代码、截图或任何公开的配置文件。在 AIRI 设置界面中，API Key 字段以密码类型（type: 'password'）渲染，见 google-generative-ai/index.ts，输入时不会被明文展示。

第二步：在 AIRI 中配置 Google Gemini

按以下路径完成配置：

打开设置 → 提供者 → 聊天 → Google Gemini；
填入 API Key；
保持默认 Base URL：https://generativelanguage.googleapis.com/v1beta/openai/。

配置项的源码级说明

该提供者的配置结构由 Zod Schema 定义，见 google-generative-ai/index.ts：

const googleGenerativeConfigSchema = z.object({ apiKey: z.string('API Key'), baseUrl: z .string('Base URL') .optional() .default('https://generativelanguage.googleapis.com/v1beta/openai/'), })

apiKey：必填。用于调用 Google Generative Language API 的身份凭证；
baseUrl：可选，默认值为 OpenAI 兼容端点https://generativelanguage.googleapis.com/v1beta/openai/。该地址带尾部/openai/，对应 Google 为 OpenAI 生态提供的适配层，与原生端点/v1beta/不同——如果不小心填错为原生端点，连接性校验会失败。

从实现上还可以读出两个重要行为（google-generative-ai/index.ts）：

推理（reasoning）能力映射：该提供者声明chat.reasoning.modes = ['enabled', 'disabled']，当你在"意识"模块开启 Thinking（思考）时，请求会携带reasoningEffort: 'medium'；关闭时则为'none'。也就是说，Gemini 的思考强度在 AIRI 中只有开/关两档，开启即对应中等推理预算；
校验触发条件：validationRequiredWhen仅在 API Key 非空（去除首尾空格后）时才要求校验，未填 Key 时不会触发多余的网络请求。

第三步：验证配置

配置完成后，AIRI 会在你编辑配置的过程中自动执行有效性校验。界面上的两个关键入口是：

配置有效性校验（Validate configuration）：编辑配置时自动运行。若出现Ping API按钮，可直接点击发起一次真实请求测试，用于确认连通性与鉴权是否正常；
选择模型 →（Select Model →）：校验通过后，点击此按钮会跳转到设置 → 模块 → 意识（Consciousness），在此处选择提供者与具体模型，并完成"意识"模型的绑定。

校验机制内部原理

Google Gemini 提供者复用了 AIRI 通用的 OpenAI 兼容校验器，见 openai-compatible.ts，并显式声明了三种检查项（google-generative-ai/index.ts）：

validators: { ...createOpenAICompatibleValidators({ checks: [ProviderValidationCheck.Connectivity, ProviderValidationCheck.ModelList, ProviderValidationCheck.ChatCompletions], }), },

对应底层的三段校验逻辑（均在 openai-compatible.ts 中实现）：

配置格式检查（check-config）：校验 API Key 非空、Base URL 非空，且 Base URL 必须是合法的绝对 URL（存在主机名），否则会给出 "Base URL is invalid. It must be an absolute URL." 之类的明确错误（L213-L244）；
连通性检查（check-connectivity）：向${baseUrl}/models发起GET请求，携带Authorization: Bearer <apiKey>头，并设置10 秒超时（AbortController），HTTP 5xx 会视为失败（L246-L295）；
模型列表检查（check-model-list）：调用模型列表接口，若返回的模型数组为空则报 "no models found"（L324-L353）；
聊天请求检查（check-chat-completions）：用挑选出的校验模型向端点发送一条ping用户消息，max_tokens固定为 16。这里有一个兼容性细节：对部分 OpenAI 兼容服务，低于 16 的输出长度上限会被拒绝，因此代码统一使用 16 作为探针参数；同时把 HTTP 400 视为"连通但该模型不支持探针"的容错情形（L117-L165）。

另外，校验结果会按校验会话做缓存 + 互斥锁（Mutex）去重，避免同一校验周期内对聊天接口发起重复请求（L167-L206）。这意味着"Ping API / 自动校验"是轻量且幂等的，可以放心反复点击。

第四步：在"意识"模块中绑定 Gemini 模型

校验通过后，进入设置 → 模块 → 意识。该模块的界面文案定义在 i18n 的 settings.yaml（韩文文案见 ko/settings.yaml），关键交互包括：

提供者-模型选择（provider-model-selection）：从已配置的提供者中选择 LLM，作为该角色"意识"的默认模型；
模型搜索与加载：若提供者支持模型列表，会自动拉取并支持关键词搜索（"Search models..."），未配置提供者时会提示 "No Providers Configured / Click here to set up your LLM providers"；
手动模型名：当提供者不支持模型列表时，可手动输入模型名（"Model Name" / "Enter the model name to use with this provider"）；
模型选项（model-options）：即上文提到的 Thinking 开关，对应reasoningEffort的 enabled/disabled 映射；
健康检查（health check）：选中模型前会对提供者做一次状态探测，失败会给出 Health check failed 提示。

建议绑定模型时直接使用 AIRI 从提供者返回的模型名，而不是手工改写 Google AI Studio 页面显示的名称——两端命名可能不一致，改写容易造成"模型不可用"的假象。

问题排查

AIRI 的提供者校验会依次检查连接状态、模型列表和聊天请求，因此错误信息通常能直接定位到问题层级。常见排查方向：

现象	排查方向
权限错误 / 401	确认 API Key 所属的 Google Cloud 项目已启用 Gemini API，且 Key 未过期、未吊销
模型不可用（Model not found）	确认目标模型在 Key 所属项目的区域内可用；部分模型仅在特定区域开放
校验失败：Base URL 无效	确认 Base URL 以`/openai/`结尾的绝对 URL 形式填写，且未误填原生`/v1beta/`端点
提示无可用模型	项目未启用 Gemini API 时模型列表会为空，先回控制台启用
聊天请求被拒	检查网络代理是否拦截对`generativelanguage.googleapis.com`的请求；校验探针要求请求体带`max_tokens`等 OpenAI 兼容参数