Intégration Azure OpenAI pour LibreChat

LibreChat prend en charge les services Azure OpenAI API en tant qu'endpoint de premier ordre. Pour utiliser Azure OpenAI dans LibreChat, configurez le fichier librechat.yaml pour votre installation. Ce document couvre le processus de configuration pour l'utilisation de plusieurs déploiements et modèles.

Exemple

Un exemple de configuration incluant bon nombre des options et fonctionnalités décrites ci-dessous :

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

Cet exemple suit la documentation de configuration de l'endpoint Azure OpenAI.

Chaque niveau de configuration est détaillé dans sa section respective :

1. Configuration au niveau de l'endpoint

2. Configuration au niveau du groupe

3. Configuration au niveau du modèle

Configuration

1. Ouvrir librechat.yaml pour modification : Utilisez votre éditeur de texte ou IDE préféré pour ouvrir et modifier le fichier librechat.yaml.

   • Optionnel : utilisez un chemin de fichier distant ou personnalisé avec la variable d'environnement suivante :

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

2. Configurer les paramètres Azure OpenAI : Suivez la structure décrite ci-dessous pour renseigner vos paramètres Azure OpenAI, y compris les clés API, les noms d'instance, les groupes de modèles et d'autres configurations.

3. Supprimer les paramètres hérités : Si vous utilisez l'une des configurations héritées, supprimez-les. Le serveur LibreChat les détectera également et vous le rappellera.

4. Enregistrez vos modifications : Enregistrez le fichier librechat.yaml.

5. Redémarrer LibreChat : Redémarrez votre application LibreChat afin que la configuration mise à jour soit chargée.

Champs requis

Pour intégrer Azure OpenAI avec LibreChat, des champs spécifiques doivent être configurés dans votre fichier librechat.yaml. Ces champs sont validés par une combinaison de variables personnalisées et de variables d'environnement. Les exigences détaillées suivent.

Configuration au niveau de l'endpoint

Paramètres Azure globaux :

Paramètres du titre et de la conversation :

Configuration du groupe :

Ordre personnalisé (Optionnel) :

L'option customOrder est mise en commentaire, car elle est facultative.

Exemple de ces paramètres au niveau de l'endpoint dans votre fichier 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)

Configuration au niveau du groupe

Les champs configurables dans le fichier de configuration personnalisée (librechat.yaml). Pour plus d'informations sur chaque champ, consultez la section Azure OpenAI dans la documentation de configuration personnalisée.

Configuration au niveau du groupe : Identification du groupe :

Authentification :

Instance Azure OpenAI :

Configuration du déploiement :

Paramètres avancés :

Configuration du modèle :

Exemple d'une configuration au niveau du groupe dans le fichier 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)

Configuration au niveau du modèle

Au sein de chaque groupe, le champ models contient un mappage des identifiants de modèles vers leurs configurations :

Identification du modèle :

Configuration du modèle :

Endpoints d'inférence serverless :

• L'identifiant du modèle doit correspondre à son nom de modèle OpenAI correspondant afin qu'il reflète correctement ses limites de contexte connues et/ou son fonctionnement dans le cas de la vision. Par exemple, si vous avez l'intention d'utiliser gpt-4-vision, il doit être configuré comme suit :

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

• Voir Model Deployments pour plus d'exemples.

• Si un modèle est défini sur true, cela implique l'utilisation du deploymentName et de la version au niveau du groupe pour ce modèle. Les deux doivent être définis au niveau du groupe dans ce cas.

• Si un modèle est configuré en tant qu'objet, il peut spécifier ses propres deploymentName et version. Si ceux-ci ne sont pas fournis, le modèle hérite du deploymentName et de la version du groupe.

• Si le groupe représente un serverless inference endpoint, le modèle singulier doit être défini sur true pour l'ajouter à la liste des modèles.

Considérations particulières

1. Noms uniques : Les noms de modèles et de groupes doivent être uniques dans l'ensemble de la configuration. Les noms en double entraînent des échecs de validation.

