pottokao/Qwen-Image-2.1-Text-Encoder-Heretic-GGUF · Hugging Face

来源：https://huggingface.co/pottokao/Qwen-Image-2.1-Text-Encoder-Heretic-GGUF

https://huggingface.co/pottokao/Qwen-Image-2.1-Text-Encoder-Heretic-GGUF#qwen-image-21-text-encoder-heretic–gguf-%C2%B7-fp8-%C2%B7-bf16Qwen-Image-2.1 文本编码器 (Heretic) — GGUF · FP8 · bf16

使用 GGUF 时遇到 got input of size [1, 512, 12288] 的错误？已修复。 问题不在于 GGUF 文件本身 — ComfyUI-GGUF 此前只是没有加载 Qwen3-VL 的视觉塔。请安装附加节点 ComfyUI-GGUF-Qwen3VL-TE (https://github.com/pottokao-dotcom/ComfyUI-GGUF-Qwen3VL-TE)，确保 mmproj 文件与 GGUF 文件置于同一目录，然后重启 ComfyUI。无需重新下载任何文件。此补丁同样修复了 Qwen-Image-2.1 DiT GGUFs 报告的 Unknown model architecture! 错误 — 因此整个流程都可以在 GGUF 上运行。

https://huggingface.co/pottokao/Qwen-Image-2.1-Text-Encoder-Heretic-GGUF#made-with-a-simple-node使用简单节点制作

本仓库中的示例/展示图像是通过 ComfyUI-QwenImage-PhotoStyles (https://github.com/pottokao-dotcom/ComfyUI-QwenImage-PhotoStyles) 背后的技术生成的 — 这是一个小型 ComfyUI 节点（提供17种摄影风格；通过 PE-T2I 重写器将一个简短提示词转化为完整的风格化提示词）。如果您对这些图像的制作方式感兴趣，可以查看该节点及其配方。

https://huggingface.co/pottokao/Qwen-Image-2.1-Text-Encoder-Heretic-GGUF#%F0%9F%93%A5-which-file-should-i-use📥 我应该使用哪个文件？

所有三个版本都在此仓库中。所有加载器都使用 类型 qwen\_image 并将其馈入 TextEncodeQwenImage21。

https://huggingface.co/pottokao/Qwen-Image-2.1-Text-Encoder-Heretic-GGUF#%E2%9A%99%EF%B8%8F-recommended-sampler-settings⚙️ 推荐的采样器设置

Qwen-Image-2.1 是一个完整（未蒸馏）的模型。请使用 25 步 — 更多步骤不会使文字更清晰，并且会开始破坏高光部分。

• 图像中无文字： 纯 KSampler，cfg 1.0（最快，效果最柔和；cfg 1 时负面提示词被忽略）。
• 图像中有文字（标牌、标签、海报）： 在采样过程中途切换 cfg — 前 1⁄2 到 2⁄3 的步骤使用 cfg 1 来锁定构图和材质，其余步骤使用 cfg 3 并配合负面提示词重新绘制文字。这样您可以在一次采样中获得 cfg 1 的视觉风格以及 cfg 3 的清晰文字，并使用相同的种子。

在 ComfyUI 中，这对应两个串联的 KSamplerAdvanced 节点（使用相同的模型、种子和步数）：

较晚分割（17）保留更多 cfg 1 的外观；较早分割（12）文字更清晰。负面提示词示例：oversaturated, overexposure, gibberish text。

https://huggingface.co/pottokao/Qwen-Image-2.1-Text-Encoder-Heretic-GGUF#%F0%9F%8D%B1-all-gguf-qwen-image-21🍱 全 GGUF 版 Qwen-Image-2.1

https://huggingface.co/pottokao/Qwen-Image-2.1-Text-Encoder-Heretic-GGUF#%F0%9F%96%BC%EF%B8%8F-showcase🖼️ 展示

Juan I-Jong 风格 Henri Cartier-Bresson 风格 William Eggleston 风格 Daido Moriyama 风格 Fan Ho 风格 Gregory Crewdson 风格 Thomas Struth 风格 Richard Avedon 风格 Irving Penn 风格 Peter Lindbergh 风格 Saul Leiter 风格 Shōmei Tōmatsu 风格 Ko Si-chi 风格 Chen Man 风格 Lee Friedlander 风格 Hiroh Kikai 风格 Masahisa Fukase 风格 Tim Walker 风格 Helmut Newton 风格 Helmut Newton 风格 Chen Man 风格 Tim Walker 风格 Chen Man 风格 Richard Avedon 风格

以上是全链路使用 Q4_K_M 量化模型的效果 — 以上每张图像均由以下方式生成：

AI 生成。仅作风格致敬 — 与摄影师无关联，亦不代表其认可。

https://huggingface.co/pottokao/Qwen-Image-2.1-Text-Encoder-Heretic-GGUF#gguf-in-comfyui–3-stepsGGUF 在 ComfyUI 中的使用 — 3 个步骤

1. 安装两个自定义节点到 ComfyUI/custom\_nodes/：

   cd ComfyUI/custom_nodes
   git clone https://github.com/pottokao-dotcom/ComfyUI-GGUF-Qwen3VL-TE
   

   没有 git？请在 GitHub 页面点击 Code → Download ZIP，解压到 ComfyUI/custom\_nodes/。自定义节点新手请参考：官方指南。 此补丁修复了两个错误：文本编码器的 [1, 512, 12288] 错误，以及当 Qwen-Image-2.1 DiT GGUF 缺少架构元数据时（例如 unsloth / leejet 版本）出现的 Unknown model architecture! 错误。

2. 将两个文件放入 ComfyUI/models/text\_encoders/

   • qwen3vl\_8b\_heretic\-Q4\_K\_M\.gguf
   • mmproj\-qwen3vl\_8b\_heretic\-f16\.gguf ← 视觉塔（必需 — 也用于图像编辑） 不要重命名任何一个文件 — 视觉塔是通过文件名匹配的。如果缺失，附加节点会报错 Missing vision tower 并提示您需要下载哪个文件。

3. 重启 ComfyUI，然后使用 CLIPLoaderGGUF → 类型 qwen\_image → TextEncodeQwenImage21 → 接入官方工作流的其余部分。控制台应显示 [GGUF\-Qwen3VL\-TE] added 351 Qwen3\-VL vision tensors from mmproj.

于 2026-09-23 在 ComfyUI 0.36.0 + ComfyUI-GGUF 6ea2651（NVIDIA GPU）上验证：文生图和参考图编辑均可正常工作，并且在相同种子下，其输出与 bf16 编码器匹配至 Q4 量化噪声水平。未在 Mac 上测试。

关于补丁更改的内容及原因，请参见本页底部 What the patch handles。

https://huggingface.co/pottokao/Qwen-Image-2.1-Text-Encoder-Heretic-GGUF#files-in-this-repo本仓库中的文件

https://huggingface.co/pottokao/Qwen-Image-2.1-Text-Encoder-Heretic-GGUF#other-formats-of-the-same-model同一模型的其他格式

https://huggingface.co/pottokao/Qwen-Image-2.1-Text-Encoder-Heretic-GGUF#ablation-inherited-from-the-bf16-source消融（继承自 bf16 源）

使用 Heretic 制作：方向性消融（o\_proj + down\_proj），200 轮试验 / 60 轮启动试验，帕累托前沿的拐点。在 bf16 源上独立复核：0/20 次拒绝，4/4 个良性问题均正确回答。完整方法见 bf16 仓库。

https://huggingface.co/pottokao/Qwen-Image-2.1-Text-Encoder-Heretic-GGUF#format-details格式详情

GGUF: Q4_K_M 语言模型，视觉塔为单独的 f16 mmproj。

FP8: 自量化 float8\_e4m3fn（Comfy-Org 未提供 FP8 编码器）：

已重映射为 ComfyUI 的键布局（model\.layers\....，无 language\_model\. 前缀）。

需要支持 QwenImage21 的 ComfyUI 版本（0.36.0 或更新）。

https://huggingface.co/pottokao/Qwen-Image-2.1-Text-Encoder-Heretic-GGUF#%F0%9F%8E%A8-also-for-qwen-image-21-the-prompt-rewriters-heretic🎨 同样适用于 Qwen-Image-2.1：提示词重写器（Heretic）

Qwen-Image-2.1 附带两个提示词重写器 — 将简短请求扩展为模型训练所用详细提示词的小型 LLM。两者均提供拒绝消融版本，并且都有可在任何运行 llama.cpp 的平台（包括 Mac）上运行的 GGUF 构建版本：

输入一个简短请求，输出一行 JSON（PE-T2I GGUF 的实际输出，已修剪）：

in:  雨夜的東京小巷,一隻流浪狗,森山大道風格
out: {"rewritten_prompt": "A vertical nighttime street photograph in the style of Daido Moriya 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"}

展示 — 使用 NVFP4 构建版本通过完整流程（PE-T2I 重写器 → Qwen-Image-2.1 文本编码器 → DiT）生成，每张图仅用一行提示词和一个种子，无任何后期处理。同时在 PE-T2I NVFP4 仓库 中展示。

https://huggingface.co/pottokao/Qwen-Image-2.1-Text-Encoder-Heretic-GGUF#what-the-patch-handles补丁修复的内容

ComfyUI-GGUF-Qwen3VL-TE 不更改磁盘上的文件 — 它只在加载时调整 ComfyUI-GGUF 在内存中加载 Qwen-Image-2.1 文件的方式。

1. 文本编码器 — [1, 512, 12288]

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

ComfyUI-GGUF 仅为 qwen2vl 加载 mmproj 视觉塔，不支持 qwen3vl。没有它，ComfyUI 无法将编码器识别为 Qwen3-VL，从而构建了错误的模型，得到宽度为 12288 的隐状态而非 4096。此补丁会从同一文件夹加载匹配的 mmproj\-\*\.gguf，并将其张量重命名为 ComfyUI 的 Qwen3-VL 布局（model\.visual\.\*）。这样视觉塔才真正被使用 — 用于编辑的参考图像会通过它处理。

2. DiT — Unknown model architecture!

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

缺少 general\.architecture 元数据（stable-diffusion.cpp 惯例，如 unsloth / leejet）的 DiT GGUF 会通过其张量名称被识别，而 ComfyUI-GGUF 的列表中没有 Qwen-Image 条目。此补丁通过 img\_in、txt\_in\.in\_layer 和 txt\_in\.text\_norm 识别 Qwen-Image-2.1，并将其作为 qwen\_image 加载。已包含该元数据的 DiT GGUF（如 Abiray 的版本）不受影响。

一旦 ComfyUI-GGUF 自身处理了任一情况，补丁的该部分会检测到并停止工作。

与阿里巴巴 / Qwen 无关联，亦不代表其认可。 本模型是 Qwen/Qwen3\-VL\-8B\-Instruct (https://huggingface.co/Qwen/Qwen3-VL-8B-Instruct) — Qwen-Image-2.1 使用的、未经修改的文本编码器 — 的社区衍生版本（拒绝消融）。Qwen 以 Apache-2.0 协议发布该模型，因此此衍生版本也以 Apache-2.0 协议再分发（见 LICENSE 和 NOTICE）。