# PP-OCRv5 / PP-StructureV3 能力验证报告

验证时间：2026-05-08  
生产 OCR 服务：`http://192.168.1.13:18080/layout-parsing`  
生产 PP-ChatOCR 视觉服务：`http://192.168.1.13:18083/chatocr-visual`  
样本图片：`doc/56CDF923B8CAE7000FE3274C10ECBC0C.jpg`

## 0. 当前落地状态

截至 2026-05-08，系统已经接入 PP-ChatOCR 的视觉分析和字段抽取服务：

- `maodou-ppchatocr` 容器已在 13 服务器启动，端口映射为 `18083:8080`。
- 后端已调整为键值对优先链路：`/layout-parsing` 负责主文本、主表格和兜底键值对，`/chatocr-visual` 只作为可选视觉诊断旁路，用于人眼初步评估和对照查看。
- 后端已接入 `/chatocr-chat`：先从表单模板字段、PP-StructureV3 表格候选键和通用政务表单字段生成 `keyList`，再结合 `/chatocr-visual` 返回的 `visualInfo` 调用 PP-ChatOCR 做语义键值抽取。
- `/chatocr-chat` 依赖大模型。后端支持通过 `PADDLEOCR_CHAT_BOT_MODEL_NAME`、`PADDLEOCR_CHAT_BOT_BASE_URL`、`PADDLEOCR_CHAT_BOT_API_TYPE`、`PADDLEOCR_CHAT_BOT_API_KEY` 向 PP-ChatOCR 传递 OpenAI 兼容的 `chatBotConfig`。
- OCR 识别详情页已展示 PP-ChatOCR 返回的可视化图片，用于第一眼评估版面检测、OCR 框和表格单元格识别效果。
- 识别详情页已展示清洗后的键值对列表，并单独提供 `ChatOCR抽取` 页签；若 `chatResult` / `chat_res` 存在，会与表格 HTML、文本行兜底候选一起展示，便于对比准确率和覆盖率。

当前样张 `T20260508095229-da42a731` 曾验证出一个重要问题：

- 耗时：约 12 秒
- OCR 文本块：69
- 表格块：2
- 可视化图：4 张
- 清洗键值对：1 个，来源为 `table_fallback`

该任务只返回 1 个键值对的原因是 `/chatocr-visual` 只把底部“二、变更情形”识别成表格，没有把主表识别成表格；而旧任务 `T20260508085659-560260b5` 通过 `/layout-parsing` 识别到了整张主表，可以兜底抽出 12 个键值对。因此生产链路应保持 `/layout-parsing` 为结构主链路，可视化结果只做人工对照参考。PP-ChatOCR 的语义键值对能力应通过 `/chatocr-chat` 验证，而不是只看 `/chatocr-visual`。

## 1. 当前服务确认

当前生产容器确实在使用 PaddleOCR 3.x 体系下的 PP-OCRv5 文本检测和识别模型，不是 OCRv4。

- 容器：`maodou-paddleocr`
- 镜像：`maodou-paddleocr:ppstructurev3-gpu`
- 启动命令：`paddlex --serve --pipeline /app/PP-StructureV3.form.yaml --device gpu:0`
- PaddleOCR：`3.5.99`
- PaddlePaddle：`3.2.0`
- GPU：已启用，容器内设备为 `gpu:0`
- 文本检测模型：`PP-OCRv5_server_det`
- 文本识别模型：`PP-OCRv5_server_rec`

## 2. 官方能力边界

PP-StructureV3 的定位是复杂文档解析。它会输出版面块、文本行、坐标、表格结构、表格 HTML、单元格坐标、Markdown 等结构化文档数据。

它不是“语义字段抽取”产线，本身不会直接给出稳定的业务字段键值对，例如：

```json
{
  "经营者名称": "xxx",
  "证件号码": "xxx"
}
```

PaddleOCR 体系里更接近这个目标的是两类能力：

- `PP-ChatOCR`：结合 OCR、版面分析、LLM、MLLM、检索，按给定 `key_list` 抽取信息，示例输出是 `{"驾驶室准乘人数": "2"}`。
- `KIE / SER / RE`：关键信息抽取，属于 OCR 下游任务，通过语义实体识别和关系抽取建立字段关系，通常需要场景数据标注或训练/微调。

因此，如果目标是“少造轮子”，优先评估顺序应该是：

1. 先完整保存和展示 PP-StructureV3 原生结果。
2. 已接入 PP-ChatOCR 的 `/chatocr-chat`，下一步重点是用真实样张对比 `chatResult` 与 PP-StructureV3 结构候选的覆盖率、准确率。
3. 如果 PP-ChatOCR 对我们的表单不稳定，再考虑 KIE 小样本训练或轻量规则兜底。

## 3. 本次样本 A/B 结果

### 3.1 默认调用

后端当前只传 `file` 和 `fileType`。服务返回中显示实际启用了 `use_doc_preprocessor=true`。

- 耗时：约 21.55 秒
- OCR 文本行：66
- 平均置信度：0.9694
- 最低置信度：0.5064
- 版面块：2 个，`figure_title` + `table`
- 表格：1 个
- 表格 HTML 单元格：33 个
- 原生语义键值对：无

典型识别结果：

```text
产请衣（令售证许可类事项）
一、申请人基本情况
申请类型
新办
□变更□延续
花厂
企业名称/个体工
广西浦北县泉水华盛烟
统一社会信用代
商户名称
91450722201221829R
```

