MinerU/zhch

MinerU vLLM 批量处理系统

基于 MinerU 2.5+ 的文档解析和批量处理系统，支持 PDF 和图像文档的智能解析。

1. 环境配置

1.1 代码获取

git clone https://gitee.com/zhch158_admin/MinerU.git -c user.name=zhch158_admin -c user.email=zhch158@sina.com
cd MinerU
git config --local user.name "zhch158_admin"
git config --local user.email "zhch158@sina.com"

1.2 Python 环境安装

# 创建 conda 环境
conda create -n mineru2 python=3.12
conda activate mineru2

# 安装 MinerU 核心
pip install -U "mineru[core]" -i https://mirrors.aliyun.com/pypi/simple

# 开发模式安装（推荐）
uv pip install -U -e '.[all]'

# 安装额外依赖
pip install PyMuPDF loguru tqdm pillow

# 检查 PyTorch 版本
python -c "import torch; print(f'PyTorch: {torch.__version__}, CUDA: {torch.cuda.is_available()}')"

1.3 模型下载

# 从 ModelScope 下载模型权重文件
python -m mineru.cli.models_download

# 模型会保存到 $MODELSCOPE_CACHE 目录
# 默认路径: /home/ubuntu/models/modelscope_cache/models/OpenDataLab/MinerU2___5-2509-1___2B

1.4 环境变量配置

创建 .env 文件或设置环境变量：

# .env 文件内容
NLTK_DATA="/home/ubuntu/nltk_data"
HF_HOME="/home/ubuntu/models/hf_home"
HF_ENDPOINT=https://hf-mirror.com
HF_HUB_OFFLINE=0
TORCH_HOME="/home/ubuntu/models/torch/"
MODELSCOPE_CACHE="/home/ubuntu/models/modelscope_cache"
USE_MODELSCOPE_HUB=1
CUDA_VISIBLE_DEVICES=0,1,2,3
MINERU_TOOLS_CONFIG_JSON="/home/ubuntu/zhch/MinerU/mineru.json"

2. 服务启动

2.1 vLLM 服务器

# 启动 vLLM 服务器（单GPU）
CUDA_VISIBLE_DEVICES="4" mineru-vllm-server --port 8121 --gpu-memory-utilization 0.3

# 或使用守护进程脚本
./mineru_vllm_daemon.sh start
./mineru_vllm_daemon.sh status
./mineru_vllm_daemon.sh logs

mac OS 用户请使用以下命令启动 vLLM 服务器：

pip install -U "mineru-vl-utils[mlx]"

vllm serve opendatalab/MinerU2.5-2509-1.2B --host 127.0.0.1 --port 8121 \
  --logits-processors mineru_vl_utils:MinerULogitsProcessor --max-model-len 2048

2.2 FastAPI 服务器（可选）

# 启动 FastAPI HTTP 服务
./mineru_fast_api_daemon.sh start

# 访问 API 文档
# http://localhost:8120/docs

3. 使用方式

3.1 命令行调用（官方方式）

Pipeline 后端（传统OCR + 规则）

export MINERU_TOOLS_CONFIG_JSON="/home/ubuntu/zhch/MinerU/mineru.json"

# 处理单个文件
python -m mineru.cli.client -p /path/to/document.pdf -o /path/to/output --lang ch --source modelscope

# 处理目录
python -m mineru.cli.client -p /path/to/images/ -o /path/to/output --lang ch --source modelscope

VLM 后端（视觉语言模型）

# 使用本地 vLLM 引擎
CUDA_VISIBLE_DEVICES=4 python -m mineru.cli.client \
    -p /path/to/document.pdf \
    -o /path/to/output \
    --backend vlm-vllm-engine \
    --gpu-memory-utilization 0.3 \
    --source modelscope

# 使用 HTTP 客户端（连接到 vLLM 服务器）
python -m mineru.cli.client \
    -p /path/to/document.pdf \
    -o /path/to/output \
    --backend vlm-http-client \
    --server-url http://127.0.0.1:8121 \
    --source modelscope

3.2 批量处理脚本

使用增强的批量处理脚本 mineru2_vllm_multthreads.py：

