Z-Image.md

Z-Image

Z-Image 是由阿里巴巴通义实验室多模态交互团队训练并开源的图像生成模型。

安装

在使用本项目进行模型推理和训练前，请先安装 DiffSynth-Studio。

git clone https://github.com/modelscope/DiffSynth-Studio.git
cd DiffSynth-Studio
pip install -e .

更多关于安装的信息，请参考安装依赖。

快速开始

运行以下代码可以快速加载 Tongyi-MAI/Z-Image-Turbo 模型并进行推理。FP8 精度量化会导致明显的图像质量劣化，因此不建议在 Z-Image Turbo 模型上开启任何量化，仅建议开启 CPU Offload，最低 8G 显存即可运行。

from diffsynth.pipelines.z_image import ZImagePipeline, ModelConfig
import torch

vram_config = {
    "offload_dtype": torch.bfloat16,
    "offload_device": "cpu",
    "onload_dtype": torch.bfloat16,
    "onload_device": "cpu",
    "preparing_dtype": torch.bfloat16,
    "preparing_device": "cuda",
    "computation_dtype": torch.bfloat16,
    "computation_device": "cuda",
}
pipe = ZImagePipeline.from_pretrained(
    torch_dtype=torch.bfloat16,
    device="cuda",
    model_configs=[
        ModelConfig(model_id="Tongyi-MAI/Z-Image-Turbo", origin_file_pattern="transformer/*.safetensors", **vram_config),
        ModelConfig(model_id="Tongyi-MAI/Z-Image-Turbo", origin_file_pattern="text_encoder/*.safetensors", **vram_config),
        ModelConfig(model_id="Tongyi-MAI/Z-Image-Turbo", origin_file_pattern="vae/diffusion_pytorch_model.safetensors", **vram_config),
    ],
    tokenizer_config=ModelConfig(model_id="Tongyi-MAI/Z-Image-Turbo", origin_file_pattern="tokenizer/"),
    vram_limit=torch.cuda.mem_get_info("cuda")[1] / (1024 ** 3) - 0.5,
)
prompt = "Young Chinese woman in red Hanfu, intricate embroidery. Impeccable makeup, red floral forehead pattern. Elaborate high bun, golden phoenix headdress, red flowers, beads. Holds round folding fan with lady, trees, bird. Neon lightning-bolt lamp (⚡️), bright yellow glow, above extended left palm. Soft-lit outdoor night background, silhouetted tiered pagoda (西安大雁塔), blurred colorful distant lights."
image = pipe(prompt=prompt, seed=42, rand_device="cuda")
image.save("image.jpg")

模型总览

模型 ID	推理	低显存推理	全量训练	全量训练后验证	LoRA 训练	LoRA 训练后验证
Tongyi-MAI/Z-Image	code	code	code	code	code	code
DiffSynth-Studio/Z-Image-i2L	code	code	-	-	-	-
Tongyi-MAI/Z-Image-Turbo	code	code	code	code	code	code
PAI/Z-Image-Turbo-Fun-Controlnet-Union-2.1	code	code	code	code	code	code
PAI/Z-Image-Turbo-Fun-Controlnet-Union-2.1-8steps	code	code	code	code	code	code
PAI/Z-Image-Turbo-Fun-Controlnet-Tile-2.1-8steps	code	code	code	code	code	code

特殊训练脚本：

• 差分 LoRA 训练：doc、code
• 轨迹模仿蒸馏训练（实验性功能）：code

模型推理

模型通过 ZImagePipeline.from_pretrained 加载，详见加载模型。

ZImagePipeline 推理的输入参数包括：

• prompt: 提示词，描述画面中出现的内容。
• negative_prompt: 负向提示词，描述画面中不应该出现的内容，默认值为 ""。
• cfg_scale: Classifier-free guidance 的参数，默认值为 1。
• input_image: 输入图像，用于图生图，该参数与 denoising_strength 配合使用。
• denoising_strength: 去噪强度，范围是 0～1，默认值为 1，当数值接近 0 时，生成图像与输入图像相似；当数值接近 1 时，生成图像与输入图像相差更大。在不输入 input_image 参数时，请不要将其设置为非 1 的数值。
• height: 图像高度，需保证高度为 16 的倍数。
• width: 图像宽度，需保证宽度为 16 的倍数。
• seed: 随机种子。默认为 None，即完全随机。
• rand_device: 生成随机高斯噪声矩阵的计算设备，默认为 "cpu"。当设置为 cuda 时，在不同 GPU 上会导致不同的生成结果。
• num_inference_steps: 推理次数，默认值为 8。
• controlnet_inputs: ControlNet 模型的输入。
• edit_image: 编辑模型的待编辑图像，支持多张图像。
• positive_only_lora: 仅在正向提示词中使用的 LoRA 权重。

