Struktura obiektu Anthropic Vertex AI

LibreChat obsługuje uruchamianie modeli Anthropic Claude za pośrednictwem Google Cloud Vertex AI. Pozwala to na korzystanie z modeli Claude przy użyciu istniejącej infrastruktury, rozliczeń i poświadczeń Google Cloud.

Aby uzyskać szybką konfigurację przy użyciu zmiennych środowiskowych, zobacz przewodnik konfiguracji Anthropic

Korzyści

• Ujednolicone rozliczenia: Użyj swojego istniejącego konta rozliczeniowego Google Cloud
• Funkcje Enterprise: Uzyskaj dostęp do funkcji bezpieczeństwa i zgodności klasy enterprise w Google Cloud
• Zgodność regionalna: Wdrażaj w określonych regionach, aby spełnić wymogi dotyczące przechowywania danych (data residency).
• Istniejąca infrastruktura: Wykorzystaj swoje obecne konta serwisowe GCP i polityki IAM

Wymagania wstępne

Zanim skonfigurujesz Anthropic Vertex AI, upewnij się, że posiadasz:

1. Projekt Google Cloud z włączonym interfejsem Vertex AI API
2. Konto serwisowe z rolą Vertex AI User (roles/aiplatform.user)
3. Modele Claude włączone w Twoim Vertex AI Model Garden
4. Klucz konta serwisowego (plik JSON) pobrany i dostępny dla LibreChat

Przykładowa konfiguracja

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

Uwaga: Endpoint Anthropic obsługuje wszystkie Shared Endpoint Settings, w tym streamRate, titleModel, titleMethod, titlePrompt, titlePromptTemplate oraz titleEndpoint.

vertex

Obiekt vertex zawiera wszystkie opcje konfiguracji specyficzne dla Vertex AI.

region

Klucz:

Domyślnie: us-east5

Dostępne regiony:

• global (zalecane w większości przypadków użycia)
• us-east5
• us-central1
• europe-west1
• europe-west4
• asia-southeast1

Wskazówka: Zaleca się używanie regionu global, ponieważ zapewnia on automatyczne kierowanie do najbliższego dostępnego regionu. Używaj konkretnych regionów tylko wtedy, gdy wymagają tego przepisy dotyczące przechowywania danych.

Przykład:

region: "global"

projectId

Klucz:

Domyślnie: Wykryto automatycznie z pliku klucza usługi

Przykład:

projectId: "${GOOGLE_PROJECT_ID}"

serviceKeyFile

Klucz:

Domyślnie: api/data/auth.json (lub zmienna środowiskowa GOOGLE_SERVICE_KEY_FILE)

Przykład:

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

models

Pole models definiuje dostępne modele Claude i mapuje przyjazne dla użytkownika nazwy na identyfikatory wdrożeń Vertex AI. Działa to podobnie do mapowania modeli Azure OpenAI.

Opcje formatowania

Możesz skonfigurować modele na trzy sposoby:

Opcja 1: Prosta tablica

Użyj bezpośrednio rzeczywistych identyfikatorów modeli Vertex AI. Będą one wyświetlane w interfejsie użytkownika w niezmienionej formie:

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

Opcja 2: Obiekt z własnymi nazwami (Zalecane)

Mapuj przyjazne dla użytkownika nazwy na nazwy wdrożeń 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

Opcja 3: Format mieszany z wartością domyślną

Ustaw domyślną nazwę wdrożenia i użyj wartości logicznych dla modeli, które ją dziedziczą:

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

Właściwości obiektu Model

Przykład:

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

Alternatywa dla zmiennych środowiskowych

W przypadku prostszych konfiguracji możesz skonfigurować Vertex AI przy użyciu zmiennych środowiskowych zamiast 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

Uwaga: Podczas korzystania ze zmiennych środowiskowych mapowanie modeli nie jest dostępne. Wszystkie znane modele Claude zostaną uwzględnione automatycznie.

Kompletne przykłady

Podstawowa konfiguracja

