Struktur Objek Anthropic Vertex AI

LibreChat mendukung penggunaan model Anthropic Claude melalui Google Cloud Vertex AI. Hal ini memungkinkan Anda untuk menggunakan model Claude dengan infrastruktur, penagihan, dan kredensial Google Cloud yang sudah Anda miliki.

Untuk pengaturan cepat menggunakan variabel lingkungan, lihat panduan konfigurasi Anthropic

Manfaat

• Penagihan Terpadu: Gunakan akun penagihan Google Cloud Anda yang sudah ada
• Fitur Perusahaan: Akses fitur keamanan dan kepatuhan perusahaan Google Cloud
• Kepatuhan Regional: Terapkan di wilayah tertentu untuk memenuhi persyaratan residensi data
• Infrastruktur yang Ada: Manfaatkan akun layanan GCP dan kebijakan IAM Anda saat ini

Prasyarat

Sebelum mengonfigurasi Anthropic Vertex AI, pastikan Anda telah:

1. Google Cloud Project dengan Vertex AI API diaktifkan
2. Service Account dengan peran Vertex AI User (roles/aiplatform.user)
3. Model Claude diaktifkan di Vertex AI Model Garden Anda
4. Service Account Key (file JSON) yang telah diunduh dan dapat diakses oleh LibreChat

Contoh Konfigurasi

endpoints:
  anthropic:
    streamRate: 20
    titleModel: "claude-3.5-haiku"  # Use the visible model name (key from models config)

    vertex:
      region: "us-east5"
      # serviceKeyFile: "/path/to/service-account.json"  # Optional, defaults to api/data/auth.json
      # projectId: "${VERTEX_PROJECT_ID}"  # Optional, auto-detected from service key

      # Model mapping: visible name -> Vertex AI deployment name
      models:
        claude-opus-4.5:
          deploymentName: claude-opus-4-5@20251101
        claude-sonnet-4:
          deploymentName: claude-sonnet-4-20250514
        claude-3.7-sonnet:
          deploymentName: claude-3-7-sonnet-20250219
        claude-3.5-sonnet:
          deploymentName: claude-3-5-sonnet-v2@20241022
        claude-3.5-haiku:
          deploymentName: claude-3-5-haiku@20241022

Catatan: Endpoint Anthropic mendukung semua Shared Endpoint Settings, termasuk streamRate, titleModel, titleMethod, titlePrompt, titlePromptTemplate, dan titleEndpoint.

vertex

Objek vertex berisi semua opsi konfigurasi khusus Vertex AI.

region

Kunci:

Default: us-east5

Wilayah yang Tersedia:

• global (direkomendasikan untuk sebagian besar kasus penggunaan)
• us-east5
• us-central1
• europe-west1
• europe-west4
• asia-southeast1

Tip: Wilayah global direkomendasikan karena menyediakan perutean otomatis ke wilayah terdekat yang tersedia. Gunakan wilayah tertentu hanya jika Anda memiliki persyaratan residensi data.

Contoh:

region: "global"

projectId

Kunci:

Default: Terdeteksi otomatis dari file kunci layanan

Contoh:

projectId: "${GOOGLE_PROJECT_ID}"

serviceKeyFile

Kunci:

Default: api/data/auth.json (atau variabel lingkungan GOOGLE_SERVICE_KEY_FILE)

Contoh:

serviceKeyFile: "/etc/secrets/gcp-service-account.json"

models

Kolom models mendefinisikan model Claude yang tersedia dan memetakan nama yang mudah digunakan ke ID deployment Vertex AI. Ini bekerja dengan cara yang mirip dengan pemetaan model Azure OpenAI.

Opsi Format

Anda dapat mengonfigurasi model dengan tiga cara:

Opsi 1: Array Sederhana

Gunakan ID model Vertex AI yang sebenarnya secara langsung. ID ini akan ditampilkan apa adanya di UI:

models:
  - "claude-sonnet-4-20250514"
  - "claude-3-7-sonnet-20250219"
  - "claude-3-5-haiku@20241022"

Opsi 2: Objek dengan Nama Kustom (Direkomendasikan)

Petakan nama yang mudah digunakan ke nama deployment Vertex AI:

models:
  claude-opus-4.5:           # Visible in UI
    deploymentName: claude-opus-4-5@20251101  # Actual Vertex AI model ID
  claude-sonnet-4:
    deploymentName: claude-sonnet-4-20250514
  claude-3.5-haiku:
    deploymentName: claude-3-5-haiku@20241022

Opsi 3: Format Campuran dengan Default

Tetapkan nama deployment default dan gunakan nilai boolean untuk model yang mewarisinya:

deploymentName: claude-sonnet-4-20250514  # Default deployment
models:
  claude-sonnet-4: true  # Uses default deploymentName
  claude-3.5-haiku:
    deploymentName: claude-3-5-haiku@20241022  # Override for this model

Properti Objek Model

Contoh:

models:
  claude-sonnet-4:
    deploymentName: claude-sonnet-4-20250514

Alternatif Variabel Lingkungan

