尧图网站建设 
深度学习计算机视觉媒体生成模型训练微调【免费下载链接】sd-scripts项目地址https://gitcode.com/gh_mirrors/sd/sd-scripts点击查看免费下载本文是 sd-scripts 仓库中 docs/hunyuan_image_train_network.md 的完整技术展开系统讲解如何使用hunyuan_image_train_network.py对腾讯 HunyuanImage-2.1 图像生成模型DiT 架构训练 LoRA低秩适配模型包括与train_network.py的差异、模型文件准备、完整训练命令、HunyuanImage-2.1 特有参数逐项详解、不同显存下的优化策略、训练后推理验证以及与 ComfyUI 的格式互转。读者读完即可独立完成从数据准备、训练到推理验证的完整 LoRA 工作流。1. 概述为 HunyuanImage-2.1 定制的 LoRA 训练入口hunyuan_image_train_network.py是 sd-scripts 中针对HunyuanImage-2.1模型训练的专用脚本位于仓库根目录。与基于 UNet 的 Stable Diffusion 系列不同HunyuanImage-2.1 采用Diffusion TransformerDiT架构并使用了两个文本编码器Qwen2.5-VL 与 byT5以及专用 VAE。从源码看该脚本的核心入口是hunyuan_image_train_network.py中的HunyuanImageNetworkTrainer类它继承自train_network.NetworkTrainer通过覆写模型加载、文本编码、噪声调度、VAE 缓存等环节来适配 HunyuanImage-2.1其参数解析器则在train_network.setup_parser()基础上追加了 DiT / Qwen2.5-VL / byT5 / VAE 相关参数。在开始之前建议先熟悉通用 LoRA 训练基础知识公共选项--output_dir、--output_name、--network_module、--network_dim、--network_alpha、--learning_rate等与 train_network.py 指南 及 sdxl_train_network.py 指南 一致。前置条件已克隆 sd-scripts 仓库并完成 Python 环境配置参见 README.md 的依赖安装说明。已准备好训练数据集。数据集配置TOML 格式请参考 数据集配置指南或 config_README-en.md。2. 与train_network.py的主要差异hunyuan_image_train_network.py基于train_network.py改造而来主要差异如下维度说明目标模型HunyuanImage-2.1DiT 架构而非 Stable Diffusion UNet模型结构Transformer-based DiT双文本编码器 Qwen2.5-VL byT5专用 VAE必需参数新增 DiT 模型、Qwen2.5-VL、byT5、VAE 四个模型文件参数不兼容参数Stable Diffusion 专用参数如--v2、--clip_skip、--max_token_length不可用新增参数Flow Matching 相关--discrete_flow_shift、--model_prediction_type、--timestep_sampling等及显存优化参数在代码层面hunyuan_image_train_network.py的setup_parser()明确列出了这些 HunyuanImage-2.1 特有参数同时HunyuanImageNetworkTrainer.get_text_encoders_train_flags()返回[False, False]从实现上确认了本脚本不支持对两个文本编码器做 LoRA 训练详见第 4 节。3. 训练前的准备工作开始训练前需要准备以下 5 类文件训练脚本hunyuan_image_train_network.py仓库根目录。HunyuanImage-2.1 DiT 模型文件基础 DiT 模型.safetensors文件--pretrained_model_name_or_path。文本编码器模型文件Qwen2.5-VL 模型文件--text_encoder。byT5 模型文件--byt5。VAE 模型文件HunyuanImage-2.1 兼容的 VAE.safetensors文件--vae。数据集定义文件.toml描述训练数据集配置的 TOML 文件。3.1 模型文件下载清单组件来源仓库文件路径DiT 模型Tencent HunyuanImage-2.1 官方仓库dit/hunyuanimage2.1.safetensorsQwen2.5-VLComfy-Org/HunyuanImage_2.1_ComfyUIsplit_files/text_encoders/qwen_2.5_vl_7b.safetensorsbyT5Comfy-Org/HunyuanImage_2.1_ComfyUIsplit_files/text_encoders/byt5_small_glyphxl_fp16.safetensorsVAEComfy-Org/HunyuanImage_2.1_ComfyUIsplit_files/vae/hunyuan_image_2.1_vae_fp16.safetensors从实现细节看hunyuan_image_train_network.py的load_target_model()对 Qwen2.5-VL 默认按bfloat16加载--fp8_vl时按 FP8byT5 固定按float16加载VAE 也固定为fp16这与上表中的模型文件命名fp16一致——请务必使用官方提供的这些 fp16/bf16 版本文件而不是自行转换精度。4. 执行训练在终端中运行hunyuan_image_train_network.py并指定 HunyuanImage-2.1 特有参数。基本命令示例如下accelerate launch --num_cpu_threads_per_process 1 hunyuan_image_train_network.py \ --pretrained_model_name_or_pathpath to HunyuanDiT model \ --text_encoderpath to Qwen2.5-VL model \ --byt5path to byT5 model \ --vaepath to VAE model \ --dataset_configmy_hunyuan_dataset_config.toml \ --output_diroutput directory \ --output_namemy_hunyuan_lora \ --save_model_assafetensors \ --network_modulenetworks.lora_hunyuan_image \ --network_dim16 \ --network_alpha1 \ --network_train_unet_only \ --learning_rate1e-4 \ --optimizer_typeAdamW8bit \ --lr_schedulerconstant \ --attn_modetorch \ --split_attn \ --max_train_epochs10 \ --save_every_n_epochs1 \ --mixed_precisionbf16 \ --gradient_checkpointing \ --model_prediction_typeraw \ --discrete_flow_shift5.0 \ --blocks_to_swap18 \ --cache_text_encoder_outputs \ --cache_latents重要约束HunyuanImage-2.1 训练不支持文本编码器的 LoRA 模块因此--network_train_unet_only是必需的。这一点在源码中得到印证HunyuanImageNetworkTrainer.get_text_encoders_train_flags()恒返回[False, False]hunyuan_image_train_network.pyLoRA 网络networks/lora_hunyuan_image.py也只为 DiT 创建unet_lorastext_encoder_loras始终为空。4.1 模型相关参数必填参数说明--pretrained_model_name_or_pathpath to HunyuanDiT model[必填]基础 DiT 模型的.safetensors文件路径--text_encoderpath to Qwen2.5-VL model[必填]Qwen2.5-VL 文本编码器文件路径应为bfloat16精度--byt5path to byT5 model[必填]byT5 文本编码器文件路径应为float16精度--vaepath to VAE model[必填]HunyuanImage-2.1 兼容 VAE 模型的.safetensors文件路径4.2 HunyuanImage-2.1 训练参数参数默认值说明--network_train_unet_only[必填]—仅训练 DiT 模型不支持文本编码器的 LoRA 模块--discrete_flow_shiftfloat5.0Flow Matching 调度器Euler Discrete Scheduler的 shift 值--model_prediction_typechoiceraw模型预测内容的解释与处理方式可选raw/additive/sigma_scaled默认且推荐raw--timestep_samplingchoicesigma训练时 timestep噪声水平的采样方式可选sigma/uniform/sigmoid/shift/flux_shift--sigmoid_scalefloat1.0timestep_sampling为sigmoid/shift/flux_shift时的缩放系数4.3 显存与速度相关参数参数说明--attn_modechoice注意力实现可选torch/xformers/flash/sageattn默认torch使用 scaled dot product attention。除torch外各库需单独安装。使用xformers且 batch size 1 时必须同时指定--split_attn--split_attn注意力计算时按 batch 逐个处理避免注意力掩码计算降低显存占用使用torch时可提升速度。xformers batch size 1 时必需--fp8_scaled以 scaled FP8 格式训练 DiT。可显著降低显存配合--blocks_to_swap最低约 8GB 可运行但训练结果可能有差异。这是不支持的--fp8_base的新替代方案。相关实现见 library/fp8_optimization_utils.py 与 library/hunyuan_image_models.py--fp8_vl对 VLMQwen2.5-VL文本编码器使用 FP8--text_encoder_cpu将文本编码器放到 CPU 上运行以降低显存占用适合显存不足12GB的环境。单条文本编码可能需要几分钟取决于 CPU。强烈建议配合--cache_text_encoder_outputs_to_disk避免每次训练都重复编码。此外可增大accelerate launch中的--num_cpu_threads_per_process如8或16部分环境可加速编码--blocks_to_swapinteger[实验特性]将部分模型Transformer 块在 CPU 与 GPU 之间交换以降低显存。指定要交换的块数如18。数值越大显存占用越低但训练越慢需按 GPU 显存调整。可与gradient_checkpointing同用--cache_text_encoder_outputs缓存 Qwen2.5-VL 与 byT5 的输出减少内存占用--cache_latents、--cache_latents_to_disk缓存 VAE 输出功能与 sdxl_train_network.py 指南 类似--vae_chunk_sizeintegerVAE 编码/解码分块处理以降低显存。指定块大小如16。越大越耗显存但越快。默认None不分块。适合显存受限如 8GB 或 12GB的环境源码级补充timestep 采样--timestep_sampling与--sigmoid_scale的底层实现位于 library/flux_train_utils.py 的get_noisy_model_input_and_timesteps()sigma为 sigma 密度采样、uniform为均匀随机、sigmoid取正态随机数的 sigmoid乘sigmoid_scale、shift/flux_shift在 sigmoid 基础上再做离散流 shift。而 library/flux_train_utils.py 的apply_model_prediction_type()则实现了raw原样使用、additive叠加到带噪输入、sigma_scaled乘以-sigma并叠加带噪输入同时启用 SD3 风格损失加权三种预测处理。源码级补充模型结构与 blocks_to_swaplibrary/hunyuan_image_models.py 定义了HYImageDiffusionTransformer包含20 个双流块MMDoubleStreamBlock与40 个单流块MMSingleStreamBlockhidden size 为 3584、28 个注意力头、patch size 1x1、输入通道 64。enable_block_swap()将待交换块数按“半数双流 余数双倍单流”拆分且每类最多交换块总数 - 2保留首尾块这就是--blocks_to_swap上限为 37 的来源20-2 (40-2) 按比例约束。networks/lora_hunyuan_image.py中NUM_DOUBLE_BLOCKS 20、NUM_SINGLE_BLOCKS 40与此一致LoRA 的目标模块为MMDoubleStreamBlock与MMSingleStreamBlock内的Linear层。5. 训练产物的使用训练完成后指定output_dir下会保存 LoRA 模型文件例如my_hunyuan_lora.safetensors可直接用于支持 HunyuanImage-2.1 的推理环境。保存时还会写入 SAI 模型规范元数据get_sai_model_spec()在 hunyuan_image_train_network.py 中指定hunyuan_image2.1并记录ss_timestep_sampling、ss_model_prediction_type、ss_discrete_flow_shift等训练关键参数update_metadata()。6. 高级设置6.1 显存优化按 GPU 显存推荐配置HunyuanImage-2.1 是大型模型显存不足的 GPU 需要优化。以下推荐配置基于该功能引入时的 Pull Request 测试结果GPU 显存推荐配置40GB标准设置无需特别优化24GB--fp8_scaled --blocks_to_swap 912GB--fp8_scaled --blocks_to_swap 328GB--fp8_scaled --blocks_to_swap 37关键显存降低选项--fp8_scaled以 scaled FP8 格式训练 DiT。这是 HunyuanImage-2.1 推荐的 FP8 选项取代不受支持的--fp8_base对 40GB 显存环境是必需的。--fp8_vl对 VLMQwen2.5-VL文本编码器使用 FP8。--blocks_to_swap number在 CPU 与 GPU 之间交换块以降低显存。数值越大省显存越多、训练越慢。HunyuanImage-2.1 最多可交换 37 个块。--cpu_offload_checkpointing将梯度检查点卸载到 CPU可降低显存但降低训练速度不能与--blocks_to_swap同时使用。使用 Adafactor 优化器比 8bit AdamW 更省显存--optimizer_type adafactor --optimizer_args relative_stepFalse scale_parameterFalse warmup_initFalse --lr_scheduler constant_with_warmup --max_grad_norm 0.0补充提示使用--blocks_to_swap时hunyuan_image_train_network.py 中prepare_unet_with_accelerator()会跳过accelerator.prepare的 device 放置改由move_to_device_except_swap_blocks()手动放置模型因此块交换与 Accelerate 的多卡/混合精度机制可以共存验证validation阶段结束时还会调用prepare_block_swap_before_forward()为下一轮前向做准备。6.2 HunyuanImage-2.1 LoRA 训练的重要设置Timestep 采样方式--timestep_sampling指定 0~1 范围内 timestep 的采样方式sigma基于 sigma 的采样类似 SD3默认。uniform均匀随机。sigmoid正态分布随机数的 sigmoid。shift正态分布随机数 sigmoid 后再做 shift。flux_shift按分辨率对 sigmoid 值做 FLUX.1 风格的 shift。模型预测处理--model_prediction_typeraw原样使用[推荐默认]。additive叠加到噪声输入上。sigma_scaled应用 sigma 缩放。推荐组合实验表明默认设置效果良好--model_prediction_type raw --discrete_flow_shift 5.06.3 基于正则表达式的 Rank / 学习率配置可以通过正则表达式为 LoRA 模块指定不同的 rankdim和学习率实现更灵活精细的控制。这些设置通过network_args参数传入network_reg_dims为正则匹配的模块指定 rank。格式为逗号分隔的patternrank字符串。示例--network_args network_reg_dimsattn.*.q_proj4,attn.*.k_proj4network_reg_lrs为正则匹配的模块指定学习率。格式为逗号分隔的patternlr字符串。示例--network_args network_reg_lrsdown_blocks.11e-4,up_blocks.22e-4注意事项要找到正确的模块名用于 pattern可能需要检查模型结构可借助--network_args verboseTrue输出每个 LoRA 模块名。network_reg_dims与network_reg_lrs的设置优先于全局的--network_dim与--learning_rate。若模块名匹配多个 pattern字符串中靠后的 pattern 生效。源码佐证networks/lora_hunyuan_image.py 中的parse_kv_pairs()解析逗号分隔的keyvalue字符串create_modules()内通过re.search(reg, lora_name)对每个模块名匹配正则匹配到即采用该 ranknetworks/lora_hunyuan_image.py未匹配的模块回退到全局lora_dim。LoRA 权重前缀为lora_unetLORA_PREFIX_HUNYUAN_IMAGE_DIT以兼容 ComfyUI。6.4 多分辨率训练可在数据集配置文件中定义多个分辨率并为每个分辨率指定不同的 batch size[general] shuffle_caption true caption_extension .txt [[datasets]] batch_size 2 enable_bucket true resolution [1024, 1024] [[datasets.subsets]] image_dir path/to/image/directory num_repeats 1 [[datasets]] batch_size 1 enable_bucket true resolution [1280, 768] [[datasets.subsets]] image_dir path/to/another/directory num_repeats 1注意该功能可用但不推荐。HunyuanImage-2.1 基础模型并未以多分辨率能力训练使用多分辨率可能导致意外结果。从代码看HunyuanImage-2.1 的 latent 缓存与 bucketing 强制按 32 的倍数校验分辨率verify_bucket_reso_steps(32)见 hunyuan_image_train_network.py且HunyuanImageLatentsCachingStrategy以multi_resolutionTrue模式支持多种尺寸缓存library/strategy_hunyuan_image.py。6.5 验证Validation训练期间可使用验证数据集计算验证损失Validation Loss评估模型的泛化性能。该功能与其他训练脚本一致详见 验证指南。7. 其他训练选项--ip_noise_gamma使用--ip_noise_gamma与--ip_noise_gamma_random_strength调整训练期间的 Input Perturbation 噪声 gamma 值。细节参见 Stable Diffusion 3 训练选项。--loss_type指定训练损失函数默认l2。l1L1 损失。l2L2 损失均方误差。huberHuber 损失。smooth_l1Smooth L1 损失。--huber_schedule、--huber_c、--huber_scaleHuber 损失参数--loss_type为huber或smooth_l1时使用。--weighting_scheme、--logit_mean、--logit_std、--mode_scale调整各 timestep 的损失权重详见 sd3_train_network.md 指南。--fused_backward_pass融合反向传播与优化器步骤降低显存占用。Flow Matching 目标说明HunyuanImage-2.1 训练采用 flow matching 目标hunyuan_image_train_network.py 中get_noise_pred_and_target()以target noise - latents作为回归目标并通过FlowMatchEulerDiscreteScheduler(num_train_timesteps1000, shiftargs.discrete_flow_shift)构造噪声调度器get_noise_scheduler()体现了--discrete_flow_shift的实际作用路径。8. 使用推理脚本验证训练结果仓库自带的hunyuan_image_minimal_inference.py可用训练好的 LoRA 生成图像。基本用法python hunyuan_image_minimal_inference.py \ --dit path to hunyuanimage2.1.safetensors \ --text_encoder path to qwen_2.5_vl_7b.safetensors \ --byt5 path to byt5_small_glyphxl_fp16.safetensors \ --vae path to hunyuan_image_2.1_vae_fp16.safetensors \ --lora_weight path to your trained LoRA \ --lora_multiplier 1.0 \ --attn_mode torch \ --prompt A cute cartoon penguin in a snowy landscape \ --image_size 2048 2048 \ --infer_steps 50 \ --guidance_scale 3.5 \ --flow_shift 5.0 \ --seed 542017 \ --save_path output_image.png关键选项--fp8_scaled推理时使用 scaled FP8 格式降低显存。--blocks_to_swap将块交换到 CPU 以降低显存。--image_size分辨率格式为高 宽官方仓库指出推理在 2560x1536、2304x1792、2048x2048、1792x2304、1536x2560 下最稳定。--guidance_scaleCFG 缩放默认3.5。--flow_shiftFlow Matching shift 参数默认5.0。--text_encoder_cpu文本编码器在 CPU 上运行以降低显存。--vae_chunk_sizeVAE 解码分块大小以降低内存默认None不分块。启用时推荐16。--apg_start_step_general与--apg_start_step_ocr推理使用 APGAdaptive Projected Guidance自适应投影引导时的起始步。50 步时官方推荐值分别为5与38。若该值超过--infer_stepsAPG 将不生效。--guidance_rescaleAPG 开始前步骤的 guidance 重新缩放默认0.0不缩放。若使用可从0.5左右起步调参。--guidance_rescale_apgAPG 阶段的 guidance 重新缩放默认0.0不缩放。此选项似乎影响不大若使用可从0.5左右起步调参。--split_attn不受支持推理为单张逐次进行--fp8_vl也不受支持若显存不足请改用--text_encoder_cpu将文本编码器放到 CPU。源码级补充APG 与 guidancehunyuan_image_minimal_inference.py中generate_body()hunyuan_image_minimal_inference.py按 OCR 与否分别构造cfg_guider_ocr/cfg_guider_general两个 APG 引导器并调用 library/hunyuan_image_utils.py 的apply_classifier_free_guidance()APG 起始步之前走标准 CFGuncond scale*(cond-uncond)之后切换为 APGnormalized_guidance_apg()将引导向量分解为平行/正交分量并分别缩放以减少过饱和。推理时 latent 通过latents / vae.scaling_factor缩放后解码与训练端shift_scale_latents()的LATENT_SCALING_FACTOR对称。9. 相关工具LoRA 格式转换networks/convert_hunyuan_image_lora_to_comfy.py用于将 LoRA 转换为 ComfyUI 兼容格式。由于两种格式存在细微差异转换是必要的。从 sd-scripts 格式转换为 ComfyUI 格式python networks/convert_hunyuan_image_lora_to_comfy.py path/to/source.safetensors path/to/destination.safetensors使用--reverse选项可反向转换ComfyUI 格式 → sd-scripts 格式。但反向转换仅适用于由本脚本转换过的 LoRA其他训练工具创建的 LoRA 无法转换。源码佐证networks/convert_hunyuan_image_lora_to_comfy.py 定义了双流块img_mlp_fc1 → img_mlp_0、img_mod_linear → img_mod_lin、txt_*同理与单流块modulation_linear → modulation_lin的键名映射表转换前后还会调用model_io.precalculate_safetensors_hashes()重算并写入sshs_model_hash/sshs_legacy_hash元数据。10. 其他常见功能hunyuan_image_train_network.py还包含许多与train_network.py共有的功能例如采样图像生成--sample_prompts等与详细的优化器设置。这些功能可参考 train_network.py 指南“其他功能”章节或直接查看脚本帮助python hunyuan_image_train_network.py --help在 hunyuan_image_train_network.py 中采样图像生成会在训练期间周期性调用hunyuan_image_minimal_inference.generate_body()做推理并将结果保存到output_dir/sample/文件名含 epoch/step、序号与 seed同时支持 wandb 记录。结语本文完整覆盖了 sd-scripts 中 HunyuanImage-2.1 LoRA 训练的核心链路脚本定位与差异、四类模型文件的准备、完整训练命令与参数逐项解析、按显存档位推荐的优化组合、正则表达式精细化 rank/学习率控制、多分辨率与验证等高级功能以及训练后推理与 ComfyUI 格式转换。配合源码中对 DiT 结构20 双流块 40 单流块、timestep 采样、flow matching 目标、块交换与 APG 引导的实现细节你可以在 8GB 到 40GB 的各类 GPU 环境中稳定地训练并验证 HunyuanImage-2.1 LoRA 模型。赞分享深度学习计算机视觉媒体生成模型训练微调【免费下载链接】sd-scripts项目地址https://gitcode.com/gh_mirrors/sd/sd-scripts点击查看免费下载相关推荐终极LoRA训练教程使用sd-scripts打造个性化AI模型终极LoRA训练教程使用sd scripts打造个性化AI模型 想要打造专属于你的AI绘画模型吗LoRA技术让你能够快速高效地训练个性化AI模型而sd s深度学习计算机视觉媒体生成模型训练微调上一篇Impeccable colorize 实战指南给灰阶 UI 注入战略性色彩的系统方法下一篇mapshaper缓冲区分析实战从基础概念到复杂应用场景创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 sd-scripts 实战指南：使用 `hunyuan_image_train_network.py` 训练 HunyuanImage-2.1 LoRA
深度学习计算机视觉媒体生成模型训练微调【免费下载链接】sd-scripts项目地址https://gitcode.com/gh_mirrors/sd/sd-scripts点击查看免费下载本文是 sd-scripts 仓库中 docs/hunyuan_image_train_network.md 的完整技术展开系统讲解如何使用hunyuan_image_train_network.py对腾讯 HunyuanImage-2.1 图像生成模型DiT 架构训练 LoRA低秩适配模型包括与train_network.py的差异、模型文件准备、完整训练命令、HunyuanImage-2.1 特有参数逐项详解、不同显存下的优化策略、训练后推理验证以及与 ComfyUI 的格式互转。读者读完即可独立完成从数据准备、训练到推理验证的完整 LoRA 工作流。1. 概述为 HunyuanImage-2.1 定制的 LoRA 训练入口hunyuan_image_train_network.py是 sd-scripts 中针对HunyuanImage-2.1模型训练的专用脚本位于仓库根目录。与基于 UNet 的 Stable Diffusion 系列不同HunyuanImage-2.1 采用Diffusion TransformerDiT架构并使用了两个文本编码器Qwen2.5-VL 与 byT5以及专用 VAE。从源码看该脚本的核心入口是hunyuan_image_train_network.py中的HunyuanImageNetworkTrainer类它继承自train_network.NetworkTrainer通过覆写模型加载、文本编码、噪声调度、VAE 缓存等环节来适配 HunyuanImage-2.1其参数解析器则在train_network.setup_parser()基础上追加了 DiT / Qwen2.5-VL / byT5 / VAE 相关参数。在开始之前建议先熟悉通用 LoRA 训练基础知识公共选项--output_dir、--output_name、--network_module、--network_dim、--network_alpha、--learning_rate等与 train_network.py 指南 及 sdxl_train_network.py 指南 一致。前置条件已克隆 sd-scripts 仓库并完成 Python 环境配置参见 README.md 的依赖安装说明。已准备好训练数据集。数据集配置TOML 格式请参考 数据集配置指南或 config_README-en.md。2. 与train_network.py的主要差异hunyuan_image_train_network.py基于train_network.py改造而来主要差异如下维度说明目标模型HunyuanImage-2.1DiT 架构而非 Stable Diffusion UNet模型结构Transformer-based DiT双文本编码器 Qwen2.5-VL byT5专用 VAE必需参数新增 DiT 模型、Qwen2.5-VL、byT5、VAE 四个模型文件参数不兼容参数Stable Diffusion 专用参数如--v2、--clip_skip、--max_token_length不可用新增参数Flow Matching 相关--discrete_flow_shift、--model_prediction_type、--timestep_sampling等及显存优化参数在代码层面hunyuan_image_train_network.py的setup_parser()明确列出了这些 HunyuanImage-2.1 特有参数同时HunyuanImageNetworkTrainer.get_text_encoders_train_flags()返回[False, False]从实现上确认了本脚本不支持对两个文本编码器做 LoRA 训练详见第 4 节。3. 训练前的准备工作开始训练前需要准备以下 5 类文件训练脚本hunyuan_image_train_network.py仓库根目录。HunyuanImage-2.1 DiT 模型文件基础 DiT 模型.safetensors文件--pretrained_model_name_or_path。文本编码器模型文件Qwen2.5-VL 模型文件--text_encoder。byT5 模型文件--byt5。VAE 模型文件HunyuanImage-2.1 兼容的 VAE.safetensors文件--vae。数据集定义文件.toml描述训练数据集配置的 TOML 文件。3.1 模型文件下载清单组件来源仓库文件路径DiT 模型Tencent HunyuanImage-2.1 官方仓库dit/hunyuanimage2.1.safetensorsQwen2.5-VLComfy-Org/HunyuanImage_2.1_ComfyUIsplit_files/text_encoders/qwen_2.5_vl_7b.safetensorsbyT5Comfy-Org/HunyuanImage_2.1_ComfyUIsplit_files/text_encoders/byt5_small_glyphxl_fp16.safetensorsVAEComfy-Org/HunyuanImage_2.1_ComfyUIsplit_files/vae/hunyuan_image_2.1_vae_fp16.safetensors从实现细节看hunyuan_image_train_network.py的load_target_model()对 Qwen2.5-VL 默认按bfloat16加载--fp8_vl时按 FP8byT5 固定按float16加载VAE 也固定为fp16这与上表中的模型文件命名fp16一致——请务必使用官方提供的这些 fp16/bf16 版本文件而不是自行转换精度。4. 执行训练在终端中运行hunyuan_image_train_network.py并指定 HunyuanImage-2.1 特有参数。基本命令示例如下accelerate launch --num_cpu_threads_per_process 1 hunyuan_image_train_network.py \ --pretrained_model_name_or_pathpath to HunyuanDiT model \ --text_encoderpath to Qwen2.5-VL model \ --byt5path to byT5 model \ --vaepath to VAE model \ --dataset_configmy_hunyuan_dataset_config.toml \ --output_diroutput directory \ --output_namemy_hunyuan_lora \ --save_model_assafetensors \ --network_modulenetworks.lora_hunyuan_image \ --network_dim16 \ --network_alpha1 \ --network_train_unet_only \ --learning_rate1e-4 \ --optimizer_typeAdamW8bit \ --lr_schedulerconstant \ --attn_modetorch \ --split_attn \ --max_train_epochs10 \ --save_every_n_epochs1 \ --mixed_precisionbf16 \ --gradient_checkpointing \ --model_prediction_typeraw \ --discrete_flow_shift5.0 \ --blocks_to_swap18 \ --cache_text_encoder_outputs \ --cache_latents重要约束HunyuanImage-2.1 训练不支持文本编码器的 LoRA 模块因此--network_train_unet_only是必需的。这一点在源码中得到印证HunyuanImageNetworkTrainer.get_text_encoders_train_flags()恒返回[False, False]hunyuan_image_train_network.pyLoRA 网络networks/lora_hunyuan_image.py也只为 DiT 创建unet_lorastext_encoder_loras始终为空。4.1 模型相关参数必填参数说明--pretrained_model_name_or_pathpath to HunyuanDiT model[必填]基础 DiT 模型的.safetensors文件路径--text_encoderpath to Qwen2.5-VL model[必填]Qwen2.5-VL 文本编码器文件路径应为bfloat16精度--byt5path to byT5 model[必填]byT5 文本编码器文件路径应为float16精度--vaepath to VAE model[必填]HunyuanImage-2.1 兼容 VAE 模型的.safetensors文件路径4.2 HunyuanImage-2.1 训练参数参数默认值说明--network_train_unet_only[必填]—仅训练 DiT 模型不支持文本编码器的 LoRA 模块--discrete_flow_shiftfloat5.0Flow Matching 调度器Euler Discrete Scheduler的 shift 值--model_prediction_typechoiceraw模型预测内容的解释与处理方式可选raw/additive/sigma_scaled默认且推荐raw--timestep_samplingchoicesigma训练时 timestep噪声水平的采样方式可选sigma/uniform/sigmoid/shift/flux_shift--sigmoid_scalefloat1.0timestep_sampling为sigmoid/shift/flux_shift时的缩放系数4.3 显存与速度相关参数参数说明--attn_modechoice注意力实现可选torch/xformers/flash/sageattn默认torch使用 scaled dot product attention。除torch外各库需单独安装。使用xformers且 batch size 1 时必须同时指定--split_attn--split_attn注意力计算时按 batch 逐个处理避免注意力掩码计算降低显存占用使用torch时可提升速度。xformers batch size 1 时必需--fp8_scaled以 scaled FP8 格式训练 DiT。可显著降低显存配合--blocks_to_swap最低约 8GB 可运行但训练结果可能有差异。这是不支持的--fp8_base的新替代方案。相关实现见 library/fp8_optimization_utils.py 与 library/hunyuan_image_models.py--fp8_vl对 VLMQwen2.5-VL文本编码器使用 FP8--text_encoder_cpu将文本编码器放到 CPU 上运行以降低显存占用适合显存不足12GB的环境。单条文本编码可能需要几分钟取决于 CPU。强烈建议配合--cache_text_encoder_outputs_to_disk避免每次训练都重复编码。此外可增大accelerate launch中的--num_cpu_threads_per_process如8或16部分环境可加速编码--blocks_to_swapinteger[实验特性]将部分模型Transformer 块在 CPU 与 GPU 之间交换以降低显存。指定要交换的块数如18。数值越大显存占用越低但训练越慢需按 GPU 显存调整。可与gradient_checkpointing同用--cache_text_encoder_outputs缓存 Qwen2.5-VL 与 byT5 的输出减少内存占用--cache_latents、--cache_latents_to_disk缓存 VAE 输出功能与 sdxl_train_network.py 指南 类似--vae_chunk_sizeintegerVAE 编码/解码分块处理以降低显存。指定块大小如16。越大越耗显存但越快。默认None不分块。适合显存受限如 8GB 或 12GB的环境源码级补充timestep 采样--timestep_sampling与--sigmoid_scale的底层实现位于 library/flux_train_utils.py 的get_noisy_model_input_and_timesteps()sigma为 sigma 密度采样、uniform为均匀随机、sigmoid取正态随机数的 sigmoid乘sigmoid_scale、shift/flux_shift在 sigmoid 基础上再做离散流 shift。而 library/flux_train_utils.py 的apply_model_prediction_type()则实现了raw原样使用、additive叠加到带噪输入、sigma_scaled乘以-sigma并叠加带噪输入同时启用 SD3 风格损失加权三种预测处理。源码级补充模型结构与 blocks_to_swaplibrary/hunyuan_image_models.py 定义了HYImageDiffusionTransformer包含20 个双流块MMDoubleStreamBlock与40 个单流块MMSingleStreamBlockhidden size 为 3584、28 个注意力头、patch size 1x1、输入通道 64。enable_block_swap()将待交换块数按“半数双流 余数双倍单流”拆分且每类最多交换块总数 - 2保留首尾块这就是--blocks_to_swap上限为 37 的来源20-2 (40-2) 按比例约束。networks/lora_hunyuan_image.py中NUM_DOUBLE_BLOCKS 20、NUM_SINGLE_BLOCKS 40与此一致LoRA 的目标模块为MMDoubleStreamBlock与MMSingleStreamBlock内的Linear层。5. 训练产物的使用训练完成后指定output_dir下会保存 LoRA 模型文件例如my_hunyuan_lora.safetensors可直接用于支持 HunyuanImage-2.1 的推理环境。保存时还会写入 SAI 模型规范元数据get_sai_model_spec()在 hunyuan_image_train_network.py 中指定hunyuan_image2.1并记录ss_timestep_sampling、ss_model_prediction_type、ss_discrete_flow_shift等训练关键参数update_metadata()。6. 高级设置6.1 显存优化按 GPU 显存推荐配置HunyuanImage-2.1 是大型模型显存不足的 GPU 需要优化。以下推荐配置基于该功能引入时的 Pull Request 测试结果GPU 显存推荐配置40GB标准设置无需特别优化24GB--fp8_scaled --blocks_to_swap 912GB--fp8_scaled --blocks_to_swap 328GB--fp8_scaled --blocks_to_swap 37关键显存降低选项--fp8_scaled以 scaled FP8 格式训练 DiT。这是 HunyuanImage-2.1 推荐的 FP8 选项取代不受支持的--fp8_base对 40GB 显存环境是必需的。--fp8_vl对 VLMQwen2.5-VL文本编码器使用 FP8。--blocks_to_swap number在 CPU 与 GPU 之间交换块以降低显存。数值越大省显存越多、训练越慢。HunyuanImage-2.1 最多可交换 37 个块。--cpu_offload_checkpointing将梯度检查点卸载到 CPU可降低显存但降低训练速度不能与--blocks_to_swap同时使用。使用 Adafactor 优化器比 8bit AdamW 更省显存--optimizer_type adafactor --optimizer_args relative_stepFalse scale_parameterFalse warmup_initFalse --lr_scheduler constant_with_warmup --max_grad_norm 0.0补充提示使用--blocks_to_swap时hunyuan_image_train_network.py 中prepare_unet_with_accelerator()会跳过accelerator.prepare的 device 放置改由move_to_device_except_swap_blocks()手动放置模型因此块交换与 Accelerate 的多卡/混合精度机制可以共存验证validation阶段结束时还会调用prepare_block_swap_before_forward()为下一轮前向做准备。6.2 HunyuanImage-2.1 LoRA 训练的重要设置Timestep 采样方式--timestep_sampling指定 0~1 范围内 timestep 的采样方式sigma基于 sigma 的采样类似 SD3默认。uniform均匀随机。sigmoid正态分布随机数的 sigmoid。shift正态分布随机数 sigmoid 后再做 shift。flux_shift按分辨率对 sigmoid 值做 FLUX.1 风格的 shift。模型预测处理--model_prediction_typeraw原样使用[推荐默认]。additive叠加到噪声输入上。sigma_scaled应用 sigma 缩放。推荐组合实验表明默认设置效果良好--model_prediction_type raw --discrete_flow_shift 5.06.3 基于正则表达式的 Rank / 学习率配置可以通过正则表达式为 LoRA 模块指定不同的 rankdim和学习率实现更灵活精细的控制。这些设置通过network_args参数传入network_reg_dims为正则匹配的模块指定 rank。格式为逗号分隔的patternrank字符串。示例--network_args network_reg_dimsattn.*.q_proj4,attn.*.k_proj4network_reg_lrs为正则匹配的模块指定学习率。格式为逗号分隔的patternlr字符串。示例--network_args network_reg_lrsdown_blocks.11e-4,up_blocks.22e-4注意事项要找到正确的模块名用于 pattern可能需要检查模型结构可借助--network_args verboseTrue输出每个 LoRA 模块名。network_reg_dims与network_reg_lrs的设置优先于全局的--network_dim与--learning_rate。若模块名匹配多个 pattern字符串中靠后的 pattern 生效。源码佐证networks/lora_hunyuan_image.py 中的parse_kv_pairs()解析逗号分隔的keyvalue字符串create_modules()内通过re.search(reg, lora_name)对每个模块名匹配正则匹配到即采用该 ranknetworks/lora_hunyuan_image.py未匹配的模块回退到全局lora_dim。LoRA 权重前缀为lora_unetLORA_PREFIX_HUNYUAN_IMAGE_DIT以兼容 ComfyUI。6.4 多分辨率训练可在数据集配置文件中定义多个分辨率并为每个分辨率指定不同的 batch size[general] shuffle_caption true caption_extension .txt [[datasets]] batch_size 2 enable_bucket true resolution [1024, 1024] [[datasets.subsets]] image_dir path/to/image/directory num_repeats 1 [[datasets]] batch_size 1 enable_bucket true resolution [1280, 768] [[datasets.subsets]] image_dir path/to/another/directory num_repeats 1注意该功能可用但不推荐。HunyuanImage-2.1 基础模型并未以多分辨率能力训练使用多分辨率可能导致意外结果。从代码看HunyuanImage-2.1 的 latent 缓存与 bucketing 强制按 32 的倍数校验分辨率verify_bucket_reso_steps(32)见 hunyuan_image_train_network.py且HunyuanImageLatentsCachingStrategy以multi_resolutionTrue模式支持多种尺寸缓存library/strategy_hunyuan_image.py。6.5 验证Validation训练期间可使用验证数据集计算验证损失Validation Loss评估模型的泛化性能。该功能与其他训练脚本一致详见 验证指南。7. 其他训练选项--ip_noise_gamma使用--ip_noise_gamma与--ip_noise_gamma_random_strength调整训练期间的 Input Perturbation 噪声 gamma 值。细节参见 Stable Diffusion 3 训练选项。--loss_type指定训练损失函数默认l2。l1L1 损失。l2L2 损失均方误差。huberHuber 损失。smooth_l1Smooth L1 损失。--huber_schedule、--huber_c、--huber_scaleHuber 损失参数--loss_type为huber或smooth_l1时使用。--weighting_scheme、--logit_mean、--logit_std、--mode_scale调整各 timestep 的损失权重详见 sd3_train_network.md 指南。--fused_backward_pass融合反向传播与优化器步骤降低显存占用。Flow Matching 目标说明HunyuanImage-2.1 训练采用 flow matching 目标hunyuan_image_train_network.py 中get_noise_pred_and_target()以target noise - latents作为回归目标并通过FlowMatchEulerDiscreteScheduler(num_train_timesteps1000, shiftargs.discrete_flow_shift)构造噪声调度器get_noise_scheduler()体现了--discrete_flow_shift的实际作用路径。8. 使用推理脚本验证训练结果仓库自带的hunyuan_image_minimal_inference.py可用训练好的 LoRA 生成图像。基本用法python hunyuan_image_minimal_inference.py \ --dit path to hunyuanimage2.1.safetensors \ --text_encoder path to qwen_2.5_vl_7b.safetensors \ --byt5 path to byt5_small_glyphxl_fp16.safetensors \ --vae path to hunyuan_image_2.1_vae_fp16.safetensors \ --lora_weight path to your trained LoRA \ --lora_multiplier 1.0 \ --attn_mode torch \ --prompt A cute cartoon penguin in a snowy landscape \ --image_size 2048 2048 \ --infer_steps 50 \ --guidance_scale 3.5 \ --flow_shift 5.0 \ --seed 542017 \ --save_path output_image.png关键选项--fp8_scaled推理时使用 scaled FP8 格式降低显存。--blocks_to_swap将块交换到 CPU 以降低显存。--image_size分辨率格式为高 宽官方仓库指出推理在 2560x1536、2304x1792、2048x2048、1792x2304、1536x2560 下最稳定。--guidance_scaleCFG 缩放默认3.5。--flow_shiftFlow Matching shift 参数默认5.0。--text_encoder_cpu文本编码器在 CPU 上运行以降低显存。--vae_chunk_sizeVAE 解码分块大小以降低内存默认None不分块。启用时推荐16。--apg_start_step_general与--apg_start_step_ocr推理使用 APGAdaptive Projected Guidance自适应投影引导时的起始步。50 步时官方推荐值分别为5与38。若该值超过--infer_stepsAPG 将不生效。--guidance_rescaleAPG 开始前步骤的 guidance 重新缩放默认0.0不缩放。若使用可从0.5左右起步调参。--guidance_rescale_apgAPG 阶段的 guidance 重新缩放默认0.0不缩放。此选项似乎影响不大若使用可从0.5左右起步调参。--split_attn不受支持推理为单张逐次进行--fp8_vl也不受支持若显存不足请改用--text_encoder_cpu将文本编码器放到 CPU。源码级补充APG 与 guidancehunyuan_image_minimal_inference.py中generate_body()hunyuan_image_minimal_inference.py按 OCR 与否分别构造cfg_guider_ocr/cfg_guider_general两个 APG 引导器并调用 library/hunyuan_image_utils.py 的apply_classifier_free_guidance()APG 起始步之前走标准 CFGuncond scale*(cond-uncond)之后切换为 APGnormalized_guidance_apg()将引导向量分解为平行/正交分量并分别缩放以减少过饱和。推理时 latent 通过latents / vae.scaling_factor缩放后解码与训练端shift_scale_latents()的LATENT_SCALING_FACTOR对称。9. 相关工具LoRA 格式转换networks/convert_hunyuan_image_lora_to_comfy.py用于将 LoRA 转换为 ComfyUI 兼容格式。由于两种格式存在细微差异转换是必要的。从 sd-scripts 格式转换为 ComfyUI 格式python networks/convert_hunyuan_image_lora_to_comfy.py path/to/source.safetensors path/to/destination.safetensors使用--reverse选项可反向转换ComfyUI 格式 → sd-scripts 格式。但反向转换仅适用于由本脚本转换过的 LoRA其他训练工具创建的 LoRA 无法转换。源码佐证networks/convert_hunyuan_image_lora_to_comfy.py 定义了双流块img_mlp_fc1 → img_mlp_0、img_mod_linear → img_mod_lin、txt_*同理与单流块modulation_linear → modulation_lin的键名映射表转换前后还会调用model_io.precalculate_safetensors_hashes()重算并写入sshs_model_hash/sshs_legacy_hash元数据。10. 其他常见功能hunyuan_image_train_network.py还包含许多与train_network.py共有的功能例如采样图像生成--sample_prompts等与详细的优化器设置。这些功能可参考 train_network.py 指南“其他功能”章节或直接查看脚本帮助python hunyuan_image_train_network.py --help在 hunyuan_image_train_network.py 中采样图像生成会在训练期间周期性调用hunyuan_image_minimal_inference.generate_body()做推理并将结果保存到output_dir/sample/文件名含 epoch/step、序号与 seed同时支持 wandb 记录。结语本文完整覆盖了 sd-scripts 中 HunyuanImage-2.1 LoRA 训练的核心链路脚本定位与差异、四类模型文件的准备、完整训练命令与参数逐项解析、按显存档位推荐的优化组合、正则表达式精细化 rank/学习率控制、多分辨率与验证等高级功能以及训练后推理与 ComfyUI 格式转换。配合源码中对 DiT 结构20 双流块 40 单流块、timestep 采样、flow matching 目标、块交换与 APG 引导的实现细节你可以在 8GB 到 40GB 的各类 GPU 环境中稳定地训练并验证 HunyuanImage-2.1 LoRA 模型。赞分享深度学习计算机视觉媒体生成模型训练微调【免费下载链接】sd-scripts项目地址https://gitcode.com/gh_mirrors/sd/sd-scripts点击查看免费下载相关推荐终极LoRA训练教程使用sd-scripts打造个性化AI模型终极LoRA训练教程使用sd scripts打造个性化AI模型 想要打造专属于你的AI绘画模型吗LoRA技术让你能够快速高效地训练个性化AI模型而sd s深度学习计算机视觉媒体生成模型训练微调上一篇Impeccable colorize 实战指南给灰阶 UI 注入战略性色彩的系统方法下一篇mapshaper缓冲区分析实战从基础概念到复杂应用场景创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考