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 설정 구성: 아래에 명시된 구조를 따라 API 키, 인스턴스 이름, 모델 그룹 및 기타 구성을 포함한 Azure OpenAI 설정을 입력하세요.

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)

그룹 수준 구성

Custom Config (librechat.yaml) 파일에서 구성 가능한 필드입니다. 각 필드에 대한 자세한 내용은 Custom Config 문서의 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)

모델 수준 구성 (Model-Level Configuration)

각 그룹 내에서 models 필드는 모델 식별자와 해당 구성 간의 매핑을 포함합니다:

모델 식별:

모델 구성:

Serverless Inference Endpoints:

• 모델 식별자는 해당 OpenAI 모델 이름과 일치해야 올바른 컨텍스트 제한이 반영되거나 비전(vision) 기능이 정상적으로 작동합니다. 예를 들어, 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. 필수 필드 누락: 그룹 수준(boolean 플래그가 설정된 모델의 경우) 또는 모델 구성 내(상속되지 않거나 명시적으로 지정되지 않은 경우)에 필수 deploymentName 또는 version이 없으면, 해당 그룹이 serverless inference endpoint를 나타내는 경우가 아닌 한 유효성 검사 오류가 발생합니다.

3. 환경 변수 참조: 이 설정은 환경 변수 참조(예: ${VARIABLE_NAME})를 지원합니다. 런타임 오류를 방지하려면 참조된 모든 변수가 환경에 존재하는지 확인하십시오. 설정 파일에서 참조된 환경 변수가 정의되어 있지 않으면 오류가 발생합니다. ${INSTANCE_NAME} 및 ${DEPLOYMENT_NAME}은 고유한 자리 표시자이며, 환경 변수에 대응하지 않고 현재 선택된 모델의 인스턴스 및 배포 이름에 대응합니다. 잠재적인 충돌을 방지하기 위해 INSTANCE_NAME 및 DEPLOYMENT_NAME을 환경 변수 이름으로 사용하는 것은 권장하지 않습니다.

4. 오류 처리: 중복된 이름, 정의되지 않은 환경 변수 또는 누락된 필수 필드와 같이 설정 내에 문제가 있는 경우, 해당 설정은 무효화되며 신속한 해결을 돕기 위한 설명이 포함된 오류 메시지가 생성됩니다. 유효하지 않은 설정으로는 서버를 실행할 수 없습니다.

5. 모델 식별자: (프로젝트에서) 알 수 없는 모델도 모델 식별자로 사용할 수 있지만, 메시지/토큰 처리에 중요한 알려진 컨텍스트 길이를 반영하려면 알려진 모델과 일치해야 합니다. 예를 들어, gpt-7000은 유효하지만 기본적으로 4k 토큰 제한이 적용되는 반면, gpt-4-turbo는 128k 컨텍스트 제한이 있는 것으로 인식됩니다.

최신 스키마 정의 및 가이드라인에 따라 구성을 검증하여 호환성을 유지하세요.

모델 배포 (Model Deployments)

사용자가 사용할 수 있는 모델 목록은 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를 사용하려면 2가지 주요 단계가 필요합니다.

1. Endpoint-level의 azureOpenAI 엔드포인트 아래에 있는 assistants 필드를 다음과 같이 true로 설정하세요:

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

2. Azure의 Assistants API 통합과 호환되는 그룹에 assistants 필드를 추가하세요.

• 그룹 구성 중 최소 하나는 호환되어야 합니다.
• 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은 아직 지원되지 않습니다.

  • 지원되지 않는 동안 검색(retrieval) 관련 오류를 방지하려면 azureAssistants endpoint 설정에서 해당 기능을 완전히 비활성화하는 것이 좋습니다:

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

  • 기본적으로 retrieval을 제외한 모든 기능이 활성화되어 있습니다.

Azure에서 플러그인 사용하기

Azure OpenAI와 함께 Plugins endpoint를 사용하려면 **function calling**을 지원하는 배포가 필요합니다. 그렇지 않은 경우, Agent 설정에서 "Functions"를 끄십시오. "functions" 모드를 사용하지 않을 때는 에이전트가 생성한 내용을 검토하는 단계인 "skip completion"도 끄는 것을 권장합니다.

Plugins endpoint에서 Azure를 사용하려면, Azure OpenAI endpoint 설정에서 plugins 필드가 true로 설정되어 있는지 확인하세요:

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

plugins 필드를 구성하면 Azure 모델을 사용하도록 Plugins가 설정됩니다.

참고: librechat.yaml을 통한 현재 구성은 플러그인 사용을 위해 프론트엔드에서 선택한 기본 모델을 사용합니다. 이는 Azure를 사용하지 않을 때의 일반적인 방식과는 다르며, Azure를 사용할 때는 "에이전트(Agent)" 모델이 대신 사용됩니다. Azure를 통해 플러그인을 사용할 때는 에이전트 모델 설정을 무시해도 됩니다.

Azure에서 지정된 Base URL 사용하기

Azure OpenAI API 요청을 위한 기본 URL(base URL)은 동적으로 구성할 수 있습니다. 이는 Cloudflare AI Gateway와 같은 프록시 서비스를 사용하거나, 앱의 baseURL 처리를 명시적으로 재정의하려는 경우에 유용합니다.

LibreChat은 Azure 모델 그룹화에 baseURL 필드를 사용하며, 여기에는 Azure OpenAI API 인스턴스 및 배포 이름에 대한 자리 표시자(placeholder)가 포함될 수 있습니다.

설정에서 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을 구성했다면, 이를 사용하여 제목 생성에 사용할 모델을 지정할 수도 있습니다.

    titleModel: "gpt-3.5-turbo"

참고: "gpt-3.5-turbo"가 기본값이므로, 이 모델을 그대로 사용하도록 구성되어 있다면 생략할 수 있습니다. 구성되지 않은 상태에서 titleConvo가 true로 설정되어 있으면 제목 생성 과정에서 오류가 발생하며 제목이 생성되지 않습니다. 또한 이를 current_model로 설정하여 현재 모델을 동적으로 사용하도록 할 수도 있습니다.

    titleModel: "current_model"

Azure에서 GPT-4 Vision 사용하기

Azure OpenAI에서 Vision(이미지 분석)을 사용하려면 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 (버전별):

시스템 프롬프트(System Prompts):

Reverse Proxy 설정:

기본 URL (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("Models as a Service") 액세스를 설정하려면 호환되는 모델 카드에 있는 지침을 따라야 합니다.

  • 참고를 위해, 호환되는 것으로 알려진 몇 가지 모델 카드는 다음과 같습니다:

  • 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 필드는 /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(Models as a Service)" 배포 방식이며, v1/completions 또는 models/chat/completions endpoint 처리를 통해 OpenAI-SDK와 호환됩니다.
• Azure 모델 카탈로그에서 서버리스 배포("Serverless APIs")를 제공하는 모든 모델은 호환됩니다. 배포 옵션(Deployment options)에서 "Serverless API"를, 추론 작업(inference tasks)에서 "Chat completion"을 필터링하여 전체 목록을 확인할 수 있습니다. 단, 실시간 endpoint 모델은 테스트되지 않았습니다.
• 이러한 서버리스 추론 endpoint/모델은 OpenAI API 사양에 따라 함수 호출(function calling)을 지원할 수도, 지원하지 않을 수도 있으며, 이는 Agents와 함께 사용할 수 있는지를 결정합니다.