Integração do Azure OpenAI para o LibreChat

O LibreChat oferece suporte aos serviços da Azure OpenAI API como um endpoint de primeira classe. Para usar a Azure OpenAI no LibreChat, configure o arquivo librechat.yaml para sua instalação. Este documento aborda o processo de configuração para usar múltiplas implantações e modelos.

Exemplo

Um exemplo de configuração incluindo muitas das opções e recursos descritos abaixo:

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 exemplo segue a Documentação de Configuração de Endpoint do Azure OpenAI.

Cada nível de configuração está detalhado em sua respectiva seção:

1. Configuração em nível de endpoint

2. Configuração em nível de grupo

3. Configuração em nível de modelo

Configuração

1. Abra o librechat.yaml para edição: Use seu editor de texto ou IDE de preferência para abrir e editar o arquivo librechat.yaml.

   • Opcional: use um caminho de arquivo remoto ou personalizado com a seguinte variável de ambiente:

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

2. Configurar as definições do Azure OpenAI: Siga a estrutura descrita abaixo para preencher as suas definições do Azure OpenAI, incluindo chaves de API, nomes de instâncias, grupos de modelos e outras configurações.

3. Remover Configurações Legadas: Se você estiver usando qualquer uma das configurações legadas, remova-as. O servidor LibreChat também detectará isso e o lembrará.

4. Salve suas alterações: Salve o arquivo librechat.yaml.

5. Reinicie o LibreChat: Reinicie sua aplicação LibreChat para que a configuração atualizada seja carregada.

Campos Obrigatórios

Para integrar o Azure OpenAI ao LibreChat, campos específicos devem ser configurados no seu arquivo librechat.yaml. Esses campos são validados por meio de uma combinação de variáveis personalizadas e de ambiente. Os requisitos detalhados seguem abaixo.

Configuração em Nível de Endpoint

Configurações Globais do Azure:

Configurações de Título e Conversa:

Configuração de Grupo:

Ordem Personalizada (Opcional):

A opção customOrder está comentada, pois é opcional.

Exemplo dessas configurações em nível de endpoint no seu arquivo 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)

Configuração em Nível de Grupo

Os campos configuráveis no arquivo de Configuração Personalizada (librechat.yaml). Para mais informações sobre cada campo, consulte a seção Azure OpenAI na Documentação de Configuração Personalizada.

Configuração em Nível de Grupo: Identificação de Grupo:

Autenticação:

Instância do Azure OpenAI:

Configuração de Implantação:

Configurações Avançadas:

Configuração do Modelo:

Exemplo de uma configuração em nível de grupo no arquivo 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)

Configuração em Nível de Modelo

Dentro de cada grupo, o campo models contém um mapeamento de identificadores de modelo para suas configurações:

Identificação do Modelo:

Configuração do Modelo:

Endpoints de Inferência Serverless:

• O identificador do modelo deve corresponder ao seu nome de modelo OpenAI correspondente para que ele reflita corretamente seus limites de contexto conhecidos e/ou funcione no caso de visão. Por exemplo, se você pretende usar o gpt-4-vision, ele deve ser configurado da seguinte forma:

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

• Veja Model Deployments para mais exemplos.

• Se um modelo estiver definido como true, isso implica o uso do deploymentName e da version de nível de grupo para este modelo. Ambos devem ser definidos no nível do grupo neste caso.

• Se um modelo for configurado como um objeto, ele pode especificar seu próprio deploymentName e version. Se estes não forem fornecidos, o modelo herda o deploymentName e a version do grupo.

• Se o grupo representar um serverless inference endpoint, o modelo singular deve ser definido como true para adicioná-lo à lista de modelos.

Considerações Especiais

1. Nomes Únicos: Tanto os nomes dos modelos quanto os dos grupos devem ser únicos em toda a configuração. Nomes duplicados levam a falhas de validação.

2. Campos Obrigatórios Ausentes: A falta de deploymentName ou version obrigatórios, seja no nível do grupo (para modelos com sinalização booleana) ou dentro das configurações dos modelos (se não estiverem herdando ou especificados explicitamente), resultará em erros de validação, a menos que o grupo represente um serverless inference endpoint.

3. Referências de Variáveis de Ambiente: A configuração suporta referências de variáveis de ambiente (por exemplo, ${VARIABLE_NAME}). Certifique-se de que todas as variáveis referenciadas estejam presentes em seu ambiente para evitar erros de tempo de execução. A ausência de variáveis de ambiente definidas que sejam referenciadas na configuração causará erros. ${INSTANCE_NAME} e ${DEPLOYMENT_NAME} são placeholders únicos e não correspondem a variáveis de ambiente, mas sim ao nome da instância e ao nome da implantação do modelo selecionado atualmente. Não é recomendado que você use INSTANCE_NAME e DEPLOYMENT_NAME como nomes de variáveis de ambiente para evitar quaisquer conflitos potenciais.

