Google Vertex AI

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

前置条件 {#prerequisites}

• 一个 Google Cloud 项目，已启用 Vertex AI API 并开通计费。
• 凭据，以下之一：
  • 带 roles/aiplatform.user 角色的服务账号 JSON key 文件，或
  • 经 gcloud auth application-default login 的应用默认凭据（在 GCP VM 上运行时则用元数据服务器）。
• google-auth——你首次选择 Vertex 时自动安装（懒安装）。若失败，运行 hermes setup 修复托管安装。

快速开始 {#quick-start}

# 选项 A——服务账号 JSON（推荐用于服务器 / 网关）
echo "VERTEX_CREDENTIALS_PATH=/path/to/service-account.json" >> ~/.hermes/.env

# 选项 B——应用默认凭据（适合本地开发）
gcloud auth application-default login

# 选择 Vertex 作为提供商
hermes model
# → 选 "More providers..." → "Google Vertex AI"
# → 输入你的 GCP 项目 ID（或留空使用凭据里的那个）
# → 选择区域（默认：global）
# → 选择一个 Gemini 模型

# 开始对话
hermes chat

配置 {#configuration}

Vertex 按敏感程度拆分设置：

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

~/.hermes/.env：

# 以下之一（按此顺序检查）；两者都省略则用 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   # 留空 → 使用凭据内嵌的项目
  region: global               # Gemini 3.x 预览版需要 "global"

认证如何工作 {#how-authentication-works}

1. Hermes 按此顺序解析凭据：VERTEX_CREDENTIALS_PATH → GOOGLE_APPLICATION_CREDENTIALS → ADC。
2. 它铸造一个 OAuth2 access token（cloud-platform 范围）并缓存，在令牌距过期 5 分钟内刷新。
3. 令牌交给一个指向 Vertex 端点的标准 OpenAI 客户端：

   https://aiplatform.googleapis.com/v1beta1/projects/{project}/locations/{region}/endpoints/openapi
   

   区域性 location 改用 {region}-aiplatform.googleapis.com 主机。

4. 若一次会话运行超过令牌寿命且某个请求返回 401，Hermes 重新铸造令牌并自动重试。在长时间运行的网关上，若 ADC 的 refresh token 本身已过期，Hermes 在配置了服务账号 JSON 时回退到它。

可用模型 {#available-models}

Vertex 要求模型 ID 带 google/ 厂商前缀。hermes model 选择器提供：

会话中途切换模型 {#switching-models-mid-session}

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

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

推理 / 思考 {#reasoning--thinking}

Vertex 通过 OpenAI 兼容表面暴露 Gemini 的思考预算。Hermes 自动把它的 reasoning-effort 设置映射到 extra_body.google.thinking_config，因此 reasoning_effort 的工作方式与在其他 Gemini 表面上相同。

诊断 {#diagnostics}

hermes doctor

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

故障排查 {#troubleshooting}

"Vertex AI credentials could not be resolved"

Hermes 既没找到服务账号 JSON，也没找到可用的 ADC。要么在 ~/.hermes/.env 设置 VERTEX_CREDENTIALS_PATH，要么运行 gcloud auth application-default login。若你的项目未内嵌在凭据中，在 config.yaml 设置 vertex.project_id。

google-auth 未安装

你首次选择 Vertex 提供商时 Hermes 懒安装它。若失败，运行 hermes setup 修复托管安装。

Gemini 3.x 模型 404

你很可能在一个区域性端点上。在 config.yaml 的 vertex: 段设 region: global（或 unset VERTEX_REGION）。

403 / 权限被拒

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

相关 {#related}

• Google Gemini（AI Studio）——不带 GCP 的静态 API key Gemini
• AWS Bedrock——另一个原生云提供商集成
• AI 提供商
• 配置