# 基本用法
python mineru2_vllm_multthreads.py \
    --input_dir /path/to/images \
    --output_dir /path/to/output \
    --server_url http://127.0.0.1:8121

# 高级参数
python mineru2_vllm_multthreads.py \
    --input_file /path/to/document.pdf \
    --output_dir /path/to/output \
    --server_url http://127.0.0.1:8121 \
    --batch_size 1 \
    --timeout 300 \
    --debug \
    --test_mode

# 从文件列表批量处理
python mineru2_vllm_multthreads.py \
    --input_file_list /path/to/file_list.txt \
    --output_dir /path/to/output \
    --collect_results /path/to/results.csv

# 从 CSV 文件处理（支持断点续传）
python mineru2_vllm_multthreads.py \
    --input_csv /path/to/processed_files.csv \
    --output_dir /path/to/output \
    --no-normalize  # 禁用金额标准化

3.3 输出结构

output_dir/
├── filename.md                 # Markdown 格式文档内容
├── filename.json               # Content list（结构化内容）
├── filename_layout.pdf         # 布局边界框可视化
├── images/                     # 提取的图片
│   ├── image_0.jpg
│   └── ...
├── filename_results.json       # 处理结果统计
└── processed_files.csv         # 处理状态记录

# 调试模式额外输出：
├── filename_middle.json        # 中间 JSON 数据
├── filename_model.json         # 模型原始输出
└── filename_origin.pdf         # 原始 PDF 文件

4. 功能特性

4.1 支持的文档格式

• PDF 文档：多页 PDF 自动分页处理
• 图像格式：PNG, JPG, JPEG, TIFF, BMP 等
• 批量处理：目录、文件列表、CSV 文件

4.2 解析能力

• 版面分析：自动识别标题、段落、表格、图片等
• 表格识别：复杂表格结构化提取
• 公式识别：数学公式 LaTeX 格式输出
• 多语言支持：中文、英文等多语言文档

4.3 批量处理增强

• 进度显示：实时进度条和处理统计
• 断点续传：支持从中断点继续处理
• 错误处理：详细错误记录和重试机制
• 金额标准化：全角数字转半角数字（财务文档优化）
• 结果收集：自动生成处理结果统计

4.4 部署模式

1. Pipeline 模式：传统 OCR + 规则引擎（快速、轻量）
2. VLM-Transformers 模式：本地 Transformers 推理（慢但简单）
3. VLM-vLLM-Engine 模式：本地 vLLM 引擎（高性能）
4. VLM-HTTP-Client 模式：连接远程 vLLM 服务（推荐）

5. 实际应用案例

5.1 财务报表批量处理

# 处理年度报告
python mineru2_vllm_multthreads.py \
    --input_file /Users/zhch158/workspace/data/至远彩色印刷工业有限公司/2023年度报告母公司.pdf \
    --output_dir /Users/zhch158/workspace/data/至远彩色印刷工业有限公司/mineru-vlm-2.5.3_Results \
    --server_url http://10.192.72.11:8121 \
    --timeout 300 \
    --batch_size 1 \
    --pdf_dpi 200 \
    --debug

5.2 银行流水分析

# A用户流水分析
python -m mineru.cli.client \
    -p /data/流水分析/A用户_单元格扫描流水.img \
    -o /output/A用户_流水分析 \
    --lang ch --source modelscope

# B用户流水分析（VLM模式）
CUDA_VISIBLE_DEVICES=3 python -m mineru.cli.client \
    -p /data/流水分析/B用户_扫描流水.img \
    -o /output/B用户_流水分析 \
    --backend vlm-vllm-engine \
    --gpu-memory-utilization 0.3 \
    --source modelscope

# A用户_单元格扫描流水（VLM模式）
python mineru2_vllm_multthreads.py \
    --input_dir /Users/zhch158/workspace/data/流水分析/A用户_单元格扫描流水.img \
    --output_dir /Users/zhch158/workspace/data/流水分析/A用户_单元格扫描流水/mineru-vlm-2.5.3_Results \
    --server_url http://10.192.72.11:8121 \
    --timeout 300 \
    --batch_size 1 \
    --pdf_dpi 200

