Diffusers 多格式兼容实战加载与转换 .ckpt、KerasCV 与 A1111 LoRA 等 Stable Diffusion 模型格式【免费下载链接】diffusers Diffusers: State-of-the-art diffusion models for image, video, and audio generation in PyTorch.项目地址: https://gitcode.com/GitHub_Trending/di/diffusersStable Diffusion 模型因训练框架与分发渠道不同常以 PyTorch.ckpt、Keras.pb/.h5、A1111 LoRA 等多样格式存在。本文基于当前仓库的官方指南docs/source/ko/using-diffusers/other-formats.md及其对应实现系统讲解如何将这些格式转换为 Diffusers 兼容形式并直接加载使用。读完本文你将掌握三种主流格式的转换/加载方案、转换脚本的完整参数语义以及 LoRA 权重加载的底层原理从而在推理时自由使用 Diffusers 提供的全部能力——如切换多种噪声调度器、构建自定义 pipeline、以及 flash attention、fp16 等推理加速手段。为什么要做格式转换Stable Diffusion 生态中模型因训练/保存框架和下载来源不同而呈现多种格式。将它们转换为 Diffusers 可用的形式后就能解锁库内所有高级特性使用各种调度器scheduler进行去噪过程定制步数、随机/确定性、具体算法自由搭建自定义 pipeline参考 write_own_pipeline应用 flash attention、xformers、fp16 等推理优化技术提升速度与显存效率。[!TIP] 官方明确推荐使用.safetensors格式传统的 pickle 序列化文件存在安全漏洞加载时可能在机器上执行任意恶意代码而 safetensors 更安全、加载更快。详细原理可阅读安全加载指南。下面按格式逐一讲解。加载 PyTorch .ckpt 格式.ckptcheckpoint是最常见的模型存储格式单个文件包含完整模型权重通常体积达数 GB。虽然可以通过StableDiffusionPipeline.from_ckpt之类的方法直接加载但官方更推荐先将其转换为 Diffusers 格式以获得上述全部能力。转换有两条路径使用 Space 在线转换与使用仓库内置脚本转换。方案一通过 Space 转换最简单的做法是使用官方 SD → Diffusers 转换 Space按照页面指引上传.ckpt文件即可完成转换。需要留意的是该方案对基础模型base model效果很好但对经过大量自定义微调的模型可能失败——表现为返回空 pull request 或直接报错。遇到这种情况应改用下面更可靠的脚本方案。方案二通过仓库脚本转换 Diffusers 在 scripts 目录中提供了专门的转换脚本 convert_original_stable_diffusion_to_diffusers.py比 Space 方案更稳定可控。准备条件本地克隆clone本仓库确保能运行scripts下的脚本登录 Hugging Face 账号以便后续打开 pull request 并把转换结果推送到 Hubhf auth login完整操作流程以 TemporalNet 这个 SD v1.5 ControlNet 模型为例克隆包含待转换.ckpt文件的仓库git lfs install git clone https://huggingface.co/CiaraRowles/TemporalNet在目标仓库中为转换结果打开一个 pull request 分支cd TemporalNet git fetch origin refs/pr/13:pr/13 git checkout pr/13确认三个关键脚本参数详见下文参数详解checkpoint_path待转换.ckpt文件的路径original_config_file描述原始架构的 YAML 配置文件。若找不到可去下载.ckpt的 GitHub 仓库中搜索同名 YAML。例如 TemporalNet 是 SD v1.5 ControlNet 模型可直接从 ControlNet 仓库取得cldm_v15.yamldump_path转换后模型的输出路径。执行转换命令python ../diffusers/scripts/convert_original_stable_diffusion_to_diffusers.py --checkpoint_path temporalnetv3.ckpt --original_config_file cldm_v15.yaml --dump_path ./ --controlnet转换完成后将结果上传到 PR 分支并测试git push origin pr/13:refs/pr/13转换脚本核心参数详解对照 convert_original_stable_diffusion_to_diffusers.py 的 argparse 定义可归纳出以下核心参数及其语义参数类型默认值作用说明--checkpoint_pathstr必填待转换的.ckpt文件路径--original_config_filestrNone对应原始架构的 YAML 配置文件缺省时通过内部启发式自动推断但对继续微调过的模型易失败尽量显式提供--config_filesstrNone架构对应的 YAML 配置更通用的替代项--dump_pathstr必填转换后模型的保存路径--scheduler_typestrpndm调度器类型可选pndm、lms、ddim、euler、euler-ancestral、dpm--pipeline_typestrNonepipeline 类型FrozenOpenCLIPEmbedder、FrozenCLIPEmbedder、PaintByExample缺省自动推断--image_sizeintNone训练时的图像尺寸SD v1.X 与 SD v2 Base 用 512SD v2 用 768--prediction_typestrNone训练时的预测类型SD v1.X 与 SD v2 Base 用epsilonSD v2 用v_prediction--extract_emaboolFalse对同时含 EMA 与非 EMA 权重的检查点是否提取 EMA 权重EMA 推理质量通常更高非 EMA 更适合继续微调--upcast_attentionboolFalse是否始终以更高精度计算 attention运行 SD 2.1 时必需--from_safetensorsboolFalse输入为 safetensors 格式时以 safetensors 加载--to_safetensorsboolFalse是否将输出 pipeline 存为 safetensors 格式--devicestrNone运行设备如cpu、cuda:0、cuda:1--controlnetboolFalse标记该检查点是 ControlNet 检查点如上例 TemporalNet--halfboolFalse以半精度fp16保存权重--stable_unclipstrNone若是 stable unCLIP 模型则指定txt2img或img2img--vae_pathstrNone指定已转换好的 VAE 路径/Hub id避免重复转换 VAE--pipeline_class_namestrNone显式指定 pipeline 类名从实现看该脚本本质上是 convert_from_ckpt.py 中download_from_original_stable_diffusion_ckpt函数的命令行封装。这个底层函数接收checkpoint_path_or_dict.ckpt路径或直接传入 state dict、original_config_file、extract_ema、scheduler_type、num_in_channels、upcast_attention、controlnet、vae_path等参数返回一个组装完成的DiffusionPipeline对象随后脚本调用pipe.save_pretrained(args.dump_path, safe_serializationargs.to_safetensors)写出 Diffusers 格式的模型目录若为 ControlNet 则只保存pipe.controlnet。值得强调的是download_from_original_stable_diffusion_ckpt的文档注释明确指出虽然很多参数可以自动推断但部分推断依赖对全局步数的脆弱检查对经过进一步微调的模型很可能会失败因此只要可能就应提供original_config_file覆盖默认值。加载 KerasCV 的 .pb / .h5 格式 该功能为实验性特性当前 KerasCV 转换 Space 仅支持 Stable Diffusion v1 检查点。KerasCV 支持训练 Stable Diffusion v1 与 v2但针对推理与部署场景的功能较为有限相比之下 Diffusers 提供了更完整的调度器、flash attention 与其他优化手段因此将 KerasCV 权重转换过来很有价值。转换方式使用官方 KerasCV → Diffusers 转换 Space它会将.pb或.h5权重先转换为 PyTorch再包装成StableDiffusionPipeline供推理使用转换结果保存在 Hugging Face Hub 上的新仓库中。以 textual-inversion 微调过的sayakpaul/textual-inversion-kerasio检查点为例它用特殊占位符 tokenmy-funny-cat把图像个性化成猫。在 KerasCV 转换 Space 中需要填写Hugging Face 令牌tokenUNet 与文本编码器权重的下载路径。根据训练方式两者不一定都提供——例如 textual-inversion 只需文本编码器中的嵌入而文本转图像模型转换只需 UNet 权重占位符 token仅 textual-inversion 模型需要output_repo_prefix转换结果仓库的名称前缀。点击Submit后Space 自动完成转换并返回新仓库链接仓库中的模型卡片带有一个可直接体验生成效果的推理 widget。要在代码中运行推理点击模型卡片右上角的Use in Diffusers按钮复制示例代码或直接from diffusers import DiffusionPipeline pipeline DiffusionPipeline.from_pretrained(sayakpaul/textual-inversion-cat-kerascv_sd_diffusers_pipeline) pipeline.to(cuda) placeholder_token my-funny-cat-token prompt ftwo {placeholder_token} getting married, photorealistic, high quality image pipeline(prompt, num_inference_steps50).images[0]加载 A1111Automatic1111LoRA 文件Automatic1111 是 Stable Diffusion 社区广泛使用的 Web UI并支撑着 Civitai 等模型分享平台。基于 LoRA 技术训练的模型因训练速度快、文件体积远小于全参数微调模型而广受欢迎因此能否在 Diffusers 中直接加载 A1111 格式的 LoRA 检查点至关重要。使用 load_lora_weights 加载Diffusers 通过StableDiffusionLoraLoaderMixin.load_lora_weights原生支持 A1111 LoRA 检查点。完整流程如下加载基础 pipeline这里选用andite/anything-v4.0并换成UniPCMultistepScheduler调度器from diffusers import DiffusionPipeline, UniPCMultistepScheduler import torch pipeline DiffusionPipeline.from_pretrained( andite/anything-v4.0, dtypetorch.float16, safety_checkerNone ).to(cuda) pipeline.scheduler UniPCMultistepScheduler.from_config(pipeline.scheduler.config)从 Civitai 下载 LoRA 检查点官方示例用的是 Howls Moving Castle 风格的 Interior/Scenery LoRA也可换成任意 LoRA!wget https://civitai.com/api/download/models/19998 -O howls_moving_castle.safetensors将 LoRA 权重加载进 pipelinepipeline.load_lora_weights(., weight_namehowls_moving_castle.safetensors)使用正负提示词与固定随机种子生成图像prompt masterpiece, illustration, ultra-detailed, cityscape, san francisco, golden gate bridge, california, bay area, in the snow, beautiful detailed starry sky negative_prompt lowres, cropped, worst quality, low quality, normal quality, artifacts, signature, watermark, username, blurry, more than one bridge, bad architecture images pipeline( promptprompt, negative_promptnegative_prompt, width512, height512, num_inference_steps25, num_images_per_prompt4, generatortorch.manual_seed(0), ).images用辅助函数把 4 张图拼成网格展示from PIL import Image def image_grid(imgs, rows2, cols2): w, h imgs[0].size grid Image.new(RGB, size(cols * w, rows * h)) for i, img in enumerate(imgs): grid.paste(img, box(i % cols * w, i // cols * h)) return grid image_grid(images)load_lora_weights 的底层机制对照 lora_pipeline.py 中load_lora_weights的实现可以看清加载链条首先调用lora_state_dict解析检查点得到state_dict、network_alphas与元数据metadata校验格式检查所有键名是否包含lora子串否则抛出Invalid LoRA checkpoint错误分别调用load_lora_into_unet与load_lora_into_text_encoder把低秩适配权重注入 UNet 与文本编码器。StableDiffusionPipeline的类定义见 pipeline_stable_diffusion.py同时继承了StableDiffusionLoraLoaderMixin提供load_lora_weights/save_lora_weights与FromSingleFileMixin提供from_single_file直接加载.ckpt因此这两类加载方式对 SD 系列 pipeline 是开箱即用的。此外load_lora_weights还支持adapter_name为适配器命名以便引用与hotswap参数hotswapTrue时原地替换已有适配器权重在torch.compile编译模型场景下可避免重新编译加载速度与内存占用更优注意文本编码器暂不支持 hotswap。更多格式与转换辅助手段单文件single-file格式除 Diffusers 目录格式外社区常见单文件格式——把 UNet、Transformer、文本编码器全部权重塞进一个文件。其优点是兼容 ComfyUI / Automatic1111且便于下载分享。可通过FromSingleFileMixin.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, dtypetorch.float16, device_mapcuda # 或 mps、xpu、cpu )当 Diffusers 格式模型的config.json无法正确推断时可通过config参数显式指定配置仓库也可以把config、dtype等参数直接传给from_single_file覆盖默认行为。from_single_file在local_files_onlyTrue时会基于 pipeline 类签名推断组件但该方式不如显式传入本地模型路径可靠若联网应使用local_files_onlyFalse让配置下载到本地缓存。反向转换与 LoRA 格式转换脚本当前仓库的 scripts 目录还提供了多组配套转换脚本形成完整的格式生态convert_diffusers_to_original_stable_diffusion.py 与 convert_diffusers_to_original_sdxl.py把 Diffusers 格式转回原版单文件格式可用--use_safetensors指定输出文件类型convert_lora_safetensor_to_diffusers.py将 LoRA safetensors 转换为 Diffusers 可加载形式convert_original_controlnet_to_diffusers.py、convert_original_t2i_adapter.py 等覆盖 ControlNet、T2I-Adapter 等附加模块的转换。命名以to_diffusers结尾的脚本即转换为 Diffusers 格式每个脚本都有各自独立的参数集使用前务必查阅其argparse定义。对于标准模型也可直接使用官方 SD → Diffusers / SD-XL → Diffusers Space它会自动在模型仓库上打开包含转换文件的 PR是最省事的方案但对复杂模型可能失败此时脚本方案更可靠。安全提示与最佳实践优先 safetensorsconvert_original_stable_diffusion_to_diffusers.py同时支持--from_safetensors读取 safetensors 输入与--to_safetensors写出 safetensors 输出建议统一使用 safetensors 规避 pickle 反序列化风险尽量提供原始 YAML 配置original_config_file是转换成功率的关键缺失时自动推断对微调模型不可靠ControlNet 等附加模块转换时务必加上--controlnet等对应标志脚本会只保存对应的附加模型如pipe.controlnet加载 LoRA 前校验格式load_lora_weights内部会检查键名是否含lora子串若报Invalid LoRA checkpoint说明文件并非标准 LoRA 权重。通过上述方案你可以把来自 Civitai、Automatic1111、KerasCV 等生态的模型与适配器无缝接入 Diffusers 的统一推理框架享受调度器自由切换、pipeline 定制与推理优化的全部能力。【免费下载链接】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），仅供参考