Diffusers documentation
模型格式
模型格式
扩散模型通常以 Diffusers 格式或单文件格式存储。模型文件可以保存为多种文件类型，例如 safetensors 或 ckpt。
Format 指的是权重是否以目录结构存储。File type 指的是这些权重的序列化方式，例如 safetensors 或 ckpt。
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/
本指南将向您展示如何从这些格式和文件中加载管道和模型。
Diffusers 格式
Diffusers 格式将每个模型（UNet、transformer、text encoder）分别存储在独立的子文件夹中。这种分离存储方式具有多项优势。
- 整体流水线初始化速度更快，因为您可以加载所需的单个模型，或者并行加载所有模型。
- 由于您只需加载一个模型，因此无需加载所有流水线组件，从而降低了内存占用。复用在多个流水线之间共享的模型。
- 由于多个流水线共享的通用模型只需下载一次，因此存储需求更低。
- 在流水线中使用新模型或改进模型的灵活性。
单文件格式
单文件格式将所有模型权重（UNet、transformer、text encoder）存储在单个文件中。单文件格式的优点包括：
- 与 ComfyUI 或 Automatic1111 具有更高的兼容性。
- 下载和共享单个文件更加便捷。
使用 from_single_file() 加载单个文件。
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"
)from_single_file() 方法还支持传入新的模型或调度器。
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"
)配置选项
Diffusers 格式的模型在其仓库中包含一个 config.json 文件，其中包含层数和注意力头数量等重要属性。from_single_file() 方法会自动从 config.json 中确定要使用的合适配置。不过，在少数罕见情况下这可能会失败，此时应使用 config 参数。
如果流水线中的模型与原始实现不同，或者缺少确定正确配置所需的元数据，您也应该使用 config 参数。
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")当传入 original_config 并设置 local_files_only=True 时，Diffusers 会根据 pipeline 类的签名推断 pipeline 组件。它不会从 Hub 下载配置文件，从而避免在离线时出现破坏性变更。与为 config 提供本地模型路径相比，这种方式可靠性较低，且可能会报错。如果之后需要离线使用，请运行一次 local_files_only=False，以便将配置文件保存到本地缓存中。
通过直接将参数传递给 from_single_file() 来覆盖默认配置。以下示例展示了如何在流水线或模型中覆盖配置。
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
)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)本地文件
from_single_file() 方法会尝试通过推断检查点文件中的键来配置流水线或模型。例如，任何基于 Stable Diffusion XL 基础模型的单文件检查点都会从 stabilityai/stable-diffusion-xl-base-1.0 进行配置。
如果你正在处理本地文件，请使用 snapshot_download 方法下载配置文件，并使用 hf_hub_download 下载模型检查点。这些文件会下载到你的 缓存目录 中，但你可以通过 local_dir 参数将它们下载到指定目录。
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
)符号链接
如果你使用的文件系统不支持符号链接，请先使用 local_dir 参数将检查点文件下载到本地目录。使用 local_dir 参数会自动禁用符号链接。
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)将这些路径传递给 from_single_file()。
pipeline = StableDiffusionXLPipeline.from_single_file(
my_local_checkpoint_path, config=my_local_config_path, local_files_only=True
)文件类型
模型可以存储为多种文件类型。Safetensors 是最常见的文件类型，但您可能会在 Hub 或扩散模型社区中遇到其他文件类型。
safetensors
Safetensors 是一种安全且快速的文件类型，用于安全地存储和加载张量。它通过限制头部大小来防范某些类型的攻击，支持延迟加载（在分布式环境中非常有用），并且通常加载速度更快。
如果存在 safetensors 文件且已安装 Safetensors 库，Diffusers 默认会加载 safetensors 文件（这是一个必需的依赖项）。
Use from_pretrained() or from_single_file() to load safetensor files.
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,
)如果您使用的是通过 Diffusers 训练脚本训练的 checkpoint，诸如 LoRA 配置之类的元数据会自动保存。加载该文件时，系统会解析这些元数据，从而正确配置 LoRA。您可以点击 Hub 上文件旁边的 
图标来查看 safetensors 文件的元数据。
对于未使用 Diffusers 训练的 checkpoint，可通过将其传递给 save_lora_weights() 来保存 LoRA 适配器元数据。transformer 使用 transformer_lora_adapter_metadata，文本编码器使用 text_encoder_lora_adapter_metadata。您还必须传递 save_directory 以及 transformer_lora_layers 或 text_encoder_lora_layers 中的至少一个。此路径仅支持 safetensors 文件。
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
旧版模型权重通常使用 Python 的 pickle 工具保存在 ckpt 文件中。
Pickled 文件可能不安全，因为它们可能被利用来执行恶意代码。建议使用 safetensors 文件，或将权重转换为 safetensors 文件。
使用 from_single_file() 加载 ckpt 文件。
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 将预量化权重存储在单个文件中。Diffusers 通过模型的 from_single_file() 方法并结合 GGUFQuantizationConfig 来加载 GGUF。不支持在 Pipeline 层面加载 GGUF。
有关安装步骤和完整示例，请参阅 GGUF。
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),
)转换格式和文件
Diffusers 提供了脚本和方法，用于转换格式和文件，以便扩散生态系统中的更多工具能够使用它们。
请查看 diffusers/scripts 文件夹以查找转换脚本。文件名末尾带有 "to_diffusers" 的脚本用于将模型转换为 Diffusers 格式。每个脚本都有一套特定的参数用于配置转换过程。请务必检查可用的参数。
下面的示例将存储在 Diffusers 格式中的模型转换为单文件格式。请提供要转换的模型的路径以及保存转换后模型的位置。您可以选择性地指定保存模型的文件类型和数据类型。
python convert_diffusers_to_original_sdxl.py --model_path path/to/model/to/convert --checkpoint_path path/to/save/model/to --use_safetensors
save_pretrained() 方法同样会以 Diffusers 格式保存模型，并负责为每个模型创建子文件夹。默认情况下，它会将文件保存为 safetensor 文件。
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")后续步骤
- 有关设计决策以及为何在保存和加载模型权重时优先使用 safetensor 文件的更多信息，请参阅博客文章 经过审计，Safetensors 确实安全，并成为默认选项。