# B用户流水分析（VLM模式）
python mineru2_vllm_multthreads.py \
    --input_dir /Users/zhch158/workspace/data/流水分析/B用户_扫描流水.img \
    --output_dir /Users/zhch158/workspace/data/流水分析/B用户_扫描流水/mineru-vlm-2.5.3_Results \
    --server_url http://10.192.72.11:8121 \
    --timeout 300 \
    --batch_size 1 \
    --pdf_dpi 200

# 德_内蒙古银行照（VLM模式）
python mineru2_vllm_multthreads.py \
    --input_file /Users/zhch158/workspace/data/流水分析/德_内蒙古银行照.pdf \
    --output_dir /Users/zhch158/workspace/data/流水分析/德_内蒙古银行照/mineru-vlm-2.5.3_Results \
    --server_url http://10.192.72.11:8121 \
    --timeout 300 \
    --batch_size 1 \
    --pdf_dpi 200

# 对公_招商银行图（VLM模式）
python mineru2_vllm_multthreads.py \
    --input_file /Users/zhch158/workspace/data/流水分析/对公_招商银行图.pdf \
    --output_dir /Users/zhch158/workspace/data/流水分析/对公_招商银行图/mineru-vlm-2.5.3_Results \
    --server_url http://10.192.72.11:8121 \
    --timeout 300 \
    --batch_size 1 \
    --pdf_dpi 200

5.3 评测数据集处理

# OmniDocBench 评测集
python -m mineru.cli.client \
    -p /data/OmniDocBench/images \
    -o /output/OmniDocBench_Results \
    --lang ch --source modelscope

6. 服务管理

6.1 vLLM 服务管理

# 启动服务
./mineru_vllm_daemon.sh start

# 查看状态
./mineru_vllm_daemon.sh status

# 查看日志
./mineru_vllm_daemon.sh logs

# 测试 API
./mineru_vllm_daemon.sh test

# 停止服务
./mineru_vllm_daemon.sh stop

# 重启服务
./mineru_vllm_daemon.sh restart

6.2 FastAPI 服务管理

# 启动 FastAPI 服务
./mineru_fast_api_daemon.sh start

# 服务状态和测试
./mineru_fast_api_daemon.sh status
./mineru_fast_api_daemon.sh test

# API 文档访问
# http://localhost:8120/docs

7. 配置参数

7.1 GPU 配置

• CUDA_VISIBLE_DEVICES: 指定使用的GPU设备
• --gpu-memory-utilization: GPU内存利用率（0.1-0.9）
• --max-model-len: 最大模型长度
• --max-num-batched-tokens: 最大批处理token数

7.2 处理参数

• --batch_size: 批处理大小
• --timeout: 请求超时时间
• --debug: 调试模式（输出详细日志和中间文件）
• --test_mode: 测试模式（仅处理前10个文件）
• --no-normalize: 禁用金额标准化

7.3 输入参数

• --input_file: 单个文件
• --input_dir: 输入目录
• --input_file_list: 文件列表
• --input_csv: CSV文件（支持断点续传）

8. 性能优化

8.1 硬件要求

• GPU: NVIDIA GPU with CUDA support (推荐 24GB+ VRAM)
• 内存: 32GB+ RAM
• 存储: SSD 推荐（I/O密集）

8.2 性能调优

# GPU 内存优化
--gpu-memory-utilization 0.3  # 30% GPU内存使用

# 批处理优化
--batch_size 1                # 根据GPU内存调整

9. 故障排除

9.1 常见问题

1. GPU 内存不足: 降低 gpu-memory-utilization 参数
2. 服务连接失败: 检查 vLLM 服务状态和端口
3. 模型下载失败: 检查网络连接和 ModelScope 配置
4. 处理超时: 增加 timeout 参数值

10. 更新日志

• v0.2: 支持金额标准化、增强批量处理
• v0.1: 支持 vLLM 后端、多GPU并行

---

联系信息

• 开发者: zhch158_admin
• 邮箱: zhch158@sina.com
• 项目地址: https://gitee.com/zhch158_admin/MinerU