模型文件和布局

扩散模型以各种文件类型保存，并以不同的布局组织。Diffusers 将模型权重存储为 Diffusers-multifolder 布局中的 safetensors 文件，并且它还支持从 single-file 布局（在扩散生态系统中常用）加载文件（如 safetensors 和 ckpt 文件）。

每种布局都有其自身的优点和用例，本指南将向您展示如何加载不同的文件和布局，以及如何转换它们。

文件

PyTorch 模型权重通常使用 Python 的 pickle 实用程序保存为 ckpt 或 bin 文件。但是，pickle 不安全，并且 pickled 文件可能包含可以执行的恶意代码。鉴于模型共享的普及，这种漏洞是一个严重的问题。为了解决这个安全问题，开发了 Safetensors 库作为 pickle 的安全替代品，它将模型保存为 safetensors 文件。

safetensors

Safetensors 是一种安全快速的文件格式，用于安全地存储和加载 tensors。Safetensors 限制了 header 大小以限制某些类型的攻击，支持延迟加载（对于分布式设置很有用），并且通常具有更快的加载速度。

确保您已安装 Safetensors 库。

!pip install safetensors

Safetensors 将权重存储在 safetensors 文件中。如果 safetensors 文件可用且已安装 Safetensors 库，Diffusers 默认加载 safetensors 文件。safetensors 文件的组织方式有两种：

1. Diffusers-multifolder 布局：可能有几个单独的 safetensors 文件，每个 pipeline 组件（文本编码器、UNet、VAE）一个，组织在子文件夹中（查看 stable-diffusion-v1-5/stable-diffusion-v1-5 仓库作为示例）
2. single-file 布局：所有模型权重可能保存在单个文件中（查看 WarriorMama777/OrangeMixs 仓库作为示例）

from diffusers import DiffusionPipeline

pipeline = DiffusionPipeline.from_pretrained(
    "stable-diffusion-v1-5/stable-diffusion-v1-5",
    use_safetensors=True
)

LoRA 文件

LoRA 是一种轻量级 adapter，训练快速且容易，使其在以某种方式或风格生成图像时尤其受欢迎。这些 adapters 通常存储在 safetensors 文件中，并在 civitai 等模型共享平台上广受欢迎。

LoRA 使用 load_lora_weights() 方法加载到基础模型中。

from diffusers import StableDiffusionXLPipeline
import torch

# base model
pipeline = StableDiffusionXLPipeline.from_pretrained(
    "Lykon/dreamshaper-xl-1-0", torch_dtype=torch.float16, variant="fp16"
).to("cuda")

# download LoRA weights
!wget https://civitai.com/api/download/models/168776 -O blueprintify.safetensors

# load LoRA weights
pipeline.load_lora_weights(".", weight_name="blueprintify.safetensors")
prompt = "bl3uprint, a highly detailed blueprint of the empire state building, explaining how to build all parts, many txt, blueprint grid backdrop"
negative_prompt = "lowres, cropped, worst quality, low quality, normal quality, artifacts, signature, watermark, username, blurry, more than one bridge, bad architecture"

image = pipeline(
    prompt=prompt,
    negative_prompt=negative_prompt,
    generator=torch.manual_seed(0),
).images[0]
image

ckpt

PyTorch 的 torch.save 函数使用 Python 的 pickle 实用程序来序列化和保存模型。这些文件保存为 ckpt 文件，它们包含整个模型的权重。

使用 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"
)

存储布局

模型文件的组织方式有两种：Diffusers-multifolder 布局或 single-file 布局。Diffusers-multifolder 布局是默认布局，每个组件文件（文本编码器、UNet、VAE）都存储在单独的子文件夹中。Diffusers 也支持从 single-file 布局加载模型，其中所有组件捆绑在一起。

Diffusers-multifolder

Diffusers-multifolder 布局是 Diffusers 的默认存储布局。每个组件（文本编码器、UNet、VAE）的权重都存储在单独的子文件夹中。权重可以存储为 safetensors 或 ckpt 文件。

要从 Diffusers-multifolder 布局加载，请使用 from_pretrained() 方法。

from diffusers import DiffusionPipeline

pipeline = DiffusionPipeline.from_pretrained(
    "stabilityai/stable-diffusion-xl-base-1.0",
    torch_dtype=torch.float16,
    variant="fp16",
    use_safetensors=True,
).to("cuda")

使用 Diffusers-multifolder 布局的好处包括：

