​
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 API Vertex AI abilitata
  • Accesso ai modelli Claude desiderati (ad es., Claude Sonnet 4)
  • 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 su tutte le regioni. Potrebbe essere necessario passare a una regione o modello supportato.

Vertex AI potrebbe non supportare i modelli predefiniti di Claude Code sugli endpoint globali. Potrebbe essere necessario passare a un endpoint regionale o a un modello supportato.

​
Setup

​
1. Abilita l’API Vertex AI

Abilita l’API Vertex AI nel tuo progetto GCP:

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

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

​
2. Richiedi l’accesso al modello

Richiedi l’accesso ai modelli Claude in Vertex AI:

  1. Naviga al Vertex AI Model Garden
  2. Cerca i modelli “Claude”
  3. Richiedi l’accesso ai modelli Claude desiderati (ad es., Claude Sonnet 4)
  4. Attendi l’approvazione (potrebbe richiedere 24-48 ore)

​
3. Configura le credenziali GCP

Claude Code utilizza l’autenticazione standard di Google Cloud.

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

Durante l’autenticazione, Claude Code utilizzerà automaticamente l’ID progetto dalla variabile d’ambiente ANTHROPIC_VERTEX_PROJECT_ID. Per sovrascriverlo, imposta una di queste variabili d’ambiente: GCLOUD_PROJECT, GOOGLE_CLOUD_PROJECT, o GOOGLE_APPLICATION_CREDENTIALS.

​
4. Configura Claude Code

Imposta le seguenti variabili d’ambiente:

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

# Opzionale: Disabilita la cache dei prompt se necessario
export DISABLE_PROMPT_CACHING=1

# Quando CLOUD_ML_REGION=global, sovrascrivi la regione per modelli non supportati
export VERTEX_REGION_CLAUDE_3_5_HAIKU=us-east5

# Opzionale: Sovrascrivi le 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 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 utilizzi Vertex AI, i comandi /login e /logout sono disabilitati poiché l’autenticazione è 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@20250514
Modello piccolo/veloceclaude-3-5-haiku@20241022

Per personalizzare i modelli:

export ANTHROPIC_MODEL='claude-opus-4-1@20250805'
export ANTHROPIC_SMALL_FAST_MODEL='claude-3-5-haiku@20241022'

​
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
  • aiplatform.endpoints.computeTokens - Richiesto per il conteggio dei token

Per permessi più restrittivi, crea un ruolo personalizzato con solo i permessi sopra indicati.

Per dettagli, consulta la documentazione IAM di Vertex.

Raccomandiamo di creare un progetto GCP dedicato per Claude Code per semplificare il monitoraggio dei costi e il controllo degli accessi.

​
Finestra di contesto da 1M token

Claude Sonnet 4 supporta la finestra di contesto da 1M token su Vertex AI.

La finestra di contesto da 1M token è attualmente in beta. Per utilizzare la finestra di contesto estesa, includi l’header beta context-1m-2025-08-07 nelle tue richieste Vertex AI.

​
Risoluzione dei problemi

Se incontri problemi di quota:

  • Controlla le quote attuali o richiedi un aumento della quota tramite Cloud Console

Se incontri errori 404 “model not found”:

  • Conferma che il modello sia Abilitato in Model Garden
  • Verifica di avere accesso alla regione specificata
  • Se utilizzi CLOUD_ML_REGION=global, controlla che i tuoi modelli supportino gli endpoint globali in Model Garden sotto “Funzionalità supportate”. Per i modelli che non supportano gli endpoint globali, puoi:
    • Specificare un modello supportato tramite ANTHROPIC_MODEL o ANTHROPIC_SMALL_FAST_MODEL, oppure
    • Impostare un endpoint regionale utilizzando le variabili d’ambiente VERTEX_REGION_<MODEL_NAME>

Se incontri 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