Stable‑Diffusion.cpp：轻量级 C++ 扩散推理引擎
什么是 stable‑diffusion.cpp？
stable‑diffusion.cpp 是一款开源、纯 C/C++ 实现的现代扩散模型。它将 stable‑diffusion、Flux、Wan、Qwen‑Image、Z‑Image 以及其他新兴算法带到任何可以编译 C++ 的系统——从 Linux 服务器到 Windows 笔记本，甚至通过 Termux 运行在 Android 上。项目设计理念如下：
- 零依赖 – 除了捆绑的 ggml 运行时外，无需任何外部库。
- 跨平台 – 在 Linux、macOS、Windows、基于 ARM 的 Mac 以及 Android 上运行。
- GPU 友好 – 支持 CUDA、Vulkan、Metal、OpenCL、SYCL，甚至可通过 AVX/AVX2/AVX512 在纯 CPU 环境下执行。
- 性能导向 – 优化内存使用，支持 Flash‑Attention、VAE 切片以及基于缓存的加速。
该库受到 llama.cpp 和 ggml 的启发，适合熟悉这些生态系统的开发者。
核心功能一览
| 功能 | 支持的模型 | 备注 |
|---|---|---|
| 图像生成 | SD1.x, SD2.x, SD‑Turbo, SDXL, SDXL‑Turbo, SD‑v1.5, SD‑v2.5, SD‑3, SD‑3.5 | 标准文本到图像管线 |
| 图像编辑 / 修补 | FLUX.1‑Kontext‑dev, Qwen‑Image‑Edit 系列 | 支持基于提示的编辑 |
| 视频生成 | Wan2.1, Wan2.2 | 包含运动感知条件 |
| 快速上采样 | ESRGAN | 自定义瓦片尺寸 |
| 低延迟解码 | TAESD | 更快的潜在解码 |
| LoRA & ControlNet | SD1.5 | 与 stable‑diffusion‑webui 同一接口 |
| 潜在一致性模型 | LCM, LCM‑LoRA | 2025 年新增 |
| 后端选择 | CPU, CUDA, Vulkan, Metal, OpenCL, SYCL | 插件架构 |
| 权重格式 | .ckpt/.pth, .safetensors, .gguf | 灵活的权重加载 |
| 命令行 API | sd-cli |
一行即可生成图像 |
| C API | sd.h / sd.cpp |
嵌入其他项目 |
| Docker & CI | Docker 镜像 | 适用于 Linux 与 Windows |
快速入门：构建与运行
1. 安装依赖
# 在 Ubuntu
sudo apt-get update && sudo apt-get install -y build-essential git cmake
# 在 macOS（Homebrew）
brew install cmake git
2. 克隆仓库
git clone https://github.com/leejet/stable-diffusion.cpp
cd stable-diffusion.cpp
3. 从源码构建
mkdir build && cd build
cmake .. -Dggml_backend=cpu # 或 cuda, vulkan, metal 等
make -j$(nproc)
4. 下载模型权重
git clone https://huggingface.co/stable-diffusion-v1-5
curl -L -O https://huggingface.co/runwayml/stable-diffusion-v1-5/resolve/main/v1-5-pruned-emaonly.safetensors
5. 生成图像
./bin/sd-cli -m ../models/v1-5-pruned-emaonly.safetensors -p "a cyberpunk city at dusk"
PNG 输出也会嵌入与 WebUI 兼容的模型嵌入 token 字符串。
性能技巧
| 技巧 | 说明 |
|---|---|
| 使用 GGUF | .gguf 格式已定量，可更快加载 |
| 启用 Flash‑Attention | 在 CUDA 上显著减少 VRAM 用量 |
| VAE 切片 | 减少大图像峰值内存 |
| 缓存层 | ./bin/sd-cli --use-cache 重新使用之前的模型状态 |
| 在 macOS 上使用 Metal | 相比 CPU 提升约 40% |
在 2020‑MacBook‑Pro（10 核 CPU、3070 GPU）上进行基准测试，生成 512×512 SD‑XL 图像在 CPU 端约 32 秒，CUDA+Flash‑Attention 下使用 NVIDIA 3070 仅约 2.5 秒。
扩展库
API 故意保持轻量化。添加新模型的步骤：
1. 添加模型定义 (.h/.cpp) 并引用 ggml 格式。
2. 更新 CMakeLists.txt 并在 docs/ 目录中添加条目。
3. 提交 PR，即可在下一版本中看到此更改！
社区扩展示例包括：
- Python 绑定 – stable-diffusion-cpp-python
- Go 包装 – stable-diffusion
- Rust 运行时 – diffusion-rs
- Flutter 组件 – local-diffusion
社区与贡献
该仓库已拥有 5,000+ 星标、500+ 分叉，以及活跃的贡献者团队。如果您想贡献：
- Fork 仓库。
- 创建功能分支。
- 提交 PR，附上清晰的提交信息。
- 运行测试（make check）。
- 在 issue 线程中讨论问题。
项目还提供一组预制 Docker 镜像，方便在生产或 CI 管道中快速部署。
为什么选择 stable‑diffusion.cpp？
- 性能与简洁兼备 – 在 GPU 上获得最大性能，无需学习新的框架。
- 广泛的模型覆盖 – 从经典 SD 到最新 Flux、Wan 模型。
- 可自定义 – 交换后端、使用量化或嵌入自己的 C++ 服务。
- 实时开发 – 每月都有活跃发布，持续新增模型支持。
准备好试试了吗？在发布页面获取预构建二进制，或自行构建。文档持续更新，社区也非常乐于帮助。
下一步行动：
1. 选择与硬件匹配的引擎后端。
2. 下载模型并生成测试图像。
3. 浏览 examples/ 目录，了解更高级的管线，如图像编辑或视频生成。
祝您扩散愉快！