FP8 自量化内幕：Qwen-Image-2.1-Text-Encoder-Heretic-GGUF float8_e4m3fn 权重布局与 ComfyUI 键名重映射技术详解
Qwen-Image-2.1-Text-Encoder-Heretic-GGUF是 Qwen-Image-2.1 图像生成模型的文本编码器（Text Encoder）权重仓库，核心亮点是FP8 自量化（float8_e4m3fn）与面向ComfyUI 的键名重映射。它把 Qwen3-VL-8B-Instruct 做了去拒绝（Heretic）改造，再分别量化成 GGUF（Q4_K_M / Q6_K / Q8_0）、FP8 和 bf16 六种文件，让你用更少的显存跑满整条 Qwen-Image-2.1 出图流程 🚀
先搞懂：这个仓库里到底是什么
| 概念 | 通俗解释 |
|---|---|
| 文本编码器（Text Encoder） | 出图流水线的"翻译官"，把你的提示词变成模型能理解的向量，决定画面"画什么" |
| Qwen3-VL-8B-Instruct | Qwen-Image-2.1 官方使用的文本编码器本体 |
| Heretic | 用方向消融（directional ablation，作用于o_proj+down_proj）移除"拒绝回答"倾向的社区改造版本 |
改造效果来自 NOTICE 与 README.md 的消融数据：拒绝率从原版100/100 降到 5/100，KL 散度仅0.0220——也就是说，它"更听话"，但输出分布几乎没有漂移。
💡 权重文件本身不在本文展开逐层细节，重点是格式布局和怎么在 ComfyUI 里用起来。
一张表看懂 6 个文件怎么选
仓库内所有文件一览（详见 README.md）：
| 文件 | 大小 | 适合谁 | 加载器 |
|---|---|---|---|
| qwen3vl_8b_heretic-Q4_K_M.gguf | 5.03 GB | 显存紧张首选 | CLIPLoaderGGUF+ 补丁节点 |
| qwen3vl_8b_heretic-Q6_K.gguf | 6.88 GB | 更高精度 | 同上 |
| qwen3vl_8b_heretic-Q8_0.gguf | 8.71 GB | 近无损 | 同上 |
| mmproj-qwen3vl_8b_heretic-f16.gguf | 1.16 GB | 视觉塔，GGUF 路线必备 | 随 GGUF 一起加载 |
| qwen3vl_8b_fp8_heretic.safetensors | 9.34 GB | NVIDIA GPU，零额外节点 | 原生CLIPLoader |
| qwen3vl_8b_bf16_heretic.safetensors | 17.53 GB | Mac / 非 CUDA，全精度 | 原生CLIPLoader |
三条典型路线（README.md）：
- 省显存：Q4_K_M + mmproj，GGUF 加载器 + 补丁节点
- NVIDIA 省心：FP8 文件 + 原生
CLIPLoader，什么都不用装 - Mac / 非 CUDA：bf16 文件 + 原生
CLIPLoader
FP8 自量化内幕：为什么叫"自量化"
为什么要自己做 FP8 量化？
因为官方（Comfy-Org）没有发布 FP8 版本的 Qwen-Image-2.1 文本编码器。想要 8-bit 级别的体积收益，就只能自己动手——这正是仓库名里 "自量化（self-quantized）" 的含义（README.md）。
什么是 float8_e4m3fn？
float8_e4m3fn是一种 8 位浮点格式，名字可以拆开读：
| 片段 | 含义 |
|---|---|
| e4 | 4 位指数（exponent） |
| m3 | 3 位尾数（mantissa） |
| fn | 只表示有限数（finite numbers），没有 inf/NaN |
加上 1 位符号位，共 8 bit。和 bf16 相比体积直接减半，又保留了浮点的大动态范围，适合"数值分布集中"的权重矩阵。由于动态范围有限（最大约 ±448），对异常值敏感的张量就不适合硬压进 FP8——这正是下面混合精度布局的用意。
混合精度布局：哪些张量进 FP8，哪些留在 bf16
这是本仓库 FP8 文件最核心的设计（README.md）：
| 张量类别 | 数量 | 精度 | 原因 |
|---|---|---|---|
| FFN + 注意力 + embed/lm_head（全部 2-D 权重矩阵） | 254个 | FP8e4m3fn | 权重数值分布集中，量化收益大 |
| 视觉塔（vision tower） | 351个 | bf16 原样保留 | 承担图像编辑的参考图理解，精度敏感 |
| LayerNorm / 偏置（1-D 小张量） | — | bf16 | 体积小、值域窄，量化不划算 |
一句话总结：把"又大又规矩"的 2-D 权重矩阵压成 FP8，把"小而敏感"的部分留在 bf16，最终 9.34 GB，介于 Q4_K_M（5 GB）和 bf16（17.5 GB）之间，质量上更接近 bf16。
ComfyUI 键名重映射：去掉language_model.前缀的玄机
问题出在哪？
原始 Qwen3-VL-8B-Instruct 是"视觉 + 语言"一体化模型，语言模型的权重在 checkpoint 里带着language_model.前缀存放（例如model.language_model.layers.0.self_attn.q_proj.weight）。而ComfyUI 的 Qwen-Image 文本编码器流程期望的是去掉前缀的标准解码器布局（model.layers.0.…）。
键名对不上 → 权重加载后"认不出来" → 节点无法工作。
重映射做了什么？
量化脚本在导出 FP8 文件时，把所有键名重映射（remap）到 ComfyUI 的键布局：model.layers.…，并移除language_model.前缀（README.md）。
这就是为什么 FP8 文件可以直接丢进ComfyUI/models/text_encoders/，用原生CLIPLoader加载，不需要任何自定义节点——文件在落盘前就已经"说 ComfyUI 的方言"了。
对比：GGUF 路线的"运行时重映射"
有意思的是，补丁节点 ComfyUI-GGUF-Qwen3VL-TE 做的是同一件事的"运行时版"：GGUF 文件里的视觉塔来自独立的mmproj-*.gguf，补丁节点在加载时于内存中把它的张量重命名为 ComfyUI 的 Qwen3-VL 布局（model.visual.*），一个不落盘（README.md）。
两条路线的分工：
| 路线 | 重映射时机 | 视觉塔来源 |
|---|---|---|
| FP8 / bf16（safetensors） | 文件内已重映射，原生加载 | 与权重同文件（351 个 bf16 张量） |
| GGUF | 加载时由补丁节点重映射 | 独立mmproj-*.gguf，需放在 GGUF 同目录且不能改名（按文件名匹配） |
三步在 ComfyUI 里跑起来（FP8 路线）
- 把 qwen3vl_8b_fp8_heretic.safetensors 放入
ComfyUI/models/text_encoders/ - 节点用原生
CLIPLoader，type 选择qwen_image - 接到
TextEncodeQwenImage21，其余按官方工作流接 DiT 与 VAE
⚠️ 注意两点：
- 需要支持
QwenImage21的 ComfyUI（0.36.0 或更新版本，README.md） - FP8 只建议NVIDIA GPU使用；Mac 请用 bf16 文件
走 GGUF 路线则会遇到两个经典报错，补丁节点一并修复：
got input of size [1, 512, 12288]：视觉塔没被加载，模型结构搭错（隐藏维度 12288 vs 4096）Unknown model architecture!：无架构元数据的 DiT GGUF 识别失败
装好补丁节点后，控制台应出现[GGUF-Qwen3VL-TE] added 351 Qwen3-VL vision tensors from mmproj.，说明 351 个视觉塔张量全部就位 ✅
常见疑问 FAQ
Q1：FP8 文件和 Q8_0 GGUF 都是"8 位"，选哪个？FP8 是浮点 8 位，数值分布保留更好，且无需补丁节点；Q8_0 GGUF 是块量化，走 GGUF 加载器生态。NVIDIA 用户优先 FP8，想进 llama.cpp / 全 GGUF 流程则选 Q8_0。
Q2："Heretic" 会不会改变出图风格？消融只作用于拒绝方向（o_proj+down_proj的子集层），其他权重不变；同一 seed 下与 bf16 编码器输出一致到量化噪声级别（README.md）。
Q3：视觉塔（vision tower）是干什么的？它负责理解参考图，是图像编辑（图生图修改）能力的关键。所以 GGUF 路线的 mmproj 文件是必选项，缺失时补丁节点会报Missing vision tower并告诉你该下哪个文件。
Q4：采样参数有讲究吗？文本编码器只负责"提示词→向量"这一步，步数主要影响 DiT。推荐25 步；画面里要出现文字（招牌、海报）时，用两个KSamplerAdvanced分段调 cfg：前段 cfg 1 定构图，后段 cfg 3 重写文字（README.md）。
写在最后
Qwen-Image-2.1-Text-Encoder-Heretic-GGUF 的价值在于把"官方没给的东西"补齐了：FP8 自量化让你用一半显存拿到接近 bf16 的编码质量，键名重映射让文件开箱即用地融入 ComfyUI 生态，而 Heretic 消融则让编码器更配合、更少拒绝。
- NVIDIA 用户：FP8 文件 + 原生
CLIPLoader，最省事 - 显存紧张：Q4_K_M + mmproj + 补丁节点，5 GB 起步
- Mac 用户：bf16 全精度，稳稳运行
许可证为 Apache-2.0（见 LICENSE），可自由使用与再分发。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