4. Tratamento de Erros: Quaisquer problemas na configuração, como nomes duplicados, variáveis de ambiente indefinidas ou campos obrigatórios ausentes, invalidarão a configuração e gerarão mensagens de erro descritivas visando uma resolução rápida. Você não terá permissão para executar o servidor com uma configuração inválida.

5. Identificadores de modelo: Um modelo desconhecido (para o projeto) pode ser usado como um identificador de modelo, mas ele deve corresponder a um modelo conhecido para refletir seu tamanho de contexto conhecido, o que é crucial para o tratamento de mensagens/tokens; por exemplo, gpt-7000 será válido, mas usará um limite padrão de 4k tokens, enquanto gpt-4-turbo será reconhecido como tendo um limite de contexto de 128k.

Valide sua configuração em relação às definições de esquema e diretrizes mais recentes para manter a compatibilidade.

Implantações de Modelos

A lista de modelos disponíveis para seus usuários é determinada pelos agrupamentos de modelos especificados na configuração do seu endpoint azureOpenAI.

Por exemplo:

# 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

A configuração acima habilitaria gpt-4-vision-preview, gpt-3.5-turbo e gpt-4-turbo para seus usuários na ordem em que foram definidos.

Usando Assistants com Azure

Para habilitar o uso de Assistants com Azure OpenAI, existem 2 etapas principais.

1. Defina o campo assistants, abaixo do endpoint azureOpenAI, ou seja, no Endpoint-level como true, desta forma:

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

2. Adicione o campo assistants aos grupos compatíveis com a integração da Assistants API do Azure.

• Pelo menos uma das suas configurações de grupo deve ser compatível.
• Você pode verificar as regiões e modelos compatíveis na documentação do Azure aqui.
• A versão também deve ser "2024-02-15-preview" ou posterior, preferencialmente posterior para acesso aos recursos mais recentes.

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 credenciais, utilize variáveis de ambiente personalizadas especificadas em cada configuração de grupo compatível com assistants.

• Se você marcar várias regiões como compatíveis com assistants, os assistants que você criar serão agregados entre as regiões na lista principal de seleção de assistants.

• Os arquivos que você envia para o Azure OpenAI, seja no nível de mensagem ou de assistente, estarão disponíveis apenas na região da qual o modelo do assistente atual faz parte.

  • Por esse motivo, é recomendado que você utilize apenas uma região ou grupo de recursos para o Azure OpenAI Assistants, ou você encontrará um erro.
  • O upload para o "OpenAI" é o comportamento padrão para as capacidades oficiais de code_interpreter e retrieval.

• O download de arquivos gerados por assistentes terá suporte em breve.

• A partir de 19 de maio de 2024, retrieval e streaming ainda não são suportados através do Azure OpenAI.

  • Para evitar quaisquer erros com a recuperação (retrieval) enquanto ela não for suportada, recomenda-se desativar a funcionalidade completamente através da configuração do endpoint azureAssistants:

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

  • Por padrão, todos os recursos, exceto a recuperação (retrieval), estão habilitados.

Usando Plugins com Azure

Para usar o endpoint Plugins com o Azure OpenAI, você precisa de uma implantação que suporte function calling. Caso contrário, desative "Functions" nas configurações do Agent. Quando você não estiver usando o modo "functions", é recomendado também manter "skip completion" desativado, que é uma etapa de revisão do que o agente gerou.

Para usar o Azure com o endpoint Plugins, certifique-se de que o campo plugins esteja definido como true na configuração do seu endpoint do Azure OpenAI:

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

Configurar o campo plugins configurará os Plugins para usar modelos Azure.

NOTA: A configuração atual através do librechat.yaml usa o modelo principal que você seleciona no frontend para o uso de Plugins, o que geralmente não é como funciona sem o Azure, onde, em vez disso, o modelo "Agent" é usado. A configuração do modelo Agent pode ser ignorada ao usar Plugins através do Azure.

Usando uma Base URL Especificada com Azure

A URL base para solicitações da API do Azure OpenAI pode ser configurada dinamicamente. Isso é útil para serviços de proxy, como o Cloudflare AI Gateway, ou se você desejar substituir explicitamente o tratamento da baseURL do aplicativo.

O LibreChat usará o campo baseURL para o seu agrupamento de modelos Azure, que pode incluir espaços reservados para a instância da API do Azure OpenAI e nomes de implantação.

Na configuração, a base URL pode ser personalizada da seguinte forma:

# 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} e ${DEPLOYMENT_NAME} são espaços reservados únicos e não correspondem a variáveis de ambiente, mas sim ao nome da instância e ao nome da implantação do modelo selecionado atualmente. Não é recomendado que você use INSTANCE_NAME e DEPLOYMENT_NAME como nomes de variáveis de ambiente para evitar quaisquer conflitos potenciais.

