Z-Image 微调教程｜几十张图定制你的专属角色与风格

• GPU：推荐配置 NVIDIA 4090 (48GB VRAM) 或更高，最低配置 NVIDIA RTX 3090 / 4090 (24GB VRAM) 

• 内存：推荐配置 64 GB，最低配置 32GB

• 存储：推荐配置 SSD 500GB+，最低配置 100GB 可用空间

本教程使用 HHyTuner 训练器，它已内置完整的 Python 3.12 + PyTorch + Diffusers 环境，无需手动安装依赖，开箱即用。

可以通过 Hugging Face 或魔搭社区下载Z-Image 基础模型，模型选择：Tongyi-MAI/Z-Image。

创建一个名为 train_data 的文件夹，内部结构如下：

•  train_data/                    # 训练数据根目录
•    ├── image1.jpg              # 训练图片
•    ├── image1.txt              # 对应的描述文本
•    ├── image2.png
•    ├── image2.txt
•    └── ...

💡提示：每张图片必须有一个 .txt 同名文件，用于描述图像内容。

数量：10–100 张（新手建议 20–50 张）

格式：JPG、PNG、WEBP 均可

分辨率：建议 ≥1024×1024（模型原生支持 1024 分辨率）

质量：清晰、无模糊、无严重压缩

一致性：所有图片应围绕同一角色或风格

多样性：包含不同角度、光照、背景（避免过拟合）

Caption 是对图片内容的文字描述，是模型学习的关键依据，非常重要！每张训练图片都应配有一个同名的  .txt 文件。例如：图片文件 image1.jpg；对应描述：image1.txt。

在编写 Caption 时，需要遵循以下原则： 

• 使用自然语言，像你在向别人描述这张图一样； 

• 包含主体、风格、细节（如人物特征、服装、场景、光照、画风等）； 

• 长度建议 20–100 字，既不要太简略，也不要堆砌无意义的细节。

💡提示：如果某些图片未提供 .txt 文件，系统会使用 default_caption 作为默认描述。你可以在配置中按需设置它（如“动漫插画，精细线条”或“写实人像，自然光”），以保证训练一致性。

在开始训练前，你需要创建一个配置文件（或直接在脚本中定义），指定模型、数据、训练策略等关键参数。以下是基于 HHyTuner 的完整配置说明：

• checkpoint_every_n_steps: 每 N 步保存一次检查点（默认 500）

• checkpoints_total_limit: 最多保留几个检查点（默认 3）

• 自动删除旧检查点，节省空间。

• use_caption: 是否使用 caption（默认 True）

• caption_ext: caption 文件扩展名 （默认 ".txt"）

• default_caption: 默认 caption 文本

• prompt_dropout_prob: dropout 概率（默认 0.1）

• full_training: 训练模式选择

• False: LoKr 微调 （推荐，默认）

• True: 全量训练（需要大量显存）

• 时间步采样（控制训练哪个噪声范围）

• timestep_type: "sigmoid" （推荐）或 "uniform"

• min_timestep: 最小时间步 （None=0）

• max_timestep: 最大时间步 （None=1000）

• 优化相关

• lr_warmup_steps: 学习率预热步数（默认 100）

• gradient_accumulation_steps: 梯度累积（默认 1）

• max_grad_norm: 梯度裁剪（默认 1.0）

• mixed_precision: 混合精度（默认 "bf16"）

接下来，我们将通过一个完整的训练脚本来启动 LoKr 微调。请在 hhytuner 项目根目录下新建一个名为 train.py 的文件，并填入以下代码：

# -*- coding: utf-8 -*-
import os
import sys
sys.path.insert(0, os.path.join(os.path.dirname(__file__), 'hhytuner_diffusers'))


from zimage_trainer import ZImageTrainer, ZImageConfig


# ==================== 训练配置 ====================
config = ZImageConfig(
    # ---------- 必填参数 ----------
    image_folder="./train_data",      # 修改为你的图片路径
    output_dir="./output",            # 输出目录

    # ---------- 模型设置 ----------
    model_id="Tongyi-MAI/Z-Image",  # 基础模型

    # ---------- 训练设置 ----------
    num_train_steps=1500,
    batch_size=1,
    learning_rate=1e-4,
    resolution=1024,

    # ---------- Caption 设置 ----------
    use_caption=True,
    caption_ext=".txt",
    default_caption="高质量，细节丰富，摄影作品",
    prompt_dropout_prob=0.1,

    # ---------- 检查点设置 ----------
    checkpoint_every_n_steps=500,
    checkpoints_total_limit=3,

    # ---------- 训练模式 ----------
    full_training=False,              # ← 关键！必须为 False

    # ---------- 高级设置 ----------
    cache_latents=True,
    gradient_accumulation_steps=1,
    lr_warmup_steps=100,
    max_grad_norm=1.0,
    mixed_precision="bf16",
    seed=42,
    use_tensorboard=True,
)


