Tích hợp Azure OpenAI cho LibreChat

LibreChat hỗ trợ các dịch vụ API Azure OpenAI như một endpoint hạng nhất. Để sử dụng Azure OpenAI trong LibreChat, hãy cấu hình librechat.yaml file cho thiết lập của bạn. Tài liệu này bao gồm quy trình thiết lập để sử dụng nhiều deployment và model.

Ví dụ

Một ví dụ cấu hình bao gồm nhiều tùy chọn và tính năng được mô tả dưới đây:

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

Ví dụ này tuân theo Tài liệu Cấu hình Endpoint Azure OpenAI.

Mỗi cấp độ cấu hình được trình bày chi tiết trong phần tương ứng của nó:

1. Cấu hình cấp endpoint

2. Cấu hình cấp nhóm

3. Cấu hình cấp độ model

Thiết lập

1. Mở librechat.yaml để chỉnh sửa: Sử dụng trình soạn thảo văn bản hoặc IDE ưa thích của bạn để mở và chỉnh sửa tệp librechat.yaml.

   • Tùy chọn: sử dụng đường dẫn tệp từ xa hoặc tùy chỉnh với biến môi trường sau:

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

2. Cấu hình cài đặt Azure OpenAI: Làm theo cấu trúc được nêu dưới đây để điền các cài đặt Azure OpenAI của bạn, bao gồm khóa API, tên instance, nhóm model và các cấu hình khác.

3. Xóa các cài đặt cũ (Legacy Settings): Nếu bạn đang sử dụng bất kỳ cấu hình cũ nào, hãy xóa chúng đi. Máy chủ LibreChat cũng sẽ phát hiện các cấu hình này và nhắc nhở bạn.

4. Lưu các thay đổi của bạn: Lưu tệp librechat.yaml.

5. Khởi động lại LibreChat: Khởi động lại ứng dụng LibreChat của bạn để cấu hình đã cập nhật được tải lên.

Các trường bắt buộc

Để tích hợp Azure OpenAI với LibreChat, các trường cụ thể phải được cấu hình trong tệp librechat.yaml của bạn. Các trường này được xác thực thông qua sự kết hợp giữa các biến tùy chỉnh và biến môi trường. Các yêu cầu chi tiết như sau.

Cấu hình cấp Endpoint

Cài đặt Azure toàn cục:

Cài đặt Tiêu đề và Cuộc trò chuyện:

Cấu hình nhóm:

Thứ tự tùy chỉnh (Tùy chọn):

Tùy chọn customOrder đang được chú thích, vì nó là tùy chọn.

Ví dụ về các cài đặt cấp endpoint này trong tệp librechat.yaml của bạn:

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)

Cấu hình cấp nhóm

Các trường có thể cấu hình trong tệp Custom Config (librechat.yaml). Để biết thêm thông tin về từng trường, hãy xem phần Azure OpenAI trong Tài liệu Custom Config.

Cấu hình cấp nhóm: Nhận diện nhóm:

Xác thực:

Azure OpenAI Instance:

Cấu hình triển khai:

Cài đặt nâng cao:

Cấu hình Model:

Ví dụ về cấu hình cấp nhóm trong tệp 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)

Cấu hình cấp Model

Trong mỗi nhóm, trường models chứa một ánh xạ các định danh model tới cấu hình của chúng:

Nhận diện Model:

Cấu hình Model:

Các endpoint suy luận Serverless:

• Định danh model phải khớp với tên model OpenAI tương ứng để nó có thể phản ánh chính xác các giới hạn ngữ cảnh đã biết và/hoặc hoạt động trong trường hợp sử dụng vision. Ví dụ, nếu bạn định sử dụng gpt-4-vision, nó phải được cấu hình như sau:

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

• Xem Model Deployments để biết thêm các ví dụ.

• Nếu một model được đặt thành true, điều đó có nghĩa là sử dụng deploymentName và version cấp nhóm cho model này. Trong trường hợp này, cả hai đều phải được xác định ở cấp nhóm.

• Nếu một model được cấu hình dưới dạng một object, nó có thể chỉ định deploymentName và version riêng. Nếu các thông tin này không được cung cấp, model sẽ kế thừa deploymentName và version của nhóm.

• Nếu nhóm đại diện cho một serverless inference endpoint, thì model đơn lẻ nên được đặt thành true để thêm nó vào danh sách các model.

Các lưu ý đặc biệt

