做 AI 应用开发,很多人习惯了「训练用 Python、部署再想办法塞进 C++ 服务」的组合。但如果要在 C++ 工程里直接跑扩散模型,直接用 Python 生态意味着额外维护 Python 环境、模型依赖和独立服务进程,甚至要处理进程间通信。有没有方式直接在 C/C++ 工程里运行扩散模型?有——stable-diffusion.cpp。
它到底是什么
stable-diffusion.cpp 是一个基于 GGML 的 C/C++ 扩散模型推理框架,思路跟 llama.cpp 一脉相承——llama.cpp 解决大语言模型的本地推理,它把同样的思路用到了图像生成。两者都用 C/C++ 实现、靠 GGML 提供底层计算能力。目标不是提供新模型,而是提供一套「加载模型 → 执行推理 → 生成图像」的底层实现,让图像生成能力直接集成进 C/C++ 应用,不必额外维护一套 Python 推理服务。
几点特点:C/C++ 实现方便接入现有工程;基于 GGML 支持多种硬件后端;不局限于最初的 Stable Diffusion;支持 Safetensors、GGUF、PyTorch checkpoint 等多种权重格式。需要澄清的是:所谓「纯 C/C++」指推理实现用 C/C++,构建仍需编译器、CMake,启用 CUDA 仍需 CUDA Toolkit——它的价值在于把推理运行时放进 C/C++ 工程。
支持的模型早已不止 Stable Diffusion
按官方 README(截至 2026-11-08),模型支持分三类:
- 图像生成:Stable Diffusion 1.x/2.x、SDXL/SDXL-Turbo、SD3/SD3.5、FLUX.1/FLUX.2、FLUX.3 Image Klein、Qwen Image/2.1、Z-Image、MOSS-Image。
- 图像编辑:FLUX.1-Kontext、Qwen Image Edit 系列、LongCat Image Edit、Boogu Image Edit——根据输入图和文本指令修改已有图像。
- 视频生成:Wan2.1/2.2、LTX-2.3/2.5、HunyuanVideo 1.5、LingBot-Video、MiniMax-H3。
但要特别注意:声明支持某模型 ≠ 任意权重都能直接加载。不同模型有不同的权重格式、文本编码器、VAE、Tokenizer 和配置要求,部分新模型可能还在刚加入阶段。实际使用时要对照 README 确认模型版本、权重文件和配套组件是否匹配。
底层计算:多种硬件后端
通过 GGML 后端支持不同计算设备:
| 后端 | 主要用途 |
|---|---|
| CPU | 使用处理器执行推理 |
| CUDA | 使用 NVIDIA GPU |
| Vulkan | 通过 Vulkan 使用兼容 GPU |
| Metal | 面向 Apple 平台 |
| OpenCL | 面向支持 OpenCL 的设备 |
| SYCL | 面向支持 SYCL 的计算平台 |
CMake 里还能看到 HIPBLAS、MUSA 等构建选项,具体可用性需结合工具链、GGML 后端和代码版本确认。统一的后端接口能减少上层业务代码与具体硬件的耦合——但不同后端的算子覆盖、性能、稳定性并不相同,能编译不等于所有模型都获得相同效果。
项目把「计算后端」和「参数存储后端」拆成两个参数:
1 | --backend cuda0 --params-backend cpu # CUDA 计算,参数放 CPU 内存 |
--backend 决定模型计算实际在哪个设备执行;--params-backend 决定模型参数主要存放哪里。上面的配置就是「CUDA 计算,但参数主要放 CPU 内存,需要时再传到设备」,用 disk 则进一步降低显存占用(代价是磁盘读取开销)。
内存管理:扩散模型最吃资源
SDXL、FLUX 这类模型,参数、文本编码器、扩散计算、VAE 解码都很占显存。项目提供了几种手段:
- GGUF 量化:降低参数存储开销,让模型更容易部署到资源有限设备。但量化不是越低越好,不同模型/量化方式对质量和速度的影响不同。
- CPU-GPU 混合部署:即上面的 backend/params-backend 分离,给显存有限的设备更多调节空间。
- VAE Tiling:把高分辨率图像的解码拆成小块,降低峰值显存。
- Flash Attention:优化部分注意力计算,改善内存使用和计算效率。
这些功能不等于所有模型都能在低配设备上流畅跑,但至少说明项目考虑的不只是「能不能跑」,还有「怎么控制推理中的资源占用」。
实际怎么编译和运行
项目提供命令行程序 sd-cli。Linux 环境示例(注意 --recursive 是因为依赖 GGML 等子模块):
1 | git clone --recursive https://github.com/leejet/stable-diffusion.cpp.git |
编译 CPU 版本
1 | cmake -S . -B build -DCMAKE_BUILD_TYPE=Release |
编译 CUDA 版本
1 | cmake -S . -B build-cuda -DCMAKE_BUILD_TYPE=Release -DSD_CUDA=ON |
准备模型并生成图像
1 | ./build/bin/sd-cli -m ./models/v1-5-pruned-emaonly.safetensors -p "a lovely cat" |
-m 指定模型、-p 正向提示词、--backend 推理后端。可执行文件通常在构建目录的 bin 下。SD 不同版本的模型可能需要额外的文本编码器、VAE 等组件,上例是 README 的基础示例。项目明确说明 API 和 CLI 参数可能频繁变化,正式使用前看最新 README 和构建文档。
二次开发方向
- 封装成 C++ 推理 SDK:官方提供了命令行和 C/C++ 接口,实际项目通常希望把底层推理封装成统一接口(模型加载/卸载、参数配置、生成接口、异常与资源释放、多模型管理),业务代码就不用关心底层是 SD、FLUX 还是别的模型。注意这是示意,真正集成要基于项目当前提供的 C API 和上下文生命周期。
- HTTP 推理服务:在推理能力上加 HTTP Server(如
POST /api/image/generate),支持文生图/图生图/编辑、任务 ID 与异步队列、状态查询、任务取消与超时。关键工程细节:图像生成不是快请求,直接同步执行会阻塞请求线程,应把 HTTP 接口和推理任务解耦,用队列调度 GPU 资源。还要考虑推理上下文能否并发、GPU 调度、队列限流、任务取消时释放资源——不能给推理函数加个多线程调用就认为有并发能力。面向外部还要鉴权、限流、内容安全、日志审计。 - 模型管理与动态切换:多模型注册、版本管理、按任务选模型、预加载/按需加载、切换时释放资源。多模型同时驻留会带较大内存/显存压力,可能要单模型驻留、按需切换或模型池策略。
- 性能与资源调度优化:特定 GPU 算子优化、CPU-GPU 数据传输、参数存储策略、VAE 解码优化、按显存动态调参、按分辨率/模型调优。部署到 Jetson 等边缘设备还可研究量化、显存控制和功耗管理。
- 与现有视觉算法组合:把目标检测、图像检索和图像生成组合(检测→规则判断→选生成模型→生成/编辑→输出)。如工业视觉生成缺陷示意图、智能零售生成场景展示图、内容制作自动出图、数据增强补训练图像。但生成图像不能直接当真实检测结果,尤其工业视觉还需人工审核或规则校验。
对 C++ 和边缘 AI 开发的意义
- 让现有 C++ 应用拥有图像生成能力:原本只提供检测/分类/检索的 C++ 服务,现在可以在原工程里加图像生成模块,少一层独立 Python 服务依赖。是否直接集成还是封装成独立进程,要看服务架构、并发量和资源隔离要求。
- 为边缘设备提供另一种部署选择:Jetson 等平台通常要同时考虑内存、显存、功耗、启动时间和软件依赖,通过 CUDA 等后端有机会把图像生成放到本地设备。但「支持 CUDA」不等于「已适配 Jetson」,要检查 CUDA、编译环境、模型支持、实际内存/显存占用。
- 跨平台推理工程参考:它如何用 GGML 统一不同硬件的计算接口,对维护多硬件平台的 C++ 推理项目有参考价值——上层业务减少对具体硬件的依赖,底层用不同后端做适配。换后端不能解决所有兼容性问题,但至少能减少重复开发。
许可证和实际使用注意
stable-diffusion.cpp 本身采用 MIT License,允许使用、修改、再分发,但分发时要保留版权声明和许可证文本。项目许可证和模型许可证是两回事:即使框架是 MIT,也不代表它运行的所有模型都能不受限制商用。不同版本的 SD、FLUX、Qwen Image 各有自己的模型许可协议,要单独确认是否允许商用、是否对用户规模/收入/场景有限制、是否要求保留声明、是否限制生成内容用途、是否允许权重再分发。接入实际业务还要考虑输入图和生成内容的版权、隐私与内容安全。
性能要实测
CPU/CUDA/Vulkan 后端、量化、VAE Tiling、Flash Attention 存在,不等于所有设备都能拿到理想性能。本文介绍能力和工程扩展方向,未在统一硬件/模型/参数下做性能对比,因此不提供未经验证的生成耗时或显存数据。准备在自己设备上部署时,建议至少记录:
| 测试项目 | 建议记录内容 |
|---|---|
| 模型 | 模型名称、权重格式、量化方式 |
| 输入参数 | 图像分辨率、采样步数、Batch Size |
| 硬件后端 | CPU、CUDA、Vulkan 等 |
| 内存占用 | 系统 RAM 峰值 |
| 显存占用 | GPU VRAM 峰值 |
| 推理耗时 | 模型加载时间、单张生成时间 |
| 输出质量 | 是否存在明显伪影、细节损失等 |
| 稳定性 | 连续运行、并发请求和异常恢复情况 |
尤其边缘设备,别只看单张能不能生成,还要关注连续运行时的内存变化、温度、功耗和速度是否稳定。把这些数据测出来,才能判断它是否适合自己的业务。
最后聊几句
过去几年 llama.cpp 让不少人看到了在本地用 C/C++ 跑大语言模型的可能。现在 stable-diffusion.cpp 把同样的思路带到了扩散模型领域:支持的模型已从传统 SD 扩展到 FLUX、Qwen Image、Z-Image 和部分视频模型,底层提供了多种计算后端和内存优化。更重要的是,它不只是一个能跑模型的命令行工具——C++ 开发者可以围绕它继续做 SDK 封装、HTTP 服务、模型管理、硬件适配和业务集成,把图像生成真正纳入现有工程体系。当然它不能替代 Python 图像生成生态,复杂的工作流、训练和实验 Python 仍有很大优势。但如果你的目标是把图像生成集成进现有 C/C++ 应用,或在不同硬件上探索本地扩散推理,这个项目值得研究。对 C++ 开发者来说,AI 应用的能力边界,可能又要往外扩一圈了。
参考链接
- 项目:github.com/leejet/stable-diffusion.cpp
- 原文整理自 GitHub 仓库截至 2026-11-08 的 README、构建文档和相关说明