纯 C 写 OCR Runtime 这件事圈子里聊的人多真正动手的少。大部分团队的思路是先用 Python 把 PaddleOCR 跑通再想办法用 C 包一层部署遇到嵌入式环境就直接打包成 so 丢过去。听起来没问题但一旦设备算力有限、内存紧张、交叉编译链路复杂这层 C 包装就成了第一个卡脖子的地方。这个项目想解决的就是这个问题用纯 C 把 PPOCR 的模型推理链路完整重写做成一个零依赖、可裁剪、能被 C 程序直接调用的 OCR Runtime。preview.5 刚发出来内部结构又往前挪了一大步今天来说说这段时间都干了什么。适合看这篇文章的人挺明确做嵌入式终端、边缘盒子、离线识别设备的开发者或者正在为 OCR 推理引擎依赖太重而头疼的同学。如果你只是想在 PC 上快速调个 OCR 接口官方 PaddleOCR 更合适没必要折腾这套东西。1. 项目动机与整体定位1.1 现有方案的尴尬位置先讲讲我看到的现状。官方 PaddleOCR 本身的质量没得说中文识别精度在开源方案里基本是第一梯队模型也一直在迭代。但用到实际设备上会有几个坎第一PaddlePaddle 推理引擎的体积很可观完整的推理库打出来动不动几十 MB加上模型文件很多低端设备的存储空间直接亮红灯。第二推理引擎依赖的底层库五花八门OpenBLAS、MKL、CUDA、cuDNN 这些组件往上一摞交叉编译一次恨不得把整个人生都重新过一遍。第三C 程序要调用它中间必然隔着一层 C ABI 封装出了问题定位麻烦进程的内存布局也绕来绕去。Tesseract 倒是纯 C依赖也轻但那个识别效果在中文场景下真的一言难尽。遇到清晰印刷体还好稍微带点倾斜、光照变化、复杂背景准确率就肉眼可见地往下掉更别说现在常见的版面分析和结构化信息抽取场景了。云 API 方案就更不用说了离线设备上不许联网数据敏感的场景也不允许把图片传出去网络延迟和功耗就更别提了。综合下来在离线嵌入式场景里一个轻量的、推理精度能对齐 PaddleOCR 的本地 runtime就是刚需。1.2 为什么执着于纯 C选 C 而不是 C 或者 Rust理由很朴素C 是嵌入式世界的事实标准几乎所有交叉编译工具链都支持 C所有操作系统都能加载 C 编译出来的产物所有语言都提供 C ABI 的 FFI 接口。用 C 写出来的库编译成静态库之后可以被 C、Rust、Go、Python 直接调用不产生任何绑定成本。另外纯 C 有利于控制生成的代码。内存分配、数据类型、结构体布局完全由开发者掌控在资源受限设备上做内存池、零拷贝优化时不用跟 C 运行时的一些隐含行为较劲。有人可能会说用 Rust 写更安全用 C 写更省事。这话没错但在一个需要精确控制每个字节、需要适配各种老旧工具链的场景里C 的简单和直接恰恰是最大的优势。这个项目从名字就能看出思路lw 是 lightweightPPOCR 是对齐 PaddleOCR 的模型语义C 就是实现语言目标是把轻量做到底。提示如果你面向的是纯 Linux x86 服务器场景这些理由可能不那么成立。但在嵌入式、MCU 边缘节点、老旧的 ARM 设备上C 几乎是无条件的最佳选择。2. 纯 C Runtime 的整体架构与关键拆解2.1 OCR 识别链路的三段式设计我一直觉得OCR runtime 最核心的价值不只是会算还得把识别链路完整串起来。lw.PPOCR.C 沿用了 PaddleOCR 经典的三段式结构文本检测、方向分类、文本识别。文本检测阶段用的是 DBDifferentiable Binarization系列模型输入一张图输出的是文本区域的包围盒坐标。这个模型的输出是一张概率图要做像素级的二值化处理然后通过连通域分析找到文本行区域。传统做法是把检测框直接交给识别模型但实际图片里文本方向往往不一致尤其是手机拍照的场景所以中间加了一个方向分类器判断文本区域是否需要旋转到正向。最后才是文本识别模型把规整后的文本行图片变成字符串。三个模型串起来以后就是一条完整的 OCR 流水线。每两个模型之间都涉及图像裁剪、缩放、归一化、颜色空间转换这些在官方实现里都是 Python 和 OpenCV 一把梭在纯 C 环境下全部要自己写。我最初的代码量大概有三分之一花在这些预处理和后处理上。整个过程中的张量流转是分阶段进行的检测阶段整图输入输出文本框坐标数组。方向阶段按坐标裁剪出文本行图块逐块输入分类器得到是否旋转的标签。识别阶段将旋转后的图块输入识别模型通过 CTC 解码拿到字符串。这样拆开的优势在于每一段都可以独立优化比如检测阶段可以用低分辨率输入提速识别阶段再切回标准分辨率保证精度也可以针对不同硬件分别做算子优化。三个模型各司其职逻辑清晰。2.2 推理引擎的算子层实现纯 C 的推理引擎说白了就是一个最简化的深度学习框架。这个框架只需要支持卷积、池化、全连接、BatchNorm、激活函数、Softmax 这些基础算子因为 PPOCR 系列的模型结构基本就是这些算子的组合。算子层的设计我做了一个很关键的取舍所有算子的实现都按 NHWC 的布局来做。PaddlePaddle 原生模型导出时通常用 NCHW 布局但 NHWC 在纯 CPU 推理时对缓存的友好度更高因为连续的内存访问正好是每个像素的所有通道。实测下来在 ARM Cortex-A 系列芯片上NHWC 布局比 NCHW 有大约 15% 到 30% 的加速而且做图像预处理时不需要额外的 transpose省了一轮拷贝。卷积算子是最核心的部分我实现了直接卷积和 im2col GEMM 两种路径。当卷积核大小小于等于 3 且 stride 为 1 时走直接卷积利用循环展开减少乘加指令的开销其余情况走 im2col把卷积转换成矩阵乘法用纯手写的矩阵乘实现配合缓存分块做加速。BatchNorm 在推理阶段可以折叠进前面的卷积权重里这是所有推理引擎都会做的基本优化我这个实现也不例外在模型加载时就把 BN 参数融合进卷积层推理时少一次全张量遍历。内存管理是我花时间最多的地方。推理引擎如果频繁 malloc 和 free在实时场景下会带来两个问题一是分配耗时不可控容易有抖动二是长时间运行会产生内存碎片。我的做法是在引擎初始化时一次性分配一块固定大小的内存池后续所有的中间张量都从这个池子里取不再走系统分配器。由于 OCR 推理的中间张量数量是确定的内存池的大小在初始化时可以精确计算出来按最大需求预留即可。preview.5 里我把内存池的分配策略又细化了一层引入了分段复用机制让检测和识别阶段共享同一块内存空间的不同分片整体峰值内存比 preview.3 降低了大约 20%。2.3 模型文件的解析和加载模型文件加载是整个 runtime 的另一个关键点。PaddlePaddle 的模型有两种常见格式一种是 combined参数合并在一个文件里一种是分离的每个参数一个文件。我在 lw.PPOCR.C 里主要支持了 combined 格式因为部署时一个模型就一个文件方便管理。Paddle 模型的存储格式本质上是一个序列化的 protobuf 消息里面包含了模型的结构信息每个算子的类型、输入输出节点、属性。要在纯 C 环境下解析它有两种路径一是引入 protobuf-c 库二是在导出模型时做一次离线转换把模型转成自己定义的轻量格式。我选择了后者。项目里带了一个转换脚本Python 写的负责把官方 PaddleOCR 导出的推理模型转成 lw 格式。这个格式的头部是魔数 版本号 算子数量接着是每个算子的元信息类型、输入输出索引、属性键值对最后是参数字节流。转换后的模型文件比原始 Paddle 模型小了大概 10%因为去掉了原格式里一些冗余的字段描述同时权重做了量化对齐。这种做法的好处是运行时不需要 protobuf 解析器模型加载就是一次内存映射加少量解析加载时间在毫秒级。坏处是模型更新时转换脚本也要跟着维护不过这个代价完全值得因为 C runtime 本身的代码量维持在一个很克制的水平。3. preview.5 解决了什么关键问题3.1 从 preview.1 到 preview.5 的演进脉络这个项目从第一个预览版到现在大概经历了五个阶段。每次发 preview都是因为某个核心问题被彻底解决或模块被大幅重构而不只是修修 bug 就换个版本号。preview.1 做的是最小可用验证。用纯 C 把 PPOCR 的 mobile 版本三个模型全部跑通推理识别结果能出中文。那时候性能还很拉胯一张 640x640 的检测图在树莓派 4B 上要跑 4 秒多但至少证明了这条路走得通。preview.2 重点优化了卷积算子。通过寄存器分块 cache 优化把卷积耗时降到了原来的三分之一。同时补上了内存池的第一版实现大幅减少运行时的内存分配次数。preview.3 引入了多线程并行把检测和识别两个阶段用流水线方式并行执行。同时增加了模型热切换能力可以在运行时动态加载和卸载不同语言的识别模型。preview.4 做的是精度对齐工作。我拿官方 PaddleOCR 的 Python 推理结果逐张图比对一项项排查算子实现里的数值精度损失修了好几个因为 float 计算顺序导致的精度偏差问题。这个版本结束后同一张图的识别结果和官方方案已经能对齐到 99% 以上。preview.5 就是这个月的版本重点做了两件事内存池的优化重构和方向分类器的加速。另外还把模型转换脚本做了新一轮的整理让它支持 PaddleOCR 最新的模型版本。3.2 preview.5 里的三块硬骨头第一个是内存池的收尾重构。之前内存池有一个问题虽然不再频繁调用 malloc但内存碎片还是存在因为不同大小的张量交错申请和释放。preview.5 里我改成了分段式分配策略把内存池按用途分成多个 zone检测阶段只使用一个 zone识别阶段使用另一个 zone两者互不干扰。每个 zone 内部按固定大小块做分配彻底避免了碎片问题。实测下来连续处理 1000 张图片内存池的碎片率从 15% 降到了接近 0峰值内存从之前的 380MB 降到了 310MB 左右。第二个是方向分类器的加速。方向分类器本身是个很小的模型但它在流水线里是逐个文本区域调用的文本区域多的时候调用次数成百上千小的延迟被放大成大问题。我把方向分类器的推理改为批处理模式多个文本框可以合并成一批输入复用同一份卷积计算。在文本框数量超过 20 个的场景下方向分类的总耗时减少了约 40%。第三个是模型兼容性。PaddleOCR 最近更新了若干个模型版本包括新的检测模型和识别模型个别算子的结构有调整。preview.5 的转换脚本同步适配了这些变化同时将模型文件格式升级到 v2增加了一个自定义属性字段用于记录模型的输入尺寸和归一化参数运行时加载不用再写死这些值。3.3 一个直观的性能数字对比下面这组数据是我在树莓派 4B4GB 版本4 核 ARM Cortex-A72上跑出来的模型用的是 PaddleOCR mobile 版本测试图片是一张 1920x1080 的发票照片。场景preview.3 耗时preview.4 耗时preview.5 耗时检测模型整图1210 ms980 ms930 ms方向分类30 个文本框260 ms240 ms145 ms文本识别30 行文本830 ms760 ms740 ms全流程合计2300 ms1980 ms1815 ms峰值内存385 MB380 MB310 MB这些数字看起来依然不低但要注意这是纯 CPU 推理没走任何 GPU 或 NPU 加速。在带有 NPU 的设备比如 RK3588上模型可以导出成相应格式后把算子映射到 NPU 执行推理耗时会有一个数量级以上的下降。runtime 本身在设计时就留了算子后端注册的接口未来加 NPU 后端不是推翻重来只是多写一个 backends 目录。注意因为模型导出的格式、图片内容、文本行数量都不一样你实际跑出来的数据大概率跟上面有出入。对比的时候更值得关注的是同环境下不同版本的相对提升。4. 从零把 lw.PPOCR.C 跑起来4.1 准备模型文件这是最容易踩坑的环节因为 lw.PPOCR.C 不能直接加载 PaddleOCR 原版的推理模型需要先用配套的转换脚本处理一步。准备模型文件的完整步骤如下从 PaddleOCR 官方仓库下载训练好的推理模型注意选择推理模型inference model不是训练模型。推荐用 mobile 版本识别速度更快在 CPU 设备上体验更好。用项目里的 model_convert.py 脚本把 Paddle 推理模型转换成 runtime 能识别的 .lw 格式。该脚本需要 Python 3.8 以上和 PaddlePaddle 推理库但只用于离线转换转换完成后运行设备上不需要安装任何 Python 环境。确认转换输出三个文件det_model.lw、cls_model.lw、rec_model.lw分别对应检测、方向分类、识别。同时还会生成一个 model_config.json记录每个模型的输入尺寸和均值方差参数这个文件运行时也会用到。转换命令大概是这样的具体路径按你的实际目录调整python3 tools/model_convert.py \ --det_model ./ppocr_mobile/det/inference.pdmodel \ --det_params ./ppocr_mobile/det/inference.pdiparams \ --cls_model ./ppocr_mobile/cls/inference.pdmodel \ --cls_params ./ppocr_mobile/cls/inference.pdiparams \ --rec_model ./ppocr_mobile/rec/inference.pdmodel \ --rec_params ./ppocr_mobile/rec/inference.pdiparams \ --output_dir ./lw_models如果你用的不是标准的 PPOCR mobile 模型而是自己微调过的模型转换脚本也能处理只要模型结构没有引入全新的算子类型。引入新算子的话转换脚本会明确报错并提示缺哪个算子的映射这样你就知道 Runtime 内核还差什么了。4.2 编译与第一个识别示例lw.PPOCR.C 的构建系统用的是 CMake编译前只需要确认目标设备上有可用的 C99 编译器、CMake 3.10 以上版本不需要其他任何第三方依赖。连基础的图像解码库都不依赖运行时因为图像加载部分我封装了最简单的 BMP/PPM 读取真实项目中你可以用 stb_image 或自己的解码模块替代。编译步骤mkdir build cd build cmake .. -DCMAKE_BUILD_TYPERelease make -j4编译完成后build 目录下会生成静态库 liblwppocr.a 和几个示例可执行文件。最简单的示例是 lw_ocr_demo用法如下./lw_ocr_demo \ --det ./lw_models/det_model.lw \ --cls ./lw_models/cls_model.lw \ --rec ./lw_models/rec_model.lw \ --config ./lw_models/model_config.json \ --image ./test_images/invoice.bmp正常的话终端会逐行打印识别结果每一行包含文本框的四个顶点坐标和识别出的文本内容。坐标值是按输入图片的尺寸归一化后的比例值实际使用时要乘以图片宽高还原成像素坐标。4.3 集成到自己的 C 程序里集成 API 是这套 runtime 最看重的部分。整个公共接口经过几轮重构后现在收敛成非常清爽的三个函数#include lw_ppocr.h /* 初始化 runtime加载三个模型 */ lw_ocr_t* ocr lw_ocr_create( /models/det.lw, /models/cls.lw, /models/rec.lw, /models/config.json); /* 执行识别输入 RGB888 图像数据 */ lw_ocr_result_t result; lw_ocr_run(ocr, image_data, width, height, stride, result); /* 释放 runtime */ lw_ocr_destroy(ocr);结果结构体里是一个动态数组每个元素是一个文本框和对应文本。使用完调用lw_ocr_result_release(result)释放。接口设计成对 image buffer 直接操作而不是对文件路径操作就是为了方便接入摄像头帧和网络传输过来的图片数据。整个过程里没有任何隐式的全局状态。多个lw_ocr_t实例可以同时存在互不干扰这对多路视频流并行处理的场景特别有用。每个实例内部的内存池是独立的所以多实例的总内存消耗大约等于单实例乘以实例数在设备内存有限的情况下要规划好并发路数。5. 常见编译与运行问题排查实录5.1 编译期问题工具链的兼容性坑最常见的问题是老旧的交叉编译工具链不支持 C99 的某些特性尤其是变长数组和stdint.h里的固定宽度类型。preview.5 在代码里已经尽量规避了这类问题但仍建议使用 GCC 8 以上的工具链越新越省心。另一个高频问题是如果设备是 32 位 ARM 架构size_t是 4 字节的模型文件里如果保存了超过 4GB 的权重这种情况很少但确实可能出现在超大识别模型上加载会失败。解决办法是改用 mobile 系列模型不要用 server 系列。5.2 模型加载失败和内存越界模型加载失败时优先检查三件事文件路径是否正确扩展名是否为 .lw。模型文件格式版本是否和运行时版本匹配。preview.5 使用的是 v2 格式如果是用旧版转换脚本生成的 v1 文件需要重新转换。模型文件的校验和是否正确。加载时会对文件头部做一次魔数校验不对就说明模型文件在拷贝过程中损坏了。内存越界问题通常是图片尺寸没对齐导致的。runtime 内部要求输入图片的宽和高都能被 32 整除如果测试图片不是这个尺寸需要先做 padding 再传入否则卷积算子计算到边缘时会越界读取。示例代码里已经有 padding 逻辑但如果你直接通过 API 接入自己的图片数据这个细节必须注意。5.3 识别精度偏差的排查方向识别结果跟官方 PaddleOCR 不一致这个问题的排查方向是有迹可循的先确认预处理参数是否一致。PaddleOCR 模型的输入归一化用的是均值 0.5、方差 0.5和 ImageNet 的标准不一样。如果你的调用方式用了其他归一化参数精度会直接崩。model_config.json 里已经写好了这些参数正常情况下运行时会自动读取不用手工设置。检查图片通道顺序。纯 C 代码里容易出现 RGB 和 BGR 顺序混淆导致颜色空间不对文本区域检测不出来。API 文档里写的是 RGB888实际传入前可以做一次通道转换验证。确认图片是否畸变。识别模型对输入图片的宽高比有一定要求严重拉伸或压缩的图识别准确率会显著下降。官方做法是按比例缩放后做 padding保证内容不变形。5.4 常见问题速查表现象可能原因处理方法编译报错uint8_t未定义工具链 stdint.h 不完整升级工具链或在编译参数中手动包含头文件加载模型返回错误码 0x03模型格式版本不匹配重新用最新转换脚本转换模型识别结果全是空字符串图片通道顺序错误确认传入 RGB 或 BGR 与 API 文档一致检测框严重偏移输入尺寸未做 32 对齐先 padding 到 32 的整数倍运行速度远慢于预期未开启 Release 编译编译时加-O3 -DNDEBUG多线程调用偶发崩溃多个线程共用了一个 runtime 实例每个线程单独创建实例或加锁保护6. 当前版本的局限与后续路线图6.1 还没有彻底解决的几个点preview.5 虽然比之前稳定了一大截但离无脑集成还有距离。目前最明显的局限是算子覆盖范围还不够全。PPOCR 官方经常出新模型最近像 SVTR、PP-OCRv4、v5 的结构里引入了一些新的算子比如某些激活函数的变体转换脚本要跟着适配runtime 内核也要补实现。我已经把主要路径都兼容了但长尾算子可能还有缺口。第二个局限是纯 CPU 推理的性能天花板。在低端 ARM 设备上虽然内存优化已经做得比较到位但算力摆在那里大规模并发识别还是会吃力。后续计划在算子层接入 NEON SIMD 指令优化这个能带来 2 到 3 倍的性能提升同时研究 NPU 后端的接入方案。第三个是文本检测的后处理还不够灵活。目前只实现了标准的 DB 后处理对于弯曲文本、竖排文本这类场景支持还比较初级。可以做的不只是优化文本区域检测还可以考虑为后续的版面结构化、关键信息抽取打基础这类需求在实际项目中往往比单纯的识别更有价值。6.2 给想用这套方案的人几个建议综合这段时间踩过的坑我有几个比较实在的建议想分享如果你的 OCR 场景是纯 CPU、单路视频流、图片不大preview.5 已经可以直接用于产品验证。但做产品上线前建议先把典型场景的 1000 张测试图片跑一遍确认两个东西识别精度是否满足业务要求长稳测试下内存是否稳定。如果目标是量产尽量锁定一个固定的模型版本。runtime 对模型的兼容性在不断提升但换模型始终有风险模型换了以后一定要做全量回归。我在项目里写了一个简单的回归测试脚本能自动比对两个版本 runtime 的输出差异建议你也搞一个。如果是资源极小的 MCU 场景内存小于 100MBmobile 模型仍然偏大。这种场景可以放弃检测模型直接传入裁剪好的文本行图片只跑识别模型这样内存占用能压低到 60MB 左右虽然功能弱了但识别管线已经跑得起来了。从我个人的实际体会来说这个项目最值钱的部分并不是某个算子的优化或者某个模型的兼容而是把只靠标准 C 就能跑起一套完整 OCR这件事验证透了。后面再往别的平台移植或者接入新的硬件加速单元核心基础设施都已经在 preview.5 里就位了。每一版踩过的坑都在给下一版铺路接下来要做的事依然是继续把这条路往前推。