版本对应关系:本报告基于
/opt/sdcommitbb84971;当前锁定基准是6dcb5bb(见SD_VERSION.lock)。 中间经历7f410a3大重构(#1956/#1957,生成管线移到src/pipeline/,src/model.cpp、src/unet.hpp、src/clip.hpp、src/ggml_extend.hpp等旧路径已不存在),因此下文的文件路径与行号按旧结构书写, 查当前代码请以/opt/sd实际内容为准。本项目的改动清单与升级流程见design.md。本报告基于
/opt/sd(stable-diffusion.cpp)仓库,commitbb84971(refactor: move model-specific args into model parsers (#1757)),通过源码、include/stable-diffusion.h公开 C API 以及代码缓存索引/opt/code_caches/sd_cache/进行整理。
stable-diffusion.cpp(又称 sd.cpp)是 leejet 等人发起的纯 C/C++ 扩散模型推理项目,底层依赖 ggml,目标与 llama.cpp 类似:在本地 CPU/GPU 上零 Python 依赖地运行 Stable Diffusion、SDXL、SD3、FLUX、FLUX.2、Wan、LTX 等文生图/图生图/视频模型。
| 项目信息 | 说明 |
|---|---|
| 仓库路径 | /opt/sd |
| 当前 commit(报告基准) | bb84971 / bb84971129d2a094ab8051c6feed5406d3b4409d |
| 仓库当前锁定 commit | 6dcb5bb(见 SD_VERSION.lock) |
| 主要语言 | C++17 / C11 |
| 公开 API | include/stable-diffusion.h(纯 C) |
| 依赖 | ggml 子模块、thirdparty(zip 等)、可选 libwebp/libwebm |
| 跟踪文件数 | 约 344 个文件(其中 .c/.cpp/.h/.hpp 约 161 个,.md 约 48 个) |
src 目录大小 |
约 236 MB |
支持的模型族(参见 src/model.h:13 的 SDVersion 枚举):
- SD 1.x / 2.x / Inpaint / Instruct-Pix2Pix / Tiny UNet
- SDXL / SDXL Inpaint / SDXL Instruct-Pix2Pix / SDXL-Turbo
- SD3 / SD3.5
- FLUX.1-dev/schnell / FLUX.2-dev/klein / FLUX Fill / FLUX Control
- 图像模型:Lens、Chroma、Qwen Image、PiD、LongCat、Z-Image、MiniT2I、Ovis、Anima、Ernie、Boogu、Krea2、SeFi、Ideogram4、HiDream-O1 等
- 视频模型:Wan2.1/Wan2.2、LTX-2.3
- 辅助:PhotoMaker、ControlNet、LoRA、ESRGAN、TAESD
支持的后端:
- CPU(AVX / AVX2 / AVX512)
- CUDA(NVIDIA)
- HIPBLAS(AMD ROCm)
- Metal(Apple)
- Vulkan
- OpenCL(Adreno 为主)
- SYCL(Intel)
- MUSA(摩尔线程)
支持的权重格式:PyTorch checkpoint(.ckpt / .pth / .pt)、Safetensors(.safetensors)、GGUF(.gguf),以及 Diffusers 目录结构。
/opt/sd 的顶层目录如下:
/opt/sd
├── .github/ # CI / issue 模板
├── assets/ # Logo 等
├── cmake/ # CMake 配置模板
├── docker/ # Docker 构建文件
├── docs/ # 文档(build.md、sd.md、flux.md 等)
├── examples/ # 可执行示例
│ ├── cli/ # 命令行工具 sd-cli
│ ├── server/ # HTTP 服务 sd-server
│ └── common/ # CLI / Server 共用代码(参数解析、媒体 IO)
├── ggml/ # ggml 子模块
├── include/ # 公开 C API 头文件
│ └── stable-diffusion.h
├── scripts/ # 辅助脚本
├── src/ # 核心实现
│ ├── conditioning/ # 文本条件 / Embedding 注入
│ ├── core/ # GGML 扩展、backend 封装、张量工具、RNG
│ ├── extensions/ # PhotoMaker、PuLID 等扩展
│ ├── model/ # 模型结构定义
│ │ ├── diffusion/ # UNet / MMDiT / DiT / Flux 等扩散模型
│ │ ├── te/ # CLIP / T5 / LLM 文本编码器
│ │ ├── vae/ # AutoEncoderKL / TAESD / Wan / LTX VAE
│ │ └── upscaler/ # ESRGAN / LTX 潜在上采样
│ ├── model_io/ # safetensors / gguf / pickle / torch_zip 读取
│ ├── runtime/ # 采样器、去噪器、scheduler、缓存、预处理
│ ├── tokenizers/ # BPE / CLIP / T5 / Gemma / Qwen 等分词器
│ ├── model_loader.h/.cpp
│ ├── model_manager.h/.cpp
│ ├── stable-diffusion.cpp
│ └── upscaler.cpp
├── thirdparty/ # zip 等第三方代码
├── CMakeLists.txt
└── README.md
核心模块对应关系:
| 模块 | 主要文件 | 职责 |
|---|---|---|
| 公开 C API | include/stable-diffusion.h |
对外暴露的 C 接口与结构体 |
| 主入口 | src/stable-diffusion.cpp |
new_sd_ctx、generate_image、generate_video 等 API 实现;StableDiffusionGGML 主类 |
| 模型加载 | src/model_loader.h/.cpp |
多格式文件解析、张量元信息整理 |
| 权重管理 | src/model_manager.h/.cpp |
张量驻留模式、params backend / compute backend、LoRA 应用 |
| 文本条件 | src/conditioning/conditioner.hpp |
CLIP 编码器、Embedding 注入、权重文本解析 |
| 分词器 | src/tokenizers/ |
BPE、CLIP、T5、Gemma、Qwen 等 |
| 扩散模型 | src/model/diffusion/ |
UNet、MMDiT、DiT、Flux、Wan、LTX 等 |
| VAE | src/model/vae/ |
解码潜在向量到图像 |
| 采样器 | src/runtime/denoiser.hpp |
sigma 调度、K-diffusion 采样 |
| GGML 扩展 | src/core/ |
ggml_extend.h/.cpp、backend 初始化、graph cut |
一个典型的 SDXL txt2img 流程可以概括为:
[用户 prompt / negative prompt]
|
v
[CLIP 分词器] --BPE + 权重--> [token ids + weights]
|
v
[CLIP 文本编码器] (CLIP-L + OpenCLIP-G)
|
+---> [cond embeddings] (正向文本条件)
+---> [uncond embeddings] (空负向条件)
|
v
[采样 scheduler] 生成 sigma 序列
|
v
[初始潜在噪声] randn_like(latent_shape)
|
v
[UNet / DiffusionModel] 多步采样去噪
| 输入:x_t + timestep + context + y(pooled)
| 输出:预测噪声 / 速度 v / flow
|
v
[最终潜在 latent]
|
v
[VAE 解码器] 将 latent 解码为 RGB 图像
|
v
[后处理/量化] -> sd_image_t {width, height, channel, data}
|
v
[free_sd_images / 保存文件]
关键类层次:
StableDiffusionGGML(src/stable-diffusion.cpp:187):主控制器,持有ModelManager、Conditioner、DiffusionModelRunner、VAE、采样器、RNG 等。ModelManager(src/model_manager.h:15):负责张量注册、加载到 params backend、stage 到 compute backend、LoRA 合并。ModelLoader(src/model_loader.h:32):从文件解析出TensorStorage列表,并识别SDVersion。DiffusionModelRunner(src/model/diffusion/model.hpp:94):抽象基类,定义compute(...)接口。UNetModelRunner(src/model/diffusion/unet.hpp:692):传统 UNet 实现,用于 SD1.x/2.x/SDXL。MMDiTRunner(src/model/diffusion/mmdit.hpp):用于 SD3 / Flux 等 DiT 架构。VAE/AutoEncoderKL(src/model/vae/vae.hpp、src/model/vae/auto_encoder_kl.hpp):VAE 编码/解码包装。Conditioner(src/conditioning/conditioner.hpp):文本到条件的完整链路。
ModelLoader 统一支持以下格式(src/model_loader.h:32,src/model_loader.cpp):
| 格式 | 入口函数 | 说明 |
|---|---|---|
| GGUF | init_from_gguf_file |
读取 gguf_context 与 ggml_context 元数据 |
| Safetensors | init_from_safetensors_file |
通过 safe_read 解析 header 与张量偏移 |
| Torch zip | init_from_torch_zip_file |
基于 thirdparty/zip 解包 .pth/.ckpt |
| Torch legacy | init_from_torch_legacy_file |
旧版 pickle 协议 |
| Diffusers | init_from_diffusers_file |
读取 unet/、vae/、text_encoder/ 子目录 |
TensorStorage(src/model_io/tensor_storage.h)保存每个张量的:名称、GGML 类型、形状、数据文件偏移、所属文件索引。加载后按统一前缀映射到 String2TensorStorage(src/model.h:287),供后续模型构造使用。
BPETokenizer(src/tokenizers/bpe_tokenizer.h/.cpp):基础 BPE 实现,支持 webui 风格的 token 权重(()、[]、:)。CLIPTokenizer(src/tokenizers/clip_tokenizer.h/.cpp):继承BPETokenizer,加载 CLIP merges,添加<|startoftext|>/<|endoftext|>特殊 token。CLIPTextModel(src/model/te/clip.hpp:250):实现 CLIP 文本编码器,支持OPENAI_CLIP_VIT_L_14与OPEN_CLIP_VIT_H_14/OPEN_CLIP_VIT_BIGG_14(SDXL 的 CLIP-G)。CLIPTextModelRunner(src/model/te/clip.hpp:466):包装为GGMLRunner,可返回最后一层或倒数clip_skip层隐藏态,以及 pooled 投影。FrozenCLIPEmbedderWithCustomWords(src/conditioning/conditioner.hpp:141):支持自定义 Embedding( textual inversion )注入和权重文本。
DiffusionModelRunner(src/model/diffusion/model.hpp:94):所有扩散模型的基类,核心方法:virtual sd::Tensor<float> compute(int n_threads, const DiffusionParams& diffusion_params) = 0;
UNetModelRunner(src/model/diffusion/unet.hpp:692):构建UNetModel图,输入x、timesteps、context、c_concat、y,输出预测值。用于 SD1.x/2.x/SDXL/SVD 等 UNet 架构。MMDiTRunner(src/model/diffusion/mmdit.hpp):用于 SD3 / Flux 的 MMDiT(Multimodal Diffusion Transformer)架构。- Flux / Flux2 / Wan / LTX / Qwen / MiniT2I 等各自有独立的
*Runner子类,位于src/model/diffusion/。
DiffusionParams 结构(src/model/diffusion/model.hpp:70)包含 x、timesteps、context、c_concat、y、ref_latents 及 extra(如 UNetDiffusionExtra 的 ControlNet 控制)。
VAE(src/model/vae/vae.hpp:8):VAE 基类,提供encode()/decode()与 tiling 参数设置。AutoEncoderKL(src/model/vae/auto_encoder_kl.hpp):标准 SD 1.x/2.x/SDXL/SD3 VAE,包含Encoder和Decoder。TAESD(src/model/vae/tae.hpp):Tiny AutoEncoder,用于快速预览和低内存解码。WanVAE(src/model/vae/wan_vae.hpp)、LTXVideoVAE(src/model/vae/ltx_vae.hpp):视频 VAE。VAEtiling 支持空间切片(tile_size_x、tile_size_y、target_overlap),用于大分辨率图解码时降低显存占用。
采样逻辑集中在 src/runtime/denoiser.hpp:
Denoiser/CompVisDenoiser/EDMVDenoiser/EDMDenoiser/FlowDenoiser等:将模型的原始输出转换为去噪信号。SigmaScheduler及子类:DiscreteScheduler(离散线性)KarrasScheduler(Karras 边界)ExponentialScheduler、SGMUniformScheduler、LCMScheduler、BetaScheduler、AYSScheduler、GITSScheduler、LTX2Scheduler、FLUXScheduler、FLUX2Scheduler、LogitNormalScheduler等
sample_k_diffusion(src/runtime/denoiser.hpp:2663):根据sample_method_t分发 Euler、Euler-A、Heun、DPM2、DPM++2M、DPM++2S a、LCM、TCD、ER-SDE 等采样器。StableDiffusionGGML::sample(src/stable-diffusion.cpp:2184):将 UNet 调用、CFG、ControlNet、ref_latents、cache 等封装为单次采样。
RNG/PhiloxRNG/MT19937RNG(src/core/rng.hpp、rng_philox.hpp、rng_mt19937.hpp):支持CUDA_RNG(默认 webui 风格)和CPU_RNG(ComfyUI 风格)。preprocessing_tensor_to_sd_image/tensor_to_sd_image(src/core/util.cpp:678):将[H, W, C]的 float 张量量化为uint8_t的sd_image_t。examples/common/media_io.cpp:PNG / JPEG / WebP / PPM 等文件读写,以及 PNG 元数据嵌入(webui 参数格式)。
以 comfycli / sd-cli 常见的 SDXL txt2img 命令为例,其内部代码路径如下:
-
上下文创建
- 用户通过
sd_ctx_params_t设置:model_path(SDXL base)、clip_l_path、clip_g_path、vae_path(可选)、wtype、n_threads、rng_type、flash_attn等。 - 调用
new_sd_ctx(&ctx_params)(src/stable-diffusion.cpp:3337)构造StableDiffusionGGML并执行init()。
- 用户通过
-
模型加载
init()中ModelLoader依次读取 base、clip_l、clip_g、vae,随后convert_tensors_name()统一 key 名。- 通过
model_loader.get_sd_version()识别为VERSION_SDXL(src/model.h:23)。 - 根据
SDVersion创建FrozenCLIPEmbedderWithCustomWords和UNetModelRunner(src/stable-diffusion.cpp:652附近)。
-
文本条件
prepare_image_generation_embeds(src/stable-diffusion.cpp:4582)调用cond_stage_model->encode(...)。- SDXL 使用两套 CLIP:OpenAI CLIP-L(
cond_stage_model.transformer.)和 OpenCLIP-G(cond_stage_model.1.transformer.)。 - 正向 prompt 生成
cond,空字符串生成uncond;两者均包含hidden_states和pooled_projection(y)。
-
潜在初始化
prepare_image_generation_latents(src/stable-diffusion.cpp:4311)按width/8、height/8生成随机噪声 latent,并分配control_image(若启用 ControlNet)。
-
采样去噪
StableDiffusionGGML::sample(src/stable-diffusion.cpp:2184)按sample_method和scheduler构造 sigma 序列。- 默认 SDXL 常用
EULER_A_SAMPLE_METHOD+KARRAS_SCHEDULER。 - 每步调用
diffusion_model->compute(...)得到噪声预测;CFG 通过guidance.txt_cfg对cond与uncond做线性外推。
-
VAE 解码
- 去噪完成后得到
final_latents,decode_image_outputs(src/stable-diffusion.cpp:4674)调用first_stage_model->decode()。 - 输出被裁切到
[-1, 1]后映射到[0, 255],生成sd_image_t数组。
- 去噪完成后得到
-
输出
generate_image返回sd_image_t** images_out与num_images_out(include/stable-diffusion.h:466)。- 调用者使用
free_sd_images(...)释放内存,避免跨 CRT 问题(include/stable-diffusion.h:549)。
关键参数:
| 参数 | 典型值 | 作用 |
|---|---|---|
width / height |
1024×1024 | 输出尺寸,SDXL latent 为 128×128×4 |
sample_steps |
20~30 | 去噪迭代次数 |
txt_cfg |
7.0 | 无分类器引导强度 |
sample_method |
EULER_A_SAMPLE_METHOD |
采样算法 |
scheduler |
KARRAS_SCHEDULER |
sigma 调度方式 |
seed |
任意 | 噪声随机种子 |
clip_skip |
-1(默认) | 使用 CLIP 第几层隐藏态 |
include/stable-diffusion.h 是唯一的对外接口,所有类型、枚举、函数均使用 SD_API 宏导出。主要结构体:
| 结构体 | 关键字段 | 说明 |
|---|---|---|
sd_ctx_params_t |
model_path, clip_l_path, clip_g_path, t5xxl_path, vae_path, control_net_path, wtype, n_threads, rng_type, flash_attn, max_vram, backend, params_backend, split_mode, enable_mmap, lora_apply_mode 等 |
创建上下文所需的全局参数(include/stable-diffusion.h:186) |
sd_image_t |
width, height, channel, uint8_t* data |
图像数据块,由库内 malloc 分配(include/stable-diffusion.h:239) |
sd_sample_params_t |
guidance, scheduler, sample_method, sample_steps, eta, custom_sigmas, flow_shift 等 |
采样参数(include/stable-diffusion.h:261) |
sd_img_gen_params_t |
prompt, negative_prompt, width, height, seed, batch_count, init_image, mask_image, control_image, control_strength, loras, hires, vae_tiling_params, cache 等 |
图像生成参数(include/stable-diffusion.h:357) |
sd_vid_gen_params_t |
类似图像参数,额外包含 video_frames, fps, control_frames 等 |
视频生成参数(include/stable-diffusion.h:387) |
sd_lora_t |
is_high_noise, multiplier, path |
单个 LoRA(include/stable-diffusion.h:323) |
sd_hires_params_t |
enabled, upscaler, scale, target_width, target_height, steps, denoising_strength |
高清修复(include/stable-diffusion.h:343) |
sd_tiling_params_t |
enabled, tile_size_x, tile_size_y, target_overlap, rel_size_x, rel_size_y |
VAE tiling(include/stable-diffusion.h:162) |
sd_cache_params_t |
mode(SD_CACHE_EASYCACHE 等)及阈值参数 |
采样加速缓存(include/stable-diffusion.h:296) |
核心 API:
// 初始化参数结构体
void sd_ctx_params_init(sd_ctx_params_t* sd_ctx_params);
// 创建/释放上下文
sd_ctx_t* new_sd_ctx(const sd_ctx_params_t* sd_ctx_params);
void free_sd_ctx(sd_ctx_t* sd_ctx);
// 图像生成(当前签名)
bool generate_image(sd_ctx_t* sd_ctx,
const sd_img_gen_params_t* sd_img_gen_params,
sd_image_t** images_out,
int* num_images_out);
// 视频生成
bool generate_video(sd_ctx_t* sd_ctx,
const sd_vid_gen_params_t* sd_vid_gen_params,
sd_image_t** frames_out,
int* num_frames_out,
sd_audio_t** audio_out);
// 上采样
upscaler_ctx_t* new_upscaler_ctx(...);
bool upscale(upscaler_ctx_t* upscaler_ctx, sd_image_t input_image,
uint32_t upscale_factor, sd_image_t** images_out, int* num_images_out);
// 模型转换
bool convert(const char* input_path, const char* vae_path, const char* output_path,
enum sd_type_t output_type, const char* tensor_type_rules, bool convert_name);
bool convert_with_components(...);
// 回调与工具
void sd_set_log_callback(sd_log_cb_t cb, void* data);
void sd_set_progress_callback(sd_progress_cb_t cb, void* data);
void sd_set_preview_callback(sd_preview_cb_t cb, enum preview_t mode, ...);
void sd_cancel_generation(sd_ctx_t* sd_ctx, enum sd_cancel_mode_t mode);
void free_sd_images(sd_image_t* result_images, int num_images);
size_t sd_list_devices(char* buffer, size_t buffer_size);
const char* sd_get_system_info();
const char* sd_commit();
const char* sd_version();内存所有权:generate_image 返回的 images_out 必须由调用者通过 free_sd_images 释放。free_sd_images 会释放每个 sd_image_t.data 和数组本身,从而避免 Windows 上跨 CRT 释放问题(include/stable-diffusion.h:548)。
ModelLoader 通过文件魔数识别格式,并在 init_from_file 中分派(src/model_loader.h:53):
| 文件扩展 | 实际解析 | 说明 |
|---|---|---|
.gguf |
read_gguf_file(src/model_io/gguf_io.cpp:42) |
使用 gguf_init_from_file 或直接 GGUFReader |
.safetensors |
read_safetensors_file(src/model_io/safetensors_io.cpp) |
JSON header + 原始张量数据 |
.ckpt / .pth / .pt |
torch_zip_io.cpp / torch_legacy_io.cpp / pickle_io.cpp |
zip 包或 pickle 存储 |
| Diffusers 目录 | init_from_diffusers_file(src/model_loader.cpp:404) |
读取 unet/diffusion_pytorch_model.safetensors 等 |
张量名转换:
model_loader.convert_tensors_name()调用name_conversion.cpp中的规则,将 PyTorch / Diffusers 命名映射到项目内部统一命名(如model.diffusion_model.*、cond_stage_model.transformer.*、vae.*)。- 不同
SDVersion对命名前缀有特定要求(如 SDXL 的 CLIP-G 前缀为cond_stage_model.1.transformer.,见src/stable-diffusion.cpp:662)。
量化与张量类型:
sd_type_t枚举与ggml_type一一对应(include/stable-diffusion.h:93)。model_loader.set_wtype_override(...)可将权重覆盖到指定量化类型(如SD_TYPE_Q4_0)。tensor_type_rules支持按正则匹配指定某些层保持 FP16/FP32,其余层量化。
ModelManager 加载流程:
register_param_tensors/register_runner_params:模型将自身params字典注册到ModelManager。validate_registered_tensors:检查每个张量是否存在、形状是否匹配。- 根据
ResidencyMode(Disk或ParamBackend)与 backend 分配,将张量加载到params_backend的 buffer。 - 在计算前
prepare_params将张量 stage 到compute_backend。 - 若启用
enable_mmap,则通过mmap将文件直接映射到 backend buffer。
stable-diffusion.cpp 通过 ggml 的 backend 系统支持异构计算。后端管理位于 src/core/ggml_extend_backend.cpp 和 src/core/ggml_extend.h。
sd_get_default_backend()(src/core/ggml_extend_backend.cpp:533)优先使用用户指定的--backend,否则按编译选项选择 CUDA/HIP/Metal/Vulkan/CPU。StableDiffusionGGML::init_backend()为不同模块(TE、DIFFUSION、VAE、CONTROL_NET、UPSCALER)分别建立 runtime backend 和 params backend。
| CMake 选项 | 说明 |
|---|---|
-DSD_CUDA=ON |
NVIDIA CUDA,推荐 4GB+ VRAM |
-DSD_HIPBLAS=ON |
AMD ROCm |
-DSD_METAL=ON |
Apple Metal |
-DSD_VULKAN=ON |
Vulkan SDK |
-DSD_OPENCL=ON |
OpenCL(Adreno 为主) |
-DSD_SYCL=ON |
Intel SYCL |
-DSD_MUSA=ON |
摩尔线程 MUSA |
-DGGML_OPENBLAS=ON |
CPU 端 OpenBLAS |
max_vram(sd_ctx_params_t的字符串):指定以 GiB 为单位的 VRAM 预算或后端分配规则。启用后sd::backend_fit::derive_backend_specs会决定哪些模块放到 CPU/其他设备。auto_fit:自动根据预算切分计算图。ggml_graph_cut(src/core/ggml_graph_cut.h/.cpp):在图执行中插入切分点,将中间结果驻留到 CPU 或磁盘,实现参数卸载/流水线。stream_layers:在--max-vram基础上启用参数预取流。eager_load:模型加载时就把所有参数加载到 params backend,而非首次使用时懒加载。params_backend/backend:可分别指定参数存储后端和计算后端,例如参数放 CPU、计算在 CUDA。split_mode:支持layer或row切分,以及模块级分配如diffusion=row。
ggml_ext_attention_ext(src/core/ggml_extend.h,行号见当前源码)根据 flash_attn 标志与 mask 维度判断是否可调用 Flash Attention 内核;若不可行则回退到常规 reshape + matmul 实现。在 CUDA/Vulkan 等后端开启 flash_attn 可显著降低大上下文显存占用。
上游 sd_cache_params_t / SampleCacheRuntime 已内建,本项目只做胶水:
| 层 | 文件 | 改动 |
|---|---|---|
| 参数 | src/adapters/sdcpp_adapter.h |
ImageGenerationParams.cache_mode/threshold/start/end |
| 传入 | src/adapters/sdcpp_adapter.cpp |
generate() 写入 img_params.cache.mode 等 |
| CLI | examples/img_hires.cpp |
--cache-mode/--cache-threshold/--cache-start/--cache-end + 分段计时 |
| 脚本 | backup.sh / backup_qwen.sh / backup_scene.sh |
默认 CACHE_MODE=easycache(disabled 可关) |
| 构建 | build_sd_dl.sh |
GGML_CUDA_GRAPHS=ON(FA_ALL_QUANTS 不开,DiT K/V 为 F16) |
原理:EasyCache 在相邻步去噪结果变化小于阈值时复用上一步、跳过本步 forward(蒸馏 turbo 后期更易命中);CUDA graphs 把一步采样的 kernel 序列一次提交,减 launch 开销。
实测(3080 20G / 2560×1440 / E1xMIN seed=25630):~665s → 210s(3.2×),hires 531s→142s(跳 ~30/41)。详见 backup.sh 头注释。
LoraModel(src/model/adapter/lora.hpp)与 MultiLoraAdapter(src/model/adapter/lora.hpp)在运行时或加载时修改 Linear/Conv2d 的权重。
LORA_APPLY_AUTO:StableDiffusionGGML::init()中根据是否存在量化权重、params 是否卸载、是否启用 row split 自动决定立即合并还是运行时合并(src/stable-diffusion.cpp:815)。LORA_APPLY_IMMEDIATELY:在模型加载时通过ModelManager::apply_loras_to_params将 LoRA 合并到参数 buffer。LORA_APPLY_AT_RUNTIME:在每次 Linear/Conv2d 前向传播时通过MultiLoraAdapter::forward_with_lora动态计算out_diff并相加(src/model/adapter/lora.hpp:925)。
ControlNet(src/model/diffusion/control.hpp:311)读取 control_net 权重,在 UNet 各层下采样处注入控制特征。ControlNet::compute 接受 hint(如 canny 边缘图)并返回多尺度 controls,最终由 UNetModelRunner::compute 中的 control_strength 加权。
generate_image 中若 sd_hires_params_t.enabled 为真,则先完成一次低分辨率采样,然后:
- 按
upscaler选择上采样方式(latent 最近邻/bicubic/Lanczos/ESRGAN 模型)。 - 将 latent 放大到目标尺寸。
- 根据
denoising_strength裁剪新的 sigma 序列。 - 再次调用
StableDiffusionGGML::sample做二次去噪(src/stable-diffusion.cpp:5065)。
VAE::set_tiling_params(src/model/vae/vae.hpp:229)将用户参数转换为实际 latent tile 大小,在 encode/decode 中对大图像分块处理,降低单步显存峰值。LTXVideoVAE 额外支持时序切片(temporal_tiling)。
- PhotoMaker:
src/extensions/photomaker_extension.cpp通过 ID 图像修改 CLIP 条件。 - PuLID:
src/extensions/pulid_extension.cpp提供人脸 ID 保持能力。 - TAESD:低延迟预览和快速解码(
src/model/vae/tae.hpp)。 - ESRGAN:独立上采样模型(
src/model/upscaler/esrgan.hpp)。 - 采样缓存:
sd_cache_params_t支持EASYCACHE、UCACHE、DBCache、TAYLORSEER、SPECTRUM等策略,跳过相邻步骤间相似度高的计算。
注:当前
/opt/sd主干中并未直接内置 FreeU、Self-Attention Guidance(SAG)或 IP-Adapter 的完整实现。本兼容层通过最小 patch 在/opt/sd中加入了 FreeU/SAG 支持(见patches/sdcpp-freeu-sag-v2.patch),IP-Adapter 仍需后续扩展模块实现。
examples/cli/main.cpp 实现 sd-cli 可执行文件,支持以下运行模式:
img_gen, vid_gen, convert, upscale, metadata
典型命令:
# txt2img
./bin/sd-cli -m sd_xl_base_1.0.safetensors \
--clip-l clip_l.safetensors \
--clip-g clip_g.safetensors \
-p "a lovely cat" -n "blurry" \
-o output.png -W 1024 -H 1024 --steps 20 --cfg 7.0 -s 42
# 模型格式转换
./bin/sd-cli -M convert -m model.safetensors -o model.gguf --type q4_0
# 元数据查看
./bin/sd-cli -M metadata --image output.png参数解析:
SDCliParams定义 CLI 通用选项(输出、模式、预览、metadata 等)。SDContextParams(examples/common/common.h:116)映射到sd_ctx_params_t。SDGenerationParams(examples/common/common.h:185)映射到sd_img_gen_params_t。- 三者的
get_options()通过parse_options统一解析命令行(examples/common/common.h:109)。
examples/server/main.cpp 基于 httplib.h 构建 HTTP 服务,注册四类路由:
| 路由文件 | 说明 |
|---|---|
routes_index.cpp |
根页面 / 与静态资源 |
routes_openai.cpp |
OpenAI 兼容接口(/v1/images/generations 等) |
routes_sdapi.cpp |
Stable Diffusion WebUI API 风格接口 |
routes_sdcpp.cpp |
本项目自定义接口 |
运行时结构:
ServerRuntime(examples/server/runtime.h)持有sd_ctx_t*、LoRA 缓存、Upscaler 缓存、AsyncJobManager。AsyncJobManager维护后台任务队列,避免长请求阻塞 HTTP 线程。- 通过
sd_set_log_callback将库日志重定向到服务端日志输出。
典型启动:
./bin/sd-server -m model.safetensors --listen 0.0.0.0 --port 8080cd /opt/sd
git submodule update --init --recursive
mkdir build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release -DSD_BUILD_EXAMPLES=ON
cmake --build . -j$(nproc)产物:
build/bin/sd-clibuild/bin/sd-serverbuild/bin/libstable-diffusion.a(或.so若开启SD_BUILD_SHARED_LIBS)
mkdir build-cuda && cd build-cuda
cmake .. -DCMAKE_BUILD_TYPE=Release -DSD_CUDA=ON -DSD_BUILD_EXAMPLES=ON
cmake --build . -j$(nproc)| 选项 | 默认值 | 说明 |
|---|---|---|
SD_BUILD_EXAMPLES |
ON(standalone) |
构建 sd-cli 和 sd-server |
SD_WEBP / SD_WEBM |
依赖子模块 | 启用 WebP/WebM 图像/视频 IO |
SD_USE_SYSTEM_WEBP / SD_USE_SYSTEM_WEBM |
OFF |
使用系统 libwebp/libwebm |
SD_CUDA |
OFF |
CUDA 后端 |
SD_HIPBLAS |
OFF |
AMD ROCm 后端 |
SD_METAL |
OFF |
Apple Metal 后端 |
SD_VULKAN |
OFF |
Vulkan 后端 |
SD_OPENCL |
OFF |
OpenCL 后端 |
SD_SYCL |
OFF |
Intel SYCL 后端 |
SD_MUSA |
OFF |
MUSA 后端 |
SD_BUILD_SHARED_LIBS |
OFF |
构建动态库 |
SD_BUILD_SHARED_GGML_LIB |
OFF |
将 ggml 也构建为动态库 |
SD_USE_SYSTEM_GGML |
OFF |
使用系统已安装的 ggml |
SD_RPC |
OFF |
启用 RPC 后端 |
- 运行依赖:CUDA 构建产物需要
libcudart.so/libcublas.so/libcublasLt.so/libcuda.so(stub 或真实驱动)。 - 若使用
--max-vram或--params-backend CPU,需要确保参数后端 buffer 可用内存。 - 发布二进制时通常需保留
ggml后端共享库(如果SD_BUILD_SHARED_GGML_LIB=ON)和libwebp/libwebm依赖。
/opt/static_comfyui/cpp/stable-diffusion-cli_v1.cpp 是一个最小化的 SDXL txt2img 示例,其主流程如下:
- 命令行解析,收集
model、clip_l、clip_g、prompt、negative_prompt、width、height、steps、cfg、seed、output。 - 填充
sd_ctx_params_t:sd_ctx_params_t ctx_params; sd_ctx_params_init(&ctx_params); ctx_params.model_path = model; ctx_params.clip_l_path = clip_l; ctx_params.clip_g_path = clip_g; ctx_params.n_threads = 8; ctx_params.wtype = SD_TYPE_F16; ctx_params.rng_type = STD_DEFAULT_RNG; ctx_params.keep_vae_on_cpu = false;
- 创建上下文:
sd_ctx_t* ctx = new_sd_ctx(&ctx_params); - 填充
sd_img_gen_params_t:sd_img_gen_params_t img_params; sd_img_gen_params_init(&img_params); img_params.prompt = prompt; img_params.negative_prompt = neg; img_params.width = W; img_params.height = H; img_params.seed = seed; img_params.batch_count = 1; img_params.sample_params.sample_steps = steps; img_params.sample_params.guidance.txt_cfg = cfg; img_params.sample_params.sample_method = EULER_SAMPLE_METHOD; img_params.sample_params.scheduler = KARRAS_SCHEDULER;
- 生成图像:
sd_image_t* images = generate_image(ctx, &img_params); - 保存并释放:
save_ppm(output, images[0].data, images[0].width, images[0].height, 3); free(images[0].data); free(images); free_sd_ctx(ctx);
v1 源码编写时使用的 generate_image 签名是:
sd_image_t* generate_image(sd_ctx_t* ctx, const sd_img_gen_params_t* params);该签名在较新的 /opt/sd 中已被废弃并替换为:
bool generate_image(sd_ctx_t* sd_ctx,
const sd_img_gen_params_t* sd_img_gen_params,
sd_image_t** images_out,
int* num_images_out);(定义在 include/stable-diffusion.h:466,实现在 src/stable-diffusion.cpp:4947。)
主要差异:
| 旧签名 | 新签名 |
|---|---|
直接返回 sd_image_t* |
返回 bool 表示成功/失败 |
| 默认单张图 | 通过 images_out / num_images_out 输出批量结果 |
调用者直接 free(images[0].data) |
必须调用 free_sd_images(images, num_images) 释放 |
| 无法区分失败与空指针 | 函数返回 false 时 images_out 为 nullptr |
这种不兼容导致 v1 CLI 直接链接 /opt/sd 新库时会编译失败(或如果按旧 ABI 链接则运行时崩溃)。此外,v1 中 rng_type = STD_DEFAULT_RNG 在 include/stable-diffusion.h:31 仅作为占位符,实际有效枚举为 CUDA_RNG / CPU_RNG 等;new_sd_ctx 内部会根据 rng_type 选择 PhiloxRNG 或 MT19937RNG(src/stable-diffusion.cpp:608)。
v1 CLI 中使用的 API 在 include/stable-diffusion.h 中的定位如下:
| v1 调用 | 当前 API 定位 |
|---|---|
sd_ctx_params_init |
include/stable-diffusion.h:451 |
new_sd_ctx |
include/stable-diffusion.h:454 / src/stable-diffusion.cpp:3337 |
sd_img_gen_params_init |
include/stable-diffusion.h:464 / src/stable-diffusion.cpp:3140 附近 |
generate_image |
include/stable-diffusion.h:466 / src/stable-diffusion.cpp:4947 |
free_sd_ctx |
include/stable-diffusion.h:455 / src/stable-diffusion.cpp:3358 |
正确迁移 v1 代码时,需要:
- 将
generate_image调用改为:sd_image_t* images = nullptr; int num_images = 0; bool ok = generate_image(ctx, &img_params, &images, &num_images); if (!ok || images == nullptr || num_images == 0) { ... }
- 使用
free_sd_images(images, num_images)替代free(images[0].data); free(images);。 - 将
STD_DEFAULT_RNG替换为CUDA_RNG(默认)或CPU_RNG。
这正是第 13 节 v2 适配层所做的事情。
| 文件 | 作用 |
|---|---|
/opt/static_comfyui/cpp/sd/src/adapters/sdcpp_adapter.h |
C++ 适配层头文件:暴露 sd::Image, sd::ModelConfig, sd::ImageGenerationParams, sd::SDPipeline |
/opt/static_comfyui/cpp/sd/src/adapters/sdcpp_adapter.cpp |
唯一 #include <stable-diffusion.h> 的源文件,封装 sd_ctx_t / generate_image |
/opt/static_comfyui/cpp/sd/examples/sdxl_txt2img.cpp |
v2 CLI 示例,功能对齐 v1 的 stable-diffusion-cli_v1.cpp,但使用新的 API 签名 |
/opt/static_comfyui/cpp/sd/CMakeLists.txt |
构建配置:编译 sdcpp_adapter 静态库 + sdxl_txt2img 可执行文件 |
- 隔离原则:只有
sdcpp_adapter.cpp接触/opt/sd的 C API;上层代码只依赖sdcpp_adapter.h中的 C++ 类型。 - 内存管理:
generate_image返回的sd_image_t*在适配层内部复制到sd::Image::data(std::vector<uint8_t>),然后立即调用free_sd_images释放原始内存,避免跨 CRT 释放问题。 - API 签名兼容:使用
/opt/sd最新的bool generate_image(..., sd_image_t**, int*)签名,不使用 v1 中已废弃的sd_image_t* generate_image(...)签名。 - 默认参数对齐 sd-cli:
rng_type = CUDA_RNG、wtype = SD_TYPE_COUNT(auto)、sample_method = euler_a、scheduler = discrete、steps = 20,确保与官方sd-cli输出一致。 - 链接顺序:参考
/opt/sd/build/examples/cli/CMakeFiles/sd-cli.dir/link.txt中的顺序,确保静态库依赖正确解析:sdxl_txt2img.o -> sdcpp_adapter.a -> libstable-diffusion.a -> webp, webpmux -> libggml.a -> dl -> libggml-cpu.a -> libggml-cuda.a -> libggml-base.a -> gomp, pthread -> libcudart.so -> libcublas.so -> libcublasLt.so -> libculibos.a -> libcuda.so (stub) -> webp, sharpyuv -> libm
cd /opt/static_comfyui/cpp/sd
# 1. 先编译 /opt/sd 后端为动态后端共享库(CUDA 后端独立为 libggml-cuda.so)
./build_sd_dl.sh
# 2. 再编译适配层 + 示例(默认 SD_BACKEND_DL=ON)
rm -rf build && mkdir build
cmake -S . -B build -DSD_BACKEND_DL=ON
cmake --build build -j$(nproc)
# 产物
# build/libsdcpp_adapter.so (很小,依赖 /opt/sd/build-dl/bin 下的共享库)
# build/sdxl_txt2img如需使用旧版静态链接模式(所有依赖打进 libsdcpp_adapter.so):
./build_sd.sh
cmake -S . -B build -DSD_BACKEND_DL=OFF
cmake --build build -j$(nproc)- 参考命令(sd-cli 官方 CLI,用于对比验证):
/opt/sd/build/bin/sd-cli -m /data/models/image/sd_xl_base_1.0.safetensors \ --clip_l /data/models/image/clip_l.safetensors \ --clip_g /data/models/image/clip_g.safetensors \ -p "solo,single woman,half body portrait of a young woman, soft natural lighting, elegant pose, studio lighting, sharp eyes, clean white background, medium close up" \ -n "blurry, low quality, ugly" \ -W 1024 -H 1024 --steps 20 -s 42 \ -o /home/quqiufeng/sdcli_1024_20.png
- v2 adapter 命令(默认 20 steps、Euler A、离散 scheduler):
输出:
./build/sdxl_txt2img -W 1024 -H 1024 -s 42
~/sdxl_txt2img.png(1024×1024,3 channels,约 1.8 MB) - 像素级对比:
- 使用 20 steps 时,
sdxl_txt2img生成的 PNG 与sd-cli生成的 PNG 像素完全一致(mean diff = 0,max diff = 0)。 - 哈希值不同仅因为 PNG 压缩参数/元数据差异,不影响图像内容。
- 使用 20 steps 时,
- 说明:
- 少于 20 steps(如 5 steps)的图像质量会明显下降,看起来"破碎/失真",这是 SDXL 正常行为,不是 bug。
- 建议 SDXL 推理至少使用 20 steps。
examples/img_hires.cpp 和迁移后的 img2.sh 演示了 sd::SDPipeline 的进阶用法:
- GGUF 模型:使用
z_image_turbo-Q5_K_M.gguf作为 standalone diffusion model,Qwen3-4B-Instruct-2507-Q4_K_M.gguf作为 LLM 文本编码器,ae.safetensors作为 VAE。 - HiRes Fix:先低分辨率采样,再 latent 放大二次去噪。
- VAE Tiling:大分辨率解码时开启,降低显存峰值。
- LoRA:通过
--lora path:weight支持多个。 - FreeU / SAG:通过最小 patch 接入 UNet 和采样循环。
直接运行示例(img_hires):
./build/img_hires \
--diffusion-model /data/models/image/z_image_turbo-Q5_K_M.gguf \
--llm /data/models/image/Qwen3-4B-Instruct-2507-Q4_K_M.gguf \
--vae /data/models/image/ae.safetensors \
-W 1024 -H 576 \
--hires --hires-width 1280 --hires-height 720 \
--hires-steps 45 --hires-strength 0.35 \
--vae-tiling --vae-tile-size 128 --vae-tile-overlap 0.5 \
--freeu --freeu-b1 1.4 --freeu-b2 1.5 \
--sag --sag-scale 1.0 \
--method euler --scheduler discrete --cfg 3.2 --steps 20 \
"a cat sitting on a bench" \
~/img_hires_output.png或使用迁移后的 img2.sh(与原版用法完全一致):
./img2.sh "solo,single woman,half body portrait of a young woman, soft natural lighting, elegant pose, studio lighting, sharp eyes, clean white background, medium close up" \
~/portrait.png 2560 1440img2.sh 所有参数都有默认值,可直接运行:
./img2.sh
# 输出: ~/YYYYMMDD_HHMMSS_xxxxxxxx.png,1280x720,20+45 steps验证结果:
img2.sh2560×1440 目标在 RTX 3080 20G 上约 11 分 26 秒(20+45 steps),输出2560×1440正常人像,无噪声/花屏。- 1280×720 快速测试(5+5 steps)约 25 秒,输出正常。
- 之前图像错误的原因是:错误地用 safetensors SDXL 模型测试,且 FreeU 实现为全 tensor 缩放;迁移后使用 img2.sh 同款 GGUF 模型,并把 FreeU 修复为 channel-half 缩放。
为支持 FreeU/SAG/DynCFG/RescaleCFG/区域条件/GLIGEN 等本项目需要、而 sd.cpp 原生没有的能力,
对 /opt/sd 做了最小修改。patch 文件作为本仓库的源文件维护:
cpp/sd/patches/sdcpp-freeu-sag-v2.patch # 1183 行,11 个文件(含新增 gligen.hpp)
cpp/sd/SD_VERSION.lock # 当前基准 commit(6dcb5bb)
⚠️ 本节只给应用/重生成 patch 的操作步骤。逐文件改了什么、为什么改、升级时怎么检查, 一律以design.md§4 / §5 为准(本文早期版本记录的bb84971基准与src/model/diffusion/model.hpp/src/model/vae/vae.hpp文件表已过期)。
在新的 /opt/sd 仓库上应用 patch,需先切到 SD_VERSION.lock 记录的 commit,再应用:
cd /opt/sd
# 确保子模块已初始化(升级时必须 --force,否则 ggml 头文件与 sd.cpp 不匹配)
git submodule update --init --recursive
# 检查 patch 是否能干净应用
git apply --check /opt/static_comfyui/cpp/sd/patches/sdcpp-freeu-sag-v2.patch
# 应用 patch
git apply /opt/static_comfyui/cpp/sd/patches/sdcpp-freeu-sag-v2.patch注意:patch 只包含源码改动,不包含
examples/server/frontend子模块的 dirty 状态标记。 应用时无需关心该子模块是否 clean。冲突时按design.md§5.3 用--reject看.rej手动 rebase。
如果在 /opt/sd 上继续修改了相关代码,并希望同步回 patch 文件,先清空 cpp/sd/patches/ 目录,再从 /opt/sd 生成:
# 1. 清空旧 patch
rm -f /opt/static_comfyui/cpp/sd/patches/*
# 2. 从 /opt/sd 当前改动生成新 patch(排除子模块 dirty 标记)
# gligen.hpp 是 untracked,需先 git add -N
cd /opt/sd
git add -N src/model/diffusion/gligen.hpp
git diff -- . ':!examples/server/frontend' > /opt/static_comfyui/cpp/sd/patches/sdcpp-freeu-sag-v2.patch
# 3. 检查生成结果 + 锁版本
wc -l /opt/static_comfyui/cpp/sd/patches/sdcpp-freeu-sag-v2.patch
echo "$(git rev-parse --short HEAD)" > /opt/static_comfyui/cpp/sd/SD_VERSION.lock本节写于 2026-07-08,其中的"尚未接入"项此后已陆续完成,当前状态以根目录
README.md的「对齐度说明」与TODO.md为准。已补齐的有:img2img / inpainting / ControlNet / IP-Adapter(sd.cpp 原生)/ HiRes Fix 参数化 / ADetailer / batch 采样 / EasyCache + CUDA graphs 加速。
仍未做(详见 TODO.md):
- 适配层仍是最小封装,未实现
sd::Tensor/sd::nn::Module/sd::ops抽象(顶层design.md中的规划) - PhotoMaker / ESRGAN 的 C API 尚未暴露给 StaticPy(
img_hires二进制侧可用) - GLIGEN:ggml 模块与 UNet 注入已进 patch,缺权重 loader / PositionNet 节点接线
- 执行引擎无 list 广播 / lazy 求值 / 子图;节点间数据类型仍是占位
报告更新时间:2026-07-07(补充 v1 API 分析) 报告更新时间:2026-07-08(补充 v2 适配层实现与端到端验证) 报告更新时间:2026-07-08(补充 FreeU/SAG patch、img_hires 示例与 img_hires.sh) 报告更新时间:2026-09-28(§13.6 patch 基准与文件表指向 design.md;§13.7 改为当前状态索引)