beycanai/z-image-turbo-realism

Z-Image-Turbo Realism (bf16, LoRA-merged UNet)

A single-file bf16 diffusion model (UNet only) for ComfyUI: Tongyi-MAI/Z-Image-Turbo with a realism LoRA and a flow-DPO LoRA baked into the weights. No LoRA loaders at inference — one file to download, which is the whole point of this repo.

Merge recipe

#	Component	Strength
0	z_image_turbo_bf16.safetensors (base, Tongyi-MAI/Z-Image-Turbo)	—
1	Realistic Snapshot – Z-Image Turbo	0.50
2	F16/z-image-turbo-flow-dpo	0.40

Merged with ComfyUI's stock LoraLoaderModelOnly, chained: UNETLoader → LoraLoaderModelOnly ×2 → ModelSave. The full merge graph is embedded in the .safetensors header (__metadata__.workflow / .prompt):

python -c "import json,struct;f=open('z-image-turbo-realism-bf16.safetensors','rb');n=struct.unpack('<Q',f.read(8))[0];print(json.loads(f.read(n))['__metadata__']['workflow'])"

Verified against the base

The merged weights were diffed tensor-by-tensor against vanilla z_image_turbo_bf16.safetensors (float32, from BF16 storage). Key set, shapes and dtypes match the base exactly — 453 tensors, 6,154,908,736 params, no key missing in either direction.

Tensors changed	180 of 453
Parameters changed	5.43 B of 6.15 B (88.2%)
Overall drift ‖ΔW‖_F / ‖W‖_F	4.11%

Changed: layers.0–29 attention.qkv, attention.out, feed_forward.w1/w2/w3, adaLN_modulation.0 — exactly the set the two adapters target. Untouched and bit-identical to the base: noise_refiner, context_refiner, x_embedder, cap_embedder, t_embedder, final_layer, every norm, and the pad tokens.

Recovering the effective strengths from the merged weights — reconstructing each adapter exactly (B @ A for the LoRA, kron(w1, w2) for the LoKr) and projecting the delta onto that basis — gives 0.500 for the realism LoRA on all 120 modules it touches, matching the configured strength. Nothing was silently dropped or rescaled.

Files

File	Params	Tensors	dtype	Size
z-image-turbo-realism-bf16.safetensors	6.15 B	453	BF16	~11.5 GiB
z-image-turbo-realism-int8_convrot.safetensors	6.15 B	857	INT8 ConvRot + F32	~5.8 GiB

File	Size (bytes)	sha256
z-image-turbo-realism-bf16.safetensors	12,309,879,928	f56818af5fe51a3ce4424240ce80a07243525f10c2965f6a0b5893fc91c8cc3b
z-image-turbo-realism-int8_convrot.safetensors	6,201,003,608	3d7ffc9f7ccdb165b50ff42da133e0394b09633b0270abf59d1c9e02e5838d45

Tensor keys are unprefixed (cap_embedder.0.weight, layers.0.…) — the model.diffusion_model. prefix that ComfyUI's ModelSave writes has been stripped. ComfyUI loads either form; some trainers (e.g. ostris/ai-toolkit) expect the bare keys, so this is the more portable of the two.

INT8 ConvRot

z-image-turbo-realism-int8_convrot.safetensors is an INT8 ConvRot conversion of z-image-turbo-realism-bf16.safetensors for ComfyUI. It loads with the same Load Diffusion Model (UNETLoader) node (weight_dtype default) and needs a ComfyUI with comfy-kitchen INT8 ConvRot support.

Conversion recipe

The reference is Comfy-Org/z_image_turbo split_files/diffusion_models/z_image_turbo_int8_convrot.safetensors (sha256 be517ebd47c912a5626a588e1aeea43e6be4a43c0cdcd2b48a2a780d9f358635). Its header defines the per-key rule (which tensors are quantized, the .comfy_quant JSON, dtypes), mirrored key-for-key.

INT8 ConvRot (202 tensors): int8_tensorwise with a per-row F32 weight_scale of shape [N, 1] and ConvRot enabled.

Tensors	Count	ConvRot group size
layers.0–29, noise_refiner.0–1, context_refiner.0–1: attention.qkv, attention.out, feed_forward.w1/w2/w3	170	256
adaLN_modulation.0 in layers.0–29 and noise_refiner.0–1 (in_features 256)	32	256

Not quantized (251 tensors): x_embedder, cap_embedder, t_embedder, final_layer, all biases, all norms and the pad tokens — stored as F32, as in the reference. They are exact FP32 upcasts of the bf16 values (lossless). These are exactly the tensors the reference keeps unquantized.

Each quantized layer carries a .comfy_quant U8 tensor with the same JSON as the reference: {"format": "int8_tensorwise", "convrot": true, "convrot_groupsize": 256}.

