PP-Structure 文档分析系统实战指南：版面分析、表格识别、关键信息抽取与版面恢复

PP-Structure 文档分析系统实战指南：版面分析、表格识别、关键信息抽取与版面恢复

【免费下载链接】PaddleOCRTurn any PDF or image document into structured data for your AI. A powerful, lightweight OCR toolkit that bridges the gap between images/PDFs and LLMs. Supports 100+ languages.项目地址: https://gitcode.com/GitHub_Trending/pa/PaddleOCR

PP-Structure 是 PaddleOCR 团队自研的智能文档分析系统，本文以其系统总览文档（docs/version2.x/ppstructure/overview.md）为核心骨架，结合仓库中的快速开始、模型库、版面恢复等文档与 ppstructure 源码目录，完整讲解 PP-StructureV2 的系统流程、核心特性、命令行/Python 调用方式、返回结果格式与模型选型。读完本文，你将掌握如何把一张图片或 PDF 文档拆解为版面区域、结构化表格、关键信息乃至可编辑的 Word/PDF 文件，并知道每个能力对应的源码与模型在哪里。

1. 系统概述：从文档图像到结构化信息

PP-Structure 是 PaddleOCR 团队自研的智能文档分析系统，目标在于帮助开发者更好地完成版面分析（Layout Analysis）、表格识别（Table Recognition）、关键信息抽取（Key Information Extraction，KIE）等文档理解任务，把非结构化的文档图像转换为结构化的数据表达。

PP-StructureV2 的系统流程如下：文档图像首先经过图像矫正模块（Image Orientation Correction），判断整图方向并完成转正；随后进入两条任务主线——版面信息分析与关键信息抽取：

• 版面分析任务：图像首先经过版面分析模型，被划分为文本、表格、图像等不同区域；随后对这些区域分别处理——表格区域送入表格识别模块进行结构化识别，文本区域送入 OCR 引擎进行文字识别，最后使用版面恢复模块（Layout Recovery）将其恢复为与原始图像布局一致的 Word 或 PDF 文件；
• 关键信息抽取任务：首先使用 OCR 引擎提取文本内容，然后由语义实体识别模块（Semantic Entity Recognition，SER）获取图像中的语义实体，最后经关系抽取模块（Relation Extraction，RE）获取语义实体之间的对应关系，从而提取出需要的关键信息。

从源码结构看，上述两条任务线对应 ppstructure 目录下的 predict_system.py（系统入口与任务编排）、layout/predict_layout.py（版面分析）、table/predict_table.py（表格识别）、kie（关键信息抽取）与 recovery（版面恢复）等模块。

需要说明的是，PP-Structure 系列模型自 2021 年推出以来已迭代三代。当前仓库中的 ppstructure/README.md 明确指出：本页（V2）代码与文档基于第二代 PP-StructureV2，后续将在适当时机停止维护；第三代 PP-StructureV3 提供更强大的文档解析能力，推荐通过集成 wheel 包使用。本文以 V2 文档与代码为准展开讲解。

PP-StructureV2 支持各个模块独立使用或灵活搭配，例如可以单独使用版面分析，或单独使用表格识别。对应各独立模块的教程入口为：

• 版面分析训练教程
• 表格识别训练教程
• 关键信息抽取训练教程
• 版面恢复教程

2. 核心特性

PP-StructureV2 的主要特性可归纳为以下几点：

• 版面分析：支持对图片/PDF 形式的文档进行版面分析，可以划分文字、标题、表格、图片、公式等区域；
• 表格检测：支持通用的中英文表格检测任务；
• 表格结构化识别：支持对表格区域进行结构化识别，最终结果输出为Excel 文件；
• 关键信息抽取（KIE）：支持基于多模态的语义实体识别（SER）与关系抽取（RE）；
• 版面恢复：支持恢复为与原始图像布局一致的 Word 或 PDF 格式文件；
• 灵活部署：支持自定义训练及 Python whl 包调用等多种推理部署方式，简单易用；
• 数据标注打通：与半自动数据标注工具 PPOCRLabel 打通，支持版面分析、表格识别、SER 三种任务的标注。

从系统入口看，这些特性在 ppstructure/predict_system.py 中被组织为可开关的组件：layout（版面分析）、table（表格识别）、ocr（非表格区域文字识别）、recovery（版面恢复）、image_orientation（图像方向分类）等，用户可通过参数自由组合，这正是“模块独立使用或灵活搭配”的工程实现基础。

3. 典型效果展示

