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):
"前 N 个" 按 GGUF 内张量写入顺序(字典序)计数,所以实际是第 0、1、10、11 层, 不是第 0~3 层。这一点常被误读。
各档位实测质量
以原生 bf16 safetensors 为基准,抽样 11 个张量(覆盖 attn q/out、imgmlp、txtin、 imgin/projout 及 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, 出图会出现明显退化;Q2K 余弦只有 0.942、误差 35%,基本只适合做体积下限测试。 `Q3KL` / `Q3KM` 与 `Q3KS` 的抽样误差完全相同,但前者把 32 个 `tov 升了级, 实际观感会好于 Q3KS`,多出的体积是值得的。
注意:显存只是下限。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。使用前请阅读原始许可条款。