LibreChat 的 Azure OpenAI 集成

LibreChat 将 Azure OpenAI API 服务作为一等 endpoint 提供支持。要在 LibreChat 中使用 Azure OpenAI，请针对您的设置配置 librechat.yaml 文件。本文档涵盖了使用多个部署和模型的设置过程。

示例

一个包含下述许多选项和功能的配置示例：

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

此示例遵循 Azure OpenAI Endpoint Configuration Docs。

每一级配置的详细信息请参阅其各自的章节：

1. 端点级配置

2. 组级配置

3. 模型级配置

设置

1. 编辑 librechat.yaml：使用您偏好的文本编辑器或 IDE 打开并编辑 librechat.yaml 文件。

   • 可选：使用以下环境变量来指定远程或自定义文件路径：

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

2. 配置 Azure OpenAI 设置：请遵循下述结构来填充您的 Azure OpenAI 设置，包括 API 密钥、实例名称、模型组以及其他配置。

3. 移除旧版设置：如果您正在使用任何旧版配置，请将其移除。LibreChat 服务器也会检测到这些配置并提醒您。

4. 保存更改：保存 librechat.yaml 文件。

5. 重启 LibreChat：重启您的 LibreChat 应用程序，以便加载更新后的配置。

必需字段

要将 Azure OpenAI 集成到 LibreChat 中，必须在您的 librechat.yaml 文件中配置特定字段。这些字段通过自定义变量和环境变量的组合进行验证。详细要求如下。

Endpoint-Level Configuration

全局 Azure 设置：

标题和对话设置：

群组配置：

自定义排序（可选）：

customOrder 选项已被注释掉，因为它是可选的。

在您的 librechat.yaml 文件中，这些 endpoint 级别设置的示例如下：

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)

组级别配置

可在自定义配置 (librechat.yaml) 文件中配置的字段。有关每个字段的更多信息，请参阅 自定义配置文档中的 Azure OpenAI 部分。

组级配置： 组标识：

身份验证：

Azure OpenAI 实例：

部署配置：

高级设置：

模型配置：

在 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)

模型级配置

在每个组内，models 字段包含模型标识符与其配置之间的映射：

模型标识：

模型配置：

无服务器推理端点 (Serverless Inference Endpoints):

• 模型标识符必须与其对应的 OpenAI 模型名称匹配，以便它能够正确反映其已知的上下文限制和/或在视觉功能方面正常工作。例如，如果您打算使用 gpt-4-vision，则必须按如下方式进行配置：

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

• 请参阅 Model Deployments 以获取更多示例。

• 如果一个模型被设置为 true，则意味着该模型将使用组级别的 deploymentName 和 version。在这种情况下，两者都必须在组级别进行定义。

• 如果模型被配置为一个对象，它可以指定自己的 deploymentName 和 version。如果未提供这些信息，模型将继承该组的 deploymentName 和 version。

• 如果该组代表一个 serverless inference endpoint，则应将 singular model 设置为 true 以将其添加到模型列表中。

特别注意事项

1. 唯一名称：模型名称和组名称在整个配置中都必须是唯一的。重复的名称会导致验证失败。

2. 缺少必填字段：如果在组级别（针对布尔标志模型）或模型配置内（如果未继承或未明确指定）缺少必填的 deploymentName 或 version，将会导致验证错误，除非该组代表一个 serverless inference endpoint。

3. 环境变量引用：该配置支持环境变量引用（例如 ${VARIABLE_NAME}）。请确保所有引用的变量都存在于您的环境中，以避免运行时错误。配置中引用的环境变量如果未定义，将会导致错误。${INSTANCE_NAME} 和 ${DEPLOYMENT_NAME} 是特殊的占位符，它们不对应环境变量，而是对应当前所选模型的实例名称和部署名称。不建议将 INSTANCE_NAME 和 DEPLOYMENT_NAME 用作环境变量名称，以避免任何潜在的冲突。

4. 错误处理: 配置中的任何问题，例如名称重复、未定义的环境变量或缺少必填字段，都将导致设置失效，并生成旨在快速解决问题的描述性错误消息。如果配置无效，您将无法运行服务器。

