4.7 KiB

Raw Blame History

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

主要 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 中保留坐标，调用方可以按具体业务继续处理。

测试

uv run --project cpu pytest -q

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

4.7 KiB Raw Blame History Unescape Escape