CoolFace
Modelpublic

pottokao/Qwen-Image-2.1-Text-Encoder-Heretic-GGUF

sourceHugging Faceapache-2.0updated 16h agoView on Hugging Face
243likes103kdownloads
Model Card

Qwen-Image-2.1 Text Encoder (Heretic) — GGUF · FP8 · bf16

[!IMPORTANT] Got `got input of size [1, 512, 12288]` with the GGUF? It's fixed. The GGUF files were fine all along — ComfyUI-GGUF just didn't load the Qwen3-VL vision tower. Install the add-on node [ComfyUI-GGUF-Qwen3VL-TE](https://github.com/pottokao-dotcom/ComfyUI-GGUF-Qwen3VL-TE), make sure the mmproj file sits next to the GGUF, restart ComfyUI. No need to re-download anything. The same patch also fixes Unknown model architecture! for Qwen-Image-2.1 DiT GGUFs — so the whole pipeline can run on GGUF.

Made with a simple node

The sample / showcase images in this repo were generated with the technique behind [ComfyUI-QwenImage-PhotoStyles](https://github.com/pottokao-dotcom/ComfyUI-QwenImage-PhotoStyles) — a small ComfyUI node (17 photographic styles; one short prompt becomes a full styled prompt via the PE-T2I rewriter). If you're interested in how the images are made, the node and its recipe are there.

📥 Which file should I use?

Your setupFile(s)SizeLoader
Smallest (GGUF)qwen3vl_8b_heretic-Q4_K_M.gguf + mmproj-qwen3vl_8b_heretic-f16.gguf5.0 + 1.2 GBCLIPLoaderGGUF + add-on node
NVIDIA GPU, no extra nodesqwen3vl_8b_fp8_heretic.safetensors9.3 GBstock CLIPLoader
Mac / non-CUDA, no extra nodesqwen3vl_8b_bf16_heretic.safetensors17.5 GBstock CLIPLoader

All three are in this repo. Every loader uses type `qwen_image` and feeds TextEncodeQwenImage21.

⚙️ Recommended sampler settings

Qwen-Image-2.1 is a full (non-distilled) model. Use 25 steps — more steps don't make text sharper and start to burn the highlights.

  • —No text in the image: plain KSampler, cfg 1.0 (fastest, softest look; the negative prompt is ignored at cfg 1).
  • —Text in the image (signs, labels, posters): switch cfg partway through — the first ½–⅔ of the steps at cfg 1 lock in composition and materials, the rest at cfg 3 with a negative prompt redraws the lettering. You get cfg 1's look and cfg 3's readable text, in one pass with one seed.

In ComfyUI that's two chained KSamplerAdvanced nodes (same model, seed and steps):

`add_noise``steps``cfg``start_at_step``end_at_step``return_with_leftover_noise`
1stenable251.0012–17enable
2nddisable253.012–1725disable

Split later (17) keeps more of the cfg 1 look; split earlier (12) gives crisper text. Example negative prompt: oversaturated, overexposed, gibberish text.

🍱 All-GGUF Qwen-Image-2.1

PartWhereLoader
Prompt rewriter (optional)PE-T2I Heretic GGUFllama.cpp / LLM node
Text encoderthis repo — Q4KM + mmprojCLIPLoaderGGUF + patch node
DiTQwen-Image-2.1 DiT GGUF — Q80 / Q6K / Q4KMUnetLoaderGGUF — stock, no patch
VAEofficial qwen_image_2.1_vae_bf16.safetensorsVAELoader

🖼️ Showcase

<table> <tr><td width="33%"><a href="https://huggingface.co/pottokao/Qwen-Image-2.1-DiT-GGUF/blob/main/showcaseassets/01.jpg"><img src="https://huggingface.co/pottokao/Qwen-Image-2.1-DiT-GGUF/resolve/main/showcaseassets/01.jpg" width="100%"></a><br><sub>Warm Documentary</sub></td><td width="33%"><a href="https://huggingface.co/pottokao/Qwen-Image-2.1-DiT-GGUF/blob/main/showcaseassets/02.jpg"><img src="https://huggingface.co/pottokao/Qwen-Image-2.1-DiT-GGUF/resolve/main/showcaseassets/02.jpg" width="100%"></a><br><sub>Candid B&W Street</sub></td><td width="33%"><a href="https://huggingface.co/pottokao/Qwen-Image-2.1-DiT-GGUF/blob/main/showcaseassets/04.jpg"><img src="https://huggingface.co/pottokao/Qwen-Image-2.1-DiT-GGUF/resolve/main/showcaseassets/04.jpg" width="100%"></a><br><sub>Vivid Everyday Color</sub></td></tr> <tr><td width="33%"><a href="https://huggingface.co/pottokao/Qwen-Image-2.1-DiT-GGUF/blob/main/showcaseassets/05.jpg"><img src="https://huggingface.co/pottokao/Qwen-Image-2.1-DiT-GGUF/resolve/main/showcaseassets/05.jpg" width="100%"></a><br><sub>Black Fury</sub></td><td width="33%"><a href="https://huggingface.co/pottokao/Qwen-Image-2.1-DiT-GGUF/blob/main/showcaseassets/06.jpg"><img src="https://huggingface.co/pottokao/Qwen-Image-2.1-DiT-GGUF/resolve/main/showcaseassets/06.jpg" width="100%"></a><br><sub>Geometry of Light</sub></td><td width="33%"><a href="https://huggingface.co/pottokao/Qwen-Image-2.1-DiT-GGUF/blob/main/showcaseassets/07.jpg"><img src="https://huggingface.co/pottokao/Qwen-Image-2.1-DiT-GGUF/resolve/main/showcaseassets/07.jpg" width="100%"></a><br><sub>Frozen Film Still</sub></td></tr> <tr><td width="33%"><a href="https://huggingface.co/pottokao/Qwen-Image-2.1-DiT-GGUF/blob/main/showcaseassets/08.jpg"><img src="https://huggingface.co/pottokao/Qwen-Image-2.1-DiT-GGUF/resolve/main/showcaseassets/08.jpg" width="100%"></a><br><sub>Deadpan Large-Format</sub></td><td width="33%"><a href="https://huggingface.co/pottokao/Qwen-Image-2.1-DiT-GGUF/blob/main/showcaseassets/09.jpg"><img src="https://huggingface.co/pottokao/Qwen-Image-2.1-DiT-GGUF/resolve/main/showcaseassets/09.jpg" width="100%"></a><br><sub>White Leap</sub></td><td width="33%"><a href="https://huggingface.co/pottokao/Qwen-Image-2.1-DiT-GGUF/blob/main/showcaseassets/10.jpg"><img src="https://huggingface.co/pottokao/Qwen-Image-2.1-DiT-GGUF/resolve/main/showcaseassets/10.jpg" width="100%"></a><br><sub>Corner Elegance</sub></td></tr> <tr><td width="33%"><a href="https://huggingface.co/pottokao/Qwen-Image-2.1-DiT-GGUF/blob/main/showcaseassets/11.jpg"><img src="https://huggingface.co/pottokao/Qwen-Image-2.1-DiT-GGUF/resolve/main/showcaseassets/11.jpg" width="100%"></a><br><sub>Raw B&W Fashion</sub></td><td width="33%"><a href="https://huggingface.co/pottokao/Qwen-Image-2.1-DiT-GGUF/blob/main/showcaseassets/12.jpg"><img src="https://huggingface.co/pottokao/Qwen-Image-2.1-DiT-GGUF/resolve/main/showcaseassets/12.jpg" width="100%"></a><br><sub>Color Behind Glass</sub></td><td width="33%"><a href="https://huggingface.co/pottokao/Qwen-Image-2.1-DiT-GGUF/blob/main/showcaseassets/13.jpg"><img src="https://huggingface.co/pottokao/Qwen-Image-2.1-DiT-GGUF/resolve/main/showcaseassets/13.jpg" width="100%"></a><br><sub>High-Contrast Reportage</sub></td></tr> <tr><td width="33%"><a href="https://huggingface.co/pottokao/Qwen-Image-2.1-DiT-GGUF/blob/main/showcaseassets/14.jpg"><img src="https://huggingface.co/pottokao/Qwen-Image-2.1-DiT-GGUF/resolve/main/showcaseassets/14.jpg" width="100%"></a><br><sub>Lyrical Landscape</sub></td><td width="33%"><a href="https://huggingface.co/pottokao/Qwen-Image-2.1-DiT-GGUF/blob/main/showcaseassets/15.jpg"><img src="https://huggingface.co/pottokao/Qwen-Image-2.1-DiT-GGUF/resolve/main/showcaseassets/15.jpg" width="100%"></a><br><sub>Hyper Chic East</sub></td><td width="33%"><a href="https://huggingface.co/pottokao/Qwen-Image-2.1-DiT-GGUF/blob/main/showcaseassets/16.jpg"><img src="https://huggingface.co/pottokao/Qwen-Image-2.1-DiT-GGUF/resolve/main/showcaseassets/16.jpg" width="100%"></a><br><sub>Street in the Mirror</sub></td></tr> <tr><td width="33%"><a href="https://huggingface.co/pottokao/Qwen-Image-2.1-DiT-GGUF/blob/main/showcaseassets/18.jpg"><img src="https://huggingface.co/pottokao/Qwen-Image-2.1-DiT-GGUF/resolve/main/showcaseassets/18.jpg" width="100%"></a><br><sub>Plain Portrait</sub></td><td width="33%"><a href="https://huggingface.co/pottokao/Qwen-Image-2.1-DiT-GGUF/blob/main/showcaseassets/19.jpg"><img src="https://huggingface.co/pottokao/Qwen-Image-2.1-DiT-GGUF/resolve/main/showcaseassets/19.jpg" width="100%"></a><br><sub>Melancholy B&W</sub></td><td width="33%"><a href="https://huggingface.co/pottokao/Qwen-Image-2.1-DiT-GGUF/blob/main/showcaseassets/20.jpg"><img src="https://huggingface.co/pottokao/Qwen-Image-2.1-DiT-GGUF/resolve/main/showcaseassets/20.jpg" width="100%"></a><br><sub>Fairytale Giants</sub></td></tr> <tr><td width="33%"><a href="https://huggingface.co/pottokao/Qwen-Image-2.1-DiT-GGUF/blob/main/showcaseassets/21.jpg"><img src="https://huggingface.co/pottokao/Qwen-Image-2.1-DiT-GGUF/resolve/main/showcaseassets/21.jpg" width="100%"></a><br><sub>Cold Power</sub></td><td width="33%"><a href="https://huggingface.co/pottokao/Qwen-Image-2.1-DiT-GGUF/blob/main/showcaseassets/22.jpg"><img src="https://huggingface.co/pottokao/Qwen-Image-2.1-DiT-GGUF/resolve/main/showcaseassets/22.jpg" width="100%"></a><br><sub>Cold Power</sub></td><td width="33%"><a href="https://huggingface.co/pottokao/Qwen-Image-2.1-DiT-GGUF/blob/main/showcaseassets/23.jpg"><img src="https://huggingface.co/pottokao/Qwen-Image-2.1-DiT-GGUF/resolve/main/showcaseassets/23.jpg" width="100%"></a><br><sub>Hyper Chic East</sub></td></tr> <tr><td width="33%"><a href="https://huggingface.co/pottokao/Qwen-Image-2.1-DiT-GGUF/blob/main/showcaseassets/24.jpg"><img src="https://huggingface.co/pottokao/Qwen-Image-2.1-DiT-GGUF/resolve/main/showcaseassets/24.jpg" width="100%"></a><br><sub>Fairytale Giants</sub></td><td width="33%"><a href="https://huggingface.co/pottokao/Qwen-Image-2.1-DiT-GGUF/blob/main/showcaseassets/25.jpg"><img src="https://huggingface.co/pottokao/Qwen-Image-2.1-DiT-GGUF/resolve/main/showcaseassets/25.jpg" width="100%"></a><br><sub>Hyper Chic East</sub></td><td width="33%"><a href="https://huggingface.co/pottokao/Qwen-Image-2.1-DiT-GGUF/blob/main/showcaseassets/26.jpg"><img src="https://huggingface.co/pottokao/Qwen-Image-2.1-DiT-GGUF/resolve/main/showcaseassets/26.jpg" width="100%"></a><br><sub>White Leap</sub></td></tr> </table>

This is what Q4_K_M across the board looks like — every image above was made with:

PartFile
PE-T2I rewriter`pe_t2i_heretic-Q4_K_M.gguf`
Text encoder`qwen3vl_8b_heretic-Q4_K_M.gguf` + f16 mmproj
DiT`qwen_image_2.1-Q4_K_M.gguf`
VAEqwen_image_2.1_vae_bf16.safetensors (official)

<sub>AI-generated. Style homage only — not affiliated with or endorsed by the photographers.</sub>

GGUF in ComfyUI — 3 steps

  1. 1.Install two custom nodes into ComfyUI/custom_nodes/:
NodeWhat it does
city96/ComfyUI-GGUFthe GGUF loaders (CLIPLoaderGGUF, UnetLoaderGGUF) — also in ComfyUI Manager
pottokao-dotcom/ComfyUI-GGUF-Qwen3VL-TEtemporary patch for Qwen-Image-2.1 until ComfyUI-GGUF supports it — manual install only
bash
   cd ComfyUI/custom_nodes
   git clone https://github.com/pottokao-dotcom/ComfyUI-GGUF-Qwen3VL-TE

No git? On the GitHub page click Code → Download ZIP, unzip it into ComfyUI/custom_nodes/. New to custom nodes: official guide.

The patch fixes both errors: the text encoder's [1, 512, 12288], and Unknown model architecture! when a Qwen-Image-2.1 DiT GGUF has no architecture metadata (e.g. unsloth / leejet builds).

  1. 1.Put both files in `ComfyUI/models/text_encoders/`
  2. 2.qwen3vl_8b_heretic-Q4_K_M.gguf
  3. 3.mmproj-qwen3vl_8b_heretic-f16.gguf ← the vision tower (required — also used for image editing)

Don't rename either file — the vision tower is matched by name. If it's missing, the add-on stops with a Missing vision tower error telling you which file to download.

  1. 1.Restart ComfyUI, then CLIPLoaderGGUF → type `qwen_image` → TextEncodeQwenImage21 → the rest of the official workflow. The console should show [GGUF-Qwen3VL-TE] added 351 Qwen3-VL vision tensors from mmproj.

Verified 2026-09-23 on ComfyUI 0.36.0 + ComfyUI-GGUF 6ea2651 (NVIDIA GPU): text-to-image and reference-image editing both work and match the bf16 encoder's output for the same seed up to Q4 quantization noise. Not tested on a Mac.

What the patch changes, and why: see the bottom of this page.

Files in this repo

FileSizeUse for
qwen3vl_8b_heretic-Q4_K_M.gguf5.03 GBComfyUI via CLIPLoaderGGUF + add-on · llama.cpp
qwen3vl_8b_heretic-Q6_K.gguf6.88 GBhigher quality — same loader (CLIPLoaderGGUF + add-on + mmproj)
qwen3vl_8b_heretic-Q8_0.gguf8.71 GBnear-lossless — same loader (for spare VRAM)
mmproj-qwen3vl_8b_heretic-f16.gguf1.16 GBvision tower — required next to the GGUF
qwen3vl_8b_fp8_heretic.safetensors9.34 GBComfyUI via stock CLIPLoader (NVIDIA GPU)
qwen3vl_8b_bf16_heretic.safetensors17.53 GBComfyUI via stock CLIPLoader (any device, incl. Mac) — full precision

Other formats of the same model

RepoFormatSizeNote
`…-Heretic`bf1617.5 GBHF transformers shards (+ the same bf16 single file)
`…-int8-convrot`INT8 convrot9.35 GBofficial template default format, CUDA
`…-W4A8`W4A86.31 GBCUDA
`…-NVFP4`NVFP46.31 GBBlackwell GPUs

Ablation (inherited from the bf16 source)

RefusalsKL divergence
Stock Qwen-Image-2.1 text encoder100/1000 (by definition)
This family5/1000.0220

Produced with Heretic directional ablation (o_proj + down_proj), 200 trials / 60 startup trials, knee point of the Pareto front. Independently re-checked on the bf16 source: 0/20 refusals, 4/4 benign questions answered correctly. Full methodology in the bf16 repo.

Format details

GGUF: Q4KM language model, vision tower as a separate f16 mmproj.

FP8: self-quantized float8_e4m3fn (Comfy-Org doesn't ship an FP8 encoder):

LayersCountPrecision
FFN + attention + embed/lm_head (all 2-D weights)254FP8 e4m3fn
Vision tower351 tensorsbf16 — untouched
norms / biases—bf16

Remapped to the ComfyUI key layout (model.layers.…, no language_model. prefix).

Requires a ComfyUI build with QwenImage21 support (0.36.0 or newer).

🎨 Also for Qwen-Image-2.1: the prompt rewriters (Heretic)

Qwen-Image-2.1 ships two prompt rewriters — small LLMs that expand a short request into the detailed prompt the model was trained on. Both are available refusal-ablated, and both have GGUF builds that run anywhere llama.cpp runs (Mac included):

RewriterWhat it doesBuilds
PE-T2I (text-to-image)one line in any language → detailed English prompt + aspect ratioGGUF · NVFP4 · bf16
PE-I2I (image editing)vague edit instruction + input image(s) → precise editing promptGGUF + mmproj

A short request goes in; one JSON line comes out (real output of the PE-T2I GGUF, trimmed):

text
in:  雨夜的東京小巷，一隻流浪狗，粗粒黑白街拍風格
out: {"rewritten_prompt": "A vertical nighttime street photograph in a gritty grainy black-and-white street style shows a
      narrow, rain-soaked urban alley with a stray dog standing in the lower foreground. The scene is
      composed with strong depth: dark building walls and utility poles frame the left and right sides,
      while the wet pavement stretches into a softly blurred background. … (2,137 characters)",
      "wh_ratio": "2:3"}

Showcase — generated with the NVFP4 builds through the full pipeline (PE-T2I rewriter → Qwen-Image-2.1 text encoder → DiT), each from a one-line prompt, one seed per image, no retouching. Also shown in the PE-T2I NVFP4 repo.

<table> <tr> <td width="25%"><img src="https://huggingface.co/pottokao/Qwen-Image-2.1-PE-T2I-Heretic-NVFP4/resolve/main/showcaseassets/blackfurynightdog.png" width="100%"></td> <td width="25%"><img src="https://huggingface.co/pottokao/Qwen-Image-2.1-PE-T2I-Heretic-NVFP4/resolve/main/showcaseassets/blackfurystreetdog.png" width="100%"></td> <td width="25%"><img src="https://huggingface.co/pottokao/Qwen-Image-2.1-PE-T2I-Heretic-NVFP4/resolve/main/showcaseassets/deadpanportraitpair.png" width="100%"></td> <td width="25%"><img src="https://huggingface.co/pottokao/Qwen-Image-2.1-PE-T2I-Heretic-NVFP4/resolve/main/showcaseassets/geometryoflightstairs.png" width="100%"></td> </tr> <tr> <td><img src="https://huggingface.co/pottokao/Qwen-Image-2.1-PE-T2I-Heretic-NVFP4/resolve/main/showcaseassets/colorbehindglassrain.png" width="100%"></td> <td><img src="https://huggingface.co/pottokao/Qwen-Image-2.1-PE-T2I-Heretic-NVFP4/resolve/main/showcaseassets/surrealbwstreet.png" width="100%"></td> <td><img src="https://huggingface.co/pottokao/Qwen-Image-2.1-PE-T2I-Heretic-NVFP4/resolve/main/showcaseassets/softeverydaylightchild.png" width="100%"></td> <td><img src="https://huggingface.co/pottokao/Qwen-Image-2.1-PE-T2I-Heretic-NVFP4/resolve/main/showcaseassets/softeverydaylightharbour.png" width="100%"></td> </tr> <tr> <td><img src="https://huggingface.co/pottokao/Qwen-Image-2.1-PE-T2I-Heretic-NVFP4/resolve/main/showcaseassets/warmdocumentaryportrait.png" width="100%"></td> <td><img src="https://huggingface.co/pottokao/Qwen-Image-2.1-PE-T2I-Heretic-NVFP4/resolve/main/showcaseassets/palelightglass.png" width="100%"></td> <td><img src="https://huggingface.co/pottokao/Qwen-Image-2.1-PE-T2I-Heretic-NVFP4/resolve/main/showcaseassets/vivideverydaydiner.png" width="100%"></td> <td><img src="https://huggingface.co/pottokao/Qwen-Image-2.1-PE-T2I-Heretic-NVFP4/resolve/main/showcaseassets/vividgardengoldfish.png" width="100%"></td> </tr> <tr> <td><img src="https://huggingface.co/pottokao/Qwen-Image-2.1-PE-T2I-Heretic-NVFP4/resolve/main/showcaseassets/boldminimalflower.png" width="100%"></td> <td><img src="https://huggingface.co/pottokao/Qwen-Image-2.1-PE-T2I-Heretic-NVFP4/resolve/main/showcaseassets/softcolorslip.png" width="100%"></td> <td><img src="https://huggingface.co/pottokao/Qwen-Image-2.1-PE-T2I-Heretic-NVFP4/resolve/main/showcaseassets/privatediaryflowers.png" width="100%"></td> <td><img src="https://huggingface.co/pottokao/Qwen-Image-2.1-PE-T2I-Heretic-NVFP4/resolve/main/showcaseassets/privatediaryportrait.png" width="100%"></td> </tr> <tr> <td><img src="https://huggingface.co/pottokao/Qwen-Image-2.1-PE-T2I-Heretic-NVFP4/resolve/main/showcaseassets/privatediarystreet.png" width="100%"></td> <td><img src="https://huggingface.co/pottokao/Qwen-Image-2.1-PE-T2I-Heretic-NVFP4/resolve/main/showcaseassets/lyricallandscape.png" width="100%"></td> <td><img src="https://huggingface.co/pottokao/Qwen-Image-2.1-PE-T2I-Heretic-NVFP4/resolve/main/showcaseassets/nocturnalstage.png" width="100%"></td> <td><img src="https://huggingface.co/pottokao/Qwen-Image-2.1-PE-T2I-Heretic-NVFP4/resolve/main/showcaseassets/deadpanindustrialtower.png" width="100%"></td> </tr> <tr> <td><img src="https://huggingface.co/pottokao/Qwen-Image-2.1-PE-T2I-Heretic-NVFP4/resolve/main/showcaseassets/minimalseascape.png" width="100%"></td> <td><img src="https://huggingface.co/pottokao/Qwen-Image-2.1-PE-T2I-Heretic-NVFP4/resolve/main/showcaseassets/largeformatcontainers.png" width="100%"></td> <td><img src="https://huggingface.co/pottokao/Qwen-Image-2.1-PE-T2I-Heretic-NVFP4/resolve/main/showcaseassets/largeformatretail.png" width="100%"></td> <td></td> </tr> </table>

What the patch handles

ComfyUI-GGUF-Qwen3VL-TE changes nothing on disk — it only adjusts how ComfyUI-GGUF loads Qwen-Image-2.1 files, in memory, at load time.

1. Text encoder — `[1, 512, 12288]`

RuntimeError: Given normalized_shape=[4096], expected input with shape [*, 4096],
but got input of size [1, 512, 12288]

ComfyUI-GGUF loads the mmproj vision tower only for qwen2vl, not qwen3vl. Without it, ComfyUI doesn't recognise the encoder as Qwen3-VL, builds the wrong model, and gets 12288-wide hidden states instead of 4096. The patch loads the matching mmproj-*.gguf from the same folder and renames its tensors to ComfyUI's Qwen3-VL layout (model.visual.*). The vision tower is then really used — reference images for editing go through it.

2. DiT — `Unknown model architecture!`

ValueError: This model is not currently supported - (Unknown model architecture!)

A DiT GGUF without general.architecture metadata (stable-diffusion.cpp convention, e.g. unsloth / leejet) is identified by its tensor names, and ComfyUI-GGUF's list has no Qwen-Image entry. The patch recognises Qwen-Image-2.1 by img_in, txt_in.in_layer and txt_in.text_norm and loads it as qwen_image. DiT GGUFs that already carry the metadata (e.g. Abiray's) are unaffected.

Once ComfyUI-GGUF handles either case itself, that part of the patch detects it and does nothing.

Not affiliated with, or endorsed by, Alibaba / Qwen. Community derivative (refusal-ablated) of `Qwen/Qwen3-VL-8B-Instruct` — the model Qwen-Image-2.1 uses, unmodified, as its text encoder. Qwen releases that model under Apache-2.0, so this derivative is redistributed under Apache-2.0 (see LICENSE and NOTICE).