# PP-OCRv6 本地 OCR

本项目使用 PP-OCRv6 实现图片、PDF 和目录批量 OCR。工程结构参考 `../ocr-VL1.6`，CPU/GPU 环境隔离，并通过根目录 `ocr.py` 统一调用。

输出 Markdown 的定位是**便于阅读的文字结果**。本项目不实现版面分析、表格结构恢复或富文档还原。

## 功能

- 单图片 PP-OCRv6 识别
- 图片与 PDF 目录批处理
- PDF `hybrid` / `text` / `ocr` 模式
- PDF 文本层质量判断和扫描页自动 OCR
- PDF 页码选择、断点续传与覆盖重做
- TXT、简单 Markdown、归一化 JSON、Benchmark
- 可选 PaddleOCR 原始 JSON 和 OCR 可视化
- CPU/GPU 隔离，GPU 失败不回退 CPU
- 模型延迟加载，同一批次复用模型

支持三种成对的检测与识别模型规格：

| 参数 | 检测模型 | 识别模型 |
|---|---|---|
| `tiny` | `PP-OCRv6_tiny_det` | `PP-OCRv6_tiny_rec` |
| `small` | `PP-OCRv6_small_det` | `PP-OCRv6_small_rec` |
| `medium` | `PP-OCRv6_medium_det` | `PP-OCRv6_medium_rec` |

不传参数时默认使用 `medium`。

## 安装

### CPU

```bash
uv sync --project cpu
```

### GPU

```bash
python gpu/setup_env.py --cuda cu118 --dry-run
python gpu/setup_env.py --cuda cu118
```

也可按目标机器使用 `cu126`。CUDA、驱动和 PaddlePaddle Wheel 必须相互兼容。

## 使用

### 验证环境

```bash
python ocr.py verify --device cpu
python ocr.py verify --device gpu
```

`verify` 只验证 Paddle 运行环境，不下载和初始化 OCR 模型。

### 单图片

```bash
# 默认 medium
python ocr.py data/images/手写01.png --device cpu

# 选择 small
python ocr.py data/images/手写01.png --device cpu --model-size small

# 选择 tiny；--model 是 --model-size 的别名
python ocr.py data/images/手写01.png --device cpu --model tiny
```

保存可视化和原始结果：

```bash
python ocr.py data/images/手写01.png \
  --device cpu \
  --save-visualization \
  --save-raw-result
```

多轮 Benchmark：

```bash
python ocr.py data/images/手写01.png --warmup 1 --rounds 3
```

### PDF

```bash
# 默认混合模式：优先文本层，扫描页才 OCR
python ocr.py data/documents/sample.pdf --device cpu

# 强制文本层
python ocr.py sample.pdf --pdf-mode text

# 强制全部页面 OCR
python ocr.py sample.pdf --pdf-mode ocr

# 指定页码
python ocr.py sample.pdf --pages "1-5,8,10-"

# 中断后恢复
python ocr.py sample.pdf --resume

# 删除原任务并重做
python ocr.py sample.pdf --overwrite
```

### 目录

```bash
python ocr.py data/ --device cpu
python ocr.py data/ --recursive --device cpu
```

目录任务串行处理文件，避免无控制并发造成内存占用和界面卡顿。

## 主要 PP-OCRv6 参数

```text
--model-size tiny|small|medium
--model tiny|small|medium          # --model-size 的别名
--lang ch
--text-rec-score-thresh 0.0
--text-det-limit-side-len N
--text-det-limit-type min|max
--text-det-thresh FLOAT
--text-det-box-thresh FLOAT
--text-det-unclip-ratio FLOAT
--text-recognition-batch-size 6
--return-word-box
--doc-orientation-classify / --no-doc-orientation-classify
--doc-unwarping / --no-doc-unwarping
--textline-orientation / --no-textline-orientation
```

默认开启文档方向分类和文本行方向分类，默认关闭文档去畸变。

## 输出

```text
outputs/
├── images/
│   └── <图片名_扩展名>/
│       ├── result.txt
│       ├── result.md
│       ├── result.json
│       ├── benchmark.json
│       ├── raw-result.json       # 可选
│       └── visualization.jpg     # 可选
├── pdfs/
│   └── <PDF名>/
│       ├── manifest.json
│       ├── document.md
│       ├── document.json
│       └── pages/
└── batches/
```

`result.json` 使用项目自有稳定结构，主要包含：

- 文本行
- 识别置信度
- 多边形与矩形坐标
- 模型和语言信息
- 图片尺寸
- 汇总统计

## PDF 混合模式

每页先提取 PDF 文本层：

```text
有效文本层 → 直接保存文本
无效文本层 → 渲染 PNG → PP-OCRv6
```

纯电子 PDF 不加载 PP-OCRv6 模型。Manifest 会记录 PDF 哈希、DPI、文本层阈值和模型配置；关键配置变化时必须使用 `--overwrite`，不能错误续传。

## 能力边界

本项目只提供通用文字检测和识别：

- Markdown 是按识别顺序拼接的便读文本；
- 不恢复标题层级；
- 不恢复多栏版面；
- 不恢复表格单元格结构；
- 不提供与 PaddleOCR-VL 等价的富 Markdown。

JSON 中保留坐标，调用方可以按具体业务继续处理。

## 参数速度测试

使用根目录 `benchmark.py` 对 `data/` 中的图片和 PDF 执行参数矩阵测试，并生成 Markdown 对比报告：

```bash
# 默认测试 tiny/small/medium × fast/standard，PDF 强制 OCR
python benchmark.py

# 显式指定模型、预处理配置、DPI 和 CPU 线程
python benchmark.py \
  --models tiny small medium \
  --profiles fast standard robust \
  --dpis 120 144 200 \
  --threads auto 4 8 \
  --det-limit-side-lens 64 960 \
  --det-thresholds 0.2 0.3 \
  --det-box-thresholds 0.5 0.6 \
  --det-unclip-ratios 1.5 2.0 \
  --rec-score-thresholds 0.0 0.5 \
  --rec-batch-sizes 1 6

# 指定报告路径
python benchmark.py --output benchmarks/参数测试报告.md
```

默认场景共 6 组：

- 三种模型：`tiny`、`small`、`medium`；
- 两种预处理配置：`fast`、`standard`；
- PDF 使用 `ocr` 模式，确保不同模型真正参与 PDF 测试；
- 每个场景在独立进程中执行，避免模型缓存到内存造成场景间干扰。

可测试的参数维度包括模型规格、预处理配置、PDF DPI、CPU 线程、检测边长及限制方式、检测阈值、文本框阈值、扩张比例、识别阈值和识别 Batch Size。所有列表参数会组成笛卡尔积。

报告统计墙钟耗时、模型初始化、图片推理、PDF OCR、纯 OCR 耗时、吞吐、识别行数和平均置信度。原始输出、日志及汇总 JSON 保存在 `benchmarks/parameter-runs/`。

> `robust` 会启用文档去畸变，测试显著更慢；多组 DPI 和线程参数会产生笛卡尔积，请控制测试规模。

## 测试

```bash
uv run --project cpu pytest -q
```

测试使用假模型覆盖结果适配、输出路由、参数测试程序和 PDF 混合流程，不要求每次测试都下载 OCR 模型。