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

Claude Code su Google Vertex AI

Scopri come configurare Claude Code tramite Google Vertex AI, inclusa la configurazione, la configurazione IAM e la risoluzione dei problemi.

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" />} />

Prerequisiti

Prima di configurare Claude Code con Vertex AI, assicurati di avere:

Per accedere con le tue credenziali Vertex AI, segui Accedi con Vertex AI di seguito. Per distribuire Claude Code in un team, utilizza i passaggi di configurazione manuale e fissa le versioni del tuo modello prima del rollout.

Accedi con Vertex AI

Se hai credenziali Google Cloud e desideri iniziare a utilizzare Claude Code tramite Vertex AI, la procedura guidata di accesso ti guida attraverso i passaggi. Completi i prerequisiti lato GCP una volta per progetto; la procedura guidata gestisce il lato Claude Code.

1

Abilita i modelli Claude nel tuo progetto GCP

Abilita Vertex AI API per il tuo progetto, quindi richiedi accesso ai modelli Claude che desideri in Vertex AI Model Garden. Consulta Configurazione IAM per le autorizzazioni di cui il tuo account ha bisogno.

2

Avvia Claude Code e scegli Vertex AI

Esegui claude. Al prompt di accesso, seleziona 3rd-party platform, quindi Google Vertex AI.

3

Segui i prompt della procedura guidata

Scegli come autenticarti a Google Cloud: Application Default Credentials da gcloud, un file di chiave dell'account di servizio, o credenziali già presenti nel tuo ambiente. La procedura guidata rileva il tuo progetto e la tua regione, verifica quali modelli Claude il tuo progetto può invocare, e ti consente di fissarli. Salva il risultato nel blocco env del tuo file di impostazioni utente, quindi non è necessario esportare variabili di ambiente da solo.

Dopo aver effettuato l'accesso, esegui /setup-vertex in qualsiasi momento per riaprire la procedura guidata e modificare le tue credenziali, progetto, regione o fissaggi di modello.

Configurazione della regione

Claude Code supporta endpoint Vertex AI globali, multi-regione e regionali. Imposta CLOUD_ML_REGION su global, una posizione multi-regione come eu o us, o una regione specifica come us-east5. Claude Code seleziona il nome host Vertex AI corretto per ogni modulo, inclusi gli host aiplatform.eu.rep.googleapis.com e aiplatform.us.rep.googleapis.com per le posizioni multi-regione.

Configurazione manuale

Per configurare Vertex AI tramite variabili di ambiente invece della procedura guidata, ad esempio in CI o in un rollout aziendale con script, segui i passaggi di seguito.

1. Abilita Vertex AI API

Abilita Vertex AI API nel tuo progetto GCP:

# Imposta il tuo ID progetto
gcloud config set project YOUR-PROJECT-ID

# Abilita Vertex AI API
gcloud services enable aiplatform.googleapis.com

2. Richiedi accesso al modello

Richiedi accesso ai modelli Claude in Vertex AI:

  1. Accedi a Vertex AI Model Garden
  2. Cerca i modelli "Claude"
  3. Richiedi accesso ai modelli Claude desiderati (ad esempio, Claude Sonnet 4.6)
  4. Attendi l'approvazione (potrebbe richiedere 24-48 ore)

3. Configura le credenziali GCP

Claude Code utilizza l'autenticazione standard di Google Cloud.

Per ulteriori informazioni, consulta la documentazione di autenticazione di Google Cloud.

Claude Code v2.1.121 o versioni successive supporta X.509 certificate-based Workload Identity Federation attraverso la stessa catena Application Default Credentials. Imposta GOOGLE_APPLICATION_CREDENTIALS al percorso del tuo file di configurazione delle credenziali.

Configurazione avanzata delle credenziali

Claude Code supporta l'aggiornamento automatico delle credenziali GCP tramite l'impostazione gcpAuthRefresh. Quando Claude Code rileva che le tue credenziali GCP sono scadute o non possono essere caricate, esegue il comando configurato per ottenere nuove credenziali prima di riprovare la richiesta.

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

L'output del comando viene visualizzato all'utente, ma l'input interattivo non è supportato. Questo funziona bene per i flussi di autenticazione basati su browser in cui la CLI mostra un URL e completi l'autenticazione nel browser. Il comando di aggiornamento scade dopo tre minuti se l'autenticazione non viene completata. Se imposti gcpAuthRefresh nelle impostazioni del progetto come .claude/settings.json, il comando viene eseguito solo dopo che accetti il prompt di fiducia dell'area di lavoro.

4. Configura Claude Code

Imposta le seguenti variabili di ambiente:

# Abilita integrazione Vertex AI
export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=global
export ANTHROPIC_VERTEX_PROJECT_ID=YOUR-PROJECT-ID

