在 stable-diffusion.cpp 中运行 Qwen Image 2.1:文生图、图像编辑与 Prefix 缓存实战指南

原创2026-09-28 18:11:152,920 阅读
文章标签:人工智能推理引擎本地部署媒体生成

在 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 的推理需要三部分权重:

  1. Diffusion 主模型(Qwen Image 2.1):负责生成潜在空间中的图像表征,可从 Comfy-Org/Qwen-Image-2.1 仓库的 diffusion_models 目录获取 safetensors 格式,或从 leejet/Qwen-Image-2.1-GGUF 获取 GGUF 量化格式。
  2. 专属 VAE(Qwen Image 2.1 VAE):负责在像素空间与潜在空间之间转换。必须使用 qwen_image_2_1_vae_bf16.safetensors,从 Comfy-Org/Qwen-Image-2.1 的 vae 目录下载。
  3. 文本编码器(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 量化下的运行示例:

输入 提示词 输出
Qwen Image 2.1 alpha 输入示例 1 This is an RGBA image with transparency. Replace the text "BLOOM" with "Qwen Image 2.1", keeping the same font of the original text. The image has alpha channel and the background is transparent. Qwen Image 2.1 alpha 输出示例 1
alpha 输入示例 2 This is an RGBA image with transparency. Remove the background of the image, keeping only the text and cat. The image has alpha channel and the background is transparent. Qwen Image 2.1 alpha 输出示例 2

从源码看,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 中,与本模型相关的更多资料还包括:

总结

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。

登录后查看全文
stable-diffusion.cpp