1. 可以更快地单独或并行加载每个组件文件。

2. 减少内存使用，因为您只需加载所需的组件。例如，SDXL Turbo、SDXL Lightning 和 Hyper-SD 等模型除了 UNet 之外，其他组件都相同。您可以使用 from_pipe() 方法重用它们的共享组件，而不会消耗额外的内存（查看 重用 pipeline 指南），并且仅加载 UNet。这样，您无需下载冗余组件并无谓地使用更多内存。

   已复制

   import torch
   from diffusers import StableDiffusionXLPipeline, UNet2DConditionModel, EulerDiscreteScheduler
   
   # download one model
   sdxl_pipeline = StableDiffusionXLPipeline.from_pretrained(
       "stabilityai/stable-diffusion-xl-base-1.0",
       torch_dtype=torch.float16,
       variant="fp16",
       use_safetensors=True,
   ).to("cuda")
   
   # switch UNet for another model
   unet = UNet2DConditionModel.from_pretrained(
       "stabilityai/sdxl-turbo",
       subfolder="unet",
       torch_dtype=torch.float16,
       variant="fp16",
       use_safetensors=True
   )
   # reuse all the same components in new model except for the UNet
   turbo_pipeline = StableDiffusionXLPipeline.from_pipe(
       sdxl_pipeline, unet=unet,
   ).to("cuda")
   turbo_pipeline.scheduler = EulerDiscreteScheduler.from_config(
       turbo_pipeline.scheduler.config,
       timestep+spacing="trailing"
   )
   image = turbo_pipeline(
       "an astronaut riding a unicorn on mars",
       num_inference_steps=1,
       guidance_scale=0.0,
   ).images[0]
   image

3. 减少存储需求，因为如果一个组件（例如 SDXL VAE）在多个模型之间共享，您只需下载并存储一份副本，而不是多次下载和存储。对于 10 个 SDXL 模型，这可以节省约 3.5GB 的存储空间。对于像 PixArt Sigma 这样的较新模型，存储节省甚至更大，其中仅 文本编码器 就约 19GB！

4. 更灵活地用更新或更好的版本替换模型中的组件。

   已复制

   from diffusers import DiffusionPipeline, AutoencoderKL
   
   vae = AutoencoderKL.from_pretrained("madebyollin/sdxl-vae-fp16-fix", torch_dtype=torch.float16, use_safetensors=True)
   pipeline = DiffusionPipeline.from_pretrained(
       "stabilityai/stable-diffusion-xl-base-1.0",
       vae=vae,
       torch_dtype=torch.float16,
       variant="fp16",
       use_safetensors=True,
   ).to("cuda")

5. 更多关于模型组件的可见性和信息，这些信息存储在每个组件子文件夹的 config.json 文件中。

单文件

单文件布局将所有模型权重存储在一个文件中。所有模型组件（文本编码器、UNet、VAE）的权重都保存在一起，而不是分别放在子文件夹中。这可以是 safetensors 或 ckpt 文件。

要从单文件布局加载模型，请使用 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",
    torch_dtype=torch.float16,
    variant="fp16",
    use_safetensors=True,
).to("cuda")

使用单文件布局的好处包括

1. 易于兼容扩散界面，例如 ComfyUI 或 Automatic1111，它们通常使用单文件布局。
2. 更易于管理（下载和共享）单个文件。

转换布局和文件

Diffusers 提供了许多脚本和方法来转换存储布局和文件格式，以便在扩散生态系统中实现更广泛的支持。

查看 diffusers/scripts 集合，找到适合您转换需求的脚本。

例如，要将以 Diffusers 多文件夹布局存储的 Stable Diffusion XL 模型转换为单文件布局，请运行 convert_diffusers_to_original_sdxl.py 脚本。提供要转换的模型路径和保存转换后模型的路径。您可以选择指定是否要将模型保存为 safetensors 文件以及是否以半精度保存模型。

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 多文件夹布局。如果目录尚不存在，这将为您创建一个目录，并且默认情况下还会将文件保存为 safetensors 文件。

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()

最后，还有一些 Spaces，例如 SD To Diffusers 和 SD-XL To Diffusers，它们为将模型转换为 Diffusers 多文件夹布局提供了更友好的用户界面。这是转换布局最简单、最方便的选择，它会在您的模型仓库中打开一个包含转换后文件的 PR。但是，此选项不如运行脚本可靠，并且 Space 可能会因更复杂的模型而失败。

