Integracja Azure OpenAI z LibreChat

LibreChat obsługuje usługi Azure OpenAI API jako pierwszorzędny endpoint. Aby korzystać z Azure OpenAI wewnątrz LibreChat, skonfiguruj plik librechat.yaml dla swojej konfiguracji. Niniejszy dokument opisuje proces konfiguracji dla korzystania z wielu wdrożeń i modeli.

Przykład

Przykładowa konfiguracja zawierająca wiele opcji i funkcji opisanych poniżej:

endpoints:
  azureOpenAI:
    # Endpoint-level configuration
    titleModel: "llama-70b-chat"
    plugins: true
    assistants: true
    groups:
    # Group-level configuration
    - group: "my-resource-westus"
      apiKey: "${WESTUS_API_KEY}"
      instanceName: "my-resource-westus"
      version: "2024-03-01-preview"
      # Model-level configuration
      models:
        gpt-4-vision-preview:
          deploymentName: gpt-4-vision-preview
          version: "2024-03-01-preview"
        gpt-3.5-turbo:
          deploymentName: gpt-35-turbo
        gpt-4-1106-preview:
          deploymentName: gpt-4-1106-preview
    # Group-level configuration
    - group: "mistral-inference"
      apiKey: "${AZURE_MISTRAL_API_KEY}"
      baseURL: "https://Mistral-large-vnpet-serverless.region.inference.ai.azure.com/v1/chat/completions"
      serverless: true
      # Model-level configuration
      models:
        mistral-large: true
    # Group-level configuration
    - group: "my-resource-sweden"
      apiKey: "${SWEDEN_API_KEY}"
      instanceName: "my-resource-sweden"
      deploymentName: gpt-4-1106-preview
      version: "2024-03-01-preview"
      assistants: true
      # Model-level configuration
      models:
        gpt-4-turbo: true

Ten przykład jest zgodny z Dokumentacją konfiguracji endpointu Azure OpenAI.

Każdy poziom konfiguracji został szczegółowo opisany w odpowiedniej sekcji:

1. Konfiguracja na poziomie endpoint

2. Konfiguracja na poziomie grupy

3. Konfiguracja na poziomie modelu

Konfiguracja

1. Otwórz librechat.yaml do edycji: Użyj preferowanego edytora tekstu lub środowiska IDE, aby otworzyć i edytować plik librechat.yaml.

   • Opcjonalnie: użyj zdalnej lub niestandardowej ścieżki pliku za pomocą następującej zmiennej środowiskowej:

   CONFIG_PATH="/alternative/path/to/librechat.yaml"

2. Konfiguracja ustawień Azure OpenAI: Postępuj zgodnie z poniższą strukturą, aby uzupełnić ustawienia Azure OpenAI, w tym klucze API, nazwy instancji, grupy modeli oraz inne konfiguracje.

3. Usuń starsze ustawienia: Jeśli używasz jakichkolwiek starszych konfiguracji, usuń je. Serwer LibreChat również je wykryje i przypomni Ci o tym.

4. Zapisz swoje zmiany: Zapisz plik librechat.yaml.

5. Restart LibreChat: Zrestartuj swoją aplikację LibreChat, aby załadować zaktualizowaną konfigurację.

Wymagane pola

Aby zintegrować Azure OpenAI z LibreChat, należy skonfigurować określone pola w pliku librechat.yaml. Pola te są weryfikowane za pomocą kombinacji zmiennych niestandardowych oraz zmiennych środowiskowych. Poniżej znajdują się szczegółowe wymagania.

Konfiguracja na poziomie endpoint

Globalne ustawienia Azure:

Ustawienia tytułu i konwersacji:

Konfiguracja grupy:

Niestandardowa kolejność (opcjonalne):

Opcja customOrder jest zakomentowana, ponieważ jest opcjonalna.

Przykład tych ustawień na poziomie endpoint w pliku librechat.yaml:

endpoints:
  azureOpenAI:
    titleModel: "gpt-3.5-turbo-1106"
    plugins: true
    assistants: true
    summarize: true
    summaryModel: "gpt-3.5-turbo-1106"
    titleConvo: true
    titleMethod: "functions"
    groups:
      # ... (group-level and model-level configurations)

Konfiguracja na poziomie grupy

Pola konfigurowalne w pliku Custom Config (librechat.yaml). Aby uzyskać więcej informacji na temat każdego pola, zobacz sekcję Azure OpenAI w dokumentacji Custom Config.

Konfiguracja na poziomie grupy: Identyfikacja grupy:

Uwierzytelnianie:

Instancja Azure OpenAI:

Konfiguracja wdrożenia:

Zaawansowane ustawienia:

Konfiguracja modelu:

Przykład konfiguracji na poziomie grupy w pliku librechat.yaml:

endpoints:
  azureOpenAI:
    # ... (endpoint-level configurations)
    groups:
      - group: "my-resource-group"
        apiKey: "${AZURE_API_KEY}"
        instanceName: "my-instance"
        deploymentName: "gpt-35-turbo"
        version: "2023-03-15-preview"
        baseURL: "https://my-instance.openai.azure.com/"
        additionalHeaders:
          CustomHeader: "HeaderValue"
        addParams:
          max_tokens: 2048
          temperature: 0.7
        dropParams:
          - "frequency_penalty"
          - "presence_penalty"
        models:
        # ... (model-level configurations)

Konfiguracja na poziomie modelu

Wewnątrz każdej grupy pole models zawiera mapowanie identyfikatorów modeli na ich konfiguracje:

Identyfikacja modelu:

Konfiguracja modelu:

Punkty końcowe wnioskowania bezserwerowego (Serverless Inference Endpoints):

• Identyfikator modelu musi być zgodny z odpowiadającą mu nazwą modelu OpenAI, aby poprawnie odzwierciedlał znane limity kontekstu i/lub działał w przypadku funkcji wizji (vision). Na przykład, jeśli zamierzasz użyć gpt-4-vision, musi on zostać skonfigurowany w następujący sposób:

endpoints:
  azureOpenAI:
    # ... (endpoint-level configurations)
    groups:
    # ... (group-level configurations)
    - group: "example_group"
    models:
     # Model identifiers must match OpenAI Model name (can be a partial match)
      gpt-4-vision-preview:
      # Object setting: must include at least "deploymentName" and/or "version"
        deploymentName: "arbitrary-deployment-name"
        version: "2024-02-15-preview" # version can be any that supports vision
      # Boolean setting, must be "true"
      gpt-4-turbo: true

• Zobacz Model Deployments, aby uzyskać więcej przykładów.

• Jeśli model jest ustawiony na true, oznacza to użycie deploymentName i version na poziomie grupy dla tego modelu. W takim przypadku oba te parametry muszą być zdefiniowane na poziomie grupy.

• Jeśli model jest skonfigurowany jako obiekt, może określić własne deploymentName oraz version. Jeśli nie zostaną one podane, model dziedziczy deploymentName oraz version grupy.

• Jeśli grupa reprezentuje serverless inference endpoint, pojedynczy model powinien być ustawiony na true, aby dodać go do listy modeli.

Szczególne uwagi

1. Unikalne nazwy: Zarówno nazwy modeli, jak i grup muszą być unikalne w całej konfiguracji. Zduplikowane nazwy prowadzą do błędów walidacji.

2. Brakujące wymagane pola: Brak wymaganego pola deploymentName lub version na poziomie grupy (w przypadku modeli z flagą logiczną) lub w konfiguracjach modeli (jeśli nie są dziedziczone lub jawnie określone) spowoduje błędy walidacji, chyba że grupa reprezentuje serverless inference endpoint.