5. 模型标识符 (Model identifiers)：一个（对本项目而言）未知的模型可以用作模型标识符，但它必须匹配一个已知模型，以便反映其已知的上下文长度，这对于消息/令牌处理至关重要；例如，gpt-7000 将是有效的，但会默认使用 4k 令牌限制，而 gpt-4-turbo 将被识别为具有 128k 上下文限制。

根据最新的模式定义和指南验证您的配置，以保持兼容性。

模型部署

用户可用的模型列表由您在 azureOpenAI endpoint 配置 中指定的模型分组决定。

例如：

# 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

上述配置将按照定义的顺序为您的用户启用 gpt-4-vision-preview、gpt-3.5-turbo 和 gpt-4-turbo。

在 Azure 中使用 Assistants

要启用 Azure OpenAI 的 Assistants 功能，主要有两个步骤。

1. 在 azureOpenAI endpoint 下方（即 Endpoint-level）将 assistants 字段设置为 true，如下所示：

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

2. 将 assistants 字段添加到与 Azure 的 Assistants API 集成兼容的组中。

• 您的组配置中至少必须有一个是兼容的。
• 您可以在 Azure 文档中查看兼容的区域和模型。
• 版本必须为 "2024-02-15-preview" 或更高版本，建议使用更高版本以获取最新功能。

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)

注意：

• 对于凭据，请依赖在每个兼容 assistants 的组配置中指定的自定义环境变量。

• 如果您将多个区域标记为 assistants-compatible，您创建的助手将跨区域聚合到主助手选择列表中。

• 您上传到 Azure OpenAI 的文件（无论是消息级别还是助手级别）将仅在当前助手模型所属的区域内可用。

  • 出于这个原因，建议您仅为 Azure OpenAI Assistants 使用一个区域或资源组，否则将会遇到错误。
  • 对于官方的 code_interpreter 和 retrieval 功能，上传到 "OpenAI" 是默认行为。

• 即将支持下载助手生成的文件。

• 截至 2024 年 5 月 19 日，Azure OpenAI 尚不支持检索（retrieval）和流式传输（streaming）。

  • 为避免在不支持检索功能时出现任何错误，建议通过 azureAssistants endpoint 配置完全禁用该功能：

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

  • 默认情况下，除 retrieval 外的所有功能均已启用。

在 Azure 中使用插件

若要将 Plugins endpoint 与 Azure OpenAI 配合使用，你需要一个支持 function calling 的部署。否则，请在 Agent 设置中关闭“Functions”。当你未使用“functions”模式时，建议同时关闭“skip completion”，这是一个对 Agent 生成内容进行审查的步骤。

若要将 Azure 与 Plugins endpoint 配合使用，请确保在您的 Azure OpenAI endpoint 配置中将 plugins 字段设置为 true：

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

配置 plugins 字段将配置 Plugins 以使用 Azure 模型。

注意：目前通过 librechat.yaml 进行的配置使用您从前端选择的主模型来使用插件，这通常不是在没有 Azure 的情况下的工作方式，在没有 Azure 时，会改用“Agent”模型。当通过 Azure 使用插件时，可以忽略 Agent 模型设置。

在 Azure 中使用指定的 Base URL

Azure OpenAI API 请求的 base URL 可以进行动态配置。这对于代理服务（例如 Cloudflare AI Gateway）非常有用，或者如果您希望显式覆盖应用程序的 baseURL 处理方式，也可以使用此功能。

LibreChat 将使用 baseURL 字段进行 Azure 模型分组，其中可以包含 Azure OpenAI API 实例和部署名称的占位符。

在配置中，可以按如下方式自定义 base URL：

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

注意：${INSTANCE_NAME} 和 ${DEPLOYMENT_NAME} 是唯一的占位符，它们不对应环境变量，而是对应当前所选模型的实例名称和部署名称。不建议将 INSTANCE_NAME 和 DEPLOYMENT_NAME 用作环境变量名称，以避免任何潜在的冲突。

您也可以完全省略占位符，直接使用您的凭据构建 baseURL：

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

最后，你可以通过自定义环境变量来指定整个 baseURL

      baseURL: "${MY_CUSTOM_BASEURL}"

使用 Azure 启用自动生成标题

