Claude Code 中文文档
Docs Claude Code 上 Google Vertex AI
部署 官方原文

Claude Code 上 Google Vertex AI

了解如何通过 Google Vertex AI 配置 Claude Code，包括设置、IAM 配置和故障排除。

了解如何通过 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 区域分配的配额

注意

如果您要将 Claude Code 部署给多个用户，请固定您的模型版本，以防止 Anthropic 发布新模型时出现损坏。

区域配置

Claude Code 可与 Vertex AI 全球 和区域端点一起使用。

注意

Vertex AI 可能不支持所有区域 或全球端点 上的 Claude Code 默认模型。您可能需要切换到支持的区域、使用区域终端节点或指定支持的模型。

设置

1.启用Vertex AI API

在您的 GCP 项目中启用 Vertex AI API：

# Set your project ID
gcloud config set project YOUR-PROJECT-ID

# Enable Vertex AI API
gcloud services enable aiplatform.googleapis.com

2.请求模型访问

请求访问 Vertex AI 中的 Claude 模型：

  1. 导航至【Vertex AI模型花园】(https://console.cloud.google.com/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

设置以下环境变量：

# Enable Vertex AI integration
export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=global
export ANTHROPIC_VERTEX_PROJECT_ID=YOUR-PROJECT-ID

# Optional: Disable prompt caching if needed
export DISABLE_PROMPT_CACHING=1

# When CLOUD_ML_REGION=global, override region for unsupported models
export VERTEX_REGION_CLAUDE_3_5_HAIKU=us-east5

# Optional: Override regions for other specific models
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 临时标志时，自动支持提示缓存。要禁用它，请设置 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_DEFAULT_HAIKU_MODEL='claude-haiku-4-5@20251001'

IAM 配置

分配所需的 IAM 权限：roles/aiplatform.user 角色包括所需的权限：

  • aiplatform.endpoints.predict - 模型调用和令牌计数所需

如需更严格的权限，请创建仅具有上述权限的自定义角色。

有关详细信息，请参阅 Vertex IAM 文档。

注意

为 Claude Code 创建专用 GCP 项目，以简化成本跟踪和访问控制。

1M 令牌上下文窗口

Claude Opus 4.6、Sonnet 4.6、Sonnet 4.5 和 Sonnet 4 支持 Vertex AI 上的 1M 令牌上下文窗口。当您选择 1M 模型变体时，Claude Code 会自动启用扩展上下文窗口。

要为固定模型启用 1M 上下文窗口，请将 [1m] 附加到模型 ID。有关详细信息，请参阅第三方部署的引脚模型。

故障排除

如果您遇到配额问题：

如果遇到“找不到模型”404错误：

  • 确认模型已在[模型花园]中启用(https://console.cloud.google.com/vertex-ai/model-garden)
  • 验证您是否有权访问指定区域
  • 如果使用 CLOUD_ML_REGION=global，请在“支持的功能”下的 模型花园 中检查您的模型是否支持全局端点。对于不支持全局端点的模型，可以：
    • 通过 ANTHROPIC_MODEL 或 ANTHROPIC_DEFAULT_HAIKU_MODEL 指定支持的模型，或者
    • 使用 VERTEX_REGION_<MODEL_NAME> 环境变量设置区域端点

如果遇到 429 错误：

  • 对于区域端点，请确保您选择的区域支持主要模型和小/快速模型
  • 考虑切换到 CLOUD_ML_REGION=global 以获得更好的可用性

其他资源