3. Odwołania do zmiennych środowiskowych: Konfiguracja obsługuje odwołania do zmiennych środowiskowych (np. ${VARIABLE_NAME}). Upewnij się, że wszystkie przywołane zmienne znajdują się w Twoim środowisku, aby uniknąć błędów wykonania. Brak zdefiniowanych zmiennych środowiskowych, do których odwołuje się konfiguracja, spowoduje błędy. ${INSTANCE_NAME} oraz ${DEPLOYMENT_NAME} to unikalne symbole zastępcze, które nie odpowiadają zmiennym środowiskowym, lecz nazwie instancji i wdrożenia aktualnie wybranego modelu. Nie zaleca się używania INSTANCE_NAME oraz DEPLOYMENT_NAME jako nazw zmiennych środowiskowych, aby uniknąć potencjalnych konfliktów.

4. Obsługa błędów: Wszelkie problemy w konfiguracji, takie jak zduplikowane nazwy, niezdefiniowane zmienne środowiskowe lub brak wymaganych pól, unieważnią konfigurację i wygenerują opisowe komunikaty o błędach, mające na celu szybkie rozwiązanie problemu. Uruchomienie serwera z nieprawidłową konfiguracją nie będzie możliwe.

5. Identyfikatory modeli: Nieznany model (dla projektu) może być użyty jako identyfikator modelu, ale musi on odpowiadać znanemu modelowi, aby odzwierciedlić jego znaną długość kontekstu, co jest kluczowe dla obsługi wiadomości/tokenów; np. gpt-7000 będzie poprawny, ale domyślnie przyjmie limit 4 tys. tokenów, podczas gdy gpt-4-turbo zostanie rozpoznany jako posiadający limit kontekstu 128 tys. tokenów.

Zweryfikuj swoją konfigurację zgodnie z najnowszymi definicjami schematów i wytycznymi, aby zachować kompatybilność.

Wdrożenia modeli

Lista modeli dostępnych dla Twoich użytkowników jest określana przez grupy modeli wyszczególnione w konfiguracji punktu końcowego azureOpenAI w pliku librechat.yaml.

Na przykład:

# Example Azure OpenAI Object Structure
endpoints:
  azureOpenAI:
    groups:
      - group: "my-westus" # arbitrary name
        apiKey: "${WESTUS_API_KEY}"
        instanceName: "actual-instance-name" # name of the resource group or instance
        version: "2023-12-01-preview"
        models:
          gpt-4-vision-preview:
            deploymentName: gpt-4-vision-preview
            version: "2024-02-15-preview"
          gpt-3.5-turbo: true
      - group: "my-eastus"
        apiKey: "${EASTUS_API_KEY}"
        instanceName: "actual-eastus-instance-name"
        deploymentName: gpt-4-turbo
        version: "2024-02-15-preview"
        models:
          gpt-4-turbo: true

Powyższa konfiguracja włączy gpt-4-vision-preview, gpt-3.5-turbo oraz gpt-4-turbo dla Twoich użytkowników w kolejności, w jakiej zostały zdefiniowane.

Korzystanie z Assistants z Azure

Aby włączyć korzystanie z Assistants w Azure OpenAI, należy wykonać 2 główne kroki.

1. Ustaw pole assistants, pod endpointem azureOpenAI, tj. na poziomie endpointu, na true, w następujący sposób:

endpoints:
  azureOpenAI:
  # Enable use of Assistants with Azure
    assistants: true

2. Dodaj pole assistants do grup kompatybilnych z integracją Azure Assistants API.

• Co najmniej jedna z Twoich konfiguracji grup musi być kompatybilna.
• Możesz sprawdzić kompatybilne regiony i modele w dokumentacji Azure tutaj.
• Wersja musi również być "2024-02-15-preview" lub nowsza, najlepiej późniejsza, aby uzyskać dostęp do najnowszych funkcji.

