8.6M超轻量中文OCR：单模型搞定中英数混排与竖排长文本

简介：这是一款面向开发者与算法工程师的超轻量级中文OCR工具库，总模型体积仅8.6MB，专为在资源受限环境下实现快速、准确文本识别而设计。单模型即可覆盖中英文数字组合识别、竖排文本识别与长文本识别，适用于文档数字化、古籍整理、法律与学术资料批量处理等场景，兼顾入门调试与工程落地需求。资源包共约2000个文件，以Python源码、Markdown说明、文本配置、图片样本及YAML训练配置为主，另含C++、Java、Shell等工程文件与字体资源，压缩包整体约195MB，目录结构完整，便于按模块查阅与二次开发。目前已有449人学习下载。内容涵盖文本检测与识别训练算法、后处理与裁剪等核心模块，读者可据此快速搭建识别流程、理解模型推理与训练细节，并针对竖排、长文本等难点进行调优与排错，具备较高的实用参考价值。

1. 8.6M 超轻量中文 OCR 工具库：单模型搞定中英数混排与竖排长文本

前阵子帮朋友做一个古籍数字化的小工具，需求很具体：把扫描的竖排繁体书页转成可编辑文本，跑在一台没有独立显卡的旧笔记本上。试了几个方案，要么模型动辄几百兆，要么竖排识别直接乱序，直到翻到这个总模型仅 8.6M 的超轻量级中文 OCR 工具库。它最反直觉的地方在于——单模型同时支持中英文数字组合识别、竖排文本识别和长文本识别，不需要为每种版式单独切模型。这意味着在边缘设备、嵌入式终端或者纯 CPU 环境下，你也能跑起一套完整的中文 OCR 流程。适合谁？做文档数字化、票据字段抽取、问卷拍照识别、古籍整理的开发者，尤其是那些被模型体积和推理速度卡住的场景。下面我按「这是什么 → 怎么用 → 坑在哪」的顺序，把源码包里那几个核心文件拆开讲。

2. 从 infer.c 到 ocr_ppredictor.cpp：推理链路与编译落地

2.1 源码包里的文件分工，先搞清楚谁调谁

拿到源码包，别急着编译。先看文件清单，理解模块边界，后面排错能省一半时间。这个工具库的推理链路大致分四层：入口层、检测层、识别层、后处理层。

常见做法是：infer.c负责参数解析和主循环，ocr_ppredictor.cpp里的类负责实际推理，general_detection_op.cpp出检测框，ocr_clipper.cpp把框裁出来送识别，postprocess_op.cpp把识别结果拼回原图坐标。paddlestructure.cpp是竖排和长文本能跑通的关键——它决定文本行是按列读还是按行读。

提示：如果你只做横排短文本，可以暂时不碰paddlestructure.cpp；但只要涉及竖排或跨栏长文本，这个文件必须编译进去，否则输出顺序会乱。

2.2 编译参数怎么设：CPU 推理与裸机裁剪

这个库的编译选项直接决定体积和速度。我一般会先跑通 CPU 版本，再根据目标平台裁剪。下面是一套常见的 CMake 配置片段，注意注释里的参数含义。

# 创建构建目录，保持源码树干净 mkdir build && cd build # 基础配置：开启 CPU 推理，关闭不必要的测试和文档 cmake .. \ -DCMAKE_BUILD_TYPE=Release \ # Release 下算子融合更充分，速度明显快于 Debug -DWITH_CPU=ON \ # 纯 CPU 推理，适合无显卡环境 -DWITH_TESTING=OFF \ # 关掉单元测试，减小产物体积 -DWITH_DOCS=OFF \ # 不生成文档 -DUSE_OPENMP=ON # 开启 OpenMP，多核并行预处理和后处理 # 编译，-j 后面跟 CPU 核心数，别开太大否则内存吃紧 make -j4

逻辑说明：CMAKE_BUILD_TYPE=Release不只是优化等级，它还会影响某些算子的实现路径，Debug 下可能慢三到五倍。WITH_CPU=ON是这套库的默认推荐，因为 8.6M 的模型本身就不是为 GPU 大吞吐设计的。USE_OPENMP=ON对长文本识别帮助明显，因为后处理里的解码和坐标还原可以并行。

