Buckets:

hf-doc-build
/

doc

Files

xet

hf-doc-build/doc / diffusers /main /vi /installation.md

mishig

1 day ago

preview code

download

raw

9.2 kB

# 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](https://pytorch.org/get-started/locally/) theo hệ thống và cấu hình của bạn.

Tạo một [môi trường ảo](https://packaging.python.org/guides/installing-using-pip-and-virtual-environments/) để 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](https://docs.astral.sh/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.

```bash
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.

```bash
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.

```bash
nvidia-smi
```

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

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

```bash
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](https://github.com/huggingface/diffusers/issues/new/choose) 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](https://huggingface.co/docs/accelerate/index) đã được cài đặt.

```bash
uv pip install accelerate
```

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

```bash
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`](https://github.com/huggingface/diffusers/blob/main/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"`.

```py
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](https://docs.pytorch.org/docs/stable/accelerator.html).

```py
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.

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

> [!WARNING]
> 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.

```bash
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](https://huggingface.co/docs/huggingface_hub/package_reference/environment_variables#hfhome) hoặc [HF_HUB_CACHE](https://huggingface.co/docs/huggingface_hub/package_reference/environment_variables#hfhubcache) hoặc bằng cách cấu hình tham số `cache_dir` trong các phương thức như [from_pretrained()](/docs/diffusers/main/vi/api/pipelines/overview#diffusers.DiffusionPipeline.from_pretrained).

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

```py
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](https://huggingface.co/docs/huggingface_hub/package_reference/environment_variables#hfhuboffline) thành `1` để ngăn Diffusers kết nối với internet.

```shell
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](https://huggingface.co/docs/huggingface_hub/guides/manage-cache).

### 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()](/docs/diffusers/main/vi/api/pipelines/overview#diffusers.DiffusionPipeline.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](https://huggingface.co/docs/hub/xet/index) 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.

> [!NOTE]
> 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](./using-diffusers/loading#reusing-models-in-multiple-pipelines).
Để 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.
```shell
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()](/docs/diffusers/main/vi/api/pipelines/overview#diffusers.DiffusionPipeline.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](https://huggingface.co/docs/huggingface_hub/package_reference/environment_variables#hfhubdisabletelemetry).
```bash
export HF_HUB_DISABLE_TELEMETRY=1
```
```bash
set HF_HUB_DISABLE_TELEMETRY=1
```

Xet Storage Details

Size:: 9.2 kB
Xet hash:: cc1edf86b507b7604d6489837d70456284525efb34029f1c9bf21e81cff0f385

Xet efficiently stores files, intelligently splitting them into unique chunks and accelerating uploads and downloads. More info.

	# 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](https://pytorch.org/get-started/locally/) theo hệ thống và cấu hình của bạn.

	Tạo một [môi trường ảo](https://packaging.python.org/guides/installing-using-pip-and-virtual-environments/) để 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](https://docs.astral.sh/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.

	```bash
	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.

	```bash
	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.

	```bash
	nvidia-smi
	```

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

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

	```bash
	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](https://github.com/huggingface/diffusers/issues/new/choose) 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](https://huggingface.co/docs/accelerate/index) đã được cài đặt.

	```bash
	uv pip install accelerate
	```

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

	```bash
	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`](https://github.com/huggingface/diffusers/blob/main/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"`.

	```py
	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](https://docs.pytorch.org/docs/stable/accelerator.html).

	```py
	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.

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

	> [!WARNING]
	> 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.

	```bash
	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](https://huggingface.co/docs/huggingface_hub/package_reference/environment_variables#hfhome) hoặc [HF_HUB_CACHE](https://huggingface.co/docs/huggingface_hub/package_reference/environment_variables#hfhubcache) hoặc bằng cách cấu hình tham số `cache_dir` trong các phương thức như [from_pretrained()](/docs/diffusers/main/vi/api/pipelines/overview#diffusers.DiffusionPipeline.from_pretrained).

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

	```py
	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](https://huggingface.co/docs/huggingface_hub/package_reference/environment_variables#hfhuboffline) thành `1` để ngăn Diffusers kết nối với internet.

	```shell
	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](https://huggingface.co/docs/huggingface_hub/guides/manage-cache).

	### 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()](/docs/diffusers/main/vi/api/pipelines/overview#diffusers.DiffusionPipeline.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](https://huggingface.co/docs/hub/xet/index) 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.

	> [!NOTE]
	> 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](./using-diffusers/loading#reusing-models-in-multiple-pipelines).

	Để 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.

	```shell
	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()](/docs/diffusers/main/vi/api/pipelines/overview#diffusers.DiffusionPipeline.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](https://huggingface.co/docs/huggingface_hub/package_reference/environment_variables#hfhubdisabletelemetry).

	```bash
	export HF_HUB_DISABLE_TELEMETRY=1
	```

	```bash
	set HF_HUB_DISABLE_TELEMETRY=1
	```