​
Voraussetzungen

Bevor Sie Claude Code mit Vertex AI konfigurieren, stellen Sie sicher, dass Sie Folgendes haben:

  • Ein Google Cloud Platform (GCP) Konto mit aktivierter Abrechnung
  • Ein GCP-Projekt mit aktivierter Vertex AI API
  • Zugang zu gewünschten Claude-Modellen (z.B. Claude Sonnet 4)
  • Google Cloud SDK (gcloud) installiert und konfiguriert
  • Kontingent in der gewünschten GCP-Region zugewiesen

​
Regionskonfiguration

Claude Code kann sowohl mit Vertex AI globalen als auch regionalen Endpunkten verwendet werden.

Vertex AI unterstützt möglicherweise nicht die Claude Code Standard-Modelle in allen Regionen. Sie müssen möglicherweise zu einer unterstützten Region oder einem unterstützten Modell wechseln.

Vertex AI unterstützt möglicherweise nicht die Claude Code Standard-Modelle auf globalen Endpunkten. Sie müssen möglicherweise zu einem regionalen Endpunkt oder einem unterstützten Modell wechseln.

​
Setup

​
1. Vertex AI API aktivieren

Aktivieren Sie die Vertex AI API in Ihrem GCP-Projekt:

# Setzen Sie Ihre Projekt-ID
gcloud config set project YOUR-PROJECT-ID

# Vertex AI API aktivieren
gcloud services enable aiplatform.googleapis.com

​
2. Modellzugang anfordern

Fordern Sie Zugang zu Claude-Modellen in Vertex AI an:

  1. Navigieren Sie zum Vertex AI Model Garden
  2. Suchen Sie nach “Claude”-Modellen
  3. Fordern Sie Zugang zu gewünschten Claude-Modellen an (z.B. Claude Sonnet 4)
  4. Warten Sie auf die Genehmigung (kann 24-48 Stunden dauern)

​
3. GCP-Anmeldedaten konfigurieren

Claude Code verwendet die Standard-Google Cloud-Authentifizierung.

Weitere Informationen finden Sie in der Google Cloud-Authentifizierungsdokumentation.

Bei der Authentifizierung verwendet Claude Code automatisch die Projekt-ID aus der Umgebungsvariable ANTHROPIC_VERTEX_PROJECT_ID. Um dies zu überschreiben, setzen Sie eine dieser Umgebungsvariablen: GCLOUD_PROJECT, GOOGLE_CLOUD_PROJECT oder GOOGLE_APPLICATION_CREDENTIALS.

​
4. Claude Code konfigurieren

Setzen Sie die folgenden Umgebungsvariablen:

# Vertex AI Integration aktivieren
export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=global
export ANTHROPIC_VERTEX_PROJECT_ID=YOUR-PROJECT-ID

# Optional: Prompt-Caching deaktivieren falls erforderlich
export DISABLE_PROMPT_CACHING=1

# Wenn CLOUD_ML_REGION=global, Region für nicht unterstützte Modelle überschreiben
export VERTEX_REGION_CLAUDE_3_5_HAIKU=us-east5

# Optional: Regionen für andere spezifische Modelle überschreiben
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

Prompt-Caching wird automatisch unterstützt, wenn Sie das cache_control ephemeral Flag angeben. Um es zu deaktivieren, setzen Sie DISABLE_PROMPT_CACHING=1. Für erhöhte Rate-Limits wenden Sie sich an den Google Cloud Support.

Bei der Verwendung von Vertex AI sind die /login und /logout Befehle deaktiviert, da die Authentifizierung über Google Cloud-Anmeldedaten abgewickelt wird.

​
5. Modellkonfiguration

Claude Code verwendet diese Standard-Modelle für Vertex AI:

ModelltypStandardwert
Primäres Modellclaude-sonnet-4@20250514
Kleines/schnelles Modellclaude-3-5-haiku@20241022

Um Modelle anzupassen:

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

​
IAM-Konfiguration

Weisen Sie die erforderlichen IAM-Berechtigungen zu:

Die Rolle roles/aiplatform.user umfasst die erforderlichen Berechtigungen:

  • aiplatform.endpoints.predict - Erforderlich für Modellaufruf
  • aiplatform.endpoints.computeTokens - Erforderlich für Token-Zählung

Für restriktivere Berechtigungen erstellen Sie eine benutzerdefinierte Rolle mit nur den oben genannten Berechtigungen.

Details finden Sie in der Vertex IAM-Dokumentation.

Wir empfehlen, ein dediziertes GCP-Projekt für Claude Code zu erstellen, um die Kostenverfolgung und Zugriffskontrolle zu vereinfachen.

​
1M Token Kontextfenster

Claude Sonnet 4 unterstützt das 1M Token Kontextfenster auf Vertex AI.

Das 1M Token Kontextfenster befindet sich derzeit in der Beta-Phase. Um das erweiterte Kontextfenster zu verwenden, fügen Sie den context-1m-2025-08-07 Beta-Header in Ihre Vertex AI-Anfragen ein.

​
Fehlerbehebung

Wenn Sie Kontingentprobleme haben:

  • Überprüfen Sie aktuelle Kontingente oder fordern Sie eine Kontingenterhöhung über die Cloud Console an

Wenn Sie “model not found” 404-Fehler haben:

  • Bestätigen Sie, dass das Modell im Model Garden aktiviert ist
  • Überprüfen Sie, ob Sie Zugang zur angegebenen Region haben
  • Wenn Sie CLOUD_ML_REGION=global verwenden, überprüfen Sie, ob Ihre Modelle globale Endpunkte im Model Garden unter “Unterstützte Funktionen” unterstützen. Für Modelle, die keine globalen Endpunkte unterstützen, entweder:
    • Geben Sie ein unterstütztes Modell über ANTHROPIC_MODEL oder ANTHROPIC_SMALL_FAST_MODEL an, oder
    • Setzen Sie einen regionalen Endpunkt mit VERTEX_REGION_<MODEL_NAME> Umgebungsvariablen

Wenn Sie 429-Fehler haben:

  • Für regionale Endpunkte stellen Sie sicher, dass das primäre Modell und das kleine/schnelle Modell in Ihrer ausgewählten Region unterstützt werden
  • Erwägen Sie den Wechsel zu CLOUD_ML_REGION=global für bessere Verfügbarkeit

​
Zusätzliche Ressourcen