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):

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

各档位实测质量

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

两个值得注意的点:

• 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)做全量比对:

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

怎么选

不建议 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 获取:

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,官方支持以下宽高比

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。使用前请阅读原始许可条款。