# PP-StructureV3 批量处理工具

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

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

本工具提供两种处理方式：
- **本地处理** (`main.py`)：直接调用本地 PaddleX pipeline 进行处理
- **API 客户端** (`api_client.py`)：通过 HTTP API 调用远程服务进行处理

## 功能特性

- ✅ 统一输入接口：支持 PDF 文件、图片文件、图片目录、文件列表（.txt）、CSV 文件
- ✅ 自动判断输入类型：根据输入路径自动识别文件类型并处理
- ✅ 页面范围支持：PDF 文件和图片目录支持指定页面范围（如 `1-5,7,9-12`）
- ✅ 成功判断优化：基于输出文件存在性判断处理是否成功
- ✅ 数字标准化：自动将全角数字转换为半角（可选）
- ✅ Dry run 模式：验证配置和输入，不执行实际处理
- ✅ 增强适配器：支持表格识别和文档预处理的增强功能（可选）
- ✅ 进度显示：实时显示处理进度和统计信息
- ✅ 全面文档分析：支持布局检测、表格识别、公式识别、图表识别、印章识别等

## 安装依赖

### 本地处理模式（main.py）

```bash
conda activate paddle_env  # 或 py312

# 安装 PaddleX
pip install paddlex

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

### API 客户端模式（api_client.py）

```bash
# 只需要安装基础依赖，不需要安装 PaddleX
pip install loguru tqdm pillow requests
```

## 使用方法

### 本地处理模式（main.py）

#### 基本用法

```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
```

### API 客户端模式（api_client.py）

#### 基本用法

```bash
# 处理单个PDF文件
python api_client.py --input document.pdf --output_dir ./output --api_url http://localhost:8080/layout-parsing

# 处理图片目录
python api_client.py --input ./images/ --output_dir ./output --api_url http://10.192.72.11:8111/layout-parsing

# 处理文件列表
python api_client.py --input file_list.txt --output_dir ./output --api_url http://localhost:8080/layout-parsing

# 处理CSV文件（失败的文件）
python api_client.py --input results.csv --output_dir ./output --api_url http://localhost:8080/layout-parsing
```

#### 高级用法（本地处理）

```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

# 指定 Pipeline 配置文件
python main.py --input document.pdf --output_dir ./output --pipeline ../paddle_common/config/PP-StructureV3-RT-DETR-H_layout_17cls.yaml

# 指定设备
python main.py --input document.pdf --output_dir ./output --device cpu

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

# 禁用增强适配器
python main.py --input document.pdf --output_dir ./output --no-adapter
```

#### 高级用法（API 客户端）

```bash
# 指定页面范围（PDF或图片目录）
python api_client.py --input document.pdf --output_dir ./output --pages "1-5,7" --api_url http://localhost:8080/layout-parsing

# 只处理前10页（PDF或图片目录）
python api_client.py --input document.pdf --output_dir ./output --pages "-10" --api_url http://localhost:8080/layout-parsing

# 从第5页到最后（PDF或图片目录）
python api_client.py --input document.pdf --output_dir ./output --pages "5-" --api_url http://localhost:8080/layout-parsing

# 仅验证配置（dry run）
python api_client.py --input document.pdf --output_dir ./output --api_url http://localhost:8080/layout-parsing --dry_run

# 使用 DEBUG 日志级别获取详细错误信息
python api_client.py --input document.pdf --output_dir ./output --api_url http://localhost:8080/layout-parsing --log_level DEBUG

# 设置 API 超时时间
python api_client.py --input document.pdf --output_dir ./output --api_url http://localhost:8080/layout-parsing --timeout 600

# 禁用数字标准化
python api_client.py --input document.pdf --output_dir ./output --api_url http://localhost:8080/layout-parsing --no-normalize
```

## 参数说明

### 通用参数（两种模式都支持）

#### 输入输出参数

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

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

#### 处理参数

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

#### 功能开关

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

#### 日志参数

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

### 本地处理模式特有参数（main.py）

#### PP-StructureV3 Pipeline 参数

- `--pipeline`: Pipeline 名称或配置文件路径（默认: `PP-StructureV3`）
  - 可以是内置 pipeline 名称（如 `PP-StructureV3`）
  - 也可以是配置文件路径（如 `../paddle_common/config/PP-StructureV3-RT-DETR-H_layout_17cls.yaml`）

- `--device`: 设备字符串（默认: `gpu:0`）
  - 格式：`gpu:0`, `gpu:1`, `cpu` 等

- `--batch_size`: 批次大小（默认: `1`，PaddleX 通常单张处理）
- `--no-adapter`: 禁用增强适配器（默认启用）

### API 客户端模式特有参数（api_client.py）

#### API 参数

- `--api_url`: API URL（默认: `http://localhost:8080/layout-parsing`）
  - 远程服务的完整 URL 地址
  - 示例：`http://10.192.72.11:8111/layout-parsing`

- `--timeout`: API 调用超时时间（秒，默认: `300`）
  - 单个 API 请求的最大等待时间