单文件布局的使用

既然您已经熟悉了 Diffusers 多文件夹布局和单文件布局之间的区别，那么本节将向您展示如何使用 from_single_file() 方法加载模型和 pipeline 组件、自定义加载配置选项以及加载本地文件。

加载 pipeline 或模型

将 pipeline 或模型的文件路径传递给 from_single_file() 方法即可加载它。

from diffusers import StableDiffusionXLPipeline

ckpt_path = "https://huggingface.co/stabilityai/stable-diffusion-xl-base-1.0/blob/main/sd_xl_base_1.0_0.9vae.safetensors"
pipeline = StableDiffusionXLPipeline.from_single_file(ckpt_path)

通过将组件直接传递给 from_single_file() 方法，自定义 pipeline 中的组件。例如，您可以在 pipeline 中使用不同的调度器。

from diffusers import StableDiffusionXLPipeline, DDIMScheduler

ckpt_path = "https://huggingface.co/stabilityai/stable-diffusion-xl-base-1.0/blob/main/sd_xl_base_1.0_0.9vae.safetensors"
scheduler = DDIMScheduler()
pipeline = StableDiffusionXLPipeline.from_single_file(ckpt_path, scheduler=scheduler)

或者您可以在 pipeline 中使用 ControlNet 模型。

from diffusers import StableDiffusionControlNetPipeline, ControlNetModel

ckpt_path = "https://huggingface.co/stable-diffusion-v1-5/stable-diffusion-v1-5/blob/main/v1-5-pruned-emaonly.safetensors"
controlnet = ControlNetModel.from_pretrained("lllyasviel/control_v11p_sd15_canny")
pipeline = StableDiffusionControlNetPipeline.from_single_file(ckpt_path, controlnet=controlnet)

自定义配置选项

模型有一个配置文件，用于定义其属性，例如 UNet 中的输入数量。Pipeline 的配置选项在 pipeline 的类中可用。例如，如果您查看 StableDiffusionXLInstructPix2PixPipeline 类，则有一个使用 is_cosxl_edit 参数缩放图像潜在空间的选项。

这些配置文件可以在模型的 Hub 仓库中找到，也可以在配置文件的其他来源位置找到（例如，GitHub 仓库或本地设备上）。

from diffusers import StableDiffusionXLPipeline

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

pipeline = StableDiffusionXLPipeline.from_single_file(ckpt_path, config=repo_id)

虽然配置文件指定了 pipeline 或模型的默认参数，但您可以通过直接向 from_single_file() 方法提供参数来覆盖它们。模型或 pipeline 类支持的任何参数都可以通过这种方式进行配置。

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)

本地文件

在 Diffusers>=v0.28.0 中，from_single_file() 方法尝试通过检查点文件中的键来推断模型类型，从而配置 pipeline 或模型。推断的模型类型用于确定 Hugging Face Hub 上的适当模型仓库，以配置模型或 pipeline。

例如，任何基于 Stable Diffusion XL 基础模型的单文件检查点都将使用 stabilityai/stable-diffusion-xl-base-1.0 模型仓库来配置 pipeline。

但是，如果您在互联网访问受限的环境中工作，则应使用 snapshot_download 函数下载配置文件，并使用 hf_hub_download 函数下载模型检查点。默认情况下，这些文件将下载到 Hugging Face Hub 缓存目录，但您可以使用 local_dir 参数指定首选的文件下载目录。

将配置和检查点路径传递给 from_single_file() 方法即可本地加载。

from huggingface_hub import hf_hub_download, snapshot_download

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)

不使用符号链接的本地文件

from_single_file() 方法依赖于 huggingface_hub 缓存机制来获取和存储模型和 pipeline 的检查点和配置文件。如果您使用的文件系统不支持符号链接，则应首先将检查点文件下载到本地目录，并使用 hf_hub_download 函数和 snapshot_download 函数中的 local_dir_use_symlink=False 参数禁用符号链接。

from huggingface_hub import hf_hub_download, snapshot_download

my_local_checkpoint_path = hf_hub_download(
    repo_id="segmind/SSD-1B",
    filename="SSD-1B.safetensors"
    local_dir="my_local_checkpoints",
    local_dir_use_symlinks=False
)
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"]
    local_dir_use_symlinks=False,
)
print("My local config: ", my_local_config_path)

然后，您可以将本地路径传递给 pretrained_model_link_or_path 和 config 参数。

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