---
license: apache-2.0
base_model:
  - Tongyi-MAI/Z-Image-Turbo
  - martin-rizzo/Z-Image-Turbo-INT8-ConvRot-ComfyUI
pipeline_tag: text-to-image
tags:
  - z-image
  - int8
  - apple-silicon
  - h3ddle
---

# Z-Image-Turbo, repackaged for H3ddle

The released weights rearranged into one file per subsystem so a native engine
can validate and demand-page each independently. **No tensor was retrained,
merged, pruned, or quantized here.**

| file | what |
|------|------|
| `transformer.safetensors` | 30 S3-DiT layers plus 2+2 refiners, int8 ConvRot |
| `text_encoder.safetensors` | Qwen3-4B |
| `vae_decoder.safetensors` | AutoencoderKL's decoder half |
| `tokenizer.json` | the released vocabulary, byte for byte |

## Measured performance versus the regular layout

On an M1 Pro, a matched 4,128-token transformer forward measured:

| comparison | regular / baseline | optimized path | resulting gain |
|---|---:|---:|---:|
| complete transformer forward | 23.9 s output-major | 22.5 s input-major | **5.9% (1.06x)** |
| individual INT8 projection shapes | 1.00x | about 1.09x | about 9% |

The numerical reference error remained unchanged at 3.25e-02. Actual complete
image-generation gains vary because text encoding and VAE decoding are not
changed by this layout.

## What was changed, and why

- **One file per subsystem.** Each can be checked against a reference and
  loaded on its own.
- **The autoencoder's encoder half is gone.** Text to image never encodes an
  image, so half of it is dead weight: 244 tensors down to 138, 167 MB to 99.
- **The int8 matrices are stored input-major**, transposed from the release.
  A GPU tile reading two weights a lane one output column apart finds them
  `input_dim` bytes apart in the original layout, so every lane of a simdgroup
  takes its own cache line. Transposed, both reads are adjacent — worth about
  9% on Apple silicon. Values are untouched, and ConvRot rotates the activation
  rather than the weight, so the quantization is unaffected.
- **The final layer's two small linears are back at bf16.** Together they are
  1.2M of 6.15B parameters — 2.5 MB against 1.2 — so the saving was never real,
  and `final_layer.linear` at [64, 3840] was the most aggressively quantized
  tensor in the model. This reverses quantization rather than applying it.
- **`recipe.json`** carries the constants that live only in the reference's
  Python: the flow-match shift, the latent scaling and shift, the DiT's
  hyperparameters. The engine reads them back instead of holding its own copy.

## Provenance and licences

Z-Image-Turbo is by Alibaba Tongyi Lab under the Apache License 2.0. The
diffusion transformer is the INT8-ConvRot quantization published by Martin
Rizzo, also Apache 2.0, copied layer for layer. Both licences travel with this
repository; see `NOTICE`.