揭秘NDLOCR-Lite内部机制:布局识别、字符识别与阅读顺序三大模块全解析
揭秘NDLOCR-Lite内部机制:布局识别、字符识别与阅读顺序三大模块全解析
NDLOCR-Lite 是国立国会图书馆开源的一款轻量级 OCR(光学字符识别)工具,它由布局识别、字符识别(文字列识别)、阅读顺序整理三大核心模块组成,无需 GPU,在普通笔记本上即可把图书、杂志的扫描图像批量转换成文本。本文带你深入源码,彻底搞懂这三大模块是如何协同工作的。
下面这段动图展示的是 NDLOCR-Lite 的「屏幕捕获」模式:直接在桌面上截取图书页面,不经过图像文件就完成文字化。
整体架构一览:一张图看懂处理流水线
NDLOCR-Lite 的核心逻辑都汇聚在主入口 src/ocr.py 中,处理流程可以概括为:
输入图像 → 布局识别(DEIMv2)→ 逐行切图 + 字符识别(PARSeq 级联)→ 阅读顺序重排(XY-Cut)→ 输出 XML / JSON / TXT
三大模块对应的关键文件如下:
| 模块 | 实现文件 | 模型文件 |
|---|---|---|
| 布局识别 | src/deim.py | src/model/deim-s-1024x1024.onnx |
| 字符识别 | src/parseq.py | src/model/ 下 3 个 PARSeq ONNX 模型 |
| 阅读顺序 | src/reading_order/ | 纯算法实现(XY-Cut),无需模型 |

上图是布局识别的可视化结果(--viz True 开启):红框是识别出的文字行,黑框是版面区块(text_block)。模型能准确区分正文、标题、图注等不同元素,这正是后续精确 OCR 的基础。
模块一:布局识别 —— DINOv3 蒸馏驱动的 DEIMv2 检测器
布局识别回答的问题是:"这一页上,文字都在哪里?每一行属于什么类型?"
技术选型
NDLOCR-Lite 采用的是 DEIMv2(Real-Time Object Detection Meets DINOv3)检测框架,并做了一系列"轻量化"定制:
- 骨干网络使用 DINOv3 蒸馏出的 ViT-Tiny 模型,参数量小,CPU 也能跑得飞快。训练配置见 train/deimv2code/part2/configs/ndl_deimv2/deimv2_dinov3_s_coco_r4_800.yml;
- 训练完成后导出为 ONNX 格式,运行时通过 ONNX Runtime 的
CPUExecutionProvider推理(见 src/deim.py 的create_session),GPU 环境也可切换到CUDAExecutionProvider。
17 个版面类别
模型一次推理输出 17 种版面元素,类别定义在 src/config/ndl.yaml:
text_block(文字块)、line_main(正文行)、line_title(标题行)、line_caption(图注行)等;block_fig(图片)、block_table(表格)、block_ad(广告)等非文字区块。
一个容易被忽略的细节:检测模型还会额外输出每个文本行的预测字符数(pred_char_count),这个数字将直接决定下一环节选用哪个识别模型——这就是"级联识别"的关键。
模块二:字符识别 —— PARSeq 三级级联策略
字符识别(文字列识别)模块由 src/parseq.py 实现,基于 PARSeq(Permuted Autoregressive Sequence)场景文字识别模型。它的巧妙之处不在于"一个模型打天下",而在于三个大小不同的模型分级调度。
为什么要三个模型?
观察 src/model/ 目录,会发现三个 PARSeq 模型:
| 模型 | 输入宽度 | 最大识别字符数 | 适用场景 |
|---|---|---|---|
parseq-ndl-24x256-30-...onnx |
256 | 30 字符 | 短行:标题、图注、段落末行 |
parseq-ndl-24x384-50-...onnx |
384 | 50 字符 | 中等长度的行 |
parseq-ndl-24x768-100-...onnx |
768 | 100 字符 | 完整的长正文行 |
字符数越少,模型输入越短,推理越快。主流程中的 process_cascade 函数会利用布局识别阶段预测的字符数,把每一行分派给最合适的模型:短行走 30 字符小模型,长行才动 100 字符大模型。
这套"按行长度分级"的策略,是 NDLOCR-Lite 在纯 CPU 环境下仍能保持高速的秘诀之一。
字符集与手写文字支持
识别用的字符表定义在 src/config/NDLmoji.yaml,覆盖日文假名、汉字、全半角符号等数千个字符。自 v1.2 起,模型在"手書き3(tegaki3)"手写数据上重新训练,对手写文字的识别能力也显著增强。下图就是手写横排文字的识别可视化结果:
进阶:竖中横(Tate-Chuu-Yoko)修正
日语报纸中常见"竖排里嵌横排"的排版(竖中横)。NDLOCR-Lite 提供了 src/tcy_wrapper.py 包装器,它能检测竖排行中混入的横排小段并单独识别,命令行加上 --enable-tcy 参数即可启用。
模块三:阅读顺序 —— 用 XY-Cut 算法还原人类阅读路径
识别出所有文本行后,还有一个关键问题:输出的文字应该按什么顺序排列? 多栏排版、表格混排的页面里,简单的"从上到下、从左到右"显然是不行的。
NDLOCR-Lite 复用了 NDLOCR 中成熟的 XY-Cut 算法,代码位于 src/reading_order/:
- block_xy_cut.py:核心递归切分逻辑。它把页面看成一个方块,先在 X 方向和 Y 方向寻找"最大空白间隔"(栏与栏、段与段之间的空隙)作为切割线,像切蛋糕一样递归切分,直到每个区域只剩一行文本;
- eval_xml.py:对检测结果做 XML 层面的整理,给每行写入最终的
ORDER属性。