PP-StructureV2 支持各模块独立使用或灵活搭配，下面仅展示几种代表性使用方式的可视化效果。

3.1 版面分析与表格识别

下图展示了“版面分析 + 表格识别”的整体流程：图片先由版面分析划分为图像、文本、标题和表格四种区域，然后对图像、文本和标题三种区域执行 OCR 检测识别，对表格区域执行表格识别；其中图像区域还会被单独裁剪存储下来以便后续使用。

在 predict_system.py 的__call__流程中可以看到这一编排逻辑：先调用layout_predictor得到layout_res区域列表（源码约 L129-L134），随后对每个区域判断label：table区域交给table_system做结构化识别，其余区域使用text_system做 OCR 检测识别（源码约 L143-L178）。

版面识别返回单字坐标：基于版面分析结果，还可以进一步对文字区域进行单字粒度的定位，效果示意如下，详细用法可参考 return_word_pos 文档。

3.2 版面恢复

下图展示了基于上一节版面分析和表格识别结果进行版面恢复（Layout Recovery）的效果，输出为与原始图像布局一致的 Word 文档：

3.3 关键信息抽取（SER 与 RE）

• SER（语义实体识别）：图中不同颜色的框表示不同的类别，模型为每个文本片段打上实体类别标签（如姓名、日期、地址等）；
• RE（关系抽取）：图中红色框表示问题（Question），蓝色框表示答案（Answer），问题和答案之间使用绿色线连接，模型抽取出实体之间的对应关系。

SER 与 RE 的更多效果图、训练与推理细节可参见 train_kie 教程 与 KIE 推理部署文档。

4. 环境准备与安装

4.1 安装 PaddlePaddle

在安装 PP-Structure 前，请先根据本机环境安装对应版本的 PaddlePaddle：

• CUDA 11.8 环境：

python3 -m pip install "paddlepaddle-gpu<=2.6" -i https://www.paddlepaddle.org.cn/packages/stable/cu118/

• CUDA 12.3 环境：

python3 -m pip install "paddlepaddle-gpu<=2.6" -i https://www.paddlepaddle.org.cn/packages/stable/cu123/

• 纯 CPU 机器：

python3 -m pip install "paddlepaddle<=2.6" -i https://www.paddlepaddle.org.cn/packages/stable/cpu/

更多版本需求请参照飞桨官网安装文档中的说明进行操作。若无基础 Python 运行环境，可先参考运行环境准备文档完成环境搭建。

4.2 安装 PaddleOCR whl 包

python3 -m pip install "paddleocr<3.0" # 安装图像方向分类依赖包 paddleclas（如不需要图像方向分类功能，可跳过） python3 -m pip install paddleclas

说明：上述版本约束来自 quick_start 文档，PP-StructureV2 的功能通过paddleocr<3.0版本提供。

5. 命令行快速体验

安装完成后，即可通过paddleocr命令行在--type=structure模式下按需组合各模块。

5.1 图像方向分类 + 版面分析 + 表格识别

# 暂时关闭新 IR 功能 export FLAGS_enable_pir_api=0 paddleocr --image_dir=ppstructure/docs/table/1.png --type=structure --image_orientation=true

--image_orientation=true会先对整图做方向分类并转正，再进入版面分析与表格识别流程。若不需要图像方向分类，直接执行：

paddleocr --image_dir=ppstructure/docs/table/1.png --type=structure

5.2 仅版面分析

paddleocr --image_dir=ppstructure/docs/table/1.png --type=structure --table=false --ocr=false

5.3 仅表格识别

paddleocr --image_dir=ppstructure/docs/table/table.jpg --type=structure --layout=false

当--layout=false时，整张图会被视为一个表格区域直接送入表格识别模块（这一点与 predict_system.py 中“layout 为空时默认整图作为 table 区域”的实现一致，源码约 L132-L134）。

5.4 版面恢复

版面恢复提供两种方法，详细介绍参考 版面恢复教程：

• PDF 解析（只支持 PDF 格式输入）：

paddleocr --image_dir=ppstructure/docs/recovery/UnrealText.pdf --type=structure --recovery=true --use_pdf2docx_api=true

• OCR 技术（支持图片与 PDF）：

# 中文测试图 paddleocr --image_dir=ppstructure/docs/table/1.png --type=structure --recovery=true # 英文测试图 paddleocr --image_dir=ppstructure/docs/table/1.png --type=structure --recovery=true --lang='en' # pdf 测试文件 paddleocr --image_dir=ppstructure/docs/recovery/UnrealText.pdf --type=structure --recovery=true --lang='en'

