Skip to content

diffsynth.md

Latest commit

 

History

History
348 lines (257 loc) · 18.2 KB

diffsynth.md

File metadata and controls

348 lines (257 loc) · 18.2 KB
Raw

Qwen-Image-2.1 LoRA 训练入门

这篇教程教你在 Next Trainer 中，从安装引擎开始，训练一个 Qwen-Image-2.1 LoRA。 LoRA 是训练后得到的小模型文件，需要搭配原来的 Qwen-Image-2.1 大模型使用，不能单独出图。

当前 main 版本支持单卡 BF16 文生图 LoRA 和 Edit 图像编辑 LoRA，不支持量化模型训练、全量微调或多卡训练。 本文第 1–10 节以文生图为例；图像编辑的数据和预览设置见第 11 节。 不用修改引擎源码，也不用自己写训练脚本。

1. 先确认准备条件

  • 使用支持 BF16 的 NVIDIA 显卡，并安装可用的显卡驱动。本教程不是 AMD 或 Intel 显卡教程。
  • 安装过程需要联网下载独立的 Python 和训练依赖；模型权重需要另外准备。
  • 安装器需要 Git 和 uv。若日志提示找不到它们，请先按训练器安装说明补齐，再重试。
  • 为模型、转换副本、训练缓存和输出文件留出磁盘空间，不要只预留原模型文件的大小。
  • CPU 卸载会使用系统内存；显存不足不能只靠开关解决，也需要足够的内存与磁盘空间。

显存怎么选？

以下文生图实测记录使用 RTX 4090 24GB 的低分辨率短训，不是 1024 分辨率长训或 Edit 训练保证。 实测使用 256×256、Batch 1、Rank 4、AdamW8bit、预编码缓存，完成训练中出图及 LoRA 保存， 并通过独立 ComfyUI 加载和出图检查。CPU 卸载开启与关闭都分别测过。

你的情况 建议
24GB 显存，第一次使用 先按本文的低分辨率试跑配置确认流程，再逐步提高分辨率和 Rank
高于 24GB 显存 仍建议先试跑；显存更大不代表任意图片尺寸、Batch 和预览配置都能运行
低于 24GB 显存 尚无本项目的实机验收保证；可尝试缓存、CPU 卸载与低分辨率，但不承诺跑通

这些是试跑建议，不是最低硬件门槛或训练质量推荐。实测范围见验收记录。

2. 安装 DiffSynth 引擎

  1. 打开训练器，进入 设置 → 训练引擎。
  2. 找到 DiffSynth-Studio，点击安装。
  3. 等待下载、安装和环境检查完成。过程中可以查看安装日志，不要提前关闭训练器。
  4. 确认引擎显示为就绪，再进入训练页面。

已经显示就绪就不用重复安装。DiffSynth 使用自己的环境，不需要往 Kohya 或其他引擎里安装依赖。 安装引擎不会替你下载下面的训练模型权重。

若显示“环境异常”，先看具体错误。如果之前已经装好，只是在移动目录或修改依赖后出现异常， 先保留日志并反馈，不要急着卸载。修复操作可能重新安装环境。

3. 在训练页选对三个选项

进入训练页面，依次选择：

选项 选择什么
模型 Qwen-Image-2.1
训练引擎 DiffSynth-Studio
训练目标 LoRA

后面的参数会随选择变化。不要在其他模型或其他引擎的页面填写本教程的参数。

4. 选择训练模型文件

方式一：已有 ComfyUI 模型文件

在“训练用模型”中，把模型输入方式 model_input_mode 切换成 comfyui_files（ComfyUI 文件）。 分别选择这三个文件。它们可以放在不同目录，不必手动合并或改名。

页面字段 要选择的文件 通俗理解
dit_path qwen_image_2.1_bf16.safetensors 主要负责生成图片的模型
text_encoder_path qwen3vl_8b_bf16.safetensors 负责理解提示词的模型
vae_path qwen_image_2.1_vae_bf16.safetensors 负责图片编码和解码的模型

模型来源：Comfy-Org / Qwen-Image-2.1。 在仓库文件列表中查找对应的 diffusion_models、text_encoders 和 vae 目录。 本版选择 BF16 文件，不要换成 FP8、GGUF 或其他量化版本。 这里填写的是运行训练服务的机器上已经下载好的文件路径，不是网页地址。 如果通过浏览器访问远程训练器，应选择服务器上的文件，而不是浏览器所在电脑的文件。

例如主模型下载在 D:\models\qwen_image_2.1_bf16.safetensors， 就在 dit_path 选择这个文件，不要只选混放很多模型的 D:\models 文件夹。

