Integrasi Azure OpenAI untuk LibreChat

LibreChat mendukung layanan API Azure OpenAI sebagai endpoint kelas satu. Untuk menggunakan Azure OpenAI di dalam LibreChat, konfigurasikan file librechat.yaml untuk pengaturan Anda. Dokumen ini mencakup proses penyiapan untuk menggunakan beberapa deployment dan model.

Contoh

Contoh konfigurasi yang mencakup banyak opsi dan fitur yang dijelaskan di bawah ini:

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

Contoh ini mengikuti Azure OpenAI Endpoint Configuration Docs.

Setiap tingkat konfigurasi dirinci di bagian masing-masing:

1. Konfigurasi tingkat endpoint

2. Konfigurasi tingkat grup

3. Konfigurasi tingkat model

Pengaturan

1. Buka librechat.yaml untuk Mengedit: Gunakan editor teks atau IDE pilihan Anda untuk membuka dan mengedit file librechat.yaml.

   • Opsional: gunakan jalur file jarak jauh atau kustom dengan variabel lingkungan berikut:

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

2. Konfigurasi Pengaturan Azure OpenAI: Ikuti struktur yang diuraikan di bawah ini untuk mengisi pengaturan Azure OpenAI Anda, termasuk kunci API, nama instance, grup model, dan konfigurasi lainnya.

3. Hapus Pengaturan Lama: Jika Anda menggunakan konfigurasi lama apa pun, hapuslah. Server LibreChat juga akan mendeteksi hal ini dan mengingatkan Anda.

4. Simpan Perubahan Anda: Simpan file librechat.yaml.

5. Restart LibreChat: Mulai ulang aplikasi LibreChat Anda agar konfigurasi yang diperbarui dimuat.

Bidang yang Diperlukan

Untuk mengintegrasikan Azure OpenAI dengan LibreChat, kolom-kolom tertentu harus dikonfigurasi di dalam file librechat.yaml Anda. Kolom-kolom ini divalidasi melalui kombinasi variabel kustom dan variabel lingkungan. Persyaratan rincinya adalah sebagai berikut.

Konfigurasi Tingkat-Endpoint

Pengaturan Global Azure:

Judul dan Pengaturan Percakapan:

Konfigurasi Grup:

Urutan Kustom (Opsional):

Opsi customOrder dikomentari, karena bersifat opsional.

Contoh pengaturan tingkat endpoint ini di dalam file librechat.yaml Anda:

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)

Konfigurasi Tingkat Grup

Bidang-bidang yang dapat dikonfigurasi dalam file Custom Config (librechat.yaml). Untuk informasi lebih lanjut mengenai setiap bidang, lihat bagian Azure OpenAI di Dokumen Custom Config.

Konfigurasi Tingkat Grup: Identifikasi Grup:

Autentikasi:

Instans Azure OpenAI:

Konfigurasi Deployment:

Pengaturan Lanjutan:

Konfigurasi Model:

Contoh konfigurasi tingkat grup dalam 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)

Konfigurasi Tingkat Model

Di dalam setiap grup, kolom models berisi pemetaan pengidentifikasi model ke konfigurasi masing-masing:

Identifikasi Model:

Konfigurasi Model:

Endpoint Inferensi Serverless:

• Pengidentifikasi model harus sesuai dengan nama model OpenAI yang bersangkutan agar dapat mencerminkan batas konteks yang diketahui dan/atau berfungsi dengan benar dalam hal visi. Sebagai contoh, jika Anda bermaksud menggunakan gpt-4-vision, model tersebut harus dikonfigurasi seperti ini:

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

• Lihat Model Deployments untuk contoh lainnya.

• Jika sebuah model diatur ke true, ini menyiratkan penggunaan deploymentName dan version tingkat grup untuk model tersebut. Keduanya harus didefinisikan di tingkat grup dalam kasus ini.

• Jika model dikonfigurasi sebagai objek, model tersebut dapat menentukan deploymentName dan version-nya sendiri. Jika hal ini tidak disediakan, model akan mewarisi deploymentName dan version dari grup tersebut.

• Jika grup tersebut merepresentasikan serverless inference endpoint, model tunggal harus diatur ke true untuk menambahkannya ke daftar model.

