ocr_platform/ocr_tools/mineru_vl_tool

MinerU vLLM 批量处理工具

基于 MinerU demo.py 框架的批量文档处理工具，支持 PDF 和图片文件的批量处理。

📚 详细文档：更多技术文档、环境配置、处理流程等，请查看 docs/mineru/

功能特性

• ✅ 统一输入接口：支持 PDF 文件、图片文件、图片目录、文件列表（.txt）、CSV 文件
• ✅ 自动判断输入类型：根据输入路径自动识别文件类型并处理
• ✅ 页面范围支持：PDF 文件和图片目录支持指定页面范围（如 1-5,7,9-12）
• ✅ 成功判断优化：基于输出文件存在性判断处理是否成功
• ✅ 数字标准化：自动将全角数字转换为半角（可选）
• ✅ Dry run 模式：验证配置和输入，不执行实际处理
• ✅ 调试模式：保存中间结果（middle.json, model.json）
• ✅ 进度显示：实时显示处理进度和统计信息

安装依赖

# 安装 MinerU
pip install mineru

# 安装其他依赖
pip install loguru tqdm pypdfium2

使用方法

基本用法

# 处理单个PDF文件
python main.py --input document.pdf --output_dir ./output

# 处理图片目录
python main.py --input ./images/ --output_dir ./output

# 处理文件列表
python main.py --input file_list.txt --output_dir ./output

# 处理CSV文件（失败的文件）
python main.py --input results.csv --output_dir ./output

高级用法

# 指定页面范围（PDF或图片目录）
python main.py --input document.pdf --output_dir ./output --pages "1-5,7"

# 只处理前10页（PDF或图片目录）
python main.py --input document.pdf --output_dir ./output --pages "-10"

# 从第5页到最后（PDF或图片目录）
python main.py --input document.pdf --output_dir ./output --pages "5-"

# 仅验证配置（dry run）
python main.py --input document.pdf --output_dir ./output --dry_run

# 使用 DEBUG 日志级别获取详细错误信息和中间结果
python main.py --input document.pdf --output_dir ./output --log_level DEBUG

# 指定服务器地址
python main.py --input document.pdf --output_dir ./output --server_url http://10.192.72.11:20006

# 调整批次大小
python main.py --input ./images/ --output_dir ./output --batch_size 4

# 禁用数字标准化
python main.py --input document.pdf --output_dir ./output --no-normalize

参数说明

输入输出参数

• --input, -i: 输入路径（必需）

  • PDF 文件：自动转换为图片处理
  • 图片文件：直接处理
  • 图片目录：扫描所有图片文件
  • 文件列表（.txt）：每行一个文件路径
  • CSV 文件：读取失败的文件列表

• --output_dir, -o: 输出目录（必需）

MinerU vLLM 参数

• --server_url: MinerU vLLM 服务器地址（默认: http://127.0.0.1:20006）
• --timeout: 请求超时时间，秒（默认: 300）
• --pdf_dpi: PDF 转图片的 DPI（默认: 200）

处理参数

• --batch_size: 批次大小（默认: 1）
• --pages, -p: 页面范围（PDF和图片目录有效）
  • 格式："1-5,7,9-12"（第1-5页、第7页、第9-12页）
  • "1-"：从第1页到最后
  • "-10"：前10页（可用于测试，类似之前的 test_mode）
• --collect_results: 收集处理结果到指定CSV文件

功能开关

• --no-normalize: 禁用数字标准化（默认启用）
• --dry_run: 仅验证配置，不执行处理

日志参数

• --log_level: 日志级别（DEBUG, INFO, WARNING, ERROR，默认: INFO）
• --log_file: 日志文件路径

输出格式

输出目录结构（兼容 MinerU demo.py）：

output_dir/
├── filename.md              # Markdown 内容
├── filename.json            # Content list JSON
├── filename_layout.pdf      # 布局边界框（始终保存）
├── filename_middle.json     # Middle JSON（仅 log_level=DEBUG 时保存）
├── filename_model.json      # 模型输出（仅 log_level=DEBUG 时保存）
└── images/                  # 提取的图片
    └── filename.png

成功判断标准

处理成功的判断标准：

• 输出目录中存在对应的 .md 文件
• 输出目录中存在对应的 .json 文件

如果两个文件都存在，则认为处理成功。

统计信息

处理完成后会显示：

• 文件统计：总文件数、成功数、失败数、跳过数
• 内容提取：提取的块总数、各类型块数量
• 性能指标：总耗时、吞吐量、平均处理时间

结果会保存到 {output_dir}_results.json 文件中。

示例

示例1：处理PDF文件

python main.py \
  --input /path/to/document.pdf \
  --output_dir ./output \
  --pages "1-10" \
  --server_url http://10.192.72.11:20006 \
  --log_level DEBUG

示例2：批量处理图片目录

python main.py \
  --input /path/to/images/ \
  --output_dir ./output \
  --batch_size 4 \
  --log_file ./processing.log

示例3：Dry run 验证

python main.py \
  --input /path/to/document.pdf \
  --output_dir ./output \
  --dry_run

注意事项

1. 服务器连接：确保 MinerU vLLM 服务器正在运行并可访问
2. 内存使用：处理大文件时注意内存使用情况
3. 文件命名：PDF 页面会转换为 filename_page_001.png 格式
4. 页面范围：页面编号从 1 开始（不是 0）

故障排查

问题：连接服务器失败

• 检查服务器地址是否正确
• 确认服务器是否正在运行
• 检查网络连接和防火墙设置

问题：处理失败

• 使用 --log_level DEBUG 获取详细错误信息和 traceback，同时会保存中间结果（middle.json, model.json）
• 检查输出目录权限
• 查看日志文件获取更多信息

问题：输出文件不存在

• 检查处理是否真的失败（查看错误信息）
• 确认输出目录路径正确
• 检查磁盘空间是否充足

相关工具

• ocr_utils: OCR 工具包，提供 PDF 处理、文件处理等功能
• MinerU: 文档解析框架