Azure OpenAI Integration für LibreChat

LibreChat unterstützt Azure OpenAI API-Dienste als erstklassigen endpoint. Um Azure OpenAI innerhalb von LibreChat zu nutzen, konfigurieren Sie die librechat.yaml Datei für Ihr Setup. Dieses Dokument behandelt den Einrichtungsprozess für die Verwendung mehrerer Deployments und Modelle.

Beispiel

Ein Beispiel für eine Konfiguration, die viele der unten beschriebenen Optionen und Funktionen enthält:

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

Dieses Beispiel folgt der Azure OpenAI Endpoint Configuration Docs.

Jede Konfigurationsebene wird im jeweiligen Abschnitt detailliert beschrieben:

1. Konfiguration auf Endpoint-Ebene

2. Gruppen-Konfiguration

3. Modell-Konfiguration

Einrichtung

1. librechat.yaml zum Bearbeiten öffnen: Verwenden Sie Ihren bevorzugten Texteditor oder Ihre IDE, um die Datei librechat.yaml zu öffnen und zu bearbeiten.

   • Optional: Verwenden Sie einen Remote- oder benutzerdefinierten Dateipfad mit der folgenden Umgebungsvariable:

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

2. Azure OpenAI Einstellungen konfigurieren: Befolgen Sie die unten aufgeführte Struktur, um Ihre Azure OpenAI Einstellungen einzutragen, einschließlich API-Schlüsseln, Instanznamen, Modellgruppen und anderen Konfigurationen.

3. Veraltete Einstellungen entfernen: Wenn Sie veraltete Konfigurationen verwenden, entfernen Sie diese. Der LibreChat-Server erkennt diese ebenfalls und weist Sie darauf hin.

4. Änderungen speichern: Speichern Sie die librechat.yaml Datei.

5. LibreChat neu starten: Starten Sie Ihre LibreChat-Anwendung neu, damit die aktualisierte Konfiguration geladen wird.

Erforderliche Felder

Um Azure OpenAI in LibreChat zu integrieren, müssen bestimmte Felder in Ihrer librechat.yaml Datei konfiguriert werden. Diese Felder werden durch eine Kombination aus benutzerdefinierten Variablen und Umgebungsvariablen validiert. Die detaillierten Anforderungen folgen hier.

Endpoint-Level Konfiguration

Globale Azure-Einstellungen:

Titel- und Konversationseinstellungen:

Gruppenkonfiguration:

Benutzerdefinierte Reihenfolge (Optional):

Die Option customOrder ist auskommentiert, da sie optional ist.

Beispiel für diese Einstellungen auf endpoint-Ebene in Ihrer librechat.yaml Datei:

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)

Konfiguration auf Gruppenebene

Die Felder, die in der Custom Config (librechat.yaml) Datei konfigurierbar sind. Weitere Informationen zu den einzelnen Feldern finden Sie im Azure OpenAI Abschnitt in der Custom Config Docs.

Konfiguration auf Gruppenebene: Gruppenidentifizierung:

Authentifizierung:

Azure OpenAI Instanz:

Bereitstellungskonfiguration:

Erweiterte Einstellungen:

Modellkonfiguration:

Beispiel einer Konfiguration auf Gruppenebene in der librechat.yaml Datei:

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)

Konfiguration auf Modellebene

Innerhalb jeder Gruppe enthält das Feld models eine Zuordnung von Modellkennungen zu ihren Konfigurationen:

Modellidentifizierung:

Modellkonfiguration:

Serverless Inference Endpoints:

• Die Modellkennung muss mit dem entsprechenden OpenAI-Modellnamen übereinstimmen, damit die bekannten Kontextgrenzen korrekt widergespiegelt werden und/oder die Vision-Funktionalität ordnungsgemäß funktioniert. Wenn Sie beispielsweise gpt-4-vision verwenden möchten, muss es wie folgt konfiguriert werden:

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

• Weitere Beispiele finden Sie unter Model Deployments.

• Wenn ein Modell auf true gesetzt ist, bedeutet dies, dass der deploymentName und die version auf Gruppenebene für dieses Modell verwendet werden. In diesem Fall müssen beide auf Gruppenebene definiert sein.

• Wenn ein Modell als Objekt konfiguriert ist, kann es seinen eigenen deploymentName und seine eigene version angeben. Wenn diese nicht bereitgestellt werden, erbt das Modell den deploymentName und die version der Gruppe.

• Wenn die Gruppe einen serverless inference endpoint darstellt, sollte das einzelne Modell auf true gesetzt werden, um es zur Modellliste hinzuzufügen.

