pottokao/Qwen-Image-2.1-Text-Encoder-Heretic-GGUF
Verified checksumsquantizedfp8ggufcomfyuiqwen-imageabliterated
- License
- apache-2.0
- Size
- 45 GB
- Revision
- main
Mirrored from pottokao/Qwen-Image-2.1-Text-Encoder-Heretic-GGUF
All models by pottokao β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, make sure themmprojfile sits next to the GGUF, restart ComfyUI. No need to re-download anything. The same patch also fixesUnknown 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 β 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?
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):
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
πΌοΈ Showcase
 Warm Documentary |  Candid B&W Street |  Vivid Everyday Color |
 Black Fury |  Geometry of Light |  Frozen Film Still |
 Deadpan Large-Format |  White Leap |  Corner Elegance |
 Raw B&W Fashion |  Color Behind Glass |  High-Contrast Reportage |
 Lyrical Landscape |  Hyper Chic East |  Street in the Mirror |
 Plain Portrait |  Melancholy B&W |  Fairytale Giants |
 Cold Power |  Cold Power |  Hyper Chic East |
 Fairytale Giants |  Hyper Chic East |  White Leap |
This is what Q4_K_M across the board looks like β every image above was made with:
AI-generated. Style homage only β not affiliated with or endorsed by the photographers.
GGUF in ComfyUI β 3 steps
-
Install two custom nodes into
ComfyUI/custom_nodes/: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], andUnknown model architecture!when a Qwen-Image-2.1 DiT GGUF has no architecture metadata (e.g. unsloth / leejet builds). -
Put both files in
ComfyUI/models/text_encoders/qwen3vl_8b_heretic-Q4_K_M.ggufmmproj-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 towererror telling you which file to download. -
Restart ComfyUI, then
CLIPLoaderGGUFβ typeqwen_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
Other formats of the same model
Ablation (inherited from the bf16 source)
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: Q4_K_M language model, vision tower as a separate f16 mmproj.
FP8: self-quantized float8_e4m3fn (Comfy-Org doesn't ship an FP8 encoder):
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):
A short request goes in; one JSON line comes out (real output of the PE-T2I GGUF, trimmed):
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.
 |  |  |  |
 |  |  |  |
 |  |  |  |
 |  |  |  |
 |  |  |  |
 |  |  |
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]
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!
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 (seeLICENSEandNOTICE).