2. Champs requis manquants : L'absence du deploymentName ou de la version requis, soit au niveau du groupe (pour les modèles avec indicateur booléen), soit dans les configurations des modèles (s'ils n'héritent pas ou ne sont pas explicitement spécifiés), entraînera des erreurs de validation, à moins que le groupe ne représente un serverless inference endpoint.

3. Références aux variables d'environnement : La configuration prend en charge les références aux variables d'environnement (par exemple, ${VARIABLE_NAME}). Assurez-vous que toutes les variables référencées sont présentes dans votre environnement pour éviter les erreurs d'exécution. L'absence de variables d'environnement définies et référencées dans la configuration provoquera des erreurs. ${INSTANCE_NAME} et ${DEPLOYMENT_NAME} sont des espaces réservés uniques ; ils ne correspondent pas à des variables d'environnement, mais plutôt au nom de l'instance et au nom du déploiement du modèle actuellement sélectionné. Il n'est pas recommandé d'utiliser INSTANCE_NAME et DEPLOYMENT_NAME comme noms de variables d'environnement afin d'éviter tout conflit potentiel.

4. Gestion des erreurs : Tout problème dans la configuration, tel que des noms en double, des variables d'environnement non définies ou des champs requis manquants, invalidera l'installation et générera des messages d'erreur descriptifs visant une résolution rapide. Vous ne serez pas autorisé à exécuter le serveur avec une configuration invalide.

5. Identifiants de modèle : Un modèle inconnu (du projet) peut être utilisé comme identifiant de modèle, mais il doit correspondre à un modèle connu pour refléter sa longueur de contexte connue, ce qui est crucial pour la gestion des messages/jetons ; par exemple, gpt-7000 sera valide mais utilisera par défaut une limite de 4k jetons, tandis que gpt-4-turbo sera reconnu comme ayant une limite de contexte de 128k.

Validez votre configuration par rapport aux dernières définitions de schéma et directives pour maintenir la compatibilité.

Déploiements de modèles

La liste des modèles disponibles pour vos utilisateurs est déterminée par les regroupements de modèles spécifiés dans votre configuration d'endpoint azureOpenAI.

Par exemple :

# 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

La configuration ci-dessus activerait gpt-4-vision-preview, gpt-3.5-turbo et gpt-4-turbo pour vos utilisateurs dans l'ordre où ils ont été définis.

Utilisation des Assistants avec Azure

Pour activer l'utilisation des Assistants avec Azure OpenAI, il y a 2 étapes principales.

1. Définissez le champ assistants, sous l'endpoint azureOpenAI, c'est-à-dire au niveau de l'endpoint, sur true, comme ceci :

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

2. Ajoutez le champ assistants aux groupes compatibles avec l'intégration de l'Assistants API d'Azure.

• Au moins l'une de vos configurations de groupe doit être compatible.
• Vous pouvez consulter les régions et modèles compatibles dans la documentation Azure ici.
• La version doit également être « 2024-02-15-preview » ou ultérieure, de préférence ultérieure pour accéder aux dernières fonctionnalités.

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)

Notes :

• Pour les identifiants, fiez-vous aux variables d'environnement personnalisées spécifiées dans chaque configuration de groupe compatible avec les assistants.

• Si vous marquez plusieurs régions comme étant compatibles avec les assistants, les assistants que vous créez seront regroupés par région dans la liste principale de sélection des assistants.

• Les fichiers que vous téléchargez sur Azure OpenAI, que ce soit au niveau du message ou de l'assistant, ne seront disponibles que dans la région dont fait partie le modèle de l'assistant actuel.

  • Pour cette raison, il est recommandé d'utiliser une seule région ou un seul groupe de ressources pour les Azure OpenAI Assistants, sous peine de rencontrer une erreur.
  • Le téléchargement vers "OpenAI" est le comportement par défaut pour les fonctionnalités officielles code_interpreter et retrieval.