如果模型由多个分片组成，把分片和对应索引保存在一起，选择索引文件或只包含这一套模型的目录即可； 不用逐个填写分片，也不要只下载其中一个分片。

方式二：已有完整模型目录

把模型输入方式保持为 model_repository（模型仓库目录）， 选择里面包含 transformer、text_encoder、vae 子目录的 BF16 模型根目录。 不是所有名字相同的模型仓库都满足本版格式要求，F32 或量化权重不能当作 BF16 直接使用。 不确定自己下载的是哪种格式时，按上面的分组件方式准备文件更直观。

Processor 不需要手动填写。 它是配套的文本和图片处理配置，开始训练时会自动检查本地缓存， 仅在文件缺失或损坏时联网下载；缓存完整时直接复用。下载失败时看训练日志中的具体原因。

5. 准备训练图片和说明文字

新手选择 image_text（图片 + TXT），不用制作表格。 每张图片旁边放一个同名 TXT 文件，在 TXT 中写这张图片的描述，建议保存为 UTF-8 编码。

D:\train\my-qwen-lora\
  001.jpg
  001.txt
  002.png
  002.txt

例如 001.txt 可以写：

A woman wearing a yellow kimono, smiling, upper body, plain background.

描述应与实际图片相符，不要把同一段示例文字不加区分地用于所有图片。 确保 TXT 真正叫 001.txt，不是 Windows 隐藏扩展名后产生的 001.txt.txt。 缺少 TXT 会报错；空 TXT 可以读取，但表示这张图片没有文字描述。

在页面“数据集设置”中填写：

字段 第一次怎么填
dataset_format image_text
train_data_dir 选择 D:\train\my-qwen-lora 这个目录
dataset_repeat 先填 1

也兼容 Kohya 常见的重复次数子目录：

D:\train\my-qwen-lora\
  3_character\
    001.jpg
    001.txt
  1_style\
    002.jpg
    002.txt

选择最外层 my-qwen-lora。第一层子目录名中的数字表示重复次数： 上例中第一组每轮重复 3 次，第二组重复 1 次；还会乘页面的全局 dataset_repeat。 普通子目录和根目录的图片也会读取。重复次数会增加训练量，不会生成新的图片文件。

metadata 是给已经准备好 CSV / JSON / JSONL 数据的用户使用的，不必为了训练改用它。 这种方式需要 image、prompt 字段，不按子目录名字计算重复次数。

6. 第一次先用小配置跑通

下面是检查安装、数据、保存和预览是否正常的试跑配置，不是正式训练的最佳参数。 建议先准备少量图片，完成一次试跑后，再决定正式训练的分辨率与训练量。 其中低分辨率、Rank 4 等值需要手动修改，不是页面默认值。

图片尺寸与保存

字段 试跑填写 作用
resolution 256,256 基准分辨率，使用英文逗号；宽高必须是 64 的倍数
enable_bucket 开启 把接近宽高比的图片分组，减少不必要的裁剪
其他分桶参数 先保持默认 不需要为第一次试跑逐项调整
output_dir 选择一个有剩余空间的目录 保存 LoRA 和预览图
output_name my-qwen-test 给本次训练起名字
save_steps 留空 每轮保存；也可以填正整数，按更新步数保存

256 分辨率只是为了试跑省资源，不能据此判断正式训练效果。 跑通后可以逐级尝试更高分辨率；不要一次同时提高分辨率、Batch 和 Rank，否则难以判断哪里导致显存不足。 分桶开启时实际图片尺寸不一定全是填写的宽高。

训练参数

字段 试跑填写 作用
num_epochs 1 完整学习一次数据集
learning_rate 1e-4 每次更新的学习幅度，先不调整
lr_scheduler constant 保持学习率恒定
lr_warmup_steps 0 试跑不预热
optimizer_type AdamW8bit 使用较省显存的优化器状态
train_batch_size 1 一次处理一张图片
gradient_accumulation_steps 1 每个 Batch 更新一次
lora_rank 4 低 Rank 试跑；不是正式训练质量推荐
lora_alpha 留空 自动与 Rank 相同
lora_target_modules 留空 由引擎选择训练层
lora_checkpoint 留空 第一次训练不加载已有 LoRA

轮数和步数不是同一个东西。例如 10 张图片、重复 1 次、Batch 1、梯度累积 1， 一轮是 10 次更新；5 轮就是 50 次更新。启用不同子目录重复次数、分桶、较大 Batch 或梯度累积后， 计算会变化，以任务显示的实际总步数为准。

显存设置

