LibreChat için Azure OpenAI Entegrasyonu

LibreChat, Azure OpenAI API hizmetlerini birinci sınıf bir endpoint olarak destekler. LibreChat içinde Azure OpenAI kullanmak için, kurulumunuza uygun şekilde librechat.yaml dosyasını yapılandırın. Bu belge, birden fazla dağıtım ve model kullanmaya yönelik kurulum sürecini kapsamaktadır.

Örnek

Aşağıda açıklanan birçok seçenek ve özelliği içeren örnek bir yapılandırma:

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

Bu örnek, Azure OpenAI Endpoint Configuration Docs dokümanını takip eder.

Yapılandırmanın her seviyesi ilgili bölümünde detaylandırılmıştır:

1. Endpoint-seviyesi yapılandırma

2. Grup düzeyi yapılandırma

3. Model düzeyi yapılandırması

Kurulum

1. librechat.yaml dosyasını düzenlemek için açın: librechat.yaml dosyasını açmak ve düzenlemek için tercih ettiğiniz metin düzenleyiciyi veya IDE'yi kullanın.

   • İsteğe bağlı: aşağıdaki ortam değişkeni ile uzak veya özel bir dosya yolu kullanın:

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

2. Azure OpenAI Ayarlarını Yapılandırma: API anahtarları, örnek adları, model grupları ve diğer yapılandırmalar dahil olmak üzere Azure OpenAI ayarlarınızı doldurmak için aşağıda belirtilen yapıyı izleyin.

3. Eski Ayarları Kaldırın: Eğer herhangi bir eski yapılandırma kullanıyorsanız, bunları kaldırın. LibreChat sunucusu bunları algılayacak ve size hatırlatacaktır.

4. Değişikliklerinizi Kaydedin: librechat.yaml dosyasını kaydedin.

5. LibreChat'i Yeniden Başlatın: Güncellenen yapılandırmanın yüklenmesi için LibreChat uygulamanızı yeniden başlatın.

Gerekli Alanlar

Azure OpenAI'yi LibreChat ile entegre etmek için librechat.yaml dosyanızda belirli alanların yapılandırılması gerekir. Bu alanlar, özel değişkenler ve ortam değişkenlerinin bir kombinasyonu aracılığıyla doğrulanır. Ayrıntılı gereksinimler aşağıdadır.

Endpoint-Level Configuration

Global Azure Ayarları:

Başlık ve Sohbet Ayarları:

Grup Yapılandırması:

Özel Sıralama (İsteğe bağlı):

customOrder seçeneği isteğe bağlı olduğu için yorum satırı haline getirilmiştir.

librechat.yaml dosyanızdaki bu endpoint düzeyindeki ayarlara bir örnek:

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)

Grup Düzeyinde Yapılandırma

Özel Yapılandırma (librechat.yaml) dosyasında yapılandırılabilir alanlar. Her bir alan hakkında daha fazla bilgi için Özel Yapılandırma Belgelerindeki Azure OpenAI bölümüne bakın.

Grup Düzeyinde Yapılandırma: Grup Tanımlama:

Kimlik Doğrulama:

Azure OpenAI Örneği:

Dağıtım Yapılandırması:

Gelişmiş Ayarlar:

Model Yapılandırması:

librechat.yaml dosyasındaki grup düzeyi yapılandırma örneği:

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 Düzeyinde Yapılandırma

Her grubun içinde, models alanı, model tanımlayıcılarının yapılandırmalarıyla eşleşmesini içerir:

Model Tanımlama:

Model Yapılandırması:

Serverless Inference Endpoints:

• Model tanımlayıcısı, bilinen bağlam sınırlarını doğru bir şekilde yansıtması ve/veya vision (görüntü) durumunda işlev görmesi için ilgili OpenAI model adıyla eşleşmelidir. Örneğin, gpt-4-vision kullanmak istiyorsanız, şu şekilde yapılandırılmalıdır:

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

• Daha fazla örnek için Model Deployments bölümüne bakın.

• Bir model true olarak ayarlanmışsa, bu durum söz konusu model için grup düzeyindeki deploymentName ve version değerlerinin kullanılacağı anlamına gelir. Bu durumda her ikisinin de grup düzeyinde tanımlanmış olması gerekir.

• Bir model nesne olarak yapılandırılmışsa, kendi deploymentName ve version değerlerini belirtebilir. Bunlar sağlanmazsa, model grubun deploymentName ve version değerlerini devralır.

• Eğer grup bir serverless inference endpoint temsil ediyorsa, onu modeller listesine eklemek için singular model true olarak ayarlanmalıdır.

