# stable-diffusion.cpp-runtime **Repository Path**: ningpengtao-apps/stable-diffusion.cpp-runtime ## Basic Information - **Project Name**: stable-diffusion.cpp-runtime - **Description**: stable-diffusion.cpp 的 Flutter C ABI 运行时:Dart FFI 绑定与 Windows / macOS 预编译库 - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-11-18 - **Last Updated**: 2026-11-18 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # diffusion_cpp_runtime `stable-diffusion.cpp` 的 Flutter FFI 运行时模块。动态库随 App 打包,Dart 侧通过 C ABI 直接加载模型并生成图片,不依赖远端 FAL。 ## 当前状态 | 平台 | 产物 | 状态 | | --- | --- | --- | | Windows x64 | `windows/Assets/stable-diffusion.dll` | 已构建并随包(CPU) | | macOS | `macos/Assets/libstable-diffusion.dylib` | **待构建**,需在 macOS 上生成后放入 | `DiffusionCppRuntime.isAvailable` 在 Android / iOS / Linux 返回 `false`; macOS 上若资源缺失,插件会返回中文错误,不会伪造动态库。 ## Vendored 上游 - 源码:`packages/stable-diffusion.cpp`(见其 `UPSTREAM.md`) - Commit:`5dcfa79801213f23e27b3e83617350ebb8ea93aa` - C ABI:`include/stable-diffusion.h` ## 构建 Windows 共享库(MSVC) ```powershell cd packages/stable-diffusion.cpp cmake -S . -B build-windows -G "Visual Studio 17 2022" -A x64 ` -DSD_BUILD_SHARED_LIBS=ON ` -DSD_BUILD_SHARED_GGML_LIB=OFF ` -DSD_BUILD_EXAMPLES=OFF ` -DSD_WEBP=OFF -DSD_WEBM=OFF cmake --build build-windows --config Release ``` 产物:`build-windows/bin/Release/stable-diffusion.dll`。 复制到本模块并补齐 MSVC 运行时(`dumpbin /dependents` 结果): ```powershell Copy-Item build-windows/bin/Release/stable-diffusion.dll ` ../stable-diffusion.cpp-runtime/windows/Assets/ # MSVCP140.dll、MSVCP140_CODECVT_IDS.dll、VCOMP140.DLL、VCRUNTIME140*.dll ``` 本次验证的依赖:`KERNEL32.dll`、`ADVAPI32.dll`、`MSVCP140.dll`、 `MSVCP140_CODECVT_IDS.dll`、`VCOMP140.DLL`、`VCRUNTIME140.dll`、 `VCRUNTIME140_1.dll` 与 `api-ms-win-crt-*`(系统 UCRT)。`windows/Assets` 已包含前几项,`api-ms-win-crt-*` 由 Windows 10+ 提供。 ## Dart 使用 ```dart import 'package:diffusion_cpp_runtime/diffusion_cpp_runtime.dart'; if (DiffusionCppRuntime.isAvailable) { final path = await DiffusionCppRuntime.libraryPath(); final library = DiffusionCppLibrary.open(path); // 模型加载与推理较慢,实际业务应放到后台 Isolate。 final session = DiffusionCppSession.load( library, const DiffusionCppLoadOptions(modelPath: r'D:\models\sd15.safetensors'), ); try { final png = session.generatePng( const DiffusionCppGenerateOptions( prompt: 'a lovely cat', width: 256, height: 256, ), ); // png 为 PNG 字节流;也可用 session.generate(...) 拿原始 RGB/RGBA 像素。 } finally { session.dispose(); } } ``` 取消:`session.cancel()` 需要从另一个 Isolate / 线程发起(生成本身是同步调用)。 `cancel(mode: 1)` 会在完成当前图片后停止。 ## 绑定的 C ABI | 用途 | 符号 | | --- | --- | | 初始化加载参数 | `sd_ctx_params_init` | | 创建 / 释放上下文 | `new_sd_ctx` / `free_sd_ctx` | | 初始化生成参数 | `sd_img_gen_params_init` | | 生成图片 | `generate_image` | | 释放生成结果 | `free_sd_image_generation_result` | | 取消生成 | `sd_cancel_generation` | | 能力查询 | `sd_ctx_supports_image_generation`、`sd_get_model_version_name` | | 版本信息 | `sd_version`、`sd_commit`、`sd_get_system_info` | 结构体字段与 `include/stable-diffusion.h` 逐一对应;C `bool` 用 `@Uint8()` 表示。 ## 错误信息 - 动态库缺失 / 缺少符号:`DiffusionCppException(stage: runtime)`; - 模型文件不存在、`new_sd_ctx` 返回空、模型不支持图片生成: `DiffusionCppException(stage: load)`; - 生成返回空结果 / 像素为空 / 参数非法:`DiffusionCppException(stage: generate)`。 上游没有 `last_error` 接口,错误详情主要通过日志输出;本模块不会伪造日志, 异常消息会带上模型路径、阶段与常见原因提示。 ## 冒烟测试 仓库内没有 Stable Diffusion 权重(已检查 `*.safetensors` / `*.gguf` / `*.ckpt`), 因此**未执行 256×256 生成冒烟**,也未下载 GB 级权重。补测命令: ```powershell cd packages/stable-diffusion.cpp-runtime $env:STABLE_DIFFUSION_DLL = (Resolve-Path ` "..\stable-diffusion.cpp\build-windows\bin\Release\stable-diffusion.dll").Path # VCOMP140 等运行时依赖需要能被 Windows 加载器找到 $env:PATH = (Resolve-Path "windows\Assets").Path + ";" + $env:PATH flutter test ``` `test/bindings_smoke_test.dart` 会在设置 `STABLE_DIFFUSION_DLL` 时打开动态库并 校验 ABI(不加载模型);有本地权重时可再跑: ```dart final session = DiffusionCppSession.load(...); session.generatePng(const DiffusionCppGenerateOptions( prompt: 'a lovely cat', width: 256, height: 256, steps: 8)); // 预期:输出 256×256 PNG,单张文件数 MB 级,日志中出现采样步进度。 ``` ## 验证记录(2026-11-15,Windows x64) - `flutter pub get`:成功。 - `flutter analyze`:No issues found。 - `flutter test`(不设置 `STABLE_DIFFUSION_DLL`):2 通过,1 跳过。 - `flutter test`(设置 `STABLE_DIFFUSION_DLL`):3 通过;打开真实 DLL 并校验 `sd_ctx_params_init` / `sd_img_gen_params_init` 的默认值,证明 Dart 侧结构体 布局与上游 C 结构体一致。 - Windows 插件源码(`diffusion_cpp_runtime_plugin.cpp`、 `diffusion_cpp_runtime_plugin_c_api.cpp`):用 MSVC 19.44 以 OBJECT 库编译通过 (未链接 Flutter 运行时)。 ## 已知限制 - 仅 CPU 构建;未启用 CUDA / Vulkan / Metal / WebP / WebM。 - macOS 产物尚未构建(本机为 Windows,不能生成 dylib)。 - 模块不接入 App,不修改根 `pubspec.yaml`。 - 上游 C ABI 随 commit 变化;升级 `packages/stable-diffusion.cpp` 时需同步更新 `lib/src/diffusion_cpp_bindings.dart`。