Integrazione Azure OpenAI per LibreChat

LibreChat supporta i servizi API di Azure OpenAI come endpoint di prima classe. Per utilizzare Azure OpenAI all'interno di LibreChat, configura il file librechat.yaml per la tua configurazione. Questo documento illustra il processo di configurazione per l'utilizzo di distribuzioni e modelli multipli.

Esempio

Un esempio di configurazione che include molte delle opzioni e funzionalità descritte di seguito:

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

Questo esempio segue la Documentazione di Configurazione dell'Endpoint Azure OpenAI.

Ogni livello di configurazione è dettagliato nella rispettiva sezione:

1. Configurazione a livello di endpoint

2. Configurazione a livello di gruppo

3. Configurazione a livello di modello

Setup

1. Apri librechat.yaml per la modifica: Usa il tuo editor di testo o IDE preferito per aprire e modificare il file librechat.yaml.

   • Opzionale: utilizza un percorso file remoto o personalizzato con la seguente variabile d'ambiente:

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

2. Configura le impostazioni di Azure OpenAI: Segui la struttura delineata di seguito per popolare le tue impostazioni di Azure OpenAI, inclusi chiavi API, nomi delle istanze, gruppi di modelli e altre configurazioni.

3. Rimuovere le impostazioni legacy: Se stai utilizzando una qualsiasi delle configurazioni legacy, rimuovila. Il server LibreChat le rileverà e te lo ricorderà.

4. Salva le tue modifiche: Salva il file librechat.yaml.

5. Riavvia LibreChat: Riavvia la tua applicazione LibreChat in modo che la configurazione aggiornata venga caricata.

Campi Obbligatori

Per integrare Azure OpenAI con LibreChat, è necessario configurare campi specifici nel file librechat.yaml. Questi campi vengono convalidati attraverso una combinazione di variabili personalizzate e d'ambiente. Di seguito sono riportati i requisiti dettagliati.

Configurazione a livello di endpoint

Impostazioni Globali Azure:

Impostazioni del titolo e della conversazione:

Configurazione del gruppo:

Ordine personalizzato (Opzionale):

L'opzione customOrder è commentata, poiché è facoltativa.

Esempio di queste impostazioni a livello di endpoint nel tuo file 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)

Configurazione a livello di gruppo

I campi configurabili nel file Custom Config (librechat.yaml). Per ulteriori informazioni su ciascun campo, consulta la sezione Azure OpenAI nella documentazione di Custom Config.

Configurazione a livello di gruppo: Identificazione del gruppo:

Autenticazione:

Istanza Azure OpenAI:

Configurazione di Deployment:

Impostazioni avanzate:

Configurazione del modello:

Esempio di una configurazione a livello di gruppo nel file 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)

Configurazione a livello di modello

All'interno di ciascun gruppo, il campo models contiene una mappatura degli identificatori dei modelli verso le relative configurazioni:

Identificazione del modello:

Configurazione del modello:

Endpoint di inferenza serverless:

• L'identificativo del modello deve corrispondere al nome del modello OpenAI corrispondente affinché possa riflettere correttamente i suoi limiti di contesto noti e/o funzionare nel caso della visione. Ad esempio, se intendi utilizzare gpt-4-vision, deve essere configurato in questo modo:

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

• Vedi Model Deployments per ulteriori esempi.

• Se un modello è impostato su true, ciò implica l'utilizzo di deploymentName e version a livello di gruppo per questo modello. In questo caso, entrambi devono essere definiti a livello di gruppo.

• Se un modello è configurato come oggetto, può specificare il proprio deploymentName e version. Se questi non vengono forniti, il modello eredita il deploymentName e la version del gruppo.

• Se il gruppo rappresenta un serverless inference endpoint, il modello singolo deve essere impostato su true per aggiungerlo all'elenco dei modelli.

Considerazioni speciali

1. Nomi univoci: Sia i nomi dei modelli che quelli dei gruppi devono essere univoci nell'intera configurazione. Nomi duplicati portano a errori di convalida.

2. Campi obbligatori mancanti: La mancanza dei campi obbligatori deploymentName o version, sia a livello di gruppo (per i modelli con flag booleano) che all'interno delle configurazioni dei modelli (se non ereditati o specificati esplicitamente), comporterà errori di convalida, a meno che il gruppo non rappresenti un serverless inference endpoint.

3. Riferimenti alle variabili d'ambiente: La configurazione supporta i riferimenti alle variabili d'ambiente (ad esempio, ${VARIABLE_NAME}). Assicurati che tutte le variabili referenziate siano presenti nel tuo ambiente per evitare errori in fase di esecuzione. L'assenza di variabili d'ambiente definite e richiamate nella configurazione causerà degli errori. ${INSTANCE_NAME} e ${DEPLOYMENT_NAME} sono segnaposto univoci e non corrispondono a variabili d'ambiente, bensì al nome dell'istanza e al nome della distribuzione del modello attualmente selezionato. Si sconsiglia l'utilizzo di INSTANCE_NAME e DEPLOYMENT_NAME come nomi di variabili d'ambiente per evitare potenziali conflitti.