Pertimbangan Khusus

1. Nama Unik: Baik nama model maupun nama grup harus unik di seluruh konfigurasi. Nama duplikat akan menyebabkan kegagalan validasi.

2. Kolom Wajib Diisi yang Hilang: Kurangnya deploymentName atau version yang wajib diisi, baik di tingkat grup (untuk model dengan flag boolean) atau di dalam konfigurasi model (jika tidak mewarisi atau ditentukan secara eksplisit), akan mengakibatkan kesalahan validasi, kecuali jika grup tersebut mewakili serverless inference endpoint.

3. Referensi Variabel Lingkungan: Konfigurasi ini mendukung referensi variabel lingkungan (contoh: ${VARIABLE_NAME}). Pastikan semua variabel yang direferensikan ada di lingkungan Anda untuk menghindari kesalahan saat runtime. Ketiadaan variabel lingkungan yang ditentukan dan direferensikan dalam konfigurasi akan menyebabkan kesalahan. ${INSTANCE_NAME} dan ${DEPLOYMENT_NAME} adalah placeholder unik, dan tidak merujuk pada variabel lingkungan, melainkan merujuk pada nama instance dan deployment dari model yang sedang dipilih. Tidak disarankan untuk menggunakan INSTANCE_NAME dan DEPLOYMENT_NAME sebagai nama variabel lingkungan untuk menghindari potensi konflik.

4. Penanganan Kesalahan: Masalah apa pun dalam konfigurasi, seperti nama duplikat, variabel lingkungan yang tidak terdefinisi, atau kolom wajib yang hilang, akan membatalkan pengaturan dan menghasilkan pesan kesalahan deskriptif yang bertujuan untuk penyelesaian masalah secara cepat. Anda tidak akan diizinkan untuk menjalankan server dengan konfigurasi yang tidak valid.

5. Pengidentifikasi model: Model yang tidak dikenal (oleh proyek ini) dapat digunakan sebagai pengidentifikasi model, namun model tersebut harus cocok dengan model yang sudah dikenal agar dapat mencerminkan panjang konteksnya yang diketahui, yang sangat penting untuk penanganan pesan/token; misalnya, gpt-7000 akan valid tetapi secara default menggunakan batas 4k token, sedangkan gpt-4-turbo akan dikenali memiliki batas konteks 128k.

Validasi konfigurasi Anda terhadap definisi skema dan panduan terbaru untuk menjaga kompatibilitas.

Model Deployments

Daftar model yang tersedia bagi pengguna Anda ditentukan oleh pengelompokan model yang ditentukan dalam konfigurasi endpoint azureOpenAI Anda.

Sebagai contoh:

# 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

Konfigurasi di atas akan mengaktifkan gpt-4-vision-preview, gpt-3.5-turbo, dan gpt-4-turbo bagi pengguna Anda sesuai urutan pendefinisiannya.

Menggunakan Assistants dengan Azure

Untuk mengaktifkan penggunaan Assistants dengan Azure OpenAI, terdapat 2 langkah utama.

1. Atur kolom assistants, di bawah endpoint azureOpenAI, yaitu, pada Endpoint-level menjadi true, seperti ini:

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

2. Tambahkan field assistants ke grup yang kompatibel dengan integrasi Assistants API Azure.

• Setidaknya satu dari konfigurasi grup Anda harus kompatibel.
• Anda dapat memeriksa wilayah dan model yang kompatibel di dokumentasi Azure di sini.
• Versi tersebut juga harus "2024-02-15-preview" atau yang lebih baru, sebaiknya yang lebih baru untuk mendapatkan akses ke fitur-fitur terbaru.

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)

Catatan:

• Untuk kredensial, gunakan variabel lingkungan kustom yang ditentukan pada setiap konfigurasi grup yang kompatibel dengan assistants.

• Jika Anda menandai beberapa wilayah sebagai kompatibel dengan assistants, assistant yang Anda buat akan digabungkan di seluruh wilayah ke dalam daftar pilihan assistant utama.

