forked from Zakaria/hermes-agent
Hermes-agent
This commit is contained in:
Zakaria
@@ -0,0 +1,280 @@
|
||||
---
|
||||
sidebar_position: 16
|
||||
title: "Google Gemini"
|
||||
description: "将 Hermes Agent 与 Google Gemini 配合使用——原生 AI Studio API、API 密钥配置、OAuth 选项、工具调用、流式传输及配额说明"
|
||||
---
|
||||
|
||||
# Google Gemini
|
||||
|
||||
Hermes Agent 通过 **Google AI Studio / Gemini API** 原生支持 Google Gemini——而非 OpenAI 兼容端点。这使 Hermes 能够将其内部 OpenAI 格式的消息和工具循环转换为 Gemini 原生的 `generateContent` API，同时保留工具调用、流式传输、多模态输入以及 Gemini 特有的响应元数据。
|
||||
|
||||
Hermes 还支持独立的 **Google Gemini（OAuth）** provider，使用与 Google Gemini CLI 相同的 Cloud Code Assist 后端。如需最低风险的官方 API 路径，请使用 API 密钥 provider（`gemini`）。
|
||||
|
||||
## 前提条件
|
||||
|
||||
- **Google AI Studio API 密钥** — 在 [aistudio.google.com/apikey](https://aistudio.google.com/apikey) 创建
|
||||
- **已启用计费的 Google Cloud 项目** — 推荐用于 Agent 场景。Gemini 免费层级对长时间运行的 Agent 会话而言配额过小，因为 Hermes 每次用户交互可能发起多次模型调用。
|
||||
- **已安装 Hermes** — 原生 Gemini provider 无需额外安装 Python 包。
|
||||
|
||||
:::tip API 密钥路径
|
||||
设置 `GOOGLE_API_KEY` 或 `GEMINI_API_KEY`。Hermes 对 `gemini` provider 会同时检查这两个名称。
|
||||
:::
|
||||
|
||||
## 快速开始
|
||||
|
||||
```bash
|
||||
# 添加 Gemini API 密钥
|
||||
echo "GOOGLE_API_KEY=..." >> ~/.hermes/.env
|
||||
|
||||
# 选择 Gemini 作为 provider
|
||||
hermes model
|
||||
# → 选择 "More providers..." → "Google AI Studio"
|
||||
# → Hermes 检查密钥层级并显示 Gemini 模型列表
|
||||
# → 选择一个模型
|
||||
|
||||
# 开始对话
|
||||
hermes chat
|
||||
```
|
||||
|
||||
如果你偏好直接编辑配置文件，请使用原生 Gemini API 基础 URL：
|
||||
|
||||
```yaml
|
||||
model:
|
||||
default: gemini-3-flash-preview
|
||||
provider: gemini
|
||||
base_url: https://generativelanguage.googleapis.com/v1beta
|
||||
```
|
||||
|
||||
## 配置
|
||||
|
||||
运行 `hermes model` 后，`~/.hermes/config.yaml` 将包含：
|
||||
|
||||
```yaml
|
||||
model:
|
||||
default: gemini-3-flash-preview
|
||||
provider: gemini
|
||||
base_url: https://generativelanguage.googleapis.com/v1beta
|
||||
```
|
||||
|
||||
`~/.hermes/.env` 中：
|
||||
|
||||
```bash
|
||||
GOOGLE_API_KEY=...
|
||||
```
|
||||
|
||||
### 原生 Gemini API
|
||||
|
||||
推荐使用的端点为：
|
||||
|
||||
```text
|
||||
https://generativelanguage.googleapis.com/v1beta
|
||||
```
|
||||
|
||||
Hermes 检测到该端点后会创建原生 Gemini 适配器。在内部，Hermes 仍以 OpenAI 格式维护 Agent 循环，然后将每个请求转换为 Gemini 原生 schema：
|
||||
|
||||
- `messages[]` → Gemini `contents[]`
|
||||
- 系统提示（system prompt）→ Gemini `systemInstruction`
|
||||
- 工具 schema → Gemini `functionDeclarations`
|
||||
- 工具结果 → Gemini `functionResponse` 部分
|
||||
- 流式响应 → 供 Hermes 循环使用的 OpenAI 格式流式数据块
|
||||
|
||||
:::note Gemini 3 思维签名
|
||||
对于 Gemini 3 的工具调用，Hermes 会保留附加在函数调用部分的 `thoughtSignature` 值，并在下一个工具轮次中重放。这覆盖了多步骤 Agent 工作流中验证关键路径的需求。
|
||||
|
||||
Gemini 3 也可能在其他响应部分附加思维签名。Hermes 的原生适配器目前针对 Agent 工具循环进行了优化，尚未以完整的部分级保真度重放所有非工具调用签名。
|
||||
:::
|
||||
|
||||
### 优先使用原生端点
|
||||
|
||||
Google 还提供了 OpenAI 兼容端点：
|
||||
|
||||
```text
|
||||
https://generativelanguage.googleapis.com/v1beta/openai/
|
||||
```
|
||||
|
||||
对于 Hermes Agent 会话，请优先使用上述原生 Gemini 端点。Hermes 内置原生 Gemini 适配器，可将多轮工具调用、工具调用结果、流式传输、多模态输入以及 Gemini 响应元数据直接映射到 Gemini 的 `generateContent` API。OpenAI 兼容端点在你明确需要 OpenAI API 兼容性时仍然有用。
|
||||
|
||||
如果你之前将 `GEMINI_BASE_URL` 设置为 `/openai` URL，请将其删除或修改：
|
||||
|
||||
```bash
|
||||
GEMINI_BASE_URL=https://generativelanguage.googleapis.com/v1beta
|
||||
```
|
||||
|
||||
### OAuth Provider
|
||||
|
||||
Hermes 还提供 `google-gemini-cli` provider：
|
||||
|
||||
```bash
|
||||
hermes model
|
||||
# → 选择 "Google Gemini (OAuth)"
|
||||
```
|
||||
|
||||
该方式使用浏览器 PKCE 登录和 Cloud Code Assist 后端。对于希望使用 Gemini CLI 风格 OAuth 的用户可能有用，但 Hermes 会显示明确警告，因为 Google 可能将第三方软件使用 Gemini CLI OAuth 客户端的行为视为违反政策。对于生产环境或最低风险使用场景，请优先使用上述 API 密钥 provider。
|
||||
|
||||
## 可用模型
|
||||
|
||||
`hermes model` 选择器显示 Hermes provider 注册表中维护的 Gemini 模型。常见选项包括：
|
||||
|
||||
| 模型 | ID | 说明 |
|
||||
|------|----|------|
|
||||
| Gemini 3.1 Pro Preview | `gemini-3.1-pro-preview` | 可用时最强大的预览模型 |
|
||||
| Gemini 3 Pro Preview | `gemini-3-pro-preview` | 强大的推理和编码模型 |
|
||||
| Gemini 3 Flash Preview | `gemini-3-flash-preview` | 推荐的默认选项，速度与能力均衡 |
|
||||
| Gemini 3.1 Flash Lite Preview | `gemini-3.1-flash-lite-preview` | 可用时速度最快、成本最低的选项 |
|
||||
|
||||
模型可用性会随时间变化。如果某个模型消失或未对你的密钥启用，请重新运行 `hermes model` 并从当前列表中选择。
|
||||
|
||||
:::info 模型 ID
|
||||
当 `provider: gemini` 时，请使用 Gemini 原生模型 ID，如 `gemini-3-flash-preview`，而非 OpenRouter 风格的 ID（如 `google/gemini-3-flash-preview`）。
|
||||
:::
|
||||
|
||||
### 最新别名
|
||||
|
||||
Google 为 Pro 和 Flash Gemini 系列发布了滚动别名。当你希望 Google 自动升级模型而无需修改 Hermes 配置时，`gemini-pro-latest` 和 `gemini-flash-latest` 非常实用。
|
||||
|
||||
| 别名 | 当前指向 | 说明 |
|
||||
|------|----------|------|
|
||||
| `gemini-pro-latest` | 最新 Gemini Pro 模型 | 需要 Google 当前 Pro 默认值时的最佳选择 |
|
||||
| `gemini-flash-latest` | 最新 Gemini Flash 模型 | 需要 Google 当前 Flash 默认值时的最佳选择 |
|
||||
|
||||
```yaml
|
||||
model:
|
||||
default: gemini-pro-latest
|
||||
provider: gemini
|
||||
base_url: https://generativelanguage.googleapis.com/v1beta
|
||||
```
|
||||
|
||||
如果需要严格的可复现性，请优先使用明确的模型 ID，如 `gemini-3.1-pro-preview` 或 `gemini-3-flash-preview`。
|
||||
|
||||
### 通过 Gemini API 使用 Gemma
|
||||
|
||||
Google 也通过 Gemini API 提供 Gemma 模型。Hermes 将这些模型识别为 Google 模型，但会在默认模型选择器中隐藏吞吐量极低的 Gemma 条目，以防新用户在长时间运行的 Agent 会话中意外选择评估层级的模型。
|
||||
|
||||
常用评估 ID 包括：
|
||||
|
||||
| 模型 | ID | 说明 |
|
||||
|------|----|------|
|
||||
| Gemma 4 31B IT | `gemma-4-31b-it` | 较大的 Gemma 模型；适用于兼容性和质量评估 |
|
||||
| Gemma 4 26B A4B IT | `gemma-4-26b-a4b-it` | 可用时的较小活跃参数变体 |
|
||||
|
||||
这些模型最适合作为 Gemini API 密钥的评估选项。Google 的 Gemma API 定价仅限免费层级，与生产级 Gemini 模型相比使用上限较低，因此持续的 Hermes Agent 使用通常应切换到付费 Gemini 模型、自托管部署或具有适当配额的其他 provider。
|
||||
|
||||
如需使用选择器中隐藏的 Gemma 模型，请直接在配置中指定：
|
||||
|
||||
```yaml
|
||||
model:
|
||||
default: gemma-4-31b-it
|
||||
provider: gemini
|
||||
base_url: https://generativelanguage.googleapis.com/v1beta
|
||||
```
|
||||
|
||||
## 会话中途切换模型
|
||||
|
||||
在对话中使用 `/model` 命令：
|
||||
|
||||
```text
|
||||
/model gemini-3-flash-preview
|
||||
/model gemini-flash-latest
|
||||
/model gemini-3-pro-preview
|
||||
/model gemini-pro-latest
|
||||
/model gemma-4-31b-it
|
||||
/model gemini-3.1-flash-lite-preview
|
||||
```
|
||||
|
||||
如果尚未配置 Gemini，请退出会话并先运行 `hermes model`。`/model` 用于在已配置的 provider 和模型之间切换，不会收集新的 API 密钥。
|
||||
|
||||
## 诊断
|
||||
|
||||
```bash
|
||||
hermes doctor
|
||||
```
|
||||
|
||||
doctor 命令检查：
|
||||
|
||||
- `GOOGLE_API_KEY` 或 `GEMINI_API_KEY` 是否可用
|
||||
- `google-gemini-cli` 的 Gemini OAuth 凭据是否存在
|
||||
- 已配置的 provider 凭据是否可以解析
|
||||
|
||||
如需查看 OAuth 配额使用情况，请在 Hermes 会话中运行：
|
||||
|
||||
```text
|
||||
/gquota
|
||||
```
|
||||
|
||||
`/gquota` 适用于 `google-gemini-cli` OAuth provider，不适用于 AI Studio API 密钥 provider。
|
||||
|
||||
## Gateway（消息平台）
|
||||
|
||||
Gemini 可与所有 Hermes gateway 平台配合使用（Telegram、Discord、Slack、WhatsApp、LINE、飞书等）。将 Gemini 配置为你的 provider，然后正常启动 gateway：
|
||||
|
||||
```bash
|
||||
hermes gateway setup
|
||||
hermes gateway start
|
||||
```
|
||||
|
||||
gateway 读取 `config.yaml` 并使用相同的 Gemini provider 配置。
|
||||
|
||||
## 故障排查
|
||||
|
||||
### "Gemini native client requires an API key"
|
||||
|
||||
Hermes 找不到可用的 API 密钥。请将以下任一项添加到 `~/.hermes/.env`：
|
||||
|
||||
```bash
|
||||
GOOGLE_API_KEY=...
|
||||
# 或
|
||||
GEMINI_API_KEY=...
|
||||
```
|
||||
|
||||
然后重新运行 `hermes model`。
|
||||
|
||||
### "This Google API key is on the free tier"
|
||||
|
||||
Hermes 在设置期间会探测 Gemini API 密钥。由于工具调用、重试、压缩和辅助任务可能需要多次模型调用，免费层级配额在少数几轮 Agent 交互后即可耗尽。
|
||||
|
||||
请为与密钥关联的 Google Cloud 项目启用计费，必要时重新生成密钥，然后运行：
|
||||
|
||||
```bash
|
||||
hermes model
|
||||
```
|
||||
|
||||
### "404 model not found"
|
||||
|
||||
所选模型对你的账号、地区或密钥不可用。重新运行 `hermes model` 并从当前列表中选择其他 Gemini 模型。
|
||||
|
||||
### Gemma 模型未显示在 `hermes model` 中
|
||||
|
||||
Hermes 默认可能会在选择器中隐藏低吞吐量的 Gemma 模型。如果你有意评估某个模型，请直接在 `~/.hermes/config.yaml` 中设置模型 ID。
|
||||
|
||||
### Gemma 出现 "429 quota exceeded"
|
||||
|
||||
通过 Gemini API 提供的 Gemma 模型适合评估使用，但其 Gemini API 免费层级上限较低。请将其用于兼容性测试，然后切换到付费 Gemini 模型或其他 provider 以进行持续的 Agent 会话。
|
||||
|
||||
### 已配置 OpenAI 兼容端点
|
||||
|
||||
检查 `~/.hermes/.env` 中是否存在：
|
||||
|
||||
```bash
|
||||
GEMINI_BASE_URL=https://generativelanguage.googleapis.com/v1beta/openai/
|
||||
```
|
||||
|
||||
将其修改为原生端点或删除该覆盖项：
|
||||
|
||||
```bash
|
||||
GEMINI_BASE_URL=https://generativelanguage.googleapis.com/v1beta
|
||||
```
|
||||
|
||||
### OAuth 登录警告
|
||||
|
||||
`google-gemini-cli` provider 使用 Gemini CLI / Cloud Code Assist OAuth 流程。Hermes 在启动前会发出警告，因为这与官方 AI Studio API 密钥路径不同。如需官方 API 密钥集成，请使用 `provider: gemini` 配合 `GOOGLE_API_KEY`。
|
||||
|
||||
### 工具调用因 schema 错误而失败
|
||||
|
||||
升级 Hermes 并重新运行 `hermes model`。原生 Gemini 适配器会针对 Gemini 更严格的函数声明格式对工具 schema 进行清理；旧版本或自定义端点可能不支持此功能。
|
||||
|
||||
## 相关链接
|
||||
|
||||
- [AI Providers](/integrations/providers)
|
||||
- [Configuration](/user-guide/configuration)
|
||||
- [Fallback Providers](/user-guide/features/fallback-providers)
|
||||
- [AWS Bedrock](/guides/aws-bedrock) — 使用 AWS 凭据的原生云 provider 集成
|
||||
Reference in New Issue
Block a user