# vision.cpp **Repository Path**: ningpengtao-apps/vision.cpp ## Basic Information - **Project Name**: vision.cpp - **Description**: vision.cpp:基于 ggml 的视觉推理 C ABI 运行时(PP-OCR / SCRFD / ArcFace / MobileNetV2) - **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-19 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # vision.cpp `vision.cpp` 是基于 [ggml](../ggml) 的 CNN 视觉运行时基座,为 PP-OCR、SCRFD、ArcFace、MobileNetV2 等模型族提供统一的 GGUF 加载、ggml 会话生命周期与稳定 C ABI。 当前已注册 `echo` 测试架构,以及 PP-OCR 检测 / 识别、SCRFD 人脸检测、ArcFace 人脸特征与 MobileNetV2 宠物分类模型;`echo` 用于端到端验证 C ABI、后端初始化、 F16 / Q8_0 权重加载与错误路径,其余模型通过 GGUF 中的图描述解释执行。 ## 已支持模型 | 架构名 | 模型 | 输入 | 输出 | 状态 | | --- | --- | --- | --- | --- | | `echo` | 测试架构 | `[4]` 任意数值 dtype | 与输入相同 | 已实现 | | `ppocr_det` | PP-OCRv4 / PP-OCRv5_server 文本检测(DB) | NCHW `[1,3,H,W]` F32 | v4:1 个 `[1,1,H,W]`;v5_server:2 个 `[1,1,H,W]` | 已实现(F16 / Q8_0 GGUF 实测) | | `ppocr_rec` | PP-OCRv4 / PP-OCRv5_server 文本识别(CTC) | NCHW `[1,3,H,W]` F32 | `[1,T,6625]`(CTC logits) | 已实现(F16 / Q8_0 GGUF 实测) | | `scrfd` | SCRFD det_500m / det_10g / scrfd_10g_bnkps 人脸检测 | NCHW `[1,3,H,W]` F32 | 9 个张量:score8/16/32、bbox8/16/32、kps8/16/32 | 已实现(F16 / Q8_0 GGUF 实测,640×640) | | `arcface` | ArcFace glintr100 / w600k_r50 / w600k_mbf 人脸特征 | NCHW `[1,3,112,112]` F32 | `[1,512]` 原始 embedding | 已实现(F16 / Q8_0 GGUF 实测) | | `mobilenetv2` | MobileNetV2-12 宠物分类 | NCHW `[1,3,224,224]` F32 | `[1,1000]` 原始 logits | 已实现(F16 / Q8_0 GGUF 实测) | 模型族的图结构、权重与字符表全部来自 GGUF: - `vision.ppocr.graph` / `vision.graph`:转换器序列化的节点描述,运行时按顺序建 ggml 图; - `quant` 图节点:按 `y_scale` / `y_zero_point` 模拟 int8 激活量化后反量化, 使 MobileNetV2 的反量化 float 图与源 ONNX int8 图语义一致; - `ppocr.character_table`:识别字符表,供 Dart 侧 CTC 解码; - 权重支持 F16 / Q8_0;PP-OCR 的卷积与部分 2D 线性权重、SCRFD 的全部权重会回退 F16,ArcFace 仅 `fc.weight` 使用 Q8_0,MobileNetV2 仅 `classifier.weight` 使用 Q8_0(原因见 `tool/vision_gguf/README.md`)。 ## 目录结构 ``` packages/vision.cpp/ CMakeLists.txt README.md include/vision.h # 稳定 C ABI src/vision.cpp # session 生命周期、后端、架构分发、C ABI 实现 src/gguf_loader.cpp/.h # GGUF 元数据、张量清单与权重读取 src/ops.cpp/.h # linear / conv2d / layernorm / rms_norm / softmax 等 src/models/model.h # VisionModel 接口与模型上下文 src/models/echo.cpp # 仅测试用的最小架构 src/models/ppocr_common.cpp/.h # PP-OCR 图描述解释器(v4 / v5_server 共用) src/models/ppocr_det.cpp # PP-OCR 检测模型工厂 src/models/ppocr_rec.cpp # PP-OCR 识别模型工厂 src/models/graph_common.cpp/.h # 通用 CNN 图描述解释器(PP-OCR / SCRFD / ArcFace / MobileNetV2 共用) src/models/scrfd.cpp # SCRFD 检测模型工厂与超参校验 src/models/arcface.cpp # ArcFace 特征模型工厂与输出校验 src/models/mobilenetv2.cpp # MobileNetV2 分类模型工厂与输入 / 输出校验 tests/test_vision.cpp # C ABI + ops + PP-OCR / SCRFD / ArcFace / MobileNetV2 真实 GGUF 测试 ``` ## 构建 要求 CMake 3.20+、C++17 编译器。ggml 复用共享 submodule `packages/ggml`(`https://github.com/ningpengtao-coder/ggml`),不复制源码;请先执行 `git submodule update --init packages/ggml`。 ### Windows(MSVC) ```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 ctest --test-dir packages/vision.cpp/build -C Release --output-on-failure ``` ### macOS(Clang) ```bash cmake -S packages/vision.cpp -B packages/vision.cpp/build -DVISION_BUILD_TESTS=ON cmake --build packages/vision.cpp/build --config Release -j8 ctest --test-dir packages/vision.cpp/build -C Release --output-on-failure ``` ### Linux(CPU) ```bash cmake -S packages/vision.cpp -B packages/vision.cpp/build -DVISION_BUILD_TESTS=ON cmake --build packages/vision.cpp/build --config Release -j8 ctest --test-dir packages/vision.cpp/build -C Release --output-on-failure ``` 产物默认输出到 `packages/vision.cpp/build/vision.cpp/`: - `vision_static.lib` / `libvision_static.a`:静态库,供 C++ 测试与 `vision.cpp-runtime` 内部链接; - `vision.dll` / `libvision.dylib` / `libvision.so`:只导出 `include/vision.h` 中的 C ABI。 ### 构建选项 | 选项 | 默认 | 说明 | | --- | --- | --- | | `VISION_BUILD_TESTS` | `OFF` | 构建 CTest 单元测试 | | `VISION_NATIVE_CPU` | `ON` | 为当前主机 CPU 编译 ggml 内核 | | `VISION_GGML_SOURCE_DIR` | `../ggml` | 复用的 ggml 源码目录 | | `VISION_OUTPUT_DIR` | `/vision.cpp` | 产物输出目录 | macOS 上 ggml 的 Metal 后端默认启用;运行时优先初始化 `MTL` 设备,失败则自动回退 CPU。Windows / Linux 使用 CPU 后端。 ## C ABI 用法 完整声明见 [`include/vision.h`](include/vision.h)。 ```c #include "vision.h" #include void run_once(const char * gguf_path, const float * image, float * logits) { char * err = NULL; vision_session * session = vision_session_load(gguf_path, 4, &err); if (session == NULL) { fprintf(stderr, "加载失败:%s\n", err != NULL ? err : vision_last_error()); vision_free_string(err); return; } int64_t in_shape[4] = {224, 224, 3, 1}; /* ggml 顺序:最内层维度在前 */ vision_tensor_input input = { .name = "input", .data = image, .shape = in_shape, .n_dims = 4, .dtype = VISION_DTYPE_F32, }; int64_t out_shape[4] = {0, 0, 0, 0}; vision_tensor_output output = { .name = "output", .data = logits, .shape = out_shape, .n_dims = 4, /* 进入时表示 shape 缓冲区容量 */ .dtype = VISION_DTYPE_F32, }; const int32_t status = vision_session_run(session, &input, 1, &output, 1, &err); if (status != VISION_OK) { fprintf(stderr, "推理失败:%s\n", err != NULL ? err : vision_last_error()); vision_free_string(err); } vision_session_free(session); vision_session_free(NULL); /* 安全空操作 */ } ``` ### 约定与内存所有权 - `vision_session_load`、`vision_session_run` 失败时通过 `error` 返回堆分配的中文消息,调用方必须用 `vision_free_string()` 释放。 - `vision_last_error()` 返回线程局部缓冲区,借用语义,永远不为 `NULL`;多线程调用不会串消息。 - 输入 / 输出 `data` 始终由调用方拥有,vision.cpp 只读写、不释放。 - `shape` 按 ggml 顺序排列:`shape[0]` 是最内层 / 最快变化维度。 - 输出张量的 `shape` 缓冲区容量由进入时的 `n_dims` 表示;run 成功后 `n_dims` 被改写为实际维度。实际维度大于容量会返回错误。 - 输出 `data` 必须由调用方按模型文档预留足够空间;基础 C ABI 没有输出字节数参数,不做越界检查。 - `vision_session_free(NULL)` 与重复释放同一个非空句柄均为安全空操作,但仍建议释放后置空指针。 - 同一个 session 的 `vision_session_run` 内部串行执行;不同 session 可并发。 ### 状态码 | 状态码 | 含义 | | --- | --- | | `VISION_OK` | 成功 | | `VISION_ERR_INVALID_ARGUMENT` | 参数非法 | | `VISION_ERR_IO` | GGUF 不存在、不可读或损坏 | | `VISION_ERR_ARCH_MISMATCH` | `general.architecture` 缺失或未注册 | | `VISION_ERR_MISSING_TENSOR` | 缺少模型实现所需张量 | | `VISION_ERR_BACKEND` | ggml 后端初始化失败 | | `VISION_ERR_OOM` | 内存或后端缓冲分配失败 | | `VISION_ERR_INTERNAL` | 内部错误 | ## GGUF 元数据约定 所有 vision.cpp 的 GGUF 必须包含: | Key | 类型 | 说明 | | --- | --- | --- | | `general.architecture` | string | 模型架构名,用于分派到 `VisionModel` 实现 | | `vision.version` | string 或 uint32 | 运行时模型版本;GGUF 布局变化时递增 | 可选: | Key | 类型 | 说明 | | --- | --- | --- | | `general.name` | string | 人类可读名称 | | `.*` | string / uint32 / float32 / 数组 | 模型族私有超参数 | 张量约定: - 张量名与转换工具(Task 3 的 `tool/vision_gguf`)输出保持一致; - 形状按 ggml 顺序记录在 GGUF tensor info 中,vision.cpp 通过 `tensor_info::ne` 暴露; - 权重支持 F32 / F16 / Q8_0 等 ggml 类型。线性层权重可以直接使用 Q8_0;LayerNorm、bias、位置编码、embedding 表按 spec 保持 F16 / F32; - 读取工具位于 `src/gguf_loader.h`:`read_string`、`read_u32`、`read_i32`、`read_f32`、`read_bool`、`read_string_array`、`read_i32_array`、`read_u32_array`、`read_f32_array`,`required = false` 时缺失 key 不报错。 ### echo 测试架构 `echo` 只用于测试,不是业务模型: - 必须有 `echo.weight` 2D 张量,类型 F32 / F16 / Q8_0; - `vision_session_run` 要求 1 个输入、1 个输出,输入与输出 dtype 必须一致; - run 时把输入原样拷贝到输出,并回填实际 shape。 单元测试用 C++ 直接写最小 GGUF(F16 / Q8_0 各一份),覆盖文件不存在、缺少 `general.architecture`、加载 / run / 重复 free,以及 ops 数值正确性。不依赖 Python 或 gguf-py。 ### SCRFD / ArcFace / MobileNetV2 元数据 三个架构与 PP-OCR 共用 `src/models/graph_common.cpp` 的图描述解释器: | 架构 | 必需元数据 | | --- | --- | | `scrfd` | `vision.graph`、`scrfd.variant`、`scrfd.strides`(uint32 数组)、`scrfd.anchors`、`scrfd.kps`、`scrfd.num_outputs` | | `arcface` | `vision.graph`、`arcface.variant`、`arcface.embedding_dim`、`arcface.input_size` | | `mobilenetv2` | `vision.graph`、`vision.input.width`、`vision.input.height`、`vision.input.channels`、`vision.num_classes` | - `scrfd.num_outputs` 必须等于 `scrfd.strides` 数量的 3 倍(每个 stride 输出 score / bbox / kps); - `arcface` 要求 1 个 4D 输入,H/W 必须等于 `arcface.input_size`,且恰好 1 个输出、 最后一维等于 `arcface.embedding_dim`; - `mobilenetv2` 要求 1 个 `[1,3,H,W]` 输入,H/W 与 `vision.input.height/width` 一致, 且恰好 1 个输出 `[1,vision.num_classes]`;`vision.batch_norm_folded` 为 false 时拒绝加载; - 图描述中的分组卷积:depthwise 走 `ggml_conv_2d_dw`,其它分组(如 MobileFaceNet 的 `group=64`、每组 2 个输入通道)逐组拆分后分别卷积,再按通道拼接; - SCRFD 的 `Resize` 目标尺寸来自运行时的 `Shape / Gather / Slice / Concat`,因此输出 行数随输入分辨率变化;ArcFace 的 BN 已在转换阶段折叠为 mul / add。 PP-OCR / SCRFD / ArcFace / MobileNetV2 测试会读取 `build/vision_gguf/` 下由 `tool/vision_gguf/convert.py` 生成的真实 GGUF;文件缺失时打印中文提示并跳过, 不会伪造通过。当前覆盖: - `ppocr_det-PP-OCRv4-f16` / `q8_0` 检测推理; - `ppocr_rec-PP-OCRv4-f16` / `q8_0` 识别推理; - `ppocr_det-PP-OCRv5_server-f16`、`ppocr_rec-PP-OCRv5_server-f16` 加载与推理; - `scrfd-det_500m-f16` / `det_10g-f16` / `scrfd_10g_bnkps-f16` / `det_500m-q8_0` 推理,640×640 输入下检查 9 个输出数量与形状与 ONNX 一致; - `arcface-w600k_mbf-f16` / `w600k_r50-f16` / `glintr100-f16` / `w600k_mbf-q8_0` 推理,检查输出形状为 `[1,512]`; - `mobilenetv2-12-int8-f16` / `q8_0` 推理,检查输出 `[1,1000]`;若 `test/fixtures/vision/generated/pet_mobilenetv2_12_int8/` 的 ONNX Runtime 参考张量存在,则按同一输入比较 top-1 与 logits 余弦并打印真实值,否则只校验形状。 MobileNetV2 的数值限制:源模型是 int8 QOperator,GGUF 保存反量化后的 F16 / Q8_0 权重。F16 权重舍入沿 52 层卷积累积,与 ONNX Runtime int8 参考相比 logits 余弦实测 约 **0.989**(top-1 完全一致);Q8_0 档只有分类头量化,余弦也约 **0.989**。 因此不套用 float 模型的 0.999 parity 目标,CTest 以 0.985 作为下限。 ## ops 算子层 `src/ops.h` 提供建图 helper(只建图,不执行): - `linear`:`x [in, n]`、`w [in, out]`(支持 Q8_0)、`b [out]`; - `conv2d`:`x [W, H, IC, N]`、`w [KW, KH, IC, OC]`、`b [OC]`; - `layernorm` / `rms_norm`:沿 `ne[0]` 归一化,gamma / beta 可广播; - `softmax`:沿 `ne[0]`; - `add` / `mul`:任一操作数可 repeat 到另一方即可广播,结果形状为较大操作数; - `view_2d`、`reshape_2d` / `reshape_4d`、`transpose`、`contiguous`。 模型在 `run()` 中把算子建到 `VisionModelContext::work_ctx`,最后调用 `execute_graph()`(定义在 `src/models/model.h`),由 session 的 gallocr 与 backend 执行。 ## 新增模型族 以新增模型族为例(`mobilenetv2` 已按此流程实现): 1. 新建 `src/models/mobilenetv2.cpp`,实现 `vision::VisionModel`: - `load()`:用 `VisionModelContext::find_tensor_info()` / `find_weight()` 校验张量,用 `gguf_loader` 的 `read_*` 读取超参; - `run()`:在 `ctx.work_ctx` 中用 `ops::*` 建图,`execute_graph()` 执行,`ggml_backend_tensor_get()` 把结果写回 `VisionOutput::data`,并填写 `shape` / `written_bytes`; - `metadata()`:可选导出元信息。 2. 在 `src/models/model.h` 声明工厂函数,例如 `std::unique_ptr create_mobilenetv2_model();`。 3. 在 `src/vision.cpp` 的 `create_model()` 中注册架构名: ```cpp if (arch == "mobilenetv2") { return create_mobilenetv2_model(); } ``` 4. 把新源文件加入 `CMakeLists.txt` 的 `VISION_SOURCES`。 5. 在 `tests/` 中补该架构的 C++ 测试;模型转换与量化由 Task 3 的 `tool/vision_gguf` 负责。 ## 平台支持 | 平台 | 后端 | 状态 | | --- | --- | --- | | Windows x64 (MSVC) | CPU | 已构建并通过 CTest | | macOS (Clang) | Metal(默认)/ CPU 回退 | 代码路径已实现,需在 macOS 上构建验证 | | Linux (Clang/GCC) | CPU | 代码路径已实现,未在本机验证 |