z-image-turbo-qnn

Z-Image Turbo — Qualcomm NPU (QNN) build for Local Dream

⚠️ UNTESTED

These artifacts have never been run on a Snapdragon device. They were converted and compiled on a machine with no NPU, so nothing here has produced an image. They are published so they can be tested, not because they work.

What has been verified, and what has not:

Static export matches the reference pipeline	✅ bit-exact on CPU
ONNX matches PyTorch	✅ ~1e-6
Graphs accepted by qairt-converter	✅
Quantization error after w4a16	❌ never measured
Text encoder, caption branch and DiT part 1 load and run on an 8 Gen 2	✅ reported
The whole 33-graph DiT chain loading	❌ failed once, fixed, not yet retested
Output image quality	❌ unknown

If it does not work, that is expected rather than surprising. Please open an issue with logs. This banner will be removed once someone confirms a successful generation.

A conversion of Tongyi-MAI/Z-Image-Turbo — a 6B Scalable Single-Stream DiT with a Qwen3-4B text encoder and the Flux VAE — to Qualcomm QNN context binaries, for the zimage backend in Local Dream.

The APK

LocalDream-zimage-2.8.1-arm64-v8a-UNTESTED-debug.apk in this repo is a build of Local Dream with --type zimage support compiled in — the stock releases do not have it, so the weights below need this build (or your own from source).

It is built from claude/zimage-q2-runner-ftk3lo, against the 33-graph DiT below — an older build will not load this model.

It is a debug build: installable and signed with the standard Android debug key, so it coexists with a Play/release install rather than upgrading it. arm64-v8a only. Sideload with adb install <apk> or a file manager.

2026-08-13 — this APK replaces one that could not get past DiT part 2. The weights are unchanged; do not re-download them. The first device run got the text encoder, the caption branch and part 1 loaded, then failed:

[dit-seq] part 2/32: creating context
Failed to find available PD for contextId 1 ... with context size estimate 2204186880
Skel failed to process context binary

Every context binary records the HTP scratch ("spill-fill") its graph needs, and qnn-context-binary-utility --json_file prints it:

The scratch buffer is twice the context binary. Sequential loading was allocating a private one per part, so each part asked the DSP for ~2.2 GB, freed it and asked again, 33 times per step; the device granted the first and refused the second, then went into an SSR. The caption branch now heads a spill-fill group that every part references, so one allocation serves the whole denoising loop. The group size was also a stale constant — 601 MB, below what every DiT part needs and a third of the VAE decoder's — and is now measured.

If you installed the model before 2026-08-12 14:22 UTC, install this APK and let it refresh the model. The manifest published before that time listed 38 files instead of 45 — it had lost the text encoder — so those installs look complete and cannot start: the backend exits on the missing clip_part1.bin. This build knows those installs are stale and offers the refresh, and it seeds the download from what you already have, so it fetches the missing 4.4 GB rather than all 17.7 GB again.

The Z-Image runner inside it has never executed a single graph. Installing it and reaching the model list proves the app works; it proves nothing about Z-Image.

Requirements

• Snapdragon 8 Gen 2 or newer. The context binaries are built for Hexagon v73 (8 Gen 2), which also runs on v75 (8 Gen 3) and v79 (8 Elite) — a binary built for a newer Hexagon will not load on an older one, which is why v73 is the target rather than v75.
• 16 GB RAM recommended; 12 GB needs DiT sequential loading in settings
• A Local Dream build with --type zimage support

Install

Use the in-app download, which reads model/manifest.json and fetches the 45 files listed there. There is no archive: at 17.6 GB the device would need the zip and its extraction free at the same time, and a dropped connection would cost the whole download instead of one file. The manifest form resumes at file granularity.

To install by hand, put everything under model/ into one model directory.

partial/ — the pieces as they were built

partial/ holds the conversion's own output, before assembly. model/ is built from it by server-side copy, so the two are the same bytes. Each file lands in partial/ the moment it is built, because the conversion runs on ephemeral machines with less free disk than the finished model needs — publishing every piece immediately is what stops a reclaimed container from costing the whole run.

partial/n32-attn5/stats/*.tsv records peak RSS and wall clock per stage (stage, peak_rss_kb, seconds, exit_code) for the machine that built each graph. That is what the split is chosen from, and it is worth reading, because the split is not arbitrary — see below.

What is in the model

Total 17.6 GB: 12.9 GB of DiT, 3.6 GB of text encoder, 0.8 GB of token embeddings, 0.3 GB of VAE.

Why 33 DiT graphs

Because that is what fits. The context-binary generator's peak RSS, measured on a 16 GB machine:

A 4096-token noise-refiner block costs ~4.7 GB at that stage — 4096² scores over 30 heads — so one per graph is the only arrangement that works. The caption branch is separate for the same reason, and the cut follows the model: the caption path and the image path exchange nothing until the concatenation that forms the residual stream, so splitting them changes no arithmetic. It is verified bit-exact against the reference.

That one also earns something at run time. The caption branch is the only piece of the DiT that does not depend on the timestep, so the runner computes it once per prompt rather than once per step.

Generation settings

Turbo is distilled to 8 steps and trained guidance-free, so keep cfg = 1.0. At cfg 1.0 the pipeline skips the unconditional pass entirely, halving the work per step; raising it both doubles generation time and degrades a distilled model. Prompts are natural language, not booru tags. Negative prompts are not evaluated at cfg 1.0.

Fixed 1024×1024 canvas; other aspect ratios go through inpaint padding. Prompt limit is 512 Qwen tokens, and short prompts cost nothing in quality — the static 512-slot caption graph is bit-exact against the reference's variable-length one.

Quantization

w4a16 — 4-bit weight encodings, 16-bit activations.

Why not 2-bit, since the toolchain accepts it

qairt-quantizer --weights_bitwidth does accept 2, and Hexagon v73 does compile the result — this was tested, not assumed. It is still pointless, and the measurement says why. One real DiT part (181 M parameters), one float DLC, quantized four ways:

w2 and w4 are byte-identical. --weights_bitwidth sets a metadata field on the encoding, not the storage; QnnTypes.h says data quantized below its datatype's width "will still occupy the full extent of bits allotted to the tensor ... in unpacked form". So asking for 2 bits discards three quarters of the quantization levels and writes exactly as many bytes.

--pack_4_bit_weights genuinely halves it — and then qnn-context-binary-generator refuses the graph, because across all three activation configurations the weight datatypes FullyConnected accepts on v73 are only FLOAT_16/32, SFIXED_POINT_8/16 and UFIXED_POINT_8/16. There is no 4-bit weight datatype on this hardware.

So every runnable weight width is the same size, and w4 is chosen over w8 only for the VTCM-traffic benefit the HTP documents for int4 encodings — not for bytes. If quality turns out to be the binding problem, w8 costs nothing extra.

Conversion

Reproducible from tools/zimage/ in the Local Dream repo. See docs/zimage.md for the graph IO contract and the non-obvious parts — RoPE has to be de-complexified, the sequence is ordered [image, caption], positions must be graph inputs, and the attention mask has to be applied to the caption refiner as well as the main blocks.

Credits

Model: Tongyi-MAI, Apache 2.0. App: xororz/local-dream.