• File yang Anda unggah ke Azure OpenAI, baik di tingkat pesan maupun asisten, hanya akan tersedia di wilayah tempat model asisten saat ini berada.

  • Untuk alasan ini, disarankan agar Anda hanya menggunakan satu region atau grup sumber daya untuk Azure OpenAI Assistants, atau Anda akan mengalami error.
  • Mengunggah ke "OpenAI" adalah perilaku default untuk kapabilitas code_interpreter dan retrieval resmi.

• Mengunduh file yang dihasilkan oleh asisten akan segera didukung.

• Per 19 Mei 2024, retrieval dan streaming belum didukung melalui Azure OpenAI.

  • Untuk menghindari kesalahan apa pun dengan retrieval saat fitur tersebut belum didukung, disarankan untuk menonaktifkan kapabilitas tersebut sepenuhnya melalui konfigurasi endpoint azureAssistants:

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

  • Secara default, semua kapabilitas, kecuali retrieval, diaktifkan.

Menggunakan Plugin dengan Azure

Untuk menggunakan endpoint Plugins dengan Azure OpenAI, Anda memerlukan deployment yang mendukung function calling. Jika tidak, nonaktifkan "Functions" di pengaturan Agent. Saat Anda tidak menggunakan mode "functions", disarankan juga untuk menonaktifkan "skip completion", yang merupakan langkah peninjauan terhadap apa yang dihasilkan oleh agen.

Untuk menggunakan Azure dengan endpoint Plugins, pastikan kolom plugins diatur ke true dalam konfigurasi endpoint Azure OpenAI Anda:

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

Mengonfigurasi kolom plugins akan mengonfigurasi Plugins untuk menggunakan model Azure.

CATATAN: Konfigurasi saat ini melalui librechat.yaml menggunakan model utama yang Anda pilih dari frontend untuk penggunaan Plugin, yang biasanya tidak berfungsi seperti itu tanpa Azure, di mana model "Agent" digunakan sebagai gantinya. Pengaturan model Agent dapat diabaikan saat menggunakan Plugin melalui Azure.

Menggunakan Base URL Tertentu dengan Azure

URL dasar untuk permintaan API Azure OpenAI dapat dikonfigurasi secara dinamis. Hal ini berguna untuk layanan proksi seperti Cloudflare AI Gateway, atau jika Anda ingin mengganti penanganan baseURL aplikasi secara eksplisit.

LibreChat akan menggunakan kolom baseURL untuk pengelompokan model Azure Anda, yang dapat menyertakan placeholder untuk instance Azure OpenAI API dan nama deployment.

Dalam konfigurasi, base URL dapat disesuaikan seperti berikut:

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

CATATAN: ${INSTANCE_NAME} dan ${DEPLOYMENT_NAME} adalah placeholder unik, dan tidak merujuk pada variabel lingkungan, melainkan merujuk pada nama instance dan deployment dari model yang sedang dipilih. Anda tidak disarankan menggunakan INSTANCE_NAME dan DEPLOYMENT_NAME sebagai nama variabel lingkungan untuk menghindari potensi konflik.

Anda juga dapat menghilangkan placeholder sepenuhnya dan cukup menyusun baseURL dengan kredensial Anda:

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

Terakhir, Anda dapat menentukan baseURL secara keseluruhan melalui variabel lingkungan kustom

      baseURL: "${MY_CUSTOM_BASEURL}"

Mengaktifkan Judul yang Dihasilkan Otomatis dengan Azure

Untuk mengaktifkan penjudulan untuk Azure, atur titleConvo ke true.

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

Anda juga dapat menentukan model yang akan digunakan untuk pemberian judul, dengan titleModel asalkan Anda telah mengonfigurasinya di dalam grup Anda.

    titleModel: "gpt-3.5-turbo"

Catatan: "gpt-3.5-turbo" adalah nilai default, jadi Anda dapat menghilangkannya jika ingin menggunakan model yang tepat ini dan telah mengonfigurasinya. Jika tidak dikonfigurasi dan titleConvo diatur ke true, proses pemberian judul akan menghasilkan kesalahan dan tidak ada judul yang dibuat. Anda juga dapat mengaturnya agar menggunakan model saat ini secara dinamis dengan menyetelnya ke current_model.

    titleModel: "current_model"

Menggunakan GPT-4 Vision dengan Azure

Untuk menggunakan Vision (analisis gambar) dengan Azure OpenAI, pastikan gpt-4-vision-preview adalah model yang ditentukan di salah satu pengelompokan Anda.

