Integración de Azure OpenAI para LibreChat

LibreChat admite los servicios de la API de Azure OpenAI como un endpoint de primera clase. Para usar Azure OpenAI dentro de LibreChat, configure el archivo librechat.yaml para su instalación. Este documento cubre el proceso de configuración para utilizar múltiples despliegues y modelos.

Ejemplo

Un ejemplo de configuración que incluye muchas de las opciones y características descritas a continuación:

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

Este ejemplo sigue la Documentación de configuración del endpoint de Azure OpenAI.

Cada nivel de configuración se detalla en su sección respectiva:

1. Configuración a nivel de endpoint

2. Configuración a nivel de grupo

3. Configuración a nivel de modelo

Configuración

1. Abrir librechat.yaml para editar: Utilice su editor de texto o IDE preferido para abrir y editar el archivo librechat.yaml.

   • Opcional: utilice una ruta de archivo remota o personalizada con la siguiente variable de entorno:

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

2. Configurar los ajustes de Azure OpenAI: Siga la estructura descrita a continuación para completar sus ajustes de Azure OpenAI, incluyendo claves de API, nombres de instancia, grupos de modelos y otras configuraciones.

3. Eliminar configuraciones heredadas: Si está utilizando alguna de las configuraciones heredadas, elimínelas. El servidor de LibreChat también las detectará y se lo recordará.

4. Guarda tus cambios: Guarda el archivo librechat.yaml.

5. Reiniciar LibreChat: Reinicie su aplicación LibreChat para que se cargue la configuración actualizada.

Campos obligatorios

Para integrar Azure OpenAI con LibreChat, se deben configurar campos específicos en su archivo librechat.yaml. Estos campos se validan mediante una combinación de variables personalizadas y de entorno. A continuación, se detallan los requisitos.

Configuración a nivel de endpoint

Configuración global de Azure:

Configuración de Título y Conversación:

Configuración de grupo:

Orden personalizada (Opcional):

La opción customOrder está comentada, ya que es opcional.

Ejemplo de estos ajustes a nivel de endpoint en su archivo 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)

Configuración a nivel de grupo

Los campos configurables en el archivo de Custom Config (librechat.yaml). Para obtener más información sobre cada campo, consulta la sección de Azure OpenAI en la documentación de Custom Config.

Configuración a nivel de grupo: Identificación de grupo:

Autenticación:

Instancia de Azure OpenAI:

Configuración de despliegue:

Configuración avanzada:

Configuración del modelo:

Ejemplo de una configuración a nivel de grupo en el archivo 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)

Configuración a nivel de modelo

Dentro de cada grupo, el campo models contiene un mapeo de los identificadores de modelo a sus configuraciones:

Identificación del modelo:

Configuración del modelo:

Endpoints de inferencia Serverless:

• El identificador del modelo debe coincidir con su nombre de modelo de OpenAI correspondiente para que pueda reflejar correctamente sus límites de contexto conocidos y/o funcionar en el caso de visión. Por ejemplo, si tiene la intención de usar gpt-4-vision, debe configurarse de la siguiente manera:

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

• Consulta Model Deployments para ver más ejemplos.

• Si un modelo se establece en true, implica el uso de deploymentName y version a nivel de grupo para este modelo. Ambos deben estar definidos a nivel de grupo en este caso.

• Si un modelo está configurado como un objeto, puede especificar su propio deploymentName y version. Si estos no se proporcionan, el modelo hereda el deploymentName y la version del grupo.

• Si el grupo representa un serverless inference endpoint, el modelo singular debe establecerse en true para añadirlo a la lista de modelos.

Consideraciones especiales

1. Nombres únicos: Tanto los nombres de los modelos como los de los grupos deben ser únicos en toda la configuración. Los nombres duplicados provocan errores de validación.

2. Campos obligatorios faltantes: La falta del campo obligatorio deploymentName o version, ya sea a nivel de grupo (para modelos marcados con indicadores booleanos) o dentro de las configuraciones de los modelos (si no se heredan o especifican explícitamente), resultará en errores de validación, a menos que el grupo represente un serverless inference endpoint.

3. Referencias a variables de entorno: La configuración admite referencias a variables de entorno (p. ej., ${VARIABLE_NAME}). Asegúrese de que todas las variables referenciadas estén presentes en su entorno para evitar errores en tiempo de ejecución. La ausencia de variables de entorno definidas que se referencien en la configuración provocará errores. ${INSTANCE_NAME} y ${DEPLOYMENT_NAME} son marcadores de posición únicos y no corresponden a variables de entorno, sino que corresponden al nombre de la instancia y al nombre del despliegue del modelo seleccionado actualmente. No se recomienda utilizar INSTANCE_NAME y DEPLOYMENT_NAME como nombres de variables de entorno para evitar posibles conflictos.