Özel Hususlar

1. Benzersiz İsimler: Hem model hem de grup isimleri, tüm yapılandırma genelinde benzersiz olmalıdır. Yinelenen isimler doğrulama hatalarına yol açar.

2. Eksik Zorunlu Alanlar: Grup düzeyinde (boolean bayraklı modeller için) veya modellerin yapılandırmaları içinde (miras alınmıyorsa veya açıkça belirtilmemişse) zorunlu deploymentName veya version alanlarının eksik olması, grup bir serverless inference endpoint temsil etmediği sürece doğrulama hatalarına yol açacaktır.

3. Ortam Değişkeni Referansları: Yapılandırma, ortam değişkeni referanslarını (örneğin, ${VARIABLE_NAME}) destekler. Çalışma zamanı hatalarını önlemek için başvurulan tüm değişkenlerin ortamınızda mevcut olduğundan emin olun. Yapılandırmada başvurulan tanımlı ortam değişkenlerinin eksikliği hatalara neden olacaktır. ${INSTANCE_NAME} ve ${DEPLOYMENT_NAME} benzersiz yer tutuculardır ve ortam değişkenlerine karşılık gelmezler; bunun yerine, o an seçili olan modelin instance ve deployment adına karşılık gelirler. Olası çakışmaları önlemek için INSTANCE_NAME ve DEPLOYMENT_NAME ifadelerini ortam değişkeni adı olarak kullanmanız önerilmez.

4. Hata Yönetimi: Yinelenen isimler, tanımlanmamış ortam değişkenleri veya eksik zorunlu alanlar gibi yapılandırmadaki her türlü sorun, kurulumu geçersiz kılacak ve hızlı çözüm sağlamayı amaçlayan açıklayıcı hata mesajları üretecektir. Geçersiz bir yapılandırmayla sunucuyu çalıştırmanıza izin verilmeyecektir.

5. Model tanımlayıcıları: (Projeye göre) bilinmeyen bir model, model tanımlayıcısı olarak kullanılabilir, ancak mesaj/token işleme için kritik olan bilinen bağlam uzunluğunu yansıtması için bilinen bir modelle eşleşmelidir; örneğin, gpt-7000 geçerli olacaktır ancak varsayılan olarak 4k token sınırına sahip olacaktır, oysa gpt-4-turbo 128k bağlam sınırına sahip olarak tanınacaktır.

Uyumluluğu korumak için yapılandırmanızı en güncel şema tanımlamaları ve yönergelerine göre doğrulayın.

Model Dağıtımları

Kullanıcılarınızın kullanımına sunulan modellerin listesi, azureOpenAI endpoint yapılandırmanızda belirtilen model grupları tarafından belirlenir.

Örneğin:

# 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

Yukarıdaki yapılandırma, gpt-4-vision-preview, gpt-3.5-turbo ve gpt-4-turbo modellerini kullanıcılarınız için tanımlandıkları sırada etkinleştirecektir.

Azure ile Assistants Kullanımı

Assistants özelliğini Azure OpenAI ile kullanabilmek için 2 temel adım bulunmaktadır.

1. azureOpenAI endpoint'i altında, yani Endpoint-level seviyesinde assistants alanını aşağıdaki gibi true olarak ayarlayın:

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

2. Azure'un Assistants API entegrasyonu ile uyumlu gruplara assistants alanını ekleyin.

• Grup yapılandırmalarınızdan en az biri uyumlu olmalıdır.
• Azure belgelerindeki uyumlu bölgeleri ve modelleri buradan kontrol edebilirsiniz.
• Sürüm ayrıca "2024-02-15-preview" veya daha yeni bir sürüm olmalıdır; en son özelliklere erişim için daha yeni bir sürüm tercih edilir.

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)

Notlar:

• Kimlik bilgileri için, her assistants-uyumlu grup yapılandırmasında belirtilen özel ortam değişkenlerine güvenin.

• Birden fazla bölgeyi assistants-compatible olarak işaretlerseniz, oluşturduğunuz asistanlar bölgeler genelinde toplanarak ana asistan seçim listesine eklenecektir.

• Azure OpenAI'ye yüklediğiniz dosyalar, ister mesaj ister asistan düzeyinde olsun, yalnızca mevcut asistanın modelinin bulunduğu bölgede kullanılabilir olacaktır.

  • Bu nedenle, Azure OpenAI Assistants için yalnızca bir bölge veya kaynak grubu kullanmanız önerilir, aksi takdirde bir hata ile karşılaşırsınız.
  • "OpenAI" üzerine yükleme yapmak, resmi code_interpreter ve retrieval yetenekleri için varsayılan davranıştır.

