跳轉到主要內容

​
先決條件

在使用 Vertex AI 設定 Claude Code 之前，請確保您具有：
  • 已啟用計費的 Google Cloud Platform (GCP) 帳戶
  • 已啟用 Vertex AI API 的 GCP 專案
  • 存取所需的 Claude 模型（例如 Claude Sonnet 4.6）
  • 已安裝並設定 Google Cloud SDK (gcloud)
  • 在所需的 GCP 區域中分配的配額
如果您要將 Claude Code 部署給多個使用者，請固定您的模型版本，以防止在 Anthropic 發佈新模型時發生中斷。

​
區域設定

Claude Code 可與 Vertex AI 全球和區域端點搭配使用。
Vertex AI 可能不支援所有區域或全球端點上的 Claude Code 預設模型。您可能需要切換到支援的區域、使用區域端點或指定支援的模型。

​
設定

​
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.6）
  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

設定下列環境變數： 
# 啟用 Vertex AI 整合
export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=global
export ANTHROPIC_VERTEX_PROJECT_ID=YOUR-PROJECT-ID

# 選用：如需要，停用 prompt caching
export DISABLE_PROMPT_CACHING=1

# 當 CLOUD_ML_REGION=global 時，覆寫不支援模型的區域
export VERTEX_REGION_CLAUDE_3_5_HAIKU=us-east5

# 選用：覆寫其他特定模型的區域
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-west1
export VERTEX_REGION_CLAUDE_4_0_SONNET=us-east5
export VERTEX_REGION_CLAUDE_4_1_OPUS=europe-west1
當您指定 cache_control 暫時旗標時，Prompt caching 會自動支援。若要停用它，請設定 DISABLE_PROMPT_CACHING=1。如需提高速率限制，請聯絡 Google Cloud 支援。使用 Vertex AI 時，/login 和 /logout 命令會被停用，因為驗證是透過 Google Cloud 認證處理的。

​
5. 固定模型版本

為每個部署固定特定的模型版本。如果您使用模型別名（sonnet、opus、haiku）而不固定版本，Claude Code 可能會嘗試使用未在您的 Vertex AI 專案中啟用的較新模型版本，在 Anthropic 發佈更新時破壞現有使用者。
將這些環境變數設定為特定的 Vertex AI 模型 ID： 
export ANTHROPIC_DEFAULT_OPUS_MODEL='claude-opus-4-6'
export ANTHROPIC_DEFAULT_SONNET_MODEL='claude-sonnet-4-6'
export ANTHROPIC_DEFAULT_HAIKU_MODEL='claude-haiku-4-5@20251001'
如需目前和舊版模型 ID，請參閱模型概覽。如需完整的環境變數清單，請參閱模型設定。 未設定固定變數時，Claude Code 使用這些預設模型：
模型類型預設值
主要模型claude-sonnet-4-6
小型/快速模型claude-haiku-4-5@20251001
若要進一步自訂模型： 
export ANTHROPIC_MODEL='claude-opus-4-6'
export ANTHROPIC_SMALL_FAST_MODEL='claude-haiku-4-5@20251001'

​
IAM 設定

指派所需的 IAM 權限： roles/aiplatform.user 角色包含所需的權限：
  • aiplatform.endpoints.predict - 模型呼叫和權杖計數所需
如需更嚴格的權限，請建立只包含上述權限的自訂角色。 如需詳細資訊，請參閱 Vertex IAM 文件。
為 Claude Code 建立專用的 GCP 專案，以簡化成本追蹤和存取控制。

​
1M token context window

Claude Opus 4.6、Sonnet 4.6、Sonnet 4.5 和 Sonnet 4 在 Vertex AI 上支援 1M token context window。當您選擇 1M 模型變體時，Claude Code 會自動啟用擴展 context window。 若要為您的固定模型啟用 1M context window，請在模型 ID 後附加 [1m]。如需詳細資訊，請參閱為第三方部署固定模型。

​
故障排除

如果您遇到配額問題： 如果您遇到「找不到模型」404 錯誤：
  • 確認模型在 Model Garden 中已啟用
  • 驗證您有權存取指定的區域
  • 如果使用 CLOUD_ML_REGION=global，請檢查您的模型是否在 Model Garden 中的「支援的功能」下支援全球端點。對於不支援全球端點的模型，請執行下列其中一項：
    • 透過 ANTHROPIC_MODEL 或 ANTHROPIC_SMALL_FAST_MODEL 指定支援的模型，或
    • 使用 VERTEX_REGION_<MODEL_NAME> 環境變數設定區域端點
如果您遇到 429 錯誤：
  • 對於區域端點，請確保主要模型和小型/快速模型在您選擇的區域中受支援
  • 考慮切換到 CLOUD_ML_REGION=global 以獲得更好的可用性

​
其他資源