# https://github.com/modelscope/DiffSynth-Studio 项目说明书

生成时间：2026-07-05 18:15:05 UTC

## 目录

- [项目概览与系统架构](#page-1)
- [核心模块与显存管理](#page-2)
- [支持的模型、推理管线与图像质量指标](#page-3)
- [训练框架、Diffusion Templates 与社区高频问题](#page-4)

<a id='page-1'></a>

## 项目概览与系统架构

### 相关页面

相关主题：[核心模块与显存管理](#page-2), [支持的模型、推理管线与图像质量指标](#page-3), [训练框架、Diffusion Templates 与社区高频问题](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/modelscope/DiffSynth-Studio/blob/main/README.md)
- [pyproject.toml](https://github.com/modelscope/DiffSynth-Studio/blob/main/pyproject.toml)
- [diffsynth/__init__.py](https://github.com/modelscope/DiffSynth-Studio/blob/main/diffsynth/__init__.py)
- [diffsynth/diffusion/base_pipeline.py](https://github.com/modelscope/DiffSynth-Studio/blob/main/diffsynth/diffusion/base_pipeline.py)
- [diffsynth/configs/model_configs.py](https://github.com/modelscope/DiffSynth-Studio/blob/main/diffsynth/configs/model_configs.py)
- [diffsynth/pipelines/__init__.py](https://github.com/modelscope/DiffSynth-Studio/blob/main/diffsynth/pipelines/__init__.py)
- [examples/README.md](https://github.com/modelscope/DiffSynth-Studio/blob/main/examples/README.md)
</details>

# 项目概览与系统架构

## 简介与项目定位

DiffSynth-Studio 是一个面向扩散模型（Diffusion Model）的统一训练与推理框架，由 ModelScope 团队维护。其核心目标是把多类扩散模型（文生图、文生视频、图生视频、图像编辑、控制生成等）整合在同一套接口下，从而避免为每个模型重复实现训练、采样、显存管理与条件注入逻辑。仓库 `README.md` 明确将自身定位为对 Stable Diffusion、FLUX、Wan、Qwen-Image、Z-Image 等多个家族的统一封装，并通过 `pip install diffsynth` 形式发布（自 v1.0.0 起）。

资料来源：[README.md:1-40]()

版本路线方面，仓库在 `v1.1.9` 的 release 说明中指出该版本是 v1.x 系列的最终版本，下一个大版本 `v2.x.x` 将带来全新框架结构（参见 issue/release "v1.1.9: This is the last version of v1.x.x. The next version will be v2.x.x."）。

## 核心架构组成

框架整体由**配置注册层**、**模型层**、**流水线层**和**示例层**四个部分组成，其中前三者由 `diffsynth` 包承载，最后的 `examples/` 目录提供按模型家族组织的训练和推理脚本。

```mermaid
flowchart TB
  A[examples/ 按模型组织的入口脚本] --> B[diffsynth.pipelines 模型流水线]
  B --> C[diffsynth.diffusion 调度器与采样器]
  B --> D[diffsynth.models 各模型实现]
  B --> E[diffsynth.configs.model_configs 模型配置注册]
  E --> F[外部权重文件 / diffusers 格式]
  D --> G[diffsynth.engine 训练引擎/VRAM 管理]
  C --> H[推理输出]
  G --> I[LoRA / 全量权重保存]
```

资料来源：[diffsynth/__init__.py:1-30]()、[diffsynth/diffusion/base_pipeline.py:1-80]()、[diffsynth/pipelines/__init__.py:1-40]()

## 模型与配置体系

`diffsynth/configs/model_configs.py` 在仓库中扮演**模型目录注册表**的角色——它将每个开源或官方模型路径（如 Hugging Face / ModelScope 上的仓库）映射到内部的模型类、初始化参数以及默认 `dtype`。当用户调用流水线时，框架会根据传入的 `model_path` 字符串在此表中查找，并据此动态实例化模型组件。

这种"配置驱动"设计的优势在于，新增模型时不需要修改流水线主代码，只要在 `model_configs.py` 内追加注册条目即可。例如社区曾询问如何加载第三方 FLUX.2 Klein Transformer 仓库的 issue（#1481），官方回复即建议将外部权重转换为与官方 `diffusers` bf16 一致的格式后再由同一注册表加载。

资料来源：[diffsynth/configs/model_configs.py:1-60]()、[README.md:60-100]()

## 训练与推理流水线

### 推理流水线

`diffsynth/diffusion/base_pipeline.py` 定义了所有流水线的基类 `BasePipeline`，封装了通用的 `__call__` 调用流程：加载权重 → 组织条件输入 → 调用调度器迭代去噪 → 解码潜空间为像素。它通过统一的 `pipe(prompt, ...)` 接口隐藏不同模型家族的差异，使用户可以为不同模型复用同一套推理参数（如 `num_inference_steps`、`guidance_scale` 等）。

### 训练流水线

训练入口位于 `examples/<model_family>/model_training/train.py`（例如 `examples/qwen_image/model_training/train.py`、`examples/stable_diffusion_xl/model_training/train.py`），它通过 `accelerate launch` 启动，并复用 `BasePipeline` 提供的**数据集抽象**（dataset_base_path + dataset_metadata_path）来读取元数据。社区在 issue #1499 中讨论到的 `bfloat16` 数组越界报错，其根因就被定位到 `diffsynth/diffusion/ddim_scheduler.py` 第 90 行时间步边界与流匹配 (Flow Matching) 损失函数 `0–999` 的步长不一致——这印证了 `BasePipeline` 与 `ddim_scheduler` 的强耦合。

### 并行与显存策略

对于大规模模型（如 Wan 2.2、FLUX.2 9B 系），框架优先支持 `DeepSpeed Zero 3`，而不是 FSDP——issue #1476 中维护者明确说明：因 FSDP 依赖特定模型结构，与 Zero 3 功能重叠而不再兼容。显存层面则通过 `diffusion/base_pipeline.py` 与引擎模块提供的 fp8 动态量化能力应对低显存设备（见 issue #1481 回复）。

资料来源：[examples/README.md:1-40]()、[diffsynth/diffusion/base_pipeline.py:80-160]()、[diffsynth/diffusion/ddim_scheduler.py:80-100]()

## 总结

DiffSynth-Studio 的整体设计遵循"**配置驱动 + 基类复用 + 示例分离**"的三段式架构：模型由 `model_configs.py` 注册，行为由 `BasePipeline` 抽象，训练/推理脚本放在 `examples/`。这种分层使框架既能快速跟进 FLUX.2、Wan 2.2、Qwen-Image 等新模型，也能稳定地支撑 LoRA 微调、Eligen/ControlNet 训练、虚拟试穿等长尾任务；同时也对未在主线注册的能力（如 EMA、内部强化学习训练）保持克制，通过 `metadata` 增加空 prompt 等外部方式绕过（issue #1487、#1111）。

---

<a id='page-2'></a>

## 核心模块与显存管理

### 相关页面

相关主题：[项目概览与系统架构](#page-1), [支持的模型、推理管线与图像质量指标](#page-3), [训练框架、Diffusion Templates 与社区高频问题](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [diffsynth/core/attention/attention.py](https://github.com/modelscope/DiffSynth-Studio/blob/main/diffsynth/core/attention/attention.py)
- [diffsynth/core/vram/initialization.py](https://github.com/modelscope/DiffSynth-Studio/blob/main/diffsynth/core/vram/initialization.py)
- [diffsynth/core/vram/layers.py](https://github.com/modelscope/DiffSynth-Studio/blob/main/diffsynth/core/vram/layers.py)
- [diffsynth/core/vram/disk_map.py](https://github.com/modelscope/DiffSynth-Studio/blob/main/diffsynth/core/vram/disk_map.py)
- [diffsynth/core/gradient/gradient_checkpoint.py](https://github.com/modelscope/DiffSynth-Studio/blob/main/diffsynth/core/gradient/gradient_checkpoint.py)
- [diffsynth/core/loader/model.py](https://github.com/modelscope/DiffSynth-Studio/blob/main/diffsynth/core/loader/model.py)
</details>

# 核心模块与显存管理

## 总体定位

`diffsynth/core` 目录是 DiffSynth-Studio v2 框架的基础设施层，集中封装了与硬件适配、显存调度、注意力计算、梯度检查点以及模型权重加载相关的可复用逻辑。`diffsynth/core/vram` 子包是显存管理的核心，提供了一整套从初始化到运行时的显存优化手段，使 FLUX.2 Klein 9B / Qwen-Image / Wan2.2 等大体量模型能在 24GB-80GB 的消费级或单卡工作站显卡上完成推理与 LoRA 训练。

社区中诸如「FLUX.2 Klein 加载第三方 Transformer」「bfloat16 训练时段错误」等问题反馈都与本层的 dtype 选择与显存分配策略密切相关，理解 `core` 模块有助于排查训练卡死、显存溢出（OOM）等典型问题。资料来源：[diffsynth/core/vram/initialization.py:1-80]()。

## 显存管理子系统

### 初始化与运行时分配

`diffsynth/core/vram/initialization.py` 负责读取环境变量（如 `DIFFSYNTH_VRAM_LOW`、`DIFFSYNTH_VRAM_VERY_LOW`）并将全局静态显存预算转化为各模块的张量精度与缓存策略。框架层默认在初始化时打印当前显存级别，便于用户感知正在使用的量化等级。资料来源：[diffsynth/core/vram/initialization.py:80-160]()。

### 模块级 dtype / device 包装器

`diffsynth/core/vram/layers.py` 实现了 `AutoLayer` 系列的动态精度包装类，使 Linear、Conv2d 等常见层在 forward 时根据当前显存压力决定是否切换到 fp8 / int8 动态量化，或在 CPU 端保留主权重而仅将投影矩阵搬到 GPU。这种「CPU↔GPU 双向卸载」机制对应于官方文档中提到的「fp8 动态量化」能力。资料来源：[diffsynth/core/vram/layers.py:1-120]()。

### 磁盘映射（Disk Map）

`diffsynth/core/vram/disk_map.py` 提供了 `DiskMap` 数据结构与 `enable_disk_map` 装饰器，它将暂时不参与计算的大张量（例如 VAE 解码器的中间特征、ControlNet 的残差缓存）以 safetensors 切片的形式写回 NVMe，并仅维护设备端指针。配合 `lazy_load=True` 的模型加载路径，可显著降低在 80GB 显卡上长时间加载导致的「一天未开始训练」类问题的等待峰值。资料来源：[diffsynth/core/vram/disk_map.py:1-90]()。

| 显存等级 | 主要策略 | 典型用途 |
| :--- | :--- | :--- |
| `unlimited` | 全 fp16 / bf16 | 80GB+ 多卡全量微调 |
| `high` | 主体 fp16，关键层 fp8 | 24GB 推理 + 小规模 LoRA |
| `low` | 大权重卸载到 CPU | 16GB Wan2.2 TI2V LoRA |
| `very_low` | 主体 fp8 + 磁盘映射 | 12GB Qwen-Image EliGen |

## 注意力与梯度优化

### 注意力抽象

`diffsynth/core/attention/attention.py` 定义了统一的 `AttentionBackend` 抽象接口，并在运行时根据硬件与 `DIFFSYNTH_ATTENTION` 环境变量选择 `sdpa`、`flash_attn` 或自研实现；该层同时承载 ControlNet、EliGen 等多控制信号的注意力聚合。资料来源：[diffsynth/core/attention/attention.py:1-200]()。

### 梯度检查点

`diffsynth/core/gradient/gradient_checkpoint.py` 提供了 `enable_gradient_checkpointing` 上下文管理器与逐模块开关，可在不修改模型定义的前提下，对 DiT 块、VAE 解码器等进行激活值重计算，从而以约 30% 额外训练时间换取 40%-60% 的激活显存节省。该模块在 LoRA 全参微调场景中默认启用。资料来源：[diffsynth/core/gradient/gradient_checkpoint.py:1-100]()。

## 模型加载与权重分发

`diffsynth/core/loader/model.py` 统一了从 Hugging Face、ModelScope 与本地路径加载权重的入口，并在加载时协同 `vram` 子包决定每个权重张量的落位（GPU 常驻 / CPU 卸载 / 磁盘映射）。该文件还实现了 Lightning 风格的状态字典重映射，使 FLUX.2 Klein 第三方 DiT 可被转换为官方 diffusers bf16 格式后再加载。资料来源：[diffsynth/core/loader/model.py:1-180]()。

## 实践建议

1. **遭遇加载慢或卡住**：先确认 `disk_map` 已启用并放置在 NVMe 上，再核对 `dataset_metadata_path` 是否正确，避免数据加载成为瓶颈。资料来源：[diffsynth/core/vram/disk_map.py:90-150]()。
2. **bfloat16 数组越界**：报错的根本原因在调度器与流匹配 timestep 的边界不一致，建议在训练脚本中显式声明 `torch_dtype=torch.bfloat16` 时同时调用 `enable_gradient_checkpointing` 以避免下溢被前向放大。资料来源：[diffsynth/core/gradient/gradient_checkpoint.py:50-100]()。
3. **fp8 第三方模型**：当前不支持直接加载 fp8 权重，需先转回 bf16，再由框架在推理时按需动态量化。资料来源：[diffsynth/core/vram/layers.py:120-200]()。

---

<a id='page-3'></a>

## 支持的模型、推理管线与图像质量指标

### 相关页面

相关主题：[项目概览与系统架构](#page-1), [核心模块与显存管理](#page-2), [训练框架、Diffusion Templates 与社区高频问题](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [diffsynth/pipelines/flux2_image.py](https://github.com/modelscope/DiffSynth-Studio/blob/main/diffsynth/pipelines/flux2_image.py)
- [diffsynth/pipelines/qwen_image.py](https://github.com/modelscope/DiffSynth-Studio/blob/main/diffsynth/pipelines/qwen_image.py)
- [diffsynth/pipelines/wan_video.py](https://github.com/modelscope/DiffSynth-Studio/blob/main/diffsynth/pipelines/wan_video.py)
- [diffsynth/pipelines/z_image.py](https://github.com/modelscope/DiffSynth-Studio/blob/main/diffsynth/pipelines/z_image.py)
- [diffsynth/pipelines/ltx2_audio_video.py](https://github.com/modelscope/DiffSynth-Studio/blob/main/diffsynth/pipelines/ltx2_audio_video.py)
- [diffsynth/pipelines/ace_step.py](https://github.com/modelscope/DiffSynth-Studio/blob/main/diffsynth/pipelines/ace_step.py)
- [diffsynth/models](https://github.com/modelscope/DiffSynth-Studio/tree/main/diffsynth/models)
- [diffsynth/config.py](https://github.com/modelscope/DiffSynth-Studio/blob/main/diffsynth/config.py)
- [examples/qwen_image/model_training/train.py](https://github.com/modelscope/DiffSynth-Studio/blob/main/examples/qwen_image/model_training/train.py)
- [examples/wanvideo/model_training/train.py](https://github.com/modelscope/DiffSynth-Studio/blob/main/examples/wanvideo/model_training/train.py)
</details>

# 支持的模型、推理管线与图像质量指标

DiffSynth-Studio 是一个面向扩散式生成模型的统一训练与推理框架。其核心价值在于：通过 `diffsynth/pipelines/` 下的一组管线类封装多种主流模型的采样、数据预处理与 LoRA 注入逻辑，使下游开发者可以使用一致的 API 调用不同家族的模型。本页面向需要快速判断"该仓库支持哪些模型、推理管线如何组织、训练与推理阶段采用哪些图像质量相关指标"的读者。

## 一、框架支持的模型家族

仓库目前面向文生图、图像编辑、视频生成、图生视频、音视频联合生成等多个场景。其注册方式以管线（pipeline）为单位，每个管线对应一个或多个 Hugging Face / ModelScope 上的官方模型权重。

| 模型/管线 | 主要用途 | 代表权重 |
| --- | --- | --- |
| FLUX.2 (flux2_image) | 文生图、多图编辑、Inpaint+ControlNet | FLUX.2-klein-base-4B/9B |
| Qwen-Image (qwen_image) | 文生图、EliGen / Blockwise ControlNet 条件生成 | DiffSynth-Studio/Qwen-Image-EliGen 等 |
| Wan 2.x (wan_video) | T2V、I2V、TI2V；首帧替换式 I2V 训练 | Wan-AI 系列权重 |
| Z-Image (z_image) | 少步蒸馏文生图 Turbo 训练与反蒸馏 LoRA | zimage-turbo |
| LTX-2 (ltx2_audio_video) | 音视频联合生成 | LTX-2 系列 |
| ACE-Step (ace_step) | 音频 / 长序列生成基座 | ACE-Step 官方权重 |
| Stable Diffusion XL | LoRA 训练基座参考实现 | stabilityai/stable-diffusion-xl-base-1.0 |

资料来源：[diffsynth/pipelines/flux2_image.py]()、[diffsynth/pipelines/qwen_image.py]()、[diffsynth/pipelines/wan_video.py]()、[diffsynth/pipelines/z_image.py]()、[diffsynth/pipelines/ltx2_audio_video.py]()、[diffsynth/pipelines/ace_step.py]()。

需要注意的是，第三方（非官方 diffusers bf16 格式）Transformer 权重需要先进行格式转换后才能被框架加载；目前仓库不原生支持 fp8 模型权重加载，仅在推理时通过动态量化方式使用 fp8。资料来源：[diffsynth/config.py]() 与社区回复 `modelscope/DiffSynth-Studio#1481`。

## 二、推理管线的统一结构

所有管线共享相同的入口范式：先构造 `PipelineConfig`（由 `diffsynth/config.py` 提供字段），再调用 `xxx.from_pretrained(...)` 加载权重，最后通过 `__call__` 或专用 `generate` 方法驱动采样。

```mermaid
flowchart LR
    A[diffsynth/config.py<br/>PipelineConfig] --> B[diffsynth/pipelines/*.py<br/>管线类]
    B --> C[diffsynth/models<br/>DiT/UNet/VAE/TextEncoder]
    B --> D[diffsynth/samplers<br/>FlowMatching/DDIM]
    B --> E[diffsynth/schedulers<br/>调度与时间步]
    B --> F[diffsynth/prompters<br/>Qwen/FLUX/Wan 专用模板]
    E --> G[采样循环]
    C --> G
    D --> G
    F --> G
```

设计上存在两类限制：第一，DDIM 调度器的时间步索引范围为 `0..999`，但流匹配损失函数采样时可能取到 `1000`，从而在 bfloat16 训练中触发数组越界。该问题来自 `diffsynth/diffusion/ddim_scheduler.py:90` 行附近，建议通过将训练 dtype 保持为 float32 或在外部脚本中进行后处理。资料来源：社区回复 `modelscope/DiffSynth-Studio#1499`。

第二，对于 FLUX.2-Klein 等非 base 模型上的步数蒸馏训练，应避免直接在已 LoRA 微调过的非 base 模型权重上再做蒸馏，否则会出现编辑结果变糊的现象；正确的做法是在原始 base 模型上重做蒸馏。资料来源：社区回复 `modelscope/DiffSynth-Studio#1468`。

## 三、训练阶段的图像质量相关机制

仓库的训练脚本（如 `examples/qwen_image/model_training/train.py` 与 `examples/wanvideo/model_training/train.py`）以 `accelerate launch` 为入口，支持 LoRA 与全量微调两种范式，并通过 `args` 对象控制是否加载 VAE、Text Encoder 等子模块。在图像质量层面，框架提供以下机制：

- 通过数据集 metadata 控制样本条件：在 metadata 中追加空 `prompt` 样本，等价于以一定概率将文本置空，从而隐式实现训练期 CFG dropout。资料来源：社区回复 `modelscope/DiffSynth-Studio#1487`。
- 通过 LoRA 维度与目标模块（`--lora_rank`、`--lora_target_modules` 等）影响细节保持能力，而非依赖外部 EMA。EMA 模型不被框架原生集成，原因在于会显著提升显存占用且指数系数被固定，因此建议在训练后用外部脚本对权重做指数平滑。资料来源：社区回复 `modelscope/DiffSynth-Studio#1463`。
- Wan 2.2 训练支持 DeepSpeed Zero-3 多卡并行，框架不提供 FSDP 支持（FSDP 需要绑定模型结构，与 DeepSpeed 功能重叠）。资料来源：社区回复 `modelscope/DiffSynth-Studio#1476`。

## 四、关于验证指标与早期停止

当前训练脚本本身不打印验证 loss 或计算 FID/CLIP-score 等参考指标，开发者若要判断过/欠拟合，需要自行组织离线评估脚本，或基于保存的 LoRA 权重在统一管线内手动对比推理结果。这是社区在 `modelscope/DiffSynth-Studio#1506` 中多次被提出的需求点。仓库提供了 `--output_dir` 与按 step 存盘的逻辑，开发者可周期性地载入不同 checkpoint 并在固定 prompt 集上做主观对比。资料来源：[examples/qwen_image/model_training/train.py]() 与 [examples/wanvideo/model_training/train.py]()。

## 五、版本与迁移提示

当前最新主线版本为 v1.1.9（v1.x.x 的最终版本）。官方公告指出，下一代版本将迁移到 v2.x.x 并引入新的框架结构，建议在新项目开始前关注 release 页与迁移指南。资料来源：Release `v1.1.9` 与 `v1.0.0`（自该版本起支持 `pip install diffsynth`）。

总结来说，DiffSynth-Studio 通过 `pipelines/*` 与 `models/*` 的模块化划分，统一了对 FLUX.2、Qwen-Image、Wan2.x、Z-Image、LTX-2、ACE-Step 等模型家族的加载和采样流程。其图像质量的保障主要依赖于管线内的数据预处理、调度器行为以及 LoRA 配置，而非框架内置的 EMA 或验证指标——这两类能力需要由开发者在外部脚本中自行补齐。

---

<a id='page-4'></a>

## 训练框架、Diffusion Templates 与社区高频问题

### 相关页面

相关主题：[项目概览与系统架构](#page-1), [核心模块与显存管理](#page-2), [支持的模型、推理管线与图像质量指标](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [diffsynth/diffusion/runner.py](https://github.com/modelscope/DiffSynth-Studio/blob/main/diffsynth/diffusion/runner.py)
- [diffsynth/diffusion/training_module.py](https://github.com/modelscope/DiffSynth-Studio/blob/main/diffsynth/diffusion/training_module.py)
- [diffsynth/diffusion/flow_match.py](https://github.com/modelscope/DiffSynth-Studio/blob/main/diffsynth/diffusion/flow_match.py)
- [diffsynth/diffusion/ddim_scheduler.py](https://github.com/modelscope/DiffSynth-Studio/blob/main/diffsynth/diffusion/ddim_scheduler.py)
- [diffsynth/diffusion/dmd2.py](https://github.com/modelscope/DiffSynth-Studio/blob/main/diffsynth/diffusion/dmd2.py)
- [diffsynth/diffusion/template.py](https://github.com/modelscope/DiffSynth-Studio/blob/main/diffsynth/diffusion/template.py)
- [examples/qwen_image/model_training/train.py](https://github.com/modelscope/DiffSynth-Studio/blob/main/examples/qwen_image/model_training/train.py)
- [examples/stable_diffusion_xl/model_training/train.py](https://github.com/modelscope/DiffSynth-Studio/blob/main/examples/stable_diffusion_xl/model_training/train.py)
</details>

# 训练框架、Diffusion Templates 与社区高频问题

本页聚焦 `diffsynth/diffusion/` 目录下的训练核心代码以及上层 `examples/*/model_training/train.py` 示例脚本，结合社区高频问题，对训练框架的设计、模板（Templates）抽象以及常见使用陷阱做一次系统性梳理。

## 框架角色与组成

`DiffSynth-Studio` 的训练栈沿"调度循环 → 训练模块 → 损失/采样"分层：

| 层 | 主要文件 | 角色 |
|---|---|---|
| 调度循环 | `diffsynth/diffusion/runner.py` | 负责 epoch / step 推进、日志、checkpoint、accelerate 集成 |
| 模型封装 | `diffsynth/diffusion/training_module.py` | 把 Pipeline 拆成可训练模块，挂载 LoRA 等适配器 |
| 损失函数 | `diffsynth/diffusion/flow_match.py`、`diffsynth/diffusion/dmd2.py` | 流匹配目标、Distribution Matching Distillation 蒸馏目标 |
| 采样器 | `diffsynth/diffusion/ddim_scheduler.py` | 推理/训练共享的 DDIM 时间步调度 |

`Runner` 在 `init_models`、`init_lora` 阶段加载底模与适配器，并在每个 step 中调用 `TrainingModule.forward_backward` 完成前向与梯度回传。资料来源：[diffsynth/diffusion/runner.py:1-120]()。

`TrainingModule` 是 Pipeline 的轻量代理：它持有原始 `Pipe` 的子模块引用，仅对带有 LoRA 标记的参数计算梯度，从而把显存占用控制在可控范围。资料来源：[diffsynth/diffusion/training_module.py:1-80]()。

## Diffusion Templates 与损失族

### Flow Matching 模板

`template.py` 把"采样起点、目标点、噪声调度"封装为可复用的 Template，主流模型（包括 Wan 2.2、Qwen-Image、Z-Image、FLUX.2）均通过同一套 Template 描述训练时的潜变量构造方式。资料来源：[diffsynth/diffusion/template.py:1-160]()。

`flow_match.py` 实现流匹配损失：在线性插值空间 `(1-t)·x0 + t·x1` 上对网络预测的速度 `v` 计算 MSE，时间步 `t` 通常在 `[0, 1000)`。资料来源：[diffsynth/diffusion/flow_match.py:40-110]()。

### DDIM 共享与潜在越界

`ddim_scheduler.py` 同时被训练与推理调用；当损失端采样到 `t=1000` 而 `sigmas` 数组长度为 `1000` 时会触发"数组越界"。社区在 issue #1499 中复现了 bf16 训练下的该问题，建议在该文件的 `__call__` 处对 `t` 做 `min(t, len(sigmas)-1)` 夹紧。资料来源：[diffsynth/diffusion/ddim_scheduler.py:80-100]()。

### DMD2 蒸馏路径

`dmd2.py` 提供"分布匹配蒸馏"实现，可与 base 模型 + LoRA 链路叠加使用，但官方在 issue #1468 中明确：**对非 base 模型直接蒸馏会导致编辑图变模糊**，正确的做法是先回到 base 模型重新蒸馏。

## examples/ 训练脚本

每个模型仓库的入口脚本结构相似，以 `examples/qwen_image/model_training/train.py` 为例：通过命令行参数指定 `dataset_base_path`、`dataset_metadata_path`、`dataset_repeats`，再由 `accelerate launch` 启动 `Runner`。资料来源：[examples/qwen_image/model_training/train.py:1-60]()。

`examples/stable_diffusion_xl/model_training/train.py` 则展示了将 `torch.dtype=torch.float32` 切换到 `torch.bfloat16` 时进入低精度训练的最简路径——这正是触发 #1499 数组越界问题的最小复现脚本。资料来源：[examples/stable_diffusion_xl/model_training/train.py:30-35]()。

## 社区高频问题速查

| 问题 | Issue | 当前框架行为 | 缓解方案 |
|---|---|---|---|
| EMA 模型支持 | #1463 | 不内置，会额外占显存 | 训练后用外部脚本滑动平均 |
| bfloat16 数组越界 | #1499 | DDIM `t` 取到 `1000` | `min(t, len(sigmas)-1)` 或保持 fp32 |
| CFG 文本置空 | #1487 | 无内置概率参数 | 在 metadata 中插入空 prompt 样本 |
| Wan2.2 FSDP | #1476 | 暂不支持 FSDP | 使用 DeepSpeed ZeRO-3 |
| FLUX.2 第三方 DiT | #1481 | 仅注册官方权重 | 转换为官方 diffusers bf16 格式 |
| Wan2.2 TI2V 首帧色差 | #1195/#1402 | 持续存在的已知问题 | 暂无稳定 workaround，待框架 v2 |
| 加速度蒸馏后变糊 | #1468 | 非 base 模型二次蒸馏不推荐 | 训练完成后再蒸馏，或等待官方蒸馏脚本 |
| Image-to-LoRA 图生图风格 | #1510 | t2i 训练，可勉强 i2i | 不保证端到端效果 |

> 关于评估指标：issue #1506 指出训练脚本目前没有 validation loss/metrics。如需判断过/欠拟合，推荐在自有脚本中以相同 Template 周期性跑一个固定评估集，参考 `diffsynth/prompts/` 下的提示词组织方式即可。

## 小结

`Runner` + `TrainingModule` + `Template` 三件套构成了框架的训练主干，`flow_match.py` 与 `dmd2.py` 分别覆盖 SFT 与蒸馏两大常见目标。社区中大部分高频问题（EMA、CFG、空越界、FSDP、第三方权重）属于"框架能力边界"问题，官方建议是在 v2 框架重构前用外部脚本或保持 base 模型路径绕过。

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：modelscope/DiffSynth-Studio

摘要：发现 9 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安全/权限坑 - 来源证据：Inquiry regarding Full Training speed and First-frame color shift on Wan2.2 TI2V 5B。

## 1. 安全/权限坑 · 来源证据：Inquiry regarding Full Training speed and First-frame color shift on Wan2.2 TI2V 5B

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Inquiry regarding Full Training speed and First-frame color shift on Wan2.2 TI2V 5B
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/modelscope/DiffSynth-Studio/issues/1195 | 来源类型 github_issue 暴露的待验证使用条件。

## 2. 身份坑 · 仓库名和安装名不一致

- 严重度：medium
- 证据强度：runtime_trace
- 发现：仓库名 `diffsynth-studio` 与安装入口 `DiffSynth` 不完全一致。
- 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。
- 复现命令：`pip install DiffSynth`
- 证据：identity.distribution | https://github.com/modelscope/DiffSynth-Studio | repo=diffsynth-studio; install=DiffSynth

## 3. 安装坑 · 来源证据：训练异常

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：训练异常
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/modelscope/DiffSynth-Studio/issues/1494 | 来源类型 github_issue 暴露的待验证使用条件。

## 4. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://github.com/modelscope/DiffSynth-Studio | README/documentation is current enough for a first validation pass.

## 5. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://github.com/modelscope/DiffSynth-Studio | last_activity_observed missing

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://github.com/modelscope/DiffSynth-Studio | no_demo; severity=medium

## 7. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://github.com/modelscope/DiffSynth-Studio | no_demo; severity=medium

## 8. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://github.com/modelscope/DiffSynth-Studio | issue_or_pr_quality=unknown

## 9. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://github.com/modelscope/DiffSynth-Studio | release_recency=unknown

<!-- canonical_name: modelscope/DiffSynth-Studio; human_manual_source: deepwiki_human_wiki -->