​
Prérequis

Avant de configurer Claude Code avec Vertex AI, assurez-vous d’avoir :

  • Un compte Google Cloud Platform (GCP) avec facturation activée
  • Un projet GCP avec l’API Vertex AI activée
  • Accès aux modèles Claude souhaités (par exemple, Claude Sonnet 4)
  • Google Cloud SDK (gcloud) installé et configuré
  • Quota alloué dans la région GCP souhaitée

​
Configuration de région

Claude Code peut être utilisé avec les points de terminaison globaux et régionaux de Vertex AI.

Vertex AI peut ne pas prendre en charge les modèles par défaut de Claude Code sur toutes les régions. Vous devrez peut-être passer à une région ou modèle pris en charge.

Vertex AI peut ne pas prendre en charge les modèles par défaut de Claude Code sur les points de terminaison globaux. Vous devrez peut-être passer à un point de terminaison régional ou à un modèle pris en charge.

​
Configuration

​
1. Activer l’API Vertex AI

Activez l’API Vertex AI dans votre projet GCP :

# Définir votre ID de projet
gcloud config set project YOUR-PROJECT-ID

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

​
2. Demander l’accès au modèle

Demandez l’accès aux modèles Claude dans Vertex AI :

  1. Naviguez vers le Jardin de modèles Vertex AI
  2. Recherchez les modèles “Claude”
  3. Demandez l’accès aux modèles Claude souhaités (par exemple, Claude Sonnet 4)
  4. Attendez l’approbation (peut prendre 24-48 heures)

​
3. Configurer les identifiants GCP

Claude Code utilise l’authentification Google Cloud standard.

Pour plus d’informations, consultez la documentation d’authentification Google Cloud.

Lors de l’authentification, Claude Code utilisera automatiquement l’ID de projet de la variable d’environnement ANTHROPIC_VERTEX_PROJECT_ID. Pour remplacer cela, définissez l’une de ces variables d’environnement : GCLOUD_PROJECT, GOOGLE_CLOUD_PROJECT, ou GOOGLE_APPLICATION_CREDENTIALS.

​
4. Configurer Claude Code

Définissez les variables d’environnement suivantes :

# Activer l'intégration Vertex AI
export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=global
export ANTHROPIC_VERTEX_PROJECT_ID=YOUR-PROJECT-ID

# Optionnel : Désactiver la mise en cache des invites si nécessaire
export DISABLE_PROMPT_CACHING=1

# Quand CLOUD_ML_REGION=global, remplacer la région pour les modèles non pris en charge
export VERTEX_REGION_CLAUDE_3_5_HAIKU=us-east5

# Optionnel : Remplacer les régions pour d'autres modèles spécifiques
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 mise en cache des invites est automatiquement prise en charge lorsque vous spécifiez le drapeau éphémère cache_control. Pour la désactiver, définissez DISABLE_PROMPT_CACHING=1. Pour des limites de taux accrues, contactez le support Google Cloud.

Lors de l’utilisation de Vertex AI, les commandes /login et /logout sont désactivées car l’authentification est gérée via les identifiants Google Cloud.

​
5. Configuration du modèle

Claude Code utilise ces modèles par défaut pour Vertex AI :

Type de modèleValeur par défaut
Modèle principalclaude-sonnet-4@20250514
Modèle petit/rapideclaude-3-5-haiku@20241022

Pour personnaliser les modèles :

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

​
Configuration IAM

Attribuez les permissions IAM requises :

Le rôle roles/aiplatform.user inclut les permissions requises :

  • aiplatform.endpoints.predict - Requis pour l’invocation du modèle
  • aiplatform.endpoints.computeTokens - Requis pour le comptage des jetons

Pour des permissions plus restrictives, créez un rôle personnalisé avec seulement les permissions ci-dessus.

Pour plus de détails, consultez la documentation IAM Vertex.

Nous recommandons de créer un projet GCP dédié pour Claude Code afin de simplifier le suivi des coûts et le contrôle d’accès.

​
Fenêtre de contexte de 1M de jetons

Claude Sonnet 4 prend en charge la fenêtre de contexte de 1M de jetons sur Vertex AI.

La fenêtre de contexte de 1M de jetons est actuellement en version bêta. Pour utiliser la fenêtre de contexte étendue, incluez l’en-tête bêta context-1m-2025-08-07 dans vos requêtes Vertex AI.

​
Dépannage

Si vous rencontrez des problèmes de quota :

  • Vérifiez les quotas actuels ou demandez une augmentation de quota via la Console Cloud

Si vous rencontrez des erreurs 404 “modèle non trouvé” :

  • Confirmez que le modèle est Activé dans le Jardin de modèles
  • Vérifiez que vous avez accès à la région spécifiée
  • Si vous utilisez CLOUD_ML_REGION=global, vérifiez que vos modèles prennent en charge les points de terminaison globaux dans le Jardin de modèles sous “Fonctionnalités prises en charge”. Pour les modèles qui ne prennent pas en charge les points de terminaison globaux, soit :
    • Spécifiez un modèle pris en charge via ANTHROPIC_MODEL ou ANTHROPIC_SMALL_FAST_MODEL, ou
    • Définissez un point de terminaison régional en utilisant les variables d’environnement VERTEX_REGION_<MODEL_NAME>

Si vous rencontrez des erreurs 429 :

  • Pour les points de terminaison régionaux, assurez-vous que le modèle principal et le modèle petit/rapide sont pris en charge dans votre région sélectionnée
  • Envisagez de passer à CLOUD_ML_REGION=global pour une meilleure disponibilité

​
Ressources supplémentaires