🤗 Diffusers 官方训练脚本全景指南：从零训练你自己的扩散模型

🤗 Diffusers 不仅在推理侧提供了开箱即用的 Pipeline，还在 examples 目录下沉淀了一套完整、可直接运行的训练脚本集合，覆盖无条件图像生成、文生图（text-to-image）、DreamBooth、ControlNet、文本反演（Textual Inversion）等主流扩散模型训练任务。本文以官方训练总览文档 overview.md 为核心骨架，结合当前仓库中的真实源码与配置，系统讲解训练脚本的设计原则、任务覆盖范围、环境安装步骤与训练加速手段，帮助你快速定位适合自己任务的训练入口，并具备在此基础上二次开发的能力。

训练脚本的设计哲学：四个原则

官方训练脚本遵循四个明确的工程原则（详见 examples/README.md），理解它们有助于判断某个脚本是否适合直接使用、以及需要如何改造：

• 自包含（Self-contained）：训练脚本不依赖任何仓库内的本地文件，所有第三方依赖全部通过 requirements.txt 声明并安装。以 text_to_image/requirements.txt 为例，它明确列出了 accelerate>=0.16.0、torchvision、transformers>=4.25.1、datasets>=2.19.1、ftfy、tensorboard、Jinja2、peft>=0.17.0 等包——把脚本单独拷贝出来，配合这份依赖清单即可运行。

• 易修改（Easy-to-tweak）：官方明确声明脚本是"示例"而非万能模板，不会开箱即用地适配每一种训练场景。为此，数据预处理代码和完整训练循环都被完全暴露在脚本中（例如 train_text_to_image.py 中从数据集加载、图像变换到前向传播与损失计算的完整逻辑均可直接编辑），方便你按自己的数据集和任务改造。

• 新手友好（Beginner-friendly）：训练脚本追求"容易读懂"，优先保证可理解性，而非引入最新 SOTA 方法。刻意省略了过于复杂的高级训练技巧，作为理解扩散模型训练机制和上手 diffusers 的桥梁。

• 单一用途（Single-purpose）：每个脚本只演示一个任务。即使某些任务在模型层面高度相似（例如图像超分与图像编辑共用同一类 UNet 结构），官方也坚持一脚本一任务，以保证代码可读性。

从源码结构看，这一原则贯穿始终：examples 下每个目录对应一个训练任务，且每个目录都自带 requirements.txt，部分任务还有针对 SDXL、LoRA 或特定模型（如 FLUX）的专属依赖文件（如 examples/dreambooth/requirements_sdxl.txt、examples/controlnet/requirements_flux.txt），印证了"自包含"与"按任务拆分"的工程约束。

官方训练脚本全景

下表是官方当前维护的训练脚本清单（对应原文档核心表格，已将链接映射到本仓库路径，并补充了 SDXL 与 LoRA 支持情况）：

训练任务	SDXL 支持	LoRA 支持	仓库路径
无条件图像生成（Unconditional Image Generation）	—	—	examples/unconditional_image_generation
文生图微调（Text-to-Image）	👍	👍	examples/text_to_image
文本反演（Textual Inversion）	—	—	examples/textual_inversion
DreamBooth	👍	👍	examples/dreambooth
ControlNet	👍	—	examples/controlnet
InstructPix2Pix	👍	—	examples/instruct_pix2pix
Custom Diffusion	—	—	examples/custom_diffusion
T2I-Adapter	👍	—	examples/t2i_adapter
Kandinsky 2.2 文生图	—	👍	examples/kandinsky2_2/text_to_image

逐个拆解：每个脚本解决什么问题

无条件图像生成：train_unconditional.py 是最基础的自监督训练示例，使用 UNet2DModel + DDPMScheduler 从零训练 DDPM 模型，不依赖任何文本条件，适合理解扩散模型前向加噪、反向去噪的核心训练循环，也是上手训练脚本的首选入口。

文生图微调：train_text_to_image.py 在 Stable Diffusion 之上微调 UNet，支持使用 --dataset_name 指定 Hugging Face Hub 数据集（脚本内置了 lambdalabs/naruto-blip-captions 的字段映射），也支持本地数据目录。训练完成后脚本会自动生成模型卡片并推送到 Hub。

文本反演（Textual Inversion）：textual_inversion.py 只训练新增的文本嵌入向量（不更新 UNet 与 VAE），教会模型"认识"一个新的概念 token，用于个性化生成。

DreamBooth：examples/dreambooth 目录下提供 train_dreambooth.py 与 train_dreambooth_lora.py 等脚本，用少量主题图片微调扩散模型，并配套 SDXL、SD3、FLUX 等多个模型的专属训练脚本与需求文件，是当前仓库中覆盖模型最广的训练任务之一。

ControlNet：train_controlnet.py 在基础扩散模型之上训练 ControlNet 分支，让生成过程受边缘、深度、姿态等条件控制，另见 docs/source/en/training/controlnet.md。

InstructPix2Pix：train_instruct_pix2pix.py 训练指令式图像编辑模型，用自然语言指令对图像进行局部修改。

