diffusers/main/vi/installation.md

Cài đặt

Diffusers yêu cầu Python 3.10+ và được kiểm thử với PyTorch 2.6+. Cài đặt PyTorch theo hệ thống và cấu hình của bạn.

Tạo một môi trường ảo để quản lý các dự án riêng biệt dễ dàng hơn và tránh các vấn đề tương thích giữa các phụ thuộc. Sử dụng uv, một trình quản lý gói và dự án Python dựa trên Rust, để tạo môi trường ảo và cài đặt Diffusers.

uv venv my-env
source my-env/bin/activate

Cài đặt Diffusers bằng một trong các phương pháp sau.

uv pip install diffusers["torch"] transformers

Để cài đặt Diffusers với PyTorch trên các thiết bị NVIDIA Spark (chẳng hạn như laptop RTX Spark) chạy ARM64, hãy cài đặt PyTorch từ chỉ mục PyPI của NVIDIA. Các thiết bị này yêu cầu các bản dựng ARM64 của PyTorch do NVIDIA cung cấp, vốn không có sẵn trên chỉ mục PyPI mặc định hay chỉ mục wheel PyTorch tiêu chuẩn.

Chạy lệnh bên dưới để kiểm tra xem hệ thống của bạn có phát hiện được GPU NVIDIA hay không.

nvidia-smi

Cài đặt PyTorch từ chỉ mục PyPI của NVIDIA, sau đó cài đặt Diffusers.

uv pip install torch --index-url https://pypi.nvidia.com
uv pip install diffusers

conda install -c conda-forge diffusers

Cài đặt từ mã nguồn sẽ cài đặt phiên bản main thay vì phiên bản stable mới nhất. Phiên bản main hữu ích để cập nhật các thay đổi mới nhất nhưng có thể không luôn ổn định. Nếu bạn gặp vấn đề, hãy mở một Issue và chúng tôi sẽ cố gắng giải quyết sớm nhất có thể.

Hãy đảm bảo rằng Accelerate đã được cài đặt.

uv pip install accelerate

Cài đặt Diffusers từ mã nguồn bằng lệnh bên dưới.

uv pip install git+https://github.com/huggingface/diffusers

Cài đặt kèm các gói bổ sung khi bạn cần. diffusers["torch"] sẽ kéo theo PyTorch và Accelerate. Các gói bổ sung khác bao gồm các backend lượng tử hóa, huấn luyện và tài liệu. Xem setup.py để biết danh sách đầy đủ.

Thiết bị

Diffusers chạy trên bất kỳ bộ tăng tốc nào được PyTorch hỗ trợ. Các ví dụ trong tài liệu sử dụng "cuda" vì đây là cấu hình phổ biến nhất, nhưng không có gì đặc thù cho CUDA. Hãy thay chuỗi thiết bị bằng phần cứng của bạn, chẳng hạn như "xpu" cho GPU Intel, "mps" cho Apple silicon, hoặc "cpu".

device = "cuda"  # or "mps", "xpu", "cpu"
pipeline.to(device)

Để chọn thiết bị khi chạy thay vì hardcode, hãy sử dụng torch.accelerator.

import torch

device = torch.accelerator.current_accelerator().type if torch.accelerator.is_available() else "cpu"

Cài đặt có thể chỉnh sửa

Cài đặt dạng có thể chỉnh sửa được khuyến nghị cho các quy trình phát triển hoặc khi bạn đang sử dụng phiên bản main của mã nguồn. Một liên kết đặc biệt được tạo giữa kho đã clone và các đường dẫn thư viện Python. Điều này giúp tránh việc phải cài đặt lại gói sau mỗi lần thay đổi.

Clone kho lưu trữ và cài đặt Diffusers bằng các lệnh sau.

git clone https://github.com/huggingface/diffusers.git
cd diffusers
uv pip install -e ".[torch]"

Bạn phải giữ lại thư mục diffusers nếu muốn tiếp tục sử dụng thư viện với cài đặt dạng có thể chỉnh sửa.

Cập nhật kho mã đã nhân bản của bạn lên phiên bản Diffusers mới nhất bằng lệnh bên dưới.

cd ~/diffusers/
git pull

Bộ nhớ đệm

