​
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

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 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 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 non abilitato
export DISABLE_PROMPT_CACHING=1

Per limiti di velocità aumentati e abilitazione del caching dei prompt, contatta il supporto Google Cloud. Una volta abilitato, rimuovi l’impostazione DISABLE_PROMPT_CACHING.

​
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@20250514'
export ANTHROPIC_SMALL_FAST_MODEL='claude-3-5-haiku@20241022'

​
Configurazione IAM

Concedi i ruoli IAM richiesti per Claude Code.

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 in Model Garden

Se riscontri errori 429:

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

​
Risorse aggiuntive