實戰：接入 Google Vertex AI

這篇教學教你如何把 Hermes Agent 接到 Google 的 Vertex AI 上，用上 Gemini 大模型，而且用的是企業級的額度與帳單。

如果你用過 Google AI Studio，那就像用個人微信；而 Vertex AI 更像是企業釘釘——它沒有固定的 API 鑰匙，而是靠一種叫 OAuth2 的「臨時通行證」來驗證身份。這個通行證大約 1 小時就過期，不過別擔心，Hermes 會自動幫你續期，你全程不用碰它。

開始前的準備

你需要三樣東西：

1. 一個 Google Cloud 專案：記得開通 Vertex AI API 並啟用計費。
2. 一把「鑰匙」：二選一。要麼下載一個服務帳號 JSON 檔案（推薦給伺服器用）；要麼在本機電腦執行 gcloud auth application-default login 登入（適合自己開發玩）。
3. 一個叫 google-auth 的小工具：Hermes 會在你第一次選 Vertex 時自動裝好，不用操心。

第 1 步：告訴 Hermes 你的鑰匙在哪

打開終端機，把鑰匙路徑寫進 Hermes 的設定裡。如果你用的是服務帳號 JSON 檔案，就執行：

echo "VERTEX_CREDENTIALS_PATH=/你的/路徑/service-account.json" >> ~/.hermes/.env

如果你剛才已經用 gcloud 登入了，這一步可以跳過。

第 2 步：選擇 Vertex 作為你的模型供應商

執行指令：

hermes model

在選單裡選 「More providers…」 → 「Google Vertex AI」。接著它會問你兩個問題：

• 專案 ID：填你的 GCP 專案名稱（不填也行，它會自動從鑰匙裡讀）。
• 區域：直接按 Enter 用預設的 global 就行。

最後挑一個 Gemini 模型，比如 google/gemini-3-flash-preview。

第 3 步：開始聊天

hermes chat

搞定！現在你用的就是 Vertex 上的 Gemini 了。

設定小抄

• 秘密資訊（鑰匙路徑）放在 ~/.hermes/.env 檔案裡。
• 非秘密資訊（專案 ID 和區域）放在 ~/.hermes/config.yaml 檔案裡，像這樣：

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

vertex:
  project_id: my-gcp-project   # 留空則用鑰匙裡的
  region: global               # Gemini 3.x 必須用 global

小提示：環境變數 VERTEX_PROJECT_ID 和 VERTEX_REGION 能暫時覆蓋設定檔案裡的值，適合不同終端機用不同設定。

常見問題速查

• 報錯「找不到鑰匙」：去 .env 檔案裡檢查路徑寫沒寫對，或者跑一下 gcloud auth application-default login。
• Gemini 3.x 模型報 404：多半是區域設錯了，把 region 改回 global。
• 403 權限不足：確認服務帳號有 roles/aiplatform.user 角色，並且專案裡已啟用 Vertex AI API。

總結

接入 Vertex 的核心就三步：放好鑰匙、選好模型、開聊。它比 AI Studio 更穩，適合正經專案用。想換模型？聊天時輸入 /model google/gemini-3-pro-preview 就能切換。

下篇預告：下一篇我們聊聊怎麼把 Hermes 接到亞馬遜的 Bedrock 上，看看另一朵雲上的風景。