Open-weight model
Qwen-Image-2.1-Text-Encoder-Heretic-GGUF
by Pottokao pottokao/Qwen-Image-2.1-Text-Encoder-Heretic-GGUF
Qwen-Image-2.1-Text-Encoder-Heretic-GGUF is an open-weight model from Pottokao, released under Apache License 2.0. Its published files total 15.5 GB. It draws 34.1k downloads a month.
Every loader uses type qwenimage and feeds TextEncodeQwenImage21. Qwen-Image-2.1 is a full (non-distilled) model — use ~20–30 steps. 1. Install the add-on (you also need city96/ComfyUI-GGUF): 2.
Model Card
By Pottokao, published under apache-2.0, revision 8bca0e4d488c.
Every loader uses type qwenimage and feeds TextEncodeQwenImage21. Qwen-Image-2.1 is a full (non-distilled) model — use ~20–30 steps. 1. Install the add-on (you also need city96/ComfyUI-GGUF): 2. Put both files in ComfyUI/models/textencoders/ - qwen3vl8bheretic-Q4KM.gguf - mmproj-qwen3vl8bheretic-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. 3. Restart ComfyUI, then CLIPLoaderGGUF → type qwenimage → TextEncodeQwenImage21 → the rest of the official workflow. The console should show [GGUF-Qwen3VL-TE] added…
Read Pottokao's full model card
Qwen-Image-2.1 Text Encoder (Heretic) — GGUF + FP8
[!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.
Which file should I use?
| Your setup | File(s) | Size | Loader |
|---|---|---|---|
| Smallest (GGUF) | qwen3vl_8b_heretic-Q4_K_M.gguf + mmproj-qwen3vl_8b_heretic-f16.gguf |
4.7 + 1.1 GB | CLIPLoaderGGUF + add-on node |
| NVIDIA GPU, no extra nodes | qwen3vl_8b_fp8_heretic.safetensors |
8.7 GB | stock CLIPLoader |
| Mac / non-CUDA, no extra nodes | qwen3vl_8b_bf16_heretic.safetensors (-Heretic repo) |
16 GB | stock CLIPLoader |
Every loader uses type qwen_image and feeds TextEncodeQwenImage21.
Qwen-Image-2.1 is a full (non-distilled) model — use ~20–30 steps.
GGUF in ComfyUI — 3 steps
- Install the add-on (you also need city96/ComfyUI-GGUF):
bash cd ComfyUI/custom_nodes git clone https://github.com/pottokao-dotcom/ComfyUI-GGUF-Qwen3VL-TE - Put both files in
ComfyUI/models/text_encoders/-qwen3vl_8b_heretic-Q4_K_M.gguf-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.
3. 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.
Why did it break?
ComfyUI-GGUF loads the `mmproj` vision tower only for `qwen2vl`, not `qwen3vl`. Without the vision tower ComfyUI doesn't recognise the encoder as Qwen3-VL, builds the wrong model, and returns 12288-wide hidden states instead of 4096:RuntimeError: Given normalized_shape=[4096], expected input with shape [*, 4096],
but got input of size [1, 512, 12288]
Files in this repo
| File | Size | Use for |
|---|---|---|
qwen3vl_8b_heretic-Q4_K_M.gguf |
4.68 GB | ComfyUI via CLIPLoaderGGUF + add-on · llama.cpp |
mmproj-qwen3vl_8b_heretic-f16.gguf |
1.08 GB | vision tower — required next to the GGUF |
qwen3vl_8b_fp8_heretic.safetensors |
8.70 GB | ComfyUI via stock CLIPLoader (NVIDIA GPU) |
Other formats of the same model
| Repo | Format | Size | Note |
|---|---|---|---|
…-Heretic |
bf16 | 16.3 GB | single ComfyUI file (any device) + HF transformers shards |
…-int8-convrot |
INT8 convrot | 8.71 GB | official template default format, CUDA |
…-W4A8 |
W4A8 | 5.88 GB | CUDA |
…-NVFP4 |
NVFP4 | 5.87 GB | Blackwell GPUs |
Ablation (inherited from the bf16 source)
| Refusals | KL divergence | |
|---|---|---|
| Stock Qwen-Image-2.1 text encoder | 100/100 | 0 (by definition) |
| This family | 5/100 | 0.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: 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):
| Layers | Count | Precision |
|---|---|---|
| FFN + attention + embed/lm_head (all 2-D weights) | 254 | FP8 e4m3fn |
| Vision tower | 351 tensors | bf16 — 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).
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).
Identity and Version
- Repository
- pottokao/Qwen-Image-2.1-Text-Encoder-Heretic-GGUF
- Publisher
- Pottokao
- Task
- Not stated by the source
- Modality
- Other
- Library
- Not stated by the source
- Parameters
- Not stated by the source
- Languages
- Not stated by the source
- Revision
- 8bca0e4d488c7568c4ca695d3ed290a9ab1df16a
- First published
- 2026-09-20
- Last updated
- 2026-09-23
Files and Weights
7 files, 15.5 GB in total. The weights are 3 files totalling 15.5 GB in gguf, safetensors.
Every file
| File | Type | Size | SHA-256 |
|---|---|---|---|
| mmproj-qwen3vl_8b_heretic-f16.gguf | Weights | 1.2 GB | 4649839491c8 |
| qwen3vl_8b_fp8_heretic.safetensors | Weights | 9.3 GB | a927dd638b96 |
| qwen3vl_8b_heretic-Q4_K_M.gguf | Weights | 5.0 GB | 1338274ac7a6 |
| LICENSE | Documentation | 11.4 KB | — |
| NOTICE | Documentation | 887 B | — |
| README.md | Documentation | 5.7 KB | — |
| .gitattributes | Repository | 1.7 KB | — |
License and Download
- License
- apache-2.0
- Access
- Open weights, no gate
- Download size
- 15.5 GB
Released by Pottokao through its official repository on Hugging Face. Read the license.
Built From
- Derived from pottokao/Qwen-Image-2.1-Text-Encoder-Heretic
- Quantized from pottokao/Qwen-Image-2.1-Text-Encoder-Heretic
Memory Requirements
| Precision | Weights in memory |
|---|---|
| As published | 15.5 GB |
Weights only, from the published parameter count; the key-value cache and runtime add to this.
Questions About Qwen-Image-2.1-Text-Encoder-Heretic-GGUF
Can I use Qwen-Image-2.1-Text-Encoder-Heretic-GGUF commercially?
Yes. Qwen-Image-2.1-Text-Encoder-Heretic-GGUF is released under Apache License 2.0. The Apache License 2.0 is a permissive open-source license. It permits commercial use, modification and redistribution. It requires keeping the license and copyright notices and any NOTICE file, stating significant changes, and it includes an express patent grant from contributors.