Azure OpenAI-integratie voor LibreChat

LibreChat ondersteunt Azure OpenAI API-services als een eersteklas endpoint. Om Azure OpenAI binnen LibreChat te gebruiken, configureer je het librechat.yaml bestand voor jouw setup. Dit document behandelt het installatieproces voor het gebruik van meerdere deployments en modellen.

Voorbeeld

Een voorbeeldconfiguratie inclusief veel van de opties en functies die hieronder worden beschreven:

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

Dit voorbeeld volgt de Azure OpenAI Endpoint Configuration Docs.

Elk configuratieniveau wordt in detail beschreven in de betreffende sectie:

1. Configuratie op endpoint-niveau

2. Configuratie op groepsniveau

3. Model-level config

Setup

1. Open librechat.yaml om te bewerken: Gebruik je favoriete teksteditor of IDE om het librechat.yaml bestand te openen en te bewerken.

   • Optioneel: gebruik een extern of aangepast bestandspad met de volgende omgevingsvariabele:

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

2. Azure OpenAI-instellingen configureren: Volg de onderstaande structuur om uw Azure OpenAI-instellingen in te vullen, inclusief API-sleutels, exemplaarnamen, modelgroepen en andere configuraties.

3. Verwijder verouderde instellingen: Als je gebruikmaakt van verouderde configuraties, verwijder deze dan. De LibreChat server zal deze ook detecteren en je hieraan herinneren.

4. Sla uw wijzigingen op: Sla het librechat.yaml bestand op.

5. Restart LibreChat: Start je LibreChat applicatie opnieuw op zodat de bijgewerkte configuratie wordt geladen.

Vereiste velden

Om Azure OpenAI te integreren met LibreChat, moeten specifieke velden worden geconfigureerd in je librechat.yaml bestand. Deze velden worden gevalideerd door een combinatie van aangepaste variabelen en omgevingsvariabelen. De gedetailleerde vereisten volgen hieronder.

Configuratie op endpoint-niveau

Algemene Azure-instellingen:

Titel- en gespreksinstellingen:

Groepsconfiguratie:

Aangepaste volgorde (Optioneel):

De customOrder optie is uitgeschakeld (commented out), aangezien deze optioneel is.

Voorbeeld van deze instellingen op endpoint-niveau in uw librechat.yaml bestand:

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)

Groepsniveau-configuratie

De velden die configureerbaar zijn in het Custom Config (librechat.yaml) bestand. Voor meer informatie over elk veld, zie de Azure OpenAI sectie in de Custom Config Docs.

Configuratie op groepsniveau: Groepsidentificatie:

Authenticatie:

Azure OpenAI-instantie:

Deployment-configuratie:

Geavanceerde instellingen:

Modelconfiguratie:

Voorbeeld van een configuratie op groepsniveau in het librechat.yaml bestand:

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)

Model-Level Configuratie

Binnen elke groep bevat het models veld een toewijzing van model-identifiers aan hun configuraties:

Modelidentificatie:

Modelconfiguratie:

Serverless Inference Endpoints:

• De model-identifier moet overeenkomen met de bijbehorende OpenAI-modelnaam om de bekende contextlimieten correct weer te geven en/of te functioneren in het geval van vision. Als u bijvoorbeeld gpt-4-vision wilt gebruiken, moet dit als volgt worden geconfigureerd:

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

• Zie Model Deployments voor meer voorbeelden.

• Als een model is ingesteld op true, impliceert dit het gebruik van de deploymentName en version op groepsniveau voor dit model. Beide moeten in dit geval op groepsniveau zijn gedefinieerd.

• Als een model als object is geconfigureerd, kan het zijn eigen deploymentName en version specificeren. Als deze niet worden verstrekt, erft het model de deploymentName en version van de groep.

• Als de groep een serverless inference endpoint vertegenwoordigt, moet het enkelvoudige model worden ingesteld op true om het toe te voegen aan de modellenlijst.

Bijzondere overwegingen

