1046 lines
29 KiB
Markdown
1046 lines
29 KiB
Markdown
# PP-OCRv6 可行性分析与实施方案
|
||
|
||
## 1. 文档目的
|
||
|
||
本文评估在当前 `PP-OCRv6` 项目中，参考相邻项目 `../ocr-VL1.6` 的工程结构和功能，建设一套基于 **PP-OCRv6** 的本地 OCR 应用是否可行，并给出推荐架构、改造范围、实施步骤、风险及验收标准。
|
||
|
||
本文所称“仿照 `../ocr-VL1.6`”主要指复用其以下工程能力：
|
||
|
||
- 根目录统一入口；
|
||
- CPU/GPU 运行环境隔离；
|
||
- 图片、PDF、目录自动路由；
|
||
- PDF 文本层提取与 OCR 混合处理；
|
||
- 模型延迟加载；
|
||
- 批量串行处理；
|
||
- 统一输出目录；
|
||
- Benchmark、日志、断点续传与测试。
|
||
|
||
本项目已确认不实现版面分析和表格结构恢复。Markdown 输出仅定位为“便于阅读的文字结果”，按识别顺序拼接文本，不追求原文档版面或表格结构还原。
|
||
|
||
---
|
||
|
||
## 2. 参考项目现状
|
||
|
||
参考项目 `../ocr-VL1.6` 已具备较完整的本地 OCR 工程框架，其主要结构如下：
|
||
|
||
```text
|
||
ocr-VL1.6/
|
||
├── ocr.py # 根目录统一入口
|
||
├── ocr_app/
|
||
│ ├── cli.py # 命令行参数
|
||
│ ├── commands.py # 图片/PDF/目录路由
|
||
│ ├── runtime.py # CPU/GPU 校验和模型延迟加载
|
||
│ ├── output.py # 输出归一化
|
||
│ ├── pdf.py # PDF 分页、OCR、断点续传
|
||
│ ├── pdf_text.py # PDF 文本层提取与质量判断
|
||
│ └── logging_utils.py # UTF-8 日志
|
||
├── cpu/ # CPU 独立 uv 项目
|
||
├── gpu/ # GPU 独立 uv 项目
|
||
├── tests/ # 共享逻辑测试
|
||
├── outputs/
|
||
├── benchmarks/
|
||
└── logs/
|
||
```
|
||
|
||
参考项目当前使用：
|
||
|
||
- `paddleocr[doc-parser]==3.7.0`；
|
||
- CPU：`paddlepaddle==3.2.1`；
|
||
- GPU：`paddlepaddle-gpu==3.2.1`；
|
||
- PDF 渲染：`pypdfium2>=5.11.0`；
|
||
- Python 环境管理：`uv`。
|
||
|
||
经本地已安装包源码核验，PaddleOCR 3.7.0 已原生支持：
|
||
|
||
```python
|
||
from paddleocr import PaddleOCR
|
||
|
||
ocr = PaddleOCR(
|
||
ocr_version="PP-OCRv6",
|
||
lang="ch",
|
||
device="cpu",
|
||
)
|
||
```
|
||
|
||
当不显式指定模型名称时，PP-OCRv6 默认使用：
|
||
|
||
- 默认文本检测：`PP-OCRv6_medium_det`；
|
||
- 默认文本识别：`PP-OCRv6_medium_rec`；
|
||
- 可选规格：`tiny`、`small`、`medium`，检测与识别模型按相同规格成对选择。
|
||
|
||
因此，参考项目的依赖体系和 CPU/GPU 隔离方案可以继续使用，不需要引入新的 OCR 框架。
|
||
|
||
---
|
||
|
||
## 3. 模型能力差异
|
||
|
||
### 3.1 PaddleOCR-VL-1.6
|
||
|
||
参考项目使用的 PaddleOCR-VL-1.6 属于视觉语言文档解析管线，输出中包含：
|
||
|
||
- 版面区域；
|
||
- 文档块标签；
|
||
- 按版面组织的文本内容；
|
||
- 富 Markdown；
|
||
- Markdown 图片资源；
|
||
- `parsing_res_list`、`layout_det_res` 等结构化信息。
|
||
|
||
它更适合复杂文档解析、版面理解和接近原文档结构的 Markdown 导出。
|
||
|
||
### 3.2 PP-OCRv6
|
||
|
||
PP-OCRv6 是传统检测与识别组合式 OCR 管线，主要输出：
|
||
|
||
- `dt_polys`：检测框多边形；
|
||
- `rec_texts`：识别文本；
|
||
- `rec_scores`：识别置信度；
|
||
- `rec_polys`：保留的识别区域；
|
||
- `rec_boxes`：矩形坐标；
|
||
- 可选文字方向和单词级坐标。
|
||
|
||
其核心优势是文本检测与识别，默认不提供与 PaddleOCR-VL-1.6 等价的：
|
||
|
||
- 标题、正文、表格、图片等版面语义分类；
|
||
- 复杂阅读顺序恢复；
|
||
- 表格结构还原；
|
||
- 公式、图表和文档级语义理解；
|
||
- 原生富 Markdown。
|
||
|
||
### 3.3 能力对比
|
||
|
||
| 维度 | PaddleOCR-VL-1.6 | PP-OCRv6 | 影响 |
|
||
|---|---|---|---|
|
||
| 普通文字识别 | 支持 | 支持，通常更轻量 | 可替换 |
|
||
| 文本框坐标 | 支持 | 支持 | 可替换 |
|
||
| 识别置信度 | 结果形态依管线 | 原生支持 | PP-OCRv6 更直接 |
|
||
| 版面分析 | 强 | 非核心能力 | 不可直接等价替换 |
|
||
| 表格结构恢复 | 支持文档解析能力 | 默认不支持 | 需要额外模型或降级输出 |
|
||
| Markdown | 原生富 Markdown | 需要自行拼接 | 必须重写输出适配器 |
|
||
| 推理资源 | 较高 | 通常较低 | PP-OCRv6 更适合通用 OCR |
|
||
| 批量吞吐 | 受 VLM 生成影响 | 检测识别管线更适合批量 | 预期更好，需实测 |
|
||
| PDF 文本层混合路由 | 工程层实现 | 可复用同一工程层 | 可直接复用 |
|
||
|
||
---
|
||
|
||
## 4. 可行性结论
|
||
|
||
### 4.1 总体结论
|
||
|
||
**项目可行，推荐实施。**
|
||
|
||
如果目标是实现“图片/PDF/目录的本地文字识别应用”，并保留 `../ocr-VL1.6` 的统一入口、CPU/GPU 隔离、PDF 混合模式、输出管理、Benchmark 和日志能力，则整体可行性为 **高**。
|
||
|
||
本项目不要求与 PaddleOCR-VL-1.6 完全一致的版面结构和富 Markdown，也不实现表格结构恢复，因此上述能力不纳入本次实施范围。
|
||
|
||
### 4.2 分项可行性
|
||
|
||
| 项目 | 可行性 | 说明 |
|
||
|---|---|---|
|
||
| CPU 本地推理 | 高 | 当前依赖已支持 PP-OCRv6，参考项目 CPU 环境可复用 |
|
||
| NVIDIA GPU 推理 | 高但需实机验证 | GPU Wheel 安装逻辑可复用，仍需目标 CUDA 机器验证 |
|
||
| 单图片 OCR | 高 | `PaddleOCR.predict()` 可直接处理图片 |
|
||
| 批量目录 OCR | 高 | 可复用串行路由和单模型复用机制 |
|
||
| 扫描 PDF OCR | 高 | 复用 PDF 渲染后逐页调用 PP-OCRv6 |
|
||
| 电子 PDF 文本直取 | 高 | 与 OCR 模型无关，可直接复用 |
|
||
| PDF 混合模式 | 高 | 可复用文本层质量判定和按页路由 |
|
||
| PDF 断点续传 | 高 | 可复用 manifest 机制，调整结果字段即可 |
|
||
| TXT/JSON 输出 | 高 | PP-OCRv6 原生结果适合导出 |
|
||
| 简单 Markdown 输出 | 高 | 可按阅读顺序拼接纯文本行 |
|
||
| 便读 Markdown | 高 | 按识别顺序拼接文字，不恢复原版面 |
|
||
| 版面/表格结构恢复 | 不实施 | 已明确排除在本项目范围之外 |
|
||
| 多语言 | 中 | PP-OCRv6 支持范围需按语言确认，不支持的语言应回退 PP-OCRv5 或拒绝启动 |
|
||
|
||
### 4.3 推荐适用场景
|
||
|
||
PP-OCRv6 版本适合：
|
||
|
||
- 名片、票据、截图、扫描件的文字提取；
|
||
- 中文、英文、日文及已支持拉丁语种识别；
|
||
- 大量普通图片的批处理；
|
||
- 电子 PDF 与扫描 PDF 混合处理；
|
||
- 对坐标、置信度和纯文本有明确需求的场景；
|
||
- CPU 本地部署或资源受限部署。
|
||
|
||
不建议仅使用 PP-OCRv6 完成：
|
||
|
||
- 高保真合同版面还原；
|
||
- 表格单元格结构恢复；
|
||
- 公式语义识别；
|
||
- 图文混排文档的章节层级恢复；
|
||
- 与 PaddleOCR-VL 输出完全兼容的富 Markdown 生成。
|
||
|
||
---
|
||
|
||
## 5. 建设目标
|
||
|
||
建议本项目第一阶段实现以下功能：
|
||
|
||
1. 根目录统一入口：
|
||
|
||
```bash
|
||
python ocr.py <图片|PDF|目录> --device cpu|gpu
|
||
```
|
||
|
||
2. 自动按输入类型路由：
|
||
|
||
- 图片：PP-OCRv6 检测与识别；
|
||
- PDF：文本层直取或页面 OCR；
|
||
- 目录：发现支持的图片和 PDF，串行处理。
|
||
|
||
3. CPU/GPU 环境完全隔离：
|
||
|
||
- `cpu/.venv`；
|
||
- `gpu/.venv`；
|
||
- GPU 不可用时明确失败，不静默回退 CPU。
|
||
|
||
4. 模型延迟加载：
|
||
|
||
- 纯电子 PDF 不加载 PP-OCRv6；
|
||
- 首张图片或首个扫描 PDF 页面才初始化模型；
|
||
- 同一批次复用单个模型实例。
|
||
|
||
5. 输出格式：
|
||
|
||
- `result.txt`：纯文本；
|
||
- `result.md`：简单 Markdown；
|
||
- `result.json`：归一化结构化结果；
|
||
- `visualization.jpg`：可选识别可视化；
|
||
- `benchmark.json`：耗时、设备、模型和统计信息。
|
||
|
||
6. PDF 能力：
|
||
|
||
- `hybrid`、`text`、`ocr` 三种模式；
|
||
- 页码选择；
|
||
- PDF 密码；
|
||
- 断点续传；
|
||
- 覆盖重做；
|
||
- 每页独立结果和整文档合并结果。
|
||
|
||
7. UTF-8 结构化日志、错误处理和自动化测试。
|
||
|
||
---
|
||
|
||
## 6. 推荐目录结构
|
||
|
||
建议沿用参考项目结构，但将模型相关字段改为 PP-OCRv6：
|
||
|
||
```text
|
||
PP-OCRv6/
|
||
├── ocr.py
|
||
├── ocr_app/
|
||
│ ├── __init__.py
|
||
│ ├── cli.py
|
||
│ ├── commands.py
|
||
│ ├── runtime.py
|
||
│ ├── result_adapter.py # PP-OCRv6 结果归一化
|
||
│ ├── output.py
|
||
│ ├── pdf.py
|
||
│ ├── pdf_text.py
|
||
│ └── logging_utils.py
|
||
├── cpu/
|
||
│ ├── .python-version
|
||
│ ├── pyproject.toml
|
||
│ ├── uv.lock
|
||
│ ├── README.md
|
||
│ └── runner.py
|
||
├── gpu/
|
||
│ ├── .python-version
|
||
│ ├── pyproject.toml
|
||
│ ├── README.md
|
||
│ ├── runner.py
|
||
│ └── setup_env.py
|
||
├── data/
|
||
│ ├── images/
|
||
│ └── documents/
|
||
├── outputs/
|
||
├── benchmarks/
|
||
├── logs/
|
||
├── tests/
|
||
├── docs/
|
||
│ └── 01-可行性分析与实施方案.md
|
||
├── .gitignore
|
||
└── README.md
|
||
```
|
||
|
||
新增 `result_adapter.py` 的原因是 PP-OCRv6 与 PaddleOCR-VL-1.6 的结果对象差异较大。模型原始结果不应直接扩散到 PDF、输出、Benchmark 和日志模块中，应先转换为稳定的项目内部数据结构。
|
||
|
||
---
|
||
|
||
## 7. 核心架构设计
|
||
|
||
### 7.1 分层结构
|
||
|
||
```text
|
||
ocr.py
|
||
↓ 选择 CPU/GPU 独立环境
|
||
cpu/runner.py 或 gpu/runner.py
|
||
↓
|
||
ocr_app/cli.py
|
||
↓
|
||
ocr_app/commands.py
|
||
├── 图片路由
|
||
├── PDF 路由
|
||
└── 目录路由
|
||
↓
|
||
ocr_app/runtime.py
|
||
↓ 延迟创建
|
||
PaddleOCR(ocr_version="PP-OCRv6")
|
||
↓
|
||
ocr_app/result_adapter.py
|
||
↓
|
||
TXT / Markdown / JSON / 可视化 / Benchmark
|
||
```
|
||
|
||
### 7.2 运行时设计
|
||
|
||
`PipelineProvider` 继续负责：
|
||
|
||
- 导入 PaddlePaddle；
|
||
- CPU 线程配置；
|
||
- CUDA 构建检查；
|
||
- GPU 数量和设备编号检查；
|
||
- 模型延迟初始化；
|
||
- GPU 同步；
|
||
- 设备和环境元数据收集。
|
||
|
||
模型初始化建议为：
|
||
|
||
```python
|
||
from paddleocr import PaddleOCR
|
||
|
||
self._pipeline = PaddleOCR(
|
||
ocr_version="PP-OCRv6",
|
||
lang=self.config.lang,
|
||
device=self.resolved_device,
|
||
use_doc_orientation_classify=self.config.use_doc_orientation_classify,
|
||
use_doc_unwarping=self.config.use_doc_unwarping,
|
||
use_textline_orientation=self.config.use_textline_orientation,
|
||
text_recognition_batch_size=self.config.text_recognition_batch_size,
|
||
)
|
||
```
|
||
|
||
建议默认配置：
|
||
|
||
| 参数 | 建议默认值 | 说明 |
|
||
|---|---:|---|
|
||
| `ocr_version` | `PP-OCRv6` | 显式锁定版本，避免依赖升级后默认值变化 |
|
||
| `lang` | `ch` | 主要面向中英文混合文档 |
|
||
| `use_doc_orientation_classify` | `true` | 处理整页旋转 |
|
||
| `use_doc_unwarping` | `false` | 默认关闭以降低加载和推理开销，可通过参数开启 |
|
||
| `use_textline_orientation` | `true` | 处理倒置文本行 |
|
||
| `text_recognition_batch_size` | `6` | 与默认配置保持一致，后续按设备调优 |
|
||
| `text_rec_score_thresh` | `0.0` | 保留原始结果，输出层可另设过滤阈值 |
|
||
|
||
所有模型选项必须记录到 Benchmark 和 PDF manifest 中，以保证结果可追溯并支持安全续传。
|
||
|
||
### 7.3 统一内部结果模型
|
||
|
||
建议将 PaddleOCR 原始结果转换为以下项目内部结构：
|
||
|
||
```json
|
||
{
|
||
"schema_version": 1,
|
||
"source_type": "image_ocr",
|
||
"input_path": "data/images/example.jpg",
|
||
"page_index": 0,
|
||
"model": {
|
||
"ocr_version": "PP-OCRv6",
|
||
"detection_model": "PP-OCRv6_medium_det",
|
||
"recognition_model": "PP-OCRv6_medium_rec",
|
||
"language": "ch"
|
||
},
|
||
"image": {
|
||
"width": 1920,
|
||
"height": 1080
|
||
},
|
||
"lines": [
|
||
{
|
||
"index": 1,
|
||
"text": "示例文本",
|
||
"score": 0.9876,
|
||
"polygon": [[10, 20], [200, 20], [200, 50], [10, 50]],
|
||
"box": [10, 20, 200, 50],
|
||
"orientation": 0
|
||
}
|
||
],
|
||
"summary": {
|
||
"detected_lines": 1,
|
||
"non_empty_lines": 1,
|
||
"mean_score": 0.9876,
|
||
"min_score": 0.9876
|
||
}
|
||
}
|
||
```
|
||
|
||
内部结果模型应满足：
|
||
|
||
- 不依赖 PaddleOCR 私有类；
|
||
- 所有 NumPy 类型转换为标准 Python 类型；
|
||
- 字段稳定，可用于测试和后续 API 服务；
|
||
- 保留坐标和置信度；
|
||
- 原始 PaddleOCR JSON 可选择另存为 `raw-result.json`，但不作为项目主接口。
|
||
|
||
### 7.4 文本阅读顺序
|
||
|
||
PP-OCRv6 已对检测框进行基础排序，但复杂多栏文档的阅读顺序仍可能不符合人类阅读习惯。
|
||
|
||
第一阶段建议：
|
||
|
||
1. 使用模型结果顺序；
|
||
2. 按顺序写入 TXT 和简单 Markdown；
|
||
3. JSON 中完整保留坐标；
|
||
4. 不承诺复杂多栏和表格的语义顺序。
|
||
|
||
如后续需要增强，可增加可选的坐标排序策略：
|
||
|
||
- 单栏：从上到下、从左到右；
|
||
- 多栏：先聚类列，再逐列排序；
|
||
- 表格：交由专用表格结构识别模块处理。
|
||
|
||
---
|
||
|
||
## 8. 图片处理方案
|
||
|
||
### 8.1 处理流程
|
||
|
||
```text
|
||
校验图片类型
|
||
↓
|
||
延迟加载 PP-OCRv6
|
||
↓
|
||
可选预热
|
||
↓
|
||
执行 N 轮推理
|
||
↓
|
||
结果适配和统计
|
||
↓
|
||
输出 TXT/MD/JSON/可视化/Benchmark
|
||
```
|
||
|
||
### 8.2 输出目录
|
||
|
||
```text
|
||
outputs/images/<图片名_扩展名>/
|
||
├── result.txt
|
||
├── result.md
|
||
├── result.json
|
||
├── raw-result.json # 可选
|
||
├── visualization.jpg # 可选
|
||
└── benchmark.json
|
||
```
|
||
|
||
### 8.3 Markdown 输出定义
|
||
|
||
PP-OCRv6 不提供版面语义，因此 `result.md` 应明确定位为“便于阅读的文字结果”，例如：
|
||
|
||
```markdown
|
||
# example.jpg
|
||
|
||
示例文本第一行
|
||
|
||
示例文本第二行
|
||
```
|
||
|
||
不应伪造标题、表格、图片引用等模型未识别出的结构。
|
||
|
||
### 8.4 Benchmark 指标
|
||
|
||
建议记录：
|
||
|
||
- Paddle 导入时间；
|
||
- 运行时配置时间；
|
||
- 模型初始化时间；
|
||
- 预热时间；
|
||
- 每轮推理时间；
|
||
- 结果适配时间；
|
||
- 导出时间；
|
||
- 文件总耗时；
|
||
- 检测文本行数；
|
||
- 非空文本行数；
|
||
- 平均、最小、最大置信度；
|
||
- CPU 线程数；
|
||
- GPU 显存信息；
|
||
- 模型名称、语言和预处理开关。
|
||
|
||
---
|
||
|
||
## 9. PDF 处理方案
|
||
|
||
### 9.1 复用策略
|
||
|
||
参考项目的 PDF 文本层提取、质量判断、页码解析、渲染、manifest 和断点续传逻辑与具体 OCR 模型耦合较低，建议保留。
|
||
|
||
需要重写的部分主要是：
|
||
|
||
- OCR 页结果解析；
|
||
- OCR 页 Markdown 生成；
|
||
- OCR 页 JSON 结构；
|
||
- 页面统计字段；
|
||
- manifest 中的模型配置和结果摘要。
|
||
|
||
### 9.2 混合处理流程
|
||
|
||
```text
|
||
打开 PDF
|
||
↓
|
||
逐页提取文本层并评估质量
|
||
├── 文本层有效：直接保存文本
|
||
└── 文本层无效：渲染为 PNG → PP-OCRv6
|
||
↓
|
||
保存逐页 MD/JSON
|
||
↓
|
||
更新 manifest
|
||
↓
|
||
合并 document.md/document.json
|
||
```
|
||
|
||
### 9.3 PDF 模式
|
||
|
||
| 模式 | 行为 |
|
||
|---|---|
|
||
| `hybrid` | 默认。优先使用有效文本层，必要时才 OCR |
|
||
| `text` | 只提取文本层，不加载模型 |
|
||
| `ocr` | 所有选中页面均渲染并执行 PP-OCRv6 |
|
||
|
||
### 9.4 PDF 输出目录
|
||
|
||
```text
|
||
outputs/pdfs/<PDF名>/
|
||
├── manifest.json
|
||
├── document.md
|
||
├── document.json
|
||
├── pages/
|
||
│ ├── page-0001.md
|
||
│ ├── page-0001.json
|
||
│ └── ...
|
||
├── visualizations/ # 可选
|
||
└── rendered/ # 仅 --keep-rendered 时保留
|
||
```
|
||
|
||
### 9.5 断点续传兼容性
|
||
|
||
建议为 PP-OCRv6 项目设置独立的 manifest 版本，例如：
|
||
|
||
```json
|
||
{
|
||
"manifest_version": 1,
|
||
"pipeline": "PP-OCRv6",
|
||
"model_config": {
|
||
"language": "ch",
|
||
"detection_model": "PP-OCRv6_medium_det",
|
||
"recognition_model": "PP-OCRv6_medium_rec",
|
||
"use_doc_orientation_classify": true,
|
||
"use_doc_unwarping": false,
|
||
"use_textline_orientation": true
|
||
}
|
||
}
|
||
```
|
||
|
||
恢复任务时至少校验：
|
||
|
||
- PDF SHA-256；
|
||
- PDF 模式；
|
||
- 页面渲染 DPI；
|
||
- 文本层质量阈值；
|
||
- PP-OCRv6 模型名称；
|
||
- 语言；
|
||
- 文档方向、去畸变、文本行方向开关；
|
||
- 识别置信度阈值；
|
||
- manifest 版本。
|
||
|
||
任一关键配置变化时，应拒绝直接续传并提示使用 `--overwrite`。
|
||
|
||
---
|
||
|
||
## 10. CLI 设计
|
||
|
||
### 10.1 基础命令
|
||
|
||
```bash
|
||
python ocr.py data/images/example.jpg --device cpu
|
||
python ocr.py data/documents/example.pdf --device cpu
|
||
python ocr.py data/ --recursive --device cpu
|
||
python ocr.py verify --device gpu
|
||
```
|
||
|
||
### 10.2 建议保留的参数
|
||
|
||
```text
|
||
--device cpu|gpu
|
||
--device-id 0
|
||
--threads N
|
||
--recursive
|
||
--output PATH
|
||
--fail-fast
|
||
--warmup N
|
||
--rounds N
|
||
--benchmark-json PATH
|
||
--pdf-mode hybrid|text|ocr
|
||
--pages "1-5,8,10-"
|
||
--dpi 144
|
||
--password PASSWORD
|
||
--resume
|
||
--overwrite
|
||
--keep-rendered
|
||
--log-file PATH
|
||
--verbose
|
||
```
|
||
|
||
### 10.3 PP-OCRv6 新参数
|
||
|
||
```text
|
||
--lang ch
|
||
--text-rec-score-thresh 0.0
|
||
--text-det-limit-side-len N
|
||
--text-det-limit-type min|max
|
||
--text-det-thresh 0.3
|
||
--text-det-box-thresh 0.6
|
||
--text-det-unclip-ratio 1.5
|
||
--text-recognition-batch-size 6
|
||
--return-word-box
|
||
--use-doc-orientation-classify / --no-doc-orientation-classify
|
||
--use-doc-unwarping / --no-doc-unwarping
|
||
--use-textline-orientation / --no-textline-orientation
|
||
--save-visualization
|
||
--save-raw-result
|
||
```
|
||
|
||
### 10.4 应删除的 VLM 专用参数
|
||
|
||
以下参数属于 PaddleOCR-VL 生成式推理，不适用于 PP-OCRv6，应从新项目中移除：
|
||
|
||
```text
|
||
--max-new-tokens
|
||
--min-pixels
|
||
--max-pixels
|
||
```
|
||
|
||
---
|
||
|
||
## 11. CPU/GPU 环境方案
|
||
|
||
### 11.1 CPU
|
||
|
||
建议首先沿用参考项目已验证组合：
|
||
|
||
```toml
|
||
[project]
|
||
requires-python = ">=3.13"
|
||
dependencies = [
|
||
"paddleocr==3.7.0",
|
||
"paddlepaddle==3.2.1",
|
||
"pypdfium2>=5.11.0",
|
||
"setuptools>=83.0.0",
|
||
]
|
||
```
|
||
|
||
如果可视化功能需要 OpenCV，应通过 PaddleOCR/PaddleX 实际依赖验证后补充对应包，避免同时安装冲突的 OpenCV 变体。
|
||
|
||
安装：
|
||
|
||
```bash
|
||
uv sync --project cpu
|
||
```
|
||
|
||
### 11.2 GPU
|
||
|
||
GPU 项目继续独立管理：
|
||
|
||
```toml
|
||
[project]
|
||
requires-python = ">=3.11,<3.13"
|
||
dependencies = [
|
||
"paddleocr==3.7.0",
|
||
"paddlepaddle-gpu==3.2.1",
|
||
"pypdfium2>=5.11.0",
|
||
"setuptools>=83.0.0",
|
||
]
|
||
```
|
||
|
||
GPU Wheel 不能仅依赖默认 PyPI 解析，应沿用 `gpu/setup_env.py`，按 PaddlePaddle 官方 CUDA 兼容矩阵选择安装源。
|
||
|
||
安装完成后生成 `gpu/.gpu-ready`，统一入口仅允许调用已完成安装的 GPU 环境。
|
||
|
||
### 11.3 模型缓存
|
||
|
||
首次运行时可能下载多个模型，包括：
|
||
|
||
- PP-OCRv6 检测模型；
|
||
- PP-OCRv6 识别模型；
|
||
- 文档方向分类模型；
|
||
- 文本行方向模型；
|
||
- 开启去畸变时的去畸变模型。
|
||
|
||
实施时应：
|
||
|
||
1. 在 README 中说明首次启动需要网络和下载时间；
|
||
2. 记录模型缓存位置；
|
||
3. 支持通过模型目录参数加载离线模型；
|
||
4. 在正式部署前预下载并执行一次冷启动验证；
|
||
5. 不将模型权重提交到 Git。
|
||
|
||
---
|
||
|
||
## 12. 代码复用与改造清单
|
||
|
||
### 12.1 可直接或小幅复用
|
||
|
||
| 参考文件 | 复用程度 | 调整内容 |
|
||
|---|---|---|
|
||
| `ocr.py` | 高 | 修改项目提示文字 |
|
||
| `ocr_app/logging_utils.py` | 高 | 基本可直接复用 |
|
||
| `ocr_app/pdf_text.py` | 高 | 基本可直接复用 |
|
||
| `ocr_app/cli.py` | 中 | 替换模型参数 |
|
||
| `ocr_app/commands.py` | 中 | 替换图片结果统计和推理参数 |
|
||
| `ocr_app/pdf.py` | 中 | 替换 OCR 页结果解析和导出 |
|
||
| `cpu/runner.py` | 高 | 基本可直接复用 |
|
||
| `gpu/runner.py` | 高 | 基本可直接复用 |
|
||
| `gpu/setup_env.py` | 高 | 修改项目名称并重新验证 |
|
||
| 测试基础设施 | 高 | 保留假模型和临时目录模式 |
|
||
|
||
### 12.2 必须重写
|
||
|
||
| 模块 | 原因 |
|
||
|---|---|
|
||
| `ocr_app/runtime.py` 的模型创建部分 | `PaddleOCRVL` 改为 `PaddleOCR` |
|
||
| 图片结果摘要 | 不再存在 `parsing_res_list` 和 `layout_det_res` |
|
||
| `ocr_app/output.py` 的 Markdown 导出 | PP-OCRv6 没有 `result.markdown` |
|
||
| PDF OCR 页导出 | 需基于 `rec_texts/rec_scores/rec_polys` 生成 |
|
||
| Benchmark 统计 | 从版面块统计改为文本行和置信度统计 |
|
||
| 模型参数和日志字段 | 删除 VLM 参数，增加检测/识别参数 |
|
||
|
||
### 12.3 不建议机械复制
|
||
|
||
不建议直接复制整个 `../ocr-VL1.6` 后仅替换模型类名，原因包括：
|
||
|
||
- 输出代码强依赖 `result.markdown`；
|
||
- 纯文本生成强依赖 `parsing_res_list`；
|
||
- Benchmark 强依赖版面框和解析块；
|
||
- PDF 页面统计强依赖 `layout_det_res`；
|
||
- VLM 参数会被错误传给 PP-OCRv6；
|
||
- 断点续传 manifest 未记录 PP-OCRv6 的关键配置。
|
||
|
||
推荐做法是复用工程骨架，同时新建明确的 PP-OCRv6 结果适配层。
|
||
|
||
---
|
||
|
||
## 13. 实施步骤
|
||
|
||
### 阶段一：工程骨架与环境
|
||
|
||
1. 从参考项目选择性迁移目录结构；
|
||
2. 创建根入口、CPU/GPU runner；
|
||
3. 建立 CPU/GPU `pyproject.toml`；
|
||
4. 迁移日志、PDF 文本层和基础工具；
|
||
5. 完成 `verify` 命令；
|
||
6. 验证 CPU PaddlePaddle 和 PaddleOCR 版本。
|
||
|
||
交付物：
|
||
|
||
- CPU 环境可安装；
|
||
- `python ocr.py verify --device cpu` 成功；
|
||
- GPU 不可用时有明确提示且不回退 CPU。
|
||
|
||
### 阶段二：单图片 OCR
|
||
|
||
1. 实现 PP-OCRv6 延迟加载；
|
||
2. 实现单图片推理；
|
||
3. 实现 `result_adapter.py`；
|
||
4. 输出 TXT、MD、JSON；
|
||
5. 实现 Benchmark；
|
||
6. 增加可选可视化输出。
|
||
|
||
交付物：
|
||
|
||
- 中文、英文、旋转文本样例识别成功；
|
||
- 坐标和置信度正确写入 JSON；
|
||
- 多轮 Benchmark 可用。
|
||
|
||
### 阶段三：目录批处理
|
||
|
||
1. 迁移后缀路由；
|
||
2. 复用单模型实例；
|
||
3. 保持串行处理；
|
||
4. 处理递归目录和同名文件；
|
||
5. 生成批次汇总 JSON；
|
||
6. 验证单文件失败不会污染其他结果。
|
||
|
||
交付物：
|
||
|
||
- 图片目录可批量处理；
|
||
- 输出保留相对目录；
|
||
- 批次结果可追溯。
|
||
|
||
### 阶段四：PDF 混合模式
|
||
|
||
1. 接入文本层质量判断；
|
||
2. 实现扫描页渲染与 PP-OCRv6 推理；
|
||
3. 实现逐页 TXT/MD/JSON；
|
||
4. 实现整文档合并；
|
||
5. 实现 manifest 和断点续传；
|
||
6. 验证电子 PDF 不加载模型。
|
||
|
||
交付物：
|
||
|
||
- `hybrid`、`text`、`ocr` 模式可用；
|
||
- 可选择页码；
|
||
- 中断后可恢复；
|
||
- 配置不一致时拒绝错误续传。
|
||
|
||
### 阶段五：GPU、性能与文档
|
||
|
||
1. 在 NVIDIA GPU 机器安装环境；
|
||
2. 执行 GPU Smoke Test；
|
||
3. 测试冷启动、热启动和批量吞吐；
|
||
4. 调整识别 Batch Size；
|
||
5. 评估方向分类和去畸变的性能影响；
|
||
6. 完善 README、故障排查和部署说明。
|
||
|
||
交付物：
|
||
|
||
- CPU/GPU Benchmark 对比；
|
||
- GPU 显存使用记录；
|
||
- 明确推荐参数。
|
||
|
||
---
|
||
|
||
## 14. 测试方案
|
||
|
||
### 14.1 单元测试
|
||
|
||
建议至少覆盖：
|
||
|
||
- 输入类型识别；
|
||
- 支持后缀发现；
|
||
- 页码范围解析；
|
||
- 文本层质量判断；
|
||
- PP-OCRv6 原始结果归一化；
|
||
- 空识别结果处理；
|
||
- NumPy 类型 JSON 序列化；
|
||
- TXT/Markdown 生成；
|
||
- 输出目录命名；
|
||
- 递归目录相对路径；
|
||
- manifest 参数一致性校验；
|
||
- CPU/GPU 根入口路由。
|
||
|
||
### 14.2 集成测试
|
||
|
||
建议准备以下样例：
|
||
|
||
| 样例 | 目的 |
|
||
|---|---|
|
||
| 中文印刷体图片 | 基础识别 |
|
||
| 中英文混合名片 | 多语言和小字号 |
|
||
| 90°/180° 旋转图片 | 方向分类 |
|
||
| 透视拍摄文档 | 去畸变开关 |
|
||
| 手写图片 | 能力边界测试 |
|
||
| 纯电子 PDF | 验证不加载 OCR 模型 |
|
||
| 纯扫描 PDF | 验证逐页 OCR |
|
||
| 混合 PDF | 验证按页路由 |
|
||
| 加密 PDF | 密码处理 |
|
||
| 多页大 PDF | 断点续传和稳定性 |
|
||
| 多栏文档 | 验证阅读顺序限制 |
|
||
| 表格文档 | 明确非结构化输出边界 |
|
||
|
||
### 14.3 假模型测试
|
||
|
||
与参考项目一致，应使用假模型完成大多数工程测试，避免测试过程下载模型或消耗大量推理时间。
|
||
|
||
假结果至少包含：
|
||
|
||
```python
|
||
{
|
||
"rec_texts": ["第一行", "第二行"],
|
||
"rec_scores": [0.98, 0.95],
|
||
"rec_polys": [...],
|
||
"rec_boxes": [...],
|
||
}
|
||
```
|
||
|
||
### 14.4 性能测试
|
||
|
||
分别记录：
|
||
|
||
- 首次模型下载时间；
|
||
- 冷启动模型初始化时间；
|
||
- 单图热推理时间；
|
||
- 100 张图片串行总耗时；
|
||
- 10 页扫描 PDF 总耗时；
|
||
- CPU 不同线程数；
|
||
- GPU 不同识别 Batch Size；
|
||
- 开启/关闭文档方向分类；
|
||
- 开启/关闭去畸变；
|
||
- 开启/关闭文本行方向分类。
|
||
|
||
Benchmark 必须标注输入尺寸、DPI、硬件和模型配置，否则不同结果不可直接比较。
|
||
|
||
---
|
||
|
||
## 15. 风险与应对
|
||
|
||
### 风险一：输出能力被误认为与 PaddleOCR-VL 等价
|
||
|
||
**影响：高。**
|
||
|
||
应对：
|
||
|
||
- README 明确 PP-OCRv6 是文字检测识别管线；
|
||
- `result.md` 标注为简单文本 Markdown；
|
||
- 不承诺表格、标题层级和复杂阅读顺序；
|
||
- 如业务确有结构化需求，另立 PP-Structure/文档解析增强阶段。
|
||
|
||
### 风险二：结果对象格式与参考项目不兼容
|
||
|
||
**影响：高。**
|
||
|
||
应对：
|
||
|
||
- 新建 `result_adapter.py`；
|
||
- 业务层只依赖内部结果模型；
|
||
- 使用假模型固定输出契约；
|
||
- 原始结果与归一化结果分开保存。
|
||
|
||
### 风险三：PP-OCRv6 语言支持有限
|
||
|
||
**影响：中。**
|
||
|
||
本地 PaddleOCR 3.7.0 的 PP-OCRv6 映射适用于中文、繁体中文、英文、日文及多数拉丁语种；韩文、阿拉伯文、部分西里尔文和印度语系等不应默认假设支持 PP-OCRv6。
|
||
|
||
应对：
|
||
|
||
- 默认 `lang=ch`；
|
||
- 启动时验证 `lang + ocr_version`；
|
||
- 不支持时给出明确错误；
|
||
- 如业务允许，可设计显式 `--allow-version-fallback` 回退 PP-OCRv5，但默认不应静默回退。
|
||
|
||
### 风险四：首次运行需要下载多个模型
|
||
|
||
**影响：中。**
|
||
|
||
应对：
|
||
|
||
- 增加部署前模型预热步骤；
|
||
- 支持离线模型目录；
|
||
- 在日志中记录下载和初始化阶段；
|
||
- 在生产环境提前准备缓存。
|
||
|
||
### 风险五：CPU 性能受辅助模型影响
|
||
|
||
**影响：中。**
|
||
|
||
默认 OCR 管线可能同时加载方向分类、文本行方向和去畸变模型。
|
||
|
||
应对：
|
||
|
||
- 默认关闭去畸变；
|
||
- 对方向正常的批量扫描件提供轻量配置；
|
||
- 分别 Benchmark 各开关；
|
||
- 不以单个样例推断整体性能。
|
||
|
||
### 风险六：GPU 环境未实机验证
|
||
|
||
**影响：中。**
|
||
|
||
应对：
|
||
|
||
- 保留严格的 GPU 就绪标记；
|
||
- 不允许 GPU 失败后自动回退 CPU；
|
||
- 在目标机器验证 CUDA、驱动和 Paddle Wheel；
|
||
- 记录实际显存和吞吐。
|
||
|
||
### 风险七：复杂 PDF 阅读顺序不准确
|
||
|
||
**影响：中。**
|
||
|
||
应对：
|
||
|
||
- 第一阶段保留坐标并按模型顺序输出；
|
||
- 对多栏和表格文档在验收中标记能力边界；
|
||
- 后续按业务需求增加版面排序或结构识别，而非在基础 OCR 中堆叠启发式规则。
|
||
|
||
---
|
||
|
||
## 16. 验收标准
|
||
|
||
### 16.1 功能验收
|
||
|
||
- [ ] `python ocr.py verify --device cpu` 成功；
|
||
- [ ] 单张图片可输出 TXT、MD、JSON 和 Benchmark；
|
||
- [ ] JSON 包含文本、置信度和坐标；
|
||
- [ ] 目录模式可处理图片和 PDF；
|
||
- [ ] 递归目录输出不会因同名文件互相覆盖；
|
||
- [ ] PDF `hybrid` 模式能区分电子文本页和扫描页；
|
||
- [ ] 纯电子 PDF 不初始化 PP-OCRv6；
|
||
- [ ] PDF 可按页处理并支持断点续传；
|
||
- [ ] `--overwrite` 可安全重做；
|
||
- [ ] GPU 环境不可用时明确失败且不回退 CPU；
|
||
- [ ] 日志、JSON 和中文路径均使用 UTF-8；
|
||
- [ ] 中断或单文件失败后已有结果保持完整。
|
||
|
||
### 16.2 质量验收
|
||
|
||
- [ ] 内部结果模型有固定 `schema_version`；
|
||
- [ ] 模型原始结果不直接泄漏到业务层；
|
||
- [ ] 关键文件写入采用原子替换；
|
||
- [ ] manifest 记录完整模型配置；
|
||
- [ ] 配置变化时不能错误续传；
|
||
- [ ] 单元测试覆盖核心路由、输出、PDF 和恢复逻辑；
|
||
- [ ] 文档明确说明 PP-OCRv6 与 PaddleOCR-VL 的能力差异。
|
||
|
||
### 16.3 性能验收
|
||
|
||
性能目标不应在缺少目标硬件数据时设置绝对秒数。第一版建议以参考基线方式验收：
|
||
|
||
- [ ] 同一批次只初始化一次模型；
|
||
- [ ] 纯电子 PDF 不产生模型初始化耗时；
|
||
- [ ] 批量任务默认串行，不出现无控制的多进程；
|
||
- [ ] Benchmark 可分离模型初始化、推理和导出耗时；
|
||
- [ ] CPU/GPU 结果均记录完整硬件与参数信息；
|
||
- [ ] 连续处理大批量文件时内存无持续明显增长。
|
||
|
||
---
|
||
|
||
## 17. 工作量预估
|
||
|
||
在复用参考项目工程逻辑、且第一阶段不增加表格结构识别和复杂版面分析的前提下，建议工作量如下：
|
||
|
||
| 阶段 | 预估 |
|
||
|---|---:|
|
||
| 工程骨架和 CPU/GPU 环境 | 0.5～1 人日 |
|
||
| PP-OCRv6 运行时和单图结果适配 | 1～1.5 人日 |
|
||
| 图片输出、Benchmark、批处理 | 0.5～1 人日 |
|
||
| PDF 混合模式和断点续传适配 | 1～1.5 人日 |
|
||
| 自动化测试 | 1～1.5 人日 |
|
||
| GPU 实机验证、性能调优和文档 | 0.5～1 人日 |
|
||
| **合计** | **4.5～7.5 人日** |
|
||
|
||
如果增加以下能力，需单独评估：
|
||
|
||
- 表格结构识别；
|
||
- 多栏阅读顺序恢复；
|
||
- PP-Structure 集成；
|
||
- HTTP API/队列服务；
|
||
- 多 GPU 调度；
|
||
- TensorRT/HPI 加速；
|
||
- 离线模型打包和安装程序。
|
||
|
||
---
|
||
|
||
## 18. 推荐决策
|
||
|
||
推荐采用以下决策：
|
||
|
||
1. **确认立项**：PP-OCRv6 可满足通用本地文字识别需求；
|
||
2. **复用工程骨架，不机械复制模型输出代码**；
|
||
3. **新增统一结果适配层**，隔离 PaddleOCR 原始结果；
|
||
4. **第一阶段聚焦 TXT、简单 Markdown、JSON、坐标和置信度**；
|
||
5. **保留 PDF 混合模式**，这是参考项目中最有价值且与模型无关的能力；
|
||
6. **支持 `tiny`、`small`、`medium` 三种模型规格，默认使用 `PP-OCRv6_medium_det + PP-OCRv6_medium_rec`**；
|
||
7. **默认中文模式、开启方向分类、关闭文档去畸变**，后续根据 Benchmark 调整；
|
||
8. **GPU 必须实机验收，不声明未经验证的性能结论**；
|
||
9. **将版面分析和表格结构识别作为独立增强阶段**，避免基础 OCR 项目范围失控。
|
||
|
||
最终判断：
|
||
|
||
> 以 `../ocr-VL1.6` 为工程参考，建设 PP-OCRv6 图片、PDF 和批量本地 OCR 项目，在技术和工程上均可行；主要改造点集中在模型初始化、结果适配、输出生成和统计指标。只要接受 PP-OCRv6 不等价于 PaddleOCR-VL 文档解析能力这一边界，方案风险可控，且预期具有更低资源消耗和更好的通用 OCR 吞吐能力。
|