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

uv sync --project cpu

GPU

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

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

使用

验证环境

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

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

单图片

# 默认 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

保存可视化和原始结果：

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

多轮 Benchmark：

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

PDF

# 默认混合模式：优先文本层，扫描页才 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

目录

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

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

主要 PP-OCRv6 参数

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

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

输出

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 文本层：

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

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

能力边界

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

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

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

参数速度测试

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

# 默认测试 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 和线程参数会产生笛卡尔积，请控制测试规模。

测试

uv run --project cpu pytest -q

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