1. Unieke namen: Zowel model- als groepsnamen moeten uniek zijn in de gehele configuratie. Dubbele namen leiden tot validatiefouten.

2. Ontbrekende vereiste velden: Het ontbreken van de vereiste deploymentName of version, hetzij op groepsniveau (voor modellen met een boolean-vlag) of binnen de configuraties van de modellen (indien niet overgeërfd of expliciet gespecificeerd), zal resulteren in validatiefouten, tenzij de groep een serverless inference endpoint vertegenwoordigt.

3. Omgevingsvariabele-referenties: De configuratie ondersteunt verwijzingen naar omgevingsvariabelen (bijv. ${VARIABLE_NAME}). Zorg ervoor dat alle verwezen variabelen aanwezig zijn in uw omgeving om runtime-fouten te voorkomen. Het ontbreken van gedefinieerde omgevingsvariabelen waarnaar in de configuratie wordt verwezen, zal fouten veroorzaken. ${INSTANCE_NAME} en ${DEPLOYMENT_NAME} zijn unieke tijdelijke aanduidingen en komen niet overeen met omgevingsvariabelen, maar corresponderen in plaats daarvan met de instance- en deployment-naam van het momenteel geselecteerde model. Het wordt niet aanbevolen om INSTANCE_NAME en DEPLOYMENT_NAME als namen voor omgevingsvariabelen te gebruiken om mogelijke conflicten te voorkomen.

4. Foutafhandeling: Eventuele problemen in de configuratie, zoals dubbele namen, niet-gedefinieerde omgevingsvariabelen of ontbrekende verplichte velden, zullen de setup ongeldig maken en beschrijvende foutmeldingen genereren die gericht zijn op een snelle oplossing. Het is niet toegestaan om de server uit te voeren met een ongeldige configuratie.

5. Model-identifiers: Een onbekend model (voor het project) kan worden gebruikt als model-identifier, maar het moet overeenkomen met een bekend model om de bekende contextlengte te weerspiegelen, wat cruciaal is voor de afhandeling van berichten/tokens; bijv. gpt-7000 is geldig, maar zal standaard een limiet van 4k tokens hebben, terwijl gpt-4-turbo zal worden herkend als een model met een contextlimiet van 128k.

Valideer uw configuratie aan de hand van de nieuwste schemadefinities en richtlijnen om de compatibiliteit te behouden.

Model Deployments

De lijst met modellen die beschikbaar zijn voor uw gebruikers wordt bepaald door de modelgroeperingen die zijn gespecificeerd in uw azureOpenAI endpoint config.

Bijvoorbeeld:

# 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

De bovenstaande configuratie zou gpt-4-vision-preview, gpt-3.5-turbo en gpt-4-turbo inschakelen voor uw gebruikers in de volgorde waarin ze zijn gedefinieerd.

Assistants gebruiken met Azure

Om het gebruik van Assistants met Azure OpenAI in te schakelen, zijn er 2 hoofdstappen.

1. Stel het assistants veld, onder het azureOpenAI endpoint, oftewel op Endpoint-niveau, in op true, als volgt:

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

2. Voeg het assistants veld toe aan groepen die compatibel zijn met de Assistants API-integratie van Azure.

• Ten minste één van je groepconfiguraties moet compatibel zijn.
• Je kunt de compatibele regio's en modellen in de Azure-documentatie hier bekijken.
• De versie moet ook "2024-02-15-preview" of later zijn, bij voorkeur later voor toegang tot de nieuwste functies.

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)

Opmerkingen:

• Gebruik voor inloggegevens aangepaste omgevingsvariabelen die zijn opgegeven bij elke configuratie van een assistants-compatibele groep.

• Als je meerdere regio's markeert als assistants-compatible, worden de assistants die je aanmaakt geaggregeerd over de regio's heen naar de hoofdlijst voor assistant-selectie.

• Bestanden die je uploadt naar Azure OpenAI, of dit nu op bericht- of assistentniveau is, zijn alleen beschikbaar in de regio waar het model van de huidige assistent deel van uitmaakt.

  • Om deze reden wordt het aanbevolen om slechts één regio of resourcegroep te gebruiken voor Azure OpenAI Assistants, anders zult u een foutmelding ervaren.
  • Uploaden naar "OpenAI" is het standaardgedrag voor officiële code_interpreter en retrieval functionaliteiten.