Untuk pengaturan yang lebih sederhana, Anda dapat mengonfigurasi Vertex AI menggunakan variabel lingkungan alih-alih YAML:

# Enable Vertex AI mode
ANTHROPIC_USE_VERTEX=true

# Vertex AI region (optional, defaults to us-east5)
ANTHROPIC_VERTEX_REGION=global

# Path to service account key (optional, defaults to api/data/auth.json)
GOOGLE_SERVICE_KEY_FILE=/path/to/service-account.json

Catatan: Saat menggunakan variabel lingkungan, pemetaan model tidak tersedia. Semua model Claude yang dikenal akan disertakan secara otomatis.

Contoh Lengkap

Pengaturan Dasar

Konfigurasi minimal menggunakan default (Vertex AI diaktifkan dengan adanya bagian vertex):

endpoints:
  anthropic:
    vertex:
      region: us-east5

Ini menggunakan:

• Wilayah: us-east5
• Kunci layanan: api/data/auth.json (atau variabel lingkungan GOOGLE_SERVICE_KEY_FILE)
• ID Proyek: Terdeteksi otomatis dari kunci layanan
• Model: Semua model Claude yang diketahui

Pengaturan Produksi dengan Model Mapping

Konfigurasi lengkap dengan nama model dan judul kustom:

endpoints:
  anthropic:
    streamRate: 20
    titleModel: "haiku"
    titleMethod: "completion"

    vertex:
      region: "global"
      serviceKeyFile: "${GOOGLE_SERVICE_KEY_FILE}"

      models:
        opus:
          deploymentName: claude-opus-4-5@20251101
        sonnet:
          deploymentName: claude-sonnet-4-20250514
        haiku:
          deploymentName: claude-3-5-haiku@20241022

Pengaturan Multi-Region

Anda hanya dapat mengonfigurasi satu region per deployment. Untuk kebutuhan multi-region, pertimbangkan untuk menggunakan instance LibreChat terpisah atau endpoint kustom.

Pemecahan Masalah

Kesalahan Umum

"Tidak dapat memuat kredensial default"

• Pastikan file kunci akun layanan ada di jalur yang ditentukan
• Periksa izin file (harus dapat dibaca oleh proses LibreChat)
• Pastikan file JSON valid dan tidak rusak

"Permission denied" atau "403 Forbidden"

• Verifikasi bahwa akun layanan memiliki peran Vertex AI User
• Pastikan model Claude diaktifkan di Vertex AI Model Garden Anda
• Pastikan akun layanan tersebut milik proyek yang benar

"Model not found"

• Periksa apakah ID model di deploymentName sudah benar
• Pastikan model tersedia di wilayah yang Anda pilih
• Pastikan model telah diaktifkan di Vertex AI Model Garden Anda

Masalah Wilayah

"Invalid region" atau "Region not supported"

• Gunakan salah satu wilayah yang didukung yang tercantum di atas
• Coba gunakan region global yang menyediakan perutean otomatis
• Periksa dokumentasi Google Cloud untuk daftar terbaru wilayah yang menyediakan Claude.

"Model tidak tersedia di wilayah ini"

• Tidak semua model Claude tersedia di semua wilayah
• Coba beralih ke region global untuk perutean otomatis ke region yang tersedia
• Periksa Vertex AI Model Garden untuk melihat model mana yang tersedia di wilayah Anda
• Pertimbangkan untuk menggunakan wilayah lain yang memiliki ketersediaan model yang lebih luas (contohnya, us-east5)

Masalah latensi

• Jika Anda mengalami latensi tinggi, cobalah menggunakan wilayah yang secara geografis lebih dekat dengan pengguna Anda
• Wilayah global secara otomatis mengarahkan ke wilayah terdekat yang tersedia
• Untuk beban kerja produksi dengan persyaratan latensi yang ketat, uji berbagai wilayah dan pilih wilayah dengan performa terbaik untuk kasus penggunaan Anda.

Memverifikasi Pengaturan

1. Pastikan kunci akun layanan Anda valid:

   gcloud auth activate-service-account --key-file=/path/to/key.json
   gcloud auth list

2. Uji akses Vertex AI:

   gcloud ai models list --region=us-east5

3. Verifikasi akses model Claude:

   curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" \
     "https://us-east5-aiplatform.googleapis.com/v1/projects/YOUR_PROJECT/locations/us-east5/publishers/anthropic/models/claude-3-5-haiku@20241022:rawPredict" \
     -d '{"anthropic_version": "vertex-2023-10-16", "max_tokens": 100, "messages": [{"role": "user", "content": "Hello"}]}'

Catatan

• Vertex AI dan API Anthropic langsung bersifat eksklusif satu sama lain. Ketika bagian konfigurasi vertex ada, variabel lingkungan ANTHROPIC_API_KEY akan diabaikan.
• Fungsionalitas pencarian web didukung sepenuhnya dengan Vertex AI.
• Prompt caching didukung melalui pemfilteran header otomatis untuk kompatibilitas Vertex AI.
• Function calling dan penggunaan tool bekerja dengan cara yang sama seperti pada API Anthropic secara langsung.