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

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.

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

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.

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. 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. 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. 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:

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:

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.

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