# Định dạng mô hình

Mô hình khuếch tán thường được lưu trữ ở định dạng Diffusers hoặc định dạng tệp đơn. Các tệp mô hình có thể được lưu trữ ở nhiều loại tệp khác nhau như safetensors hoặc ckpt.

> [!TIP]
> Format đề cập đến việc các trọng số có được lưu trữ trong một cấu trúc thư mục hay không. File type đề cập đến cách các trọng số đó được serialize, chẳng hạn như safetensors hoặc ckpt.

```text
Diffusers format                    Single-file format
model/                              model.safetensors   (or .ckpt)
├─ model_index.json                 └─ all components in one file
├─ unet/  (or transformer/)
├─ text_encoder/
├─ vae/
└─ scheduler/
```

Hướng dẫn này sẽ cho bạn thấy cách nạp các pipeline và mô hình từ các định dạng và tệp này.

## Định dạng Diffusers

Định dạng Diffusers lưu trữ mỗi mô hình (UNet, transformer, text encoder) trong một thư mục con riêng biệt. Việc lưu trữ các mô hình riêng lẻ mang lại một số lợi ích.

- Khởi tạo pipeline tổng thể nhanh hơn vì bạn có thể tải riêng mô hình cần thiết hoặc tải tất cả chúng song song.
- Giảm lượng bộ nhớ sử dụng vì bạn không cần tải tất cả các thành phần của pipeline nếu chỉ cần một model. [Tái sử dụng](./loading#reusing-models-in-multiple-pipelines) một model được chia sẻ giữa nhiều pipeline.
- Yêu cầu lưu trữ thấp hơn vì các mô hình chung được chia sẻ giữa nhiều pipeline chỉ được tải xuống một lần.
- Tính linh hoạt trong việc sử dụng các mô hình mới hoặc được cải tiến trong một pipeline.

## Định dạng tệp đơn

Định dạng tệp đơn lưu trữ *toàn bộ* trọng số mô hình (UNet, transformer, text encoder) trong một tệp duy nhất. Lợi ích của các định dạng tệp đơn bao gồm:

- Tương thích tốt hơn với [ComfyUI](https://github.com/comfyanonymous/ComfyUI) hoặc [Automatic1111](https://github.com/AUTOMATIC1111/stable-diffusion-webui).
- Dễ dàng tải xuống và chia sẻ một tệp duy nhất hơn.

Sử dụng [from_single_file()](/docs/diffusers/main/vi/api/loaders/single_file#diffusers.loaders.FromSingleFileMixin.from_single_file) để tải một tệp duy nhất.

```py
import torch
from diffusers import StableDiffusionXLPipeline

pipeline = StableDiffusionXLPipeline.from_single_file(
    "https://huggingface.co/stabilityai/stable-diffusion-xl-base-1.0/blob/main/sd_xl_base_1.0.safetensors",
    dtype=torch.float16,
    device_map="cuda"  # or "mps", "xpu", "cpu"
)
```

Phương thức [from_single_file()](/docs/diffusers/main/vi/api/loaders/single_file#diffusers.loaders.FromSingleFileMixin.from_single_file) cũng hỗ trợ việc truyền các mô hình hoặc trình lập lịch mới.

```py
import torch
from diffusers import FluxPipeline, FluxTransformer2DModel

transformer = FluxTransformer2DModel.from_single_file(
    "https://huggingface.co/Kijai/flux-fp8/blob/main/flux1-dev-fp8.safetensors", dtype=torch.bfloat16
)
pipeline = FluxPipeline.from_pretrained(
    "black-forest-labs/FLUX.1-dev",
    transformer=transformer,
    dtype=torch.bfloat16,
    device_map="cuda"  # or "mps", "xpu", "cpu"
)
```

### Các tùy chọn cấu hình

Các mô hình ở định dạng Diffusers có tệp `config.json` trong kho chứa của chúng với các thuộc tính quan trọng như số lượng lớp và đầu chú ý. Phương thức [from_single_file()](/docs/diffusers/main/vi/api/loaders/single_file#diffusers.loaders.FromSingleFileMixin.from_single_file) tự động xác định cấu hình phù hợp để sử dụng từ `config.json`. Tuy nhiên, điều này có thể thất bại trong một vài trường hợp hiếm gặp, khi đó bạn nên sử dụng đối số `config`.

Bạn cũng nên sử dụng đối số `config` nếu các model trong pipeline khác với bản triển khai gốc hoặc nếu model không có metadata cần thiết để xác định config chính xác.

```py
from diffusers import StableDiffusionXLPipeline

ckpt_path = "https://huggingface.co/segmind/SSD-1B/blob/main/SSD-1B.safetensors"

pipeline = StableDiffusionXLPipeline.from_single_file(ckpt_path, config="segmind/SSD-1B")
```

Khi bạn truyền `original_config` cùng với `local_files_only=True`, Diffusers suy luận các thành phần pipeline từ chữ ký của lớp pipeline. Nó không tải các tệp cấu hình từ Hub, giúp tránh các thay đổi gây lỗi khi bạn đang ở chế độ ngoại tuyến. Con đường này kém đáng tin cậy hơn so với việc chỉ định cho `config` một đường dẫn mô hình cục bộ, và có thể gây ra lỗi. Hãy chạy một lần với `local_files_only=False` để các tệp cấu hình được lưu vào bộ nhớ đệm cục bộ, phòng khi bạn cần chúng ở chế độ ngoại tuyến sau này.

Ghi đè các cấu hình mặc định bằng cách truyền các đối số trực tiếp vào [from_single_file()](/docs/diffusers/main/vi/api/loaders/single_file#diffusers.loaders.FromSingleFileMixin.from_single_file). Các ví dụ dưới đây minh họa cách ghi đè các cấu hình trong một pipeline hoặc model.

```py
from diffusers import StableDiffusionXLInstructPix2PixPipeline

ckpt_path = "https://huggingface.co/stabilityai/cosxl/blob/main/cosxl_edit.safetensors"
pipeline = StableDiffusionXLInstructPix2PixPipeline.from_single_file(
    ckpt_path, config="diffusers/sdxl-instructpix2pix-768", is_cosxl_edit=True
)
```

```py
from diffusers import UNet2DConditionModel

ckpt_path = "https://huggingface.co/stabilityai/stable-diffusion-xl-base-1.0/blob/main/sd_xl_base_1.0_0.9vae.safetensors"
model = UNet2DConditionModel.from_single_file(ckpt_path, upcast_attention=True)
```

### Tệp cục bộ

Phương thức [from_single_file()](/docs/diffusers/main/vi/api/loaders/single_file#diffusers.loaders.FromSingleFileMixin.from_single_file) cố gắng cấu hình một pipeline hoặc model bằng cách suy luận loại model từ các khóa trong tệp checkpoint. Ví dụ, bất kỳ tệp checkpoint đơn nào dựa trên model cơ sở Stable Diffusion XL đều được cấu hình từ [stabilityai/stable-diffusion-xl-base-1.0](https://huggingface.co/stabilityai/stable-diffusion-xl-base-1.0).

Nếu bạn đang làm việc với các tệp cục bộ, hãy tải xuống các tệp cấu hình bằng phương thức [snapshot_download](https://huggingface.co/docs/huggingface_hub/main/en/package_reference/file_download#huggingface_hub.snapshot_download) và điểm kiểm tra mô hình bằng [hf_hub_download](https://huggingface.co/docs/huggingface_hub/main/en/package_reference/file_download#huggingface_hub.hf_hub_download). Các tệp này được tải xuống [thư mục cache](https://huggingface.co/docs/huggingface_hub/en/guides/manage-cache) của bạn, nhưng bạn có thể tải chúng xuống một thư mục cụ thể bằng đối số `local_dir`.

```py
from huggingface_hub import hf_hub_download, snapshot_download
from diffusers import StableDiffusionXLPipeline

my_local_checkpoint_path = hf_hub_download(
    repo_id="segmind/SSD-1B",
    filename="SSD-1B.safetensors"
)

my_local_config_path = snapshot_download(
    repo_id="segmind/SSD-1B",
    allow_patterns=["*.json", "**/*.json", "*.txt", "**/*.txt"]
)

pipeline = StableDiffusionXLPipeline.from_single_file(
    my_local_checkpoint_path, config=my_local_config_path, local_files_only=True
)
```

### Symlink

Nếu bạn đang làm việc với hệ thống tệp không hỗ trợ liên kết mềm, hãy tải tệp checkpoint xuống thư mục cục bộ trước bằng tham số `local_dir`. Việc sử dụng tham số `local_dir` sẽ tự động tắt liên kết mềm.

```py
from huggingface_hub import hf_hub_download, snapshot_download
from diffusers import StableDiffusionXLPipeline

my_local_checkpoint_path = hf_hub_download(
    repo_id="segmind/SSD-1B",
    filename="SSD-1B.safetensors",
    local_dir="my_local_checkpoints",
)
print("My local checkpoint: ", my_local_checkpoint_path)

my_local_config_path = snapshot_download(
    repo_id="segmind/SSD-1B",
    allow_patterns=["*.json", "**/*.json", "*.txt", "**/*.txt"]
)
print("My local config: ", my_local_config_path)
```

Truyền các đường dẫn này vào [from_single_file()](/docs/diffusers/main/vi/api/loaders/single_file#diffusers.loaders.FromSingleFileMixin.from_single_file).

```py
pipeline = StableDiffusionXLPipeline.from_single_file(
    my_local_checkpoint_path, config=my_local_config_path, local_files_only=True
)
```

## Các loại tệp

Mô hình có thể được lưu trữ dưới nhiều định dạng tệp khác nhau. Safetensors là định dạng tệp phổ biến nhất, nhưng bạn có thể gặp các định dạng tệp khác trên Hub hoặc trong cộng đồng diffusion.

### safetensors

[Safetensors](https://hf.co/docs/safetensors) là định dạng tệp an toàn và nhanh để lưu trữ và nạp tensor một cách bảo mật. Nó giới hạn kích thước header để hạn chế một số loại tấn công, hỗ trợ nạp chậm (hữu ích cho các cấu hình phân tán) và nhìn chung nạp nhanh hơn.

Diffusers sẽ tải tệp safetensors theo mặc định (một phụ thuộc bắt buộc) nếu chúng có sẵn và thư viện Safetensors đã được cài đặt.

Sử dụng [from_pretrained()](/docs/diffusers/main/vi/api/pipelines/overview#diffusers.DiffusionPipeline.from_pretrained) hoặc [from_single_file()](/docs/diffusers/main/vi/api/loaders/single_file#diffusers.loaders.FromSingleFileMixin.from_single_file) để tải các tệp safetensor.

```py
import torch
from diffusers import DiffusionPipeline, StableDiffusionXLPipeline

pipeline = DiffusionPipeline.from_pretrained(
    "stabilityai/stable-diffusion-xl-base-1.0",
    dtype=torch.float16,
    device_map="cuda",  # or "mps", "xpu", "cpu"
)

pipeline = StableDiffusionXLPipeline.from_single_file(
    "https://huggingface.co/stabilityai/stable-diffusion-xl-base-1.0/blob/main/sd_xl_base_1.0.safetensors",
    dtype=torch.float16,
)
```

Nếu bạn đang sử dụng checkpoint được huấn luyện bằng một script huấn luyện của Diffusers, các metadata như cấu hình LoRA sẽ được lưu tự động. Khi tệp được nạp, metadata đó sẽ được phân tích để cấu hình LoRA chính xác. Kiểm tra metadata của một tệp safetensors bằng cách nhấp vào biểu tượng  bên cạnh tệp trên Hub.

Lưu metadata của adapter LoRA cho các checkpoint không được huấn luyện bằng Diffusers bằng cách truyền nó vào [save_lora_weights()](/docs/diffusers/main/vi/api/loaders/lora#diffusers.loaders.FluxLoraLoaderMixin.save_lora_weights). Sử dụng `transformer_lora_adapter_metadata` cho transformer và `text_encoder_lora_adapter_metadata` cho text encoder. Bạn cũng phải truyền `save_directory` và ít nhất một trong số `transformer_lora_layers` hoặc `text_encoder_lora_layers`. Đường dẫn này chỉ được hỗ trợ cho các tệp safetensors.

```py
import torch
from peft.utils import get_peft_model_state_dict
from diffusers import FluxPipeline

pipeline = FluxPipeline.from_pretrained(
    "black-forest-labs/FLUX.1-dev", dtype=torch.bfloat16, device_map="cuda"  # or "mps", "xpu", "cpu"
)
pipeline.load_lora_weights("linoyts/yarn_art_Flux_LoRA")

transformer_lora_layers = get_peft_model_state_dict(pipeline.transformer)
pipeline.save_lora_weights(
    save_directory="path/to/lora",
    transformer_lora_layers=transformer_lora_layers,
    transformer_lora_adapter_metadata={"r": 8, "lora_alpha": 8},
)
```

### ckpt

Trọng số của các mô hình cũ thường được lưu bằng tiện ích [pickle](https://docs.python.org/3/library/pickle.html) của Python trong một tệp ckpt.

Các tệp pickle có thể không an toàn vì chúng có thể bị khai thác để thực thi mã độc. Khuyến nghị sử dụng tệp safetensors hoặc chuyển đổi trọng số sang tệp safetensors.

Sử dụng [from_single_file()](/docs/diffusers/main/vi/api/loaders/single_file#diffusers.loaders.FromSingleFileMixin.from_single_file) để tải tệp ckpt.

```py
from diffusers import StableDiffusionPipeline

pipeline = StableDiffusionPipeline.from_single_file(
    "https://huggingface.co/stable-diffusion-v1-5/stable-diffusion-v1-5/blob/main/v1-5-pruned.ckpt"
)
```

### GGUF

GGUF lưu trữ các trọng số đã lượng tử hóa trước trong một tệp duy nhất. Diffusers nạp GGUF thông qua mô hình [from_single_file()](/docs/diffusers/main/vi/api/loaders/single_file#diffusers.loaders.FromSingleFileMixin.from_single_file) với [GGUFQuantizationConfig](/docs/diffusers/main/vi/api/quantization#diffusers.GGUFQuantizationConfig). Việc nạp GGUF ở cấp pipeline không được hỗ trợ.

Xem [GGUF](../quantization/gguf) để biết các bước cài đặt và các ví dụ đầy đủ.

```py
import torch
from diffusers import FluxTransformer2DModel, GGUFQuantizationConfig

transformer = FluxTransformer2DModel.from_single_file(
    "https://huggingface.co/city96/FLUX.1-dev-gguf/blob/main/flux1-dev-Q2_K.gguf",
    quantization_config=GGUFQuantizationConfig(compute_dtype=torch.bfloat16),
)
```

## Chuyển đổi định dạng và tệp

Diffusers cung cấp các script và phương pháp để chuyển đổi định dạng và tệp, giúp nhiều công cụ hơn trong hệ sinh thái diffusion có thể sử dụng chúng.

Hãy xem thư mục [diffusers/scripts](https://github.com/huggingface/diffusers/tree/main/scripts) để tìm một script chuyển đổi. Các script có `"to_diffusers"` được thêm vào cuối tên sẽ chuyển đổi một model sang định dạng Diffusers. Mỗi script có một bộ tham số riêng để cấu hình quá trình chuyển đổi. Hãy đảm bảo bạn kiểm tra các tham số khả dụng.

Ví dụ dưới đây chuyển đổi một mô hình được lưu ở định dạng Diffusers sang định dạng tệp đơn. Hãy cung cấp đường dẫn đến mô hình cần chuyển đổi và vị trí để lưu mô hình đã chuyển đổi. Bạn có thể tùy chọn chỉ định loại tệp và kiểu dữ liệu để lưu mô hình.

```bash
python convert_diffusers_to_original_sdxl.py --model_path path/to/model/to/convert --checkpoint_path path/to/save/model/to --use_safetensors
```

Phương thức [save_pretrained()](/docs/diffusers/main/vi/api/pipelines/overview#diffusers.DiffusionPipeline.save_pretrained) cũng lưu mô hình ở định dạng Diffusers và tự động tạo các thư mục con cho từng mô hình. Mặc định, nó lưu các tệp dưới dạng tệp safetensor.

```py
from diffusers import StableDiffusionXLPipeline

pipeline = StableDiffusionXLPipeline.from_single_file(
    "https://huggingface.co/stabilityai/stable-diffusion-xl-base-1.0/blob/main/sd_xl_base_1.0.safetensors",
)
pipeline.save_pretrained("path/to/save/model")
```

## Các bước tiếp theo

- Tìm hiểu thêm về các quyết định thiết kế và lý do tại sao các tệp safetensor được ưu tiên để lưu trữ và tải trọng số mô hình trong bài đăng trên blog [Safetensors audited as really safe and becoming the default](https://blog.eleuther.ai/safetensors-security-audit/).