Diffusers 模型格式与单文件加载完全指南从 Diffusers 目录格式到 safetensors/ckpt 的转换实战【免费下载链接】diffusers Diffusers: State-of-the-art diffusion models for image, video, and audio generation in PyTorch.项目地址: https://gitcode.com/GitHub_Trending/di/diffusers导读本文是围绕 Hugging Face Diffusers 官方文档《Model formats》整理的技术指南核心解决两类工程问题一是理解格式format与文件类型file的区别——前者指权重以目录结构存储还是单文件存储后者指 safetensors 或 ckpt 等文件封装二是掌握from_single_file加载单文件权重、config参数覆盖默认配置、LoRA 元数据保存以及借助 转换脚本 与save_pretrained在两种格式间互转的完整方案。读完本文你将能在不依赖 Diffusers 目录结构的情况下直接加载社区流传的 .safetensors / .ckpt 检查点并安全地在各生态格式间迁移模型。引言理解格式与文件类型在 Diffusion 模型生态中模型权重的存储方式常常让人混淆。Diffusers 官方文档用一个简明的 Tip 点破了本质Format 指的是权重以目录结构存储还是单文件存储File 指的是文件的具体封装类型safetensors 或 ckpt。格式Format分为 Diffusers 格式每个组件一个子目录与单文件格式所有组件权重塞进一个文件。文件类型Filesafetensors、ckpt基于 Python pickle、以及其他社区封装。这两条轴彼此正交一个单文件格式的模型既可以是.safetensors也可以是.ckpt一个 Diffusers 格式的模型仓库内部组件也各自以 safetensors 存储。本文后续所有章节都围绕这两条轴展开。Diffusers 格式目录化的组件存储Diffusers 格式将 UNet、Transformer、文本编码器等每个模型组件分别存放在独立的子文件夹中每个组件目录下都有对应的权重文件与config.json。官方文档总结了这种存储方式的四重收益更快的整体管线初始化可以只加载需要的单个模型也可以并行加载全部组件更低的内存占用当只需要某个模型时不必把整条管线的组件全部加载进内存更低的存储需求多个管线共享的公共模型只需下载一次更高的灵活性可以在管线中自由替换更新或更优的模型组件。这种格式与 [~DiffusionPipeline.from_pretrained] 天然配套。模型仓库根目录的config.json记录了各组件unet、vae、text_encoder、scheduler 等的类名与子目录位置from_pretrained据此逐组件实例化。你可以在 加载指南 中看到更完整的加载细节如多管线复用模型的用法。单文件格式一个文件装下整条管线单文件格式将所有模型权重UNet、Transformer、文本编码器等打包进单个文件。其优势同样明显与 ComfyUI、Automatic1111stable-diffusion-webui等生态工具兼容性更好社区模型常以此形态分发更易下载与分享一个文件即可分发完整模型。加载单文件格式的标准入口是 [~loaders.FromSingleFileMixin.from_single_file]其底层实现位于 src/diffusers/loaders/single_file.py。从源码 docstring 可知该方法支持两种输入Hub 上.ckpt/.safetensors文件的直链或本地包含全部管线权重的单文件路径加载完成后管线默认处于model.eval()评估模式。基础用法加载 SDXL 单文件检查点官方文档给出的最小示例直接把模型链接与设备/精度参数传给from_single_fileimport 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, dtypetorch.float16, device_mapcuda # or mps, xpu, cpu )这里dtypetorch.float16将管线权重以半精度加载以节省显存device_map指定设备分发策略。从源码看single_file.py该方法还接受force_download、cache_dir、proxies、token、local_files_only、revision、disable_mmap等 huggingface_hub 风格参数disable_mmapTrue在网络挂载盘或机械硬盘上加载 safetensors 时可能获得更好性能。单组件加载为管线替换新模型from_single_file同样支持只加载某个组件如新的 Transformer再组装进已有管线——这正是Diffusers 格式下灵活替换组件思想的延伸import torch from diffusers import FluxPipeline, FluxTransformer2DModel transformer FluxTransformer2DModel.from_single_file( https://huggingface.co/Kijai/flux-fp8/blob/main/flux1-dev-fp8.safetensors, dtypetorch.bfloat16 ) pipeline FluxPipeline.from_pretrained( black-forest-labs/FLUX.1-dev, transformertransformer, dtypetorch.bfloat16, device_mapcuda # or mps, xpu, cpu )此例先用FluxTransformer2DModel.from_single_file单独加载 FP8 量化的 Flux Transformer再通过FluxPipeline.from_pretrained将其注入完整管线。由于量化模型通常要求更低的数值精度这里使用torch.bfloat16。这种组件级单文件加载 管线级目录加载的组合是生产环境中处理量化/蒸馏/微调组件的常见姿势。配置选项config 参数的自动推断与手动覆盖Diffusers 格式的模型仓库中都有config.json记录层数、注意力头数等关键结构属性。from_single_file会自动从检查点推断合适的 config——源码中的fetch_diffusers_config(checkpoint)通过检查点内的 key 识别模型类型single_file.py例如任何基于 SDXL base 模型的单文件检查点都会被配置为stabilityai/stable-diffusion-xl-base-1.0。但在少数情况下自动推断会失败此时应显式传入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, configsegmind/SSD-1B)config参数既可以是 Hub 上的 repo id也可以是本地 Diffusers 格式目录路径。源码single_file.py展示了完整的解析逻辑若config不是本地目录则视为 repo id 并尝试下载其配置若本地无缓存且local_files_onlyTrue则会回退下载配置除非同时提供original_config走旧版推断路径。关于original_config有一个官方文档强调的坑当使用original_config且local_files_onlyTrue时Diffusers 会基于管线类的签名类型推断组件配置源码中的_infer_pipeline_config_dictsingle_file.py此时不会从 Hub 下载配置文件以避免断网时产生向后不兼容变更。但这种推断不如显式传入本地模型目录的config可靠可能报错——建议先以local_files_onlyFalse运行一次让配置文件下载到本地缓存之后再离线使用。覆盖默认配置管线级与模型级示例from_single_file还允许把额外的参数直接传给管线或模型的__init__从而覆盖默认配置。官方文档给出两个典型场景管线级覆盖——以 COSXL 编辑模型为例from diffusers import StableDiffusionXLInstructPix2PixPipeline ckpt_path https://huggingface.co/stabilityai/cosxl/blob/main/cosxl_edit.safetensors pipeline StableDiffusionXLInstructPix2PixPipeline.from_single_file( ckpt_path, configdiffusers/sdxl-instructpix2pix-768, is_cosxl_editTrue )这里同时做了两件事用config指定与 COSXL 结构匹配的 InstructPix2Pix 配置用is_cosxl_editTrue告诉管线这是一个 COSXL 编辑模型触发对应分支逻辑。模型级覆盖——以 0.9 VAE 的 UNet 为例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_attentionTrue)upcast_attentionTrue覆盖了 UNet 默认的注意力上转型配置对兼容旧版 VAE 训练权重很有用。从源码看多余的 kwargs 会通过passed_class_obj机制传递到组件构造器single_file.py。本地文件用 huggingface_hub 工具预先下载如果希望完全离线操作可以先用 [~huggingface_hub.snapshot_download] 下载配置文件、用 [~huggingface_hub.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_idsegmind/SSD-1B, filenameSSD-1B.safetensors ) my_local_config_path snapshot_download( repo_idsegmind/SSD-1B, allow_patterns[*.json, **/*.json, *.txt, **/*.txt] ) pipeline StableDiffusionXLPipeline.from_single_file( my_local_checkpoint_path, configmy_local_config_path, local_files_onlyTrue )注意snapshot_download的allow_patterns只拉取 json/txt 配置类文件而避开大权重文件——这正是配置文件来自 Diffusers 仓库、权重文件来自单文件检查点这一混合策略的精髓。local_files_onlyTrue保证加载阶段绝不联网。符号链接Symlink与不支持符号链接的文件系统HuggingFace Hub 的缓存机制默认使用符号链接。若你工作的文件系统如某些网络盘、Windows 老式文件系统、容器挂载卷不支持符号链接则应在下载时就通过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_idsegmind/SSD-1B, filenameSSD-1B.safetensors, local_dirmy_local_checkpoints, ) print(My local checkpoint: , my_local_checkpoint_path) my_local_config_path snapshot_download( repo_idsegmind/SSD-1B, allow_patterns[*.json, **/*.json, *.txt, **/*.txt] ) print(My local config: , my_local_config_path)随后照常传入from_single_filepipeline StableDiffusionXLPipeline.from_single_file( my_local_checkpoint_path, configmy_local_config_path, local_files_onlyTrue )文件类型safetensors 与 ckpt无论采用哪种格式模型权重最终都要落到某种文件封装中。Hub 与社区里最常见的是 safetensors但也会遇到 ckpt。safetensors默认且推荐的文件类型Safetensors 是一种安全、快速的张量存储格式安全严格限制文件头大小抵御特定类型的恶意攻击快速一般加载速度优于 pickle 系格式支持惰性加载lazy loading对分布式部署尤其有用。Diffusers 将 safetensors 作为默认加载格式也是必需的依赖只要 Safetensors 库已安装且文件可用就会优先加载 safetensors。无论目录格式还是单文件格式加载入口都是一致的import torch from diffusers import DiffusionPipeline pipeline DiffusionPipeline.from_pretrained( stabilityai/stable-diffusion-xl-base-1.0, torch.dtypetorch.float16, device_mapcuda # or mps, xpu, cpu ) pipeline DiffusionPipeline.from_single_file( https://huggingface.co/stabilityai/stable-diffusion-xl-base-1.0/blob/main/sd_xl_base_1.0.safetensors, dtypetorch.float16, )LoRA 元数据是 safetensors 的重要特性若检查点由 Diffusers 训练脚本产出LoRA 配置等元数据会自动写入文件加载时 Diffusers 解析这些元数据以正确配置 LoRA避免配置缺失或错误。可在 Hub 上点击文件旁的 safetensors logo 查看元数据。对非 Diffusers 训练产出的 LoRA需要手动保存元数据Transformer/UNet 分别用transformer_lora_adapter_metadata或unet_lora_adapter_metadata文本编码器则用text_encoder_lora_adapter_metadata与text_encoder_2_lora_adapter_metadata传给 [~loaders.FluxLoraLoaderMixin.save_lora_weights]。该功能仅支持 safetensors 文件。Flux 管线的完整示例import torch from diffusers import FluxPipeline pipeline FluxPipeline.from_pretrained( black-forest-labs/FLUX.1-dev, dtypetorch.bfloat16 ).to(cuda) # or mps, xpu, cpu pipeline.load_lora_weights(linoyts/yarn_art_Flux_LoRA) pipeline.save_lora_weights( text_encoder_lora_adapter_metadata{r: 8, lora_alpha: 8}, text_encoder_2_lora_adapter_metadata{r: 8, lora_alpha: 8} )源码层面src/diffusers/loaders/lora_base.py 定义了LORA_ADAPTER_METADATA_KEY lora_adapter_metadata并强制约束指定了lora_adapter_metadata时safe_serialization必须为 True即只能存为 safetensors且该参数必须是 dict最终会以组件名前缀 元数据的形式打包进文件的 header。各管线类如 SDXL、Flux、SD3 等的save_lora_weights实现分布在 src/diffusers/loaders/lora_pipeline.py 中分别接受unet_lora_adapter_metadata、text_encoder_lora_adapter_metadata、text_encoder_2_lora_adapter_metadata、transformer_lora_adapter_metadata等参数见该文件 L471-L509、L896-L916、L1182 附近加载时据此还原 LoRA 的 rank、alpha 等关键配置。ckpt历史遗留但需警惕较老的权重常用 Python 的 pickle 序列化进.ckpt文件。pickle 存在安全隐患——恶意文件可借此执行任意代码官方文档明确建议优先使用 safetensors或将 ckpt 权重转换为 safetensors。若确需加载 ckpt同样走from_single_filefrom diffusers import DiffusionPipeline pipeline DiffusionPipeline.from_single_file( https://huggingface.co/stable-diffusion-v1-5/stable-diffusion-v1-5/blob/main/v1-5-pruned.ckpt )务必只从可信来源获取 ckpt 文件并在隔离环境中先验证其安全性。格式与文件类型互转脚本、API 与 SpaceDiffusers 提供了多层次的转换能力以覆盖整个扩散生态。转换脚本scripts 目录仓库的 scripts 目录汇集了大量转换脚本。命名规律是以to_diffusers结尾的脚本将模型转换为 Diffusers 格式例如convert_original_stable_diffusion_to_diffusers.py、convert_sd3_to_diffusers.py、convert_flux_to_diffusers.py等。每个脚本都有一套专属参数使用前务必查看其具体参数说明。反向转换Diffusers 格式 → 单文件格式的官方示例使用convert_diffusers_to_original_sdxl.pypython convert_diffusers_to_original_sdxl.py --model_path path/to/model/to/convert --checkpoint_path path/to/save/model/to --use_safetensors其中--model_path指向待转换的 Diffusers 格式模型--checkpoint_path是转换产物的保存路径--use_safetensors可选地指定输出为 safetensors不指定则输出 ckpt。类似地仓库还提供了convert_diffusers_to_original_stable_diffusion.py等脚本覆盖其他架构你可以按需选择。save_pretrained代码内一键转 Diffusers 格式[~DiffusionPipeline.save_pretrained] 负责将模型保存为 Diffusers 格式自动为每个组件创建子目录默认以 safetensors 落盘。结合from_single_file即可完成单文件 → Diffusers 目录的纯代码转换from diffusers import DiffusionPipeline pipeline DiffusionPipeline.from_single_file( https://huggingface.co/stabilityai/stable-diffusion-xl-base-1.0/blob/main/sd_xl_base_1.0.safetensors, ) pipeline.save_pretrained()零代码方案SD To Diffusers 等 Space若不想写代码还可以使用社区提供的转换 Space如 SD To Diffusers、SD-XL To Diffusers上传模型后Space 会在你的模型仓库上自动打开一个包含转换产物的 PR。这是最省事的方案但对结构较复杂的模型可能失败——此时使用转换脚本更可靠。小结与选型建议维度Diffusers 格式单文件格式存储形态每组件独立子目录 config.json全部权重打包进一个文件加载入口from_pretrainedfrom_single_file初始化速度可按需/并行加载更快一次载入全部内存占用按需加载更低需整载生态兼容Diffusers 原生ComfyUI / A1111 友好典型文件类型safetensorssafetensors / ckpt实际工程中的推荐路径新训练/新发布模型优先采用 Diffusers 格式 safetensors享受按需加载与安全默认消费社区单文件检查点使用from_single_file必要时用config显式指定结构配置需要与 WebUI 生态互换用 scripts 下的转换脚本如convert_diffusers_to_original_sdxl.py导出单文件离线/特殊文件系统环境先通过hf_hub_download/snapshot_download配合local_dir落地文件再以local_files_onlyTrue加载安全底线对 ckpt 文件保持警惕优先转换或使用 safetensors。如需进一步了解模型加载的完整话题包括多管线复用、组件卸载等可继续阅读 加载指南。【免费下载链接】diffusers Diffusers: State-of-the-art diffusion models for image, video, and audio generation in PyTorch.项目地址: https://gitcode.com/GitHub_Trending/di/diffusers创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考