README.md

---
license: apache-2.0
base_model: Tongyi-MAI/Z-Image-Turbo
pipeline_tag: text-to-image
library_name: diffusers
tags:
  - z-image
  - nunchaku
  - svdquant
  - int4
  - quantization
---

# Z-Image-Turbo Nunchaku Lite INT4 r32

Diffusers-loadable conversion of:

- Base model: `Tongyi-MAI/Z-Image-Turbo`
- Source repo: `nunchaku-ai/nunchaku-z-image-turbo`
- Source checkpoint: `svdq-int4_r32-z-image-turbo.safetensors`

The transformer uses `quant_method: nunchaku_lite`, INT4 SVDQ, group size 64, rank 32, and 238 quantized targets. Packed fused QKV and SwiGLU projections are split in logical layout into the stock Z-Image graph. The Qwen3 text encoder is packaged with BitsAndBytes 4-bit NF4.

## Benchmark

| Checkpoint | Latency | Max VRAM |
| --- | ---: | ---: |
| Converted Diffusers Nunchaku Lite INT4 r32 + BNB4 Qwen3 | 6.03 s (stdev 0.00 s) | 12.01 GiB |

RTX 5090, 1024×1024, 9 scheduler steps (8 DiT forwards), guidance scale 0, seed 42, one warmup and three measured runs. VRAM is peak total device usage sampled through `nvidia-smi`. The native row uses the base model's BF16 Qwen3 encoder.

## Output Comparison

![Native reference (left) and converted output (right)](output_comparison.png)

Both images use the same prompt, seed, scheduler, resolution, and step count. Native Nunchaku 1.x selects NVFP4 kernels on Blackwell, so the comparison uses native NVFP4 as a visual reference only (cross-precision MAE 23.37, RMSE 30.81).

## Run

Requires the Hugging Face `kernels` package and an NVIDIA Turing, Ampere, Ada, or Blackwell (not Hopper) GPU.

```python
import torch
from diffusers import ZImagePipeline

pipe = ZImagePipeline.from_pretrained(
    "lite-infer/z-image-turbo-nunchaku-lite-int4_r32-bnb4-text-encoder",
    torch_dtype=torch.bfloat16,
).to("cuda")

image = pipe(
    prompt='A cinematic portrait of a red fox in a misty forest at sunrise, detailed fur, volumetric light',
    height=1024,
    width=1024,
    num_inference_steps=9,
    guidance_scale=0.0,
    generator=torch.Generator("cuda").manual_seed(42),
).images[0]
image.save("output.png")
```