## 输出格式

输出目录结构：

```
output_dir/
├── filename.md              # Markdown 内容
├── filename.json            # Content list JSON
├── filename_*.jpg           # 输出图像（如 layout、table 等）
├── 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" \
  --pipeline ../paddle_common/config/PP-StructureV3-RT-DETR-H_layout_17cls.yaml \
  --device cpu \
  --log_level DEBUG
```

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

```bash
python main.py \
  --input /path/to/images/ \
  --output_dir ./output \
  --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 \
  --pipeline PP-StructureV3
```

### API 客户端模式示例

#### 示例1：通过 API 处理PDF文件

```bash
python api_client.py \
  --input /path/to/document.pdf \
  --output_dir ./output \
  --pages "1-10" \
  --api_url http://10.192.72.11:8111/layout-parsing \
  --timeout 600 \
  --log_level DEBUG
```

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

```bash
python api_client.py \
  --input /path/to/images/ \
  --output_dir ./output \
  --api_url http://localhost:8080/layout-parsing \
  --log_file ./processing.log
```

#### 示例3：Dry run 验证（API）

```bash
python api_client.py \
  --input /path/to/document.pdf \
  --output_dir ./output \
  --api_url http://localhost:8080/layout-parsing \
  --dry_run
```

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

```bash
python api_client.py \
  --input processed_files.csv \
  --output_dir ./output \
  --api_url http://localhost:8080/layout-parsing
```

## 注意事项

1. **Pipeline 配置**：确保 Pipeline 配置文件路径正确，或使用内置的 pipeline 名称
2. **设备配置**：根据实际情况设置 `--device` 参数（GPU 或 CPU）
3. **内存使用**：处理大文件时注意内存使用情况
4. **文件命名**：PDF 页面会转换为 `filename_page_001.png` 格式
5. **页面范围**：页面编号从 1 开始（不是 0）
6. **增强适配器**：默认启用增强适配器，可以提升表格识别和文档预处理的效果
7. **功能模块**：PP-StructureV3 支持布局检测、表格识别、公式识别、图表识别、印章识别等功能，可通过配置文件控制

## 故障排查

### 问题：Pipeline 初始化失败

- 检查 Pipeline 配置文件路径是否正确
- 确认 PaddleX 已正确安装
- 检查设备配置（GPU/CPU）是否正确

### 问题：处理失败

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

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

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

### 问题：适配器应用失败（仅本地处理模式）

- 检查 PaddleX 版本是否支持适配器
- 可以尝试使用 `--no-adapter` 禁用适配器
- 查看日志获取详细错误信息

### 问题：API 调用失败（仅 API 客户端模式）

- 检查 API URL 是否正确
- 确认远程服务是否正常运行
- 检查网络连接是否正常
- 尝试增加 `--timeout` 参数值
- 使用 `--log_level DEBUG` 获取详细错误信息
- 检查 API 服务返回的错误信息

## 相关工具

- `ocr_utils`: OCR 工具包，提供 PDF 处理、文件处理等功能
- `paddle_common`: PaddleX 共享核心模块（处理器、工具函数、适配器）
- PaddleX: 文档解析框架

## 本地处理 vs API 客户端

| 特性 | `main.py`（本地处理） | `api_client.py`（API 客户端） |
|------|---------------------|---------------------------|
| **处理方式** | 本地 PaddleX pipeline | HTTP API 远程服务 |
| **主要参数** | `--pipeline`, `--device` | `--api_url`, `--timeout` |
| **依赖** | 需要本地安装 PaddleX | 只需要网络连接和 requests |
| **适用场景** | 本地处理、GPU 加速 | 远程服务、分布式处理 |
| **优势** | 无需网络、性能可控 | 无需本地资源、可扩展 |
| **劣势** | 需要本地 GPU/CPU 资源 | 依赖网络和服务可用性 |

### 选择建议

- **使用本地处理** (`main.py`) 当：
  - 有本地 GPU 资源
  - 需要离线处理
  - 对处理速度有较高要求
  - 需要自定义 pipeline 配置

- **使用 API 客户端** (`api_client.py`) 当：
  - 没有本地 GPU 资源
  - 需要分布式处理
  - 服务端已有部署好的 PP-StructureV3 服务
  - 需要统一管理和调度

## 与 PaddleOCR-VL 工具的差异

1. **默认 Pipeline**：PP-StructureV3 工具默认使用 `PP-StructureV3` pipeline
2. **参数命名**：PP-StructureV3 使用下划线命名（如 `use_layout_detection`），PaddleOCR-VL 使用驼峰命名（如 `useLayoutDetection`）
3. **功能差异**：PP-StructureV3 提供更全面的文档结构分析（布局检测、表格识别、公式识别、图表识别、印章识别等），PaddleOCR-VL 专注于视觉语言模型
4. **处理方式**：PP-StructureV3 支持本地处理和 API 客户端两种模式，PaddleOCR-VL layout 调用本地模型，VLRecognition 调用服务端 VL 模型进行处理