stable-diffusion.cpp 实战指南:在纯 C/C++ 推理框架中运行 Qwen Image Edit 系列图像编辑模型
stable-diffusion.cpp 实战指南:在纯 C/C++ 推理框架中运行 Qwen Image Edit 系列图像编辑模型
Qwen Image Edit 是通义千问团队推出的指令式图像编辑模型,支持通过自然语言指令直接修改参考图中的局部内容。本文基于 stable-diffusion.cpp 官方文档 docs/qwen_image_edit.md 与仓库源码,完整介绍 Qwen Image Edit / Edit 2509 / Edit 2511 三个版本的权重下载、CLI 运行命令与关键参数解析,并结合 QwenImageRunner 的实现说明其底层编辑原理。读完本文,你将能够在 CPU 或 GPU 环境下,用一条命令完成"以文改图"的图像编辑任务。
一、模型与版本概览
Qwen Image Edit 系列是 Qwen Image 的指令编辑版本,与单纯的文生图模型不同,它接受一张参考图(reference image)+ 一段自然语言指令,输出修改后的新图。stable-diffusion.cpp 当前支持三个子版本:
| 版本 | 说明 | 下载来源(safetensors / gguf) |
|---|---|---|
| Qwen Image Edit | 基础版图像编辑模型 | Comfy-Org 的 split_files/diffusion_models;GGUF 见 QuantStack 的 Qwen-Image-Edit-GGUF |
| Qwen Image Edit 2509 | 2509 迭代版本 | 同一 Comfy-Org 目录;GGUF 见 QuantStack 的 Qwen-Image-Edit-2509-GGUF |
| Qwen Image Edit 2511 | 2511 迭代版本,需开启 qwen_image_zero_cond_t=true |
同一 Comfy-Org 目录;GGUF 见 unsloth 的 Qwen-Image-Edit-2511-GGUF |
本文仅介绍各权重的官方获取渠道,不提供外部链接;具体下载地址请以 docs/qwen_image_edit.md 中列出的 Hugging Face 仓库为准。
从源码看,三个版本共享同一个 QwenImageRunner 推理实现,版本差异通过 SDVersion(如 VERSION_QWEN_IMAGE、VERSION_QWEN_IMAGE_LAYERED)区分,并由 model_builders.cpp 在构建模型时按版本路由到不同的条件编码器与扩散模型 runner。
二、权重下载与文件清单
运行 Qwen Image Edit 需要三类权重:
1. 扩散模型(Diffusion Model)
- Qwen Image Edit:safetensors 从 Comfy-Org/Qwen-Image-Edit_ComfyUI 的
split_files/diffusion_models目录下载;GGUF 量化版从 QuantStack/Qwen-Image-Edit-GGUF 下载(文档示例中使用Qwen_Image_Edit-Q8_0.gguf)。 - Qwen Image Edit 2509:safetensors 同源;GGUF 从 QuantStack/Qwen-Image-Edit-2509-GGUF 下载(示例使用
Qwen-Image-Edit-2509-Q4_K_S.gguf)。 - Qwen Image Edit 2511:safetensors 同源;GGUF 从 unsloth/Qwen-Image-Edit-2511-GGUF 下载(示例使用
qwen-image-edit-2511-Q4_K_M.gguf)。
2. VAE
- 从 Comfy-Org/Qwen-Image_ComfyUI 的
split_files/vae目录下载qwen_image_vae.safetensors。VAE 负责将参考图编码为潜空间(latent),并在生成结束后把潜变量解码回像素图像。
3. 文本编码器(LLM / Vision LLM)
- Qwen2.5-VL 7B:safetensors 从 Comfy-Org/Qwen-Image_ComfyUI 的
split_files/text_encoders目录下载;GGUF 从 mradermacher/Qwen2.5-VL-7B-Instruct-GGUF 下载。 - 2509 版本额外需要视觉投影文件:
Qwen2.5-VL-7B-Instruct.mmproj-Q8_0.gguf,对应 CLI 中的--llm_vision参数。
三个版本所需的文件清单如下:
| 版本 | 扩散模型 | VAE | LLM | 视觉投影 |
|---|---|---|---|---|
| Edit | Qwen_Image_Edit-Q8_0.gguf |
qwen_image_vae.safetensors |
qwen_2.5_vl_7b.safetensors |
无需 |
| Edit 2509 | Qwen-Image-Edit-2509-Q4_K_S.gguf |
qwen_image_vae.safetensors |
Qwen2.5-VL-7B-Instruct-Q8_0.gguf |
Qwen2.5-VL-7B-Instruct.mmproj-Q8_0.gguf |
| Edit 2511 | qwen-image-edit-2511-Q4_K_M.gguf |
qwen_image_vae.safetensors |
qwen_2.5_vl_7b.safetensors |
无需 |
三、CLI 运行命令与参数解析
1. Qwen Image Edit(基础版)
文档给出的命令如下(Windows 路径示例,Linux 下将 .exe 与 \ 替换为对应路径/分隔符即可):
.\bin\Release\sd-cli.exe --diffusion-model ..\models\diffusion_models\Qwen_Image_Edit-Q8_0.gguf --vae ..\models\vae\qwen_image_vae.safetensors --llm ..\models\text_encoders\qwen_2.5_vl_7b.safetensors --cfg-scale 2.5 --sampling-method euler -v --offload-to-cpu --diffusion-fa --flow-shift 3 -r ..\assets\flux\flux1-dev-q8_0.png -p "change 'flux.cpp' to 'edit.cpp'" --seed 1118877715456453
2. Qwen Image Edit 2509
2509 版本与前者的关键差异在于多了一个 --llm_vision 参数,用于加载视觉编码器投影文件(.mmproj):
.\bin\Release\sd-cli.exe --diffusion-model ..\models\diffusion_models\Qwen-Image-Edit-2509-Q4_K_S.gguf --vae ..\models\vae\qwen_image_vae.safetensors --llm ..\models\text_encoders\Qwen2.5-VL-7B-Instruct-Q8_0.gguf --llm_vision ..\models\text_encoders\Qwen2.5-VL-7B-Instruct.mmproj-Q8_0.gguf --cfg-scale 2.5 --sampling-method euler -v --offload-to-cpu --diffusion-fa --flow-shift 3 -r ..\assets\flux\flux1-dev-q8_0.png -p "change 'flux.cpp' to 'Qwen Image Edit 2509'"
3. Qwen Image Edit 2511
2511 版本必须开启 --model-args qwen_image_zero_cond_t=true,文档明确指出:不开启该选项时图像编辑质量会显著下降:
.\bin\Release\sd-cli.exe --diffusion-model ..\models\diffusion_models\qwen-image-edit-2511-Q4_K_M.gguf --vae ..\models\vae\qwen_image_vae.safetensors --llm ..\models\text_encoders\qwen_2.5_vl_7b.safetensors --cfg-scale 2.5 --sampling-method euler -v --offload-to-cpu --diffusion-fa --flow-shift 3 -r ..\assets\flux\flux1-dev-q8_0.png -p "change 'flux.cpp' to 'edit.cpp'" --model-args qwen_image_zero_cond_t=true
4. 关键参数一览
| 参数 | 作用 | 示例值 |
|---|---|---|
--diffusion-model |
扩散模型(DiT)权重路径,GGUF 或 safetensors 均可 | ..\models\diffusion_models\Qwen_Image_Edit-Q8_0.gguf |
--vae |
VAE 权重路径,用于参考图编码与结果解码 | ..\models\vae\qwen_image_vae.safetensors |
--llm |
文本/视觉 LLM 主干权重 | ..\models\text_encoders\qwen_2.5_vl_7b.safetensors |
--llm_vision |
(2509 必需)视觉编码器 mmproj 投影文件 | Qwen2.5-VL-7B-Instruct.mmproj-Q8_0.gguf |
--cfg-scale |
无分类器引导强度,数值越大越贴近提示词 | 2.5 |
--sampling-method |
采样器,示例使用 euler |
euler |
--flow-shift |
Flow Matching 的时间步偏移量 | 3 |
--diffusion-fa |
开启 Flash Attention 加速扩散模型注意力计算 | 开关 |
--offload-to-cpu |
将部分层卸载到 CPU 以节省显存 | 开关 |
-r / --ref-image |
参考图路径(被编辑的原图) | ..\assets\flux\flux1-dev-q8_0.png |
-p / --prompt |
编辑指令,例如 "change 'flux.cpp' to 'edit.cpp'" | 文本 |
--seed |
随机种子,保证可复现 | 1118877715456453 |
--model-args |
模型级参数,2511 需设 qwen_image_zero_cond_t=true |
qwen_image_zero_cond_t=true |
四、源码级原理:参考图如何参与编辑
1. 参考图的加载与潜空间编码
在 CLI 中通过 -r 传入的参考图,在 examples/cli/main.cpp 中被加载为 ref_images,随后进入 pipeline/image.cpp 的处理流程:每张参考图先被送入 VAE 编码为潜空间张量(ref_latents),并跟随扩散过程参与 DiT 的每一轮去噪。
2. 参考潜变量与主潜变量的拼接
在 QwenImageRunner::build_graph 中,主图像潜变量与参考图潜变量(ref_latents)会先被 patchify 成 token 序列,然后沿序列维度拼接(ggml_concat),形成一个包含"待编辑图像 token + 参考图像 token"的联合序列,再送入 Transformer 块进行联合注意力计算。这解释了为什么编辑任务必须同时提供参考图和文本指令——两者在同一个注意力空间内被融合。
3. qwen_image_zero_cond_t 背后的调制机制
2511 版本强制要求的 qwen_image_zero_cond_t=true 对应源码中的 QwenImageConfig::zero_cond_t 字段。该字段的取值有两层来源:
- 权重自动探测:在 QwenImageConfig::detect_from_weights 中,若权重张量名包含
__index_timestep_zero__,则自动置为true; - 命令行覆盖:在 QwenImageRunner 构造函数 中解析
--model-args qwen_image_zero_cond_t=true,通过parse_strict_bool校验后与默认值做或合并。
开启该模式后,build_graph 会为图像 token 与参考 token 分别构造 modulate_index 调制索引(主图 token 为 0,参考 token 为 1),让 DiT 块在每一层显式区分"要修改的区域"与"保持不变的参考区域",从而显著提升编辑保真度——这正是文档中"不开启则编辑质量明显下降"的源码级解释。
4. 条件编码器:LLM + Vision
在 model_builders.cpp 中,Qwen Image 系列使用 LLMEmbedder 作为条件编码器,enable_vision 的取值区分是否加载视觉编码器(2509 的 --llm_vision 对应视觉投影模块)。文本指令与图像特征共同被编码为上下文序列,作为 DiT 的 context 输入,最终参与 QwenImageRunner::build_graph 中的注意力计算。
五、运行注意事项与调优建议
- 版本与参数必须匹配:Edit 2509 需要
--llm_vision;Edit 2511 必须加--model-args qwen_image_zero_cond_t=true。用错组合会导致权重加载失败或编辑质量严重下降。 - 量化选择:示例中分别使用 Q8_0 / Q4_K_S / Q4_K_M 三种 GGUF 量化,显存紧张时可优先选择 Q4 系列;
--offload-to-cpu可进一步缓解显存压力,代价是推理速度下降。 - 显存优化:
--diffusion-fa开启 Flash Attention 可显著降低注意力计算的开销;-v开启详细日志便于排查加载与推理问题。 - 可复现性:固定
--seed可获得稳定输出;编辑指令-p应尽量具体,例如将文字区域改成目标内容时直接描述目标文本。 - 提示词与引导:
--cfg-scale 2.5与--flow-shift 3是文档推荐的默认组合,如需更强的一致性可小幅上调--cfg-scale,但过大会导致过饱和。
六、更多参考资料
- 完整官方文档:docs/qwen_image_edit.md
- 扩散模型实现:src/model/diffusion/qwen_image.hpp
- 模型构建与版本路由:src/pipeline/model_builders.cpp
- 参考图处理管线:src/pipeline/image.cpp
- 运行示例图:
assets/qwen/qwen_image_edit.png、assets/qwen/qwen_image_edit_2509.png、assets/qwen/qwen_image_edit_2511.png
本文所涉及的命令与参数均以 stable-diffusion.cpp 当前仓库 docs/qwen_image_edit.md 为准;权重文件需从文档列出的 Hugging Face 仓库自行下载后按上述路径组织即可运行。

