NDLOCR CLI 项目使用指南

核心功能解析

💡 本节将带你了解NDLOCR CLI的核心能力与组件构成，帮助你快速把握项目整体架构。

项目核心组件关系

NDLOCR CLI采用模块化设计，各功能模块通过主程序协调工作，形成完整的OCR处理流程。核心组件包括：

• 主程序模块：main.py 作为入口点，负责解析命令行参数并调度各处理流程
• 核心处理模块：cli/core/ 包含推理(inference.py)和评估(evaluate.py)的核心逻辑
• 处理流程模块：cli/procs/ 实现具体处理步骤，如页面分离(page_separation.py)、倾斜校正(page_deskew.py)、布局提取(layout_extraction.py)等
• 配置模块：config.yml 和 eval_config.yml 分别控制推理和评估过程的参数
• 子模块：submodules/ 包含各类专业处理功能，如文字识别(text_recognition_lightning/)、读取顺序识别(reading_order/)等

三大核心功能

1. 全流程OCR处理

实现从图像输入到文本输出的完整流程，包括页面分离、倾斜校正、布局分析、文字识别等步骤。核心处理类 Inference（位于inference.py）通过 run() 方法启动处理流程，并提供 _infer() 和 _infer_ruby_only() 等方法支持不同场景需求。

2. 灵活的部分执行

支持指定处理步骤，可通过命令行参数控制执行范围。例如仅进行注音推定或读取顺序识别，无需运行完整流程。这一功能通过 _create_proc_list() 方法动态生成处理流程列表实现。

3. 多维度评估能力

提供对OCR结果的量化评估，包括准确率、召回率等指标。评估功能由 evaluate.py 中的 Evaluate 类实现，通过 run() 方法执行评估流程。

快速上手指南

💡 按照以下步骤，即使是OCR新手也能在5分钟内完成首次运行。所有命令均在项目根目录执行。

5分钟启动流程

📌 步骤1：环境准备

首先克隆项目并安装依赖：

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

📌 步骤2：准备测试数据

在项目根目录创建输入输出文件夹：

mkdir -p input_data output_results

将测试图片放入 input_data 文件夹。

📌 步骤3：执行基础OCR处理

python main.py infer input_data output_results -c config.yml

命令行操作全解

NDLOCR CLI提供丰富的命令行选项，基本语法为：

python main.py [命令] [输入目录] [输出目录] [选项]

场景1：完整流程处理

python main.py infer ./test_images ./output -c config.yml -s all

参数说明：

• -c config.yml：指定配置文件
• -s all：执行所有处理步骤

场景2：仅进行注音推定

python main.py infer ./japanese_texts ./ruby_results -c config.yml --ruby-only

参数说明：

• --ruby-only：仅执行注音推定处理

场景3：评估模型性能

python main.py evaluate ./test_data ./eval_results -e eval_config.yml

参数说明：

• evaluate：切换到评估模式
• -e eval_config.yml：指定评估配置文件

常见故障排除

错误现象	可能原因	解决命令
依赖包缺失	未安装或版本不匹配	pip install -r requirements.txt
配置文件错误	配置参数无效或路径错误	python main.py check-config config.yml
输入文件格式错误	不支持的图像格式	convert input.jpg -resize 2000x2000 output.jpg（使用ImageMagick转换）

个性化配置指南

💡 配置文件是定制NDLOCR行为的核心，通过调整参数可以显著提升特定场景下的处理效果。

核心配置项对比

配置项	默认值	优化建议	适用场景
line_order	false	true	处理多列文本或复杂排版
ruby_read	false	true	处理日文文本（含注音需求）
add_title_author	false	true	学术论文或书籍封面处理
max_image_size	2000	4000	高分辨率文档处理
confidence_threshold	0.7	0.5	低质量图像识别

配置模板及自定义范围

以下是 config.yml 的核心配置模板，标注了可自定义的关键参数范围：

# 处理流程配置
process:
  page_separation: true         # 是否启用页面分离
  deskew: true                  # 是否启用倾斜校正
  layout_extraction: true       # 是否启用布局提取
  line_ocr: true                # 是否启用行识别
  line_order: false             # [0-1] 是否启用读取顺序识别
  ruby_read: false              # [0-1] 是否启用注音推定
  add_title_author: false       # [0-1] 是否启用标题作者识别

# 模型参数配置
model:
  text_recognition:
    confidence_threshold: 0.7   # [0.1-0.9] 识别置信度阈值
    max_batch_size: 8           # [1-32] 批处理大小
  layout:
    min_area: 100               # [50-500] 最小区域面积阈值

# 输出配置
output:
  save_intermediate: false      # 是否保存中间结果
  image_format: "png"           # 输出图像格式
  xml_format: "ndlocr"          # XML输出格式
  text_encoding: "utf-8"        # 文本编码方式

高级参数调优技巧

📌 性能与质量平衡

• 提高 max_batch_size（如16）可加速处理，但会增加内存占用
• 降低 confidence_threshold（如0.5）可提高召回率，但可能增加错误识别

📌 特定场景优化

• 处理古籍扫描件：启用 deskew 和 line_order，设置 max_image_size: 4000
• 处理多语言文档：禁用 ruby_read，调整 text_recognition 模型参数
• 批量处理：启用 save_intermediate: true，便于中断后恢复处理

通过合理配置这些参数，NDLOCR CLI可以适应从简单到复杂的各种OCR应用场景，满足不同用户的个性化需求。