5.5 版面恢复 + 转换为 Markdown 文件

• 不使用 LaTeXOCR 模型进行公式识别：

paddleocr --image_dir=ppstructure/docs/recovery/UnrealText.pdf --type=structure --recovery=true --recovery_to_markdown=true --lang='en'

• 使用 LaTeXOCR 模型进行公式识别（此时必须使用中文 layout 模型）：

paddleocr --image_dir=ppstructure/docs/recovery/UnrealText.pdf --type=structure --recovery=true --formula=true --recovery_to_markdown=true --lang='ch'

5.6 关于关键信息抽取

关键信息抽取暂不支持通过 whl 包调用，详细使用教程请参考 关键信息抽取教程 与 KIE 推理部署文档。

6. Python API 调用与返回结果

6.1 基础调用：图像方向分类 + 版面分析 + 表格识别

import os import cv2 from paddleocr import PPStructure, draw_structure_result, save_structure_res table_engine = PPStructure(show_log=True, image_orientation=True) save_folder = './output' img_path = 'ppstructure/docs/table/1.png' img = cv2.imread(img_path) result = table_engine(img) save_structure_res(result, save_folder, os.path.basename(img_path).split('.')[0]) for line in result: line.pop('img') print(line) from PIL import Image font_path = 'doc/fonts/simfang.ttf' # PaddleOCR 下提供字体包 image = Image.open(img_path).convert('RGB') im_show = draw_structure_result(image, result, font_path=font_path) im_show = Image.fromarray(im_show) im_show.save('result.jpg')

其中save_structure_res负责把表格保存为 Excel、把图片区域裁剪保存，draw_structure_result负责把区域框与文字可视化到原图上。

6.2 常用变体

• 仅版面分析（table=False, ocr=False，不执行表格识别与 OCR）：

from paddleocr import PPStructure, save_structure_res table_engine = PPStructure(table=False, ocr=False, show_log=True) result = table_engine(img)

• 版面分析 + OCR（不识别表格），可处理 PDF 输入（会按页渲染为图像再逐页处理）：

ocr_engine = PPStructure(table=False, ocr=True, show_log=True) result = ocr_engine(img_path) # img_path 可为 PDF 文件

• 仅表格识别：

table_engine = PPStructure(layout=False, show_log=True) result = table_engine(img)

• 版面恢复（依赖sorted_layout_boxes排序与convert_info_docx重建 Word 文档）：

from paddleocr.ppstructure.recovery.recovery_to_doc import sorted_layout_boxes, convert_info_docx table_engine = PPStructure(recovery=True) # 英文图可加 lang='en' result = table_engine(img) save_structure_res(result, save_folder, os.path.basename(img_path).split('.')[0]) h, w, _ = img.shape res = sorted_layout_boxes(result, w) convert_info_docx(img, res, save_folder, os.path.basename(img_path).split('.')[0])

• 版面恢复并输出 Markdown（改用convert_info_markdown）：

from paddleocr.ppstructure.recovery.recovery_to_markdown import convert_info_markdown res = sorted_layout_boxes(result, w) convert_info_markdown(res, save_folder, os.path.basename(img_path).split('.')[0])

6.3 返回结果结构说明

PP-Structure 的返回结果是一个由 dict 组成的 list，示例如下：

[ { 'type': 'Text', 'bbox': [34, 432, 345, 462], 'res': ([[36.0, 437.0, 341.0, 437.0, 341.0, 446.0, 36.0, 447.0], [41.0, 454.0, 125.0, 453.0, 125.0, 459.0, 41.0, 460.0]], [('Tigure-6. The performance of CNN and IPT models using difforen', 0.90060663), ('Tent ', 0.465441)]) } ]

各字段含义如下：

运行完成后，每张图片会在output字段指定的目录下生成一个同名子目录；图片里的每个表格会保存为一个 Excel 文件，图片区域会被裁剪后保存，Excel 与图片文件名即该区域在原图中的坐标，例如：

/output/table/1/ └─ res.txt └─ [454, 360, 824, 658].xlsx 表格识别结果 └─ [16, 2, 828, 305].jpg 被裁剪出的图片区域 └─ [17, 361, 404, 711].xlsx 表格识别结果

6.4 核心参数说明

PP-Structure 的常用参数及其默认值如下（大部分参数与 PaddleOCR whl 包保持一致）：