Custom Diffusion：train_custom_diffusion.py 通过联合微调 UNet 与文本编码器实现多概念个性化，详见 docs/source/en/training/custom_diffusion.md。

T2I-Adapter：train_t2i_adapter_sdxl.py 训练轻量级 T2I-Adapter 适配器，将额外条件注入生成过程，详见 docs/source/en/training/t2i_adapters.md。

Kandinsky 2.2：examples/kandinsky2_2/text_to_image 提供多语言文生图模型 Kandinsky 2.2 的 LoRA 微调脚本。

需要说明的是，当前仓库的 examples 目录远比上表更丰富，还包含 LoRA（docs/source/en/training/lora.md）、SDXL（docs/source/en/training/sdxl.md）、Latent Consistency Distillation（docs/source/en/training/lcm_distill.md）、视频模型 CogVideoX（docs/source/en/training/cogvideox.md）以及 DDPO 强化学习训练（docs/source/en/training/ddpo.md）等进阶示例；同时还有由社区维护的 examples/community 与 examples/research_projects 目录，供进阶场景参考。

环境准备：从源码安装与依赖安装

为保证训练脚本与最新代码保持同步，官方建议在全新的虚拟环境中从源码安装 diffusers：

git clone https://github.com/huggingface/diffusers
cd diffusers
pip install .

随后进入对应训练脚本目录，安装其 requirements.txt。部分脚本针对 SDXL 或 LoRA 提供了专属依赖文件，使用对应功能时必须一并安装。以 DreamBooth 为例：

cd examples/dreambooth
pip install -r requirements.txt
# 使用 DreamBooth 训练 SDXL 时还需安装：
pip install -r requirements_sdxl.txt

以 examples/dreambooth/requirements.txt 的实际内容为参照，其核心依赖包括 accelerate>=0.16.0（分布式训练框架）、torchvision、transformers>=4.25.1（文本编码器）、ftfy、tensorboard（日志可视化）、Jinja2 与固定版本的 peft==0.7.0（LoRA 训练依赖）。注意不同任务的 requirements 版本策略并不一致：text-to-image 使用 peft>=0.17.0，而 dreambooth 固定为 peft==0.7.0，混用不同示例前应仔细核对各自的依赖文件，避免版本冲突。

提示：训练脚本入口均调用 check_min_version（如 train_text_to_image.py 中校验 0.41.0.dev0），若本地 diffusers 版本过低会直接报错，这同样是"从源码安装以保持最新"的原因之一。

训练加速与显存优化

官方在训练总览中给出了两条明确的加速建议，均无需改动训练代码：

使用 PyTorch 2.0+ 自动启用 SDPA

PyTorch 2.0 及以上版本会自动启用 Scaled Dot Product Attention（SDPA）。SDPA 在底层集成了 FlashAttention、xFormers 以及原生 C++ 实现等多种注意力后端，并根据硬件自动选择最优后端，在训练与推理中同时带来速度提升与显存下降，详见 docs/source/en/optimization/fp16.md。升级 PyTorch 后无需对训练代码做任何修改即可受益。

安装 xFormers 启用内存高效注意力

官方推荐在训练与推理中都使用 xFormers。其注意力模块的优化经官方测试可同时获得更快的速度与更低的内存占用，安装方式：

pip install xformers

需要注意两点：其一，xFormers 的 pip 包要求最新的 PyTorch 版本，若使用旧版 PyTorch 需从源码编译安装；其二，官方在 xformers.md 中记录了 xFormers v0.0.16 在部分 GPU 上无法用于微调/DreamBooth 训练的问题，遇到时需安装开发版本规避。

深入学习路线：按任务查阅专项文档

docs/source/en/training 目录下为每个训练任务提供了更深入的专项指南，建议按任务需求交叉阅读：

• 数据准备：create_dataset.md 讲解如何构造训练数据集（本地目录、压缩包、远程文件与多分片等加载方式）；
• 核心任务：unconditional_training.md、text2image.md、text_inversion.md、dreambooth.md、controlnet.md、instructpix2pix.md、kandinsky.md、t2i_adapters.md；
• 进阶主题：lora.md（参数高效微调）、sdxl.md（SDXL 训练）、adapt_a_model.md（将模型适配到新任务）、lcm_distill.md（蒸馏加速采样）、ddpo.md（强化学习训练）、distributed_inference.md（分布式推断）、nemo_automodel.md（NeMo 自动模型训练）。

结语

Diffusers 的训练脚本体系是一套"可读、可跑、可改"的扩散模型训练入门与实践平台：examples 目录提供了覆盖主流任务的官方示例，docs/source/en/training 提供了逐任务的深度指南，二者配合即可从理解训练循环出发，逐步走上定制自己的扩散模型训练流水线的道路。这些示例由官方主动维护，若你在使用中发现问题，欢迎在仓库中提交 Issue；若希望新增某个训练示例，官方也鼓励通过 Feature Request 讨论其是否符合"自包含、易修改、新手友好、单一用途"四项入选标准。