企业官网建设流程全解析

DiffSynth-Studio 训练阶段 FP8 精度启用指南：--fp8_models原理、配置与 Qwen-Image LoRA 实战

【免费下载链接】DiffSynth-StudioEnjoy the magic of Diffusion models!项目地址: https://gitcode.com/GitHub_Trending/dif/DiffSynth-Studio

本篇技术指南围绕 DiffSynth-Studio 在训练阶段启用 FP8 精度这一核心主题展开，讲解为什么训练场景下 FP8 是唯一适合的显存管理策略、FP8 在训练中的真实定位（存储精度而非计算精度）、--fp8_models参数的完整配置方式，以及基于 Qwen-Image LoRA 训练的完整可运行示例。读完本文，你将掌握在 DiffSynth-Studio 训练框架中为不参与梯度更新的模型启用 FP8 存储、显著降低显存占用的实战方法，并能从源码层面理解其底层实现原理。

为什么训练阶段只有 FP8 可用

DiffSynth-Studio 在模型推理阶段支持多种显存（VRAM）管理技术，具体可参考 VRAM 管理文档。然而，这些技术中的大多数并不适合训练场景：

• Offloading（卸载）：将参数临时卸载到 CPU 或磁盘，推理时按需加载。在训练中，每个 step 都需要对参数进行前向、反向传播和优化器更新，频繁的卸载与加载会造成极其缓慢的训练过程，几乎不具备实用价值；
• Gradient Checkpointing（梯度检查点）：本质上是以重计算换取激活值显存，与参数显存管理是不同维度，无法单独覆盖模型参数本身的占用。

因此，FP8 精度是训练过程中唯一可以启用的显存管理策略：它通过把模型的存储精度降低到 FP8（每参数 1 字节，而 BF16 为 2 字节），在几乎不牺牲训练速度的前提下，将模型参数的显存占用压缩约一半。

FP8 训练的真实定位：存储精度，而非原生 FP8 计算

需要明确的是，DiffSynth-Studio 训练框架目前不支持原生 FP8 精度训练（native FP8 precision training）。原因为何，可参见 QA 文档中的解释，主要有两点：

1. 精度溢出的工程挑战：原生 FP8 训练的核心难题是梯度爆炸引起的精度溢出。为保证训练稳定性，需要据此重新设计模型结构，但目前没有模型开发者愿意这样做；
2. 硬件与推理兼容性问题：使用原生 FP8 训练的模型，在没有 Hopper 架构 GPU 的情况下推理时只能以 BF16 精度计算，理论上生成质量反而劣于直接 FP8 存储的方案。

因此，本框架在训练中使用的 FP8 指的是：把模型的参数以 FP8 精度存储在显存/内存中，在真正需要计算时再临时转换回其他精度。也就是说，FP8 在这里只降低显存占用，不带来任何计算加速（这一点与推理场景下 FP8 量化"无加速效果"的结论一致，参见 QA 文档）。

从源码实现可以印证这一点。training_module.py 中的parse_vram_config在启用 FP8 时返回的配置为：