参数怎么改：如果你的目标板内存很小（比如 256M 以下），把USE_OPENMP关掉，减少线程栈开销；如果编译报找不到custom_relu_op.cc里的符号，检查是否漏了对应的算子注册宏，常见做法是在ocr_ppredictor.cpp初始化时显式注册一次。

2.3 跑通第一张图：infer.c 的调用与输出解读

编译出可执行文件后，先用一张测试图验证链路。infer.c的参数设计比较直白，但有几个默认值容易让人误解。

# 基本调用：指定模型目录、输入图片、输出结果文件 ./ocr_infer \ --model_dir ./models \ # 模型目录，里面放 det 和 rec 两个子模型 --image_path ./test_vertical.jpg \ # 输入图片，支持 jpg/png/bmp --output_path ./result.txt \ # 输出文本文件，每行一个文本框内容 --use_gpu false \ # 强制 CPU，避免没显卡时初始化失败 --det_limit_side_len 960 \ # 检测输入边长，长文本可适当调大 --rec_batch_num 6 # 识别批大小，内存紧张就调小

逻辑说明：--det_limit_side_len控制检测阶段的输入分辨率。调大能提升小字检出率，但显存/内存占用上升；调小则快但可能漏检。--rec_batch_num是识别阶段一次送多少文本框，批越大吞吐越高，但峰值内存也越高。--use_gpu false在纯 CPU 环境必须显式指定，否则某些版本会尝试初始化 GPU 然后报错退出。

输出文件里每行是一个文本框的识别内容，顺序由paddlestructure.cpp决定。如果你发现竖排文本输出成了乱序，先检查这个文件是否参与编译，再检查--det_limit_side_len是否太小导致整列被切成多个碎片。

3. 竖排与长文本识别：paddlestructure.cpp 的版面逻辑与参数调优

3.1 竖排文本为什么容易翻车：阅读顺序与坐标排序

竖排识别的难点不在单字识别，而在阅读顺序。横排文本按 y 坐标从上到下、x 坐标从左到右排序就行；竖排文本要按 x 坐标从右到左、y 坐标从上到下排序。如果直接用横排的排序逻辑，输出就是乱的。

paddlestructure.cpp里通常有一个版面分析步骤：先判断文本块的走向，再决定排序策略。常见做法是计算文本框的宽高比，宽高比小于某个阈值就判为竖排。这个阈值在不同字体下需要微调。

// 伪代码示意：判断文本块是否为竖排 float aspect_ratio = box_width / box_height; bool is_vertical = aspect_ratio < 0.8f; // 0.8 是经验值，窄长框更可能是竖排 if (is_vertical) { // 竖排：先按 x 降序（从右到左），再按 y 升序（从上到下） sort(boxes.begin(), boxes.end(), [](const Box& a, const Box& b) { if (std::abs(a.x - b.x) > 10) return a.x > b.x; // x 差超过 10 像素才认为不同列 return a.y < b.y; }); } else { // 横排：先按 y 升序，再按 x 升序 sort(boxes.begin(), boxes.end(), [](const Box& a, const Box& b) { if (std::abs(a.y - b.y) > 10) return a.y < b.y; return a.x < b.x; }); }

逻辑说明：aspect_ratio < 0.8f这个阈值不是固定的。古籍竖排字通常比较瘦长，0.8 合适；但如果是竖排英文或数字，宽高比可能接近 1，需要调到 1.0 甚至 1.2。std::abs(a.x - b.x) > 10里的 10 像素是容差，防止同一列内因为检测框抖动被拆成两列。这个值跟图片分辨率有关，高分辨率图要相应调大。

参数怎么改：如果你处理的竖排文本列间距很小，把 x 容差调小到 5；如果列间距很大，调到 15 或 20。没有万能值，拿几张典型图跑一遍看输出顺序最靠谱。

3.2 长文本识别的分段策略：det_limit_side_len 与拼接逻辑

长文本识别不是把整张图直接塞进识别模型，而是先检测出所有文本框，再逐个识别，最后按版面顺序拼接。这里有两个关键参数：检测阶段的det_limit_side_len和识别阶段的拼接逻辑。

