​
Prasyarat

Sebelum mengonfigurasi Claude Code dengan Vertex AI, pastikan Anda memiliki:

  • Akun Google Cloud Platform (GCP) dengan penagihan diaktifkan
  • Proyek GCP dengan Vertex AI API diaktifkan
  • Akses ke model Claude yang diinginkan (misalnya, Claude Sonnet 4)
  • Google Cloud SDK (gcloud) terinstal dan dikonfigurasi
  • Kuota dialokasikan di wilayah GCP yang diinginkan

Vertex AI mungkin tidak mendukung model default Claude Code di wilayah non-us-east5. Pastikan Anda menggunakan us-east5 dan memiliki kuota yang dialokasikan, atau beralih ke model yang didukung.

​
Pengaturan

​
1. Aktifkan Vertex AI API

Aktifkan Vertex AI API di proyek GCP Anda:

# Atur ID proyek Anda
gcloud config set project YOUR-PROJECT-ID

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

​
2. Minta akses model

Minta akses ke model Claude di Vertex AI:

  1. Navigasi ke Vertex AI Model Garden
  2. Cari model “Claude”
  3. Minta akses ke model Claude yang diinginkan (misalnya, Claude Sonnet 4)
  4. Tunggu persetujuan (mungkin memerlukan 24-48 jam)

​
3. Konfigurasi kredensial GCP

Claude Code menggunakan autentikasi Google Cloud standar.

Untuk informasi lebih lanjut, lihat dokumentasi autentikasi Google Cloud.

Saat melakukan autentikasi, Claude Code akan secara otomatis menggunakan ID proyek dari variabel lingkungan ANTHROPIC_VERTEX_PROJECT_ID. Untuk mengganti ini, atur salah satu dari variabel lingkungan berikut: GCLOUD_PROJECT, GOOGLE_CLOUD_PROJECT, atau GOOGLE_APPLICATION_CREDENTIALS.

​
4. Konfigurasi Claude Code

Atur variabel lingkungan berikut:

# Aktifkan integrasi Vertex AI
export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=us-east5
export ANTHROPIC_VERTEX_PROJECT_ID=YOUR-PROJECT-ID

# Opsional: Nonaktifkan prompt caching jika diperlukan
export DISABLE_PROMPT_CACHING=1

# Opsional: Ganti wilayah untuk model tertentu
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

Prompt caching secara otomatis didukung ketika Anda menentukan flag ephemeral cache_control. Untuk menonaktifkannya, atur DISABLE_PROMPT_CACHING=1. Untuk batas tingkat yang lebih tinggi, hubungi dukungan Google Cloud.

Saat menggunakan Vertex AI, perintah /login dan /logout dinonaktifkan karena autentikasi ditangani melalui kredensial Google Cloud.

​
5. Konfigurasi model

Claude Code menggunakan model default berikut untuk Vertex AI:

Jenis modelNilai default
Model utamaclaude-sonnet-4@20250514
Model kecil/cepatclaude-3-5-haiku@20241022

Untuk menyesuaikan model:

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

​
Konfigurasi IAM

Tetapkan izin IAM yang diperlukan:

Peran roles/aiplatform.user mencakup izin yang diperlukan:

  • aiplatform.endpoints.predict - Diperlukan untuk pemanggilan model
  • aiplatform.endpoints.computeTokens - Diperlukan untuk penghitungan token

Untuk izin yang lebih ketat, buat peran kustom dengan hanya izin di atas.

Untuk detail, lihat dokumentasi Vertex IAM.

Kami merekomendasikan membuat proyek GCP khusus untuk Claude Code untuk menyederhanakan pelacakan biaya dan kontrol akses.

​
Pemecahan masalah

Jika Anda mengalami masalah kuota:

  • Periksa kuota saat ini atau minta peningkatan kuota melalui Cloud Console

Jika Anda mengalami kesalahan 404 “model not found”:

  • Verifikasi Anda memiliki akses ke wilayah yang ditentukan
  • Konfirmasi model Diaktifkan di Model Garden

Jika Anda mengalami kesalahan 429:

  • Pastikan model utama dan model kecil/cepat didukung di wilayah yang Anda pilih

​
Sumber daya tambahan