NDLOCR CLI 项目使用指南

2026-04-01 09:10:43作者：戚魁泉Nursing

1 核心功能概览：NDLOCR CLI 能力解析

NDLOCR CLI 是一款专业的文档识别工具，提供从图像到文本的完整处理流程。您可以通过命令行接口轻松实现文档的页面分割、倾斜校正、文字识别等功能，同时支持对识别结果进行专业评估。

1.1 四大核心功能：从图像到文本的全流程处理

NDLOCR CLI 主要提供以下核心功能：

推理处理（将图像转为文本数据的过程）：将输入的图像文件转换为结构化文本数据
评估处理：对识别结果进行准确性评估
多格式输出：支持文本、XML等多种输出格式
模块化架构：可灵活配置各处理模块参数

1.2 核心文件速览：关键文件功能对比

文件路径	功能描述	重要性
main.py	项目主入口文件，执行CLI命令	⭐⭐⭐⭐⭐
config.yml	推理处理配置文件	⭐⭐⭐⭐
eval_config.yml	评估处理配置文件	⭐⭐⭐
requirements.txt	Python依赖包列表	⭐⭐⭐
cli/core/inference.py	核心推理逻辑实现	⭐⭐⭐⭐

[!NOTE] 所有配置文件和核心代码均位于项目根目录下，无需额外配置环境变量即可直接使用。

📌 重点总结

NDLOCR CLI提供从图像到文本的全流程处理能力
main.py是项目的核心入口文件
配置文件分为推理配置(config.yml)和评估配置(eval_config.yml)
模块化设计使功能扩展和参数调整更加灵活
项目依赖通过requirements.txt统一管理

2 快速上手流程：5分钟完成首次推理

2.1 环境准备：从安装到验证

首先需准备Python环境（建议Python 3.7+），然后执行以下步骤：

🔧 步骤1：克隆项目仓库

git clone https://gitcode.com/gh_mirrors/nd/ndlocr_cli
cd ndlocr_cli

🔧 步骤2：安装依赖包

pip install -r requirements.txt

🔧 步骤3：验证安装

python main.py --help

若成功显示帮助信息，则说明环境准备完成。

2.2 基础命令详解：执行首次推理

执行推理处理的基本命令格式如下：

🔧 基础推理命令

python main.py infer <输入目录> <输出目录> -s <处理模式>

其中：

<输入目录>：存放待处理图像的文件夹路径
<输出目录>：保存识别结果的文件夹路径
-s：指定处理模式，"s"表示单张图片处理，"b"表示批量处理

🔧 使用示例

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

2.3 常见问题排查：错误提示与解决方案

错误提示	可能原因	解决方案
`ModuleNotFoundError: No module named 'torch'`	依赖包未安装	执行`pip install -r requirements.txt`
`FileNotFoundError: [Errno 2] No such file or directory: 'input_images'`	输入目录不存在	检查输入目录路径是否正确
`RuntimeError: CUDA out of memory`	GPU内存不足	减小批量处理大小或使用CPU模式

[!NOTE] 如遇到其他错误，请检查config.yml配置是否正确，或查看项目GitHub Issues获取解决方案。

📌 重点总结

环境准备需要克隆仓库并安装依赖
基础推理命令格式为python main.py infer 输入目录输出目录 -s 处理模式
处理模式"s"适用于单张图片，"b"适用于批量处理
常见错误多与环境配置或路径设置有关
遇到问题时可先检查依赖和配置文件

3 深度配置解析：从基础到高级的参数调优

3.1 基础配置项：满足日常需求

config.yml是推理处理的核心配置文件，基础配置项包括：

🔧 推理模式设置

# 推理模式配置
inference:
  mode: "single"  # 推理模式: single(单张)/batch(批量)
  batch_size: 4   # 批量处理大小时的批次大小
  device: "auto"  # 运行设备: auto(自动)/cpu/gpu

🔧 输出格式设置

# 输出格式配置
output:
  format: ["text", "xml"]  # 输出格式: text(文本)/xml/json
  save_intermediate: false # 是否保存中间结果
  intermediate_dir: "./intermediate_results"  # 中间结果保存目录

3.2 高级调优参数：提升识别准确率

对于有特殊需求的用户，可以调整以下高级参数：

🔧 识别精度优化

# 高级识别参数
recognition:
  enable_ensemble: true  # 是否启用集成识别
  confidence_threshold: 0.85  # 置信度阈值
  language: "ja"  # 识别语言: ja(日语)/zh(中文)/en(英文)

🔧 性能优化

# 性能优化参数
performance:
  use_quantization: true  # 是否使用模型量化
  num_workers: 4  # 数据加载线程数
  cache_dir: "./model_cache"  # 模型缓存目录

3.3 推荐配置模板：场景化配置方案

针对不同使用场景，以下是推荐的配置模板：

🔧 快速处理配置（优先速度）

inference:
  mode: "batch"
  batch_size: 8
  device: "gpu"
performance:
  use_quantization: true
  num_workers: 8
output:
  format: ["text"]
  save_intermediate: false

🔧 高精度配置（优先准确率）

inference:
  mode: "single"
  batch_size: 1
  device: "gpu"
recognition:
  enable_ensemble: true
  confidence_threshold: 0.95
output:
  format: ["text", "xml"]
  save_intermediate: true

[!NOTE] 配置文件修改后无需重启服务，下次执行命令时会自动应用新配置。

📌 重点总结

基础配置项控制推理模式、输出格式等核心功能
高级参数可优化识别准确率和处理性能
配置文件位于项目根目录下的config.yml
不同场景需要不同的配置策略，推荐使用模板进行配置
修改配置后无需重启，立即生效

4 技术模块探秘：NDLOCR CLI 内部架构

4.1 功能模块图谱：各组件协同工作

NDLOCR CLI采用模块化设计，主要包含以下核心模块：

页面处理模块（submodules/separate_pages_mmdet）：负责页面分割
倾斜校正模块（submodules/deskew_HT）：处理图像倾斜问题
布局提取模块（submodules/ndl_layout）：分析文档布局结构
文字识别模块（submodules/text_recognition_lightning）：核心OCR功能
阅读顺序模块（submodules/reading_order）：确定文本阅读顺序
注音推断模块（submodules/ruby_prediction）：处理注音文字识别
评估模块（submodules/ocr_line_eval_script）：评估识别结果

4.2 模块间数据流程：从输入到输出的旅程

图像数据在各模块间的处理流程如下：

原始图像首先进入页面处理模块进行页面分割
分割后的页面传递给倾斜校正模块进行角度调整
校正后的图像送入布局提取模块分析文档结构
提取的文本区域被送入文字识别模块转换为文本
文本结果经阅读顺序模块排序
对需要注音的文本，由注音推断模块处理
最终结果输出为指定格式文件

4.3 自定义扩展：开发新功能模块

如果您需要扩展NDLOCR CLI的功能，可以按照以下步骤开发自定义模块：

🔧 步骤1：创建模块目录

mkdir -p submodules/your_module_name
touch submodules/your_module_name/__init__.py

🔧 步骤2：实现模块接口

# submodules/your_module_name/processor.py
class YourProcessor:
    def __init__(self, config):
        self.config = config
        
    def process(self, input_data):
        # 实现处理逻辑
        return processed_data