1. Tên duy nhất: Cả tên model và tên nhóm đều phải là duy nhất trong toàn bộ cấu hình. Các tên trùng lặp sẽ dẫn đến lỗi xác thực.

2. Các trường bắt buộc bị thiếu: Việc thiếu deploymentName hoặc version bắt buộc ở cấp nhóm (đối với các mô hình được gắn cờ boolean) hoặc trong cấu hình của các mô hình (nếu không kế thừa hoặc không được chỉ định rõ ràng) sẽ dẫn đến lỗi xác thực, trừ khi nhóm đó đại diện cho một serverless inference endpoint.

3. Tham chiếu biến môi trường: Cấu hình hỗ trợ các tham chiếu biến môi trường (ví dụ: ${VARIABLE_NAME}). Đảm bảo rằng tất cả các biến được tham chiếu đều có mặt trong môi trường của bạn để tránh lỗi thời gian chạy. Việc thiếu các biến môi trường được xác định trong cấu hình sẽ gây ra lỗi. ${INSTANCE_NAME} và ${DEPLOYMENT_NAME} là các trình giữ chỗ duy nhất và không tương ứng với các biến môi trường, thay vào đó chúng tương ứng với tên instance và tên deployment của mô hình hiện đang được chọn. Bạn không nên sử dụng INSTANCE_NAME và DEPLOYMENT_NAME làm tên biến môi trường để tránh mọi xung đột tiềm ẩn.

4. Xử lý lỗi: Mọi vấn đề trong cấu hình, chẳng hạn như tên trùng lặp, biến môi trường không xác định hoặc thiếu các trường bắt buộc, sẽ làm mất hiệu lực của thiết lập và tạo ra các thông báo lỗi mô tả nhằm mục đích giải quyết nhanh chóng. Bạn sẽ không được phép chạy máy chủ với cấu hình không hợp lệ.

5. Model identifiers: Một model không xác định (đối với dự án) có thể được sử dụng làm định danh model, nhưng nó phải khớp với một model đã biết để phản ánh độ dài ngữ cảnh đã biết của nó, điều này rất quan trọng đối với việc xử lý tin nhắn/token; ví dụ: gpt-7000 sẽ hợp lệ nhưng mặc định ở giới hạn 4k token, trong khi gpt-4-turbo sẽ được nhận dạng là có giới hạn ngữ cảnh 128k.

Xác thực cấu hình của bạn dựa trên các định nghĩa lược đồ và hướng dẫn mới nhất để duy trì tính tương thích.

Triển khai Model

Danh sách các model khả dụng cho người dùng của bạn được xác định bởi các nhóm model được chỉ định trong cấu hình endpoint azureOpenAI của bạn.

Ví dụ:

# 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

Cấu hình trên sẽ kích hoạt gpt-4-vision-preview, gpt-3.5-turbo và gpt-4-turbo cho người dùng của bạn theo thứ tự đã được xác định.

Sử dụng Assistants với Azure

Để kích hoạt việc sử dụng Assistants với Azure OpenAI, có 2 bước chính.

1. Đặt trường assistants, bên dưới endpoint azureOpenAI, nghĩa là tại Endpoint-level thành true, như sau:

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

2. Thêm trường assistants vào các nhóm tương thích với tích hợp Assistants API của Azure.

• Ít nhất một trong các cấu hình nhóm của bạn phải tương thích.
• Bạn có thể kiểm tra các khu vực và mô hình tương thích trong tài liệu Azure tại đây.
• Phiên bản cũng phải là "2024-02-15-preview" hoặc mới hơn, ưu tiên phiên bản mới hơn để có quyền truy cập vào các tính năng mới nhất.

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)

Ghi chú:

• Đối với thông tin xác thực, hãy dựa vào các biến môi trường tùy chỉnh được chỉ định tại mỗi cấu hình nhóm tương thích với assistants.

• Nếu bạn đánh dấu nhiều khu vực là tương thích với assistants, các assistant bạn tạo sẽ được tổng hợp từ các khu vực vào danh sách lựa chọn assistant chính.

• Các tệp bạn tải lên Azure OpenAI, dù ở cấp độ tin nhắn hay trợ lý, sẽ chỉ khả dụng trong khu vực mà mô hình của trợ lý hiện tại thuộc về.

  • Vì lý do này, bạn chỉ nên sử dụng một vùng hoặc nhóm tài nguyên duy nhất cho Azure OpenAI Assistants, nếu không bạn sẽ gặp lỗi.
  • Tải lên "OpenAI" là hành vi mặc định cho các tính năng code_interpreter và retrieval chính thức.