det_limit_side_len设得太小，长文本会被压缩，小字糊成一团；设得太大，检测算子内存暴涨。我一般会按图片长边来算：如果原图长边超过 2000 像素，先缩放到 1600 左右再送检测，检测完把坐标映射回原图。

# 长文本场景的推荐参数组合 ./ocr_infer \ --model_dir ./models \ --image_path ./long_doc.jpg \ --output_path ./result.txt \ --det_limit_side_len 1600 \ # 长文本适当放大，保证小字可检 --det_db_thresh 0.3 \ # 检测阈值，调低召回更多框，但误检也增多 --det_db_box_thresh 0.5 \ # 框置信度阈值，低于此值的框丢弃 --rec_batch_num 4 \ # 批大小适中，兼顾内存和速度 --use_space_char true # 识别结果保留空格，长文本可读性更好

逻辑说明：det_db_thresh和det_db_box_thresh是检测阶段的两个阈值。前者控制像素级分割的灵敏度，后者控制框级过滤。长文本里小字多，det_db_thresh可以降到 0.2 到 0.3；但降太低会把噪点也检成文字，需要配合det_db_box_thresh过滤。use_space_char true对中英混排长文本很重要，否则英文单词会粘在一起。

拼接逻辑在postprocess_op.cpp里。常见做法是：按版面顺序取文本框，如果两个框在同一行且水平间距小于某个阈值，就拼成一行；如果垂直间距小于阈值，就换行。这个阈值通常跟文本框高度挂钩，比如行间距小于 0.5 倍框高就认为是同一段。

注意：长文本识别时，如果图片有倾斜，先做纠偏再送检测。ocr_clipper.cpp里的透视变换能处理轻微倾斜，但倾斜超过 15 度时检测框会严重变形，识别率断崖式下降。

3.3 中英数混排的识别边界：单模型的能力与局限

单模型支持中英文数字组合识别，听起来很美好，但实际用起来有几个边界要知道。这个 8.6M 的模型对中文常用字覆盖不错，英文单词和数字也没问题，但遇到以下情况会翻车：

第一，中英混排时没有空格分隔。比如「温度25度」识别成「温度25度」没问题，但「ABC公司」可能识别成「ABC公司」或「A BC公司」，取决于模型对字符间距的敏感度。常见做法是在后处理里加规则：连续英文字母和数字之间不插空格，中英文交界处根据字符类型判断。

第二，特殊符号和生僻字。模型体积只有 8.6M，字符集不可能覆盖所有 Unicode。如果你的场景涉及化学式、数学符号或罕见姓氏，先拿样本测一遍，别等上线了才发现某个字永远识别错。

第三，竖排英文。竖排中文的阅读顺序是从右到左、从上到下，但竖排英文通常是旋转 90 度后按横排读。paddlestructure.cpp对竖排英文的处理需要额外判断：如果文本框内字符是拉丁字母，按旋转后的横排逻辑排序。

// 伪代码：竖排英文的特殊处理 if (is_vertical && contains_latin(text)) { // 竖排英文：按 y 升序（从上到下），再按 x 降序（从右到左） // 但识别时要把图片旋转 90 度再送识别模型 rotate_image(roi, 90); text = recognize(roi); }

逻辑说明：这段逻辑不是所有版本都有，如果你的源码包里paddlestructure.cpp没有类似分支，竖排英文会识别成乱序。解决办法是在送识别前手动旋转 ROI，或者在应用层做二次排序。

4. 避坑与排查：编译、推理、后处理里的五个血泪经验

4.1 编译报错找不到 custom_relu_op 符号

现象：链接阶段报undefined reference to custom_relu_op，或者运行时报算子未注册。

原因：custom_relu_op.cc是自定义算子，需要在推理引擎初始化时显式注册。很多示例代码只调了ocr_ppredictor.cpp的初始化，忘了注册自定义算子。

解决：在ocr_ppredictor.cpp的初始化函数里加一行注册调用，常见做法是REGISTER_OPERATOR(custom_relu, ...)宏，或者手动调用注册函数。检查编译命令里是否包含了custom_relu_op.cc，有些构建脚本会漏掉.cc文件。