endpoints:
  azureOpenAI:
    assistants: true
    groups:
      - group: "my-sweden-group"
        apiKey: "${SWEDEN_API_KEY}"
        instanceName: "actual-instance-name"
      # Mark this group as assistants compatible
        assistants: true
      # version must be "2024-02-15-preview" or later
        version: "2024-03-01-preview"
        models:
          # ... (model-level configuration)

Uwagi:

• W przypadku danych uwierzytelniających należy polegać na niestandardowych zmiennych środowiskowych określonych w konfiguracji każdej grupy zgodnej z assistants.

• Jeśli oznaczysz wiele regionów jako kompatybilne z asystentami, utworzeni przez Ciebie asystenci zostaną zagregowani z różnych regionów na główną listę wyboru asystentów.

• Pliki przesyłane do Azure OpenAI, zarówno na poziomie wiadomości, jak i asystenta, będą dostępne wyłącznie w regionie, do którego należy model bieżącego asystenta.

  • Z tego powodu zaleca się korzystanie tylko z jednego regionu lub grupy zasobów dla Azure OpenAI Assistants, w przeciwnym razie wystąpi błąd.
  • Przesyłanie do "OpenAI" jest domyślnym zachowaniem dla oficjalnych funkcji code_interpreter oraz retrieval.

• Pobieranie plików generowanych przez asystentów będzie wkrótce obsługiwane.

• Od 19 maja 2024 r. pobieranie (retrieval) i przesyłanie strumieniowe (streaming) nie są jeszcze obsługiwane przez Azure OpenAI.

  • Aby uniknąć błędów związanych z funkcją retrieval, gdy nie jest ona obsługiwana, zaleca się całkowite wyłączenie tej możliwości w konfiguracji endpointu azureAssistants:

  endpoints:
    azureOpenAI:
      # ...rest
  
    azureAssistants:
    # "retrieval" omitted.
      capabilities: ["code_interpreter", "actions", "tools"]

  • Domyślnie wszystkie funkcje, z wyjątkiem retrieval, są włączone.

Używanie wtyczek z Azure

Aby korzystać z endpoint Plugins w Azure OpenAI, potrzebujesz wdrożenia obsługującego function calling. W przeciwnym razie wyłącz opcję "Functions" w ustawieniach agenta. Gdy nie korzystasz z trybu "functions", zaleca się również wyłączenie opcji "skip completion", która stanowi krok weryfikacji tego, co wygenerował agent.

Aby używać Azure z endpointem Plugins, upewnij się, że pole plugins jest ustawione na true w konfiguracji endpointu Azure OpenAI:

# Example Azure OpenAI Object Structure
endpoints:
  azureOpenAI:
    plugins: true # <------- Set this
    groups:
    # omitted for brevity

Skonfigurowanie pola plugins skonfiguruje wtyczki do korzystania z modeli Azure.

UWAGA: Bieżąca konfiguracja poprzez librechat.yaml wykorzystuje główny model wybrany z interfejsu użytkownika do obsługi wtyczek, co zazwyczaj nie działa w ten sposób bez Azure, gdzie zamiast tego używany jest model "Agent". Ustawienie modelu Agent można zignorować podczas korzystania z wtyczek przez Azure.

Używanie określonego adresu Base URL z Azure

Podstawowy adres URL (base URL) dla żądań API Azure OpenAI może być konfigurowany dynamicznie. Jest to przydatne w przypadku usług pośredniczących (proxy), takich jak Cloudflare AI Gateway, lub jeśli chcesz jawnie nadpisać sposób obsługi baseURL w aplikacji.

LibreChat użyje pola baseURL dla grupowania modeli Azure, które może zawierać symbole zastępcze dla instancji Azure OpenAI API oraz nazw wdrożeń.

W konfiguracji, base URL można dostosować w następujący sposób:

# librechat.yaml file, under an Azure group:
endpoints:
  azureOpenAI:
    groups:
      - group: "group-with-custom-base-url"
      baseURL: "https://example.azure-api.net/${INSTANCE_NAME}/${DEPLOYMENT_NAME}"

