NDLOCR CLI：高效图像文本识别工具使用指南

一、核心功能解析

NDLOCR CLI 是一款专业的图像文本识别工具，能够将图像文件中的文字信息转化为可编辑的文本数据（即推理处理），并提供对识别结果的准确性评估功能。该工具通过模块化设计，实现了从图像预处理到文本输出的完整工作流，特别适合处理古籍扫描件、印刷文档等复杂场景的批量识别任务。

1.1 核心模块架构

工具的核心功能由以下模块协同实现：

• 页面处理模块：负责图像的前期处理，包括页面分割（源码：submodules/separate_pages_mmdet）和倾斜校正（源码：submodules/deskew_HT），为后续识别提供高质量图像输入。
• 布局分析模块：识别文档中的区域布局结构（源码：submodules/ndl_layout），区分标题、正文、图片等不同内容区域。
• 文字识别模块：核心识别引擎，实现文本内容的提取（源码：submodules/text_recognition_lightning），支持多语言文本识别。
• 阅读顺序模块：分析文本的逻辑阅读顺序（源码：submodules/reading_order），确保输出文本符合自然阅读习惯。
• 注音处理模块：针对东亚语言特性，提供注音（如日文假名）的识别与标注（源码：submodules/ruby_prediction）。
• 评估模块：对识别结果进行量化评估（源码：submodules/ocr_line_eval_script），输出准确率、召回率等关键指标。

1.2 典型应用场景

• 古籍数字化：批量处理扫描的古籍图像，将其转化为可检索的文本数据
• 印刷文档电子化：快速将纸质文档转化为可编辑的数字文本
• 多语言文档处理：支持包含多种语言混合的复杂文档识别
• 学术研究辅助：帮助研究人员快速提取文献中的关键信息

二、快速上手指南

2.1 环境准备

📌 前置要求：Python 3.8+ 环境，已安装 git 和相关依赖库

# 克隆项目仓库
git clone https://gitcode.com/gh_mirrors/nd/ndlocr_cli
cd ndlocr_cli

# 安装依赖包
pip install -r requirements.txt

2.2 基础推理命令

命令功能：执行图像文本识别
完整命令示例：python main.py infer ./input_images ./output_results -s s

• infer：指定执行推理功能
• ./input_images：输入图像目录（存放待识别的图像文件）
• ./output_results：输出结果目录（保存识别后的文本及中间结果）
• -s s：设置推理模式为单张图片处理（可选参数，默认为批量处理）

💡 技巧提示：对于大量图像文件，建议使用批量处理模式，并确保输入目录中仅包含需要识别的图像文件，避免非图像文件干扰处理流程。

2.3 评估功能使用

命令功能：评估识别结果准确性
完整命令示例：python main.py evaluate ./test_data ./ground_truth -c eval_config.yml

• evaluate：指定执行评估功能
• ./test_data：包含待评估图像及识别结果的目录
• ./ground_truth：包含标准答案的目录（用于计算准确率）
• -c eval_config.yml：指定评估配置文件路径

三、深度配置说明

3.1 推理配置（config.yml）

配置项	默认值	功能说明	调整建议
inference_mode	batch	推理模式（batch：批量处理，single：单张处理）	处理大量文件时使用batch模式提高效率
output_format	xml	输出格式（xml：结构化标记，txt：纯文本）	需要保留排版信息时选择xml格式
save_intermediate	false	是否保存中间处理结果	调试或需要中间图像时设为true
language	ja	主要识别语言（ja：日语，zh：中文，en：英文）	根据文档主要语言设置，混合语言可保持默认
line_separation_threshold	0.8	行分隔阈值	文本行间距较小时可适当降低该值

📌 重点标记：若出现识别结果文本行混乱的问题，可检查 line_separation_threshold 参数，调整文本行的识别灵敏度。

3.2 评估配置（eval_config.yml）

配置项	默认值	功能说明	调整建议
eval_mode	page	评估模式（page：按页面，line：按行级别）	需要精细评估时使用line模式
metrics	accuracy,recall	评估指标（准确率、召回率等）	根据具体需求添加或移除指标
save_report	true	是否保存评估报告	需长期跟踪模型性能时设为true
tolerance	0.05	容错率（字符匹配误差允许范围）	对识别精度要求高时降低该值

💡 技巧提示：评估报告默认保存为CSV格式，可使用Excel或Python数据分析库进行进一步分析，识别准确率低于预期时，可检查输入图像质量或调整推理参数。

3.3 常见问题排查

1. 识别速度慢：

   • 检查是否启用了不必要的中间结果保存
   • 尝试降低图像分辨率或减少并发处理数量

2. 识别准确率低：

   • 检查输入图像是否清晰，模糊图像建议先进行预处理
   • 确认配置文件中的语言设置与实际文档语言匹配
   • 尝试调整布局分析相关参数

3. XML输出格式异常：

   • 检查是否正确安装了所有依赖库
   • 确认输入图像尺寸在支持范围内（建议不超过4000x3000像素）

通过灵活配置和合理使用各功能模块，NDLOCR CLI 能够满足不同场景下的图像文本识别需求，为文档数字化处理提供高效可靠的解决方案。