Trọng số và tệp của mô hình được tải xuống từ Hub vào bộ nhớ đệm, thường là thư mục home của bạn. Thay đổi vị trí bộ nhớ đệm bằng các biến môi trường HF_HOME hoặc HF_HUB_CACHE hoặc bằng cách cấu hình tham số cache_dir trong các phương thức như from_pretrained().

export HF_HOME="/path/to/your/cache"
export HF_HUB_CACHE="/path/to/your/hub/cache"

from diffusers import DiffusionPipeline

pipeline = DiffusionPipeline.from_pretrained(
    "black-forest-labs/FLUX.1-dev",
    cache_dir="/path/to/your/cache"
)

Các tệp được lưu trong bộ nhớ đệm cho phép bạn sử dụng Diffusers ngoại tuyến. Đặt biến môi trường HF_HUB_OFFLINE thành 1 để ngăn Diffusers kết nối với internet.

export HF_HUB_OFFLINE=1

Để biết thêm chi tiết về việc quản lý và dọn dẹp bộ nhớ đệm, hãy xem hướng dẫn Hiểu về bộ nhớ đệm.

Chia sẻ tệp giữa các kho

Bộ nhớ đệm chỉ giữ một bản sao của tệp ngay cả khi nhiều kho Hub chứa tệp đó. Nhiều pipeline sử dụng cùng một text encoder, chẳng hạn như T5. Nếu kho của pipeline thứ hai có các tệp text encoder giống với những tệp bạn đã tải xuống trước đó, from_pretrained() sẽ sử dụng bản sao trên đĩa thay vì tải xuống lại. Diffusers yêu cầu huggingface_hub>=1.32.0, phiên bản này bật chia sẻ tệp theo mặc định.

Bộ nhớ đệm khớp các tệp theo hash Xet của chúng, không phải theo tên kho hoặc tên mô hình. Một checkpoint phân mảnh được khớp từng mảnh một, do đó các mảnh khớp nhau sẽ được chia sẻ ngay cả khi các mảnh khác khác biệt.

Một tệp chỉ được chia sẻ khi tất cả các điều kiện sau đều đúng:

• Cả hai kho lưu trữ đều lưu trữ tệp bằng Xet.
• Cả hai lượt tải đều sử dụng cùng một thư mục cache, được đặt bởi HF_HUB_CACHE hoặc cache_dir.
• Hệ thống tệp hỗ trợ liên kết mềm (symlinks).
• Các tệp giống hệt nhau từng byte. Việc chuyển sang một dtype khác, lưu ở một định dạng khác, hoặc chia lại shard sẽ làm thay đổi hash.

Các tệp bạn đã tải xuống bằng phiên bản cũ hơn của huggingface_hub không được chia sẻ với các lần tải xuống mới. Chỉ các tệp được tải xuống bằng phiên bản 1.32.0 trở lên mới được thêm vào kho lưu trữ chung.

Chia sẻ tệp giúp tiết kiệm thời gian tải xuống và dung lượng ổ đĩa, nhưng không tiết kiệm bộ nhớ. Để sử dụng một mô hình đã tải trong nhiều pipeline, xem Tái sử dụng mô hình trong nhiều pipeline.

Để tắt chia sẻ tệp, hãy đặt HF_HUB_DISABLE_SHARED_BLOBS=1. Việc tải vẫn hoạt động bình thường, và mỗi kho lưu trữ sẽ giữ một bản sao riêng.

export HF_HUB_DISABLE_SHARED_BLOBS=1

Ghi nhật ký đo lường

Diffusers thu thập thông tin đo lường trong các yêu cầu from_pretrained(). Dữ liệu được thu thập bao gồm phiên bản Diffusers và PyTorch, lớp model hoặc pipeline được yêu cầu, và đường dẫn đến checkpoint được huấn luyện trước nếu nó được lưu trữ trên Hub.

Dữ liệu sử dụng này giúp chúng tôi gỡ lỗi các vấn đề và ưu tiên phát triển các tính năng mới. Telemetry chỉ được gửi khi tải các model và pipeline từ Hub, và sẽ không được thu thập nếu bạn đang tải các tệp cục bộ.

Tắt và vô hiệu hóa việc thu thập dữ liệu đo lường bằng biến môi trường HF_HUB_DISABLE_TELEMETRY.

export HF_HUB_DISABLE_TELEMETRY=1

set HF_HUB_DISABLE_TELEMETRY=1