如果显存不足，请开启显存管理，我们在示例代码中提供了每个模型推荐的低显存配置，详见前文"模型总览"中的表格。

模型训练

Z-Image 系列模型统一通过 examples/z_image/model_training/train.py 进行训练，脚本的参数包括：

• 通用训练参数
  • 数据集基础配置
    • --dataset_base_path: 数据集的根目录。
    • --dataset_metadata_path: 数据集的元数据文件路径。
    • --dataset_repeat: 每个 epoch 中数据集重复的次数。
    • --dataset_num_workers: 每个 Dataloder 的进程数量。
    • --data_file_keys: 元数据中需要加载的字段名称，通常是图像或视频文件的路径，以 , 分隔。
  • 模型加载配置
    • --model_paths: 要加载的模型路径。JSON 格式。
    • --model_id_with_origin_paths: 带原始路径的模型 ID，例如 "Tongyi-MAI/Z-Image-Turbo:transformer/*.safetensors"。用逗号分隔。
    • --extra_inputs: 模型 Pipeline 所需的额外输入参数，例如训练图像编辑模型时需要额外参数，以 , 分隔。
    • --fp8_models：以 FP8 格式加载的模型，格式与 --model_paths 或 --model_id_with_origin_paths 一致，目前仅支持参数不被梯度更新的模型（不需要梯度回传，或梯度仅更新其 LoRA）。
  • 训练基础配置
    • --learning_rate: 学习率。
    • --num_epochs: 轮数（Epoch）。
    • --trainable_models: 可训练的模型，例如 dit、vae、text_encoder。
    • --find_unused_parameters: DDP 训练中是否存在未使用的参数，少数模型包含不参与梯度计算的冗余参数，需开启这一设置避免在多 GPU 训练中报错。
    • --weight_decay：权重衰减大小，详见 torch.optim.AdamW。
    • --task: 训练任务，默认为 sft，部分模型支持更多训练模式，请参考每个特定模型的文档。
  • 输出配置
    • --output_path: 模型保存路径。
    • --remove_prefix_in_ckpt: 在模型文件的 state dict 中移除前缀。
    • --save_steps: 保存模型的训练步数间隔，若此参数留空，则每个 epoch 保存一次。
  • LoRA 配置
    • --lora_base_model: LoRA 添加到哪个模型上。
    • --lora_target_modules: LoRA 添加到哪些层上。
    • --lora_rank: LoRA 的秩（Rank）。
    • --lora_checkpoint: LoRA 检查点的路径。如果提供此路径，LoRA 将从此检查点加载。
    • --preset_lora_path: 预置 LoRA 检查点路径，如果提供此路径，这一 LoRA 将会以融入基础模型的形式加载。此参数用于 LoRA 差分训练。
    • --preset_lora_model: 预置 LoRA 融入的模型，例如 dit。
  • 梯度配置
    • --use_gradient_checkpointing: 是否启用 gradient checkpointing。
    • --use_gradient_checkpointing_offload: 是否将 gradient checkpointing 卸载到内存中。
    • --gradient_accumulation_steps: 梯度累积步数。
  • 图像宽高配置（适用于图像生成模型和视频生成模型）
    • --height: 图像或视频的高度。将 height 和 width 留空以启用动态分辨率。
    • --width: 图像或视频的宽度。将 height 和 width 留空以启用动态分辨率。
    • --max_pixels: 图像或视频帧的最大像素面积，当启用动态分辨率时，分辨率大于这个数值的图片都会被缩小，分辨率小于这个数值的图片保持不变。
• Z-Image 专有参数
  • --tokenizer_path: tokenizer 的路径，适用于文生图模型，留空则自动从远程下载。

我们构建了一个样例图像数据集，以方便您进行测试，通过以下命令可以下载这个数据集：

modelscope download --dataset DiffSynth-Studio/example_image_dataset --local_dir ./data/example_image_dataset

我们为每个模型编写了推荐的训练脚本，请参考前文"模型总览"中的表格。关于如何编写模型训练脚本，请参考模型训练；更多高阶训练算法，请参考训练框架详解。

训练技巧：

• Tongyi-MAI/Z-Image-Turbo 是一个蒸馏加速的模型，因此直接训练将会迅速让模型失去加速能力，以“加速配置”（num_inference_steps=8，cfg_scale=1）推理的效果变差，以“无加速配置”（num_inference_steps=30，cfg_scale=2）推理的效果变好。可采用以下方案训练和推理：
  • 标准 SFT 训练（code） + 无加速配置推理
  • 差分 LoRA 训练（code） + 加速配置推理
    • 差分 LoRA 训练中需加载一个额外的 LoRA，例如 ostris/zimage_turbo_training_adapter
  • 标准 SFT 训练（code）+ 轨迹模仿蒸馏训练（code）+ 加速配置推理
  • 标准 SFT 训练（code）+ 推理时加载蒸馏加速 LoRA（model） + 加速配置推理