4. Manejo de errores: Cualquier problema en la configuración, como nombres duplicados, variables de entorno no definidas o campos obligatorios faltantes, invalidará la configuración y generará mensajes de error descriptivos con el objetivo de lograr una resolución rápida. No se le permitirá ejecutar el servidor con una configuración no válida.

5. Identificadores de modelo: Se puede utilizar un modelo desconocido (para el proyecto) como identificador de modelo, pero debe coincidir con un modelo conocido para reflejar su longitud de contexto conocida, lo cual es crucial para el manejo de mensajes/tokens; por ejemplo, gpt-7000 será válido pero utilizará por defecto un límite de 4k tokens, mientras que gpt-4-turbo será reconocido como poseedor de un límite de contexto de 128k.

Valide su configuración con las definiciones de esquema y directrices más recientes para mantener la compatibilidad.

Despliegues de modelos

La lista de modelos disponibles para sus usuarios está determinada por las agrupaciones de modelos especificadas en la configuración de su endpoint azureOpenAI.

Por ejemplo:

# 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 configuración anterior habilitaría gpt-4-vision-preview, gpt-3.5-turbo y gpt-4-turbo para sus usuarios en el orden en que fueron definidos.

Uso de Assistants con Azure

Para habilitar el uso de Assistants con Azure OpenAI, hay 2 pasos principales.

1. Establezca el campo assistants, bajo el endpoint azureOpenAI, es decir, en el Endpoint-level a true, de la siguiente manera:

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

2. Agregue el campo assistants a los grupos compatibles con la integración de la Assistants API de Azure.

• Al menos una de tus configuraciones de grupo debe ser compatible.
• Puedes consultar las regiones y modelos compatibles en la documentación de Azure aquí.
• La versión también debe ser "2024-02-15-preview" o posterior, preferiblemente posterior para acceder a las funciones más recientes.

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)

Notas:

• Para las credenciales, confíe en las variables de entorno personalizadas especificadas en cada configuración de grupo compatible con assistants.

• Si marcas varias regiones como compatibles con assistants, los assistants que crees se agregarán a través de las regiones a la lista principal de selección de assistants.

• Los archivos que subas a Azure OpenAI, ya sea a nivel de mensaje o de asistente, solo estarán disponibles en la región a la que pertenece el modelo del asistente actual.

  • Por esta razón, se recomienda utilizar solo una región o grupo de recursos para Azure OpenAI Assistants, o experimentará un error.
  • La carga a "OpenAI" es el comportamiento predeterminado para las capacidades oficiales de code_interpreter y retrieval.

• Pronto será posible descargar los archivos que generan los assistants.

• A partir del 19 de mayo de 2024, la recuperación (retrieval) y el streaming aún no son compatibles a través de Azure OpenAI.

  • Para evitar cualquier error con la recuperación mientras no sea compatible, se recomienda deshabilitar la capacidad por completo a través de la configuración del endpoint azureAssistants:

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

  • De forma predeterminada, todas las capacidades, excepto retrieval, están habilitadas.

Uso de Plugins con Azure

Para usar el endpoint Plugins con Azure OpenAI, necesitas un despliegue que sea compatible con function calling. De lo contrario, desactiva "Functions" en la configuración del Agente. Cuando no estés usando el modo "functions", se recomienda también desactivar "skip completion", el cual es un paso de revisión de lo que el agente generó.

Para usar Azure con el endpoint Plugins, asegúrate de que el campo plugins esté configurado como true en tu configuración del endpoint de Azure OpenAI:

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

Configurar el campo plugins configurará los Plugins para usar modelos de Azure.

NOTA: La configuración actual a través de librechat.yaml utiliza el modelo principal que seleccionas desde la interfaz para el uso de Plugins, lo cual no es usualmente cómo funciona sin Azure, donde en su lugar se utiliza el modelo "Agent". La configuración del modelo Agent puede ignorarse al utilizar Plugins a través de Azure.

Uso de una URL base especificada con Azure

La URL base para las solicitudes de la API de Azure OpenAI se puede configurar de forma dinámica. Esto es útil para servicios de proxy como Cloudflare AI Gateway, o si desea anular explícitamente el manejo de la baseURL de la aplicación.

LibreChat utilizará el campo baseURL para su agrupación de modelos de Azure, el cual puede incluir marcadores de posición para la instancia de la API de Azure OpenAI y los nombres de despliegue.

En la configuración, la base URL se puede personalizar de la siguiente manera:

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

NOTA: ${INSTANCE_NAME} y ${DEPLOYMENT_NAME} son marcadores de posición únicos y no corresponden a variables de entorno, sino que corresponden al nombre de la instancia y al nombre del despliegue del modelo seleccionado actualmente. No se recomienda utilizar INSTANCE_NAME y DEPLOYMENT_NAME como nombres de variables de entorno para evitar posibles conflictos.