{ "offload_dtype": torch.float8_e4m3fn, # 卸载状态下的存储精度 "offload_device": device, "onload_dtype": torch.float8_e4m3fn, # 常驻显存时的存储精度 "onload_device": device, "preparing_dtype": torch.float8_e4m3fn, # 准备计算前的驻留精度 "preparing_device": device, "computation_dtype": torch.bfloat16, # 真正参与计算的精度 "computation_device": device, }

可以看到，模型在offload / onload / preparing三个阶段都以torch.float8_e4m3fn（FP8 E4M3 格式）存储，而只有在computation阶段才转换为torch.bfloat16参与实际运算，torch.float8_e4m3fnuz同样被支持（见 layers.py 中对enable_fp8的判断）。

FP8 存储的前向计算细节

当模型层处于 FP8 管理模式时，其线性层前向计算由 layers.py 中的fp8_linear完成，核心流程为：

1. 计算输入张量每个样本的绝对最大值x_max，并据此推导缩放因子scale_a；
2. 将输入与权重均转换为computation_dtype（即 FP8）；
3. 调用torch._scaled_mm执行带缩放因子的矩阵乘法，输出结果再恢复为原始输入精度origin_dtype。

这一设计通过逐样本缩放缓解 FP8 动态范围有限带来的精度损失，同时保证训练反向传播在 BF16 计算图下进行。从状态管理上看，layers.py 中维护了offload → onload → preparing → computation四态状态机，在forward时按需将 FP8 权重临时提升到 BF16 参与计算，这就是训练阶段 FP8 显存管理的完整闭环。

适用范围：不支持梯度更新的模型

请特别注意：FP8 显存管理策略不支持梯度更新。当某个模型被设置为可训练（trainable）时，无法为该模型启用 FP8。因此，支持 FP8 的模型只有两类：

从 training_module.py 中parse_model_configs的实现可以看到，--fp8_models与--offload_models的处理逻辑完全一致：都是按模型路径或model_id/origin_file_pattern字符串进行匹配，命中则将该模型对应的ModelConfig加上 FP8 的 VRAM 配置。这一机制完全复用了推理阶段的显存管理代码，训练框架本身并没有为 FP8 编写独立的显存调度逻辑。

关于质量损失的说明：实验验证表明，启用 FP8 的 LoRA 训练不会造成明显的图像质量下降，但理论误差确实存在。如果在使用该功能时遇到训练结果劣于 BF16 精度训练的情况，建议通过 GitHub Issues 反馈。

实战：Qwen-Image LoRA 的 FP8 训练

DiffSynth-Studio 为 Qwen-Image LoRA 训练提供了开箱即用的 FP8 训练脚本，位于 examples/qwen_image/model_training/special/fp8_training/Qwen-Image-LoRA.sh。其完整内容如下：

modelscope download --dataset DiffSynth-Studio/diffsynth_example_dataset --include "qwen_image/Qwen-Image/*" --local_dir ./data/diffsynth_example_dataset accelerate launch examples/qwen_image/model_training/train.py \ --dataset_base_path data/diffsynth_example_dataset/qwen_image/Qwen-Image \ --dataset_metadata_path data/diffsynth_example_dataset/qwen_image/Qwen-Image/metadata.csv \ --max_pixels 1048576 \ --dataset_repeat 50 \ --model_id_with_origin_paths "Qwen/Qwen-Image:transformer/diffusion_pytorch_model*.safetensors,Qwen/Qwen-Image:text_encoder/model*.safetensors,Qwen/Qwen-Image:vae/diffusion_pytorch_model.safetensors" \ --learning_rate 1e-4 \ --num_epochs 5 \ --remove_prefix_in_ckpt "pipe.dit." \ --output_path "./models/train/Qwen-Image_lora_fp8" \ --lora_base_model "dit" \ --lora_target_modules "to_q,to_k,to_v,add_q_proj,add_k_proj,add_v_proj,to_out.0,to_add_out,img_mlp.net.2,img_mod.1,txt_mlp.net.2,txt_mod.1" \ --lora_rank 32 \ --use_gradient_checkpointing \ --dataset_num_workers 8 \ --find_unused_parameters \ --fp8_models "Qwen/Qwen-Image:transformer/diffusion_pytorch_model*.safetensors,Qwen/Qwen-Image:text_encoder/model*.safetensors,Qwen/Qwen-Image:vae/diffusion_pytorch_model.safetensors"

该脚本的核心参数解读如下：

• --model_id_with_origin_paths：以模型ID:文件通配符的形式声明要加载的三个子模型（DiT、文本编码器、VAE）。Qwen/Qwen-Image对应模型仓库 ID，transformer/diffusion_pytorch_model*.safetensors等为仓库内的文件匹配模式，多个模型以逗号分隔；
• --fp8_models：本文核心参数，其取值与--model_id_with_origin_paths逐项一一对应。这里将 DiT、文本编码器、VAE 三个模型全部列入 FP8 名单。由于这是 LoRA 训练（--lora_base_model "dit"），DiT 的参数被冻结、仅 LoRA 分支可训练，文本编码器和 VAE 参数完全冻结，因此三者全部符合 FP8 的适用条件；
• --lora_base_model "dit"与--lora_target_modules：指定在 DiT 的注意力与 MLP 子模块上注入 LoRA 适配器，--lora_rank 32设置 LoRA 秩；
• --remove_prefix_in_ckpt "pipe.dit."：导出 checkpoint 时移除pipe.dit.前缀，便于后续推理时直接作为 LoRA 权重加载；
• --use_gradient_checkpointing：与 FP8 叠加使用，进一步降低激活值显存占用；
• --find_unused_parameters：LoRA 训练中文本编码器等冻结模型不参与反向传播，该参数避免 DDP/Accelerate 报"存在未使用参数"错误。

关于参数解析链路：train.py 在QwenImageTrainingModule初始化时调用self.parse_model_configs(model_paths, model_id_with_origin_paths, fp8_models=fp8_models, ...)，其中fp8_models直接来自命令行参数args.fp8_models（见 train.py），最终为命中的模型构造带 FP8 VRAM 配置的ModelConfig并交给QwenImagePipeline.from_pretrained加载。

训练结果验证

训练完成后，可以使用官方提供的验证脚本 examples/qwen_image/model_training/special/fp8_training/validate.py 检查训练效果：

from diffsynth.pipelines.qwen_image import QwenImagePipeline, ModelConfig import torch pipe = QwenImagePipeline.from_pretrained( torch_dtype=torch.bfloat16, device="cuda", model_configs=[ ModelConfig(model_id="Qwen/Qwen-Image", origin_file_pattern="transformer/diffusion_pytorch_model*.safetensors"), ModelConfig(model_id="Qwen/Qwen-Image", origin_file_pattern="text_encoder/model*.safetensors"), ModelConfig(model_id="Qwen/Qwen-Image", origin_file_pattern="vae/diffusion_pytorch_model.safetensors"), ], tokenizer_config=ModelConfig(model_id="Qwen/Qwen-Image", origin_file_pattern="tokenizer/"), ) pipe.load_lora(pipe.dit, "models/train/Qwen-Image_lora_fp8/epoch-4.safetensors") prompt = "a dog" image = pipe(prompt, seed=0) image.save("image.jpg")

该脚本以 BF16 精度加载 Qwen-Image 的三个子模型与分词器，加载训练产出的 LoRA 权重（默认使用第 5 个 epoch 结束时的epoch-4.safetensors），然后以固定随机种子seed=0生成图像并保存。注意：FP8 仅在训练阶段用于节省显存，推理验证仍使用 BF16，这正好印证了前文"FP8 是存储精度、计算恢复为 BF16"的设计。

训练框架设计概念

DiffSynth-Studio 的训练框架完全复用了推理阶段的显存管理机制，二者共用ModelConfig与底层的 VRAM 管理模块。在训练过程中，DiffusionTrainingModule.parse_model_configs负责解析显存管理配置（见 training_module.py），其核心职责包括：

1. 将--fp8_models按逗号拆分为名单；
2. 遍历--model_paths（本地文件路径）与--model_id_with_origin_paths（模型仓库 ID 列表），逐一判断是否命中 FP8/Offload 名单；
3. 为命中的模型生成携带 FP8（或 Offload）dtype/device 配置的ModelConfig；
4. 量化配置（--quant_options）也在同一入口解析，但会额外校验后端是否声明is_differentiable=True，因为冻结层必须把梯度透传给 LoRA 分支（见 training_module.py）。

由于这一设计，训练脚本与推理脚本在模型加载层面保持高度一致，降低了维护成本，也使得 FP8 显存管理能够直接继承推理阶段成熟的offload / onload / preparing / computation状态机实现。

边界条件与扩展

使用 FP8 训练时请注意以下边界与配套方案：

• 不适用于全量微调（Full SFT）：全量微调中所有模型参数都参与梯度更新，不满足 FP8 的适用条件，此时只能依赖 Gradient Checkpointing、DeepSpeed、两阶段拆分训练、CPU Offload 等低显存训练方案；
• 与 LoRA 训练天然契合：LoRA 训练中基底模型被冻结，正是 FP8 的理想场景；DiffSynth-Studio 还为差分 LoRA、低显存训练、拆分训练等场景提供了配套脚本，见 examples/qwen_image/model_training/special 下的differential_training、low_vram_training、split_training等目录；
• 误差是理论存在的：FP8 存储相对 BF16 存在精度损失，实验虽表明不明显影响 LoRA 训练质量，但若遇到生成质量下降，应优先考虑回退到 BF16 训练进行对比，并通过 GitHub Issues 反馈。

【免费下载链接】DiffSynth-StudioEnjoy the magic of Diffusion models!项目地址: https://gitcode.com/GitHub_Trending/dif/DiffSynth-Studio