235 lines
6.3 KiB
Markdown
235 lines
6.3 KiB
Markdown
# 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 模型。
|