4. Gestione degli errori: Qualsiasi problema nella configurazione, come nomi duplicati, variabili d'ambiente non definite o campi obbligatori mancanti, invaliderà l'impostazione e genererà messaggi di errore descrittivi volti a una rapida risoluzione. Non sarà consentito avviare il server con una configurazione non valida.

5. Identificatori di modello: Un modello sconosciuto (al progetto) può essere utilizzato come identificatore di modello, ma deve corrispondere a un modello noto per riflettere la sua lunghezza di contesto nota, il che è fondamentale per la gestione di messaggi/token; ad esempio, gpt-7000 sarà valido ma avrà come impostazione predefinita un limite di 4k token, mentre gpt-4-turbo verrà riconosciuto come avente un limite di contesto di 128k.

Convalida la tua configurazione rispetto alle ultime definizioni di schema e linee guida per mantenere la compatibilità.

Distribuzioni dei modelli

L'elenco dei modelli disponibili per i tuoi utenti è determinato dai raggruppamenti di modelli specificati nella configurazione dell'endpoint azureOpenAI nel tuo file librechat.yaml.

Per esempio:

# 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 configurazione di cui sopra abiliterà gpt-4-vision-preview, gpt-3.5-turbo e gpt-4-turbo per i tuoi utenti nell'ordine in cui sono stati definiti.

Utilizzo degli Assistants con Azure

Per abilitare l'uso degli Assistants con Azure OpenAI, ci sono 2 passaggi principali.

1. Imposta il campo assistants, sotto l'endpoint azureOpenAI, ovvero a livello di Endpoint-level su true, in questo modo:

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

2. Aggiungi il campo assistants ai gruppi compatibili con l'integrazione dell'Assistants API di Azure.

• Almeno una delle tue configurazioni di gruppo deve essere compatibile.
• Puoi controllare le regioni e i modelli compatibili nella documentazione di Azure qui.
• La versione deve essere anche "2024-02-15-preview" o successiva, preferibilmente successiva per l'accesso alle funzionalità più recenti.

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)

Note:

• Per le credenziali, affidati alle variabili d'ambiente personalizzate specificate nella configurazione di ciascun gruppo compatibile con gli assistants.

• Se contrassegni più regioni come compatibili con gli assistenti, gli assistenti che creerai verranno aggregati tra le regioni nell'elenco principale di selezione degli assistenti.

• I file caricati su Azure OpenAI, sia a livello di messaggio che di assistente, saranno disponibili solo nella regione di cui fa parte il modello dell'assistente corrente.

  • Per questo motivo, si consiglia di utilizzare una sola regione o un solo gruppo di risorse per Azure OpenAI Assistants, altrimenti si verificherà un errore.
  • Il caricamento su "OpenAI" è il comportamento predefinito per le funzionalità ufficiali code_interpreter e retrieval.

• Il download dei file generati dagli assistenti sarà presto supportato.

• A partire dal 19 maggio 2024, il retrieval e lo streaming non sono ancora supportati tramite Azure OpenAI.

  • Per evitare errori con il retrieval mentre non è supportato, si consiglia di disabilitare completamente la funzionalità tramite la configurazione dell'endpoint azureAssistants:

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

  • Per impostazione predefinita, tutte le funzionalità, ad eccezione di retrieval, sono abilitate.

Utilizzo dei plugin con Azure

Per utilizzare l'endpoint Plugins con Azure OpenAI, è necessario un deployment che supporti il function calling. In caso contrario, disattiva "Functions" nelle impostazioni dell'Agent. Quando non si utilizza la modalità "functions", si consiglia di disattivare anche "skip completion", che rappresenta una fase di revisione di quanto generato dall'agent.

Per utilizzare Azure con l'endpoint Plugins, assicurati che il campo plugins sia impostato su true nella configurazione del tuo endpoint Azure OpenAI:

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

La configurazione del campo plugins configurerà i Plugin per utilizzare i modelli Azure.

NOTA: La configurazione attuale tramite librechat.yaml utilizza il modello principale selezionato dal frontend per l'uso dei Plugin, il che solitamente non è il modo in cui funziona senza Azure, dove invece viene utilizzato il modello "Agent". L'impostazione del modello Agent può essere ignorata quando si utilizzano i Plugin tramite Azure.

Utilizzo di un Base URL specificato con Azure

L'URL di base per le richieste API di Azure OpenAI può essere configurato dinamicamente. Questo è utile per servizi di proxy come Cloudflare AI Gateway, o se si desidera sovrascrivere esplicitamente la gestione del baseURL dell'app.

LibreChat utilizzerà il campo baseURL per il raggruppamento dei tuoi modelli Azure, che può includere segnaposto per l'istanza dell'API Azure OpenAI e i nomi delle distribuzioni.

Nella configurazione, la base URL può essere personalizzata in questo modo:

# 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} sono segnaposto univoci e non corrispondono a variabili d'ambiente, bensì al nome dell'istanza e del deployment del modello attualmente selezionato. Si sconsiglia di utilizzare INSTANCE_NAME e DEPLOYMENT_NAME come nomi di variabili d'ambiente per evitare potenziali conflitti.