Você também pode omitir os placeholders completamente e simplesmente construir a baseURL com suas credenciais:

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

Por fim, você pode especificar a baseURL inteira por meio de uma variável de ambiente personalizada

      baseURL: "${MY_CUSTOM_BASEURL}"

Habilitando Títulos Gerados Automaticamente com Azure

Para habilitar a geração de títulos para Azure, defina titleConvo como true.

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

Você também pode especificar o modelo a ser usado para a criação de títulos, com titleModel, desde que você o tenha configurado em seu(s) grupo(s).

    titleModel: "gpt-3.5-turbo"

Nota: "gpt-3.5-turbo" é o valor padrão, portanto você pode omiti-lo se quiser usar este modelo exato e já o tiver configurado. Se não estiver configurado e titleConvo estiver definido como true, o processo de criação de título resultará em um erro e nenhum título será gerado. Você também pode definir isso para usar dinamicamente o modelo atual, configurando-o como current_model.

    titleModel: "current_model"

Usando o GPT-4 Vision com Azure

Para usar Vision (análise de imagem) com Azure OpenAI, certifique-se de que gpt-4-vision-preview seja um modelo especificado em um de seus agrupamentos.

Isso funciona da mesma forma que com o endpoint OpenAI: não há necessidade de selecionar o modelo de visão, pois ele será alternado nos bastidores.

Gerar imagens com o Azure OpenAI Service (DALL-E)

• Primeiro, você precisa criar um recurso Azure que hospede o DALL-E
  • No momento da redação deste documento, o dall-e-3 está disponível na região SwedenCentral, e o dall-e-2 na região EastUS.
• Em seguida, você precisa implantar o modelo de geração de imagem em uma das regiões acima.
  • Leia o Azure OpenAI Image Generation Quickstart Guide para obter assistência adicional
• Configure suas variáveis de ambiente com base nas credenciais do Azure:

As opções de configuração do DALL-E:

DALL-E:

Chaves de API:

Chaves de API (Específicas da Versão):

System Prompts:

Configurações de Reverse Proxy:

Base URLs:

Integração com Azure OpenAI (Opcional):

Substitua o texto de exemplo por prompts ou instruções reais e forneça suas chaves de API caso opte por incluí-las diretamente no arquivo (recomenda-se gerenciar chaves sensíveis fora da base de código). Revise e respeite as políticas de uso da OpenAI ao incorporar chaves de API em softwares.

Nota: se você tiver um PROXY definido, ele também será usado para chamadas DALL-E, o que é universal para o aplicativo.

Serverless Inference Endpoints

Por meio do arquivo librechat.yaml, você pode configurar endpoints de inferência serverless do Azure AI Studio para acessar modelos do Azure AI Foundry. Apenas um identificador de modelo, baseURL e apiKey são necessários, juntamente com o campo serverless para indicar o tratamento especial que esses endpoints exigem.

• Você precisará seguir as instruções nos cartões de modelo compatíveis para configurar o acesso MaaS ("Models as a Service") no Azure AI Studio.

  • Para referência, aqui estão alguns cartões de modelo compatíveis conhecidos:

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

• Você também pode conferir o blog técnico sobre o lançamento do modelo "Mistral-large" para mais informações.

• Em seguida, você precisará adicioná-los à sua configuração azureOpenAI no arquivo librechat.yaml.

• Aqui está um exemplo de configuração para o 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:

• Os modelos do Azure AI Foundry agora provisionam endpoints em /models/chat/completions?api-version=version para inferência serverless.
  • O campo baseURL deve ser definido como a raiz do endpoint, sem nada após /models/, ou seja, o caminho /chat/completions.
  • Exemplo: https://example.services.ai.azure.com/models/ para https://example.services.ai.azure.com/models/chat/completions?api-version=2024-05-01-preview
  • O parâmetro de consulta version é opcional e pode ser especificado no campo baseURL.
• O nome do modelo usado no campo models deve corresponder ao nome da implantação do modelo no Azure AI Foundry.
• A compatibilidade com o LibreChat depende da paridade com as especificações da API da OpenAI, que no momento da redação deste documento, são tipicamente implantações "Pay-as-you-go" ou "Models as a Service" (MaaS) no Azure AI Studio, que são compatíveis com o OpenAI-SDK com tratamento de endpoint v1/completions ou models/chat/completions.
• Todos os modelos que oferecem implantações serverless ("Serverless APIs") são compatíveis a partir do catálogo de modelos do Azure. Você pode filtrar por "Serverless API" em Deployment options e "Chat completion" em inference tasks para ver a lista completa; no entanto, modelos de real time endpoint não foram testados.
• Estes endpoints/modelos de inferência serverless podem ou não oferecer suporte a function calling de acordo com as especificações da OpenAI API, o que permite seu uso com Agents.