Claude Code 深度学习手册

主题

Claude Code on Google Vertex AI ​

通过 Google Vertex AI 使用 Claude Code，由 GCP 凭据完成鉴权。

是什么 ​

Claude Code 可以接入 Google Cloud 的 Vertex AI，把 Claude 模型托管在你自己的 GCP 项目里运行。鉴权完全走标准的 Google Cloud 认证体系（Application Default Credentials、服务账号密钥或环境内已有凭据），因此用 Vertex AI 时 /logout 命令不可用。

你可以用内置登录向导（v2.1.98 及以上）一步步配置，向导会探测项目与区域、校验项目能调用哪些 Claude 模型并写入用户设置；也可以在 CI 或企业批量部署场景下，纯靠环境变量手动配置。

怎么工作 ​

  • GCP 侧前置一次：启用 Vertex AI API，并在 Vertex AI Model Garden 申请所需 Claude 模型访问权限（审批可能 24-48 小时）
  • 账号鉴权使用标准 Google Cloud 认证（ADC / 服务账号密钥文件 / 环境内凭据）；v2.1.121 起还支持基于 X.509 证书的 Workload Identity Federation
  • 向导方式：运行 claude，登录时选 3rd-party platform 再选 Google Vertex AI；之后随时可用 /setup-vertex 重开向导改凭据、项目、区域或模型 pin
  • 手动方式：设 CLAUDE_CODE_USE_VERTEX=1、CLOUD_ML_REGION、ANTHROPIC_VERTEX_PROJECT_ID 等环境变量完成配置
  • 区域支持 global、多区域（如 eu / us）和具体区域（如 us-east5），Claude Code 自动选取对应 Vertex AI 主机名
  • 启动时会做 model checks，校验目标模型在项目内是否可调用；pin 版本过旧会提示更新，未 pin 且默认模型不可用则本会话回退到上一版本
  • Prompt caching 默认开启，可用 DISABLE_PROMPT_CACHING=1 关闭，或用 ENABLE_PROMPT_CACHING_1H=1 改为 1 小时 TTL（按更高费率计费）
  • Vertex AI 上默认禁用 MCP tool search，需要时对受支持模型设 ENABLE_TOOL_SEARCH=true

怎么配置 / 用法 ​

前置启用 API：

bash
gcloud config set project YOUR-PROJECT-ID
gcloud services enable aiplatform.googleapis.com

核心环境变量：

bash
export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=global
export ANTHROPIC_VERTEX_PROJECT_ID=YOUR-PROJECT-ID
# global 下为不支持 global 端点的模型单独指定区域
export VERTEX_REGION_CLAUDE_HAIKU_4_5=us-east5
export VERTEX_REGION_CLAUDE_4_6_SONNET=europe-west1

多用户部署时 pin 模型版本：

bash
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'

凭据自动刷新（settings 文件）：

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

什么时候用 ​

  • 已有 Google Cloud 账号与启用计费的 GCP 项目，想把 Claude 模型托管在自有 Vertex AI 环境运行
  • 企业团队批量部署：用手动环境变量配置并 pin 模型版本，控制用户何时切换到新模型
  • 需要 GCP 侧统一的成本追踪与访问控制（建议为 Claude Code 建专用项目）
  • 需要 1M token 上下文窗口（Opus 4.6 及以上、Sonnet 4.6 支持）

限制 / 坑 ​

  • 使用 Vertex AI 时 /logout 命令不可用（鉴权由 Google Cloud 凭据托管）
  • 模型在不同端点类型（具体区域 / 多区域 / global）上的可用性不同，可能需切换位置或指定受支持模型
  • tool search 仅 Sonnet 4.5+ 与 Opus 4.5+ 支持，对更早模型启用会因缺少 beta header 而请求失败
  • 后台任务（如会话标题生成）在 Vertex AI 上默认用主模型而非 Haiku，因为 Haiku 未必在每个项目/区域启用
  • ENABLE_PROMPT_CACHING_1H 的 1 小时 TTL 缓存写入按更高费率计费

硬事实速查（12 条） ​

  • 开启集成的核心变量：CLAUDE_CODE_USE_VERTEX=1、CLOUD_ML_REGION、ANTHROPIC_VERTEX_PROJECT_ID
  • Vertex AI 项目 ID 用 ANTHROPIC_VERTEX_PROJECT_ID；GCLOUD_PROJECT、GOOGLE_CLOUD_PROJECT 及 GOOGLE_APPLICATION_CREDENTIALS 引用的凭据文件优先级更高
  • CLOUD_ML_REGION 可设为 global、多区域（eu / us）或具体区域（us-east5）
  • 设置向导与启动 model checks 需要 Claude Code v2.1.98 或更高版本；X.509 证书 WIF 需 v2.1.121 或更高
  • 所需 IAM：roles/aiplatform.user 角色，含 aiplatform.endpoints.predict 权限
  • 未设 pin 变量时的默认主模型为 claude-sonnet-4-5@20250929，small/fast 模型同主模型
  • 未设 ANTHROPIC_DEFAULT_OPUS_MODEL 时，Vertex 上 opus 别名解析为 Opus 4.6；设为 claude-opus-4-8 可用最新模型
  • 在模型 ID 后追加 [1m] 可为手动 pin 的模型启用 1M token 上下文窗口
  • gcpAuthRefresh 设置用于凭据过期时自动刷新，不支持交互输入，3 分钟后超时
  • ANTHROPIC_VERTEX_BASE_URL 可覆盖 Vertex 端点 URL 用于自定义端点或网关
  • 常见排错：凭据报错跑 gcloud auth application-default login；404 检查 Model Garden 中模型是否 Enabled；429 可考虑切换 CLOUD_ML_REGION=global
  • Model Garden 申请模型访问审批可能需 24-48 小时

官方出处：https://code.claude.com/docs/en/google-vertex-ai