SpyBara
Go Premium

google-vertex-ai.md 2026-05-05 23:00 UTC to 2026-05-07 22:59 UTC

22 added, 1 removed.

2026
Sun 31 06:39 Sat 30 06:23 Fri 29 06:38 Thu 28 06:37 Wed 27 06:42 Tue 26 06:33 Sun 24 06:25 Sat 23 06:18 Fri 22 06:33 Thu 21 06:36 Wed 20 06:35 Tue 19 06:34 Mon 18 23:59 Sun 17 01:01 Fri 15 22:58 Thu 14 17:02 Wed 13 23:01 Tue 12 22:57 Mon 11 23:00 Sun 10 23:03 Sat 9 04:57 Fri 8 22:00 Thu 7 22:59 Tue 5 23:00 Mon 4 22:58 Sat 2 18:14 Fri 1 18:19

Google Vertex AI 上的 Claude Code

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

export const ContactSalesCard = ({surface}) => { const utm = content => utm_source=claude_code&utm_medium=docs&utm_content=${surface}_${content}; const iconArrowRight = (size = 13) => <svg width={size} height={size} viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2.5" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true"> ; const STYLES = .cc-cs { --cs-slate: #141413; --cs-clay: #d97757; --cs-clay-deep: #c6613f; --cs-gray-000: #ffffff; --cs-gray-700: #3d3d3a; --cs-border-default: rgba(31, 30, 29, 0.15); font-family: inherit; } .dark .cc-cs { --cs-slate: #f0eee6; --cs-gray-000: #262624; --cs-gray-700: #bfbdb4; --cs-border-default: rgba(240, 238, 230, 0.14); } .cc-cs-card { display: flex; align-items: center; justify-content: space-between; gap: 16px; padding: 14px 16px; margin: 0; background: var(--cs-gray-000); border: 0.5px solid var(--cs-border-default); border-radius: 8px; flex-wrap: wrap; } .cc-cs-text { font-size: 13px; color: var(--cs-gray-700); line-height: 1.5; flex: 1; min-width: 240px; } .cc-cs-text strong { font-weight: 550; color: var(--cs-slate); } .cc-cs-actions { display: flex; align-items: center; gap: 8px; flex-shrink: 0; } .cc-cs-btn-clay { display: inline-flex; align-items: center; gap: 8px; background: var(--cs-clay-deep); color: #fff; border: none; border-radius: 8px; padding: 8px 14px; font-size: 13px; font-weight: 500; transition: background-color 0.15s; white-space: nowrap; } .cc-cs-btn-clay:hover { background: var(--cs-clay); } .cc-cs-btn-ghost { display: inline-flex; align-items: center; gap: 8px; background: transparent; color: var(--cs-gray-700); border: 0.5px solid var(--cs-border-default); border-radius: 8px; padding: 8px 14px; font-size: 13px; font-weight: 500; } .cc-cs-btn-ghost:hover { background: rgba(0, 0, 0, 0.04); } .dark .cc-cs-btn-ghost:hover { background: rgba(255, 255, 255, 0.04); } @media (max-width: 720px) { .cc-cs-actions { width: 100%; } }; return <div className="cc-cs not-prose"> <div className="cc-cs-card"> <div className="cc-cs-text"> Deploying Claude Code across your organization? Talk to sales about enterprise plans, SSO, and centralized billing.

<div className="cc-cs-actions"> <a href={https://claude.com/pricing?${utm('view_plans')}#plans-business} className="cc-cs-btn-ghost"> View plans <a href={https://claude.com/contact-sales?${utm('contact_sales')}} className="cc-cs-btn-clay"> Contact sales {iconArrowRight()}
; };

export const Experiment = ({flag, treatment, children}) => { const VID_KEY = 'exp_vid'; const CONSENT_COUNTRIES = new Set(['AT', 'BE', 'BG', 'HR', 'CY', 'CZ', 'DK', 'EE', 'FI', 'FR', 'DE', 'GR', 'HU', 'IE', 'IT', 'LV', 'LT', 'LU', 'MT', 'NL', 'PL', 'PT', 'RO', 'SK', 'SI', 'ES', 'SE', 'RE', 'GP', 'MQ', 'GF', 'YT', 'BL', 'MF', 'PM', 'WF', 'PF', 'NC', 'AW', 'CW', 'SX', 'FO', 'GL', 'AX', 'GB', 'UK', 'AI', 'BM', 'IO', 'VG', 'KY', 'FK', 'GI', 'MS', 'PN', 'SH', 'TC', 'GG', 'JE', 'IM', 'CA', 'BR', 'IN']); const fnv1a = s => { let h = 0x811c9dc5; for (let i = 0; i < s.length; i++) { h ^= s.charCodeAt(i); h += (h << 1) + (h << 4) + (h << 7) + (h << 8) + (h << 24); } return h >>> 0; }; const bucket = (seed, vid) => fnv1a(fnv1a(seed + vid) + '') % 10000 < 5000 ? 'control' : 'treatment'; const [decision] = useState(() => { const params = new URLSearchParams(location.search); const preBucketed = document.documentElement.dataset['gb_' + flag.replace(/-/g, '_')]; const force = params.get('gb-force'); if (force) { for (const p of force.split(',')) { const [k, v] = p.split(':'); if (k === flag) return { variant: v || 'treatment', track: false }; } } if (navigator.globalPrivacyControl) { return { variant: 'control', track: false }; } const prefsMatch = document.cookie.match(/(?:^|; )anthropic-consent-preferences=([^;]+)/); if (prefsMatch) { try { if (JSON.parse(decodeURIComponent(prefsMatch[1])).analytics !== true) { return { variant: 'control', track: false }; } } catch { return { variant: 'control', track: false }; } } else { const country = params.get('country')?.toUpperCase() || (document.cookie.match(/(?:^|; )cf_geo=([A-Z]{2})/) || [])[1]; if (!country || CONSENT_COUNTRIES.has(country)) { return { variant: 'control', track: false }; } } let vid; try { const ajsMatch = document.cookie.match(/(?:^|; )ajs_anonymous_id=([^;]+)/); if (ajsMatch) { vid = decodeURIComponent(ajsMatch[1]).replace(/^"|"$/g, ''); } else { vid = localStorage.getItem(VID_KEY); if (!vid) { vid = crypto.randomUUID(); } document.cookie = ajs_anonymous_id=${vid}; domain=.claude.com; path=/; Secure; SameSite=Lax; max-age=31536000; } try { localStorage.setItem(VID_KEY, vid); } catch {} } catch { return { variant: 'control', track: false }; } const variant = preBucketed === '1' ? 'treatment' : preBucketed === '0' ? 'control' : bucket(flag, vid); return { variant, track: true, vid }; }); useEffect(() => { if (!decision.track) return; fetch('https://api.anthropic.com/api/event_logging/v2/batch', { method: 'POST', headers: { 'Content-Type': 'application/json', 'x-service-name': 'claude_code_docs' }, body: JSON.stringify({ events: [{ event_type: 'GrowthbookExperimentEvent', event_data: { device_id: decision.vid, anonymous_id: decision.vid, timestamp: new Date().toISOString(), experiment_id: flag, variation_id: decision.variant === 'treatment' ? 1 : 0, environment: 'production' } }] }), keepalive: true }).catch(() => {}); }, []); return decision.variant === 'treatment' ? treatment : children; };

<Experiment flag="docs-contact-sales-cta" treatment={<ContactSalesCard surface="vertex" />} />

前置条件

在使用 Vertex AI 配置 Claude Code 之前，请确保您拥有：

要使用您自己的 Vertex AI 凭证登录，请按照下面的使用 Vertex AI 登录进行操作。要在团队中部署 Claude Code，请使用手动设置步骤并在推出前固定您的模型版本。

使用 Vertex AI 登录

如果您拥有 Google Cloud 凭证并想开始通过 Vertex AI 使用 Claude Code，登录向导会引导您完成整个过程。您需要在每个项目中完成一次 GCP 端的前置条件；向导会处理 Claude Code 端的事务。

1

在您的 GCP 项目中启用 Claude 模型

为您的项目启用 Vertex AI API，然后在 Vertex AI Model Garden 中请求访问您想要的 Claude 模型。有关您的账户需要的权限，请参阅 IAM 配置。

2

启动 Claude Code 并选择 Vertex AI

运行 claude。在登录提示处，选择 3rd-party platform，然后选择 Google Vertex AI。

3

按照向导提示进行操作

选择您如何向 Google Cloud 进行身份验证：来自 gcloud 的应用默认凭证、服务账户密钥文件或已在您的环境中的凭证。向导会检测您的项目和区域，验证您的项目可以调用哪些 Claude 模型，并让您固定它们。它将结果保存到您的用户设置文件的 env 块中，因此您无需自己导出环境变量。

登录后，您可以随时运行 /setup-vertex 来重新打开向导并更改您的凭证、项目、区域或模型固定。

区域配置

Claude Code 支持 Vertex AI 全局、多区域和区域端点。将 CLOUD_ML_REGION 设置为 global、多区域位置（如 eu 或 us）或特定区域（如 us-east5）。Claude Code 为每种形式选择正确的 Vertex AI 主机名，包括多区域位置的 aiplatform.eu.rep.googleapis.com 和 aiplatform.us.rep.googleapis.com 主机。

手动设置

要通过环境变量而不是向导配置 Vertex AI，例如在 CI 或脚本化企业推出中，请按照下面的步骤进行。

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.6）
  4. 等待批准（可能需要 24-48 小时）

3. 配置 GCP 凭证

Claude Code 使用标准的 Google Cloud 身份验证。

有关更多信息，请参阅 Google Cloud 身份验证文档。

Claude Code v2.1.121 或更高版本通过相同的应用默认凭证链支持基于 X.509 证书的工作负载身份联合。将 GOOGLE_APPLICATION_CREDENTIALS 设置为您的凭证配置文件的路径。

高级凭证配置

Claude Code 通过 gcpAuthRefresh 设置支持 GCP 的自动凭证刷新。当 Claude Code 检测到您的 GCP 凭证已过期或无法加载时，它会运行配置的命令以在重试请求之前获取新凭证。

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

命令的输出会显示给用户，但不支持交互式输入。这对于基于浏览器的身份验证流程效果很好，其中 CLI 显示 URL，您在浏览器中完成身份验证。如果身份验证未在三分钟内完成，刷新命令将超时。如果您在项目设置（如 .claude/settings.json）中设置 gcpAuthRefresh，该命令仅在您接受工作区信任提示后运行。

4. 配置 Claude Code

设置以下环境变量：

# 启用 Vertex AI 集成
export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=global
export ANTHROPIC_VERTEX_PROJECT_ID=YOUR-PROJECT-ID

# 可选：为自定义端点或网关覆盖 Vertex 端点 URL
# export ANTHROPIC_VERTEX_BASE_URL=https://aiplatform.googleapis.com

# 可选：如果需要，禁用 prompt caching
export DISABLE_PROMPT_CACHING=1

# 可选：请求 1 小时的 prompt cache TTL 而不是 5 分钟的默认值
export ENABLE_PROMPT_CACHING_1H=1

# 当 CLOUD_ML_REGION=global 时，为不支持全局端点的模型覆盖区域
export VERTEX_REGION_CLAUDE_HAIKU_4_5=us-east5
export VERTEX_REGION_CLAUDE_4_6_SONNET=europe-west1

大多数模型版本都有对应的 VERTEX_REGION_CLAUDE_* 变量。有关完整列表，请参阅环境变量参考。检查 Vertex Model Garden 以确定哪些模型支持全局端点与仅区域端点。

Prompt caching 会自动启用。要禁用它，请设置 DISABLE_PROMPT_CACHING=1。要请求 1 小时的缓存 TTL 而不是 5 分钟的默认值，请设置 ENABLE_PROMPT_CACHING_1H=1；具有 1 小时 TTL 的缓存写入按更高费率计费。如需提高速率限制，请联系 Google Cloud 支持。使用 Vertex AI 时，/login 和 /logout 命令被禁用，因为身份验证通过 Google Cloud 凭证处理。

MCP tool search 在 Vertex AI 上默认被禁用，因为端点不接受所需的 beta 标头。所有 MCP 工具定义会预先加载。要选择加入，请设置 ENABLE_TOOL_SEARCH=true。

5. 固定模型版本

将这些环境变量设置为特定的 Vertex AI 模型 ID。

如果没有 ANTHROPIC_DEFAULT_OPUS_MODEL，Vertex 上的 opus 别名会解析为 Opus 4.6。将其设置为 Opus 4.7 ID 以使用最新模型：

export ANTHROPIC_DEFAULT_OPUS_MODEL='claude-opus-4-7'
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-5@20250929
小型/快速模型 claude-haiku-4-5@20251001

要进一步自定义模型：

export ANTHROPIC_MODEL='claude-opus-4-7'
export ANTHROPIC_DEFAULT_HAIKU_MODEL='claude-haiku-4-5@20251001'

启动模型检查

当 Claude Code 启动并配置了 Vertex AI 时，它会验证它打算使用的模型在您的项目中是否可访问。此检查需要 Claude Code v2.1.98 或更高版本。

如果您固定了一个比当前 Claude Code 默认值更旧的模型版本，并且您的项目可以调用较新版本，Claude Code 会提示您更新固定。接受会将新的模型 ID 写入您的用户设置文件并重启 Claude Code。拒绝会被记住，直到下一个默认版本更改。

如果您没有固定模型，并且当前默认值在您的项目中不可用，Claude Code 会在当前会话中回退到之前的版本并显示通知。回退不会被持久化。在 Model Garden 中启用较新的模型或固定一个版本以使选择永久化。

IAM 配置

分配所需的 IAM 权限：

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

对于更严格的权限，请创建仅包含上述权限的自定义角色。

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

1M token context window

Claude Opus 4.7、Opus 4.6 和 Sonnet 4.6 在 Vertex AI 上支持 1M token context window。当您选择 1M 模型变体时，Claude Code 会自动启用扩展 context window。

设置向导在固定模型时提供 1M context 选项。要为手动固定的模型启用它，请在模型 ID 后附加 [1m]。有关详细信息，请参阅为第三方部署固定模型。

故障排除

如果您遇到"无法加载默认凭证"错误：

如果您遇到配额问题：

如果您遇到"模型未找到"404 错误：

如果您遇到 429 错误：

其他资源