Puoi anche omettere completamente i segnaposto e costruire semplicemente la baseURL con le tue credenziali:

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

Infine, puoi specificare l'intero baseURL tramite una variabile d'ambiente personalizzata

      baseURL: "${MY_CUSTOM_BASEURL}"

Abilitazione dei titoli generati automaticamente con Azure

Per abilitare la titolazione per Azure, imposta titleConvo su true.

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

Puoi anche specificare il modello da utilizzare per la titolazione, con titleModel, a condizione che tu lo abbia configurato nel tuo gruppo (o nei tuoi gruppi).

    titleModel: "gpt-3.5-turbo"

Nota: "gpt-3.5-turbo" è il valore predefinito, quindi puoi ometterlo se desideri utilizzare questo modello specifico e lo hai configurato. Se non è configurato e titleConvo è impostato su true, il processo di titolazione genererà un errore e non verrà creato alcun titolo. Puoi anche impostarlo per utilizzare dinamicamente il modello corrente impostandolo su current_model.

    titleModel: "current_model"

Utilizzo di GPT-4 Vision con Azure

Per utilizzare Vision (analisi delle immagini) con Azure OpenAI, assicurati che gpt-4-vision-preview sia un modello specificato in uno dei tuoi raggruppamenti.

Funziona esattamente come con l'endpoint OpenAI endpoint: non è necessario selezionare il modello vision, poiché verrà commutato automaticamente in background.

Generare immagini con Azure OpenAI Service (DALL-E)

• Per prima cosa devi creare una risorsa Azure che ospiti DALL-E
  • Al momento della stesura di questo documento, dall-e-3 è disponibile nella regione SwedenCentral, mentre dall-e-2 è disponibile nella regione EastUS.
• Successivamente, è necessario distribuire il modello di generazione di immagini in una delle regioni sopra indicate.
  • Leggi la Guida rapida alla generazione di immagini con Azure OpenAI per ulteriore assistenza
• Configura le tue variabili d'ambiente in base alle credenziali Azure:

Le opzioni di configurazione di DALL-E:

DALL-E:

Chiavi API:

Chiavi API (Specifiche per versione):

System Prompts:

Impostazioni del Reverse Proxy:

URL di base:

Integrazione Azure OpenAI (Opzionale):

Sostituisci il testo segnaposto con prompt o istruzioni reali e fornisci le tue chiavi API se scegli di includerle direttamente nel file (si consiglia di gestire le chiavi sensibili al di fuori della codebase). Esamina e rispetta le politiche di utilizzo di OpenAI quando incorpori chiavi API nel software.

Nota: se hai impostato PROXY, verrà utilizzato anche per le chiamate DALL-E, il che è universale per l'app.

Endpoint di inferenza serverless

Tramite il file librechat.yaml, è possibile configurare gli endpoint di inferenza serverless di Azure AI Studio per accedere ai modelli da Azure AI Foundry. Sono necessari solo un identificatore di modello, baseURL e apiKey, insieme al campo serverless per indicare la gestione speciale richiesta da questi endpoint.

• Dovrai seguire le istruzioni nelle schede dei modelli compatibili per configurare l'accesso MaaS ("Models as a Service") su Azure AI Studio.

  • Per riferimento, ecco alcune schede modello compatibili note:

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

• Puoi anche consultare il blog tecnico per il rilascio del modello "Mistral-large" per ulteriori informazioni.

• Successivamente, dovrai aggiungerli alla tua configurazione azureOpenAI nel file librechat.yaml.

• Ecco un esempio di configurazione per 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

Note:

• I modelli Azure AI Foundry ora forniscono endpoint sotto /models/chat/completions?api-version=version per l'inferenza serverless.
  • Il campo baseURL deve essere impostato sulla radice dell'endpoint, senza nulla dopo /models/, ovvero il percorso /chat/completions.
  • Esempio: https://example.services.ai.azure.com/models/ per https://example.services.ai.azure.com/models/chat/completions?api-version=2024-05-01-preview
  • Il parametro di query version è facoltativo e può essere specificato nel campo baseURL.
• Il nome del modello utilizzato nel campo models deve corrispondere al nome della distribuzione del modello in Azure AI Foundry.
• La compatibilità con LibreChat si basa sulla parità con le specifiche dell'API OpenAI, che al momento della stesura di questo documento sono solitamente implementazioni "Pay-as-you-go" o "Models as a Service" (MaaS) su Azure AI Studio, compatibili con l'SDK di OpenAI e che gestiscono l'endpoint v1/completions o models/chat/completions.
• Tutti i modelli che offrono distribuzioni serverless ("Serverless APIs") sono compatibili dal catalogo modelli di Azure. È possibile filtrare per "Serverless API" sotto le opzioni di Deployment e "Chat completion" sotto le attività di inferenza per vedere l'elenco completo; tuttavia, i modelli real time endpoint non sono stati testati.
• Questi endpoint/modelli di inferenza serverless potrebbero supportare o meno la chiamata di funzioni (function calling) secondo le specifiche dell'API OpenAI, il che ne abilita l'utilizzo con gli Agents.