Struttura dell'oggetto Anthropic Vertex AI

LibreChat supporta l'esecuzione dei modelli Anthropic Claude tramite Google Cloud Vertex AI. Ciò ti consente di utilizzare i modelli Claude con la tua infrastruttura, fatturazione e credenziali Google Cloud esistenti.

Per una configurazione rapida utilizzando le variabili d'ambiente, consulta la guida alla configurazione di Anthropic

Vantaggi

• Fatturazione unificata: utilizza il tuo account di fatturazione Google Cloud esistente
• Funzionalità Enterprise: Accedi alle funzionalità di sicurezza e conformità enterprise di Google Cloud
• Conformità regionale: Distribuisci in regioni specifiche per soddisfare i requisiti di residenza dei dati
• Infrastruttura esistente: Sfrutta i tuoi account di servizio GCP e le policy IAM attuali

Prerequisiti

Prima di configurare Anthropic Vertex AI, assicurati di avere:

1. Google Cloud Project con l'API Vertex AI abilitata
2. Service Account con il ruolo Vertex AI User (roles/aiplatform.user)
3. Modelli Claude abilitati nel tuo Vertex AI Model Garden
4. Service Account Key (file JSON) scaricata e accessibile a LibreChat

Esempio di configurazione

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

Nota: L'endpoint Anthropic supporta tutte le Shared Endpoint Settings, incluse streamRate, titleModel, titleMethod, titlePrompt, titlePromptTemplate e titleEndpoint.

vertex

L'oggetto vertex contiene tutte le opzioni di configurazione specifiche per Vertex AI.

region

Chiave:

Predefinito: us-east5

Regioni disponibili:

• global (consigliato per la maggior parte dei casi d'uso)
• us-east5
• us-central1
• europe-west1
• europe-west4
• asia-southeast1

Suggerimento: La regione global è consigliata poiché fornisce un instradamento automatico verso la regione disponibile più vicina. Utilizza regioni specifiche solo se hai requisiti di residenza dei dati.

Esempio:

region: "global"

projectId

Chiave:

Predefinito: Rilevato automaticamente dal file della chiave del servizio

Esempio:

projectId: "${GOOGLE_PROJECT_ID}"

serviceKeyFile

Chiave:

Predefinito: api/data/auth.json (o variabile d'ambiente GOOGLE_SERVICE_KEY_FILE)

Esempio:

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

models

Il campo models definisce i modelli Claude disponibili e associa nomi intuitivi agli ID di distribuzione di Vertex AI. Questo funziona in modo simile al mapping dei modelli di Azure OpenAI.

Opzioni di formato

Puoi configurare i modelli in tre modi:

Opzione 1: Array semplice

Utilizza direttamente gli ID modello effettivi di Vertex AI. Questi verranno mostrati così come sono nell'interfaccia utente:

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

Opzione 2: Oggetto con Nomi Personalizzati (Consigliato)

Associa nomi intuitivi ai nomi di distribuzione di 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

Opzione 3: Formato misto con predefinito

Imposta un nome di distribuzione predefinito e utilizza valori booleani per i modelli che lo ereditano:

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

Proprietà dell'oggetto Model

Esempio:

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

Alternativa alle variabili d'ambiente

Per configurazioni più semplici, è possibile configurare Vertex AI utilizzando le variabili d'ambiente invece del file 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

Nota: Quando si utilizzano le variabili d'ambiente, il model mapping non è disponibile. Tutti i modelli Claude conosciuti verranno inclusi automaticamente.

Esempi completi

Configurazione di base

Configurazione minima utilizzando i valori predefiniti (Vertex AI è abilitato dalla presenza della sezione vertex):

endpoints:
  anthropic:
    vertex:
      region: us-east5

Questo utilizza:

• Regione: us-east5
• Chiave di servizio: api/data/auth.json (o variabile d'ambiente GOOGLE_SERVICE_KEY_FILE)
• ID Progetto: Rilevato automaticamente dalla chiave di servizio
• Modelli: Tutti i modelli Claude conosciuti

Configurazione di produzione con Model Mapping

Configurazione completa con nomi e titoli dei modelli personalizzati:

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

Configurazione Multi-Regione

È possibile configurare solo una regione per deployment. Per esigenze multi-regione, si consiglia di utilizzare istanze LibreChat separate o endpoint personalizzati.

Risoluzione dei problemi

Errori comuni

"Impossibile caricare le credenziali predefinite"

• Assicurati che il file della chiave dell'account di servizio esista nel percorso specificato
• Controlla i permessi dei file (devono essere leggibili dal processo LibreChat)
• Verifica che il file JSON sia valido e non corrotto

"Permission denied" o "403 Forbidden"

• Verifica che l'account di servizio abbia il ruolo Vertex AI User
• Assicurati che i modelli Claude siano abilitati nel tuo Vertex AI Model Garden
• Verifica che l'account di servizio appartenga al progetto corretto

"Modello non trovato"

• Controlla che l'ID del modello in deploymentName sia corretto
• Verifica che il modello sia disponibile nella regione selezionata
• Assicurati che il modello sia abilitato nel tuo Vertex AI Model Garden

Problemi di regione

"Regione non valida" o "Regione non supportata"

• Utilizza una delle regioni supportate elencate sopra
• Prova a utilizzare la regione global che fornisce il routing automatico
• Consulta la documentazione di Google Cloud per l'elenco aggiornato delle regioni in cui Claude è disponibile.

"Modello non disponibile nella regione"

• Non tutti i modelli Claude sono disponibili in tutte le regioni
• Prova a passare alla regione global per il routing automatico verso una regione disponibile
• Controlla il Vertex AI Model Garden per vedere quali modelli sono disponibili nella tua regione
• Prendi in considerazione l'utilizzo di una regione diversa che abbia una maggiore disponibilità di modelli (ad esempio, us-east5)

Problemi di latenza

• Se riscontri una latenza elevata, prova a utilizzare una regione geograficamente più vicina ai tuoi utenti
• La regione global instrada automaticamente verso la regione disponibile più vicina
• Per carichi di lavoro in produzione con requisiti di latenza rigorosi, testa diverse regioni e scegli quella con le migliori prestazioni per il tuo caso d'uso.

Verifica della configurazione

1. Assicurati che la chiave del tuo account di servizio sia valida:

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

2. Testa l'accesso a Vertex AI:

   gcloud ai models list --region=us-east5

3. Verifica l'accesso al modello 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"}]}'

Note

• Vertex AI e l'API Anthropic diretta sono mutuamente esclusivi. Quando è presente una sezione di configurazione vertex, la variabile d'ambiente ANTHROPIC_API_KEY viene ignorata.
• La funzionalità di ricerca web è pienamente supportata con Vertex AI.
• Il prompt caching è supportato tramite il filtraggio automatico delle intestazioni per la compatibilità con Vertex AI.
• Il function calling e l'utilizzo dei tool funzionano allo stesso modo dell'API Anthropic diretta.