# ==================== 开始训练 ====================
print("=" * 60)
print(" ZImage LoKr 训练 ")
print("=" * 60)
print(f" 数据集: {config.image_folder}")
print(f" 输出目录: {config.output_dir}")
print(f" 训练步数: {config.num_train_steps}")
print(f" 批次大小: {config.batch_size}")
print(f" 分辨率: {config.resolution}")
print("=" * 60)
print()


trainer = ZImageTrainer(config)
trainer.train()


print()
print("=" * 60)
print(" 训练完成！")
print("=" * 60)
print(f" 模型已保存到: {config.output_dir}")
print("=" * 60)

一切准备就绪后，在 hhytuner 目录下运行以下命令即可开始训练：

python\python.exe train.py

训练分为初始化、正式训练和监控三个阶段，系统会自动处理所有流程，你只需确保配置正确并留足显存。

在初始化阶段，系统会先加载 Z-Image 模型、VAE 和 Qwen 文本编码器，并将 LoKr 模块注入到 Transformer 层中。首次运行时还会缓存所有图片的潜变量和文本嵌入（这一步较慢，但后续训练会明显提速）。

正式训练时，每个 step 会自动读取一张图片及其 .txt 描述，编码后与噪声一起输入模型，仅更新 LoKr 参数。整个过程无需干预，系统会按配置定期保存检查点。

你可以通过 TensorBoard 实时监控训练状态：

python -m tensorboard --logdir=./output/logs

访问 http://localhost:6006 即可查看 loss 曲线、学习率和训练速度。

训练完成后，可以运行推理脚本：

run_zimage_lokr_inference.bat

或者直接运行 Python：

python\python.exe inference\zimage_lokr_inference.py

• 按提示输入以下信息

• GPU 设备编号 (如果有多个 GPU)

• ZImage 模型路径 (基础模型)

• LoKr 权重路径 (训练输出的 .safetensors 文件)

• 提示词 (描述想要生成的图片)

• 负面提示词 (可选)

• CFG 强度 (推荐 5.0)

• 推理步数 (推荐 50)

• 图像宽度 (如 1024)

• 图像高度 (如 1024)

实用技巧：在提示输入 LoKr 权重路径时，直接按回车跳过，系统会用原模型生成对照图，让你直观看到微调前后的差异。

在实际训练中，你可能会遇到显存不足、效果不佳或过拟合等问题。以下是一些常见情况及应对建议：

• CUDA 显存不足：将分辨率从 1024 降至 768 或 512，并确保 batch_size=1；

• 训练效果不理想：通常因为数据量太少（可增加训练图片数量）、Caption 描述太简略（优化描述文本 ）、学习率不当（尝试 5e-5 或 2e-4）或训练步数不足（建议增加步数）；

• 过拟合（只能复现训练图，无法泛化）：可通过增加图片多样性、使用更多样化的 caption、提高 prompt_dropout_prob 或减少训练步数缓解；

• 推理报错：需检查模型路径是否正确、LoKr 权重文件是否完整、lokr_config.json 是否存在、使用的模型是否与训练时一致；

• 训练中断恢复：可使用 resume_from_checkpoint 参数。

config = ZImageConfig(
    ...
    resume_from_checkpoint="./output/checkpoints/checkpoint-1000",
    ... 
)

以下是关于 LoKr 的最佳实践整理：

• 数据准备：使用高分辨率、清晰无压缩的图片；确保内容高度一致（如同一角色或画风），同时覆盖多角度、多光照和多场景；每张图配 20–100 字的详细 Caption。 

• 数量建议：人物 30–50 张，艺术风格 50–100 张

• 训练参数： 

• 训练步数 ≥ 图片数量 × 2000 

• 学习率保持默认 1e-4

• 分辨率优先用 1024，显存不足可降至 768

• 效果评估：定期用不同检查点生成测试图，与原模型对比效果，并尝试不同提示词验证泛化能力。

我们期待看到你用 LoKr 创作出的独特作品！如遇问题，请检查训练日志输出、TensorBoard loss 曲线和生成图片质量。

项目地址 https://github.com/white-2023/whitetuner/

Z-Image地址 https://github.com/Tongyi-MAI/Z-Image

模型下载（Hugging Face）https://huggingface.co/Tongyi-MAI/Z-Image

模型体验（魔搭）https://modelscope.cn/models/Tongyi-MAI/Z-Image