​
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 es. Claude Sonnet 4.5)
  • Google Cloud SDK (gcloud) installato e configurato
  • Quota allocata nella regione GCP desiderata

​
Configurazione della regione

Claude Code può essere utilizzato sia con endpoint globali che regionali di Vertex AI.
Vertex AI potrebbe non supportare i modelli predefiniti di Claude Code in tutte le regioni. Potrebbe essere necessario passare a una regione o modello supportato.
Vertex AI potrebbe non supportare i modelli predefiniti di Claude Code su endpoint globali. Potrebbe essere necessario passare a un endpoint regionale o a un modello supportato.

​
Configurazione

​
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 es. Claude Sonnet 4.5)
  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.
Durante l’autenticazione, Claude Code utilizzerà automaticamente l’ID progetto dalla variabile di ambiente ANTHROPIC_VERTEX_PROJECT_ID. Per eseguire l’override, imposta una di queste variabili di ambiente: GCLOUD_PROJECT, GOOGLE_CLOUD_PROJECT o GOOGLE_APPLICATION_CREDENTIALS.

​
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: Disabilita la memorizzazione nella cache dei prompt se necessario
export DISABLE_PROMPT_CACHING=1

# Quando CLOUD_ML_REGION=global, esegui l'override della regione per i modelli non supportati
export VERTEX_REGION_CLAUDE_3_5_HAIKU=us-east5

# Facoltativo: Esegui l'override delle regioni per altri modelli specifici
export VERTEX_REGION_CLAUDE_3_5_SONNET=us-east5
export VERTEX_REGION_CLAUDE_3_7_SONNET=us-east5
export VERTEX_REGION_CLAUDE_4_0_OPUS=europe-west1
export VERTEX_REGION_CLAUDE_4_0_SONNET=us-east5
export VERTEX_REGION_CLAUDE_4_1_OPUS=europe-west1
La memorizzazione nella cache dei prompt è supportata automaticamente quando specifichi il flag effimero cache_control. Per disabilitarla, imposta DISABLE_PROMPT_CACHING=1. Per limiti di velocità aumentati, contatta il supporto di Google Cloud.
Quando si utilizza Vertex AI, i comandi /login e /logout sono disabilitati poiché l’autenticazione viene gestita tramite le credenziali di Google Cloud.

​
5. Configurazione del modello

Claude Code utilizza questi modelli predefiniti per Vertex AI:
Tipo di modelloValore predefinito
Modello primarioclaude-sonnet-4-5@20250929
Modello piccolo/veloceclaude-haiku-4-5@20251001
Per gli utenti di Vertex AI, Claude Code non eseguirà automaticamente l’aggiornamento da Haiku 3.5 a Haiku 4.5. Per passare manualmente a un modello Haiku più recente, imposta la variabile di ambiente ANTHROPIC_DEFAULT_HAIKU_MODEL sul nome completo del modello (ad es. claude-haiku-4-5@20251001).
Per personalizzare i modelli: 
export ANTHROPIC_MODEL='claude-opus-4-1@20250805'
export ANTHROPIC_SMALL_FAST_MODEL='claude-haiku-4-5@20251001'

​
Configurazione IAM

Assegna i permessi IAM richiesti: Il ruolo roles/aiplatform.user include i permessi richiesti:
  • aiplatform.endpoints.predict - Richiesto per l’invocazione del modello e il conteggio dei token
Per permessi più restrittivi, crea un ruolo personalizzato con solo i permessi di cui sopra. Per i dettagli, consulta la documentazione IAM di Vertex.
Consigliamo di creare 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 Sonnet 4 e Sonnet 4.5 supportano la finestra di contesto da 1M token su Vertex AI.
La finestra di contesto da 1M token è attualmente in versione beta. Per utilizzare la finestra di contesto estesa, includi l’intestazione beta context-1m-2025-08-07 nelle tue richieste Vertex AI.

​
Risoluzione dei problemi

Se riscontri problemi di quota:
  • Controlla le quote attuali o richiedi un aumento della quota tramite Cloud Console
Se riscontri errori “modello non trovato” 404:
  • Conferma che il modello sia abilitato in Model Garden
  • Verifica di avere accesso alla regione specificata
  • Se utilizzi CLOUD_ML_REGION=global, verifica che i tuoi modelli supportino endpoint globali in Model Garden in “Funzionalità supportate”. Per i modelli che non supportano endpoint globali, puoi:
    • Specificare un modello supportato tramite ANTHROPIC_MODEL o ANTHROPIC_SMALL_FAST_MODEL, oppure
    • Impostare un endpoint regionale 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 regione selezionata
  • Considera di passare a CLOUD_ML_REGION=global per una migliore disponibilità

​
Risorse aggiuntive