• Het downloaden van bestanden die door assistants worden gegenereerd, wordt binnenkort ondersteund.

• Sinds 19 mei 2024 worden retrieval en streaming nog niet ondersteund via Azure OpenAI.

  • Om fouten met retrieval te voorkomen terwijl dit niet wordt ondersteund, is het aanbevolen om de functionaliteit volledig uit te schakelen via de azureAssistants endpoint config:

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

  • Standaard zijn alle mogelijkheden, met uitzondering van retrieval, ingeschakeld.

Plugins gebruiken met Azure

Om het Plugins endpoint te gebruiken met Azure OpenAI, heb je een deployment nodig die function calling ondersteunt. Schakel anders "Functions" uit in de Agent-instellingen. Wanneer je de "functions"-modus niet gebruikt, is het aanbevolen om ook "skip completion" uit te schakelen; dit is een controlestap voor wat de agent heeft gegenereerd.

Om Azure te gebruiken met het Plugins endpoint, zorg ervoor dat het veld plugins is ingesteld op true in je Azure OpenAI endpoint configuratie:

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

Het configureren van het plugins veld zal Plugins configureren om Azure modellen te gebruiken.

LET OP: De huidige configuratie via librechat.yaml gebruikt het primaire model dat je in de frontend selecteert voor Plugin-gebruik. Dit is meestal niet hoe het werkt zonder Azure, waarbij in plaats daarvan het "Agent" model wordt gebruikt. De instelling voor het Agent model kan worden genegeerd bij het gebruik van Plugins via Azure.

Een opgegeven basis-URL gebruiken met Azure

De basis-URL voor Azure OpenAI API-verzoeken kan dynamisch worden geconfigureerd. Dit is handig voor het proxen van services zoals Cloudflare AI Gateway, of als je de baseURL-afhandeling van de app expliciet wilt overschrijven.

LibreChat zal het baseURL veld gebruiken voor uw Azure modelgroepering, welke placeholders kan bevatten voor de Azure OpenAI API instantie- en deploymentnamen.

In de configuratie kan de base URL als volgt worden aangepast:

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

LET OP: ${INSTANCE_NAME} en ${DEPLOYMENT_NAME} zijn unieke tijdelijke aanduidingen en komen niet overeen met omgevingsvariabelen, maar corresponderen in plaats daarvan met de instance- en deployment-naam van het momenteel geselecteerde model. Het wordt niet aanbevolen om INSTANCE_NAME en DEPLOYMENT_NAME als namen voor omgevingsvariabelen te gebruiken om mogelijke conflicten te voorkomen.

Je kunt de placeholders ook volledig weglaten en simpelweg de baseURL met je inloggegevens opbouwen:

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

Tot slot kun je de volledige baseURL opgeven via een aangepaste omgevingsvariabele

      baseURL: "${MY_CUSTOM_BASEURL}"

Automatisch genereren van titels inschakelen met Azure

Om titels voor Azure in te schakelen, zet titleConvo op true.

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

Je kunt ook het model opgeven dat moet worden gebruikt voor het titelen, met titleModel, mits je dit hebt geconfigureerd in je groep(en).

    titleModel: "gpt-3.5-turbo"

Let op: "gpt-3.5-turbo" is de standaardwaarde, dus je kunt deze weglaten als je dit specifieke model wilt gebruiken en het geconfigureerd hebt. Indien niet geconfigureerd en titleConvo is ingesteld op true, zal het proces voor het genereren van titels resulteren in een foutmelding en wordt er geen titel gegenereerd. Je kunt dit ook instellen om dynamisch het huidige model te gebruiken door het in te stellen op current_model.

    titleModel: "current_model"

GPT-4 Vision gebruiken met Azure

