SpyBara
Go Premium

google-vertex-ai.md 2026-06-09 06:34 UTC to 2026-06-10 23:57 UTC

This page contains 50 additions and 92 deletions.

2026
Wed 10 23:57 Wed 17 17:02 Tue 30 23:02

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.6）
  • 已安裝並設定 Google Cloud SDK (gcloud)
  • 在所需的 GCP 區域中分配的配額

若要使用您自己的 Vertex AI 認證登入，請遵循下方的使用 Vertex AI 登入。若要在整個團隊中部署 Claude Code，請使用手動設定步驟並在推出前固定您的模型版本。

使用 Vertex AI 登入

如果您有 Google Cloud 認證並想開始透過 Vertex AI 使用 Claude Code，登入精靈會引導您完成整個過程。您只需在每個專案中完成一次 GCP 端的先決條件；精靈會處理 Claude Code 端的設定。

1

在您的 GCP 專案中啟用 Claude 模型

為您的專案啟用 Vertex AI API，然後在 Vertex AI Model Garden 中要求存取您想要的 Claude 模型。請參閱 IAM 設定以了解您的帳戶需要的權限。

2

啟動 Claude Code 並選擇 Vertex AI

執行 claude。在登入提示處，選擇第三方平台，然後選擇 Google Vertex AI。

3

遵循精靈提示

選擇您如何向 Google Cloud 進行驗證：來自 gcloud 的應用程式預設認證、服務帳戶金鑰檔案，或已在您的環境中的認證。精靈會偵測您的專案和區域，驗證您的專案可以呼叫哪些 Claude 模型，並讓您固定它們。它會將結果儲存到您的使用者設定檔的 env 區塊，因此您不需要自己匯出環境變數。

登入後，您可以隨時執行 /setup-vertex 以重新開啟精靈並變更您的認證、專案、區域或模型固定。

區域設定

Claude Code 支援 Vertex AI 全球、多區域和區域端點。將 CLOUD_ML_REGION 設定為 global、多區域位置（例如 eu 或 us）或特定區域（例如 us-east5）。Claude Code 為每種形式選擇正確的 Vertex AI 主機名稱，包括多區域位置的 aiplatform.eu.rep.googleapis.com 和 aiplatform.us.rep.googleapis.com 主機。

手動設定

若要透過環境變數而不是精靈來設定 Vertex AI，例如在 CI 或指令碼化企業推出中，請遵循下列步驟。

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 v2.1.121 或更新版本透過相同的 Application Default Credentials 鏈支援 X.509 憑證型 Workload Identity Federation。將 GOOGLE_APPLICATION_CREDENTIALS 設定為您的認證設定檔案路徑。

進階認證設定

Claude Code 透過 gcpAuthRefresh 設定支援 GCP 的自動認證重新整理。當 Claude Code 偵測到您的 GCP 認證已過期或無法載入時，它會執行設定的命令以在重試要求之前取得新認證。

{
  "gcpAuthRefresh": "gcloud auth application-default login",
  "env": {
    "ANTHROPIC_VERTEX_PROJECT_ID": "your-project-id"
  }
}

命令的輸出會顯示給使用者，但不支援互動式輸入。這適用於瀏覽器型驗證流程，其中 CLI 顯示 URL，您在瀏覽器中完成驗證。如果驗證未在三分鐘內完成，重新整理命令會逾時。如果您在專案設定（例如 .claude/settings.json）中設定 gcpAuthRefresh，命令只會在您接受工作區信任提示後執行。

4. 設定 Claude Code

設定下列環境變數：

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

# 選用：覆寫 Vertex 端點 URL 以用於自訂端點或閘道
# export ANTHROPIC_VERTEX_BASE_URL=https://aiplatform.googleapis.com

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

# 選用：要求 1 小時 prompt cache TTL 而不是 5 分鐘預設值
export ENABLE_PROMPT_CACHING_1H=1

# 當 CLOUD_ML_REGION=global 時，覆寫不支援全球端點的模型的區域
export VERTEX_REGION_CLAUDE_HAIKU_4_5=us-east5
export VERTEX_REGION_CLAUDE_4_6_SONNET=europe-west1

大多數模型版本都有對應的 VERTEX_REGION_CLAUDE_* 變數。如需完整清單，請參閱環境變數參考。檢查 Vertex Model Garden 以確定哪些模型支援全球端點與僅限區域端點。

