---
license: apache-2.0
tags:
  - text-to-image
  - int8
  - quantized
  - convrot
  - comfyui
  - z-image
base_model:
  - Tongyi-MAI/Z-Image-Turbo
  - Tongyi-MAI/Z-Image
---

# Z-Image Turbo + Base — INT8 ConvRot (with Qwen 3 4B Text Encoder)
![Z-Image Promotion](https://huggingface.co/Winnougan/Z-Image-Base-Turbo-INT8-Convrot/resolve/main/Z-Image%20Promotion-topaz-upscale-4x.png)

INT8 row-wise quantized versions of **Z-Image Base** and **Z-Image Turbo**, using ConvRot (Hadamard-rotation outlier suppression) for improved quantization fidelity, plus a matching INT8 ConvRot quantization of the Qwen 3 4B text encoder. Converted with [convert_to_quant](https://github.com/silveroxides/convert_to_quant) for native ComfyUI compatibility.

## Files

| File | Description |
|---|---|
| `z_image_int8_convrot.safetensors` | Z-Image Base, INT8 + ConvRot |
| `z_image_turbo_int8_convrot.safetensors` | Z-Image Turbo, INT8 + ConvRot |
| `qwen_3_4b_int8_convrot.safetensors` | Qwen 3 4B text encoder, INT8 + ConvRot |

## Why ConvRot + Row-Wise Scaling

ConvRot applies a group-wise Hadamard rotation to suppress weight outliers before quantization, improving INT8 fidelity versus plain per-tensor or per-row quantization alone. Critically, **these conversions use `--scaling_mode row`, not `tensor`**. Tensor-wise scaling computes a single scale factor for an entire weight matrix; even a small number of outlier values forces that global scale to widen, coarsening quantization precision across the rest of the matrix. In testing, this combination (ConvRot + tensor-wise scaling) produced visibly fuzzy, detail-smoothed output. Switching to row-wise scaling — which computes an independent scale per row, isolating outliers to the rows that contain them — resolved this and produced output sharpness matching or exceeding plain INT8 row-wise quantization.

If you encounter other ConvRot-quantized models with soft or "waxy" output, this scaling mode mismatch is the most likely culprit.

## Quantization Recipe

```
ctq -i <model>.safetensors -o <model>-int8-convrot.safetensors \
  --int8 --scaling_mode row --simple --low-memory \
  --convrot --convrot-group-size 64 \
  --zimage --comfy_quant --save-quant-metadata
```

The Qwen 3 4B text encoder was converted with the same flags, omitting `--zimage` (no architecture-specific preset needed for this text encoder; verify its native hidden dimensions divide cleanly by the chosen group size before quantizing).

### Why group size 64

ComfyUI's `comfy_kitchen` runtime requires the ConvRot Hadamard block size to be a power of 4 (4, 16, 64, 256, 1024…), not merely a power of 2. A group size of 64 was chosen because it divides cleanly into every 2D weight dimension in the Z-Image architecture, requiring no manual layer exclusions.

## Usage in ComfyUI

Load `z_image_int8_convrot.safetensors` or `z_image_turbo_int8_convrot.safetensors` with a standard `UNETLoader` node, and `qwen_3_4b_int8_convrot.safetensors` with a `CLIPLoader` node (type: your Z-Image workflow's text encoder type). No special ConvRot-aware nodes are required; the rotation metadata is embedded via `--save-quant-metadata` and read automatically by ComfyUI's mixed-precision quantization ops.

## Hardware

Converted and tested on an RTX 3070 (8GB VRAM) using `--low-memory` streaming conversion.

## Credits

Quantization tooling: [silveroxides/convert_to_quant](https://github.com/silveroxides/convert_to_quant)
Base models: [Tongyi-MAI/Z-Image](https://huggingface.co/Tongyi-MAI/Z-Image), [Tongyi-MAI/Z-Image-Turbo](https://huggingface.co/Tongyi-MAI/Z-Image-Turbo)