• Việc tải xuống các tệp do trợ lý tạo ra sẽ sớm được hỗ trợ.

• Kể từ ngày 19 tháng 5 năm 2024, tính năng truy xuất (retrieval) và truyền phát (streaming) vẫn chưa được hỗ trợ thông qua Azure OpenAI.

  • Để tránh bất kỳ lỗi nào với tính năng truy xuất (retrieval) trong khi nó chưa được hỗ trợ, bạn nên vô hiệu hóa hoàn toàn khả năng này thông qua cấu hình endpoint azureAssistants:

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

  • Theo mặc định, tất cả các khả năng, ngoại trừ retrieval, đều được bật.

Sử dụng Plugins với Azure

Để sử dụng endpoint Plugins với Azure OpenAI, bạn cần một bản triển khai hỗ trợ function calling. Nếu không, hãy tắt "Functions" trong cài đặt Agent. Khi bạn không sử dụng chế độ "functions", bạn cũng nên tắt "skip completion", đây là bước xem xét lại những gì agent đã tạo.

Để sử dụng Azure với endpoint Plugins, hãy đảm bảo trường plugins được đặt thành true trong cấu hình endpoint Azure OpenAI của bạn:

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

Cấu hình trường plugins sẽ định cấu hình Plugins để sử dụng các mô hình Azure.

LƯU Ý: Cấu hình hiện tại thông qua librechat.yaml sử dụng mô hình chính mà bạn chọn từ giao diện người dùng cho việc sử dụng Plugin, điều này thường không giống với cách hoạt động khi không có Azure, nơi mà thay vào đó mô hình "Agent" được sử dụng. Cài đặt mô hình Agent có thể được bỏ qua khi sử dụng Plugins thông qua Azure.

Sử dụng Base URL được chỉ định với Azure

URL cơ sở cho các yêu cầu API Azure OpenAI có thể được cấu hình linh hoạt. Điều này hữu ích cho các dịch vụ proxy như Cloudflare AI Gateway, hoặc nếu bạn muốn ghi đè rõ ràng cách xử lý baseURL của ứng dụng.

LibreChat sẽ sử dụng trường baseURL cho nhóm mô hình Azure của bạn, trường này có thể bao gồm các trình giữ chỗ (placeholders) cho tên phiên bản và tên triển khai của Azure OpenAI API.

Trong cấu hình, base URL có thể được tùy chỉnh như sau:

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

LƯU Ý: ${INSTANCE_NAME} và ${DEPLOYMENT_NAME} là các trình giữ chỗ duy nhất và không tương ứng với các biến môi trường, mà thay vào đó tương ứng với tên instance và tên deployment của mô hình hiện đang được chọn. Bạn không nên sử dụng INSTANCE_NAME và DEPLOYMENT_NAME làm tên biến môi trường để tránh mọi xung đột tiềm ẩn.

Bạn cũng có thể bỏ qua hoàn toàn các trình giữ chỗ (placeholders) và chỉ cần xây dựng baseURL với thông tin xác thực của mình:

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

Cuối cùng, bạn có thể chỉ định toàn bộ baseURL thông qua một biến môi trường tùy chỉnh

      baseURL: "${MY_CUSTOM_BASEURL}"

Kích hoạt Tự động tạo Tiêu đề với Azure

Để bật tính năng đặt tiêu đề cho Azure, hãy đặt titleConvo thành true.

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

Bạn cũng có thể chỉ định model để sử dụng cho việc đặt tiêu đề, với titleModel miễn là bạn đã cấu hình nó trong (các) nhóm của mình.

    titleModel: "gpt-3.5-turbo"

Lưu ý: "gpt-3.5-turbo" là giá trị mặc định, vì vậy bạn có thể bỏ qua nếu muốn sử dụng chính xác mô hình này và đã cấu hình nó. Nếu chưa được cấu hình và titleConvo được đặt thành true, quá trình đặt tiêu đề sẽ dẫn đến lỗi và không có tiêu đề nào được tạo. Bạn cũng có thể thiết lập giá trị này để sử dụng linh hoạt mô hình hiện tại bằng cách đặt nó thành current_model.

    titleModel: "current_model"

Sử dụng GPT-4 Vision với Azure

Để sử dụng Vision (phân tích hình ảnh) với Azure OpenAI, hãy đảm bảo gpt-4-vision-preview là một model được chỉ định trong một trong các nhóm của bạn.