字段 首次试跑建议 代价或注意事项
cache_embeddings 开启 先处理并缓存文本、图片，再卸载编码器；首次准备较慢，占用磁盘
use_gradient_checkpointing 保持开启 用额外计算换取显存节省
initialize_model_on_cpu 保持开启 降低加载时的显存峰值，会使用系统内存
enable_model_cpu_offload 显存紧张时开启 在 CPU 与 GPU 间搬运权重，会变慢并使用系统内存
use_gradient_checkpointing_offload 先保持关闭 进一步省显存的选项，必要时单独尝试

CPU 模型卸载和训练预览同时开启时，必须开启 cache_embeddings。 文生图 Batch 大于 1 也必须开启这个缓存；Edit 当前要求 Batch 为 1。 缓存不是把模型改为低精度，训练仍是本版支持的 BF16 路线。

7. 设置训练中预览图

想在训练过程中看出图效果，在“预览设置”开启 sample_enabled。 默认只有一组样例，需要比较多个提示词时再添加。

短训可以把 sample_every_n_steps 改为 2，这样在第 2、4……次更新后出图。 正式训练再按需要增大间隔，频繁出图会明显增加耗时。 如果总共只跑 5 步却设为每 100 步预览，这次就不会触发步数预览。

sample_every_n_epochs 先留空。如果填写它，就改成每 N 轮结束后出图，不再同时按步数出图。

每个样例可以单独设置：

选项 试跑示例
Prompt / 提示词 A woman wearing a yellow kimono, smiling, upper body, plain background.
宽度 / 高度 256 / 256
Seed / 随机种子 42，固定种子方便对比变化
CFG / 引导强度 4
采样步数 20

这里的尺寸只影响预览，不会改变训练分辨率。 训练能跑不代表更大预览图一定能生成，预览也需要显存。新手先让两者保持相同的小尺寸。 文生图预览不需要参考图；Edit 预览每组必须指定至少一张参考图，见第 11 节。

8. 开始训练后，看什么？

检查模型路径、数据目录和保存目录后，提交训练，并进入任务页面查看日志。 第一次启动不一定马上显示训练步数，前面还可能有：

  1. 检查和下载 Processor 配置。
  2. 转换 ComfyUI 格式的模型文件，生成适配引擎的缓存副本。
  3. 读取图片和文字，生成预编码缓存。
  4. 加载训练模型，开始更新步数。

这些准备阶段可能较慢。只要日志仍在推进，不要因为还没出现 Loss 就反复提交任务。 格式转换不会覆盖原模型，但会额外占用磁盘。后续相同输入可以复用有效缓存。 模型或数据变化后，部分缓存需要重新生成。

训练中会看到步数和 Loss（误差指标）。预览时训练暂时进入采样阶段，出图完成后继续训练。 短训只用来检查流程，不代表 LoRA 已经学会目标内容，也不要只凭某一次 Loss 判断训练质量。

9. 去哪里找 LoRA？怎么放进 ComfyUI？

输出保存在：

你选择的 output_dir/
  你填写的 output_name/
    本次运行编号/
      ...LoRA 权重文件...
      sample/
      engine_config.json
      training_args.json

在这次运行目录中找到保存的 LoRA .safetensors 文件。sample 目录是训练预览图， 不是 LoRA 模型；JSON 是配置记录，也不是模型。

  1. 使用已支持 Qwen-Image-2.1 的 ComfyUI，并先确认原模型工作流能够正常出图。
  2. 将训练得到的 LoRA 放入 ComfyUI 的 models/loras 目录。
  3. 在对应的 Qwen-Image-2.1 工作流中，用内置 Load LoRA Model Only 或 Load LoRA 节点加载。
  4. 本版训练的是图像生成模型部分，不会生成 CLIP LoRA。

本训练器的适配层已经处理输出格式，不需要你再手动转换一次。 不要把这里的输出规则直接套用于其他工具直接运行 DiffSynth 得到的文件。

需要基于已有 LoRA 再训练时，在 lora_checkpoint 中选择权重即可。 但这不是精确的断点恢复：优化器和学习率调度会重新开始，不会恢复到上次停止时的全部状态。

10. 常见问题

提示 CUDA out of memory / 显存不足

先关闭其他占用显卡的程序，再按顺序检查：

  1. Batch 是否为 1，预编码缓存和梯度检查点是否开启。
  2. 降低训练分辨率，预览图尺寸也一起降低。
  3. 尝试开启 enable_model_cpu_offload，同时确认系统内存足够。
  4. 用低 Rank 试跑，暂时关闭预览，判断是训练还是出图阶段超出显存。

