端侧OCR推理全解析:MakeACopy的PaddleOCR ONNX管线、CTC解码与语言路由实现原理
端侧OCR推理全解析:MakeACopy的PaddleOCR ONNX管线、CTC解码与语言路由实现原理
MakeACopy 是一款开源的 Android 文档扫描应用,它的核心亮点在于:OCR 全程端侧推理——手机离线运行 PaddleOCR v5 的 ONNX 模型(由 ONNX Runtime 执行),不上传云端、不做任何跟踪。对新手来说,"一张照片如何变成带坐标的文本"可能很抽象,本文就用这条 PaddleOCR ONNX 管线为主线,把 DB 文本检测、CTC 贪心解码、多语言模型路由 三大核心机制讲透,并指出每个环节在源码中的具体位置。
一、OCR 管线全景:从照片到可搜索文本
MakeACopy 的 OCR 引擎由 PaddleOcrEngine.java 统一调度,一次 run(bitmap) 调用依次经过五步:
- 语言路由:把用户选的语言码解析成识别模型 key(详见第四节);
- 文本检测:
det.ort输出概率图 → DB 后处理得到文字行的四边形(Quad); - 逐行裁剪:按四边形从原图裁出文本条;
- 字符识别:每条文本条送入按语言选定的
rec.ort,输出时间步 logits; - CTC 解码 + 布局重建:把 logits 解成文字,再按行分组、处理右起语言、输出带坐标的词表。
这套管线可以离线处理各种真实场景的文档,例如双栏排版、小字号报纸等:
(评测样例位于 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)贪心解码:
- 对每个时间步取 argmax(概率最大的字符类);
- 合并相邻重复:连续的同一个 token 只保留一个(模型用重复帧"拉长"字符,属于正常行为);
- 丢弃 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 高后,小字号文档是最难啃的场景:
四、语言路由:一张表决定用哪个模型
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 模型:
五、布局与后处理:读对顺序比认对字更关键
识别结果不能简单拼接。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 管线,它的工程价值集中在三点:
- 检测与识别分离 + 按需加载:一个小 det 模型通吃所有语言,识别模型按语言路由懒加载,LRU 限制会话数,端侧内存可控;
- CTC 解码的防御式实现:blank 槽对齐、Softmax 兼容、词级帧映射,每一处都对应真实踩过的坑;
- 置信度驱动的二次推理:低置信行回退基础模型重读,用极小的额外代价换来明显更高的端到端准确率。
想继续深挖,建议从 app/src/main/java/de/schliweb/makeacopy/utils/ocr/paddle/ 目录下的 PaddleOcrEngine(总调度)入手,单测目录 app/src/test/java/de/schliweb/ 中也有针对 CTC 解码、语言路由的独立测试,能帮你快速验证每一环的行为。


