wwdsada/qwenimage21gguf

Qwen-Image-2.1 — GGUF

Qwen-Image-2.1 扩散模型(DiT)的 GGUF 量化版本, 面向 stable-diffusion.cpp 与 ComfyUI-GGUF 的低显存推理。

⚠️ 本仓库仅包含 DiT(扩散模型)权重。文本编码器与 VAE 需另外获取,见 配套组件。

关于 Qwen-Image-2.1

• 统一的文生图 + 图像编辑模型
• 视觉生成组件 7B 参数、32 层 Single-Stream DiT
• 混合粒度注意力 + prefix KV cache 复用,兼顾质量与推理效率
• 支持原生 RGBA 透明图生成与编辑
• 图像编辑最多支持 10 张参考图,可用圈选 / 涂鸦 / 遮罩指定局部编辑
• 调度器:Flow Matching + Euler discrete(dynamic shifting)

量化档位

全部档位均为 265 个张量、7.115 G 参数。源模型 265 个张量全部为 BF16; 转换时其中 65 个 1D norm 张量被提升为 F32(32× attn.norm_q.weight、 32× attn.norm_k.weight、1× txt_in.text_norm.weight),这是对 QK-Norm 的精度保护, 属无损位宽扩展(BF16 左移 16 位补零 → F32,数值零损失),并非量化误差。 量化档位另有 3 个敏感张量保持 BF16:img_in.weight、txt_in.in_layer.weight、 txt_in.out_layer.weight(量化器按 img_in. / txt_in. 前缀硬编码排除)。

M / S / L 的差别只在一处:32 个 attn.to_v.weight 被升一级。 img_mlp.out.weight 不匹配任何 ffn_down 规则,所以留在基础档。升级规则(源码 img_tensor_get_type):

档位	to_v 升级为	实测
Q5_K_M / Q4_K_M	全部 → Q6_K	Q6_K × 32
Q3_K_L	全部 → Q5_K	Q5_K × 32
Q3_K_M	前 2 个 → Q5_K,其余 Q4_K	Q4_K × 30 + Q5_K × 2
Q4_K_S	前 4 个 → Q5_K,其余 Q4_K	Q4_K × 28 + Q5_K × 4
Q2_K	全部 → Q3_K	Q3_K × 32
Q8_0 / Q6_K / Q5_K_S / Q3_K_S	不升级	无

"前 N 个" 按 GGUF 内张量写入顺序(字典序)计数,所以实际是第 0、1、10、11 层, 不是第 0~3 层。这一点常被误读。

文件	大小	量化类型分布	说明
qwen-image-2.1-BF16.gguf	13.25 GiB	BF16 200 / F32 65	无损基准,体积最大
qwen-image-2.1-Q8_0.gguf	7.07 GiB	Q8_0 197 / BF16 3 / F32 65	质量最接近原版,首选
qwen-image-2.1-Q6_K.gguf	5.47 GiB	Q6_K 197 / BF16 3 / F32 65	质量与体积平衡
qwen-image-2.1-Q5_K_M.gguf	4.66 GiB	Q5_K 165 / Q6_K 32 / BF16 3 / F32 65	比 Q5_K_S 略好
qwen-image-2.1-Q5_K_S.gguf	4.60 GiB	Q5_K 197 / BF16 3 / F32 65
qwen-image-2.1-Q4_K_M.gguf	3.90 GiB	Q4_K 165 / Q6_K 32 / BF16 3 / F32 65	推荐,质量损失小
qwen-image-2.1-Q4_K_S.gguf	3.78 GiB	Q4_K 193 / Q5_K 4 / BF16 3 / F32 65	性价比不如 Q4_K_M
qwen-image-2.1-Q3_K_L.gguf	3.03 GiB	Q3_K 165 / Q5_K 32 / BF16 3 / F32 65
qwen-image-2.1-Q3_K_M.gguf	2.97 GiB	Q3_K 165 / Q4_K 30 / Q5_K 2 / BF16 3 / F32 65
qwen-image-2.1-Q3_K_S.gguf	2.90 GiB	Q3_K 197 / BF16 3 / F32 65	不推荐
qwen-image-2.1-Q2_K.gguf	2.28 GiB	Q2_K 165 / Q3_K 32 / BF16 3 / F32 65	极限压缩,画质损失明显

各档位实测质量

以原生 bf16 safetensors 为基准,抽样 11 个张量(覆盖 attn q/out、img_mlp、txt_in、 img_in/proj_out 及 F32 提升张量)反量化比对:

档位	余弦	相对 RMSE	最大绝对误差
BF16	1.0000000	0.000%	0.00000
Q8_0	0.9999725	0.742%	0.00598
Q6_K	0.9997386	2.287%	0.02393
Q5_K_M / Q5_K_S	0.9989987	4.475%	0.06301
Q4_K_M / Q4_K_S	0.9960965	8.839%	0.10559
Q3_K_L / Q3_K_M / Q3_K_S	0.9836174	18.246%	0.26800
Q2_K	0.9415860	35.453%	0.35107

