stable-diffusion.cpp 实战指南:在纯 C/C++ 推理框架中运行 Qwen Image Edit 系列图像编辑模型

原创2026-09-27 14:49:332,172 阅读
文章标签:人工智能推理引擎本地部署媒体生成

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

qwen_image_edit_2509 运行结果示例

四、源码级原理:参考图如何参与编辑

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 字段。该字段的取值有两层来源:

开启该模式后,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 中的注意力计算。

五、运行注意事项与调优建议

  1. 版本与参数必须匹配:Edit 2509 需要 --llm_vision;Edit 2511 必须加 --model-args qwen_image_zero_cond_t=true。用错组合会导致权重加载失败或编辑质量严重下降。
  2. 量化选择:示例中分别使用 Q8_0 / Q4_K_S / Q4_K_M 三种 GGUF 量化,显存紧张时可优先选择 Q4 系列;--offload-to-cpu 可进一步缓解显存压力,代价是推理速度下降。
  3. 显存优化:--diffusion-fa 开启 Flash Attention 可显著降低注意力计算的开销;-v 开启详细日志便于排查加载与推理问题。
  4. 可复现性:固定 --seed 可获得稳定输出;编辑指令 -p 应尽量具体,例如将文字区域改成目标内容时直接描述目标文本。
  5. 提示词与引导:--cfg-scale 2.5 与 --flow-shift 3 是文档推荐的默认组合,如需更强的一致性可小幅上调 --cfg-scale,但过大会导致过饱和。

六、更多参考资料

本文所涉及的命令与参数均以 stable-diffusion.cpp 当前仓库 docs/qwen_image_edit.md 为准;权重文件需从文档列出的 Hugging Face 仓库自行下载后按上述路径组织即可运行。

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