上图这类"双页跨栏 + 表格 + 正文"的复杂版面,正是 XY-Cut 的用武之地:它能识别出左右两大栏先分别递归处理,再合并排序,从而保证最终文本顺序与人类阅读顺序一致。
竖排页面的顺序翻转
还有一个贴心的细节:在 src/ocr.py 中,程序会统计竖排行(高大于宽)的占比,如果竖排行超过 50%,就自动把整页文本顺序反转——因为日文书籍竖排是从右向左读的。
快速上手:三步跑通 OCR
命令行方式体验最直观(需 Python 3.10+):
git clone https://gitcode.com/gh_mirrors/nd/ndlocr-lite
cd ndlocr-lite
pip install -r requirements.txt
cd src
python3 ocr.py --sourceimg 你的图片.jpg --output tmpdir --viz True
常用参数速查:
--sourcedir:批量处理整个目录的图像;--sourceimg:处理单张图像;--output:结果输出目录(生成.txt/.xml/.json三种格式);--viz True:输出带蓝色/红色识别框的可视化图,方便核对布局识别质量;--device cuda:在装有 onnxruntime-gpu 的 GPU 机器上加速推理;--json-only:仅输出 JSON 格式。
如果你不熟悉命令行,官方还提供了基于 Flet 的桌面 GUI(ndlocr-lite-gui/),支持 Windows / macOS / Linux,操作就是"选文件 → 点 OCR → 看预览",还支持 PDF 输入和屏幕捕获。
总结:三大模块如何各司其职
- 布局识别(DEIMv2):轻量目标检测,找出"文字在哪、是什么类型、大约多少字";
- 字符识别(PARSeq 级联):按预测字符数调度 3 个规格的小模型,快准狠地逐行读字;
- 阅读顺序(XY-Cut):纯算法递归切分,还原多栏、竖排、表格混排下的正确阅读顺序。
三者都以 ONNX + 纯 CPU 的方式运行,这就是 NDLOCR-Lite 敢称"轻量"的底气。如果你想进一步定制,官方在 train/README.md 中完整公开了 DEIMv2 与 PARSeq 的再训练和 ONNX 导出流程,活字识别性能评估数据也公布在 evaluation_jptype.csv,方便你验证或扩展自己的模型。

