report-detect/archive/docs/PADDLEOCRVL_5MIN_TIMEOUT_GUIDE.md

# PaddleOCRVL 5分钟超时配置指南

## 新增功能

已添加 `--paddleocrvl-timeout` 命令行参数，可以灵活设置PaddleOCRVL的超时时间。

## 命令示例

### 使用5分钟超时（推荐）

```bash
python test_accuracy_batch_full.py --ocr-model paddleocr_vl --batch --batch-size 20 --paddleocrvl-timeout 300
```

### 使用1分钟超时（默认）

```bash
python test_accuracy_batch_full.py --ocr-model paddleocr_vl --batch --batch-size 20
```

### 禁用PaddleOCRVL（最快）

```bash
python test_accuracy_batch_full.py --ocr-model ppocr_v5 --batch --batch-size 20 --disable-paddleocrvl
```

### 使用ppocr_v5但启用PaddleOCRVL备份（平衡）

```bash
python test_accuracy_batch_full.py --ocr-model ppocr_v5 --batch --batch-size 20 --paddleocrvl-timeout 300
```

## 超时时间建议

| 超时时间 | 适用场景 | 预期效果 | 风险 |
|---------|---------|---------|------|
| 30秒 | 快速测试 | 大部分印章会超时 | 识别率低 |
| 60秒（默认） | 平衡模式 | 中等识别率 | 部分印章超时 |
| 180秒（3分钟） | 高识别率 | 较高识别率 | 处理时间较长 |
| 300秒（5分钟） | 最高识别率 | 最高识别率 | 处理时间长，但不会卡住 |
| 600秒（10分钟） | 特殊困难印章 | 可能处理最困难的印章 | 处理时间很长 |

## 预期性能

### 使用5分钟超时

- **单印章处理时间**：最多5分钟
- **20个PDF预计时间**：1-3小时（取决于印章数量）
- **识别成功率**：最高（大部分印章能完成识别）
- **风险**：无（有超时保护）

### 使用60秒超时

- **单印章处理时间**：最多1分钟
- **20个PDF预计时间**：30-60分钟
- **识别成功率**：中等（部分困难印章会超时）
- **风险**：无（有超时保护）

## 测试结果对比

### ppocr_v5模型（无PaddleOCRVL）
- CMA准确率：85.0%
- 机构准确率：27.8%
- 平均处理时间：~18秒/PDF
- **推荐用于快速测试**

### paddleocr_vl模型 + 5分钟超时
- CMA准确率：预期85%+
- 机构准确率：预期60%+（显著提升）
- 平均处理时间：取决于印章复杂度
- **推荐用于最终验证**

## 关键改进

1. **全局变量 `PADDLEOCRVL_TIMEOUT`**
   - 默认值：60秒
   - 可通过命令行参数覆盖
   - 所有PaddleOCRVL调用统一使用

2. **超时保护**
   - 防止程序永久卡住
   - 超时后优雅降级到其他OCR方法
   - 详细日志记录超时事件

3. **灵活配置**
   - 可以为不同测试场景设置不同超时
   - 不需要修改代码
   - 通过命令行参数轻松调整

## 监控建议

运行测试时关注以下日志：

```
# 正常完成
[Subprocess] Prediction completed in 45.2s
[Subprocess] *** SEAL FOUND: '广东产品质量监督检验研究院' ***

# 超时（但程序继续）
PaddleOCRVL recognition timeout (300s) for seal_crop_0.png
  Seal #0: ** Both unwarp and crop OCR failed **
```

## 故障排除

### 问题：所有印章都超时
**原因**：超时时间太短
**解决**：增加到300秒或更长

### 问题：处理时间太长
**原因**：超时时间太长或印章确实很复杂
**解决**：
- 降低超时时间到180秒
- 或使用ppocr_v5模型

### 问题：识别率仍然很低
**原因**：PaddleOCRVL可能不适合这些印章
**解决**：
- 使用ppocr_v5模型
- 检查印章图像质量
- 考虑人工审核

## 文件修改

1. **test_accuracy_batch_full.py**
   - 第76行：添加全局变量 `PADDLEOCRVL_TIMEOUT = 60`
   - 第2533行：添加命令行参数 `--paddleocrvl-timeout`
   - 第2549行：设置全局变量值
   - 第1153、1362、1380、1402行：使用全局变量

## 总结

使用5分钟超时配置可以：
- ✅ 给PaddleOCRVL足够时间完成识别
- ✅ 防止程序永久卡住
- ✅ 提高印章识别成功率
- ✅ 保持代码灵活性（可调整超时时间）

**推荐命令**：
```bash
python test_accuracy_batch_full.py --ocr-model paddleocr_vl --batch --batch-size 20 --paddleocrvl-timeout 300
```

这将使用PaddleOCRVL模型，每个印章最多等待5分钟，最大化识别成功率，同时确保程序不会永久卡住。