​
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 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 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 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 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 prompt caching se necessario
export DISABLE_PROMPT_CACHING=1

# Opzionale: Sovrascrivi 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 Prompt caching è automaticamente supportato quando specifichi il flag effimero cache_control. Per disabilitarlo, 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 tracciamento 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 regione selezionata

​
Risorse aggiuntive