# MinerU vLLM 批量处理系统 基于 MinerU 2.5+ 的文档解析和批量处理系统，支持 PDF 和图像文档的智能解析。 ## 1. 环境配置 ### 1.1 代码获取 ```bash 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 环境安装 ```bash # 创建 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 模型下载 ```bash # 从 ModelScope 下载模型权重文件 python -m mineru.cli.models_download # 模型会保存到 $MODELSCOPE_CACHE 目录 # 默认路径: /home/ubuntu/models/modelscope_cache/models/OpenDataLab/MinerU2___5-2509-1___2B ``` ### 1.4 环境变量配置 创建 `.env` 文件或设置环境变量： ```bash # .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 服务器 ```bash # 启动 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 服务器： ```bash 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 服务器（可选） ```bash # 启动 FastAPI HTTP 服务 ./mineru_fast_api_daemon.sh start # 访问 API 文档 # http://localhost:8120/docs ``` ## 3. 使用方式 ### 3.1 命令行调用（官方方式） #### Pipeline 后端（传统OCR + 规则） ```bash 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 后端（视觉语言模型） ```bash # 使用本地 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`： ```bash # 基本用法 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 财务报表批量处理 ```bash # 处理年度报告 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 银行流水分析 ```bash # 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 评测数据集处理 ```bash # OmniDocBench 评测集 python -m mineru.cli.client \ -p /data/OmniDocBench/images \ -o /output/OmniDocBench_Results \ --lang ch --source modelscope ``` ## 6. 服务管理 ### 6.1 vLLM 服务管理 ```bash # 启动服务 ./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 服务管理 ```bash # 启动 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 性能调优 ```bash # 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