Google Vertex AI 上的 Claude Code
了解如何透過 Google Vertex AI 配置 Claude Code,包括設定、IAM 配置和疑難排解。
先決條件
在使用 Vertex AI 配置 Claude Code 之前,請確保您具備:
- 已啟用計費的 Google Cloud Platform (GCP) 帳戶
- 已啟用 Vertex AI API 的 GCP 專案
- 對所需 Claude 模型的存取權限(例如 Claude Sonnet 4)
- 已安裝並配置的 Google Cloud SDK (
gcloud
) - 在所需 GCP 區域中分配的配額
Vertex AI 可能不支援非 us-east5
區域的 Claude Code 預設模型。請確保您使用 us-east5
並已分配配額,或切換到支援的模型。
設定
1. 啟用 Vertex AI API
在您的 GCP 專案中啟用 Vertex AI API:
2. 請求模型存取權限
在 Vertex AI 中請求 Claude 模型的存取權限:
- 導航至 Vertex AI Model Garden
- 搜尋「Claude」模型
- 請求所需 Claude 模型的存取權限(例如 Claude Sonnet 4)
- 等待核准(可能需要 24-48 小時)
3. 配置 GCP 憑證
Claude Code 使用標準的 Google Cloud 驗證。
如需更多資訊,請參閱 Google Cloud 驗證文件。
進行驗證時,Claude Code 會自動使用來自 ANTHROPIC_VERTEX_PROJECT_ID
環境變數的專案 ID。若要覆寫此設定,請設定以下其中一個環境變數:GCLOUD_PROJECT
、GOOGLE_CLOUD_PROJECT
或 GOOGLE_APPLICATION_CREDENTIALS
。
4. 配置 Claude Code
設定以下環境變數:
當您指定 cache_control
暫時標誌時,會自動支援提示快取。若要停用它,請設定 DISABLE_PROMPT_CACHING=1
。如需提高速率限制,請聯絡 Google Cloud 支援。
使用 Vertex AI 時,/login
和 /logout
指令會被停用,因為驗證是透過 Google Cloud 憑證處理的。
5. 模型配置
Claude Code 為 Vertex AI 使用以下預設模型:
模型類型 | 預設值 |
---|---|
主要模型 | claude-sonnet-4@20250514 |
小型/快速模型 | claude-3-5-haiku@20241022 |
若要自訂模型:
IAM 配置
指派所需的 IAM 權限:
roles/aiplatform.user
角色包含所需的權限:
aiplatform.endpoints.predict
- 模型調用所需aiplatform.endpoints.computeTokens
- 權杖計數所需
如需更嚴格的權限,請僅使用上述權限建立自訂角色。
如需詳細資訊,請參閱 Vertex IAM 文件。
我們建議為 Claude Code 建立專用的 GCP 專案,以簡化成本追蹤和存取控制。
疑難排解
如果您遇到配額問題:
- 透過 Cloud Console 檢查目前配額或請求增加配額
如果您遇到「找不到模型」404 錯誤:
- 驗證您是否有指定區域的存取權限
- 確認模型在 Model Garden 中已啟用
如果您遇到 429 錯誤:
- 確保主要模型和小型/快速模型在您選擇的區域中受支援