4.2 竖排文本输出顺序错乱

现象：识别内容都对，但顺序是乱的，比如从右到左的列被读成了从左到右。

原因：paddlestructure.cpp没参与编译，或者排序阈值不适合当前字体。

解决：先确认编译产物里包含paddlestructure.o。如果包含了还乱，调aspect_ratio阈值和 x 容差。拿一张只有两列竖排的图测试，看输出顺序是否从右列开始。如果不是，把 x 排序方向反过来。

4.3 长文本识别到一半截断

现象：长文档识别结果只输出前半部分，后半部分丢失。

原因：det_limit_side_len太小，后半部分被压缩后检测不到；或者rec_batch_num太大导致内存不足，后半部分静默失败。

解决：先把det_limit_side_len调到 1600 或 1920，再跑一次。如果还截断，把rec_batch_num降到 2 或 1，看是否恢复。同时检查输出文件是否被覆盖写，有些示例代码每次识别都重新打开文件，导致只保留最后一批结果。

4.4 中英混排时英文单词被拆散

现象：「HelloWorld」识别成「Hello World」或「Hel loWorld」。

原因：后处理里的空格插入逻辑过于激进，或者检测阶段把单词切成了多个框。

解决：在postprocess_op.cpp里找到空格插入逻辑，把「连续英文字母之间不插空格」的规则加进去。如果是检测阶段切框太碎，调大det_db_box_thresh让框合并，或者调小det_db_thresh减少误切。

4.5 CPU 推理速度慢到无法接受

现象：单张 A4 文档识别耗时超过 10 秒。

原因：Debug 编译、OpenMP 没开、或者det_limit_side_len设得过大。

解决：确认CMAKE_BUILD_TYPE=Release，确认USE_OPENMP=ON，把det_limit_side_len从 1920 降到 960 试试。如果还慢，检查是否在循环里反复加载模型——常见错误是每张图都重新初始化 predictor，应该初始化一次然后复用。

5. 进阶技巧：用 demo_bare_metal.c 做嵌入式裁剪与精度验证

demo_bare_metal.c是这个源码包里最容易被忽略的文件，但它对嵌入式场景很有价值。裸机示例去掉了文件系统依赖和标准库的大部分调用，只保留核心推理链路。如果你要把 OCR 塞进单片机或 RTOS，从这个文件开始裁剪比从infer.c改要省事得多。

我一般会分三步做裁剪和验证。第一步，用demo_bare_metal.c在 PC 上跑通，确认输入输出格式符合预期。第二步，把图像预处理里的浮点运算换成定点或查表，减少 CPU 周期。第三步，用一批标注好的测试图做精度对比，确保裁剪后识别率下降不超过可接受范围。

精度验证的常见做法是：准备 50 到 100 张覆盖你业务场景的图，人工标注真值，然后跑批量推理，统计字符级准确率和整行准确率。字符级准确率看单字对不对，整行准确率看整行完全正确比例。竖排和长文本要单独统计，因为这两类最容易出问题。

# 批量验证脚本示意：遍历测试图，输出准确率统计 for img in ./test_images/*.jpg; do ./ocr_infer --model_dir ./models --image_path "$img" --output_path ./tmp_result.txt # 与真值文件对比，统计字符级和行级准确率 python3 eval.py --pred ./tmp_result.txt --gt "./gt/$(basename $img .jpg).txt" done

逻辑说明：eval.py需要自己写，核心逻辑是逐行对比预测文本和真值文本，用编辑距离算字符级准确率，用完全匹配算行级准确率。竖排测试集和横排测试集分开跑，长文本单独统计。如果竖排准确率明显低于横排，回去调paddlestructure.cpp的排序阈值；如果长文本行级准确率低但字符级不低，说明拼接逻辑有问题，检查postprocess_op.cpp的换行阈值。

从那以后我每次拿到新的 OCR 源码包，都强制先跑一遍demo_bare_metal.c的最小链路，再用自己的测试集验证竖排和长文本，最后才动业务代码。这个习惯帮我省掉了至少三次「上线后才发现竖排乱序」的返工。希望帮到你。

本文还有配套的精品资源，点击获取