# DotsOCR vLLM 批量处理工具

基于 DotsOCR 的批量文档处理工具，支持 PDF 和图片文件的批量处理。

> 📚 **详细文档**：更多技术文档、环境配置等，请查看 [docs/dotsocr/](../../docs/dotsocr/)

## 功能特性

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

## 安装依赖

```bash
conda activate py312

# 安装 DotsOCR
pip install dots-ocr

# 安装其他依赖
pip install loguru tqdm pillow
```

## 使用方法

### 基本用法

```bash
# 处理单个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
```

### 高级用法

```bash
# 指定页面范围（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 --ip 10.192.72.11 --port 8101

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

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

# 启用并发处理
python main.py --input ./images/ --output_dir ./output --use_threading --max_workers 3
```

## 参数说明

### 输入输出参数

- `--input, -i`: 输入路径（必需）
  - PDF 文件：自动转换为图片处理
  - 图片文件：直接处理
  - 图片目录：扫描所有图片文件
  - 文件列表（.txt）：每行一个文件路径
  - CSV 文件：读取失败的文件列表

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

### DotsOCR vLLM 参数

- `--ip`: vLLM 服务器 IP（默认: `127.0.0.1`）
- `--port`: vLLM 服务器端口（默认: `8101`）
- `--model_name`: 模型名称（默认: `DotsOCR`）
- `--prompt_mode`: 提示模式（默认: `prompt_layout_all_en`）
  - 可选值：`dict_promptmode_to_prompt.keys()` 中的所有模式
- `--min_pixels`: 最小像素数（默认: `MIN_PIXELS`）
- `--max_pixels`: 最大像素数（默认: `MAX_PIXELS`）
- `--dpi`: PDF 转图片的 DPI（默认: `200`）

### 处理参数

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

### 并发参数

- `--use_threading`: 启用多线程并发处理
- `--max_workers`: 最大并发工作线程数（默认: `3`，应与 vLLM data-parallel-size 匹配）

### 功能开关

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

### 日志参数

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

## 输出格式

输出目录结构：

```
output_dir/
├── filename.md              # Markdown 内容
├── filename.json            # Layout info JSON
├── filename_layout.jpg      # 布局可视化图片
├── filename_original.md     # 原始 Markdown（如果启用标准化且发生变化）
└── filename_original.json   # 原始 JSON（如果启用标准化且发生变化）
```

### 成功判断标准

处理成功的判断标准：
- 输出目录中存在对应的 `.md` 文件
- 输出目录中存在对应的 `.json` 文件

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

## 统计信息

处理完成后会显示：

- 文件统计：总文件数、成功数、失败数、跳过数
- 性能指标：总耗时、吞吐量、平均处理时间

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

## 示例

### 示例1：处理PDF文件

```bash
python main.py \
  --input /path/to/document.pdf \
  --output_dir ./output \
  --pages "1-10" \
  --ip 10.192.72.11 \
  --port 8101 \
  --log_level DEBUG
```

### 示例2：批量处理图片目录（并发）

```bash
python main.py \
  --input /path/to/images/ \
  --output_dir ./output \
  --batch_size 4 \
  --use_threading \
  --max_workers 3 \
  --log_file ./processing.log
```

### 示例3：Dry run 验证

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

### 示例4：处理失败的文件（从CSV）

```bash
python main.py \
  --input processed_files.csv \
  --output_dir ./output \
  --ip 10.192.72.11 \
  --port 8101
```

## 注意事项

1. **服务器连接**：确保 DotsOCR vLLM 服务器正在运行并可访问
2. **内存使用**：处理大文件时注意内存使用情况
3. **文件命名**：PDF 页面会转换为 `filename_page_001.png` 格式
4. **页面范围**：页面编号从 1 开始（不是 0）
5. **并发处理**：使用 `--use_threading` 时，确保 `--max_workers` 与 vLLM 服务器的 `data-parallel-size` 匹配

## 故障排查

### 问题：连接服务器失败

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

### 问题：处理失败

- 使用 `--log_level DEBUG` 获取详细错误信息和 traceback
- 检查输出目录权限
- 查看日志文件获取更多信息

### 问题：输出文件不存在

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

### 问题：并发处理性能不佳

- 确保 `--max_workers` 与 vLLM 服务器的 `data-parallel-size` 匹配
- 检查服务器资源使用情况
- 调整 `--batch_size` 参数

## 相关工具

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

## 与 MinerU 工具的差异

1. **输出格式**：DotsOCR 输出 `_layout.jpg`，MinerU 输出 `_layout.pdf`
2. **服务器参数**：DotsOCR 使用 `--ip` 和 `--port`，MinerU 使用 `--server_url`
3. **提示模式**：DotsOCR 支持多种 `prompt_mode`，MinerU 使用固定的提示方式
4. **并发处理**：DotsOCR 支持可选的并发处理（`--use_threading`），MinerU 仅支持单进程