Besondere Überlegungen

1. Eindeutige Namen: Sowohl Modell- als auch Gruppennamen müssen in der gesamten Konfiguration eindeutig sein. Doppelte Namen führen zu Validierungsfehlern.

2. Fehlende erforderliche Felder: Das Fehlen erforderlicher deploymentName- oder version-Angaben, entweder auf Gruppenebene (für Modelle mit Boolean-Flag) oder innerhalb der Modellkonfigurationen (sofern nicht vererbt oder explizit angegeben), führt zu Validierungsfehlern, es sei denn, die Gruppe repräsentiert einen serverless inference endpoint.

3. Referenzen auf Umgebungsvariablen: Die Konfiguration unterstützt Referenzen auf Umgebungsvariablen (z. B. ${VARIABLE_NAME}). Stellen Sie sicher, dass alle referenzierten Variablen in Ihrer Umgebung vorhanden sind, um Laufzeitfehler zu vermeiden. Das Fehlen von definierten Umgebungsvariablen, auf die in der Konfiguration verwiesen wird, führt zu Fehlern. ${INSTANCE_NAME} und ${DEPLOYMENT_NAME} sind eindeutige Platzhalter und entsprechen keinen Umgebungsvariablen, sondern dem Instanz- und Bereitstellungsnamen des aktuell ausgewählten Modells. Es wird nicht empfohlen, INSTANCE_NAME und DEPLOYMENT_NAME als Namen für Umgebungsvariablen zu verwenden, um mögliche Konflikte zu vermeiden.

4. Fehlerbehandlung: Jegliche Probleme in der Konfiguration, wie doppelte Namen, undefinierte Umgebungsvariablen oder fehlende erforderliche Felder, führen zur Ungültigkeit des Setups und erzeugen beschreibende Fehlermeldungen, die auf eine schnelle Lösung abzielen. Es ist Ihnen nicht gestattet, den Server mit einer ungültigen Konfiguration zu starten.

5. Modell-Identifikatoren: Ein (dem Projekt) unbekanntes Modell kann als Modell-Identifikator verwendet werden, muss jedoch mit einem bekannten Modell übereinstimmen, um dessen bekannte Kontextlänge widerzuspiegeln, was für die Nachrichten-/Token-Verarbeitung entscheidend ist; z. B. ist gpt-7000 gültig, greift aber standardmäßig auf ein 4k-Token-Limit zurück, während gpt-4-turbo als Modell mit einem 128k-Kontextlimit erkannt wird.

Validieren Sie Ihre Konfiguration anhand der neuesten Schemadefinitionen und Richtlinien, um die Kompatibilität zu gewährleisten.

Modell-Bereitstellungen

Die Liste der Modelle, die Ihren Benutzern zur Verfügung stehen, wird durch die Modellgruppierungen bestimmt, die in Ihrer azureOpenAI endpoint config festgelegt sind.

Zum Beispiel:

# 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

Die obige Konfiguration würde gpt-4-vision-preview, gpt-3.5-turbo und gpt-4-turbo für Ihre Benutzer in der Reihenfolge ihrer Definition aktivieren.

Verwendung von Assistants mit Azure

Um die Nutzung von Assistants mit Azure OpenAI zu ermöglichen, gibt es 2 Hauptschritte.

1. Setzen Sie das Feld assistants unter dem azureOpenAI endpoint, d. h. auf der Endpoint-Ebene, auf true, wie folgt:

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

2. Fügen Sie das Feld assistants zu Gruppen hinzu, die mit der Assistants API-Integration von Azure kompatibel sind.

• Mindestens eine Ihrer Gruppenkonfigurationen muss kompatibel sein.
• Sie können die kompatiblen Regionen und Modelle in der Azure-Dokumentation hier einsehen.
• Die Version muss ebenfalls "2024-02-15-preview" oder neuer sein, vorzugsweise neuer, um Zugriff auf die neuesten Funktionen zu erhalten.

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)

Hinweise:

• Verwenden Sie für Anmeldedaten benutzerdefinierte Umgebungsvariablen, die in der Konfiguration jeder mit Assistants kompatiblen Gruppe angegeben sind.

• Wenn Sie mehrere Regionen als assistants-kompatibel markieren, werden die von Ihnen erstellten Assistants über die Regionen hinweg in der Hauptauswahlliste für Assistants zusammengefasst.

