# vision.cpp-runtime **Repository Path**: ningpengtao-apps/vision.cpp-runtime ## Basic Information - **Project Name**: vision.cpp-runtime - **Description**: vision.cpp 的 Flutter C ABI 运行时:Dart FFI 绑定与各平台预编译库 - **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 # vision.cpp-runtime `vision.cpp` 稳定 C ABI 的 Flutter FFI 插件,把 `packages/vision.cpp` 提供的 GGUF 会话、张量推理与错误信息暴露给 Dart。插件本身不执行推理,只负责: - 定位随 App 打包的 `vision.dll` / `libvision.dylib`; - 把 Dart 张量转换成 `vision_tensor_input` / `vision_tensor_output`; - 把 C 侧中文错误消息与状态码转成 `VisionCppException`; - 把 Flutter 资产中的 GGUF 复制到 `/vision_models/` 并按 sha256(可选)复用。 平台支持: | 平台 | 运行时 | 状态 | | --- | --- | --- | | Windows x64 | `vision.dll`(CPU,静态链接 ggml) | 已随包 | | macOS arm64 / x64 | `libvision.dylib`(Metal 优先,CPU 回退) | 代码就绪,需在 macOS 构建 | | Android / iOS / Linux | 无 | `VisionCppRuntime.isAvailable == false`,上层回退 ONNX | ## 目录 ``` packages/vision.cpp-runtime/ lib/vision_cpp_runtime.dart # 平台查询、动态库定位、资产落盘 lib/src/vision_cpp_bindings.dart # C ABI 绑定与错误码 lib/src/vision_cpp_session.dart # 会话与张量封装 windows/CMakeLists.txt windows/vision_cpp_runtime_plugin.* # MethodChannel: vision_cpp_runtime windows/include/vision_cpp_runtime/ # 插件 C API 头 windows/Assets/ # vision.dll + MSVC 运行时 macos/vision_cpp_runtime.podspec macos/Classes/VisionCppRuntimePlugin.swift test/ ``` > macOS podspec 文件名必须是 `.podspec`,Flutter 工具按该规则查找; > 因此实际文件名是 `vision_cpp_runtime.podspec`,而不是目录名。 ## Windows 资产 `windows/Assets/` 已包含: | 文件 | 来源 | | --- | --- | | `vision.dll` | `packages/vision.cpp/build/vision.cpp/Release/vision.dll` | | `msvcp140.dll` / `vcruntime140.dll` / `vcruntime140_1.dll` / `vcomp140.dll` | MSVC 运行时(`vision.dll` 的动态依赖) | ggml 已静态链接进 `vision.dll`,没有额外的 ggml DLL。 重新构建并刷新资产: ```powershell cmake -S packages/vision.cpp -B packages/vision.cpp/build -DVISION_BUILD_TESTS=ON cmake --build packages/vision.cpp/build --config Release --parallel 8 Copy-Item packages/vision.cpp/build/vision.cpp/Release/vision.dll ` packages/vision.cpp-runtime/windows/Assets/vision.dll -Force ``` 插件构建时会把 `windows/Assets/*.dll` 复制到可执行文件旁;缺少任一文件会直接 `FATAL_ERROR`,避免发布缺运行时的包。 ## macOS 资产(未完成) 当前仓库只提交了 Windows 产物,macOS `libvision.dylib` 需要在本机构建: ```bash cmake -S packages/vision.cpp -B packages/vision.cpp/build -DVISION_BUILD_TESTS=ON cmake --build packages/vision.cpp/build --config Release -j8 mkdir -p packages/vision.cpp-runtime/macos/Assets cp packages/vision.cpp/build/vision.cpp/libvision.dylib \ packages/vision.cpp-runtime/macos/Assets/libvision.dylib ``` 然后把插件加入 App 的 Podfile 流程并执行 `pod install`。podspec 只在 `macos/Assets/libvision.dylib` 存在时声明资源,未构建时不会伪造 dylib,也不会 让 `pod install` 因缺失文件失败;Dart 侧调用会得到中文错误 “vision.cpp 运行时未随 App 打包”。 ## Dart 用法 ```dart import 'package:vision_cpp_runtime/vision_cpp_runtime.dart'; Future runOnce(String assetPath) async { if (!VisionCppRuntime.isAvailable) { // Android / iOS / Linux:回退 ONNX。 return; } final model = await VisionCppRuntime.loadAsset(assetPath); final session = await VisionCppRuntime.openSession( model.path, nThreads: 4, ); try { final input = Float32List.fromList([/* ... */]); final outputs = session.run( [ VisionTensor.f32( name: 'input', shape: [224, 224, 3, 1], // ggml 顺序:最内层维度在前 data: input, ), ], [VisionOutputBuffer.f32('output', Float32List(1000))], ); final logits = outputs.single.data as Float32List; final shape = outputs.single.shape; // 按模型文档解释 logits / shape。 } finally { session.free(); } } ``` 要点: - 输入只支持 `Float32List` / `Int32List` / `Int64List`;元素个数必须与 `shape` 相乘一致。 - 输出缓冲区由调用方预分配(`Float32List` / `Int32List` / `Int64List`,或 `VisionOutputBuffer.bytes` 的 `Uint8List` + 显式 dtype)。 - 输出 `shape` 由 C 侧回填,`VisionOutput.data` 是按实际元素个数裁剪的视图。 - 所有失败抛出 `VisionCppException`,`message` 为中文,`status` 为 C 状态码; `visionStatusMessage(status)` 可得到状态码的中文名称。 ## 资产落盘 `VisionCppRuntime.loadAsset(assetPath)`: 1. 用 `rootBundle` 读取资产字节; 2. 复制到 `/vision_models/<文件名>`; 3. 目标已存在时,传入 `sha256` 按内容校验,未传时按字节长度复用; 4. 校验失败覆盖旧文件(先写 `.tmp` 再改名)。 测试可通过 `directory` / `bundle` 参数注入临时目录与内存资产。 ## 测试 ```powershell cd packages/vision.cpp-runtime flutter pub get flutter test ``` 测试覆盖: - Android / iOS / Linux 与 Windows ARM 报告不可用; - 缺失 DLL 的中文错误; - 资产首次复制、同长度复用、sha256 不一致覆盖; - 若 `windows/Assets/vision.dll` 可加载:生成最小 echo GGUF,验证 F32 / I32 / I64 推理、重复释放与缺失 GGUF 中文错误;否则打印中文原因跳过。