feat: 更新README，优化环境配置和使用说明，新增批量处理脚本示例

zhch/README.md

@@ -1,40 +1,50 @@
-# 1. 环境
-```
-git clone https://gitee.com/zhch158_admin/MinerU.git -c user.name=zhch158_admin -c user.email=zhch158@sina.com
+# 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 安装依赖包
+### 1.2 Python 环境安装
 ```bash
+# 创建 conda 环境
 conda create -n mineru2 python=3.12
 conda activate mineru2
-pip install -U "mineru[core]" -i https://mirrors.aliyun.com/pypi/simple
-
-# 查看PyTorch版本
-python -c "import torch; print(torch.__version__)"
 
-# 应该用不着安装
-# uv pip install flash-attn==2.8.3 --find-links https://github.com/Dao-AILab/flash-attention/releases
+# 安装 MinerU 核心
+pip install -U "mineru[core]" -i https://mirrors.aliyun.com/pypi/simple
 
+# 开发模式安装（推荐）
 uv pip install -U -e '.[all]'
 
-pip install PyMuPDF
+# 安装额外依赖
+pip install PyMuPDF loguru tqdm pillow
+
+# 检查 PyTorch 版本
+python -c "import torch; print(f'PyTorch: {torch.__version__}, CUDA: {torch.cuda.is_available()}')"
 ```
 
-## 1.3 modelscope 下载模型
+### 1.3 模型下载
 ```bash
-# 从modelscope下载模型权重文件, 模型会在$MODELSCOPE_CACHE
+# 从 ModelScope 下载模型权重文件
 python -m mineru.cli.models_download
 
-# .env中加入model配置
-MINERU_TOOLS_CONFIG_JSON="/home/dev/zhch/src/MinerU/mineru.json"
-
+# 模型会保存到 $MODELSCOPE_CACHE 目录
+# 默认路径: /home/ubuntu/models/modelscope_cache/models/OpenDataLab/MinerU2___5-2509-1___2B
 ```
 
-.env
+### 1.4 环境变量配置
+
+创建 `.env` 文件或设置环境变量：
 ```bash
+# .env 文件内容
 NLTK_DATA="/home/ubuntu/nltk_data"
 HF_HOME="/home/ubuntu/models/hf_home"
 HF_ENDPOINT=https://hf-mirror.com
@@ -43,37 +53,274 @@ 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"
 ```
 
-# 启动vllm server
+## 2. 服务启动
+
+### 2.1 vLLM 服务器
 ```bash
-CUDA_VISIBLE_DEVICES="0"; mineru-vllm-server --port 8121 --gpu-memory-utilization 0.3
+# 启动 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
 ```
 
-# 命令行运行评估集
+### 2.2 FastAPI 服务器（可选）
 ```bash
-export MINERU_TOOLS_CONFIG_JSON="/home/ubuntu/zhch/MinerU/mineru.json"
-python -m mineru.cli.client -p /home/ubuntu/zhch/OmniDocBench/OpenDataLab___OmniDocBench/images -o /home/ubuntu/zhch/MinerU/zhch/OmniDocBench_MinerU-pipeline-2.1.1_Results --lang ch --source modelscope
+# 启动 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 /home/ubuntu/zhch/data/流水分析/A用户_单元格扫描流水.img -o /home/ubuntu/zhch/data/流水分析/A用户_单元格扫描流水/mineru-pipleline-2.5.3_Results --lang ch --source modelscope
-python -m mineru.cli.client -p /home/ubuntu/zhch/data/流水分析/B用户_扫描流水.img -o /home/ubuntu/zhch/data/流水分析/B用户_扫描流水/mineru-pipleline-2.5.3_Results --lang ch --source modelscope
-CUDA_VISIBLE_DEVICES=3 python -m mineru.cli.client -p /home/ubuntu/zhch/data/流水分析/B用户_扫描流水.img -o /home/ubuntu/zhch/data/流水分析/B用户_扫描流水/mineru-vlm-2.5.3_Results --backend vlm-vllm-engine --gpu-memory-utilization 0.3 --source modelscope
 
-export MINERU_TOOLS_CONFIG_JSON="/home/ubuntu/zhch/MinerU/mineru.json"
-python -m mineru.cli.client -p /home/ubuntu/zhch/data/至远彩色印刷工业有限公司/2023年度报告母公司.img -o /home/ubuntu/zhch/data/至远彩色印刷工业有限公司/2023年度报告母公司/mineru-pipleline-2.5.3_Results --lang ch --source modelscope
+# 处理单个文件
+python -m mineru.cli.client -p /path/to/document.pdf -o /path/to/output --lang ch --source modelscope
 
-export MINERU_TOOLS_CONFIG_JSON="/home/ubuntu/zhch/MinerU/mineru.json"
-CUDA_VISIBLE_DEVICES=3 python -m mineru.cli.client -p /home/ubuntu/zhch/data/至远彩色印刷工业有限公司/2023年度报告母公司.img -o /home/ubuntu/zhch/data/至远彩色印刷工业有限公司/2023年度报告母公司/mineru-vlm-2.5.3_Results --backend vlm-vllm-engine --gpu-memory-utilization 0.3 --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_dir /data/annual_reports \
+    --output_dir /output/financial_analysis \
+    --server_url http://127.0.0.1:8121 \
+    --batch_size 1 \
+    --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
+```
+
+### 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并行
+
+---
 
-# mac vlm-transformers
-export MINERU_TOOLS_CONFIG_JSON="/Users/zhch158/workspace/repository.git/MinerU/zhch/mineru.json"
-python -m mineru.cli.client -p /Users/zhch158/workspace/data/流水分析/B用户_扫描流水.1/data_PPStructureV3_Results/B用户_扫描流水/B用户_扫描流水_page_002.png -o /Users/zhch158/workspace/data/流水分析/B用户_扫描流水.1/mineru-vlm-2.5.3_Results --backend vlm-transformers --source modelscope
-# mac vlm-vllm-engine
-export MINERU_TOOLS_CONFIG_JSON="/Users/zhch158/workspace/repository.git/MinerU/zhch/mineru.json"
-python -m mineru.cli.client -p /Users/zhch158/workspace/data/流水分析/B用户_扫描流水.1/data_PPStructureV3_Results/B用户_扫描流水/B用户_扫描流水_page_002.png -o /Users/zhch158/workspace/data/流水分析/B用户_扫描流水.1/mineru-vlm-2.5.3_Results --backend vlm-vllm-engine --max-num-batched-tokens 16384 --source modelscope
+## 联系信息
 
-```
+- **开发者**: zhch158_admin
+- **邮箱**: zhch158@sina.com
+- **项目地址**: https://gitee.com/zhch158_admin/MinerU