Claude Code on Google Vertex AI

是什么

Google Vertex AI 是 Claude Code 的云提供商认证选项，通过 GCP 凭证访问 Claude 模型，继承 GCP 合规控制和计费体系。适合已有 GCP 基础设施的企业。

核心机制

前置条件

• GCP 账号，启用计费
• 启用 Vertex AI API 的 GCP 项目
• 在 Vertex AI Model Garden 申请 Claude 模型访问权限（可能需要 24-48 小时审批）
• 安装并配置 Google Cloud SDK（gcloud）

登录向导（推荐，需 v2.1.98+）

claude  # 选择 "3rd-party platform" → "Google Vertex AI"

向导检测 ADC 凭证、验证可用模型、保存配置到 user settings。之后可用 /setup-vertex 重新打开。

手动配置

# 启用 Vertex AI API
gcloud services enable aiplatform.googleapis.com
 
# 配置认证（Application Default Credentials）
gcloud auth application-default login
 
# 设置环境变量
export ANTHROPIC_VERTEX_PROJECT_ID=your-project-id
export CLOUD_ML_REGION=us-east5  # 或 global、eu、us 等

区域配置

• global：全球端点
• eu / us：多区域端点（aiplatform.eu.rep.googleapis.com 等）
• 具体区域如 us-east5：区域端点
• 注意：不同端点支持的模型不同，需确认目标区域的模型可用性

IAM 权限 最小权限：aiplatform.endpoints.predict（Vertex AI User 角色）

固定模型版本

export ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-4-5@20251001
export ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-4-5@20251001

关键细节

• Vertex 上 opus alias 解析为 Opus 4.6，sonnet 解析为 Sonnet 4.5
• 支持 X.509 证书的 Workload Identity Federation（v2.1.121+），通过 GOOGLE_APPLICATION_CREDENTIALS 配置
• Vertex 不发送 metrics 到 Anthropic，成本追踪通过 GCP Billing 或 LiteLLM
• Vertex 不支持 server-managed settings，需使用 file-based 方式

与其他概念的关联

• authentication - 认证方式总览
• llm-gateway - 通过 gateway 统一管理 Vertex 访问
• costs - Vertex 的成本追踪方案

实践要点

• 团队部署前固定模型版本，避免新模型发布导致不可用
• 多区域部署时注意各区域的模型可用性差异
• 服务账号密钥文件方式适合 CI/CD，本地开发推荐 ADC