PP-DocBlockLayout_onnx Python API完全指南:从predict到save_to_json全流程
PP-DocBlockLayout_onnx Python API完全指南:从predict到save_to_json全流程
PP-DocBlockLayout 是 PaddlePaddle 推出的高精准文档版面块检测(layout detection)模型,基于 RT-DETR-L 训练,在自建中英文论文、PPT、杂志、合同、试卷等评测集上 mAP(0.5) 高达 95.9%。本文以这个 ONNX 版模型仓库为例,带你完整走一遍 PaddleOCR Python API 全流程:从安装依赖、构建 LayoutDetection 模型,到 predict 预测、save_to_json 导出结构化结果,新手 5 分钟即可上手。
一、认识 PP-DocBlockLayout:它能做什么?
📄 该模型专注于文档版面中的 Region(区域)检测,即自动找出页面中正文段落、图表、公式等版面块的边界框。它是文档智能解析(Document AI)的第一环:先定位区域,再对每个区域做 OCR 或分类。
仓库中只有 3 个核心文件,各自职责清晰:
| 文件 | 作用 |
|---|---|
| README.md | 模型介绍与使用方法(含 CLI 与 Python API 示例) |
| inference.onnx | ONNX 格式的模型权重(通过 Git LFS 托管) |
| inference.yml | 推理配置文件,定义输入尺寸、后处理阈值等 |
二、一键安装:环境准备
只需 2 条命令完成环境配置(CPU 环境将第二条换成 pip install -U onnxruntime 即可):
pip install -U paddleocr
pip install -U onnxruntime-gpu
💡
onnxruntime-gpu提供 GPU 加速;模型权重会在首次运行时由 PaddleOCR 自动下载,无需手动拷贝 inference.onnx。
三、构建 LayoutDetection 模型实例
使用 LayoutDetection 类构建模型,关键参数只有两个:
from paddleocr import LayoutDetection
model = LayoutDetection(
model_name="PP-DocBlockLayout", # 指定模型名称
engine="onnxruntime", # 指定 ONNX Runtime 推理引擎
)
常用参数说明:
| 参数 | 说明 |
|---|---|
model_name |
模型名称,固定为 PP-DocBlockLayout |
engine |
推理引擎,可选 onnxruntime / onnxruntime-gpu / paddle / tensorrt 等 |
device |
运行设备,如 cpu、gpu:0 |
text_score_threshold |
置信度过滤阈值,低于该值的检测框会被丢弃 |
四、调用 predict:一次调用完成版面检测
predict 接收图片路径(或路径列表),并通过 batch_size 控制批量大小,返回一个可迭代的输出序列:
output = model.predict("./demo.jpg", batch_size=1)
几个实用要点:
- ✅ 传入多张图时直接给路径列表,例如
model.predict(["a.jpg", "b.jpg"]); - ✅
batch_size越大吞吐越高,GPU 显存不足时可改回1; - ✅ 每次迭代得到的
res是一个结果对象,封装了检测框坐标、置信度与标签。
五、结果输出三件套:print / save_to_img / save_to_json
拿到 output 后,遍历结果对象即可完成展示与落盘——这就是从 predict 到 save_to_json 的完整闭环:
for res in output:
res.print() # 控制台打印检测结果
res.save_to_img(save_path="./output/") # 保存带框可视化图片
res.save_to_json(save_path="./output/res.json") # 导出结构化 JSON
1️⃣ res.print():快速查看结果
在终端直接打印检测到的区域数量、标签(Region)、bbox 坐标与置信度,适合调试阶段快速验证。
2️⃣ save_to_img():保存可视化图片
将检测框画在原图上并保存,直观确认模型是否"找对"了版面块位置。
3️⃣ save_to_json():导出机器可读的结构化数据
res.json 中记录了本次检测的完整信息:输入图片路径、每个检测框的 label(Region)、bbox(左上角/右下角坐标)和 score(置信度)等字段。这是接入下游 OCR、版面理解流水线的标准数据格式,也是"从 predict 到 save_to_json"全流程的终点。
六、读懂 inference.yml:模型配置里的关键信息
如果想深入了解模型行为,可以查看 inference.yml,其中有几处值得关注:
arch: DETR—— 基于 DETR 家族的检测架构;target_size: [640, 640]—— 推理前图片被缩放到 640×640,预处理固定为Resize+Permute;label_list: [Region]—— 模型只输出"Region"一类标签,专注版面区域定位;draw_threshold: 0.5—— 可视化时置信度的绘制阈值。
七、懒人替代方案:一条 CLI 命令
如果你不想写代码,PaddleOCR 也提供了命令行入口,效果与 Python API 等价:
paddleocr layout_detection -i ./demo.jpg --model_name PP-DocBlockLayout --engine onnxruntime
八、新手常见问题
Q1:报错 onnxruntime 找不到或版本不匹配?
重新执行 pip install -U onnxruntime-gpu,并确保 Python 与 onnxruntime 的位宽一致(如 64 位环境配 64 位包)。
Q2:检测框偏多或偏少,如何调节?
调整构建模型时的 text_score_threshold:调高更严格、调低更宽松。
Q3:ONNX 版和 Paddle 原版有区别吗?
本仓库提供的是 inference.onnx 权重,通过 engine="onnxruntime" 运行,无需安装 PaddlePaddle 框架,部署更轻量。
总结
本文以 PP-DocBlockLayout_onnx 模型仓库为主线,完整演示了 PaddleOCR Python API 的四步走流程:安装 → 构建 LayoutDetection → predict 检测 → save_to_json 导出。配合 README.md 中的示例与 inference.yml 中的配置说明,你就能把这张 95.9% mAP 的版面检测网,稳稳铺进自己的文档解析流水线。🚀