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-samas 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 URLhttps://generativelanguage.googleapis.com/v1beta/openai/。配置项的源码级说明该提供者的配置结构由 Zod Schema 定义见 google-generative-ai/index.tsconst 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.tsvalidators: { ...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 秒超时AbortControllerHTTP 5xx 会视为失败L246-L295模型列表检查check-model-list调用模型列表接口若返回的模型数组为空则报 no models foundL324-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 兼容参数最后一条原则尽量使用 AIRI 校验返回 / 模型列表中出现的模型名称不要凭 Google AI Studio 页面印象手工改写这能规避绝大多数名称对不上导致的不可用问题。相关仓库资源提供者定义packages/stage-ui/src/libs/providers/providers/google-generative-ai/index.ts提供者注册表packages/stage-ui/src/libs/providers/providers/index.tsOpenAI 兼容校验器实现packages/stage-ui/src/libs/providers/validators/openai-compatible.ts意识模块界面文案packages/i18n/src/locales/en/settings.yaml本指南的原始文档韩文docs/content/ko/docs/manual/config/providers/consciousness/google-gemini.md【免费下载链接】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），仅供参考