SpyBara
Go Premium

google-vertex-ai.md 2026-06-29 23:02 UTC to 2026-06-30 23:02 UTC

2 added, 2 removed.

2026
Tue 30 23:02 Mon 29 23:02 Sat 27 01:01 Fri 26 23:00 Thu 25 23:58 Wed 24 22:02 Tue 23 22:00 Mon 22 23:59 Fri 19 22:58 Thu 18 22:00 Wed 17 17:02 Tue 16 21:57 Mon 15 23:02 Sat 13 21:59 Fri 12 22:00 Thu 11 23:01 Wed 10 23:57 Tue 9 06:34 Mon 8 06:52 Sat 6 06:24 Fri 5 06:45 Thu 4 06:52 Wed 3 06:53 Tue 2 06:51

Claude Code di Google Vertex AI

Pelajari tentang mengonfigurasi Claude Code melalui Google Vertex AI, termasuk pengaturan, konfigurasi IAM, dan pemecahan masalah.

export const ContactSalesCard = ({surface}) => { const utm = content => utm_source=claude_code&utm_medium=docs&utm_content=${surface}_${content}; const iconArrowRight = (size = 13) => <svg width={size} height={size} viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2.5" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true"> ; const STYLES = .cc-cs { --cs-slate: #141413; --cs-clay: #d97757; --cs-clay-deep: #c6613f; --cs-gray-000: #ffffff; --cs-gray-700: #3d3d3a; --cs-border-default: rgba(31, 30, 29, 0.15); font-family: inherit; } .dark .cc-cs { --cs-slate: #f0eee6; --cs-gray-000: #262624; --cs-gray-700: #bfbdb4; --cs-border-default: rgba(240, 238, 230, 0.14); } .cc-cs-card { display: flex; align-items: center; justify-content: space-between; gap: 16px; padding: 14px 16px; margin: 0; background: var(--cs-gray-000); border: 0.5px solid var(--cs-border-default); border-radius: 8px; flex-wrap: wrap; } .cc-cs-text { font-size: 13px; color: var(--cs-gray-700); line-height: 1.5; flex: 1; min-width: 240px; } .cc-cs-text strong { font-weight: 550; color: var(--cs-slate); } .cc-cs-actions { display: flex; align-items: center; gap: 8px; flex-shrink: 0; } .cc-cs-btn-clay { display: inline-flex; align-items: center; gap: 8px; background: var(--cs-clay-deep); color: #fff; border: none; border-radius: 8px; padding: 8px 14px; font-size: 13px; font-weight: 500; transition: background-color 0.15s; white-space: nowrap; } .cc-cs-btn-clay:hover { background: var(--cs-clay); } .cc-cs-btn-ghost { display: inline-flex; align-items: center; gap: 8px; background: transparent; color: var(--cs-gray-700); border: 0.5px solid var(--cs-border-default); border-radius: 8px; padding: 8px 14px; font-size: 13px; font-weight: 500; } .cc-cs-btn-ghost:hover { background: rgba(0, 0, 0, 0.04); } .dark .cc-cs-btn-ghost:hover { background: rgba(255, 255, 255, 0.04); } @media (max-width: 720px) { .cc-cs-actions { width: 100%; } }; return <div className="cc-cs not-prose"> <div className="cc-cs-card"> <div className="cc-cs-text"> Deploying Claude Code across your organization? Talk to sales about enterprise plans, SSO, and centralized billing.

<div className="cc-cs-actions"> <a href={https://claude.com/pricing?${utm('view_plans')}#plans-business} className="cc-cs-btn-ghost"> View plans <a href={https://claude.com/contact-sales?${utm('contact_sales')}} className="cc-cs-btn-clay"> Contact sales {iconArrowRight()}
; };

Prasyarat

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

Untuk masuk dengan kredensial Vertex AI Anda sendiri, ikuti Masuk dengan Vertex AI di bawah. Untuk menerapkan Claude Code di seluruh tim, gunakan langkah pengaturan manual dan pin versi model Anda sebelum melakukan peluncuran.

Masuk dengan Vertex AI

Jika Anda memiliki kredensial Google Cloud dan ingin mulai menggunakan Claude Code melalui Vertex AI, wizard login akan memandu Anda. Anda menyelesaikan prasyarat sisi GCP sekali per proyek; wizard menangani sisi Claude Code.

1

Aktifkan model Claude di proyek GCP Anda

Aktifkan Vertex AI API untuk proyek Anda, kemudian minta akses ke model Claude yang Anda inginkan di Vertex AI Model Garden. Lihat konfigurasi IAM untuk izin yang akun Anda butuhkan.

2

Mulai Claude Code dan pilih Vertex AI

Jalankan claude. Pada prompt login, pilih 3rd-party platform, kemudian Google Vertex AI.

3

Ikuti prompt wizard

Pilih cara Anda melakukan autentikasi ke Google Cloud: Application Default Credentials dari gcloud, file kunci akun layanan, atau kredensial yang sudah ada di lingkungan Anda. Wizard mendeteksi proyek dan wilayah Anda, memverifikasi model Claude mana yang dapat dijalankan proyek Anda, dan memungkinkan Anda untuk mempinnya. Ini menyimpan hasilnya ke blok env dari file pengaturan pengguna Anda, jadi Anda tidak perlu mengekspor variabel lingkungan sendiri.

Setelah Anda masuk, jalankan /setup-vertex kapan saja untuk membuka kembali wizard dan mengubah kredensial, proyek, wilayah, atau pin model Anda.

Konfigurasi wilayah

Claude Code mendukung Vertex AI global, multi-region, dan titik akhir regional. Atur CLOUD_ML_REGION ke global, lokasi multi-region seperti eu atau us, atau wilayah spesifik seperti us-east5. Claude Code memilih nama host Vertex AI yang benar untuk setiap bentuk, termasuk host aiplatform.eu.rep.googleapis.com dan aiplatform.us.rep.googleapis.com untuk lokasi multi-region.

Pengaturan manual

Untuk mengonfigurasi Vertex AI melalui variabel lingkungan alih-alih wizard, misalnya di CI atau peluncuran perusahaan yang ditulis skrip, ikuti langkah-langkah di bawah.

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. Navigasikan ke Vertex AI Model Garden
  2. Cari model "Claude"
  3. Minta akses ke model Claude yang diinginkan (misalnya, Claude Sonnet 4.6)
  4. Tunggu persetujuan (mungkin memakan waktu 24-48 jam)

3) Konfigurasi kredensial GCP

Claude Code menggunakan autentikasi Google Cloud standar.

Untuk informasi lebih lanjut, lihat dokumentasi autentikasi Google Cloud.

Claude Code v2.1.121 atau lebih baru mendukung Workload Identity Federation berbasis sertifikat X.509 melalui rantai Application Default Credentials yang sama. Atur GOOGLE_APPLICATION_CREDENTIALS ke jalur file konfigurasi kredensial Anda.

Konfigurasi kredensial lanjutan

Claude Code mendukung penyegaran kredensial otomatis untuk GCP melalui pengaturan gcpAuthRefresh. Ketika Claude Code mendeteksi bahwa kredensial GCP Anda telah kedaluwarsa atau tidak dapat dimuat, Claude Code menjalankan perintah yang dikonfigurasi untuk mendapatkan kredensial baru sebelum mencoba ulang permintaan.

{
  "gcpAuthRefresh": "gcloud auth application-default login",
  "env": {
    "ANTHROPIC_VERTEX_PROJECT_ID": "your-project-id"
  }
}

Output perintah ditampilkan kepada pengguna, tetapi input interaktif tidak didukung. Ini berfungsi dengan baik untuk alur autentikasi berbasis browser di mana CLI menampilkan URL dan Anda menyelesaikan autentikasi di browser. Perintah penyegaran habis waktu setelah tiga menit jika autentikasi tidak selesai. Jika Anda mengatur gcpAuthRefresh dalam pengaturan proyek seperti .claude/settings.json, perintah hanya berjalan setelah Anda menerima prompt kepercayaan ruang kerja.

4. Konfigurasi Claude Code

Atur variabel lingkungan berikut:

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

# Opsional: Timpa URL titik akhir Vertex untuk titik akhir kustom atau gateway
# export ANTHROPIC_VERTEX_BASE_URL=https://aiplatform.googleapis.com

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

# Opsional: Minta TTL cache prompt 1 jam alih-alih default 5 menit
export ENABLE_PROMPT_CACHING_1H=1

# Ketika CLOUD_ML_REGION=global, timpa wilayah untuk model yang tidak mendukung titik akhir global
export VERTEX_REGION_CLAUDE_HAIKU_4_5=us-east5
export VERTEX_REGION_CLAUDE_4_6_SONNET=europe-west1

Sebagian besar versi model memiliki variabel VERTEX_REGION_CLAUDE_* yang sesuai. Lihat referensi variabel lingkungan untuk daftar lengkap. Periksa Vertex Model Garden untuk menentukan model mana yang mendukung titik akhir global versus regional saja.

Prompt caching diaktifkan secara otomatis. Untuk menonaktifkannya, atur DISABLE_PROMPT_CACHING=1. Untuk meminta TTL cache 1 jam alih-alih default 5 menit, atur ENABLE_PROMPT_CACHING_1H=1; penulisan cache dengan TTL 1 jam ditagih dengan tarif yang lebih tinggi. Untuk batas laju yang lebih tinggi, hubungi dukungan Google Cloud. Saat menggunakan Vertex AI, perintah /logout tidak tersedia karena autentikasi ditangani melalui kredensial Google Cloud.

Claude Code menonaktifkan pencarian alat MCP secara default di Vertex AI, sehingga definisi alat MCP dimuat di muka. Vertex AI mendukung pencarian alat untuk Claude Sonnet 4.5 dan lebih baru serta Claude Opus 4.5 dan lebih baru. Atur ENABLE_TOOL_SEARCH=true untuk mengaktifkannya pada model tersebut. Model sebelumnya di Vertex AI tidak menerima header beta yang diperlukan, dan permintaan gagal jika Anda mengaktifkan pencarian alat dengan model tersebut.

5. Pin versi model

Atur variabel lingkungan ini ke ID model Vertex AI spesifik.

Tanpa ANTHROPIC_DEFAULT_OPUS_MODEL, alias opus di Vertex diselesaikan ke Opus 4.6. Aturnya ke ID Opus 4.8 untuk menggunakan model terbaru:

export ANTHROPIC_DEFAULT_OPUS_MODEL='claude-opus-4-8'
export ANTHROPIC_DEFAULT_SONNET_MODEL='claude-sonnet-5'
export ANTHROPIC_DEFAULT_HAIKU_MODEL='claude-haiku-4-5@20251001'

Untuk ID model saat ini dan warisan, lihat Ikhtisar Model. Lihat Konfigurasi Model untuk daftar lengkap variabel lingkungan.

Claude Code menggunakan model default ini ketika tidak ada variabel pinning yang diatur:

Jenis model Nilai default
Model utama claude-sonnet-4-5@20250929
Model kecil/cepat Sama dengan model utama

Tugas latar belakang seperti pembuatan judul sesi menggunakan model kecil/cepat, biasanya model kelas Haiku. Di Vertex AI, Claude Code menganggap default ini ke model utama karena Haiku mungkin tidak diaktifkan di setiap proyek atau wilayah. Untuk menggunakan Haiku untuk tugas latar belakang, atur ANTHROPIC_DEFAULT_HAIKU_MODEL ke ID model yang tersedia di proyek Anda.

Untuk menyesuaikan model lebih lanjut:

export ANTHROPIC_MODEL='claude-opus-4-8'
export ANTHROPIC_DEFAULT_HAIKU_MODEL='claude-haiku-4-5@20251001'

Pemeriksaan model startup

Ketika Claude Code dimulai dengan Vertex AI dikonfigurasi, ia memverifikasi bahwa model yang dimaksudkan untuk digunakan dapat diakses di proyek Anda. Pemeriksaan ini memerlukan Claude Code v2.1.98 atau lebih baru.

Jika Anda telah mempinkan versi model yang lebih lama dari default Claude Code saat ini, dan proyek Anda dapat memanggil versi yang lebih baru, Claude Code meminta Anda untuk memperbarui pin. Menerima menulis ID model baru ke file pengaturan pengguna Anda dan memulai ulang Claude Code. Menolak diingat sampai perubahan versi default berikutnya.

Jika Anda belum mempinkan model dan default saat ini tidak tersedia di proyek Anda, Claude Code kembali ke versi sebelumnya untuk sesi saat ini dan menampilkan pemberitahuan. Fallback tidak disimpan. Aktifkan model yang lebih baru di Model Garden atau pin versi untuk membuat pilihan permanen.

Konfigurasi IAM

Tetapkan izin IAM yang diperlukan:

Peran roles/aiplatform.user mencakup izin yang diperlukan:

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

Untuk detail, lihat dokumentasi Vertex IAM.

Jendela konteks token 1M

Claude Sonnet 5, Opus 4.6 dan yang lebih baru, serta Sonnet 4.6 mendukung jendela konteks token 1M di Vertex AI. Sonnet 5 selalu berjalan dengan jendela 1M, tanpa varian [1m] untuk dipilih. Untuk model lainnya, Claude Code secara otomatis mengaktifkan jendela konteks yang diperluas ketika Anda memilih varian model 1M.

Wizard pengaturan menawarkan opsi konteks 1M ketika mempinkan model. Untuk mengaktifkannya untuk model yang dipinkan secara manual, tambahkan [1m] ke ID model. Lihat Pin models for third-party deployments untuk detail.

Pemecahan masalah

Jika Anda mengalami kesalahan "Could not load the default credentials":

Jika Anda mengalami masalah kuota:

Jika Anda mengalami kesalahan "model not found" 404:

Jika Anda mengalami kesalahan 429:

Sumber daya tambahan