问题：标题被识别成 `产请衣（令售证许可类事项）`，说明文档矫正后对这张拍照手写样本不一定更好。

### 3.2 显式关闭文档预处理

请求显式设置：

```json
{
  "useDocOrientationClassify": false,
  "useDocUnwarping": false,
  "useTextlineOrientation": true,
  "useTableRecognition": true,
  "useRegionDetection": true,
  "formatBlockContent": false
}
```

结果：

- 耗时：约 4.28 秒
- OCR 文本行：68
- 平均置信度：0.9746
- 最低置信度：0.7652
- 版面块：2 个，`figure_title` + `table`
- 表格：1 个
- 表格 HTML 单元格：42 个
- 原生语义键值对：无

典型识别结果：

```text
申请表（零售证许可类事项）
一、申请人基本情况
申请类型
新办
□变更
□延续
花厂
广西浦北县泉水华盛烟
统一社会信用代
企业名称/个体工
91450722201221829R
码
商户名称
```

优点：标题识别正确，平均置信度更高，最低置信度也明显提高。  
问题：表格 HTML 的行列关系有部分错位，例如部分行出现字段和值顺序颠倒。

### 3.3 拍照增强配置

请求显式设置：

```json
{
  "useDocOrientationClassify": true,
  "useDocUnwarping": true,
  "useTextlineOrientation": true,
  "useTableRecognition": true,
  "useRegionDetection": true,
  "formatBlockContent": true
}
```

结果与默认调用基本一致：

- 耗时：约 12.82 秒
- OCR 文本行：66
- 平均置信度：0.9694
- 最低置信度：0.5064
- 版面块：2 个，`figure_title` + `table`
- 表格：1 个
- 表格 HTML 单元格：33 个
- 原生语义键值对：无

`formatBlockContent=true` 主要影响 `block_content` 的 HTML/Markdown 格式化，不会把表单内容转换成业务键值对。

### 3.4 全部模块打开

直接在当前服务请求中打开印章、公式、图表等所有能力时，服务返回 500。日志原因：

```text
Set use_seal_recognition, but the models for seal recognition are not initialized.
```

原因是当前服务启动配置关闭了印章、公式、图表等可选子产线，请求时不能临时启用未初始化模型。若要真正测试“全模块打开”，需要单独启动一个评估容器或重启 OCR 服务并预加载这些模型。

对当前表单填报场景来说，印章、公式、图表不是核心能力；更关键的是表格、文本行、坐标、阅读顺序和字段抽取。

## 4. PaddleOCR 原生返回能给我们的数据

当前 PP-StructureV3 原生返回里有价值的是这些结构：

- `parsing_res_list`：版面块列表，包含 `block_label`、`block_bbox`、`block_content`、`block_order`
- `overall_ocr_res.rec_texts`：全文 OCR 文本行
- `overall_ocr_res.rec_scores`：每个文本行置信度
- `overall_ocr_res.rec_polys` / `rec_boxes`：每个文本行坐标
- `table_res_list[].pred_html`：表格结构 HTML
- `table_res_list[].cell_box_list`：表格单元格坐标
- `table_res_list[].table_ocr_pred.rec_texts`：表格区域内文本
- `markdown.text`：可读文档内容
- `outputImages`：可视化图片，如 OCR 框、版面检测、表格单元格检测

它没有直接输出字段语义关系，例如“这个文本是字段名、右侧那个文本是字段值”。这部分需要 PP-ChatOCR、KIE，或者我们自己的轻量结构化层。

## 5. 初步结论

1. 当前服务确实是 PP-OCRv5 server 检测/识别模型。
2. 对这张拍照手写表单，`文档方向分类 + 图像矫正` 不一定提升识别，反而让标题识别变差。
3. 显式关闭文档预处理后，纯文字识别更好，但表格结构关系可能更乱。
4. PP-StructureV3 能给出很好的 OCR 元数据和表格结构，但不会直接给业务键值对。
5. 想尽量少造轮子，下一步应重点评估 PP-ChatOCR `/chatocr-chat` 的实际输出：给它我们关心的字段清单，让它基于 `/chatocr-visual` 的视觉信息、表格信息和大模型抽取键值对。
6. 如果 PP-ChatOCR 抽取效果稳定，我们的系统只需要做字段清单管理、置信度展示、人工校验和最终回填。
7. 如果 PP-ChatOCR 抽取效果不稳定，再进入 KIE/SER/RE 或轻量规则层。

## 6. 建议下一步

短期建议做一个“PaddleOCR 原生结果查看”页面或详情面板，先让用户看到模型原始能力。当前已完成第一版：

- OCR 文本行列表，带置信度和坐标
- 表格 HTML 预览
- 表格单元格列表
- Markdown 文本
- 原生 JSON 折叠查看
- 可视化图片：版面检测、OCR 框、表格单元格检测
- 请求参数预设：默认、关闭预处理、拍照增强

当前已新增 PP-ChatOCR `/chatocr-chat` 评估链路：

- 输入图片
- 自动生成字段清单 `keyList`
- 输出模型抽取的键值对到 `ChatOCR抽取` 页签
- 与 PP-StructureV3 结构候选结果并排展示
- 人工标记正确/错误，用于后续选择是否训练 KIE 或微调策略