• Le téléchargement des fichiers générés par les assistants sera bientôt pris en charge.

• Depuis le 19 mai 2024, la récupération (retrieval) et le streaming ne sont pas encore pris en charge via Azure OpenAI.

  • Pour éviter toute erreur avec la récupération (retrieval) alors qu'elle n'est pas prise en charge, il est recommandé de désactiver complètement cette fonctionnalité via la configuration de l'endpoint azureAssistants :

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

  • Par défaut, toutes les fonctionnalités, à l'exception de la récupération (retrieval), sont activées.

Utilisation de plugins avec Azure

Pour utiliser l'endpoint Plugins avec Azure OpenAI, vous avez besoin d'un déploiement prenant en charge le function calling. Sinon, désactivez « Functions » dans les paramètres de l'Agent. Lorsque vous n'utilisez pas le mode « functions », il est également recommandé de désactiver « skip completion », qui est une étape de révision de ce que l'agent a généré.

Pour utiliser Azure avec le endpoint Plugins, assurez-vous que le champ plugins est défini sur true dans votre configuration de endpoint Azure OpenAI :

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

La configuration du champ plugins configurera les Plugins pour utiliser les modèles Azure.

REMARQUE : La configuration actuelle via librechat.yaml utilise le modèle principal que vous sélectionnez depuis l'interface pour l'utilisation des Plugins, ce qui n'est généralement pas le fonctionnement prévu sans Azure, où le modèle "Agent" est utilisé à la place. Le paramètre du modèle Agent peut être ignoré lors de l'utilisation de Plugins via Azure.

Utilisation d'une URL de base spécifiée avec Azure

L'URL de base pour les requêtes API Azure OpenAI peut être configurée dynamiquement. Ceci est utile pour les services de proxy tels que Cloudflare AI Gateway, ou si vous souhaitez remplacer explicitement la gestion de baseURL de l'application.

LibreChat utilisera le champ baseURL pour votre regroupement de modèles Azure, qui peut inclure des espaces réservés pour l'instance de l'API Azure OpenAI et les noms de déploiement.

Dans la configuration, la base URL peut être personnalisée comme suit :

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

REMARQUE : ${INSTANCE_NAME} et ${DEPLOYMENT_NAME} sont des espaces réservés uniques et ne correspondent pas à des variables d'environnement, mais plutôt au nom de l'instance et au nom du déploiement du modèle actuellement sélectionné. Il n'est pas recommandé d'utiliser INSTANCE_NAME et DEPLOYMENT_NAME comme noms de variables d'environnement afin d'éviter tout conflit potentiel.

Vous pouvez également omettre complètement les espaces réservés et simplement construire la baseURL avec vos identifiants :

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

Enfin, vous pouvez spécifier l'intégralité de la baseURL via une variable d'environnement personnalisée

      baseURL: "${MY_CUSTOM_BASEURL}"

Activation des titres générés automatiquement avec Azure

Pour activer la génération de titres pour Azure, définissez titleConvo sur true.

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

Vous pouvez également spécifier le modèle à utiliser pour la génération de titres, avec titleModel, à condition de l'avoir configuré dans votre ou vos groupes.

    titleModel: "gpt-3.5-turbo"

Note : "gpt-3.5-turbo" est la valeur par défaut, vous pouvez donc l'omettre si vous souhaitez utiliser ce modèle exact et qu'il est configuré. S'il n'est pas configuré et que titleConvo est défini sur true, le processus de titrage entraînera une erreur et aucun titre ne sera généré. Vous pouvez également le configurer pour utiliser dynamiquement le modèle actuel en le définissant sur current_model.

    titleModel: "current_model"

Utilisation de GPT-4 Vision avec Azure