• Dateien, die Sie auf Azure OpenAI hochladen, egal ob auf Nachrichten- oder Assistant-Ebene, sind nur in der Region verfügbar, zu der das Modell des aktuellen Assistant gehört.

  • Aus diesem Grund wird empfohlen, nur eine Region oder Ressourcengruppe für Azure OpenAI Assistants zu verwenden, da es sonst zu einem Fehler kommt.
  • Das Hochladen zu "OpenAI" ist das Standardverhalten für die offiziellen code_interpreter- und retrieval-Funktionen.

• Das Herunterladen von Dateien, die von Assistants generiert wurden, wird in Kürze unterstützt.

• Seit dem 19. Mai 2024 werden Retrieval und Streaming über Azure OpenAI noch nicht unterstützt.

  • Um Fehler bei der Retrieval-Funktion zu vermeiden, solange diese nicht unterstützt wird, wird empfohlen, die Funktion in der azureAssistants endpoint Konfiguration vollständig zu deaktivieren:

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

  • Standardmäßig sind alle Funktionen außer Retrieval aktiviert.

Verwendung von Plugins mit Azure

Um den Plugins endpoint mit Azure OpenAI zu verwenden, benötigen Sie eine Bereitstellung, die function calling unterstützt. Andernfalls deaktivieren Sie "Functions" in den Agent-Einstellungen. Wenn Sie den "functions"-Modus nicht verwenden, wird empfohlen, auch "skip completion" zu deaktivieren, da dies ein Überprüfungsschritt für das vom Agenten Generierte ist.

Um Azure mit dem Plugins endpoint zu verwenden, stellen Sie sicher, dass das Feld plugins in Ihrer Azure OpenAI endpoint-Konfiguration auf true gesetzt ist:

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

Die Konfiguration des Feldes plugins konfiguriert Plugins für die Verwendung von Azure-Modellen.

HINWEIS: Die aktuelle Konfiguration über librechat.yaml verwendet das primäre Modell, das Sie im Frontend für die Plugin-Nutzung auswählen. Dies ist normalerweise nicht die Art und Weise, wie es ohne Azure funktioniert, wo stattdessen das "Agent"-Modell verwendet wird. Die Einstellung für das Agent-Modell kann ignoriert werden, wenn Plugins über Azure verwendet werden.

Verwendung einer angegebenen Basis-URL mit Azure

Die Basis-URL für Azure OpenAI API-Anfragen kann dynamisch konfiguriert werden. Dies ist nützlich für Proxy-Dienste wie Cloudflare AI Gateway oder wenn Sie die baseURL-Verarbeitung der App explizit überschreiben möchten.

LibreChat verwendet das Feld baseURL für Ihre Azure-Modellgruppierung, welches Platzhalter für die Azure OpenAI API-Instanz und die Bereitstellungsnamen enthalten kann.

In der Konfiguration kann die Basis-URL wie folgt angepasst werden:

# 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}"

HINWEIS: ${INSTANCE_NAME} und ${DEPLOYMENT_NAME} sind eindeutige Platzhalter und entsprechen nicht Umgebungsvariablen, sondern dem Instanz- und Bereitstellungsnamen des aktuell ausgewählten Modells. Es wird nicht empfohlen, INSTANCE_NAME und DEPLOYMENT_NAME als Namen für Umgebungsvariablen zu verwenden, um mögliche Konflikte zu vermeiden.

Sie können die Platzhalter auch vollständig weglassen und die baseURL einfach mit Ihren Anmeldedaten konstruieren:

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

Zuletzt können Sie die gesamte baseURL über eine benutzerdefinierte Umgebungsvariable festlegen

      baseURL: "${MY_CUSTOM_BASEURL}"

Aktivieren von automatisch generierten Titeln mit Azure

Um die Titelgenerierung für Azure zu aktivieren, setzen Sie titleConvo auf true.

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

Sie können auch das für die Titelvergabe zu verwendende Modell mit titleModel angeben, sofern Sie es in Ihrer/Ihren Gruppe(n) konfiguriert haben.

    titleModel: "gpt-3.5-turbo"

Hinweis: "gpt-3.5-turbo" ist der Standardwert, daher können Sie ihn weglassen, wenn Sie genau dieses Modell verwenden möchten und es konfiguriert haben. Falls es nicht konfiguriert ist und titleConvo auf true gesetzt ist, führt der Benennungsprozess zu einem Fehler und es wird kein Titel generiert. Sie können dies auch so einstellen, dass dynamisch das aktuelle Modell verwendet wird, indem Sie es auf current_model setzen.

    titleModel: "current_model"

Verwendung von GPT-4 Vision mit Azure

Um Vision (Bildanalyse) mit Azure OpenAI zu verwenden, stellen Sie sicher, dass gpt-4-vision-preview als Modell in einer Ihrer Gruppierungen angegeben ist.