如果只在预览时失败，优先检查预览分辨率，不要只改训练分辨率。 这些措施不能保证所有显卡都能训练这个 BF16 模型。

第一次特别慢，或磁盘空间突然减少

通常涉及模型转换和编码缓存。检查日志正在做哪一步，并确认剩余空间。 转换缓存位于 extensions/diffsynth/cache/models/， 编码缓存位于 extensions/diffsynth/cache/encodings/。不要在任务运行时删除缓存。

提示找不到模型、缺少分片或格式不支持

检查是否选中了实际文件、三个组件是否对应本教程列出的 BF16 版本。 分片模型要下载完整，不能只有索引或其中一个分片。不要把网页地址填进本地路径框。

提示缺少 TXT

检查图片旁边是否有同名 TXT，以及扩展名是否正确。 例如 photo.png 对应 photo.txt，不是 photo.png.txt。

训练了，但没有预览图

确认预览开关已打开，预览间隔没有超过实际训练量。 再检查是否填写了“每 N 轮预览”，覆盖了按步数预览的设置。 预览报错会让任务失败，请看日志，不要把失败当成只是少了一张图。

安装或 Processor 下载失败

先看日志中的网络、下载源、磁盘空间或权限错误。不要把其他引擎的 Python 环境复制过来。 向维护者反馈时，附上显卡型号、显存容量、训练器版本、相关配置和报错日志； 不要公开令牌、密码等敏感信息。

11. Edit 图像编辑训练

在 Qwen-Image-2.1 训练页点击 Edit 图像编辑，模型路径和其他训练参数继续复用。 点击 文生图 T2I 可切回；自动草稿、导入导出、任务重新编辑均保存 training_task。 切回 T2I 时提交参数自动清空预览参考图，草稿仍保留，切回 Edit 可继续使用。 两种模式共用同一套 Qwen-Image-2.1 模型及 ComfyUI LoRA 导出逻辑。

  • 图片 + TXT：训练目录放编辑后的目标图，同名 TXT 写编辑指令。另选一个或多个 参考图目录，按相对目录及文件主名配对，扩展名可以不同。例：目标 targets/3_character/001.png 对应 refs/3_character/001.jpg。 两个目录必须互不包含；缺失或同名多候选在提交时明确报错。重复次数沿用原规则。
  • 元数据：保留 image（目标图）、prompt（指令），增加 edit_image，支持单个路径 或有序路径数组。JSON 文件的顶层必须是记录数组，例如： [{"image":"target.png","prompt":"把衣服改成蓝色","edit_image":["source.png"]}]。 JSONL 文件则每行一个记录对象，不加外围数组，例如： {"image":"target.png","prompt":"把衣服改成蓝色","edit_image":["source.png"]}。 CSV 多图单元格填写 JSON 数组，按标准 CSV 引号规则转义。相对路径以数据集根目录为基准。 适配器会生成规范化副本，不修改原元数据。
  • Edit 当前真实 train_batch_size 必须为 1；可增加 gradient_accumulation_steps。 现有文生图 batch 的共享位置掩码不能直接用于不同参考图，提交时拒绝 Edit batch > 1。
  • 支持多参考图、预编码缓存、梯度检查点、CPU 卸载和带参考图的训练预览。 与文生图一样，CPU 卸载与预览同时开启需要预编码缓存。
  • 目标图沿用分桶；参考图通过上游默认图像操作器后，由上游 Edit 单元按目标面积缩放。 预编码文本特征包含参考图视觉信息，VAE 缓存同时包含目标图及参考图 latent。 缓存键包含参考图顺序、路径、大小、修改时间及尺寸处理参数；预览正负提示词也分别结合参考图编码。

底层传入官方 data_file_keys=image,edit_image、extra_inputs=edit_image， 继续使用固定上游训练模块和损失函数。提交前检查参考图经过数据加载器及按目标桶面积 再次缩放后的尺寸；任一边归零时拒绝提交，并提示对应图片和目标尺寸。 预览参考图按各样例的预览尺寸单独检查。

切换源码分支后，若 GUI 缺少 Edit 按钮，先在 frontend/ 使用 Node 22 执行 npm run build 并刷新页面；后端托管的 frontend/dist/ 可能仍是旧分支构建。

2026-09-28 已在 RTX 4090 24GB 上完成 Edit LoRA 全流程实测：48/48 步训练完成并成功生成训练预览图。 当前实测覆盖单参考图流程；多参考图仍有自动化覆盖，但尚未完成同等规模的真机验收。

开发者资料：适配层技术说明 · 实机验收记录。