• Asistanların oluşturduğu dosyaları indirme özelliği yakında desteklenecektir.

• 19 Mayıs 2024 itibarıyla, retrieval ve streaming özellikleri Azure OpenAI üzerinden henüz desteklenmemektedir.

  • Desteklenmediği sürece retrieval ile ilgili herhangi bir hatayı önlemek için, azureAssistants endpoint yapılandırması aracılığıyla bu yeteneği tamamen devre dışı bırakmanız önerilir:

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

  • Varsayılan olarak, retrieval hariç tüm yetenekler etkindir.

Azure ile Eklentileri Kullanma

Azure OpenAI ile Plugins endpoint'ini kullanmak için function calling desteğine sahip bir deployment'a ihtiyacınız vardır. Aksi takdirde, Agent ayarlarından "Functions" seçeneğini kapatın. "Functions" modunu kullanmadığınızda, ajanın oluşturduğu içeriğin gözden geçirilmesi aşaması olan "skip completion" seçeneğinin de kapalı tutulması önerilir.

Plugins endpoint ile Azure kullanmak için, Azure OpenAI endpoint yapılandırmanızda plugins alanının true olarak ayarlandığından emin olun:

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

plugins alanını yapılandırmak, Eklentilerin Azure modellerini kullanmasını sağlayacaktır.

NOT: librechat.yaml aracılığıyla yapılan mevcut yapılandırma, Eklenti kullanımı için arayüzden seçtiğiniz birincil modeli kullanır; bu, Azure dışındaki durumlarda genellikle işleyiş şekli değildir, çünkü Azure'da bunun yerine "Agent" modeli kullanılır. Azure üzerinden Eklentiler kullanılırken Agent modeli ayarı göz ardı edilebilir.

Azure ile Belirtilen Bir Base URL Kullanma

Azure OpenAI API istekleri için temel URL (base URL) dinamik olarak yapılandırılabilir. Bu, Cloudflare AI Gateway gibi hizmetleri proxy olarak kullanmak veya uygulamanın baseURL işleyişini açıkça geçersiz kılmak istediğiniz durumlarda kullanışlıdır.

LibreChat, Azure model gruplandırmanız için baseURL alanını kullanacaktır; bu alan, Azure OpenAI API örneği ve dağıtım adları için yer tutucular içerebilir.

Yapılandırmada, base URL şu şekilde özelleştirilebilir:

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

NOT: ${INSTANCE_NAME} ve ${DEPLOYMENT_NAME} benzersiz yer tutuculardır ve ortam değişkenlerine karşılık gelmezler; bunun yerine, o an seçili olan modelin instance ve deployment adına karşılık gelirler. Olası çakışmaları önlemek için INSTANCE_NAME ve DEPLOYMENT_NAME ifadelerini ortam değişkeni adı olarak kullanmamanız önerilir.

Ayrıca yer tutucuları tamamen atlayabilir ve baseURL'i kimlik bilgilerinizle basitçe oluşturabilirsiniz:

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

Son olarak, tüm baseURL değerini özel bir ortam değişkeni aracılığıyla belirtebilirsiniz

      baseURL: "${MY_CUSTOM_BASEURL}"

Azure ile Otomatik Başlık Oluşturmayı Etkinleştirme

Azure için başlıklandırmayı etkinleştirmek üzere titleConvo değerini true olarak ayarlayın.

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

Ayrıca, grubunuzda/gruplarınızda yapılandırdığınız takdirde titleModel ile başlıklandırma için kullanılacak modeli belirleyebilirsiniz.

    titleModel: "gpt-3.5-turbo"

Not: "gpt-3.5-turbo" varsayılan değerdir, bu nedenle tam olarak bu modeli kullanmak istiyorsanız ve yapılandırılmışsa bunu atlayabilirsiniz. Yapılandırılmamışsa ve titleConvo değeri true olarak ayarlanmışsa, başlıklandırma işlemi bir hatayla sonuçlanacak ve hiçbir başlık oluşturulmayacaktır. Ayrıca bunu current_model olarak ayarlayarak mevcut modeli dinamik bir şekilde kullanmasını sağlayabilirsiniz.

    titleModel: "current_model"

Azure ile GPT-4 Vision Kullanımı

Azure OpenAI ile Vision (görüntü analizi) özelliğini kullanmak için gpt-4-vision-preview modelinin gruplandırmalarınızdan birinde belirtildiğinden emin olun.

