部署
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)
- 已安装并配置的 Google Cloud SDK (
gcloud
) - 在所需 GCP 区域中分配的配额
Vertex AI 可能不支持非 us-east5
区域的 Claude Code 默认模型。请确保您使用的是 us-east5
并已分配配额,或切换到支持的模型。
设置
1. 启用 Vertex AI API
在您的 GCP 项目中启用 Vertex AI API:
2. 请求模型访问权限
在 Vertex AI 中请求访问 Claude 模型:
- 导航到 Vertex AI Model Garden
- 搜索 “Claude” 模型
- 请求访问所需的 Claude 模型(例如,Claude Sonnet 4)
- 等待批准(可能需要 24-48 小时)
3. 配置 GCP 凭据
Claude Code 使用标准的 Google Cloud 身份验证。
有关更多信息,请参阅 Google Cloud 身份验证文档。
4. 配置 Claude Code
设置以下环境变量:
要获得更高的速率限制和启用提示缓存,请联系 Google Cloud 支持。启用后,请移除 DISABLE_PROMPT_CACHING
设置。
5. 模型配置
Claude Code 为 Vertex AI 使用以下默认模型:
模型类型 | 默认值 |
---|---|
主要模型 | claude-sonnet-4@20250514 |
小型/快速模型 | claude-3-5-haiku@20241022 |
要自定义模型:
IAM 配置
为 Claude Code 授予所需的 IAM 角色。
有关详细信息,请参阅 Vertex IAM 文档。
我们建议为 Claude Code 创建专用的 GCP 项目,以简化成本跟踪和访问控制。
故障排除
如果您遇到配额问题:
- 通过 Cloud Console 检查当前配额或请求增加配额
如果您遇到”模型未找到”404 错误:
- 验证您是否有权访问指定区域
- 确认模型在 Model Garden 中已启用
如果您遇到 429 错误:
- 确保主要模型和小型/快速模型在您选择的区域中受支持