企业官网建设流程全解析

• 深度学习
• 计算机视觉
• 媒体生成
• 模型训练
• 微调

本文是 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 Transformer（DiT）架构，并使用了两个文本编码器（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改造而来，主要差异如下：

在代码层面，hunyuan_image_train_network.py的setup_parser()明确列出了这些 HunyuanImage-2.1 特有参数；同时HunyuanImageNetworkTrainer.get_text_encoders_train_flags()返回[False, False]，从实现上确认了本脚本不支持对两个文本编码器做 LoRA 训练（详见第 4 节）。

3. 训练前的准备工作

开始训练前需要准备以下 5 类文件：

1. 训练脚本：hunyuan_image_train_network.py（仓库根目录）。
2. HunyuanImage-2.1 DiT 模型文件：基础 DiT 模型.safetensors文件（--pretrained_model_name_or_path）。
3. 文本编码器模型文件：
   • Qwen2.5-VL 模型文件（--text_encoder）。
   • byT5 模型文件（--byt5）。
4. VAE 模型文件：HunyuanImage-2.1 兼容的 VAE.safetensors文件（--vae）。
5. 数据集定义文件（.toml）：描述训练数据集配置的 TOML 文件。

3.1 模型文件下载清单

从实现细节看，hunyuan_image_train_network.py的load_target_model()对 Qwen2.5-VL 默认按bfloat16加载（--fp8_vl时按 FP8），byT5 固定按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_path="<path to HunyuanDiT model>" \ --text_encoder="<path to Qwen2.5-VL model>" \ --byt5="<path to byT5 model>" \ --vae="<path to VAE model>" \ --dataset_config="my_hunyuan_dataset_config.toml" \ --output_dir="<output directory>" \ --output_name="my_hunyuan_lora" \ --save_model_as=safetensors \ --network_module=networks.lora_hunyuan_image \ --network_dim=16 \ --network_alpha=1 \ --network_train_unet_only \ --learning_rate=1e-4 \ --optimizer_type="AdamW8bit" \ --lr_scheduler="constant" \ --attn_mode="torch" \ --split_attn \ --max_train_epochs=10 \ --save_every_n_epochs=1 \ --mixed_precision="bf16" \ --gradient_checkpointing \ --model_prediction_type="raw" \ --discrete_flow_shift=5.0 \ --blocks_to_swap=18 \ --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.py），LoRA 网络networks/lora_hunyuan_image.py也只为 DiT 创建unet_loras，text_encoder_loras始终为空。

4.1 模型相关参数（必填）

4.2 HunyuanImage-2.1 训练参数

4.3 显存与速度相关参数

源码级补充（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_swap）：library/hunyuan_image_models.py 定义了HYImageDiffusionTransformer，包含20 个双流块（MMDoubleStreamBlock）与40 个单流块（MMSingleStreamBlock），hidden 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_image="2.1"），并记录ss_timestep_sampling、ss_model_prediction_type、ss_discrete_flow_shift等训练关键参数（update_metadata()）。

6. 高级设置

6.1 显存优化：按 GPU 显存推荐配置

HunyuanImage-2.1 是大型模型，显存不足的 GPU 需要优化。以下推荐配置基于该功能引入时的 Pull Request 测试结果：

关键显存降低选项：

• --fp8_scaled：以 scaled FP8 格式训练 DiT。这是 HunyuanImage-2.1 推荐的 FP8 选项，取代不受支持的--fp8_base；对 <40GB 显存环境是必需的。

• --fp8_vl：对 VLM（Qwen2.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_step=False" "scale_parameter=False" "warmup_init=False" --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_type）

• raw：原样使用[推荐，默认]。
• additive：叠加到噪声输入上。
• sigma_scaled：应用 sigma 缩放。

推荐组合

实验表明默认设置效果良好：

--model_prediction_type raw --discrete_flow_shift 5.0

6.3 基于正则表达式的 Rank / 学习率配置

可以通过正则表达式为 LoRA 模块指定不同的 rank（dim）和学习率，实现更灵活精细的控制。这些设置通过network_args参数传入：

• network_reg_dims：为正则匹配的模块指定 rank。格式为逗号分隔的pattern=rank字符串。
  • 示例：--network_args "network_reg_dims=attn.*.q_proj=4,attn.*.k_proj=4"
• network_reg_lrs：为正则匹配的模块指定学习率。格式为逗号分隔的pattern=lr字符串。
  • 示例：--network_args "network_reg_lrs=down_blocks.1=1e-4,up_blocks.2=2e-4"

注意事项：

• 要找到正确的模块名用于 pattern，可能需要检查模型结构（可借助--network_args "verbose=True"输出每个 LoRA 模块名）。
• network_reg_dims与network_reg_lrs的设置优先于全局的--network_dim与--learning_rate。
• 若模块名匹配多个 pattern，字符串中靠后的 pattern 生效。

源码佐证：networks/lora_hunyuan_image.py 中的parse_kv_pairs()解析逗号分隔的key=value字符串；create_modules()内通过re.search(reg, lora_name)对每个模块名匹配正则，匹配到即采用该 rank（networks/lora_hunyuan_image.py），未匹配的模块回退到全局lora_dim。LoRA 权重前缀为lora_unet（LORA_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_resolution=True模式支持多种尺寸缓存（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。
  • l1：L1 损失。
  • l2：L2 损失（均方误差）。
  • huber：Huber 损失。
  • smooth_l1：Smooth L1 损失。
• --huber_schedule、--huber_c、--huber_scale：Huber 损失参数，--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_timesteps=1000, shift=args.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_scale：CFG 缩放（默认3.5）。
• --flow_shift：Flow Matching shift 参数（默认5.0）。
• --text_encoder_cpu：文本编码器在 CPU 上运行以降低显存。
• --vae_chunk_size：VAE 解码分块大小以降低内存（默认None，不分块）。启用时推荐16。
• --apg_start_step_general与--apg_start_step_ocr：推理使用 APG（Adaptive Projected Guidance，自适应投影引导）时的起始步。50 步时官方推荐值分别为5与38。若该值超过--infer_steps，APG 将不生效。
• --guidance_rescale：APG 开始前步骤的 guidance 重新缩放，默认0.0（不缩放）。若使用，可从0.5左右起步调参。
• --guidance_rescale_apg：APG 阶段的 guidance 重新缩放，默认0.0（不缩放）。此选项似乎影响不大，若使用可从0.5左右起步调参。

--split_attn不受支持（推理为单张逐次进行）；--fp8_vl也不受支持，若显存不足请改用--text_encoder_cpu将文本编码器放到 CPU。

源码级补充（APG 与 guidance）：hunyuan_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 起始步之前走标准 CFG（uncond + scale*(cond-uncond)），之后切换为 APG；normalized_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 模型。

• 深度学习
• 计算机视觉
• 媒体生成
• 模型训练
• 微调