Vai al contenuto principale

Documentation Index

Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

​
Prerequisiti

Prima di configurare Claude Code con Vertex AI, assicurati di avere:
  • Un account Google Cloud Platform (GCP) con fatturazione abilitata
  • Un progetto GCP con Vertex AI API abilitata
  • Accesso ai modelli Claude desiderati (ad esempio, Claude Sonnet 4.6)
  • Google Cloud SDK (gcloud) installato e configurato
  • Quota allocata nella regione GCP desiderata
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.
La procedura guidata di configurazione di Vertex AI richiede Claude Code v2.1.98 o versione successiva. Esegui claude --version per verificare.
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.
Vertex AI potrebbe non supportare i modelli predefiniti di Claude Code su ogni tipo di endpoint. La disponibilità del modello varia tra regioni specifiche, posizioni multi-regione e endpoint globali. Potrebbe essere necessario passare a una posizione supportata o specificare un modello supportato.

​
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.
Claude Code utilizza ANTHROPIC_VERTEX_PROJECT_ID come ID progetto per le richieste Vertex AI. Le variabili di ambiente GCLOUD_PROJECT e GOOGLE_CLOUD_PROJECT e il file di credenziali a cui fa riferimento GOOGLE_APPLICATION_CREDENTIALS hanno la precedenza su di esso. Se nessuno di questi è impostato, l’ID progetto viene risolto dalla tua configurazione gcloud o dall’account di servizio collegato.

​
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. Claude Code disabilita MCP tool search per impostazione predefinita su Vertex AI, quindi le definizioni degli strumenti MCP vengono caricate in anticipo. Vertex AI supporta la ricerca degli strumenti per Claude Sonnet 4.5 e versioni successive e Claude Opus 4.5 e versioni successive. Imposta ENABLE_TOOL_SEARCH=true per abilitarla su questi modelli. I modelli precedenti su Vertex AI non accettano l’intestazione beta richiesta e le richieste non riescono se abiliti la ricerca degli strumenti con essi.

​
5. Fissa le versioni del modello

Fissa versioni specifiche del modello quando distribuisci a più utenti. Senza fissaggio, gli alias di modello come sonnet e opus si risolvono nella versione più recente, che potrebbe non essere ancora abilitata nel tuo progetto Vertex AI quando Anthropic rilascia un aggiornamento. Claude Code ritorna alla versione precedente all’avvio quando la versione più recente non è disponibile, ma il fissaggio ti consente di controllare quando i tuoi utenti passano a un nuovo 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 modelloValore predefinito
Modello primarioclaude-sonnet-4-5@20250929
Modello piccolo/veloceUguale al modello primario
Le attività in background come la generazione del titolo della sessione utilizzano il modello piccolo/veloce, normalmente un modello della classe Haiku. Su Vertex AI, Claude Code imposta per impostazione predefinita questo al modello primario perché Haiku potrebbe non essere abilitato in ogni progetto o regione. Per utilizzare Haiku per le attività in background, imposta ANTHROPIC_DEFAULT_HAIKU_MODEL su un ID modello disponibile nel tuo progetto. 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:
  • aiplatform.endpoints.predict - Richiesto per l’invocazione del modello e il conteggio dei token
Per autorizzazioni più restrittive, crea un ruolo personalizzato con solo le autorizzazioni di cui sopra. Per i dettagli, consulta la documentazione IAM di Vertex.
Crea un progetto GCP dedicato per Claude Code per semplificare il tracciamento dei costi e il controllo degli accessi.

​
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”:
  • Esegui gcloud auth application-default login per configurare le credenziali predefinite dell’applicazione
  • Imposta GOOGLE_APPLICATION_CREDENTIALS su un percorso di file della chiave dell’account di servizio
  • Vedi Configure GCP credentials per tutte le opzioni
Se riscontri problemi di quota:
  • Controlla le quote attuali o richiedi un aumento della quota tramite Cloud Console
Se riscontri errori “model not found” 404:
  • Conferma che il modello è abilitato in Model Garden
  • Verifica che il modello sia disponibile nella posizione che hai specificato. Alcuni modelli sono offerti solo su posizioni global o multi-regione come eu e us, non in regioni specifiche
  • Se utilizzi CLOUD_ML_REGION=global, controlla che i tuoi modelli supportino endpoint globali in Model Garden in “Supported features”. Per i modelli che non supportano endpoint globali, puoi:
    • Specificare un modello supportato tramite ANTHROPIC_MODEL o ANTHROPIC_DEFAULT_HAIKU_MODEL, oppure
    • Impostare una regione o una posizione multi-regione utilizzando le variabili di ambiente VERTEX_REGION_<MODEL_NAME>
Se riscontri errori 429:
  • Per gli endpoint regionali, assicurati che il modello primario e il modello piccolo/veloce siano supportati nella tua regione selezionata
  • Considera di passare a CLOUD_ML_REGION=global per una migliore disponibilità

​
Risorse aggiuntive