Qwen-Image-2.1 Text Encoder (Heretic) — DHQ GGUF

DHQ = Dual-Head Quant. Same heretic weights as Qwen-Image-2.1-Text-Encoder-Heretic-GGUF, quantized a different way: instead of llama.cpp's fixed rules, every tensor gets the precision that matters to what the Qwen-Image-2.1 DiT actually reads (measured per tensor with gradients through the DiT's text input), plus an importance matrix weighted the same way. Each file is exactly the size of the standard llama.cpp file of the same name, and better at every level.

Tuned for Qwen-Image-2.1 only. Other models that use Qwen3-VL-8B (Ideogram 4, Boogu, JoyImageEdit) can load these files, but they were not tuned for them. Need Q5/Q6/Q8? Use the standard files in the GGUF repo — at those sizes the standard recipe is already as good.

About the DHQ series

DHQ files are quantized for use as a diffusion model's text encoder: each tensor's precision is chosen by how much its quantization error changes what the target DiT reads (measured through the DiT's own text-input stage), not by next-token loss. They stay normal LLM GGUFs, so the same file can still write or rewrite prompts: where a model is also used as a prompt enhancer (Z-Image-Engineer-V6, the heretic Qwen3-VL-8B), every file is also checked for that (the PE column) and the tables show where it gets worse.

DHQ repos: Qwen-Image-2.1 · Ideogram 4 · Boogu · Z-Image-Engineer-V6 · Qwen3-4B (Z-Image / FLUX.2 klein 4B) · FLUX.3 Klein

We also built Dual-Head Dragon (ComfyUI-DualHead-Dragon), a ComfyUI node that runs one GGUF as both the text encoder and the prompt enhancer (llama.cpp inside). It is public but still in testing, including its LoRA support (separate LoRAs for the encoding and the rewriting head) and DFlash speculative decoding for faster rewriting. The files here work without it (see How to load).

Results

Same heretic bf16 source, same size. Standard = llama.cpp default rules + the same imatrix. TE = relative error of the text conditioning after the DiT's own text input layer, on 36 held-out prompts never used to build or pick anything (lower is better). PE = mean KL divergence of next-token predictions vs bf16 on 80 prompt-rewrite samples, i.e. how well the same file still works as a prompt enhancer (lower is better).

K or IQ?

Each size step comes in two series built the same way, with different llama.cpp formats:

• K files (Q*_K*): simple block formats. Fast to decode everywhere — GPU, CPU, Metal, Vulkan — and on the GPU in ComfyUI-GGUF.
• IQ files (IQ*): codebook formats. For a similar error the file is smaller (compare the rows above), but decoding is heavier: fine on llama.cpp GPU backends, slower on CPU, and ComfyUI-GGUF decodes IQ3/IQ2 tensors on the CPU (tens of seconds per prompt). Our IQ4_XS files also contain some IQ3 (and in some repos IQ2) tensors, so they are slow in ComfyUI-GGUF too.

ComfyUI-GGUF → use a K file. llama.cpp (or Dual-Head Dragon) → either; IQ if you want the smallest file for a given error.

Which file

K files (Q4_K_M, Q3_K_M, Q2_K) run everywhere and as fast as the standard GGUF.

[!WARNING] IQ files (IQ4_XS, IQ3_*, IQ2_*) are slow in ComfyUI-GGUF. They contain IQ3/IQ2 tensors, which ComfyUI-GGUF has no GPU decoder for; it falls back to numpy. Measured on a GB10: ~36 s per prompt for IQ3_S, vs ~1 s for the K files. They are fine in llama.cpp itself. In ComfyUI-GGUF, use the K files.

How to load (ComfyUI)

Same as the standard GGUF: CLIPLoaderGGUF, type qwen_image, with the add-on node ComfyUI-GGUF-Qwen3VL-TE, feeding TextEncodeQwenImage21. Put mmproj-qi21-te-heretic-dhq-f16.gguf (in this repo) next to the GGUF — the add-on finds the vision tower by file-name prefix, so it has to carry the qi21-te-heretic-dhq name. It is the same file as the standard repo's mmproj.

Reproducibility

recipes/ has one recipe per file: source repo and revision, llama.cpp commit, importance matrix (sha256), and the type of every tensor as built. Rebuilding from a recipe gives a bit-identical file (checked).

License

Apache-2.0, same as the base weights (Qwen3-VL-8B-Instruct, Alibaba Cloud / Qwen). See LICENSE and NOTICE.