两个值得注意的点:

• img_in.weight、txt_in.in_layer.weight、txt_in.out_layer.weight 误差恒为 0.000% —— 它们是保 BF16 的 3 个张量;attn.norm_q.weight、txt_in.text_norm.weight 同样为 0.000% —— 它们是 F32 提升张量,不参与量化。
• M 版与 S 版在抽样上误差相同,因为差异只落在 attn.to_v.weight 这 32 个张量上, 而抽样误差统计的是最大值,被未升级的大张量主导。M 版的收益体现在 to_v 上。

与原生 bf16 的等价性(已逐张量验证)

以 Comfy-Org/Qwen-Image-2.1 的 diffusion_models/qwen_image_2.1_bf16.safetensors (14,230,280,616 B)为基准,对 qwen-image-2.1-BF16.gguf(14,230,294,688 B)做全量比对:

检查项	结果
张量名 / 数量 / 顺序	265 / 265,完全一致
200 个 BF16 张量数据	逐字节 100% 相同
65 个 F32 张量数据	100% 等于 BF16 无损扩展(左移 16 位补零),非量化
参数量	7.115 G,完全相同
文件体积差	+14,072 B(0.0001%),全部来自头部与 32 字节对齐 padding

即 BF16 档在数值上与原生 bf16 safetensors 完全等价,唯一区别是容器格式 (ggml 张量维度按 ne[0] 最快变化存储,与 safetensors 的行优先布局互为逆序描述, 实际内存排布一致)。用 Q8_0 及以上档位时,唯一损失来自量化本身。

怎么选

显存	建议档位
6 ~ 8 GB	Q4_K_M(优先)/ Q3_K_M
8 ~ 12 GB	Q5_K_M / Q6_K
12 GB 以上	Q8_0
精度对比测试	BF16

不建议 Q3_K_S 与 Q2_K:Q3 档整体已到 18% 相对误差、余弦 0.984, 出图会出现明显退化;Q2_K 余弦只有 0.942、误差 35%,基本只适合做体积下限测试。 Q3_K_L / Q3_K_M 与 Q3_K_S 的抽样误差完全相同,但前者把 32 个 to_v 升了级, 实际观感会好于 Q3_K_S,多出的体积是值得的。

注意:显存只是下限。Qwen-Image-2.1 原生分辨率 2048×2048,高分辨率下激活值占用显著, 实际可用档位还取决于分辨率与 batch。显存吃紧时配合 --offload-to-cpu 或 ComfyUI 的分块加载。

配套组件

DiT 之外还需要以下两个组件,可从 Comfy-Org/Qwen-Image-2.1 获取:

组件	文件	放置目录
文本编码器(Qwen3-VL-8B)	qwen3vl_8b_bf16.safetensors	models/text_encoders/
VAE	qwen_image_2.1_vae_bf16.safetensors	models/vae/

ComfyUI 使用

📂 ComfyUI/models/
├── unet/                                    ← 本仓库的 GGUF 放这里
│   └── qwen-image-2.1-Q4_K_M.gguf
├── text_encoders/
│   └── qwen3vl_8b_bf16.safetensors
└── vae/
    └── qwen_image_2.1_vae_bf16.safetensors

需要安装 ComfyUI-GGUF,用 Unet Loader (GGUF) 节点加载。 ComfyUI 本体需要支持 Qwen-Image-2.1 架构的版本。

推荐参数

• 步数:40(官方推荐)
• CFG:官方示例未显式设置,使用 pipeline 默认值;ComfyUI 中从 4.0 起调
• 分辨率:原生 2048×2048,官方支持以下宽高比

比例	分辨率
1:1	2048 × 2048
4:3	2400 × 1792
3:4	1792 × 2400
3:2	2528 × 1696
2:3	1696 × 2528
16:9	2752 × 1536
9:16	1536 × 2752

RGBA 透明图

生成透明背景图时,推荐使用官方指定的 prompt 格式:

This is an RGBA image with transparency. <你的描述>. The image has alpha channel and the background is transparent.

量化方法

使用 stable-diffusion.cpp 的 convert 模式, 从官方 bf16 单文件权重转换:

sd-cli -M convert qwen_image_2.1_bf16.safetensors \
       -o qwen-image-2.1-Q8_0.gguf \
       --type q8_0

--type 可取 f32 / f16 / q8_0 / q6_K / q5_K / q4_K / q3_K / q2_K 等。 转换只需 CPU 与内存,不需要 GPU。

本仓库全部 11 个文件的 SHA256 均已与本地源文件逐一校验一致。

许可证

本模型继承 Qwen-Image-2.1 的 Qwen Research License Agreement。使用前请阅读原始许可条款。