Dies funktioniert genauso wie beim OpenAI endpoint: Es ist nicht erforderlich, das Vision-Modell auszuwählen, da im Hintergrund automatisch gewechselt wird.

Bilder mit Azure OpenAI Service (DALL-E) generieren

• Zuerst müssen Sie eine Azure-Ressource erstellen, die DALL-E hostet.
  • Zum Zeitpunkt der Erstellung dieses Dokuments ist dall-e-3 in der Region SwedenCentral und dall-e-2 in der Region EastUS verfügbar.
• Anschließend müssen Sie das Bildgenerierungsmodell in einer der oben genannten Regionen bereitstellen.
  • Lesen Sie den Azure OpenAI Image Generation Quickstart Guide für weitere Unterstützung.
• Konfigurieren Sie Ihre Umgebungsvariablen basierend auf den Azure-Anmeldeinformationen:

Die DALL-E Konfigurationsoptionen:

DALL-E:

API-Schlüssel:

API-Schlüssel (Versionsspezifisch):

System-Prompts:

Reverse-Proxy-Einstellungen:

Basis-URLs:

Azure OpenAI Integration (Optional):

Ersetzen Sie den Platzhaltertext durch tatsächliche Prompts oder Anweisungen und geben Sie Ihre API-Schlüssel an, falls Sie diese direkt in die Datei einfügen möchten (es wird empfohlen, sensible Schlüssel außerhalb der Codebasis zu verwalten). Überprüfen und beachten Sie die Nutzungsrichtlinien von OpenAI, wenn Sie API-Schlüssel in Software einbetten.

Hinweis: Wenn Sie PROXY festgelegt haben, wird dieser auch für DALL-E-Aufrufe verwendet, was für die gesamte App gilt.

Serverless Inference Endpoints

Über die librechat.yaml Datei können Sie serverlose Azure AI Studio Inference-Endpunkte konfigurieren, um auf Modelle aus der Azure AI Foundry zuzugreifen. Es werden lediglich eine Modellkennung, baseURL und apiKey zusammen mit dem Feld serverless benötigt, um die spezielle Handhabung anzugeben, die diese Endpunkte erfordern.

• Sie müssen die Anweisungen in den kompatiblen Model Cards befolgen, um den MaaS-Zugriff ("Models as a Service") in Azure AI Studio einzurichten.

  • Als Referenz sind hier einige bekannte kompatible Model Cards:

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

• Sie können auch den technischen Blog zur Veröffentlichung des "Mistral-large"-Modells für weitere Informationen lesen.

• Anschließend müssen Sie diese zu Ihrer azureOpenAI-Konfiguration in der librechat.yaml Datei hinzufügen.

• Hier ist eine Beispielkonfiguration für 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

Hinweise:

• Azure AI Foundry-Modelle stellen jetzt Endpunkte unter /models/chat/completions?api-version=version für serverlose Inferenz bereit.
  • Das Feld baseURL sollte auf den Root des endpoint gesetzt werden, ohne etwas nach /models/, d. h. ohne den Pfad /chat/completions.
  • Beispiel: https://example.services.ai.azure.com/models/ für https://example.services.ai.azure.com/models/chat/completions?api-version=2024-05-01-preview
  • Der version Abfrageparameter ist optional und kann im baseURL Feld angegeben werden.
• Der im Feld models verwendete Modellname muss mit dem Bereitstellungsnamen des Modells in der Azure AI Foundry übereinstimmen.
• Die Kompatibilität mit LibreChat basiert auf der Parität mit den OpenAI API-Spezifikationen, bei denen es sich zum Zeitpunkt der Erstellung dieses Dokuments in der Regel um "Pay-as-you-go"- oder "Models as a Service" (MaaS)-Bereitstellungen in Azure AI Studio handelt, die mit dem OpenAI-SDK kompatibel sind und entweder den v1/completions- oder den models/chat/completions-endpoint unterstützen.
• Alle Modelle, die serverlose Bereitstellungen ("Serverless APIs") anbieten, sind mit dem Azure-Modellkatalog kompatibel. Sie können unter den Bereitstellungsoptionen nach "Serverless API" und unter den Inferenzaufgaben nach "Chat completion" filtern, um die vollständige Liste zu sehen; Modelle mit Echtzeit-endpoint wurden jedoch nicht getestet.
• Diese serverlosen Inference-Endpunkte/Modelle unterstützen möglicherweise die Funktionsaufrufe gemäß den OpenAI API-Spezifikationen, was ihre Verwendung mit Agents ermöglicht.