本文档说明如何使用 Z-Image 训练环境进行 LoRA 训练。

• dataset-z.toml - Z-Image 数据集配置
• cache-z.sh - 缓存文本编码器输出
• latent-z.sh - 缓存 VAE latent
• train-z.sh - Z-Image LoRA 训练脚本
• run-z.sh - 一键运行所有流程

• dataset.toml - Qwen 数据集配置
• cache.sh - Qwen 缓存文本编码器输出
• latent.sh - Qwen 缓存 latent
• train.sh - Qwen 训练脚本
• run_all.sh - Qwen 一键运行脚本

• image/ - 训练图像目录（两者共用）
• prompt.txt - 采样提示词（两者共用）

• output/ - Qwen 训练输出
• output-z/ - Z-Image 训练输出
• cache/ - Qwen 缓存目录
• cache-z/ - Z-Image 缓存目录

bash run-z.sh

这个脚本会自动依次执行：

1. 缓存文本编码器输出 (cache-z.sh)
2. 缓存 VAE latent (latent-z.sh)
3. 开始 LoRA 训练 (train-z.sh)

如果需要分步执行，可以单独运行各个脚本：

bash cache-z.sh

bash latent-z.sh

bash train-z.sh

Z-Image 使用以下模型：

• DiT: /workspace/ai-toolkit-Z-Image-Turbo/Z-Image-Turbo/transformer/diffusion_pytorch_model-00001-of-00003.safetensors
• VAE: /workspace/ai-toolkit-Z-Image-Turbo/Z-Image-Turbo/vae/diffusion_pytorch_model.safetensors
• Text Encoder: /workspace/ai-toolkit-Z-Image-Turbo/Z-Image-Turbo/text_encoder/model-00001-of-00003.safetensors

• 分辨率: 1024x1024
• Batch Size: 2
• 重复次数: 20
• 启用分桶: 是

• 网络模块: networks.lora_zimage (Z-Image 专用)
• LoRA 维度: 32
• 学习率: 1e-4
• 优化器: adamw8bit
• 时间步采样: shift (discrete_flow_shift=2.0)
• 训练轮数: 16
• 保存频率: 每 1 个 epoch
• 采样频率: 每 1 个 epoch / 每 200 步

训练日志保存在 /workspace/output-z/logs，可以使用 TensorBoard 监控：

tensorboard --logdir /workspace/output-z/logs

• LoRA 权重: /workspace/output-z/zimage-lora-*.safetensors
• 采样图像: /workspace/output-z/sample/
• 训练日志: /workspace/output-z/logs/

Z-Image 使用 Turbo 版本，建议在 prompt.txt 中添加采样参数：

A beautiful landscape painting --n bad quality --w 1280 --h 720 --fs 3 --s 20 --d 1234 --l 5

参数说明：

• --n: 负面提示词
• --w: 宽度
• --h: 高度
• --fs: flow_shift (推荐 3.0)
• --s: 推理步数 (推荐 20)
• --d: 随机种子
• --l: CFG scale (推荐 5)

特性	Qwen	Z-Image
网络模块	networks.lora_qwen_image	networks.lora_zimage
时间步采样	shift (2.2)	shift (2.0)
学习率	2e-5	1e-4
模型类型	原始模型	Turbo 蒸馏模型
缓存目录	/workspace/cache	/workspace/cache-z
输出目录	/workspace/output	/workspace/output-z

1. 模型版本: 当前使用 Z-Image Turbo 版本，这是一个蒸馏模型，训练可能不稳定
2. 配置分离: Z-Image 和 Qwen 的配置完全独立，互不干扰
3. 缓存管理: 两个模型使用不同的缓存目录，避免混淆
4. 训练图像: 两者共用 /workspace/image 目录中的训练图像
5. 采样提示词: 建议为 Z-Image Turbo 模型添加 CFG 相关参数

如需修改训练参数，编辑以下文件：

• 数据集配置: dataset-z.toml
• 训练参数: train-z.sh
• 缓存参数: cache-z.sh 和 latent-z.sh

详细参数说明请参考：

• /workspace/musubi-tuner/docs/zimage.md - Z-Image 官方文档
• Z-Image 官方仓库: https://huggingface.co/Tongyi-MAI/Z-Image-Turbo

---

祝训练顺利！ 🎉