comfyui-sd-cpp — SD.cpp 生成节点（Vulkan 后端）

通过 sd-cli.exe（stable-diffusion.cpp， 纯 C++/ggml，Vulkan 后端）在 ComfyUI 里生成图像。

重要：本节点不使用 torch/CUDA/DirectML，图像生成全部由独立进程的 sd-cli.exe 完成， 走 Vulkan 图形 API —— 老卡、A 卡、核显也能跑（见下方兼容性）。

特点：所有组件直接在节点上选 —— diffusion_model 必选，llm / clip_l / clip_g / t5xxl / vae 按需选（全留空 = 单文件模型，自动用 -m 加载内嵌 clip+vae）。 VAE 解码、分块（--vae-tiling）、LoRA 全在 sd.cpp 内部完成。

兼容性（老卡延寿）

• Vulkan 要求：显卡驱动需支持 Vulkan 1.0+（2016 年后的显卡基本都行）：
  • NVIDIA GeForce 900 系及更新
  • AMD Radeon GCN 架构（HD 7000 系）及更新
  • Intel HD Graphics 530 / UHD 600 系及更新
  • 没有可用 GPU 也能跑（自动退回 CPU 后端，速度慢）
• 验证方法：命令行运行 sd-cli.exe --list-devices，能看到 Vulkan 设备即支持
• 显存：配合 --offload-to-cpu（默认开），2GB 显存都能跑（慢）

安装

1. 获取 sd.cpp 运行时（二选一）：
   • 自动（推荐）：双击仓库里的 download_sd_cpp.bat，自动下载官方 Vulkan 预编译包并解压到 bin/
   • 手动：https://github.com/leejet/stable-diffusion.cpp/releases 选 sd-master-*-bin-win-vulkan-x64.zip，解压 sd-cli.exe 及所有 DLL 到本目录 bin/ 下（全部平铺）
2. 模型放置（复用 ComfyUI 标准目录）：
   • 扩散模型 → models/checkpoints/（sd1.5/sdxl 等单文件）或 models/diffusion_models/（GGUF/safetensors/ckpt 均可）
   • 文本编码器 → models/text_encoders/ 或 models/clip/
   • VAE → models/vae/
3. 重启 ComfyUI。节点在菜单 sd.cpp 分类下：SD.cpp Generator (Vulkan)

使用起点

拖出节点后 diffusion_model 默认是 (none),必须自己选:

• 单文件模型（sd1.5 / sdxl）：只选 diffusion_model，llm/clip/vae 全留空， 节点自动用 -m 完整模型模式加载内嵌的 clip + vae
• 分离式模型（z-image / krea2 / flux2 等）：按需选 llm（文本编码器）+ vae
• 模型下载：
  • z_image_turbo-Q4_K.gguf：https://huggingface.co/leejet/Z-Image-Turbo-GGUF
  • Qwen3-4B 编码器：https://huggingface.co/unsloth/Qwen3-4B-Instruct-2507-GGUF
  • VAE（ae.safetensors）：https://huggingface.co/black-forest-labs/FLUX.1-schnell （或从 ComfyUI 的 flux 包里取 ae.safetensors）

用法

• diffusion_model：必选。模型文件，同架构内换量化档（Q3_K→Q8_0）直接选。 单文件（sd1.5/sdxl，含 clip+vae）放 models/checkpoints/；GGUF 放 models/diffusion_models/
• llm / clip_l / clip_g / t5xxl：文本编码器，按模型架构需要选。 全部留空 = 单文件模式（-m 加载）；选了任何一个 = 分离模式（--diffusion-model + 对应参数）
• vae：留空用模型内嵌 VAE（单文件模式）；或选外部 VAE 覆盖
• lora：选 loras 目录下的文件，自动以 <lora:名:强度> 注入 prompt
• scheduler：(auto) 让 sd.cpp 按模型自动选（SD1.5/SDXL→discrete）；SDXL 常用 karras
• 宽高：任意填，sd.cpp 自动向上对齐（SD1.5/SDXL→64 倍数，Flux/SD3→8 倍数）
• prompt 外部输入：ComfyUI 0.6 的文本输入框本身就带输入槽（widget 与连线共存）—— 想用反推图节点（WD14Tagger）或共享提示词（PrimitiveNode），直接把它的文本输出 连到节点的 prompt 输入槽即可，不用任何转换操作；断开后手填照常
• extra_args：追加任意 sd-cli 参数（如 --max-vram 12、--vae-tile-size 640）

两个 CPU 开关的真实语义

• clip_on_cpu：只影响传统 CLIP 三件套（clip_l / clip_g / t5xxl）。对 --llm 架构 （z-image / krea2 / flux2）完全无效（实测编码时间 2.02s vs 2.11s，无差别）。 flux1 / sd3.5（t5xxl fp16 约 9GB）建议开启省显存。
• vae_on_cpu：把 VAE 解码计算整个放 CPU——极慢（实测 512×1024 解码 93s vs GPU 2s， 约 50 倍差距）。默认关闭。什么时候才需要开：
  1. 跑图报显存不足 / Vulkan 分配失败，且 vae_tiling 已开启仍不够（1GB 级老卡 / 共享显存核显）
  2. 无独立显卡（纯 CPU 环境会自动走 CPU，无需手动开）
  • 优先用 vae_tiling 解决显存问题：GPU 上分块解码，实测解码 2.24s（无 tiling 1.86s）， 几乎无损，显存占用从 ~3.3GB 降到分块级——这才是老卡的正解。
