Diffusers 适配器加载实战指南DreamBooth、Textual Inversion、LoRA 与 IP-Adapter 完整解析【免费下载链接】diffusers Diffusers: State-of-the-art diffusion models for image, video, and audio generation in PyTorch.项目地址: https://gitcode.com/GitHub_Trending/di/diffusers本篇技术指南以 Diffusers 项目当前仓库GitHub_Trending/di/diffusers的文档《어댑터 불러오기加载适配器》为骨架系统讲解如何为扩散模型加载 DreamBooth 完整检查点、Textual Inversion 文本嵌入、LoRA 权重以及 IP-Adapter 图像适配器。读完本文后你将掌握每种适配器的加载原理、触发方式、权重缩放与卸载方法并能直接运行文中的可复现代码。阅读提示本仓库源码中src/diffusers/loaders/目录集中实现了本文涉及的所有加载器 Mixin文中将结合源码路径进行纵深说明。一、为什么需要加载适配器要让扩散模型生成特定物体或特定风格的图像常见做法是先对模型进行个性化训练。仓库文档将其概括为若干种训练方法参见 训练概览而不同训练方法会产出不同类型的适配器adapter有些适配器是全新的完整模型例如 DreamBooth 微调后产出的整个 checkpoint有些适配器只修改一小部分嵌入embedding或权重例如 Textual Inversion 的新嵌入、LoRA 的低秩权重增量。由于产物形态不同每种适配器的加载流程也各不相同。本文即围绕这一核心差异逐一演示各类适配器的加载方式。适配器资源可以在社区找到Stable Diffusion Conceptualizer、LoRA the Explorer、Diffusers Models Gallery 等社区合集收录了大量现成 checkpoint 与嵌入可直接用于下述代码示例。二、DreamBooth加载完整微调检查点2.1 原理与适用场景DreamBooth 会对整个扩散模型进行微调使其学会用新的风格和设定生成特定物体。它的工作方式是训练时让模型学习把物体图像与提示词中的特殊触发词关联起来。在所有训练方法中DreamBooth 产出的文件最大——因为它是完整的 checkpoint 模型体积通常有数 GB。2.2 加载示例下面加载仅用 10 张 Hergé 画作训练出的herge_stylecheckpoint并生成对应风格的图像。注意必须把触发词herge_style写进提示词模型才会生效from diffusers import AutoPipelineForText2Image import torch pipeline AutoPipelineForText2Image.from_pretrained(sd-dreambooth-library/herge-style, dtypetorch.float16).to(cuda) prompt A cute herge_style brown bear eating a slice of pizza, stunning color scheme, masterpiece, illustration image pipeline(prompt).images[0] image由于是完整模型加载方式与普通 pipeline 完全一致——AutoPipelineForText2Image.from_pretrained会读取仓库内的全部组件UNet、文本编码器、VAE、调度器等。这里直接用了dtypetorch.float16将权重以半精度加载以节省显存更规范的写法是传入torch_dtypetorch.float16。三、Textual Inversion加载文本嵌入3.1 原理与适用场景Textual inversion 与 DreamBooth 类似同样只需少量图像即可个性化模型学习某个风格或物体。区别在于它不修改扩散模型的任何权重而是训练并找到一个新的嵌入向量——当提示词中出现特定单词时模型会查找该单词对应的嵌入并据此生成图像。因此训练产物非常小通常只有数 KB。也正因如此Textual Inversion不能单独使用必须配合一个已有的扩散模型from diffusers import AutoPipelineForText2Image import torch pipeline AutoPipelineForText2Image.from_pretrained(stable-diffusion-v1-5/stable-diffusion-v1-5, dtypetorch.float16).to(cuda)3.2 加载嵌入并生成图像使用load_textual_inversion方法由 TextualInversionLoaderMixin 提供加载sd-concepts-library/gta5-artwork嵌入。触发词是gta5-artwork需要原样出现在提示词中pipeline.load_textual_inversion(sd-concepts-library/gta5-artwork) prompt A cute brown bear eating a slice of pizza, stunning color scheme, masterpiece, illustration, gta5-artwork style image pipeline(prompt).images[0] image3.3 加载 A1111 格式与指定触发词Textual Inversion 还能训练负向嵌入negative embedding——让模型避免生成模糊图像、多余手指等不良内容是一种快速改善出图质量的技巧。加载方式与上面相同但需要额外传入两个参数weight_name当文件以特定名称保存为 Diffusers 格式或文件是A1111Automatic1111格式时用它指定要加载的权重文件名token指定在提示词中触发该嵌入的特殊单词。示例加载sayakpaul/EasyNegative-test嵌入权重文件为EasyNegative.safetensors触发词为EasyNegativepipeline.load_textual_inversion( sayakpaul/EasyNegative-test, weight_nameEasyNegative.safetensors, tokenEasyNegative )随后即可把token用作负向提示词prompt A cute brown bear eating a slice of pizza, stunning color scheme, masterpiece, illustration, EasyNegative negative_prompt EasyNegative image pipeline(prompt, negative_promptnegative_prompt, num_inference_steps50).images[0] image3.4 源码层面的加载逻辑从 load_textual_inversion 实现 可以看到完整的处理链路确定 tokenizer 与 text encoder默认取 pipeline 自身组件将输入归一化为列表形式并校验模型列表与 token 列表长度一致_check_text_inv_inputs加载嵌入的 state dict。支持三类来源Hub 上的模型 id、本地目录、单个权重文件如./my_text_inversions.pt或 torch state dict解析嵌入格式_retrieve_tokens_and_embeddingsDiffusers 格式的 dict 只有一个 key即 token 名A1111 格式则包含string_to_param字段此时 token 从state_dict[name]读取如果传入的是纯 tensor则必须显式提供token处理多向量嵌入_extend_tokens_and_embeddings若嵌入张量的第一个维度大于 1会自动拆分为token_1、token_2…… 等多个 token并把嵌入逐行展开。配合maybe_convert_prompt见 textual_inversion.py加载多向量嵌入后即使提示词中只写token推理时也会自动替换为token token_1 token_2 ...序列校验嵌入维度与文本编码器嵌入层维度一致将 token 加入 tokenizer 词汇表、嵌入写入文本编码器。四、LoRA加载低秩适配权重4.1 原理与适用场景Low-Rank Adaptation (LoRA) 是目前最流行的训练技术训练速度快、产物小通常几十到几百 MB。原理是向扩散模型中注入新的低秩权重只训练这些新权重而不是整个模型因此更易训练、更易存储和分发。与 Textual Inversion 一样LoRA 不能独立使用必须配合一个基础模型。此外 LoRA 可与多种训练方法组合例如 DreamBooth LoRA 是常见组合也常通过加载并合并多个 LoRA 来创造全新风格的图像——多 LoRA 合并不在本文范围内可参考仓库中的 LoRA 合并专项指南。4.2 使用 load_lora_weights 加载先加载基础模型 SDXLfrom diffusers import AutoPipelineForText2Image import torch pipeline AutoPipelineForText2Image.from_pretrained(stabilityai/stable-diffusion-xl-base-1.0, dtypetorch.float16).to(cuda)然后用load_lora_weights加载ostris/super-cereal-sdxl-lora权重并通过weight_name指定仓库中的权重文件名pipeline.load_lora_weights(ostris/super-cereal-sdxl-lora, weight_namecereal_box_sdxl_v1.safetensors) prompt bears, pizza bites image pipeline(prompt).images[0] imageload_lora_weights会把 LoRA 权重同时加载到 UNet 和文本编码器是以下场景的首选方式LoRA 权重中的 UNet 与文本编码器没有独立标识符LoRA 权重中 UNet 与文本编码器有独立标识符。4.3 只加载到 UNetload_attn_procs如果只想把 LoRA 加载到 UNet可使用load_attn_procs由 UNet2DConditionLoadersMixin 提供。例如加载jbilcke-hf/sdxl-cinematic-1LoRAfrom diffusers import AutoPipelineForText2Image import torch pipeline AutoPipelineForText2Image.from_pretrained(stabilityai/stable-diffusion-xl-base-1.0, dtypetorch.float16).to(cuda) pipeline.unet.load_attn_procs(jbilcke-hf/sdxl-cinematic-1, weight_namepytorch_lora_weights.safetensors) # 在提示词中使用 cnmt 触发 LoRA prompt A cute cnmt eating a slice of pizza, stunning color scheme, masterpiece, illustration image pipeline(prompt).images[0] image4.4 卸载 LoRA调用unload_lora_weights可删除 LoRA 权重把模型恢复为原始权重pipeline.unload_lora_weights()从源码看load_lora_weights/unload_lora_weights/fuse_lora/unfuse_lora等核心方法定义在 src/diffusers/loaders/lora_pipeline.py 中且针对 Stable Diffusion、SDXL、Flux、Wan 等不同架构提供了各自的实现版本。加载时还会检查 state dict 中所有键名是否包含lora子串若格式不合法会直接抛出ValueError。另外需要注意仓库中名为LoraLoaderMixin的类已标记为弃用见 lora_pipeline.py未来版本将移除请改用StableDiffusionLoraLoaderMixin。4.5 缩放 LoRA 权重cross_attention_kwargsload_lora_weights与load_attn_procs都支持通过cross_attention_kwargs{scale: 0.5}控制 LoRA 的使用强度scale0等价于只用基础模型权重scale1等价于完全使用微调后的 LoRA 权重。4.6 逐层精细控制set_adapters若需要对每一层使用多少 LoRA 权重做更细粒度的控制可使用set_adapters实现见 src/diffusers/loaders/lora_base.py传入一个按组件/层级组织的缩放字典pipe ... # 创建 pipeline pipe.load_lora_weights(..., adapter_namemy_adapter) scales { text_encoder: 0.5, text_encoder_2: 0.5, # 仅当 pipeline 有第二个文本编码器时可用 unet: { down: 0.9, # down 部分的所有 transformer 使用 0.9 # mid # 未指定时mid 部分的 transformer 使用默认 1.0 up: { block_0: 0.6, # up 第 0 个 block 中的 3 个 transformer 全部使用 0.6 block_1: [0.4, 0.8, 1.0], # up 第 1 个 block 的 3 个 transformer 分别使用 0.4、0.8、1.0 } } } pipe.set_adapters(my_adapter, scales)其源码逻辑会校验传入的组件名是否属于该 pipeline 可加载 LoRA 的模块集合_lora_loadable_modules并自动把单个浮点数权重扩展为与 adapter 数量等长的列表若传入的 adapter 名尚未加载会抛出明确错误。set_adapters同样支持同时管理多个适配器可参考 PEFT 推理相关文档了解多适配器强度定制。[!WARNING] 当前set_adapters只支持缩放注意力权重如果 LoRA 还包含其他部分如 resnet、down/upsampler这些部分将保持 1.0 的缩放。4.7 社区训练器产物Kohya 与 TheLastBen社区流行的其他 LoRA 训练器包括 Kohya 与 TheLastBen 的 trainer。它们产出的 LoRA checkpoint 与 Diffusers 自训练格式不同但可以用同样的方式加载。Kohya LoRA 示例先从 Civitai 下载Blueprintify SD XL 1.0权重!wget https://civitai.com/api/download/models/168776 -O blueprintify-sd-xl-10.safetensors然后用load_lora_weights加载本地文件并通过weight_name指定文件名from diffusers import AutoPipelineForText2Image import torch pipeline AutoPipelineForText2Image.from_pretrained(stabilityai/stable-diffusion-xl-base-1.0, dtypetorch.float16).to(cuda) pipeline.load_lora_weights(path/to/weights, weight_nameblueprintify-sd-xl-10.safetensors)生成图像提示词中用bl3uprint触发 LoRAprompt bl3uprint, a highly detailed blueprint of the eiffel tower, explaining how to build all parts, many txt, blueprint grid backdrop image pipeline(prompt).images[0] image[!WARNING] 将 Kohya LoRA 与 Diffusers 搭配使用时存在一些限制由于多种原因生成的图像可能与 ComfyUI 等 UI 中生成的结果略有差异LyCORIS checkpoint 未完全支持load_lora_weights可以加载 LyCORIS 的LoRA 与 LoCon模块但Hada 与 LoKR不支持。TheLastBen LoRA 示例加载方式非常相似例如加载TheLastBen/William_Eggleston_Style_SDXLfrom diffusers import AutoPipelineForText2Image import torch pipeline AutoPipelineForText2Image.from_pretrained(stabilityai/stable-diffusion-xl-base-1.0, dtypetorch.float16).to(cuda) pipeline.load_lora_weights(TheLastBen/William_Eggleston_Style_SDXL, weight_namewegg.safetensors) # 在提示词中使用 william eggleston 触发 LoRA prompt a house by william eggleston, sunrays, beautiful, sunlight, sunrays, beautiful image pipeline(promptprompt).images[0] image五、IP-Adapter加载图像提示适配器5.1 原理与适用场景IP-Adapter 是一种轻量级图像提示适配器可为任意扩散模型引入以图生图能力。其原理是在cross-attention 层中将图像特征与文本特征分离冻结其余所有模型组件只训练 UNet 中嵌入的图像特征。因此 IP-Adapter 文件通常只有约 100MB。关于 IP-Adapter 在不同任务与具体用例中的详细用法可参考仓库中的 IP-Adapter 专项指南。[!TIP] Diffusers 目前只对部分最常用的 pipeline 支持 IP-Adapter如果你有优秀用例但对应 pipeline 尚不支持可以在仓库中提交 feature request。官方 IP-Adapter 检查点位于h94/IP-Adapter仓库。5.2 基本加载流程首先加载 Stable Diffusion 基础模型from diffusers import AutoPipelineForText2Image import torch from diffusers.utils import load_image pipeline AutoPipelineForText2Image.from_pretrained(stable-diffusion-v1-5/stable-diffusion-v1-5, dtypetorch.float16).to(cuda)然后用load_ip_adapter由 IPAdapterMixin 提供加载 IP-Adapter 权重并挂载到 pipelinepipeline.load_ip_adapter(h94/IP-Adapter, subfoldermodels, weight_nameip-adapter_sd15.bin)加载完成后即可同时使用图像与文本提示词引导生成过程image load_image(https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/load_neg_embed.png) generator torch.Generator(devicecpu).manual_seed(33) images pipeline( promptbest quality, high quality, wearing sunglasses, ip_adapter_imageimage, negative_promptmonochrome, lowres, bad anatomy, worst quality, low quality, num_inference_steps50, generatorgenerator, ).images[0] images5.3 IP-Adapter Plus显式加载图像编码器IP-Adapter 依赖一个图像编码器来生成图像特征。如果 IP-Adapter 仓库中存在image_encoder子文件夹加载时会自动读取并注册否则需要用CLIPVisionModelWithProjection显式加载图像编码器并传给 pipeline。使用ViT-H 图像编码器的IP-Adapter Plus检查点就属于后者from transformers import CLIPVisionModelWithProjection image_encoder CLIPVisionModelWithProjection.from_pretrained( h94/IP-Adapter, subfoldermodels/image_encoder, dtypetorch.float16 ) pipeline AutoPipelineForText2Image.from_pretrained( stabilityai/stable-diffusion-xl-base-1.0, image_encoderimage_encoder, dtypetorch.float16 ).to(cuda) pipeline.load_ip_adapter(h94/IP-Adapter, subfoldersdxl_models, weight_nameip-adapter-plus_sdxl_vit-h.safetensors)5.4 IP-Adapter Face ID人脸一致性IP-Adapter FaceID 是一类实验性适配器它不使用 CLIP 图像嵌入而是使用insightface生成的图像嵌入部分模型还会结合 LoRA 提升 ID 一致性。使用前需要安装insightface及其依赖。[!WARNING] InsightFace 预训练模型仅可用于非商业研究目的因此 IP-Adapter-FaceID 系列模型只供研究用途不可用于商业场景。SDXL 基础用法pipeline AutoPipelineForText2Image.from_pretrained( stabilityai/stable-diffusion-xl-base-1.0, dtypetorch.float16 ).to(cuda) pipeline.load_ip_adapter(h94/IP-Adapter-FaceID, subfolderNone, weight_nameip-adapter-faceid_sdxl.bin, image_encoder_folderNone)两个FaceID Plus模型为了更好的真实感同时使用insightface与 CLIP 图像嵌入因此还需要加载 CLIP 图像编码器from transformers import CLIPVisionModelWithProjection image_encoder CLIPVisionModelWithProjection.from_pretrained( laion/CLIP-ViT-H-14-laion2B-s32B-b79K, dtypetorch.float16, ) pipeline AutoPipelineForText2Image.from_pretrained( stable-diffusion-v1-5/stable-diffusion-v1-5, image_encoderimage_encoder, dtypetorch.float16 ).to(cuda) pipeline.load_ip_adapter(h94/IP-Adapter-FaceID, subfolderNone, weight_nameip-adapter-faceid-plus_sd15.bin)从源码看load_ip_adapter会依据传入的subfolder、weight_name、image_encoder_folder等参数从 Hub 或本地目录解析权重将图像编码器与 IP-Adapter 模块注册进 pipeline并在推理时通过ip_adapter_image参数接收图像输入卸载对应调用unload_ip_adapter见 src/diffusers/loaders/ip_adapter.py。六、总结四种适配器加载方式速查适配器类型产物形态文件大小量级加载方法触发方式DreamBooth完整 checkpoint 模型数 GBAutoPipelineForText2Image.from_pretrained提示词中的特殊触发词Textual Inversion文本嵌入向量数 KBload_textual_inversion提示词中的特殊 token如gta5-artworkLoRA低秩权重增量数十数百 MBload_lora_weights/unet.load_attn_procs提示词中的触发词可用scale/set_adapters调强度IP-Adapter轻量图像适配器 图像编码器约 100 MBload_ip_adapter推理时传入ip_adapter_image所有加载器 Mixin 的实现均集中在 src/diffusers/loaders/ 目录下包括 textual_inversion.py、lora_pipeline.py、lora_base.py、ip_adapter.py 与 unet.py。理解这些源码有助于排查加载失败问题例如嵌入维度不匹配、token 冲突、state dict 格式非法等——这些场景都会在加载时抛出明确的错误信息。实际使用时建议始终为 pipeline 传入torch_dtype如torch.float16并迁移到 GPU以获得合理的显存占用与推理速度。【免费下载链接】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），仅供参考