Pour utiliser Vision (analyse d'image) avec Azure OpenAI, assurez-vous que gpt-4-vision-preview est un modèle spécifié dans l'un de vos regroupements.

Cela fonctionne de la même manière qu'avec l' endpoint OpenAI : il n'est pas nécessaire de sélectionner le modèle de vision, car il sera commuté en arrière-plan.

Générer des images avec Azure OpenAI Service (DALL-E)

• Vous devez d'abord créer une ressource Azure qui héberge DALL-E
  • Au moment de la rédaction, dall-e-3 est disponible dans la région SwedenCentral, et dall-e-2 dans la région EastUS.
• Ensuite, vous devez déployer le modèle de génération d'images dans l'une des régions ci-dessus.
  • Lisez le Guide de démarrage rapide de la génération d'images Azure OpenAI pour obtenir une assistance supplémentaire.
• Configurez vos variables d'environnement en fonction de vos identifiants Azure :

Les options de configuration de DALL-E :

DALL-E:

Clés API :

Clés API (spécifiques à la version) :

Prompts système :

Paramètres du Reverse Proxy :

URLs de base :

Intégration Azure OpenAI (Optionnel) :

Remplacez le texte fictif par des prompts ou des instructions réels, et fournissez vos clés API si vous choisissez de les inclure directement dans le fichier (il est recommandé de gérer les clés sensibles en dehors de la base de code). Examinez et respectez les politiques d'utilisation d'OpenAI lors de l'intégration de clés API dans un logiciel.

Remarque : si vous avez configuré PROXY, il sera également utilisé pour les appels DALL-E, ce qui est universel pour l'application.

Points de terminaison d'inférence Serverless

Via le fichier librechat.yaml, vous pouvez configurer les endpoints d'inférence serverless d'Azure AI Studio pour accéder aux modèles depuis Azure AI Foundry. Seuls un identifiant de modèle, une baseURL et une apiKey sont nécessaires, accompagnés du champ serverless pour indiquer le traitement spécial requis par ces endpoints.

• Vous devrez suivre les instructions des fiches de modèles compatibles pour configurer l'accès MaaS ("Models as a Service") sur Azure AI Studio.

  • Pour référence, voici quelques fiches de modèles compatibles connues :

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

• Vous pouvez également consulter le blog technique sur la sortie du modèle "Mistral-large" pour plus d'informations.

• Ensuite, vous devrez les ajouter à votre configuration azureOpenAI dans le fichier librechat.yaml.

• Voici un exemple de configuration pour 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

Notes :

• Les modèles Azure AI Foundry provisionnent désormais des endpoints sous /models/chat/completions?api-version=version pour l'inférence sans serveur (serverless).
  • Le champ baseURL doit être défini sur la racine de l'endpoint, sans rien après /models/, c'est-à-dire le chemin /chat/completions.
  • Exemple : https://example.services.ai.azure.com/models/ pour https://example.services.ai.azure.com/models/chat/completions?api-version=2024-05-01-preview
  • Le paramètre de requête version est facultatif et peut être spécifié dans le champ baseURL.
• Le nom du modèle utilisé dans le champ models doit correspondre au nom du déploiement du modèle dans Azure AI Foundry.
• La compatibilité avec LibreChat repose sur la parité avec les spécifications de l'API OpenAI, qui, au moment de la rédaction, sont généralement des déploiements "Pay-as-you-go" ou "Models as a Service" (MaaS) sur Azure AI Studio, compatibles avec le SDK OpenAI et gérant soit le endpoint v1/completions, soit models/chat/completions.
• Tous les modèles proposant des déploiements sans serveur (« Serverless APIs ») sont compatibles depuis le catalogue de modèles Azure. Vous pouvez filtrer par « Serverless API » sous les options de déploiement et « Chat completion » sous les tâches d'inférence pour voir la liste complète ; cependant, les modèles de point de terminaison en temps réel n'ont pas été testés.
• Ces endpoint/modèles d'inférence serverless peuvent ou non prendre en charge l'appel de fonction selon les spécifications de l'API OpenAI, ce qui permet leur utilisation avec des Agents.