• 核显 / 低显存（Intel Iris Xe + i5-1135G7 实测，2026-08-11）：
  • 节点默认注入 GGML_VK_ALLOW_SYSMEM_FALLBACK=1，但该变量对 UMA 核显无效—— ggml-vulkan 对 UMA 设备无条件尝试 3 种内存类型，与本变量无关。Iris Xe 实测 单次 Vulkan 分配上限约 200MB 级，Z-Image 的 345MB 计算缓冲仍会报 ErrorOutOfDeviceMemory / failed to allocate the compute buffer
  • 报上述错误时，在 extra_args 填： --max-vram vulkan0=0.2 --params-backend diffusion=cpu （实测 512×512 ≈ 156s，1024×1024 ≈ 903s；--params-backend 不影响出图， 但 --max-vram 图分段在 z-image 上会改变出图——需要标准结果请改用 --backend te=cpu,diffusion=cpu 全 CPU 兜底；sd1.5/sdxl 不受图分段影响）

图生图（v1.2+）

节点有两个图像输入口，二选一使用，不要同时接：

输入口	模式	原理	配套参数
init_image	传统重绘 (img2img)	原图加噪后按 denoise 重绘	denoise_strength
ref_image	参考图编辑	指令式改图（换装/换背景/扩图等）	ref_preset（+ 编辑 LoRA）

路线一：传统重绘（init_image）

提示词按描述目标画面写（不是指令）。denoise_strength 控制改动幅度：

0.2-0.3=微调(构图不变)｜0.4-0.5=中等改动｜0.7+=基本重画｜1.0≈文生图

• sd1.5 / sdxl：全强度可用
• Krea-2-Turbo：建议 ≤0.5
• Z-Image-Turbo：会出废图，别用这条路线

路线二：参考图编辑（ref_image，推荐）

提示词用指令式写法（英文效果最好）： make it snowing heavily, keep the cabin and trees unchanged

支持架构：Krea-2、FLUX.1-Kontext、Qwen-Image-Edit、Z-Image(Omni)、Cosmos 等 编辑类模型（sd1.5/sdxl 不支持）。走这条路线时 denoise_strength 无效。

Krea-2 必须配套编辑 LoRA，否则会出颜色失真+网纹废图。下载（放 models/loras/）：

• identity-edit（指令式编辑，换脸/扩图/试衣/换装）： https://huggingface.co/conradlocke/krea2-identity-edit （推荐 v1_2_r64，0.46GB，8G 卡友好）
• style reference（参考图画风）：搜 ostris krea2_turbo_style_reference

ref_preset 必须手动匹配（默认 default 不是自动档！）：

ref_preset	适用
krea2_edit	identity-edit LoRA
krea2_ostris_edit	ostris 风格 LoRA
flux_kontext	FLUX.1-Kontext
qwen	Qwen-Image-Edit
z_image_omni	Z-Image (Omni)
cosmos_reference	Cosmos
default	不传 preset 参数，走 sd-cli 按模型权重自动识别（用编辑 LoRA 时勿选此项）

推荐参数（Krea-2-Turbo + identity-edit 实测）

steps 8｜cfg_scale 1.0｜euler｜scheduler (auto)｜lora 选编辑 LoRA 强度 1.0； 宽高与参考图一致（比例不同会降低保真度）；带 LoRA 出图 1-3 分钟属正常。

示例工作流

见 example_workflows/： sdcpp_文生图.json、sdcpp_图生图.json（Krea-2 编辑，Note 节点含完整说明）， 下载后放进 ComfyUI/user/default/workflows/ 即可在工作列表打开。

新增架构 / 模型组合

不用改任何文件：直接在节点上选 diffusion_model + 对应的 llm / clip / vae 即可。 常用组合参考：

架构	diffusion_model	配套组件
sd1.5 / sdxl（单文件）	checkpoint/safetensors	全留空（内嵌 clip+vae）
z-image-turbo	z_image_turbo-Q4_K.gguf	llm=Qwen3-4B, vae=ae.safetensors
krea2	KREA-2 GGUF	llm=Qwen3-VL-4B, vae=wan_2.1_vae.safetensors
flux1-dev/schnell	FLUX.1 GGUF	clip_l + t5xxl + vae=ae.safetensors
sd3.5	SD3.5 GGUF	clip_l + clip_g + t5xxl
flux2-dev/klein	flux2 GGUF	llm=Mistral/Qwen3, vae=flux2_ae.safetensors

已知限制

• 黑盒：prompt→图，潜空间不暴露给 ComfyUI（解码必须在 sd.cpp 内部，它不吐 latent）
• 图生图仅上述两条路线；ControlNet 不支持（sd.cpp 上游仅 SD1.5 有 ControlNet， Z-Image/Krea2 等 DiT 架构无此功能；需要 ControlNet 请用原生 ComfyUI 工作流）
• 每次生成新起进程，大模型首次加载慢；后续可做常驻模式
• 采样器名与 sd.cpp master 一致（2026-08 起新命名）：euler / euler_a / heun / dpm2 / dpm++2s_a / dpm++2m / dpm++2mv2 / ipndm / ipndm_v / lcm / ddim_trailing / tcd / res_multistep / res_2s / er_sde / euler_cfg_pp / euler_a_cfg_pp / euler_ge / dpm++2m_sde / dpm++2m_sde_bt / lms