# clip.cpp-runtime **Repository Path**: ningpengtao-apps/clip.cpp-runtime ## Basic Information - **Project Name**: clip.cpp-runtime - **Description**: clip.cpp 的 Flutter C ABI 运行时:Dart FFI 绑定与 Android / 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 # clip.cpp-runtime 把 [clip.cpp](../clip.cpp)(已 vendor 并扩展了 Chinese-CLIP 支持)的 C ABI 以 Flutter FFI 插件形式提供给 Dart。 - 动态库随 App 打包,运行时不下载、不导入外部库; - Dart 侧只通过 `clip.h` 暴露的函数调用,不复制、不修改 clip.cpp 源码; - 当前随包平台:**Windows x64**(已就位)、**macOS**(需本地构建,见下文)。 ## 目录结构 ``` packages/clip.cpp-runtime/ ├── lib/ │ ├── clip_cpp_runtime.dart # ClipCppRuntime:定位动态库 + 资产复制 │ └── src/ │ ├── clip_cpp_bindings.dart # C ABI 的 Dart FFI 绑定(ClipCppLibrary) │ └── clip_cpp_session.dart # 高层会话(ClipCppSession) ├── windows/ │ ├── CMakeLists.txt # 声明随包 DLL(clip.dll / ggml.dll) │ ├── clip_cpp_runtime_plugin.* # MethodChannel: clip_cpp_runtime │ ├── include/clip_cpp_runtime/… # 插件 C API 头 │ └── Assets/ # clip.dll、ggml.dll(Windows 构建产物) ├── macos/ │ ├── clip_cpp_runtime.podspec │ └── Classes/ClipCppRuntimePlugin.swift └── test/clip_cpp_runtime_test.dart ``` > podspec 文件名使用 `clip_cpp_runtime.podspec`(与 pubspec 包名一致), > CocoaPods 的 `:path` 依赖按包名查找 podspec,因此不能使用带点的 > `clip.cpp-runtime.podspec`。 ## 平台能力 | 平台 | 是否随包 | 说明 | | --- | --- | --- | | Windows x64 | 是 | `windows/Assets/clip.dll` + `ggml.dll` | | macOS | 需本地构建 | 放入 `macos/Assets/libclip.dylib`、`libggml.dylib` | | Android / iOS / Linux | 否 | `ClipCppRuntime.isAvailable == false` | `ClipCppRuntime.isAvailable` 只判断宿主平台(`macos` / `windows`);资产是否 真正随包由 `ClipCppRuntime.libraryPaths()` 在运行时报告,缺失时抛出中文 `ClipCppException`。 ## Windows 资产 `windows/Assets/` 下的两个 DLL 来自 vendored 的 clip.cpp 构建产物: ```powershell # 1) 构建(在仓库根目录) cmake -S packages/clip.cpp -B packages/clip.cpp/build -DBUILD_SHARED_LIBS=ON ` -DCLIP_NATIVE=OFF -DCLIP_BUILD_EXAMPLES=OFF -DCLIP_BUILD_TESTS=OFF cmake --build packages/clip.cpp/build --config Release # 2) 复制随包资产 New-Item -ItemType Directory -Force packages/clip.cpp-runtime/windows/Assets | Out-Null Copy-Item packages/clip.cpp/build/bin/Release/clip.dll packages/clip.cpp-runtime/windows/Assets/ -Force Copy-Item packages/clip.cpp/build/bin/Release/ggml.dll packages/clip.cpp-runtime/windows/Assets/ -Force ``` - `clip.dll` 依赖同目录的 `ggml.dll`;插件的 CMake 会把两者复制到可执行文件旁, Dart 侧也会先用完整路径预加载 `ggml.dll` 再加载 `clip.dll`。 - 两者使用 MSVC 动态运行库(`/MD`)。App 已在别处随包 VC++ 运行库时无需重复; 独立测试时请确认系统已安装 Microsoft Visual C++ Redistributable。 ## macOS 构建(本仓库未提交 dylib) macOS 没有本机构建,仓库内**不伪造** `dylib`。在 macOS 上执行: ```bash cmake -S packages/clip.cpp -B packages/clip.cpp/build \ -DBUILD_SHARED_LIBS=ON -DCLIP_NATIVE=ON \ -DCLIP_BUILD_EXAMPLES=OFF -DCLIP_BUILD_TESTS=OFF \ -DCMAKE_BUILD_TYPE=Release cmake --build packages/clip.cpp/build --config Release mkdir -p packages/clip.cpp-runtime/macos/Assets cp packages/clip.cpp/build/libclip.dylib packages/clip.cpp-runtime/macos/Assets/ cp packages/clip.cpp/build/libggml.dylib packages/clip.cpp-runtime/macos/Assets/ # 若产物在 build/bin 或 build/Release 下,请改成实际路径。 cd macos && pod install # 或直接 flutter run -d macos ``` `macos/Assets/*.dylib` 由 podspec 以通配符声明:未放置资产时 `pod install` 不会失败,但 `ClipCppRuntime.libraryPaths()` 会抛出「运行时未随 App 打包」。 ## 使用 ```dart import 'dart:typed_data'; import 'package:clip_cpp_runtime/clip_cpp_runtime.dart'; if (!ClipCppRuntime.isAvailable) { // Android / iOS / Linux:请改用其它嵌入后端。 } // 1) 直接从文件路径加载 GGUF final session = await ClipCppRuntime.openSession( modelPath: r'C:\models\chinese-clip-vit-base-patch16-f16.gguf', ); try { final text = session.encodeText('一只猫', normalize: false); // 未归一化 final image = session.encodeImage( rgb: rgbPixels, // Uint8List,长度 width*height*3,RGB 顺序 width: width, height: height, ); print('${text.length} / ${image.length}'); } finally { session.dispose(); } // 2) 随包资产:复制到 /clip_models/ 后复用 final assetSession = await ClipCppRuntime.loadFromAsset( assetKey: 'assets/models/clip/chinese-clip-f16.gguf', fileName: 'chinese-clip-f16.gguf', ); assetSession.dispose(); ``` 底层 API 也可直接用: ```dart final library = await ClipCppRuntime.openLibrary(); final tokens = library.tokenize(context, '一只猫'); final raw = library.encodeTextTokensRaw(context, tokens, threads: 4); final nhwc = library.preprocessImage(context, rgb: rgb, width: w, height: h); final imageVector = library.encodeImageRaw( context, nhwc: nhwc, width: library.visionImageSize(context), height: library.visionImageSize(context), ); ``` ### 图像布局 `clip_image_preprocess` 输出的是 **NHWC** 浮点图像(`RGBRGB...`,长度 `3 × image_size × image_size`),不是 NCHW。若调用方已有 NCHW 张量,需要 自行转换为 NHWC 再交给 `encodePreprocessedImage`。 ### 归一化 - `encodeText(..., normalize: false)` / `encodeImage(..., normalize: false)` 对应 `clip_text_encode_raw` / `clip_image_encode_raw`,返回未归一化向量; - `normalize: true` 时改调 `clip_text_encode` / `clip_image_encode`,由 clip.cpp 做 L2 归一化; - 无论哪种模式,文本塔与图像塔的向量维度都取自模型 hparams (`textDimension` / `imageDimension`)。 ## 测试 ```powershell cd packages/clip.cpp-runtime flutter pub get flutter test ``` 单测覆盖:不可用平台、模型路径缺失 / 文件过短 / 非 GGUF、会话重复释放、 随包 DLL 可加载(解析 C ABI 符号)。真实推理 smoke 需要: ```powershell $env:CLIP_CPP_TEST_MODEL = 'C:\models\chinese-clip-f16.gguf' flutter test ``` 未设置该变量时会打印中文原因并跳过(不会伪造推理结果)。 ## 已知限制(来自 clip.cpp 上游) 1. **分词的 token 数组无法释放**:`clip_tokenize` 用 `new[]` 分配 `clip_tokens.data`,但 C ABI 没有提供释放函数,Dart 也无法安全地 `delete[]`。每次 `encodeText` 会泄漏与 token 数成正比的少量内存 (每条约几十到几百字节)。批量编码时请尽量合并/复用调用。 2. **GGUF 解析失败会崩溃**:`clip_model_load` 在文件不是合法 GGUF 时不会返回 NULL,而是继续解引用空指针。Dart 侧因此先校验路径、文件长度与 `GGUF` 魔数;但仍无法完全防御损坏文件,请只加载可信模型。 3. **只支持 ASCII 路径**:clip.cpp 在 Windows 上用 ANSI 版 `fopen` / `std::ifstream`,非 ASCII 路径会加载失败。`ClipCppLibrary.loadModel` 会 提前抛出中文错误,请把模型放在全 ASCII 路径下。 4. `clip.cpp` 的 `clip_image_preprocess` 用线性/双三次近似替代 PIL 的 antialias 双三次,数值与 PyTorch 预处理可能有微小差异。