Om Vision (afbeeldingsanalyse) te gebruiken met Azure OpenAI, moet je ervoor zorgen dat gpt-4-vision-preview een gespecificeerd model is in een van je groeperingen.

Dit werkt op dezelfde manier als bij het OpenAI endpoint: het is niet nodig om het vision-model te selecteren, aangezien er achter de schermen naar wordt overgeschakeld.

Afbeeldingen genereren met Azure OpenAI Service (DALL-E)

• Eerst moet je een Azure-resource aanmaken die DALL-E host
  • Op het moment van schrijven is dall-e-3 beschikbaar in de SwedenCentral regio, en dall-e-2 in de EastUS regio.
• Vervolgens moet je het model voor het genereren van afbeeldingen implementeren in een van de bovenstaande regio's.
  • Lees de Azure OpenAI Image Generation Quickstart Guide voor verdere ondersteuning
• Configureer uw omgevingsvariabelen op basis van Azure-inloggegevens:

De DALL-E configuratieopties:

DALL-E:

API-sleutels:

API-sleutels (versiespecifiek):

Systeemprompts:

Reverse Proxy-instellingen:

Basis-URL's:

Azure OpenAI-integratie (Optioneel):

Vervang tijdelijke aanduidingstekst door daadwerkelijke prompts of instructies en verstrek uw API-sleutels als u ervoor kiest deze rechtstreeks in het bestand op te nemen (het is aanbevolen om gevoelige sleutels buiten de codebase te beheren). Controleer en respecteer het gebruiksbeleid van OpenAI bij het insluiten van API-sleutels in software.

Let op: als je PROXY hebt ingesteld, wordt deze ook gebruikt voor DALL-E-aanroepen, wat universeel is voor de app.

Serverless Inference Endpoints

Via het librechat.yaml bestand kun je Azure AI Studio serverless inference endpoints configureren om toegang te krijgen tot modellen vanuit de Azure AI Foundry. Alleen een model-identifier, baseURL en apiKey zijn nodig, samen met het serverless veld om aan te geven dat deze endpoints een speciale afhandeling vereisen.

• Je zult de instructies in de compatibele modelkaarten moeten volgen om MaaS ("Models as a Service") toegang in te stellen op Azure AI Studio.

  • Ter referentie, hier zijn enkele bekende compatibele modelkaarten:

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

• Je kunt ook de technische blog voor de "Mistral-large" model release bekijken voor meer informatie.

• Vervolgens moet je ze toevoegen aan je azureOpenAI configuratie in het librechat.yaml bestand.

• Hier is een voorbeeldconfiguratie voor 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

Opmerkingen:

• Azure AI Foundry modellen voorzien nu endpoints onder /models/chat/completions?api-version=version voor serverless inferentie.
  • Het baseURL veld moet worden ingesteld op de root van de endpoint, zonder iets na /models/, oftewel het /chat/completions pad.
  • Voorbeeld: https://example.services.ai.azure.com/models/ voor https://example.services.ai.azure.com/models/chat/completions?api-version=2024-05-01-preview
  • De version query-parameter is optioneel en kan worden opgegeven in het baseURL veld.
• De modelnaam die in het models veld wordt gebruikt, moet overeenkomen met de implementatienaam van het model in de Azure AI Foundry.
• Compatibiliteit met LibreChat is afhankelijk van pariteit met OpenAI API-specificaties, die op het moment van schrijven doorgaans "Pay-as-you-go" of "Models as a Service" (MaaS) implementaties zijn op Azure AI Studio, die OpenAI-SDK-compatibel zijn met ofwel v1/completions of models/chat/completions endpoint-afhandeling.
• Alle modellen die serverless deployments aanbieden ("Serverless APIs") zijn compatibel vanuit de Azure model catalog. Je kunt filteren op "Serverless API" onder Deployment options en "Chat completion" onder inference tasks om de volledige lijst te zien; real-time endpoint modellen zijn echter niet getest.
• Deze serverless inference endpoint/modellen ondersteunen mogelijk wel of niet function calling volgens de OpenAI API specs, wat hun gebruik met Agents mogelijk maakt.