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