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

Vertex AI potrebbe non supportare i modelli predefiniti di Claude Code su regioni diverse da us-east5. Assicurati di utilizzare us-east5 e di avere quota allocata, oppure passa a modelli supportati.

​
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 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 esempio, 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 Google Cloud.

​
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=us-east5
export ANTHROPIC_VERTEX_PROJECT_ID=YOUR-PROJECT-ID

# Opzionale: Disabilita il caching dei prompt se necessario
export DISABLE_PROMPT_CACHING=1

# Opzionale: Sovrascrivi le regioni per modelli specifici
export VERTEX_REGION_CLAUDE_3_5_HAIKU=us-central1
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-west4
export VERTEX_REGION_CLAUDE_4_0_SONNET=us-east5
export VERTEX_REGION_CLAUDE_4_1_OPUS=europe-west4

Il caching dei prompt è supportato automaticamente quando specifichi il flag effimero cache_control. Per disabilitarlo, imposta DISABLE_PROMPT_CACHING=1. Per limiti di velocità elevati, contatta il supporto Google Cloud.

Quando utilizzi Vertex AI, i comandi /login e /logout sono disabilitati poiché l’autenticazione è gestita tramite le credenziali 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 i 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.

​
Risoluzione dei problemi

Se riscontri problemi di quota:

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

Se riscontri errori 404 “modello non trovato”:

  • Verifica di avere accesso alla regione specificata
  • Conferma che il modello sia Abilitato nel Model Garden

Se riscontri errori 429:

  • Assicurati che il modello primario e il modello piccolo/veloce siano supportati nella tua regione selezionata

​
Risorse aggiuntive