Ini berfungsi sama seperti pada endpoint OpenAI: tidak perlu memilih model vision, karena model tersebut akan dialihkan di balik layar.

Menghasilkan gambar dengan Azure OpenAI Service (DALL-E)

• Pertama, Anda perlu membuat sumber daya Azure yang menampung DALL-E
  • Pada saat penulisan ini, dall-e-3 tersedia di wilayah SwedenCentral, dan dall-e-2 di wilayah EastUS.
• Kemudian, Anda perlu men-deploy model pembuatan gambar di salah satu wilayah di atas.
  • Baca Panduan Memulai Pembuatan Gambar Azure OpenAI untuk bantuan lebih lanjut
• Konfigurasikan variabel lingkungan Anda berdasarkan kredensial Azure:

Opsi konfigurasi DALL-E:

DALL-E:

Kunci API:

API Keys (Versi Spesifik):

System Prompts:

Pengaturan Reverse Proxy:

Base URL:

Integrasi Azure OpenAI (Opsional):

Ganti teks placeholder dengan prompt atau instruksi yang sebenarnya, dan berikan kunci API Anda jika Anda memilih untuk menyertakannya langsung di dalam file (disarankan untuk mengelola kunci sensitif di luar basis kode). Tinjau dan patuhi kebijakan penggunaan OpenAI saat menyematkan kunci API dalam perangkat lunak.

Catatan: jika Anda telah mengatur PROXY, pengaturan tersebut juga akan digunakan untuk panggilan DALL-E, yang bersifat universal untuk aplikasi ini.

Serverless Inference Endpoints

Melalui file librechat.yaml, Anda dapat mengonfigurasi endpoint inferensi serverless Azure AI Studio untuk mengakses model dari Azure AI Foundry. Hanya pengenal model, baseURL, dan apiKey yang diperlukan bersama dengan kolom serverless untuk menunjukkan penanganan khusus yang dibutuhkan oleh endpoint ini.

• Anda perlu mengikuti instruksi dalam kartu model yang kompatibel untuk menyiapkan akses MaaS ("Models as a Service") di Azure AI Studio.

  • Sebagai referensi, berikut adalah beberapa model card yang diketahui kompatibel:

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

• Anda juga dapat meninjau blog teknis untuk perilisan model "Mistral-large" untuk informasi lebih lanjut.

• Kemudian, Anda perlu menambahkannya ke konfigurasi azureOpenAI Anda di dalam file librechat.yaml.

• Berikut adalah contoh konfigurasi untuk 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

Catatan:

• Model Azure AI Foundry kini menyediakan endpoint di bawah /models/chat/completions?api-version=version untuk inferensi serverless.
  • Kolom baseURL harus diatur ke root dari endpoint, tanpa menyertakan apa pun setelah /models/, yaitu, jalur /chat/completions.
  • Contoh: https://example.services.ai.azure.com/models/ untuk https://example.services.ai.azure.com/models/chat/completions?api-version=2024-05-01-preview
  • Parameter kueri version bersifat opsional dan dapat ditentukan di dalam kolom baseURL.
• Nama model yang digunakan dalam kolom models harus sesuai dengan nama deployment model tersebut di Azure AI Foundry.
• Kompatibilitas dengan LibreChat bergantung pada paritas dengan spesifikasi OpenAI API, yang pada saat penulisan ini, biasanya merupakan penyebaran "Pay-as-you-go" atau "Models as a Service" (MaaS) di Azure AI Studio, yang kompatibel dengan OpenAI-SDK dengan penanganan endpoint v1/completions atau models/chat/completions.
• Semua model yang menawarkan penyebaran tanpa server ("Serverless APIs") kompatibel dari katalog model Azure. Anda dapat memfilter berdasarkan "Serverless API" di bawah opsi Deployment dan "Chat completion" di bawah tugas inferensi untuk melihat daftar lengkapnya; namun, model endpoint waktu nyata (real time) belum diuji.
• Endpoint/model inferensi serverless ini mungkin mendukung atau tidak mendukung pemanggilan fungsi (function calling) sesuai dengan spesifikasi OpenAI API, yang memungkinkan penggunaannya dengan Agents.