hunyuan-image3-finetune

用途

本仓库提供 HunyuanImage-3.0 的微调训练脚本。HunyuanImage-3.0 是 80B MoE 统一视觉语言模型，可同时执行理解与生成任务，官方仓库仅包含推理代码。这些脚本由 Pixo 团队独立开发，用于研究及教育目的。

主要能力

• 两种训练模式
  • 纯文本微调：基于语言模型的监督微调
  • 图像生成训练：基于流匹配的文本到图像生成
  • 注：图像理解（MMU）流程尚未实现。
• 参数高效微调
  • 支持 LoRA 微调
  • 支持 QLoRA（4-bit / 8-bit 量化），可在单 GPU 上进行内存高效训练
• 训练框架
  • 基于 Hugging Face Transformers Trainer
  • 集成 DeepSpeed（含 ZeRO-3 配置）
  • 集成 PEFT、Diffusers
• 数据准备工具
  • prepare_text_data.py：将 Alpaca、ShareGPT 等文本格式转换为训练 JSONL
  • prepare_image_gen_data.py：将图片目录与 CSV 描述转换为训练 JSONL，支持 instruct 与 pretrain 风格
  • preprocess_images.py：使用 VAE 编码器预编码图像为潜在表示，加速训练
• 训练脚本
  • train_multimodal.py：主训练脚本，支持纯文本与图像生成训练
  • train.sh：纯文本微调示例（2 GPU + DeepSpeed，默认 Alpaca 数据集）
  • train_image.sh：图像生成训练示例
  • train_image_qlora.sh：单 GPU 内存高效图像生成训练（4-bit/8-bit）
  • train_slurm.sh / train_image_slurm.sh：Slurm 集群多节点版本
• 高级特性
  • 可控制文本与图像损失权重
  • 流匹配权重方案：sigma_sqrt、logit_normal、mode、cosmap、none
  • 支持 moe_drop_tokens 以在大分辨率下节省显存

使用方式

1. 从官方仓库下载基础模型
2. 准备训练数据（JSONL 格式，支持纯文本、instruct 风格图像生成、pretrain 风格图像生成）
3. 配置训练脚本
4. 运行训练：

   # 纯文本微调
   bash train.sh
   # 图像生成训练
   bash train_image.sh
   # Slurm 集群
   bash train_slurm.sh
   

适用场景与限制

• 适用于对 HunyuanImage-3.0 进行社区微调、风格适配器训练、文本到图像生成定制。
• 训练需要较高显存，QLoRA 可降低门槛；显存需求基于 batch size 1 与短提示词（<50 tokens）测试，长提示词或更大 batch 需更多显存。
• 图像理解流程尚未实现。
• 仓库仅包含训练脚本，推理代码与文档请参考官方仓库。
• 全量模型训练需要显著更多显存，示例未涵盖。
• 官方仓库 tokenizer_wrapper.py 存在 instruct 风格训练的 bug，本仓库已修复。
• 许可：本仓库为 AGPL；官方 Hunyuan Image 3.0 仓库为腾讯混元社区许可协议。