跳到主要内容

Google Vertex AI

Hermes Agent 通过 Vertex 的 OpenAI 兼容端点支持 Google Cloud Vertex AI 上的 Gemini 模型。与 Google AI Studio 提供商（使用静态 API 密钥访问 generativelanguage.googleapis.com）不同，Vertex 为您提供企业级速率限制和 GCP 计费/额度，当您希望 Gemini 的使用量计入您的 Google Cloud 账户而非 AI Studio 密钥时，它是正确的选择。

Vertex 使用 OAuth2 进行身份验证，而非 API 密钥

Vertex 的标准端点没有静态 API 密钥。每个请求都需要一个短期有效的 OAuth2 访问令牌（生存期约 1 小时），该令牌由服务账号 JSON 文件或应用默认凭据 (ADC) 生成。Hermes 为您生成并自动刷新这些令牌——您无需手动粘贴令牌。这就是为什么将临时令牌粘贴到自定义提供商的 api_key 字段中不起作用的原因：它会在会话中途过期。

前提条件​

  • 一个 Google Cloud 项目，已启用 Vertex AI API 并激活了计费功能。
  • 凭据，任选其一：
    • 具有 roles/aiplatform.user 角色的服务账号 JSON 密钥文件，或
    • 通过 gcloud auth application-default login 配置的应用默认凭据（或在 GCP VM 上运行时通过元数据服务器配置）。
  • google-auth — 首次选择 Vertex 时会自动安装（延迟安装），或者通过 pip install 'hermes-agent[vertex]' 显式安装。

快速入门​

# Option A — service account JSON (recommended for servers / gateways)
echo "VERTEX_CREDENTIALS_PATH=/path/to/service-account.json" >> ~/.hermes/.env

# Option B — Application Default Credentials (good for local dev)
gcloud auth application-default login

# Select Vertex as your provider
hermes model
# → Choose "More providers..." → "Google Vertex AI"
# → Enter your GCP project ID (or leave blank to use the one in your credentials)
# → Choose a region (default: global)
# → Select a Gemini model

# Start chatting
hermes chat

配置​

Vertex 根据敏感性拆分其设置：

  • 凭据路径是指向秘密信息的指针，位于 ~/.hermes/.env 中。
  • 项目 ID 和区域是非秘密的路由设置，位于 ~/.hermes/config.yaml 中。

~/.hermes/.env：

# One of these (checked in this order); omit both to use ADC:
VERTEX_CREDENTIALS_PATH=/path/to/service-account.json
GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json

~/.hermes/config.yaml：

model:
  default: google/gemini-3-flash-preview
  provider: vertex

vertex:
  project_id: my-gcp-project   # blank → use the project embedded in the credentials
  region: global               # "global" is required for the Gemini 3.x previews
环境变量优先于 config.yaml

VERTEX_PROJECT_ID 和 VERTEX_REGION 会覆盖 config.yaml 中的 vertex.project_id / vertex.region 值。将它们用于每个 shell 的覆盖设置；将持久性设置保留在 config.yaml 中。

身份验证工作原理​

  1. Hermes 按以下顺序解析凭据：VERTEX_CREDENTIALS_PATH → GOOGLE_APPLICATION_CREDENTIALS → ADC。
  2. 它生成一个 OAuth2 访问令牌（cloud-platform 范围）并进行缓存，当令牌距离过期不足 5 分钟时进行刷新。
  3. 令牌被传递给指向 Vertex 端点的标准 OpenAI 客户端： 
    https://aiplatform.googleapis.com/v1beta1/projects/{project}/locations/{region}/endpoints/openapi
    区域位置使用 {region}-aiplatform.googleapis.com 主机代替。
  4. 如果会话运行时间超过令牌生命周期且请求返回 401，Hermes 会重新生成令牌并自动重试。在长期运行的网关上，如果 ADC 的刷新令牌本身已过期，Hermes 会回退到已配置的服务账号 JSON。

可用模型​

Vertex 要求模型 ID 带有 google/ 供应商前缀。hermes model 选择器提供以下选项：

模型ID
Gemini 3.1 Pro Previewgoogle/gemini-3.1-pro-preview
Gemini 3 Pro Previewgoogle/gemini-3-pro-preview
Gemini 3 Flash Previewgoogle/gemini-3-flash-preview
Gemini 3.1 Flash Lite Previewgoogle/gemini-3.1-flash-lite-preview
Gemini 2.5 Progoogle/gemini-2.5-pro
Gemini 2.5 Flashgoogle/gemini-2.5-flash
Gemini 3.x 的 global 区域

Gemini 3.x 预览模型通过 global 端点提供服务。区域端点（如 us-central1 等）可能会返回 404 错误。除非有特定理由固定区域，否则请保留 region: global。

在会话中切换模型​

/model google/gemini-3-pro-preview
/model google/gemini-3-flash-preview

/model 在已配置的提供商和模型之间切换；它不会收集新的凭据。请先使用 hermes model 配置 Vertex。

推理 / 思考​

Vertex 通过 OpenAI 兼容界面暴露 Gemini 的思考预算。Hermes 自动将其推理努力设置映射到 extra_body.google.thinking_config，因此 reasoning_effort 的工作方式与其他 Gemini 界面相同。

诊断​

hermes doctor

Doctor 报告是否可以解析 Vertex 凭据（服务账号路径或 ADC）以及是否已配置提供商。

故障排除​

“无法解析 Vertex AI 凭据”​

Hermes 既未找到服务账号 JSON，也未找到有效的 ADC。请在 ~/.hermes/.env 中设置 VERTEX_CREDENTIALS_PATH，或运行 gcloud auth application-default login。如果您的项目未嵌入凭据中，请在 config.yaml 中设置 vertex.project_id。

未安装 google-auth​

安装额外依赖项：pip install 'hermes-agent[vertex]'。Hermes 还会在您首次选择 Vertex 提供商时延迟安装它。

Gemini 3.x 模型出现 404​

您可能正在使用区域端点。请在 config.yaml 的 vertex: 部分中设置 region: global（或取消设置 VERTEX_REGION）。

403 / 权限被拒绝​

服务账号（或您的 ADC 身份需要在项目上拥有 roles/aiplatform.user 角色，并且必须为该项目启用 Vertex AI API。