Prompt caching 會自動啟用。若要停用它，請設定 DISABLE_PROMPT_CACHING=1。若要要求 1 小時 cache TTL 而不是 5 分鐘預設值，請設定 ENABLE_PROMPT_CACHING_1H=1；具有 1 小時 TTL 的 cache 寫入會以更高費率計費。如需提高速率限制，請聯絡 Google Cloud 支援。使用 Vertex AI 時，/logout 命令會被停用，因為驗證是透過 Google Cloud 認證處理的。

Claude Code 在 Vertex AI 上預設停用 MCP tool search，因此 MCP 工具定義會預先載入。Vertex AI 支援 Claude Sonnet 4.5 及更新版本以及 Claude Opus 4.5 及更新版本的工具搜尋。設定 ENABLE_TOOL_SEARCH=true 以在這些模型上啟用它。Vertex AI 上的較早模型不接受所需的 beta 標頭，如果您使用它們啟用工具搜尋，要求會失敗。

5. 固定模型版本

將這些環境變數設定為特定的 Vertex AI 模型 ID。

如果沒有 ANTHROPIC_DEFAULT_OPUS_MODEL，Vertex 上的 opus 別名會解析為 Opus 4.6。將其設定為 Opus 4.8 ID 以使用最新模型：

export ANTHROPIC_DEFAULT_OPUS_MODEL='claude-opus-4-8'
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-5@20250929
小型/快速模型 與主要模型相同

背景工作（例如工作階段標題產生）使用小型/快速模型，通常是 Haiku 級模型。在 Vertex AI 上，Claude Code 預設為主要模型，因為 Haiku 可能不會在每個專案或區域中啟用。若要使用 Haiku 進行背景工作，請將 ANTHROPIC_DEFAULT_HAIKU_MODEL 設定為您專案中可用的模型 ID。

若要進一步自訂模型：

export ANTHROPIC_MODEL='claude-opus-4-8'
export ANTHROPIC_DEFAULT_HAIKU_MODEL='claude-haiku-4-5@20251001'

啟動模型檢查

當 Claude Code 以設定的 Vertex AI 啟動時，它會驗證它打算使用的模型在您的專案中是否可存取。此檢查需要 Claude Code v2.1.98 或更新版本。

如果您已固定的模型版本比目前 Claude Code 預設值更舊，且您的專案可以呼叫較新版本，Claude Code 會提示您更新固定。接受會將新模型 ID 寫入您的使用者設定檔並重新啟動 Claude Code。拒絕會被記住，直到下一次預設版本變更。

如果您尚未固定模型，且目前預設值在您的專案中無法使用，Claude Code 會在目前工作階段中回退到先前版本並顯示通知。回退不會被保留。在 Model Garden 中啟用較新模型或固定版本以使選擇永久化。

IAM 設定

指派所需的 IAM 權限：

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

  • aiplatform.endpoints.predict - 模型呼叫和權杖計數所需

如需更嚴格的權限，請建立只包含上述權限的自訂角色。

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

1M token context window

Claude Opus 4.6 及更新版本，以及 Sonnet 4.6，在 Vertex AI 上支援 1M token context window。當您選擇 1M 模型變體時，Claude Code 會自動啟用擴展 context window。

設定精靈在固定模型時提供 1M context 選項。若要為手動固定的模型啟用它，請在模型 ID 後附加 [1m]。如需詳細資訊，請參閱為第三方部署固定模型。

故障排除

如果您遇到「無法載入預設認證」錯誤：

  • 執行 gcloud auth application-default login 以設定應用程式預設認證
  • 將 GOOGLE_APPLICATION_CREDENTIALS 設定為服務帳戶金鑰檔案路徑
  • 請參閱 設定 GCP 認證 以了解所有選項

如果您遇到配額問題：

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

  • 確認模型在 Model Garden 中已啟用
  • 驗證模型在您指定的位置中可用。某些模型僅在 global 或多區域位置（例如 eu 和 us）上提供，不在特定區域中
  • 如果使用 CLOUD_ML_REGION=global，請檢查您的模型是否在 Model Garden 中的「支援的功能」下支援全球端點。對於不支援全球端點的模型，請執行下列其中一項：
    • 透過 ANTHROPIC_MODEL 或 ANTHROPIC_DEFAULT_HAIKU_MODEL 指定支援的模型，或
    • 使用 VERTEX_REGION_<MODEL_NAME> 環境變數設定區域或多區域位置

如果您遇到 429 錯誤：

  • 對於區域端點，請確保主要模型和小型/快速模型在您選擇的區域中受支援
  • 考慮切換到 CLOUD_ML_REGION=global 以獲得更好的可用性

其他資源