Bu, OpenAI endpoint ile aynı şekilde çalışır: vision modelini seçmenize gerek yoktur, çünkü arka planda otomatik olarak değiştirilecektir.

Azure OpenAI Service (DALL-E) ile görseller oluşturun

• Öncelikle DALL-E barındıran bir Azure kaynağı oluşturmanız gerekir
  • Bu yazının yazıldığı sırada, dall-e-3 SwedenCentral bölgesinde, dall-e-2 ise EastUS bölgesinde mevcuttur.
• Ardından, görüntü oluşturma modelini yukarıdaki bölgelerden birinde dağıtmanız gerekir.
  • Daha fazla yardım için Azure OpenAI Image Generation Quickstart Guide kılavuzunu okuyun.
• Azure kimlik bilgilerinize göre ortam değişkenlerinizi yapılandırın:

DALL-E yapılandırma seçenekleri:

DALL-E:

API Anahtarları:

API Anahtarları (Sürüme Özel):

Sistem İstemi (System Prompts):

Reverse Proxy Ayarları:

Temel URL'ler:

Azure OpenAI Entegrasyonu (İsteğe bağlı):

Yer tutucu metinleri gerçek istemler veya talimatlarla değiştirin ve bunları doğrudan dosya içine dahil etmeyi seçerseniz API anahtarlarınızı sağlayın (hassas anahtarların kod tabanı dışında yönetilmesi önerilir). API anahtarlarını yazılıma gömerken OpenAI'ın kullanım politikalarını inceleyin ve bunlara uyun.

Not: Eğer PROXY ayarlıysa, bu ayar uygulama genelinde evrensel olduğu için DALL-E çağrıları için de kullanılacaktır.

Serverless Inference Endpoints

librechat.yaml dosyası aracılığıyla, Azure AI Foundry üzerindeki modellere erişmek için Azure AI Studio sunucusuz çıkarım (serverless inference) uç noktalarını yapılandırabilirsiniz. Bu uç noktaların ihtiyaç duyduğu özel işleme işaret etmek için serverless alanıyla birlikte yalnızca bir model tanımlayıcısı, baseURL ve apiKey gereklidir.

• Azure AI Studio üzerinde MaaS ("Models as a Service") erişimini ayarlamak için uyumlu model kartlarındaki talimatları izlemeniz gerekecektir.

  • Referans olması açısından, bilinen uyumlu model kartlarından bazıları şunlardır:

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

• Daha fazla bilgi için "Mistral-large" model sürümüne ilişkin teknik blogu inceleyebilirsiniz.

• Ardından, bunları librechat.yaml dosyanızdaki azureOpenAI yapılandırmanıza eklemeniz gerekecektir.

• Meta-Llama-3.1-8B-Instruct için örnek bir yapılandırma aşağıdadır:

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

Notlar:

• Azure AI Foundry modelleri artık sunucusuz çıkarım için /models/chat/completions?api-version=version altında endpoint'ler sağlamaktadır.
  • baseURL alanı, /models/ sonrasındaki herhangi bir şey, yani /chat/completions yolu olmadan, endpoint'in kök dizinine ayarlanmalıdır.
  • Örnek: https://example.services.ai.azure.com/models/ için https://example.services.ai.azure.com/models/chat/completions?api-version=2024-05-01-preview
  • version sorgu parametresi isteğe bağlıdır ve baseURL alanında belirtilebilir.
• models alanında kullanılan model adı, Azure AI Foundry içindeki modelin dağıtım adıyla eşleşmelidir.
• LibreChat ile uyumluluk, yazıldığı tarihte genellikle Azure AI Studio üzerinde "Kullandıkça Öde" (Pay-as-you-go) veya "Hizmet Olarak Modeller" (MaaS) dağıtımları olan ve v1/completions ya da models/chat/completions endpoint işleme özelliklerine sahip OpenAI-SDK uyumlu OpenAI API spesifikasyonları ile eşdeğerliğe dayanır.
• Azure model kataloğundan sunucusuz dağıtımlar ("Serverless APIs") sunan tüm modeller uyumludur. Tam listeyi görmek için Dağıtım seçenekleri altında "Serverless API" ve çıkarım görevleri altında "Chat completion" seçeneklerine göre filtreleme yapabilirsiniz; ancak, gerçek zamanlı endpoint modelleri test edilmemiştir.
• Bu sunucusuz çıkarım endpoint'leri/modelleri, Agents ile kullanımlarını sağlayan OpenAI API spesifikasyonlarına göre fonksiyon çağırmayı destekleyebilir veya desteklemeyebilir.