Azure Blob Storage

Thiết lập môi trường Production

Azure Blob Storage cung cấp khả năng lưu trữ đối tượng có thể mở rộng và bảo mật cho các tệp tin trong LibreChat. Hãy làm theo các bước sau để cấu hình Azure Blob Storage của bạn.

1. Tạo một Azure Storage Account

1. Đăng nhập vào Azure:

   • Mở Azure Portal và đăng nhập bằng tài khoản Microsoft của bạn.

2. Tạo một Storage Account:

   • Nhấp vào "Create a resource" và tìm kiếm "Storage account".
   • Nhấp vào "Create" và điền các thông tin chi tiết được yêu cầu:
     • Subscription & Resource Group: Chọn subscription của bạn và chọn một resource group hiện có hoặc tạo mới.
     • Tên tài khoản lưu trữ (Storage Account Name): Nhập một tên duy nhất (ví dụ: mylibrechatstorage).
     • Region: Chọn khu vực gần với người dùng của bạn nhất.
     • Hiệu suất & Dự phòng: Chọn cấp độ hiệu suất và mức độ dự phòng phù hợp nhất với nhu cầu của bạn.
   • Nhấp vào "Review + Create" và sau đó là "Create". Đợi cho đến khi quá trình triển khai hoàn tất.

2. Thiết lập xác thực

Bạn có hai tùy chọn để xác thực với Azure Storage Account của mình:

Tùy chọn A: Sử dụng chuỗi kết nối (Connection String)

1. Điều hướng đến Access Keys:

   • Trong tài khoản lưu trữ mới tạo của bạn, hãy đi tới "Access keys" ở thanh bên.

2. Sao chép chuỗi kết nối:

   • Sao chép một trong các chuỗi kết nối được cung cấp. Chuỗi này bao gồm các thông tin xác thực cần thiết để kết nối với tài khoản Blob Storage của bạn.

Tùy chọn B: Sử dụng Managed Identity

Nếu ứng dụng LibreChat của bạn đang chạy trên một dịch vụ Azure hỗ trợ Managed Identity (chẳng hạn như Azure VM, App Service hoặc AKS), bạn có thể sử dụng tính năng đó thay vì chuỗi kết nối (connection string).

1. Gán Managed Identity:

   • Đảm bảo tài nguyên Azure của bạn (VM, App Service hoặc AKS) đã được bật Managed Identity do hệ thống chỉ định hoặc do người dùng chỉ định.

2. Cấp quyền lưu trữ:

   • Trong tài khoản lưu trữ của bạn, hãy gán vai trò Storage Blob Data Contributor (hoặc một vai trò có phạm vi tương tự) cho Managed Identity của bạn. Điều này cho phép ứng dụng của bạn truy cập Blob Storage mà không cần chuỗi kết nối (connection string).

3. Cập nhật các biến môi trường của bạn

Tạo hoặc cập nhật tệp .env của bạn trong thư mục gốc của dự án với cấu hình sau:

# 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: Thiết lập biến này nếu bạn đang sử dụng Tùy chọn A.
• AZURE_STORAGE_ACCOUNT_NAME: Thiết lập biến này nếu bạn đang sử dụng Tùy chọn B (Managed Identity). Không được thiết lập cả hai.
• AZURE_STORAGE_PUBLIC_ACCESS: Đặt thành false nếu bạn không muốn các blob của mình có thể truy cập công khai theo mặc định. Đặt thành true nếu bạn cần quyền truy cập công khai (ví dụ: đối với các hình ảnh có thể xem công khai).
• AZURE_CONTAINER_NAME: Đây là tên container mà ứng dụng của bạn sẽ sử dụng (ví dụ: files). Ứng dụng sẽ tự động tạo container này nếu nó chưa tồn tại.

4. Cấu hình LibreChat để sử dụng Azure Blob Storage

Cập nhật tệp cấu hình LibreChat (librechat.yaml) của bạn để chỉ định rằng ứng dụng nên sử dụng Azure Blob Storage cho việc xử lý tệp:

version: 1.3.5
cache: true
fileStrategy: "azure_blob"

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

Tóm tắt

1. Tạo một Storage Account:
   Đăng nhập vào Azure Portal, tạo một storage account và đợi quá trình triển khai hoàn tất.

2. Thiết lập xác thực:

• Lựa chọn A: Lấy chuỗi kết nối từ "Access keys" trong tài khoản lưu trữ của bạn.
• Lựa chọn B: Sử dụng Managed Identity bằng cách bật tính năng này trên tài nguyên Azure của bạn và cấp các quyền lưu trữ thích hợp.

3. Cập nhật các biến môi trường:
   Trong tệp .env của bạn, hãy thiết lập một trong hai:

• AZURE_STORAGE_CONNECTION_STRING (cho Tùy chọn A), hoặc
• AZURE_STORAGE_ACCOUNT_NAME (cho Tùy chọn B), cùng với:
• AZURE_STORAGE_PUBLIC_ACCESS và
• AZURE_CONTAINER_NAME.

4. Cấu hình LibreChat:
   Đặt fileStrategy thành "azure_blob" trong tệp cấu hình librechat.yaml của bạn.

Với các bước này, ứng dụng LibreChat của bạn sẽ tự động tạo container (nếu nó chưa tồn tại) và quản lý việc tải lên, tải xuống cũng như xóa tệp bằng Azure Blob Storage. Managed Identity cung cấp một giải pháp thay thế an toàn bằng cách loại bỏ nhu cầu sử dụng thông tin xác thực dài hạn.

Phát triển cục bộ với Azurite

Để phát triển và kiểm thử cục bộ, bạn có thể sử dụng Azurite, một trình giả lập Azure Storage cung cấp môi trường cục bộ để kiểm thử tích hợp Azure Blob Storage của bạn mà không cần tài khoản Azure thực tế.

1. Thiết lập Azurite

Bạn có thể chạy Azurite theo một vài cách:

Tùy chọn A: Sử dụng tiện ích mở rộng VS Code (Khuyến nghị cho phát triển)

1. Cài đặt Azurite extension cho VS Code
2. Mở bảng lệnh (Ctrl+Shift+P hoặc Cmd+Shift+P)
3. Tìm kiếm và chọn "Azurite: Start"

Thao tác này sẽ khởi chạy Azurite ở chế độ nền với các cài đặt mặc định.

Lựa chọn B: Sử dụng Docker

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

Tùy chọn C: Sử dụng npm

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

2. Cấu hình các biến môi trường cho phát triển cục bộ

Thêm các biến môi trường sau vào tệp .env của bạn:

# 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

Ghi chú:

• Giá trị AccountKey là khóa phát triển mặc định được sử dụng bởi Azurite
• Kết nối sử dụng giao thức http thay vì https cho quá trình phát triển cục bộ
• BlobEndpoint trỏ đến instance Azurite cục bộ đang chạy trên cổng 10000

3. Xác minh kết nối

Để xác minh rằng ứng dụng của bạn có thể kết nối với instance Azurite cục bộ:

1. Khởi chạy ứng dụng LibreChat của bạn
2. Thử tải tệp lên thông qua giao diện
3. Kiểm tra nhật ký Azurite để xác nhận kết nối và các thao tác

Nếu bạn đang sử dụng tiện ích mở rộng VS Code, bạn có thể xem nhật ký Azurite trong bảng Output bằng cách chọn "Azurite Blob" từ menu thả xuống.