# Facoltativo: Esegui l'override dell'URL dell'endpoint Vertex per endpoint personalizzati o gateway
# export ANTHROPIC_VERTEX_BASE_URL=https://aiplatform.googleapis.com

# Facoltativo: Disabilita prompt caching se necessario
export DISABLE_PROMPT_CACHING=1

# Facoltativo: Richiedi TTL cache prompt di 1 ora invece del valore predefinito di 5 minuti
export ENABLE_PROMPT_CACHING_1H=1

# Quando CLOUD_ML_REGION=global, esegui l'override della regione per i modelli che non supportano endpoint globali
export VERTEX_REGION_CLAUDE_HAIKU_4_5=us-east5
export VERTEX_REGION_CLAUDE_4_6_SONNET=europe-west1

La maggior parte delle versioni del modello ha una variabile VERTEX_REGION_CLAUDE_* corrispondente. Consulta il riferimento delle variabili di ambiente per l'elenco completo. Controlla Vertex Model Garden per determinare quali modelli supportano endpoint globali rispetto a quelli solo regionali.

Prompt caching è abilitato automaticamente. Per disabilitarlo, imposta DISABLE_PROMPT_CACHING=1. Per richiedere un TTL cache di 1 ora invece del valore predefinito di 5 minuti, imposta ENABLE_PROMPT_CACHING_1H=1; le scritture della cache con TTL di 1 ora vengono fatturate a una tariffa più elevata. Per limiti di velocità aumentati, contatta il supporto di Google Cloud. Quando utilizzi Vertex AI, i comandi /login e /logout sono disabilitati poiché l'autenticazione è gestita tramite le credenziali di Google Cloud.

MCP tool search è disabilitato per impostazione predefinita su Vertex AI perché l'endpoint non accetta l'intestazione beta richiesta. Tutte le definizioni degli strumenti MCP vengono caricate in anticipo. Per acconsentire, imposta ENABLE_TOOL_SEARCH=true.

5. Fissa le versioni del modello

Imposta queste variabili di ambiente su ID modello Vertex AI specifici.

Senza ANTHROPIC_DEFAULT_OPUS_MODEL, l'alias opus su Vertex si risolve in Opus 4.6. Impostalo sull'ID di Opus 4.7 per utilizzare il modello più recente:

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'

Per gli ID modello attuali e legacy, consulta Panoramica dei modelli. Consulta Configurazione del modello per l'elenco completo delle variabili di ambiente.

Claude Code utilizza questi modelli predefiniti quando nessuna variabile di fissaggio è impostata:

Tipo di modello Valore predefinito
Modello primario claude-sonnet-4-5@20250929
Modello piccolo/veloce claude-haiku-4-5@20251001

Per personalizzare ulteriormente i modelli:

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

Controlli del modello all'avvio

Quando Claude Code si avvia con Vertex AI configurato, verifica che i modelli che intende utilizzare siano accessibili nel tuo progetto. Questo controllo richiede Claude Code v2.1.98 o versione successiva.

Se hai fissato una versione del modello più vecchia del valore predefinito corrente di Claude Code, e il tuo progetto può invocare la versione più recente, Claude Code ti chiede di aggiornare il fissaggio. Accettare scrive il nuovo ID modello nel tuo file di impostazioni utente e riavvia Claude Code. Rifiutare viene ricordato fino al prossimo cambio di versione predefinita.

Se non hai fissato un modello e il valore predefinito corrente non è disponibile nel tuo progetto, Claude Code ritorna alla versione precedente per la sessione corrente e mostra un avviso. Il ritorno non è persistente. Abilita il modello più recente in Model Garden o fissa una versione per rendere la scelta permanente.

Configurazione IAM

Assegna le autorizzazioni IAM richieste:

Il ruolo roles/aiplatform.user include le autorizzazioni richieste:

Per autorizzazioni più restrittive, crea un ruolo personalizzato con solo le autorizzazioni di cui sopra.

Per i dettagli, consulta la documentazione IAM di Vertex.

Finestra di contesto da 1M token

Claude Opus 4.7, Opus 4.6 e Sonnet 4.6 supportano la finestra di contesto da 1M token su Vertex AI. Claude Code abilita automaticamente la finestra di contesto estesa quando selezioni una variante di modello 1M.

La procedura guidata di configurazione offre un'opzione di contesto 1M quando fissa i modelli. Per abilitarla per un modello fissato manualmente, aggiungi [1m] all'ID del modello. Consulta Fissa i modelli per le distribuzioni di terze parti per i dettagli.

Risoluzione dei problemi

Se riscontri errori "Could not load the default credentials":

Se riscontri problemi di quota:

Se riscontri errori "model not found" 404:

Se riscontri errori 429:

Risorse aggiuntive