跳到主要內容

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。