要为 Azure 启用标题生成功能，请将 titleConvo 设置为 true。

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

你也可以通过 titleModel 指定用于生成标题的模型，前提是你已经在你的组（group(s)）中进行了配置。

    titleModel: "gpt-3.5-turbo"

注意：“gpt-3.5-turbo” 是默认值，因此如果您想使用此确切模型并已对其进行配置，则可以省略它。如果未配置且 titleConvo 设置为 true，则标题生成过程将导致错误，且不会生成标题。您也可以将其设置为 current_model，以动态使用当前模型。

    titleModel: "current_model"

在 Azure 上使用 GPT-4 Vision

若要将 Vision（图像分析）与 Azure OpenAI 配合使用，请确保 gpt-4-vision-preview 是您的分组之一中指定的模型。

这与 OpenAI endpoint 的工作方式相同：无需手动选择视觉模型，系统会在后台自动切换。

使用 Azure OpenAI Service 生成图像 (DALL-E)

• 首先，你需要创建一个托管 DALL-E 的 Azure 资源。
  • 在撰写本文时，dall-e-3 可在 SwedenCentral 区域使用，dall-e-2 可在 EastUS 区域使用。
• 然后，你需要在上述区域之一中部署图像生成模型。
  • 请阅读 Azure OpenAI Image Generation Quickstart Guide 以获取进一步的帮助。
• 根据 Azure 凭据配置您的环境变量：

DALL-E 配置选项：

DALL-E:

API Keys:

API Keys (Version Specific):

系统提示词 (System Prompts):

反向代理设置：

Base URLs:

Azure OpenAI 集成（可选）：

将占位符文本替换为实际的提示词或指令，如果您选择直接在文件中包含 API 密钥，请提供它们（建议在代码库之外管理敏感密钥）。在软件中嵌入 API 密钥时，请查阅并遵守 OpenAI 的使用政策。

注意：如果您设置了 PROXY，它也将用于 DALL-E 调用，这适用于整个应用程序。

Serverless Inference Endpoints

通过 librechat.yaml 文件，您可以配置 Azure AI Studio 无服务器推理端点，以访问来自 Azure AI Foundry 的模型。除了需要 serverless 字段来指示这些端点所需的特殊处理外，仅需提供模型标识符、baseURL 和 apiKey。

• 您需要按照兼容模型卡片中的说明，在 Azure AI Studio 上设置 MaaS（“模型即服务”）访问权限。

  • 作为参考，以下是一些已知的兼容模型卡片：

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

• 您也可以查阅 “Mistral-large” 模型发布的技术博客 以获取更多信息。

• 然后，你需要将它们添加到 librechat.yaml 文件中的 azureOpenAI 配置中。

• 以下是 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

注意:

• Azure AI Foundry 模型现在为无服务器推理在 /models/chat/completions?api-version=version 下配置 endpoint。
  • baseURL 字段应设置为 endpoint 的根路径，不应包含 /models/ 之后的任何内容，即不应包含 /chat/completions 路径。
  • 示例：https://example.services.ai.azure.com/models/ 对应 https://example.services.ai.azure.com/models/chat/completions?api-version=2024-05-01-preview
  • version 查询参数是可选的，可以在 baseURL 字段中指定。
• models 字段中使用的模型名称必须与 Azure AI Foundry 中模型的部署名称一致。
• 与 LibreChat 的兼容性依赖于与 OpenAI API 规范的一致性，在撰写本文时，这些规范通常是 Azure AI Studio 上的 “即用即付” (Pay-as-you-go) 或 “模型即服务” (MaaS) 部署，它们是与 OpenAI-SDK 兼容的，并处理 v1/completions 或 models/chat/completions endpoint。
• 所有提供无服务器部署（"Serverless APIs"）的模型均与 Azure 模型目录兼容。您可以在“部署选项”（Deployment options）下筛选“Serverless API”，并在“推理任务”（inference tasks）下筛选“Chat completion”以查看完整列表；但实时 endpoint 模型尚未经过测试。
• 根据 OpenAI API 规范，这些无服务器推理 endpoint/模型可能支持也可能不支持函数调用，而函数调用是其与 Agents 配合使用的前提。