Azure Blob Storage

프로덕션 설정

Azure Blob Storage는 LibreChat에서 파일을 위한 확장 가능하고 안전한 객체 스토리지를 제공합니다. Azure Blob Storage를 구성하려면 다음 단계를 따르세요.

1. Azure Storage Account 생성하기

1. Azure에 로그인:

   • Azure Portal을 열고 Microsoft 계정으로 로그인하세요.

2. 스토리지 계정 생성:

   • **"Create a resource"**를 클릭하고 **"Storage account"**를 검색하세요.
   • **"Create"**를 클릭하고 필요한 세부 정보를 입력하세요:
     • 구독 및 리소스 그룹: 구독을 선택하고 기존 리소스 그룹을 선택하거나 새로 만드세요.
     • Storage Account Name: 고유한 이름을 입력하세요 (예: mylibrechatstorage).
     • Region: 사용자와 가장 가까운 리전을 선택하세요.
     • 성능 및 중복성: 귀하의 필요에 가장 적합한 성능 계층과 중복성 수준을 선택하십시오.
   • **"Review + Create"**를 클릭한 다음 **"Create"**를 클릭합니다. 배포가 완료될 때까지 기다립니다.

2. 인증 설정

Azure Storage Account로 인증하는 방법에는 두 가지 옵션이 있습니다:

옵션 A: 연결 문자열(Connection String) 사용하기

1. 액세스 키(Access Keys)로 이동:

   • 새로 생성한 스토리지 계정에서 사이드바의 **"Access keys"**로 이동하세요.

2. 연결 문자열 복사:

   • 제공된 연결 문자열 중 하나를 복사하세요. 이 문자열에는 Blob Storage 계정에 연결하는 데 필요한 자격 증명이 포함되어 있습니다.

옵션 B: 관리 ID(Managed Identity) 사용

LibreChat 애플리케이션이 Managed Identity를 지원하는 Azure 서비스(Azure VM, App Service, AKS 등)에서 실행 중인 경우, 연결 문자열(connection string) 대신 이를 사용할 수 있습니다.

1. 관리 ID 할당:

   • Azure 리소스(VM, App Service 또는 AKS)에 시스템 할당 또는 사용자 할당 Managed Identity가 활성화되어 있는지 확인하세요.

2. 저장소 권한 부여:

   • 스토리지 계정에서 Storage Blob Data Contributor(또는 이와 유사한 범위의 역할)를 관리 ID(Managed Identity)에 할당하세요. 이를 통해 애플리케이션이 연결 문자열 없이도 Blob Storage에 액세스할 수 있습니다.

3. 환경 변수 업데이트

프로젝트 루트에 있는 .env 파일을 생성하거나 업데이트하여 다음 구성을 추가하세요:

# Option A: Using a Connection String
AZURE_STORAGE_CONNECTION_STRING=DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=yourAccountKey;EndpointSuffix=core.windows.net

# Option B: Using Managed Identity (do not set the connection string if using Managed Identity)
AZURE_STORAGE_ACCOUNT_NAME=yourAccountName

AZURE_STORAGE_PUBLIC_ACCESS=false
AZURE_CONTAINER_NAME=files

• AZURE_STORAGE_CONNECTION_STRING: Option A를 사용하는 경우 이 값을 설정하세요.
• AZURE_STORAGE_ACCOUNT_NAME: 옵션 B(Managed Identity)를 사용하는 경우 이 항목을 설정하세요. 두 옵션을 모두 설정하지 마세요.
• AZURE_STORAGE_PUBLIC_ACCESS: 기본적으로 blob이 공개적으로 액세스되지 않기를 원하면 false로 설정하세요. 공개 액세스가 필요한 경우(예: 공개적으로 볼 수 있는 이미지) true로 설정하세요.
• AZURE_CONTAINER_NAME: 애플리케이션이 사용할 컨테이너 이름입니다(예: files). 애플리케이션은 해당 컨테이너가 존재하지 않을 경우 자동으로 생성합니다.

4. Azure Blob Storage를 사용하도록 LibreChat 구성하기

