在 stable-diffusion.cpp 中运行 Qwen Image 2.1:文生图、图像编辑与 Prefix 缓存实战指南
在 stable-diffusion.cpp 中运行 Qwen Image 2.1:文生图、图像编辑与 Prefix 缓存实战指南
导读
Qwen Image 2.1 是阿里通义团队推出的多模态图像生成模型,支持文本生成图像与图像编辑两大能力,其架构以 Qwen3-VL-8B 作为文本编码器,并搭配专属 VAE 完成潜在空间编解码。stable-diffusion.cpp 通过 src/model/diffusion/qwen_image_2_1.hpp 对该模型提供了完整的纯 C/C++ 推理支持。读完本文,你将掌握:如何下载与搭配 Qwen Image 2.1 所需的 Diffusion、VAE 与文本编码器权重;如何用 sd-cli 命令行完成文生图、图像编辑与多参考图编辑;如何利用 Prefix 缓存与不同量化缓存类型显著节省显存;以及如何通过提示词触发该模型特有的透明通道(RGBA)输出。
一、模型架构与权重搭配
1.1 三件套:Diffusion 主模型 + 专属 VAE + Qwen3-VL 文本编码器
根据 docs/qwen_image_2.1.md 的说明,Qwen Image 2.1 的推理需要三部分权重:
- Diffusion 主模型(Qwen Image 2.1):负责生成潜在空间中的图像表征,可从 Comfy-Org/Qwen-Image-2.1 仓库的
diffusion_models目录获取 safetensors 格式,或从 leejet/Qwen-Image-2.1-GGUF 获取 GGUF 量化格式。 - 专属 VAE(Qwen Image 2.1 VAE):负责在像素空间与潜在空间之间转换。必须使用
qwen_image_2_1_vae_bf16.safetensors,从 Comfy-Org/Qwen-Image-2.1 的vae目录下载。 - 文本编码器(Qwen3-VL-8B-Instruct):同时承担文本理解与视觉理解(编辑时需要)。safetensors(BF16 或 INT8 convrot)在 Comfy-Org/Qwen-Image-2.1 的
text_encoders目录;GGUF 量化版本在 Qwen/Qwen3-VL-8B-Instruct-GGUF。
关键兼容性提醒:Qwen Image 2.1 的 VAE 与早期的 Qwen Image 或 Wan 2.2 VAE 权重不可互换,必须使用专用版本。
1.2 源码中的模型结构
从源码结构看,QwenImage21Config 定义了模型的关键超参数:
in_channels = 64、out_channels = 64:输入输出通道数;hidden_size = 4096、context_dim = 4096:隐藏维度与文本上下文维度;head_dim = 128:每个注意力头的维度,共有hidden_size / head_dim = 32个头;num_layers = 32:默认 32 层 Transformer;axes_dim = {16, 56, 56}:多维 RoPE 的轴向频率维度。
detect_from_weights 会根据权重张量(如 img_in.weight、transformer_blocks.0.attn.norm_q.weight)自动推断实际层数、隐藏维度与 MLP 结构(支持 fused_mlp 门控融合变体),因此同一份代码可以适配不同规模的权重。
模型主体 QwenImage21Model 的结构(src/model/diffusion/qwen_image_2_1.hpp)包含:
txt_in(QwenImage21TextProjection):将 Qwen3-VL 输出的文本上下文投影到模型隐藏空间,使用 Zero-Center RMSNorm、in_layer/out_layer两个 Linear 与 GELU 激活;img_in:将 patch 化后的图像潜在张量嵌入隐藏空间;modulation.1:由时间步嵌入产生 AdaLN 调制参数;- 32 个
QwenImage21TransformerBlock:包含 LayerNorm、带多维 RoPE 的注意力与 SwiGLU MLP; norm_out+proj_out:输出解码前的归一化与投影。
QwenImage21Runner::compute(src/model/diffusion/qwen_image_2_1.hpp)负责组装输入:图像潜在 x、文本条件 context(要求 batch 为 1)、以及可选的参考图潜在 ref_latents(编辑场景)。注意力按 QwenImage21Segment 分段执行:文本段使用因果掩码,图像段与参考图段使用全注意力,最终通过 DiT::unpatchify_and_crop 还原为图像张量。
VAE 的权重名转换在 src/name_conversion.cpp 的 convert_diffusers_to_original_wan_vae 中实现:当版本为 VERSION_QWEN_IMAGE_2_1 时,启用专门的 downsamples/upsamples 命名映射,与 Wan 系 VAE 的通用映射区分开,印证了 VAE 权重的不可互换性。
二、文生图(Text to Image)
2.1 完整命令行
从构建目录执行以下命令(示例为 Windows PowerShell 风格):
.\bin\Release\sd-cli.exe --diffusion-model ..\models\diffusion_models\qwen_image_2_1_int8_convrot.safetensors --vae ..\models\vae\qwen_image_2_1_vae_bf16.safetensors --llm ..\models\text_encoders\Qwen3VL-8B-Instruct-Q4_K_M.gguf -p "a lovely cat holding a sign says 'qwen2.1.cpp'" --cfg-scale 6.0 --sampling-method euler -v --offload-to-cpu --fa -o qwen_image_2_1.png
参数说明:
| 参数 | 作用 |
|---|---|
--diffusion-model |
Diffusion 主模型路径,safetensors 或 GGUF 均可 |
--vae |
专属 VAE 路径,使用 qwen_image_2_1_vae_bf16.safetensors |
--llm |
文本编码器路径,推荐 GGUF 量化版如 Qwen3VL-8B-Instruct-Q4_K_M.gguf |
-p |
正向提示词 |
--cfg-scale |
分类器自由引导强度,示例 6.0 |
--sampling-method |
采样器,示例 euler |
-v |
详细日志输出 |
--offload-to-cpu |
显存不足时将部分层卸载到 CPU |
--fa |
启用 Flash Attention |
-o |
输出图片文件名 |
注意事项:
- 图像尺寸必须能被 32 整除(如 512×512、1024×1024 等);
- 与分辨率相关的 flow schedule 会自动选择,无需手动指定;
- 若使用 GGUF 格式的 Diffusion 权重,将
--diffusion-model指向如qwen_image_2_1-Q4_K.gguf的文件即可。
生成的示例效果可参考 assets/qwen/qwen_image_2.1.png。
2.2 从源码看参数如何生效
--diffusion-model、--vae、--llm 等参数在 examples/common/common.cpp 中被解析并写入 sd_ctx_params。其中 --llm_vision(视觉权重路径)在 examples/common/common.cpp 定义,并可通过 deprecated 的别名指定。模型构建时,src/pipeline/model_builders.cpp 通过 Qwen::QwenImage21Runner 实例化 Diffusion 模型,--fa 对应的 Flash Attention 开关则在 runner 内部影响注意力执行路径(详见下文 Prefix 缓存章节)。
三、图像编辑(Image Editing)
3.1 单参考图编辑
编辑模式需要额外的视觉权重(Vision weights)。示例中通过 --llm_vision 单独加载:
.\bin\Release\sd-cli.exe --diffusion-model ..\models\diffusion_models\qwen_image_2_1_int8_convrot.safetensors --vae ..\models\vae\qwen_image_2_1_vae_bf16.safetensors --llm ..\models\text_encoders\Qwen3VL-8B-Instruct-Q4_K_M.gguf --llm_vision ..\models\text_encoders\Qwen3VL-8B-Instruct-mmproj-BF16.gguf -r ..\assets\qwen\qwen_image_2.1.png -p "change 'qwen2.1.cpp' to 'sd.cpp'" --cfg-scale 6.0 --sampling-method euler -v --offload-to-cpu --fa -o qwen_image_2_1_edit.png
要点:
-r传入参考图像,-p描述要做的修改(如替换文字、改背景、换主体等);- 若文本编码器使用 GGUF,必须同时下载
mmproj-Qwen3VL-8B-Instruct-F16.gguf并通过--llm_vision传入; - 编辑结果的构图与质量由 Qwen3-VL 的视觉理解能力驱动,提示词应精确描述目标修改。
3.2 多参考图编辑
多个参考图按顺序重复 -r 即可,例如:
.\bin\Release\sd-cli.exe ... -r first.png -r second.png -p "combine the two subjects into one scene" ...
从源码看,QwenImage21Layout::build 会依据文本中的图像槽位(image_slots)与参考图张量形状构造段布局:每个参考图段与目标图段分别以 QwenImage21Segment 记录起点、终点、上下文起点与图像索引,并在 image_slots 与参考图数量不匹配时抛出异常,保证"文本中出现的图占位符数量 = 参考图数量 + 目标图"的一致性。
四、Prefix 缓存(Prefix Cache)
4.1 原理
默认情况下,每次去噪调用的第一步会为固定条件(文本、参考图)计算所有 Transformer 层的 K/V 并保存为前缀缓存;后续的多次去噪调用只计算目标图像的 token,直接复用缓存的 K/V。正负条件各使用独立的缓存,采样结束时释放。
源码层面的实现细节:
QwenImage21PrefixCache(src/model/diffusion/qwen_image_2_1.hpp)有三种模式:NONE(不使用)、STORE(写入缓存)、REUSE(复用缓存);- 写入时通过
ctx->persist_cache_tensor持久化每一层的 K/V,复用前如果缓存类型与当前计算类型不一致会先ggml_cast转回注意力输入类型再ggml_concat拼接(src/model/diffusion/qwen_image_2_1.hpp); - 缓存内容按
hidden_size连续打包成宽行,因此 256 元素的量化块可以直接用于 128 元素注意力头而不产生 padding(前提是类型的 block size 能整除hidden_size)。
4.2 缓存类型参数
通过 --model-args 设置 qwen_image_2_1_prefix_cache_type,取值与 --type 使用相同的解析器与大小写敏感命名:
auto(默认):仅在 Flash Attention 启用、Sage Attention 关闭、注意力 scale 未改变,且写缓存/读缓存图上的每个注意力操作都通过后端支持检查并选择 Flash Attention 时,才使用 FP16。若某个操作回退到普通注意力,则在执行前以 FP32 重建前缀,并在本次采样剩余过程中保持 FP32。f32:始终以 FP32 存储 K/V。f16:始终以 FP16 存储,包括普通注意力或自定义注意力 scale 场景。更省缓存内存,但可能引入额外舍入误差。- 其他类型(
bf16、q4_1、q5_0、q5_1、q8_0、q4_K、q6_K、iq4_nl、iq4_xs等):若当前 ggml 构建提供与 FP32 之间的运行时转换则可用。量化是有损的,必须显式选择;auto永远不会自动选择量化类型。
未知类型、缺少运行时转换的类型(如 q8_1 与部分 IQ 格式)、block size 与 hidden_size 不兼容的类型,会被忽略并打印警告,保持之前的设置或默认 auto。
例如:
.\bin\Release\sd-cli.exe ... --model-args qwen_image_2_1_prefix_cache_type=q8_0 ...
启用 8-bit 缓存存储后,缓存的 K/V 在拼接回目标 token 前会转回注意力输入类型。这会显著降低持久缓存内存,但注意力工作缓冲区仍使用浮点值,且每次转换都会增加计算量;缺少所需转换算子的后端会使用已有的 CPU fallback。
从源码看,类型校验逻辑(supports_prefix_cache_type,src/model/diffusion/qwen_image_2_1.hpp)会实际检查 CPU 后端是否支持 F32 -> type -> F32 的往返转换算子;qwen_image_2_1_prefix_cache=false 则可完全关闭此优化(src/model/diffusion/qwen_image_2_1.hpp)。注意:该优化复用与步数无关的激活,矩阵尺寸变化可能使数值结果产生细微差异。
4.3 缓存内存开销参考
对于默认 32 层模型,4096 token 前缀的每条件内存开销(不含权重、工作缓冲区与分配开销)约为:
| 缓存类型 | 内存 |
|---|---|
f32 |
4 GiB |
f16 |
2 GiB |
q8_0 |
1.0625 GiB |
q4_0 |
0.5625 GiB |
Runner 在检查内存预算时会计入缓存。若缓存执行时内存不足,会释放前缀缓存、禁用本次采样剩余的缓存,并重试一次完整序列。每个步进的 conditioning 扩展目前走完整序列路径。
源码中的自动回退机制(src/model/diffusion/qwen_image_2_1.hpp)说明了两点:一是 F16 缓存转回 F32 无法恢复原始值,因此当 Flash Attention 不可用时,会先释放缓存并以 FP32 重建前缀再执行;二是内存分配失败(GGML_STATUS_ALLOC_FAILED)时会释放缓存上下文并以无缓存模式重试,保证即使显存紧张也能完成任务,只是速度下降。
五、透明通道(Alpha Channel / RGBA)
Qwen Image 2.1 支持输出带透明通道的图片。模型通过提示词自行判断输出普通图还是透明图(官方推荐做法),因此要获得好的透明效果,建议使用如下提示词格式:
This is an RGBA image with transparency. <your description>. The image has alpha channel and the background is transparent.
由于透明与否由提示词决定,而非由输入图或显式开关决定,因此编辑场景同样适用该格式——无论参考图本身是否带 alpha 通道。
输出格式限制:透明通道只保留在 .png 与 .webp 输出中;保存为 .jpg 会丢失透明度。
以下是 Q6_K 量化下的运行示例:
从源码看,stable-diffusion.cpp 的预处理管线在 src/conditioning/conditioner.hpp 中支持 4 通道输入图:当 image.shape()[2] == 4 时按 rgb * alpha + (1 - alpha) 的方式将透明通道合成到 RGB 空间,再归一化到 [-1, 1],说明 RGBA 输入图在条件化阶段即被正确处理,与提示词驱动的透明输出相互配合。
六、其他特性与延伸阅读
Qwen Image 2.1 的更多能力(包括 2 个微调过的提示词改写模型 Qwen3.5-9B)可参考 QwenLM/Qwen-Image-2.1 官方模型卡。在 stable-diffusion.cpp 中,与本模型相关的更多资料还包括:
- docs/qwen_image.md:早期 Qwen Image 版本的使用指南;
- docs/qwen_image_edit.md:图像编辑功能的专题说明;
- docs/sd.md:stable-diffusion.cpp 基础用法与命令参数总览;
- docs/model_config.md:
--model-args等模型配置参数的详细说明; - docs/quantization_and_gguf.md:GGUF 量化格式与精度选择参考;
- examples/cli/README.md 与 examples/cli/main.cpp:CLI 入口与全部命令行参数;
- 模型实现源码:src/model/diffusion/qwen_image_2_1.hpp、VAE 名称转换:src/name_conversion.cpp、模型构建:src/pipeline/model_builders.cpp。
总结
Qwen Image 2.1 在 stable-diffusion.cpp 中形成了完整可用的推理链路:Qwen3-VL-8B 负责文本与视觉理解、专属 VAE 负责潜在空间转换、32 层 DiT 主干负责生成。实战中只需记住三条主线:文生图关注 Diffusion/VAE/LLM 三件套的搭配与 32 整除的尺寸;图像编辑额外加载 --llm_vision 视觉权重并用 -r 传入参考图;显存优化依赖 Prefix 缓存——默认 auto 在 Flash Attention 环境下自动启用 F16,也可通过 --model-args qwen_image_2_1_prefix_cache_type=<类型> 显式选择 f32/f16/q8_0/q4_0 等存储类型,在 4096 token 前缀下将每条件缓存内存从 4 GiB(f32)降至 1 GiB 以下(q8_0 约 1.06 GiB、q4_0 约 0.56 GiB)。透明通道输出则遵循官方提示词模板即可,注意仅 .png/.webp 保留 alpha。