Minimalna konfiguracja przy użyciu ustawień domyślnych (Vertex AI jest włączone dzięki obecności sekcji vertex):

endpoints:
  anthropic:
    vertex:
      region: us-east5

Wykorzystuje to:

• Region: us-east5
• Klucz usługi: api/data/auth.json (lub zmienna środowiskowa GOOGLE_SERVICE_KEY_FILE)
• Identyfikator projektu: Wykryty automatycznie z klucza usługi
• Modele: Wszystkie znane modele Claude

Konfiguracja produkcyjna z Model Mapping

Pełna konfiguracja z niestandardowymi nazwami i tytułami modeli:

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

Konfiguracja wieloregionalna

Możesz skonfigurować tylko jeden region na wdrożenie. W przypadku potrzeb obejmujących wiele regionów, rozważ użycie oddzielnych instancji LibreChat lub niestandardowych endpoint.

Rozwiązywanie problemów

Typowe błędy

"Nie udało się załadować domyślnych poświadczeń"

• Upewnij się, że plik klucza konta serwisowego istnieje pod wskazaną ścieżką
• Sprawdź uprawnienia do pliku (muszą być możliwe do odczytania przez proces LibreChat)
• Zweryfikuj, czy plik JSON jest poprawny i nieuszkodzony

"Permission denied" lub "403 Forbidden"

• Zweryfikuj, czy konto serwisowe posiada rolę Vertex AI User
• Upewnij się, że modele Claude są włączone w Twoim Vertex AI Model Garden
• Sprawdź, czy konto serwisowe należy do właściwego projektu

"Model not found"

• Sprawdź, czy identyfikator modelu w deploymentName jest poprawny
• Zweryfikuj, czy model jest dostępny w wybranym regionie
• Upewnij się, że model jest włączony w Twoim Vertex AI Model Garden

Problemy z regionem

"Invalid region" lub "Region not supported"

• Użyj jednego z obsługiwanych regionów wymienionych powyżej
• Spróbuj użyć regionu global, który zapewnia automatyczne routowanie
• Sprawdź dokumentację Google Cloud, aby uzyskać najnowszą listę regionów, w których Claude jest dostępny.

"Model niedostępny w tym regionie"

• Nie wszystkie modele Claude są dostępne we wszystkich regionach
• Spróbuj przełączyć się na region global, aby uzyskać automatyczne kierowanie do dostępnego regionu
• Sprawdź Vertex AI Model Garden, aby zobaczyć, które modele są dostępne w Twoim regionie
• Rozważ użycie innego regionu, który ma szerszą dostępność modeli (np. us-east5)

Problemy z opóźnieniami

• Jeśli doświadczasz wysokich opóźnień, spróbuj użyć regionu geograficznie bliższego Twoim użytkownikom
• Region global automatycznie kieruje do najbliższego dostępnego regionu
• W przypadku obciążeń produkcyjnych z rygorystycznymi wymaganiami dotyczącymi opóźnień, przetestuj różne regiony i wybierz ten, który zapewnia najlepszą wydajność dla Twojego przypadku użycia.

Weryfikacja konfiguracji

1. Upewnij się, że klucz konta serwisowego jest poprawny:

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

2. Przetestuj dostęp do Vertex AI:

   gcloud ai models list --region=us-east5

3. Zweryfikuj dostęp do modelu 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"}]}'

Uwagi

• Vertex AI oraz bezpośrednie API Anthropic wzajemnie się wykluczają. Gdy obecna jest sekcja konfiguracyjna vertex, zmienna środowiskowa ANTHROPIC_API_KEY jest ignorowana.
• Funkcjonalność wyszukiwania w sieci jest w pełni obsługiwana w Vertex AI.
• Buforowanie promptów (prompt caching) jest obsługiwane poprzez automatyczne filtrowanie nagłówków w celu zapewnienia kompatybilności z Vertex AI.
• Wywoływanie funkcji (function calling) i korzystanie z narzędzi (tool use) działają tak samo, jak w przypadku bezpośredniego API Anthropic.