先決條件

在使用 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:

# 設定您的專案 ID
gcloud config set project YOUR-PROJECT-ID

# 啟用 Vertex AI API
gcloud services enable aiplatform.googleapis.com

2. 請求模型存取權限

在 Vertex AI 中請求 Claude 模型的存取權限:

  1. 導航至 Vertex AI Model Garden
  2. 搜尋「Claude」模型
  3. 請求所需 Claude 模型的存取權限(例如 Claude Sonnet 4)
  4. 等待核准(可能需要 24-48 小時)

3. 配置 GCP 憑證

Claude Code 使用標準的 Google Cloud 驗證。

如需更多資訊,請參閱 Google Cloud 驗證文件

進行驗證時,Claude Code 會自動使用來自 ANTHROPIC_VERTEX_PROJECT_ID 環境變數的專案 ID。若要覆寫此設定,請設定以下其中一個環境變數:GCLOUD_PROJECTGOOGLE_CLOUD_PROJECTGOOGLE_APPLICATION_CREDENTIALS

4. 配置 Claude Code

設定以下環境變數:

# 啟用 Vertex AI 整合
export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=us-east5
export ANTHROPIC_VERTEX_PROJECT_ID=YOUR-PROJECT-ID

# 可選:如需要可停用提示快取
export DISABLE_PROMPT_CACHING=1

# 可選:為特定模型覆寫區域
export VERTEX_REGION_CLAUDE_3_5_HAIKU=us-central1
export VERTEX_REGION_CLAUDE_3_5_SONNET=us-east5
export VERTEX_REGION_CLAUDE_3_7_SONNET=us-east5
export VERTEX_REGION_CLAUDE_4_0_OPUS=europe-west4
export VERTEX_REGION_CLAUDE_4_0_SONNET=us-east5
export VERTEX_REGION_CLAUDE_4_1_OPUS=europe-west4

當您指定 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

若要自訂模型:

export ANTHROPIC_MODEL='claude-opus-4-1@20250805'
export ANTHROPIC_SMALL_FAST_MODEL='claude-3-5-haiku@20241022'

IAM 配置

指派所需的 IAM 權限:

roles/aiplatform.user 角色包含所需的權限:

  • aiplatform.endpoints.predict - 模型調用所需
  • aiplatform.endpoints.computeTokens - 權杖計數所需

如需更嚴格的權限,請僅使用上述權限建立自訂角色。

如需詳細資訊,請參閱 Vertex IAM 文件

我們建議為 Claude Code 建立專用的 GCP 專案,以簡化成本追蹤和存取控制。

疑難排解

如果您遇到配額問題:

如果您遇到「找不到模型」404 錯誤:

  • 驗證您是否有指定區域的存取權限
  • 確認模型在 Model Garden 中已啟用

如果您遇到 429 錯誤:

  • 確保主要模型和小型/快速模型在您選擇的區域中受支援

其他資源