LibreChat 설정 파일(librechat.yaml)을 업데이트하여 애플리케이션이 파일 처리에 Azure Blob Storage를 사용하도록 지정하세요:

version: 1.3.5
cache: true
fileStrategy: "azure_blob"

fileStrategies:
  avatar: "firebase"
  image: "firebase"
  document: "azure_blob"

요약

1. 스토리지 계정 생성:
   Azure Portal에 로그인하여 스토리지 계정을 생성하고 배포가 완료될 때까지 기다립니다.

2. 인증 설정:

• 옵션 A: 스토리지 계정의 **"Access keys"**에서 연결 문자열을 검색합니다.
• 옵션 B: Azure 리소스에서 관리 ID(Managed Identity)를 활성화하고 적절한 스토리지 권한을 부여하여 사용합니다.

3. 환경 변수 업데이트:
   .env 파일에서 다음 중 하나를 설정하세요:

• AZURE_STORAGE_CONNECTION_STRING (옵션 A의 경우), 또는
• AZURE_STORAGE_ACCOUNT_NAME (옵션 B의 경우), 그리고 다음을 포함합니다:
• AZURE_STORAGE_PUBLIC_ACCESS 및
• AZURE_CONTAINER_NAME

4. LibreChat 구성:
   librechat.yaml 구성 파일에서 fileStrategy를 "azure_blob"으로 설정하세요.

이 단계를 따르면 LibreChat 애플리케이션이 자동으로 컨테이너를 생성하고(존재하지 않는 경우), Azure Blob Storage를 사용하여 파일 업로드, 다운로드 및 삭제를 관리합니다. Managed Identity는 장기 자격 증명이 필요 없는 안전한 대안을 제공합니다.

Azurite를 이용한 로컬 개발

로컬 개발 및 테스트를 위해 실제 Azure 계정 없이 Azure Blob Storage 통합을 테스트할 수 있는 로컬 환경을 제공하는 Azure Storage 에뮬레이터인 Azurite를 사용할 수 있습니다.

1. Azurite 설정하기

Azurite를 실행하는 방법은 여러 가지가 있습니다:

옵션 A: VS Code 확장 프로그램 사용 (개발 시 권장)

1. VS Code용 Azurite extension을 설치하세요.
2. 명령 팔레트(Ctrl+Shift+P 또는 Cmd+Shift+P)를 엽니다.
3. "Azurite: Start"를 검색하여 선택하세요

기본 설정으로 백그라운드에서 Azurite가 시작됩니다.

옵션 B: Docker 사용하기

docker run -p 10000:10000 -p 10001:10001 -p 10002:10002 mcr.microsoft.com/azure-storage/azurite

옵션 C: npm 사용하기

npm install -g azurite
azurite --silent --location /path/to/azurite/workspace --debug /path/to/debug/log

2. 로컬 개발을 위한 환경 변수 구성

.env 파일에 다음 환경 변수를 추가하세요:

# Azurite connection string for local development
AZURE_STORAGE_CONNECTION_STRING="DefaultEndpointsProtocol=http;AccountName=devstoreaccount1;AccountKey=Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==;BlobEndpoint=http://127.0.0.1:10000/devstoreaccount1;"
AZURE_STORAGE_PUBLIC_ACCESS=true
AZURE_CONTAINER_NAME=files

참고:

• AccountKey 값은 Azurite에서 사용하는 기본 개발 키입니다.
• 로컬 개발 환경에서는 https 대신 http 프로토콜을 사용하여 연결합니다.
• BlobEndpoint는 포트 10000에서 실행 중인 로컬 Azurite 인스턴스를 가리킵니다.

3. 연결 확인

애플리케이션이 로컬 Azurite 인스턴스에 연결할 수 있는지 확인하려면:

1. LibreChat 애플리케이션 시작하기
2. 인터페이스를 통해 파일을 업로드해 보세요
3. Azurite 로그를 확인하여 연결 및 작업을 확인하세요.

VS Code 확장을 사용 중이라면, 드롭다운에서 "Azurite Blob"을 선택하여 출력(Output) 패널에서 Azurite 로그를 확인할 수 있습니다.