supermind's INT8 ConvRot build of Z-Image-Turbo (supermind/int8_convrot_models) quantizes the same 202 tensors with the same scale rule but keeps the non-quantized tensors in BF16; this file follows the Comfy-Org layout.

Scale rule. The reference scales are not plain absmax: a per-row absmax quantizer (comfy-kitchen's TensorWiseINT8Layout.quantize) changes 48 % of the reference's int8 values. The rule was recovered from the reference itself and reproduces it (see Verification):

1. Upcast the BF16 weight to FP32 and apply the ConvRot rotation W · Hᵀ (block Hadamard, group size 256) with comfy-kitchen's portable implementation.
2. For every output row r, try the 80 clip ratios c = torch.linspace(0.55, 1.0, 80), with s = absmax(r) · c / 127 and q = clamp(round(r / s), −127, 127).
3. Keep the c with the smallest Σ (q·s − r)²; on an exact tie the smaller c wins. Store q as I8 and s as the F32 weight_scale.

comfy-kitchen 0.2.35, CUDA device. __metadata__ records the source file name, source sha256, recipe and reference.

Verification

Reproduction of the reference. The same script, run on the vanilla bf16 base (z_image_turbo_bf16.safetensors from Comfy-Org/z_image_turbo), was compared with the Comfy-Org INT8 file tensor by tensor:

Key set, dtypes, shapes	identical (857 tensors)
Non-quantized tensors, bit-identical	251 / 251 (plus all 202 .comfy_quant payloads)
INT8 values differing	1,797 of 6,142,033,920 (2.9 × 10⁻⁷), all by ±1
weight_scale tensors bit-identical	168 / 202
Scales differing by 1 ulp (≤ 2 × 10⁻⁷ relative)	4,932 of 1,840,640 rows
Rows with a different clip ratio	1 (layers.12.feed_forward.w2, row 1791)

The one row with a different clip ratio is an FP32 near-tie: the two candidate ratios give quantization errors that differ by 1.6 × 10⁻⁷ relative, about one ulp of the sum, so the choice depends on summation order. The 1-ulp scale differences have the same origin. Both are at the level of floating-point rounding, not a different recipe.

Dequantization check. Each INT8 tensor of this file was dequantized through ComfyUI's own comfy_kitchen path (inverse Hadamard rotation included) and compared with z-image-turbo-realism-bf16.safetensors:

Quantized tensors	202
Cosine, mean / min	0.999962 / 0.999928
Relative error, mean / max	0.87 % / 1.20 %
Cosine without inverse rotation, mean (control)	0.061
Non-quantized tensors identical to the bf16 file	251 / 251 (exact F32 upcast)

Layout check. 857 tensors; key set, dtypes, shapes and all 202 .comfy_quant payloads are identical to the reference. Only __metadata__ differs.

Load check. comfy.sd.load_diffusion_model (the UNETLoader path, ComfyUI 1568e6c) detects ZImage (Lumina2), 202 of 208 Linear layers loaded as int8_tensorwise (ConvRot, group size 256), no missing or left-over keys.

Usage (ComfyUI)

Put the file in ComfyUI/models/diffusion_models/ and load it with Load Diffusion Model (UNETLoader). UNet only — the stock Z-Image encoder and VAE are still required:

• Text encoder: qwen_3_4b.safetensors → CLIPLoader, type lumina2
• VAE: ae.safetensors → VAELoader

Settings used for the example images

• ModelSamplingAuraFlow shift 3.0
• Pass 1: 1024×1536, dpmpp_sde / beta, 9 steps, cfg 1.0, denoise 1.0
• Latent upscale ×1.25 → 1280×1920, Pass 2: same sampler, denoise 0.45

Turbo model: keep cfg at 1.0. 8–10 steps is the useful range.

Examples

examples/merged-v1/ — this merge. examples/base/ — vanilla Z-Image-Turbo, same seed (310411576115418), same prompt, same sampler settings.

base	merged

The example PNGs do not carry generation metadata.

Download

pip install -U huggingface_hub
hf download beycanai/z-image-turbo-realism z-image-turbo-realism-bf16.safetensors \
  --local-dir ComfyUI/models/diffusion_models

INT8 ConvRot:

hf download beycanai/z-image-turbo-realism z-image-turbo-realism-int8_convrot.safetensors \
  --local-dir ComfyUI/models/diffusion_models

Notes

• The bf16 file is not quantized; for less VRAM use the INT8 ConvRot file above, or quantize to fp8/GGUF yourself.
• Merged strengths are fixed; re-merge from the base if you want a different balance.
• Usable as a LoRA-training base when you want the realism prior already baked in.

Credits

• Base model: Tongyi-MAI/Z-Image-Turbo (Apache-2.0)
• Realistic Snapshot – Z-Image Turbo — Civitai license terms apply to this merge as well
• F16/z-image-turbo-flow-dpo