justintime47/Z-Image-Turbo-iQ4.5

Z-Image-Turbo — iQ 4.5

MLX only. An imatrix-calibrated conversion of Tongyi-MAI/Z-Image-Turbo for mlx-serve on Apple Silicon. The weights are MLX's packed affine format, so diffusers, ComfyUI and GGUF runtimes cannot load them.

Requires an mlx-serve build with Z-Image support, which no release includes yet. Build from feat/zimage-calibrated-quant, which also carries the text-encoder cache fix: without it, every request after a server's first is conditioned on the earlier prompts.

	this pack	upstream release (fp32)
total on disk	5.91 GB	32.9 GB
transformer	3.46 GB at 4.5 bits per weight	24.6 GB
text encoder	2.26 GB at 4.5 bits per weight	8.05 GB
VAE	0.17 GB, unchanged	0.17 GB

Bits per weight count the stored scales and biases, so 4.5 is the size of plain 4-bit group-64 quantization. Keep "turbo" in the directory name: mlx-serve reads it to choose Turbo's sampling (8 steps, no CFG).

How it was made

• Calibration from the engine itself. Per-input-channel activation statistics for all 276 transformer linears were collected inside mlx-serve while it generated 73 varied prompts (portraits, landscapes, illustration styles, product shots, lettering). The first 20 ran at full size across four aspect ratios at 8 steps. The other 53 ran at 256px and 1 step: the caption-only context refiner needs many prompts, not large images, and small renders add little to the image-token statistics.
• Weighted scale search. Each quantization group's scale and bias come from an activation-weighted least-squares search, with min/max only as the starting point.
• Measured bit allocation. Every linear's error was measured at 3, 4, 5, 6 and 8 bits, and the transformer's widths (3bit x55, 4bit x154, 5bit x29, bf16 x38) were bought by error saved per byte inside the budget.
• Conditioning tensors kept wide. The timestep MLP, the caption and patch embedders, the final layer and every block's adaLN modulation are held at bf16.
• Text encoder by weight error. The Qwen3 text encoder runs through mlx-serve's chat loader, which collects no statistics, so its widths come from the weight-only search (3bit x30, 4bit x136, 5bit x68, 6bit x19), token table included. down_proj in the layers llama.cpp's Q4_K_M widens is held at 6-bit or wider. Z-Image reads the residual after layer 34, so layer 35 never runs and is stored at 3-bit.
• VAE untouched. No AWQ-style scale folding, so runtime LoRAs would still compose with the stored weights.