También puede omitir los marcadores de posición por completo y simplemente construir la baseURL con sus credenciales:

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

Por último, puede especificar el baseURL completo a través de una variable de entorno personalizada

      baseURL: "${MY_CUSTOM_BASEURL}"

Habilitar títulos generados automáticamente con Azure

Para habilitar la creación de títulos para Azure, establezca titleConvo en true.

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

También puede especificar el modelo a utilizar para los títulos, con titleModel, siempre que lo haya configurado en su(s) grupo(s).

    titleModel: "gpt-3.5-turbo"

Nota: "gpt-3.5-turbo" es el valor predeterminado, por lo que puede omitirlo si desea utilizar este modelo exacto y lo tiene configurado. Si no está configurado y titleConvo está establecido en true, el proceso de titulación resultará en un error y no se generará ningún título. También puede configurarlo para usar dinámicamente el modelo actual estableciéndolo en current_model.

    titleModel: "current_model"

Uso de GPT-4 Vision con Azure

Para usar Vision (análisis de imágenes) con Azure OpenAI, asegúrese de que gpt-4-vision-preview sea un modelo especificado en uno de sus grupos.

Esto funciona de la misma manera que con el endpoint de OpenAI: no es necesario seleccionar el modelo de visión, ya que se cambiará automáticamente en segundo plano.

Generar imágenes con Azure OpenAI Service (DALL-E)

• Primero necesitas crear un recurso de Azure que aloje DALL-E
  • En el momento de escribir este documento, dall-e-3 está disponible en la región SwedenCentral, y dall-e-2 en la región EastUS.
• Luego, debes implementar el modelo de generación de imágenes en una de las regiones anteriores.
  • Lea la Guía de inicio rápido de generación de imágenes de Azure OpenAI para obtener asistencia adicional.
• Configure sus variables de entorno según las credenciales de Azure:

Las opciones de configuración de DALL-E:

DALL-E:

Claves de API:

Claves de API (específicas de la versión):

System Prompts:

Configuración de Proxy Inverso:

URLs base:

Integración de Azure OpenAI (Opcional):

Reemplace el texto de marcador de posición con prompts o instrucciones reales, y proporcione sus claves de API si decide incluirlas directamente en el archivo (se recomienda gestionar las claves confidenciales fuera del código base). Revise y respete las políticas de uso de OpenAI al integrar claves de API en el software.

Nota: si tiene configurado PROXY, también se utilizará para las llamadas a DALL-E, lo cual es universal para la aplicación.

Serverless Inference Endpoints

A través del archivo librechat.yaml, puede configurar los endpoints de inferencia serverless de Azure AI Studio para acceder a modelos desde Azure AI Foundry. Solo se necesitan un identificador de modelo, baseURL y apiKey, junto con el campo serverless para indicar el manejo especial que requieren estos endpoints.

• Deberás seguir las instrucciones en las tarjetas de modelo compatibles para configurar el acceso a MaaS ("Models as a Service") en Azure AI Studio.

  • Como referencia, aquí hay algunas tarjetas de modelo compatibles conocidas:

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

• También puedes revisar el blog técnico sobre el lanzamiento del modelo "Mistral-large" para obtener más información.

• Luego, deberás agregarlos a tu configuración azureOpenAI en el archivo librechat.yaml.

• Aquí tienes un ejemplo de configuración para 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

Notas:

• Los modelos de Azure AI Foundry ahora aprovisionan endpoints bajo /models/chat/completions?api-version=version para inferencia sin servidor (serverless).
  • El campo baseURL debe establecerse en la raíz del endpoint, sin nada después de /models/, es decir, la ruta /chat/completions.
  • Ejemplo: https://example.services.ai.azure.com/models/ para https://example.services.ai.azure.com/models/chat/completions?api-version=2024-05-01-preview
  • El parámetro de consulta version es opcional y puede especificarse en el campo baseURL.
• El nombre del modelo utilizado en el campo models debe coincidir con el nombre de despliegue del modelo en Azure AI Foundry.
• La compatibilidad con LibreChat depende de la paridad con las especificaciones de la API de OpenAI, las cuales, al momento de redactar este documento, suelen ser implementaciones de "Pago por uso" o "Modelos como servicio" (MaaS) en Azure AI Studio, que son compatibles con el SDK de OpenAI mediante el manejo del endpoint v1/completions o models/chat/completions.
• Todos los modelos que ofrecen implementaciones sin servidor ("Serverless APIs") son compatibles desde el catálogo de modelos de Azure. Puedes filtrar por "Serverless API" en las opciones de Deployment y "Chat completion" en las tareas de inferencia para ver la lista completa; sin embargo, los modelos de real time endpoint no han sido probados.
• Estos endpoint/modelos de inferencia serverless pueden o no admitir llamadas a funciones (function calling) de acuerdo con las especificaciones de la API de OpenAI, lo que permite su uso con Agents.