对应地，ppstructure/predict_system.py 的__init__会根据这些参数按需初始化image_orientation_predictor、layout_predictor、table_system、text_system等组件（源码约 L45-L96），并在__call__中按“方向分类 → 版面分析 → 表格/文本分区处理 → 版面恢复”的顺序串联执行，time_dict会分别统计各阶段耗时。

7. 模型选型与模型库

部分任务需要同时使用结构化分析模型和OCR 模型。例如表格识别既需要表格识别模型做结构化解析，也需要 OCR 模型识别表格内的文字，请根据具体需求选择合适的模型：

• 结构化分析相关模型：参考 PP-Structure 模型库；
• OCR 相关模型：参考 PP-OCR 模型库。

7.1 版面分析模型

上述三份版面分析字典均位于 ppocr/utils/dict/layout_dict 目录，与 quick_start 参数表 中layout_dict_path的取值一一对应。

7.2 OCR 与表格识别模型

表格场景专用 OCR 模型（PubTabNet 数据集训练）：

如需使用其他 OCR 模型，可在 PP-OCR 模型库 下载模型，或使用自己训练好的模型，配置到det_model_dir、rec_model_dir两个字段即可。

表格识别模型：

7.3 KIE 模型

在 XFUND_zh 数据集上的精度（hmean）与 V100 GPU 推理耗时如下（数据来自 models_list 文档；耗时仅统计 inference 模型推理，不含预处理与后处理）：

此外，在 wildreceipt 数据集上还提供了SDMGR关键信息提取模型（78.0M，精度 86.70%）。各模型的下载地址请以 PP-Structure 模型库 页面为准。

8. 源码视角：PP-Structure 的模块化实现

PP-StructureV2 的工程实现集中在仓库的 ppstructure 目录，主要模块与对应文件如下：

• 系统入口与任务编排：predict_system.py —— 定义StructureSystem类，负责解析命令行参数、按需初始化各子模型，并在__call__中完成“方向分类 → 版面分析 → 表格识别 / OCR → 版面恢复”的完整调用链；
• 通用工具：utility.py —— 提供parse_args（参数解析）、draw_structure_result（结果可视化）、cal_ocr_word_box（单字坐标计算）等函数；
• 版面分析：layout/predict_layout.py —— 版面区域检测；
• 表格识别：table/predict_table.py 与 table/matcher.py、table/table_master_match.py —— 表格结构解析、单元格匹配与 Excel 导出；
• 关键信息抽取：kie —— SER 与 RE 的训练/推理脚本（如 predict_kie_token_ser.py、predict_kie_token_ser_re.py）；
• 版面恢复：recovery/recovery_to_doc.py、recovery/recovery_to_markdown.py、recovery/table_process.py —— 将版面分析与表格识别结果重建为 Word/Markdown 文档；另有 pdf2word 提供基于 pdf2docx 的 PDF 解析路径。

一个值得注意的实现细节是：旧版实现直接从版面区域中做 OCR，存在识别精度问题；当前 predict_system.py 改为先对整图做文本检测识别，再根据版面区域过滤出属于各区域的文本（源码注释见 L136-L142），从而提升 OCR 精度。

9. 深入拓展：训练、恢复与部署

围绕本文主线，可以继续深入以下主题（均为仓库内文档，可直接跳转阅读）：

• 快速开始：完整的环境安装、命令行与 Python 调用示例、参数说明；
• 版面恢复教程：标准 PDF 解析与图片格式 PDF 解析两种恢复方法的对比、模型下载与predict_system.py命令行恢复示例；
• 版面分析训练教程、表格识别训练教程、关键信息抽取训练教程：各模块的自定义训练、评估与推理方法；
• PP-Structure 模型库 与 PP-OCR 模型库：全部可用模型的下载与字典配置；
• Python 推理部署、C++ 推理部署、Paddle Serving 部署：不同生产环境下的部署方式；
• return_word_pos 文档：版面识别返回单字坐标的进阶用法。

通过本文，你已经掌握了 PP-StructureV2 的系统架构、核心特性、命令行动手方式、Python API、返回结果与参数体系，并了解每个模块在仓库中的源码位置与模型选型依据，可以据此在图片/PDF 文档理解任务中组合出适合自己场景的解决方案。

【免费下载链接】PaddleOCRTurn any PDF or image document into structured data for your AI. A powerful, lightweight OCR toolkit that bridges the gap between images/PDFs and LLMs. Supports 100+ languages.项目地址: https://gitcode.com/GitHub_Trending/pa/PaddleOCR