先决条件

在使用 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 身份验证文档

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

要获得更高的速率限制和启用提示缓存,请联系 Google Cloud 支持。启用后,请移除 DISABLE_PROMPT_CACHING 设置。

5. 模型配置

Claude Code 为 Vertex AI 使用以下默认模型:

模型类型默认值
主要模型claude-sonnet-4@20250514
小型/快速模型claude-3-5-haiku@20241022

要自定义模型:

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

IAM 配置

为 Claude Code 授予所需的 IAM 角色。

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

我们建议为 Claude Code 创建专用的 GCP 项目,以简化成本跟踪和访问控制。

故障排除

如果您遇到配额问题:

如果您遇到”模型未找到”404 错误:

  • 验证您是否有权访问指定区域
  • 确认模型在 Model Garden 中已启用

如果您遇到 429 错误:

  • 确保主要模型和小型/快速模型在您选择的区域中受支持

其他资源