# 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 吞吐能力。