端侧OCR推理全解析:MakeACopy的PaddleOCR ONNX管线、CTC解码与语言路由实现原理

原创2026-11-15 21:57:452,209 阅读

端侧OCR推理全解析:MakeACopy的PaddleOCR ONNX管线、CTC解码与语言路由实现原理

MakeACopy 是一款开源的 Android 文档扫描应用,它的核心亮点在于:OCR 全程端侧推理——手机离线运行 PaddleOCR v5 的 ONNX 模型(由 ONNX Runtime 执行),不上传云端、不做任何跟踪。对新手来说,"一张照片如何变成带坐标的文本"可能很抽象,本文就用这条 PaddleOCR ONNX 管线为主线,把 DB 文本检测、CTC 贪心解码、多语言模型路由 三大核心机制讲透,并指出每个环节在源码中的具体位置。

一、OCR 管线全景:从照片到可搜索文本

MakeACopy 的 OCR 引擎由 PaddleOcrEngine.java 统一调度,一次 run(bitmap) 调用依次经过五步:

  1. 语言路由:把用户选的语言码解析成识别模型 key(详见第四节);
  2. 文本检测:det.ort 输出概率图 → DB 后处理得到文字行的四边形(Quad);
  3. 逐行裁剪:按四边形从原图裁出文本条;
  4. 字符识别:每条文本条送入按语言选定的 rec.ort,输出时间步 logits;
  5. CTC 解码 + 布局重建:把 logits 解成文字,再按行分组、处理右起语言、输出带坐标的词表。

这套管线可以离线处理各种真实场景的文档,例如双栏排版、小字号报纸等:

MakeACopy端侧OCR双栏文档识别评测样例:PaddleOCR检测管线对双栏排版的处理对象

(评测样例位于 app/src/androidTest/assets/eval/,附 *.gt.txt 标准答案,可用于核对识别结果。)

二、第一阶段:DB 文本检测与 Letterbox 预处理

