README.md

---
license: apache-2.0
language:
- en
pipeline_tag: text-to-image
tags:
- text-to-image
- diffusers
- ZImagePipeline
library_name: diffusers
base_model:
- Tongyi-MAI/Z-Image-Turbo
---


## ✨ Z-Image-Turbo FP32 / FP16 / BF16 EMA-ONLY & FULL

Multiple versions of Z-Image-Turbo model in various precisions and configurations, prepared directly from the original [Tongyi-MAI/Z-Image-Turbo](https://huggingface.co/Tongyi-MAI/Z-Image-Turbo) repository.

## 📦 Available Variants

| Type | Precision | Size | Description |
|------|-----------|------|-------------|
| **Full** | FP32/FP16/BF16 | Largest | Complete model with training and EMA parameters |
| **EMA-only** | FP32/FP16/BF16 | Smaller | Only EMA parameters - **recommended for inference** |

### EMA vs Full - Which to Choose?

- **EMA-only**: Contains only Exponential Moving Average parameters - averaged weights from training process. Provides more stable and better results during image generation, smaller file size. **Use this for inference.**
  
- **Full**: Contains all parameters (training + EMA). Only needed if you want to continue training the model.

## 🔧 Preparation Process

Models were processed using:

1. **[merge-safetensors](https://github.com/dkotel/merge-safetensors)** - merging split transformer parts into single `*.safetensors` file (placed in `transformer` directory)

2. **[PyTorch-Precision-Converter](https://github.com/angelolamonaca/PyTorch-Precision-Converter)** - converting precision from FP32 to FP16/BF16 and creating EMA-only variants

## 💡 For Diffusers Users

> ⚠️ **This is NOT compatible with ComfyUI** - models are prepared for `diffusers` library.

### Required File Names

To use with `ZImagePipeline` without specifying full paths, rename model files in appropriate folders:
```
text_encoder/
  └── model.safetensors              # Text encoder

transformer/
  └── diffusion_pytorch_model.safetensors   # Transformer

vae/
  └── diffusion_pytorch_model.safetensors   # VAE
```

### Example Usage (based on one from original repo)

`pip install git+https://github.com/huggingface/diffusers`


```python
import torch
from diffusers import ZImagePipeline

# 1. Load the pipeline
# Use bfloat16 for optimal performance on supported GPUs
pipe = ZImagePipeline.from_pretrained(
    "path/to/model_files_main_dir",
    torch_dtype=torch.float32, # or torch.bfloat16 / torch.float16
    low_cpu_mem_usage=False,
)
pipe.to("cuda")

# [Optional] Attention Backend
# Diffusers uses SDPA by default. Switch to Flash Attention for better efficiency if supported:
# pipe.transformer.set_attention_backend("flash")    # Enable Flash-Attention-2
# pipe.transformer.set_attention_backend("_flash_3") # Enable Flash-Attention-3

# [Optional] Model Compilation
# Compiling the DiT model accelerates inference, but the first run will take longer to compile.
# pipe.transformer.compile()

# [Optional] CPU Offloading
# Enable CPU offloading for memory-constrained devices.
# pipe.enable_model_cpu_offload()

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."

# 2. Generate Image
image = pipe(
    prompt=prompt,
    height=1024,
    width=1024,
    num_inference_steps=9,  # This actually results in 8 DiT forwards
    guidance_scale=0.0,     # Guidance should be 0 for the Turbo models
    generator=torch.Generator("cuda").manual_seed(42),
).images[0]

image.save("example.png")

```

## 🎯 Recommendations

- **RTX 3060 and similar**: Use **BF16** or **FP16** for optimal performance
- **Less than 12GB VRAM**: **FP16 EMA-only** 
- **12GB+ VRAM**: **BF16 EMA-only** (better numerical stability)
- **Training**: **FP32 Full**

## 📝 License

Same as original [Z-Image-Turbo](https://huggingface.co/Tongyi-MAI/Z-Image-Turbo) model.



README was generated with a help of AI


```bibtex
@article{team2025zimage,
  title={Z-Image: An Efficient Image Generation Foundation Model with Single-Stream Diffusion Transformer},
  author={Z-Image Team},
  journal={arXiv preprint arXiv:2511.22699},
  year={2025}
}

@article{liu2025decoupled,
  title={Decoupled DMD: CFG Augmentation as the Spear, Distribution Matching as the Shield},
  author={Dongyang Liu and Peng Gao and David Liu and Ruoyi Du and Zhen Li and Qilong Wu and Xin Jin and Sihan Cao and Shifeng Zhang and Hongsheng Li and Steven Hoi},
  journal={arXiv preprint arXiv:2511.22677},
  year={2025}
}

@article{jiang2025distribution,
  title={Distribution Matching Distillation Meets Reinforcement Learning},
  author={Jiang, Dengyang and Liu, Dongyang and Wang, Zanyi and Wu, Qilong and Jin, Xin and Liu, David and Li, Zhen and Wang, Mengmeng and Gao, Peng and Yang, Harry},
  journal={arXiv preprint arXiv:2511.13649},
  year={2025}
}
```