Điều này hoạt động tương tự như với endpoint OpenAI: không cần phải chọn model vision, vì nó sẽ được tự động chuyển đổi ở phía sau.

Tạo hình ảnh với Azure OpenAI Service (DALL-E)

• Trước tiên, bạn cần tạo một tài nguyên Azure để lưu trữ DALL-E
  • Tại thời điểm viết bài này, dall-e-3 khả dụng tại khu vực SwedenCentral, còn dall-e-2 khả dụng tại khu vực EastUS.
• Sau đó, bạn cần triển khai mô hình tạo ảnh trong một trong các khu vực nêu trên.
  • Đọc Hướng dẫn bắt đầu nhanh về tạo hình ảnh Azure OpenAI để được hỗ trợ thêm
• Cấu hình các biến môi trường của bạn dựa trên thông tin xác thực Azure:

Các tùy chọn cấu hình DALL-E:

DALL-E:

Các khóa API:

API Keys (Phiên bản cụ thể):

System Prompts:

Cài đặt Reverse Proxy:

Base URLs:

Tích hợp Azure OpenAI (Tùy chọn):

Thay thế văn bản giữ chỗ bằng các câu lệnh hoặc hướng dẫn thực tế, và cung cấp các khóa API của bạn nếu bạn chọn đưa chúng trực tiếp vào tệp (khuyến nghị nên quản lý các khóa nhạy cảm bên ngoài cơ sở mã). Hãy xem xét và tuân thủ các chính sách sử dụng của OpenAI khi nhúng khóa API vào phần mềm.

Lưu ý: nếu bạn đã thiết lập PROXY, nó cũng sẽ được sử dụng cho các lệnh gọi DALL-E, vốn là thiết lập chung cho toàn bộ ứng dụng.

Các Serverless Inference Endpoints

Thông qua tệp librechat.yaml, bạn có thể cấu hình các endpoint suy luận không máy chủ (serverless) của Azure AI Studio để truy cập các mô hình từ Azure AI Foundry. Chỉ cần có định danh mô hình, baseURL và apiKey cùng với trường serverless để chỉ định cách xử lý đặc biệt mà các endpoint này yêu cầu.

• Bạn sẽ cần làm theo các hướng dẫn trong các model card tương thích để thiết lập quyền truy cập MaaS ("Models as a Service") trên Azure AI Studio.

  • Để tham khảo, dưới đây là một số model card tương thích đã được biết đến:

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

• Bạn cũng có thể xem blog kỹ thuật về bản phát hành mô hình "Mistral-large" để biết thêm thông tin.

• Sau đó, bạn sẽ cần thêm chúng vào cấu hình azureOpenAI của mình trong tệp librechat.yaml.

• Dưới đây là ví dụ cấu hình cho 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

Ghi chú:

• Các mô hình Azure AI Foundry hiện cung cấp các endpoint theo đường dẫn /models/chat/completions?api-version=version để thực hiện suy luận serverless.
  • Trường baseURL nên được đặt thành gốc của endpoint, không bao gồm bất kỳ nội dung nào sau /models/, tức là đường dẫn /chat/completions.
  • Ví dụ: https://example.services.ai.azure.com/models/ cho https://example.services.ai.azure.com/models/chat/completions?api-version=2024-05-01-preview
  • Tham số truy vấn version là tùy chọn và có thể được chỉ định trong trường baseURL.
• Tên model được sử dụng trong trường models phải khớp với tên triển khai của model trong Azure AI Foundry.
• Khả năng tương thích với LibreChat dựa trên sự tương đồng với các thông số kỹ thuật của OpenAI API, mà tại thời điểm viết bài này, thường là các triển khai "Pay-as-you-go" hoặc "Models as a Service" (MaaS) trên Azure AI Studio, vốn tương thích với OpenAI-SDK thông qua việc xử lý endpoint v1/completions hoặc models/chat/completions.
• Tất cả các model cung cấp triển khai serverless ("Serverless APIs") từ danh mục model của Azure đều tương thích. Bạn có thể lọc theo "Serverless API" trong phần Deployment options và "Chat completion" trong phần inference tasks để xem danh sách đầy đủ; tuy nhiên, các model real time endpoint vẫn chưa được kiểm thử.
• Các endpoint/model suy luận serverless này có thể hỗ trợ hoặc không hỗ trợ gọi hàm (function calling) theo thông số kỹ thuật của OpenAI API, điều này cho phép chúng được sử dụng với các Agents.