检测器只有一个模型:det.ort(约 4.9 MB,见 SUMMARY.txt)。执行器 PaddleDetOrtRunner.java 的 detectOnce() 做了三件关键的事:

  • Letterbox 缩放:由 Letterbox.java 计算缩放参数,长边默认压到 1536px(DEFAULT_MAX_SIDE);开启"最佳 OCR 质量"后提升到 1920px(HIGH_QUALITY_MAX_SIDE),专门救报纸小字号。宽高对齐 32 像素步长,黑边填充。
  • 归一化:转成 NCHW 的 BGR 张量,按 ImageNet 均值/标准差标准化(L343-L359)。
  • DB 后处理:模型输出 <a href="https://link.gitcode.com/i/27654c8dcbd2ead7ebe1acd40eab07ff" target="_blank">1,1,H,W] 概率图,[DbPostProcessor.java 以 db_thresh=0.3 二值化、BFS 找连通域、box_thresh=0.6 过滤、再按 unclip_ratio=1.5 外扩。外扩这一步至关重要——DB 模型预测的"墨核"缩在文字内部,不扩回去就会把每行的首尾字母吃掉(早期版本因此出现 "Inselbewohner" 读成 "[nselbewohner" 的 bug)。

检测完的 Quad 会去 letterbox 映射回原图坐标,并按左上到右下的阅读顺序排序。

三、第二阶段:48px 识别输入与 CTC 贪心解码

识别侧是真正"多模型"的部分。执行器 PaddleRecOrtRunner.java 的 recognize() 对每条文本条:

  • 固定识别输入高度为 48px(REC_INPUT_HEIGHT),等比缩放宽度并对齐 8 像素步长;
  • 缩放前先逐级减半(Mipmap 策略),因为 Android 双线性降采样在大倍率下会撕裂细小笔画;
  • 张量按 pixel/127.5 - 1.0 归一化到 [-1, 1]。

模型输出是 <a href="https://link.gitcode.com/i/84e6b66b60bc8e93e3f0c60beefba2d6" target="_blank">T, C] 的 logits:T 个时间步 × C 个字符类。解码交给 [CtcDecoder.java,这是标准 CTC(Connectionist Temporal Classification)贪心解码:

  1. 对每个时间步取 argmax(概率最大的字符类);
  2. 合并相邻重复:连续的同一个 token 只保留一个(模型用重复帧"拉长"字符,属于正常行为);
  3. 丢弃 blank 类:词汇表第 0 项是 CTC 空白槽,对应"此帧无字符"。

两个容易踩坑的细节,源码里都有针对性处理:

  • Softmax 自动识别(L141-L166):如果输出最大值已落在 (0,1] 且整行和约为 1,就当概率直接用;否则做数值稳定的 1/Σexp(x-max) 计算。这样无论模型尾部带不带 Softmax 层都能兼容。
  • Off-by-one 防护:RecDictLoader.java 读取词典时强制在头部插入空白槽。PaddleOCR 的 rec_dict.txt 只包含第 1..N 类,不补这个 pad 的话,vocab[argmax] 会整体错位一个字符(调试里会看到 "Mpsfn" 而不是 "Lorem")。词典也不做 trim()——因为最后一行就是一个空格 token,trim 掉会让所有词挤在一起。

解码器还额外输出 charFrames(每个字符对应的时间步下标)和按空格切分出的词级 token,供 PDF 文本层精确定位每个字。

识别输入被压到 48px 高后,小字号文档是最难啃的场景:

MakeACopy端侧OCR小字号文档识别测试图像:PaddleOCR识别管线在48px输入下的极限场景

四、语言路由:一张表决定用哪个模型

9 种识别模型不可能全加载(APK 体积和内存都扛不住),所以 PaddleLanguageRouter.java 用静态路由表做"语言码 → 模型 key"的解析。

9 个模型 key 与优先级(L55-L58):

模型 key 覆盖语言 对应资产文件
en 英语 en_PP-OCRv5_mobile_rec.ort
latin 德/法/西/意/葡/荷/波兰等拉丁语系 latin_..._rec.ort
eslav 俄语、乌克兰语等 eslav_..._rec.ort
cyrillic 保加利亚语、马其顿语等西里尔 cyrillic_..._rec.ort
arabic 阿拉伯语、波斯语、乌尔都语 arabic_..._rec.ort
devanagari 印地语、尼泊尔语 devanagari_..._rec.ort
th 泰语 th_..._rec.ort
el 希腊语 el_..._rec.ort
zh 中/日/韩(基础大模型) PP-OCRv5_mobile_rec.ort

路由规则(resolveRecModel L203-L227):接受 Tesseract 风格语言码(如 deu+eng),按 + , ; 分词后查表,命中多个模型时按上表优先级取第一个。例如用户选 deu+eng 时命中 latin 和 en,优先返回 en。

路由机制还有三个进阶设计:

  • 基础模型兜底:zh 指向 16MB 的 PP-OCRv5_mobile_rec.ort,它对拉丁字母、数字和大间距场景的识别更强。当 latin/en 模型对某行置信度低于 0.6(LOW_CONFIDENCE_RETRY_THRESHOLD,见 PaddleResultBuilder.java L151)时,会懒加载基础模型重读该行,且第二次结果必须 ≥0.8 置信度才替换原文——因为跨模型的置信度不可直接比较。
  • Light 精简版适配:bundledModel() 检查 APK 里实际打了哪些模型,精简版只带 latin 时,en 请求会自动回落到它(L196-L201)。
  • LRU 会话缓存:同时存活的识别会话上限 2 个(MAX_LIVE_REC_SESSIONS),带引用计数和 LRU 逐出(PaddleRecOrtRunner.java L449-L466),防止内存被大模型撑爆。

多语言样本是路由正确性的直接验证——同一个阿拉伯语请求会被 ara 映射到 arabic 模型:

MakeACopy端侧OCR阿拉伯语识别评测样例:语言路由将ara映射到arabic识别模型

五、布局与后处理:读对顺序比认对字更关键

识别结果不能简单拼接。PaddleResultBuilder.java 的 build() 负责最后拼装:

  • 行分组:Quad 按中心 Y 聚类(容差 = 0.6 × 中位行高),行内按 X 排序,形成阅读顺序;首字母下沉(drop cap)这种超高框会改用顶边锚定,避免把相邻两行"吸"到一起。
  • 并行识别:4 个线程池(PARALLEL_RECOGNITION_THREADS)同时读各行的 Quad,长行优先派发;每个 ORT 会话只开 1 个线程——实测在 Pixel 7a 上比"半核多线程"快约 25%(一页 A4 从 5.6-6.6s 降到 4.5-5.0s)。
  • RTL 双向排版:按 Codepoint 统计判断一行是否为右起语言(阿拉伯、波斯等),整行按右→左输出,但内嵌的拉丁串保持自身顺序。
  • 竖排 CJK:当高框 Quad 占比超过 50%,判定为日/中竖排版式(如 horizontal_jpn 评测条),改为按列分组(右→左、列内自上而下),Crop 还会做 0°/90°/180° 三个旋转候选,用置信度投票选出正确朝向。

六、模型资产:校验、缓存与"只许 .ort"

所有模型资产打包在 app/src/main/assets/paddleocr/v5/,首次使用由 PaddleAssets.java 解压到应用缓存目录,并做三重保障:

  • 词典文件按 SHA256SUMS 逐字节校验 SHA-256,不匹配即重新解压并报错;
  • 缓存文件若哈希不符会自动清除重来;
  • rejectOnnxAssetsOrThrow() 硬性禁止任何 .onnx 资产进入管线——项目统一使用经过算子裁剪的 .ort(基础优化版,算子集更小,见 paddleocr_v5.required_operators.config)。

七、总结:端侧 OCR 的三个设计支点

回顾整条 MakeACopy PaddleOCR ONNX 管线,它的工程价值集中在三点:

  1. 检测与识别分离 + 按需加载:一个小 det 模型通吃所有语言,识别模型按语言路由懒加载,LRU 限制会话数,端侧内存可控;
  2. CTC 解码的防御式实现:blank 槽对齐、Softmax 兼容、词级帧映射,每一处都对应真实踩过的坑;
  3. 置信度驱动的二次推理:低置信行回退基础模型重读,用极小的额外代价换来明显更高的端到端准确率。

想继续深挖,建议从 app/src/main/java/de/schliweb/makeacopy/utils/ocr/paddle/ 目录下的 PaddleOcrEngine(总调度)入手,单测目录 app/src/test/java/de/schliweb/ 中也有针对 CTC 解码、语言路由的独立测试,能帮你快速验证每一环的行为。

登录后查看全文
makeacopy