NDLOCR CLI：专业文档识别与处理工具使用指南

核心能力概览

理解文档智能处理全流程

NDLOCR CLI是一套基于深度学习的文档智能处理系统，能够将扫描图像转换为结构化文本数据。其核心工作流遵循专业文档处理逻辑：图像输入→[页面分割]→[倾斜校正]→[布局提取]→[文字识别]→[阅读顺序排序]→结果输出。这套流程模拟了人工处理文档的完整步骤，从物理页面分离到最终文本内容的智能组织。

掌握多场景应用能力

该工具具备三大核心应用场景：古籍数字化（支持竖排文字与注音识别）、办公文档转换（批量处理会议纪要与报告）、印刷资料归档（学术论文与历史文献的结构化存储）。特别适合需要处理大量扫描文档的图书馆、档案馆及研究机构使用，通过自动化处理显著降低人工转录成本。

快速上手流程

完成环境准备工作

首先需要克隆项目代码库并安装依赖。打开终端执行以下命令：

git clone https://gitcode.com/gh_mirrors/nd/ndlocr_cli
cd ndlocr_cli
pip install -r requirements.txt

🔧 小贴士：推荐使用Python 3.8+环境，并建议通过虚拟环境隔离依赖，避免版本冲突。

执行首次推理任务

使用默认配置处理单张图像的基本命令格式如下：

python main.py infer ./input_images ./output_results -s s

其中./input_images是存放待处理图片的目录，./output_results将保存处理结果，-s s表示使用快速处理模式。处理完成后，可在输出目录中查看生成的文本文件或XML格式结果。

⚠️ 注意事项：首次运行会自动下载模型文件（约2GB），请确保网络通畅并有足够存储空间。

配置体系详解

配置文件参数调优

NDLOCR CLI提供两套核心配置文件，分别针对推理和评估场景进行优化：

配置项类别	config.yml（推理配置）	eval_config.yml（评估配置）
核心功能	定义图像处理流程与模型参数	设置评估指标与对比标准
输出控制	指定结果格式（文本/XML）与保存路径	配置评估报告生成方式
性能参数	调整批处理大小与推理精度	设置评估样本抽样比例
中间结果	控制是否保存分割/校正后的图像	配置错误案例可视化选项

定制化配置策略

当需要处理特殊类型文档时，可通过修改配置文件实现定制化处理。例如处理古籍扫描件时，建议在config.yml中开启vertical_text: true选项；处理低分辨率图像时，可将enhance_quality参数设置为high以提升识别效果。所有配置项均提供注释说明，可直接在配置文件中查阅参数含义。

功能模块解析

实现页面预处理操作

预处理模块包含两大关键功能：页面分割（将多页扫描图像分离为单页）和倾斜校正（自动修正扫描文档的角度偏差，确保文字水平）。这些操作位于submodules/separate_pages_mmdet和submodules/deskew_HT目录中，通过计算机视觉算法实现自动化处理，特别适用于批量处理扫描质量参差不齐的文档。

执行文字识别与排版分析

文字识别核心模块由submodules/text_recognition_lightning提供支持，能够识别多语言文本及特殊符号。布局提取功能（submodules/ndl_layout）则负责分析文档中的标题、段落、表格等元素的空间分布。典型应用场景：学术论文处理时，系统可自动区分标题、摘要、正文等结构，生成带有层级关系的结构化文本。

优化阅读顺序与注音识别

阅读顺序模块（submodules/reading_order）解决了复杂排版文档的文字流排序问题，确保输出文本符合人类阅读习惯。注音识别功能（submodules/ruby_prediction）则专门针对中日文文献中的注音符号进行识别，这对古籍数字化项目尤为重要。操作示例：处理日文古籍时，启用ruby_recognition: true参数可同时提取汉字与假名注音。

扩展应用指南

构建批量处理工作流

对于需要定期处理大量文档的场景，建议结合脚本实现自动化工作流。例如，创建如下bash脚本实现每日定时处理：

#!/bin/bash
INPUT_DIR="/daily_scans"
OUTPUT_DIR="/processed_results/$(date +%Y%m%d)"
python main.py infer $INPUT_DIR $OUTPUT_DIR -c ./custom_config.yml

将此脚本添加到crontab即可实现无人值守的批量处理。

集成评估与质量控制

评估工具（submodules/ocr_line_eval_script）提供专业的识别质量分析功能，通过对比人工标注数据与系统输出，生成准确率、召回率等关键指标。建议在大规模处理前，使用少量样本运行评估命令：

python main.py eval ./test_images ./ground_truth ./eval_reports

根据评估报告调整配置参数，优化处理效果后再进行全量处理。

探索高级应用场景

NDLOCR CLI的模块化设计使其具备良好的扩展性。开发者可通过修改cli/procs目录下的处理流程代码，实现特定领域的定制化需求。例如，通过扩展line_attribute.py可添加自定义文本属性识别，或修改page_separation.py以适应特殊格式的文档分割需求。项目的开源特性也鼓励社区贡献新的处理模块与模型。