# Legacy format (.openai.azure.com)
      baseURL: "https://${INSTANCE_NAME}.openai.azure.com/openai/deployments/${DEPLOYMENT_NAME}"

# New format (.cognitiveservices.azure.com)
      baseURL: "https://${INSTANCE_NAME}.cognitiveservices.azure.com/openai/deployments/${DEPLOYMENT_NAME}"

# Cloudflare example
      baseURL: "https://gateway.ai.cloudflare.com/v1/ACCOUNT_TAG/GATEWAY/azure-openai/${INSTANCE_NAME}/${DEPLOYMENT_NAME}"

UWAGA: ${INSTANCE_NAME} oraz ${DEPLOYMENT_NAME} to unikalne symbole zastępcze, które nie odpowiadają zmiennym środowiskowym, lecz nazwie instancji i wdrożenia aktualnie wybranego modelu. Nie zaleca się używania INSTANCE_NAME oraz DEPLOYMENT_NAME jako nazw zmiennych środowiskowych, aby uniknąć potencjalnych konfliktów.

Możesz również całkowicie pominąć symbole zastępcze i po prostu skonstruować baseURL za pomocą swoich danych uwierzytelniających:

      baseURL: "https://gateway.ai.cloudflare.com/v1/ACCOUNT_TAG/GATEWAY/azure-openai/my-secret-instance/my-deployment"

Na koniec, możesz określić cały baseURL za pomocą niestandardowej zmiennej środowiskowej

      baseURL: "${MY_CUSTOM_BASEURL}"

Włączanie automatycznie generowanych tytułów z Azure

Aby włączyć tytułowanie dla Azure, ustaw titleConvo na true.

# Example Azure OpenAI Object Structure
endpoints:
  azureOpenAI:
    titleConvo: true # <------- Set this
    groups:
    # omitted for brevity

Możesz również określić model używany do nadawania tytułów za pomocą titleModel, pod warunkiem, że skonfigurowałeś go w swoich grupach.

    titleModel: "gpt-3.5-turbo"

Uwaga: "gpt-3.5-turbo" jest wartością domyślną, więc możesz ją pominąć, jeśli chcesz użyć dokładnie tego modelu i masz go skonfigurowanego. Jeśli nie jest skonfigurowany, a titleConvo jest ustawione na true, proces nadawania tytułu zakończy się błędem i tytuł nie zostanie wygenerowany. Możesz również ustawić to tak, aby dynamicznie używało bieżącego modelu, ustawiając wartość na current_model.

    titleModel: "current_model"

Używanie GPT-4 Vision z Azure

Aby korzystać z funkcji Vision (analiza obrazu) w Azure OpenAI, upewnij się, że gpt-4-vision-preview jest określonym modelem w jednej z Twoich grup.

Działa to w ten sam sposób, co w przypadku endpoint OpenAI: nie ma potrzeby wybierania modelu wizyjnego, ponieważ zostanie on przełączony automatycznie w tle.

Generowanie obrazów za pomocą Azure OpenAI Service (DALL-E)

• Najpierw musisz utworzyć zasób Azure, który hostuje DALL-E
  • W momencie pisania tego tekstu, dall-e-3 jest dostępny w regionie SwedenCentral, a dall-e-2 w regionie EastUS.
• Następnie musisz wdrożyć model generowania obrazów w jednym z powyższych regionów.
  • Zapoznaj się z przewodnikiem szybkiego startu generowania obrazów Azure OpenAI, aby uzyskać dalszą pomoc.
• Skonfiguruj swoje zmienne środowiskowe w oparciu o dane uwierzytelniające Azure:

Opcje konfiguracji DALL-E:

DALL-E:

Klucze API:

Klucze API (zależne od wersji):

System Prompts:

Ustawienia Reverse Proxy:

Bazowe adresy URL:

Integracja z Azure OpenAI (opcjonalna):

Zastąp tekst zastępczy rzeczywistymi promptami lub instrukcjami i podaj swoje klucze API, jeśli zdecydujesz się umieścić je bezpośrednio w pliku (zaleca się zarządzanie poufnymi kluczami poza bazą kodu). Zapoznaj się z zasadami użytkowania OpenAI i przestrzegaj ich podczas osadzania kluczy API w oprogramowaniu.

Uwaga: jeśli masz ustawione PROXY, będzie ono używane również dla wywołań DALL-E, co jest uniwersalne dla całej aplikacji.

Serverless Inference Endpoints

Za pomocą pliku librechat.yaml możesz skonfigurować punkty końcowe wnioskowania bezserwerowego Azure AI Studio, aby uzyskać dostęp do modeli z Azure AI Foundry. Wymagany jest jedynie identyfikator modelu, baseURL oraz apiKey, wraz z polem serverless, aby wskazać specjalną obsługę, której wymagają te punkty końcowe.

• Będziesz musiał postępować zgodnie z instrukcjami zawartymi w kompatybilnych kartach modeli, aby skonfigurować dostęp MaaS („Models as a Service”) w Azure AI Studio.

  • Dla celów informacyjnych, oto kilka znanych kompatybilnych kart modeli:

  • Mistral-large | Meta-Llama-3.1-8B-Instruct | Phi-3-medium-128k-instruct

• Możesz również zapoznać się z blogiem technicznym dotyczącym wydania modelu "Mistral-large", aby uzyskać więcej informacji.

• Następnie musisz dodać je do swojej konfiguracji azureOpenAI w pliku librechat.yaml.

• Oto przykładowa konfiguracja dla Meta-Llama-3.1-8B-Instruct:

endpoints:
  azureOpenAI:
    groups:
    - group: "serverless-example"
      apiKey: "${LLAMA318B_API_KEY}"  # arbitrary env var name
      baseURL: "https://example.services.ai.azure.com/models/"
      version: "2024-05-01-preview" # Optional: specify API version
      serverless: true
      models:
        # Must match the deployment name of the model
        Meta-Llama-3.1-8B-Instruct: true

Uwagi:

• Modele Azure AI Foundry udostępniają teraz endpointy pod adresem /models/chat/completions?api-version=version na potrzeby wnioskowania bezserwerowego (serverless inference).
  • Pole baseURL powinno być ustawione na katalog główny endpointu, bez żadnych elementów po /models/, tj. ścieżki /chat/completions.
  • Przykład: https://example.services.ai.azure.com/models/ dla https://example.services.ai.azure.com/models/chat/completions?api-version=2024-05-01-preview
  • Parametr zapytania version jest opcjonalny i można go określić w polu baseURL.
• Nazwa modelu użyta w polu models musi być zgodna z nazwą wdrożenia modelu w Azure AI Foundry.
• Zgodność z LibreChat opiera się na parytecie ze specyfikacjami OpenAI API, które w momencie pisania tego tekstu są zazwyczaj wdrożeniami typu "Pay-as-you-go" lub "Models as a Service" (MaaS) w Azure AI Studio, zgodnymi z OpenAI-SDK i obsługującymi endpoint v1/completions lub models/chat/completions.
• Wszystkie modele oferujące wdrożenia bezserwerowe ("Serverless APIs") z katalogu modeli Azure są kompatybilne. Możesz filtrować według "Serverless API" w opcjach wdrożenia (Deployment options) oraz "Chat completion" w zadaniach wnioskowania (inference tasks), aby zobaczyć pełną listę; jednakże modele typu real time endpoint nie zostały przetestowane.
• Te bezserwerowe endpointy/modele wnioskowania mogą, ale nie muszą obsługiwać wywoływania funkcji (function calling) zgodnie ze specyfikacją OpenAI API, co umożliwia ich użycie z Agentami.