PaddleOCR PP-StructureV2 智能文档分析系统全解析：版面分析、表格识别、关键信息抽取与版面恢复实战

PaddleOCR PP-StructureV2 智能文档分析系统全解析版面分析、表格识别、关键信息抽取与版面恢复实战【免费下载链接】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/PaddleOCRPP-Structure 是 PaddleOCR 团队推出的智能文档分析系统围绕把图像 / PDF 文档变成结构化数据这一目标提供了版面分析、表格结构化识别、关键信息抽取KIE与版面恢复四大核心能力。本文以 PaddleOCR 仓库中docs/version2.x/ppstructure/overview.en.md为主线结合仓库源码实现系统讲解 PP-StructureV2 的系统架构、能力特性、命令行与 Python 双入口的快速上手方式、返回结果与参数含义以及各独立模块的模型选型指南帮助读者按需组合这些能力完成文档理解类任务。1. 系统定位与总体流程1.1 PP-Structure 是什么PP-Structure 是 PaddleOCR 团队开发的智能文档分析系统旨在帮助开发者更好地完成版面分析和表格识别等文档理解相关任务。它把文档图像 → 结构化数据这条链路拆解为可独立使用、可灵活组合的若干模块覆盖从整页版面切分、表格结构化输出到关键信息抽取、以及最终把分析结果恢复为与原图版面一致的 Word / PDF / Markdown 文档的完整流程。下图展示了 PP-StructureV2 系统的整体处理流程文档图像首先经过图像方向矫正模块识别整张图像的朝向并完成旋转校正随后系统分两条任务线并行推进——版面信息分析与关键信息抽取。1.2 两条核心任务线在版面分析任务线中图像先经过版面分析模型被划分为文本、表格、图片等不同区域然后对各区域分别处理表格区域送入表格识别模块完成结构化识别最终可输出为 Excel 文件文本区域送入 OCR 引擎完成文字识别最后版面恢复模块将各区域的分析结果按原图版面还原为 Word 或 PDF 文件。在关键信息抽取任务线中流程为先用 OCR 引擎提取文本内容 → 再由 SER语义实体识别Semantic Entity Recognition模块获得图像中的语义实体 → 最后由 RE关系抽取Relation Extraction模块获得语义实体之间的对应关系从而抽出所需的键值对类关键信息。1.3 模块可独立使用、自由组合PP-StructureV2 支持各模块独立使用或灵活搭配。例如可以只用版面分析也可以只做表格识别。仓库为每个独立模块都提供了专门的训练与使用教程在文档结构中对应为版面分析Layout Analysis表格识别Table Recognition关键信息抽取Key Information Extraction版面恢复Layout Recovery2. PP-StructureV2 核心能力一览根据官方概述PP-StructureV2 的主要能力如下版面分析支持对图像 / PDF 形式的文档进行版面分析可划分为文本、标题、表格、图片、公式等区域表格检测支持常见的中英文表格检测任务结构化表格识别支持表格结构化识别并将最终结果输出为Excel 文件多模态关键信息抽取支持基于多模态的 KIE 任务——语义实体识别SER与关系抽取RE版面恢复支持将文档恢复为与原图版面一致的 Word 或 PDF 格式定制化训练与多端部署支持自定义训练并支持 Python whl 包快速上手等多种推理部署方式标注工具联动与半自动数据标注工具 PPOCRLabel 打通支持版面分析、表格识别与 SER 任务的标注。3. 效果演示3.1 版面分析 表格识别下图展示了版面分析 表格识别的串联效果图像先被版面分析划分为图片、文本、标题、表格四类区域随后对图片、文本、标题三个区域执行 OCR 检测与识别对表格区域执行表格识别图片区域会被裁剪保存备后续使用。3.1.1 版面识别返回单字坐标PP-Structure 还支持版面识别结果返回单字single word级别的坐标即不仅给出每个文本行的检测框还能进一步给出行内每个字的坐标框。其具体使用方式可参考 返回单字坐标文档。从源码看这一能力由 ppstructure/utility.py 中的cal_ocr_word_box实现它根据识别模型返回的字符级列信息rec_word_info中的col_num、word_list、word_col_list、state_list按字符宽度将文本行检测框细分为逐字坐标框中文按平均字符宽度推算英文按列索引换算。3.2 版面恢复下图展示了基于上一节版面分析与表格识别结果进行的版面恢复效果文档被还原为与原始版面一致的 Word / PDF 输出。3.3 关键信息抽取KIESER语义实体识别图中不同颜色的框代表不同类别如姓名、身份证号、地址等语义实体模型为每个实体 token 打上类别标签。RE关系抽取在图中红色框代表Question问题 / 键蓝色框代表Answer答案 / 值Question与Answer之间用绿色连线表示二者的对应关系从而抽取出结构化的键值对信息。SER 与 RE 的预测与可视化在仓库中分别由 ppstructure/kie/predict_kie_token_ser.py 与 ppstructure/kie/predict_kie_token_ser_re.py 提供可视化函数draw_ser_results/draw_re_results位于 ppocr/utils/visual.py。4. 快速开始本节内容对应仓库文档 PP-Structure Quick Start。注意下述快速上手方式针对 PaddleOCR2.x whl 包安装时指定paddleocr3.0若使用 3.x 版本API 形态与命令参数以当前版本官方文档为准。4.1 环境准备第一步安装 PaddlePaddle。若尚未准备 Python 环境可先参考 环境准备文档。根据硬件情况选择带 CUDA 11.8 的 GPU 环境python3 -m pip install paddlepaddle-gpu2.6 -i https://www.paddlepaddle.org.cn/packages/stable/cu118/带 CUDA 12.3 的 GPU 环境python3 -m pip install paddlepaddle-gpu2.6 -i https://www.paddlepaddle.org.cn/packages/stable/cu123/无 GPU 的 CPU 环境python3 -m pip install paddlepaddle2.6 -i https://www.paddlepaddle.org.cn/packages/stable/cpu/第二步安装 PaddleOCR whl 包python3 -m pip install paddleocr3.0 # 安装图像方向分类依赖包 paddleclas不使用图像方向分类时可跳过 python3 -m pip install paddleclas4.2 命令行快速使用以下命令均通过paddleocr --typestructure入口调用 PP-Structure 能力。示例中的ppstructure/docs/...为原文档给出的演示图片路径实际使用时请替换为你自己的图像 / PDF 文件。4.2.1 图像方向矫正 版面分析 表格识别# 临时关闭新的 IR 特性 export FLAGS_enable_pir_api0 paddleocr --image_dirppstructure/docs/table/1.png --typestructure --image_orientationtrue4.2.2 版面分析 表格识别paddleocr --image_dirppstructure/docs/table/1.png --typestructure4.2.3 仅版面分析paddleocr --image_dirppstructure/docs/table/1.png --typestructure --tablefalse --ocrfalse4.2.4 仅表格识别paddleocr --image_dirppstructure/docs/table/table.jpg --typestructure --layoutfalse4.2.5 关键信息抽取关键信息抽取目前不支持通过 whl 包直接使用详细使用教程参见 关键信息抽取教程。4.2.6 版面恢复提供两种版面恢复方式PDF 解析与OCR。使用 PDF 解析恢复仅支持 PDF 输入paddleocr --image_dirppstructure/docs/recovery/UnrealText.pdf --typestructure --recoverytrue --use_pdf2docx_apitrue使用 OCR 恢复paddleocr --image_dirppstructure/docs/table/1.png --typestructure --recoverytrue --langen4.2.7 版面恢复PDF 转 Markdown不使用 LaTeX-OCR 模型进行公式识别paddleocr --image_dirppstructure/docs/recovery/UnrealText.pdf --typestructure --recoverytrue --recovery_to_markdowntrue --langen使用 LaTeX-OCR 模型进行公式识别此时必须使用中文版面模型paddleocr --image_dirppstructure/docs/recovery/UnrealText.pdf --typestructure --recoverytrue --formulatrue --recovery_to_markdowntrue --langch4.3 Python 脚本快速使用4.3.1 图像方向矫正 版面分析 表格识别import os import cv2 from paddleocr import PPStructure, draw_structure_result, save_structure_res table_engine PPStructure(show_logTrue, image_orientationTrue) 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_pathfont_path) im_show Image.fromarray(im_show) im_show.save(result.jpg)4.3.2 版面分析 表格识别import os import cv2 from paddleocr import PPStructure, draw_structure_result, save_structure_res table_engine PPStructure(show_logTrue) 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_pathfont_path) im_show Image.fromarray(im_show) im_show.save(result.jpg)4.3.3 仅版面分析import os import cv2 from paddleocr import PPStructure, save_structure_res table_engine PPStructure(tableFalse, ocrFalse, show_logTrue) 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)若只想对 PDF 的每个页面执行 OCR关闭表格可以这样处理单页图像import os import cv2 from paddleocr import PPStructure, save_structure_res ocr_engine PPStructure(tableFalse, ocrTrue, show_logTrue) save_folder ./output img_path ppstructure/docs/recovery/UnrealText.pdf result ocr_engine(img_path) for index, res in enumerate(result): save_structure_res(res, save_folder, os.path.basename(img_path).split(.)[0], index) for res in result: for line in res: line.pop(img) print(line)如果输入是 PDF也可以先用 PyMuPDFfitz自行将每一页渲染为图像再逐页送入PPStructure处理便于对渲染参数做精细控制import os import cv2 import numpy as np from paddleocr import PPStructure, save_structure_res from paddle.utils import try_import from PIL import Image ocr_engine PPStructure(tableFalse, ocrTrue, show_logTrue) save_folder ./output img_path ppstructure/docs/recovery/UnrealText.pdf fitz try_import(fitz) imgs [] with fitz.open(img_path) as pdf: for pg in range(0, pdf.page_count): page pdf[pg] mat fitz.Matrix(2, 2) pm page.get_pixmap(matrixmat, alphaFalse) # 若宽或高超过 2000 像素则不放大图像 if pm.width 2000 or pm.height 2000: pm page.get_pixmap(matrixfitz.Matrix(1, 1), alphaFalse) img Image.frombytes(RGB, [pm.width, pm.height], pm.samples) img cv2.cvtColor(np.array(img), cv2.COLOR_RGB2BGR) imgs.append(img) for index, img in enumerate(imgs): result ocr_engine(img) save_structure_res(result, save_folder, os.path.basename(img_path).split(.)[0], index) for line in result: line.pop(img) print(line)4.3.4 仅表格识别import os import cv2 from paddleocr import PPStructure, save_structure_res table_engine PPStructure(layoutFalse, show_logTrue) save_folder ./output img_path ppstructure/docs/table/table.jpg 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)4.3.5 关键信息抽取关键信息抽取目前不支持通过 whl 包使用详细推理教程参见 KIE 推理文档对应仓库中的推理脚本为 ppstructure/kie/predict_kie_token_ser_re.py。4.3.6 版面恢复输出 Wordimport os import cv2 from paddleocr import PPStructure, save_structure_res from paddleocr.ppstructure.recovery.recovery_to_doc import sorted_layout_boxes, convert_info_docx # 中文图像 table_engine PPStructure(recoveryTrue) # 英文图像 # table_engine PPStructure(recoveryTrue, langen) 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) h, w, _ img.shape res sorted_layout_boxes(result, w) convert_info_docx(img, res, save_folder, os.path.basename(img_path).split(.)[0])4.3.7 版面恢复输出 Markdownimport os import cv2 from paddleocr import PPStructure, save_structure_res from paddleocr.ppstructure.recovery.recovery_to_doc import sorted_layout_boxes from paddleocr.ppstructure.recovery.recovery_to_markdown import convert_info_markdown # 中文图像 table_engine PPStructure(recoveryTrue) # 英文图像 # table_engine PPStructure(recoveryTrue, langen) 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) h, w, _ img.shape res sorted_layout_boxes(result, w) convert_info_markdown(res, save_folder, os.path.basename(img_path).split(.)[0])4.4 返回结果说明PPStructure的返回值是一个dict 列表示例如下版面分析 表格识别场景[ { 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)]) } ]dict 中各字段含义如下字段说明type图像区域的类型如 Text、Table、Figure 等。bbox图像区域在原始图像中的坐标依次为[左上角 x, 左上角 y, 右下角 x, 右下角 y]。res该图像区域的 OCR 或表格识别结果。表格区域一个 dict其中html字段为表格的 HTML 字符串在代码调用模式下设置return_ocr_result_in_tableTrue还可拿到表格区域内每个文本的检测与识别结果对应boxes文本检测框与rec_res文本识别结果字段。OCR 区域一个元组包含每个独立文本的检测框与识别结果。这一结构在源码中的对应实现在 ppstructure/predict_system.py每个区域被组织为{type, bbox, img, res, img_idx, score}的 dict其中img为裁剪出的区域图像score为版面分析置信度。识别完成后每张图像会在output字段指定目录下生成同名子目录图像中的每个表格被保存为一个 Excel 文件图片区域被裁剪保存为 jpg文件名即其在图像中的坐标。目录结构示例如下/output/table/1/ └─ res.txt └─ [454, 360, 824, 658].xlsx 表格识别结果 └─ [16, 2, 828, 305].jpg 图像中的图片区域 └─ [17, 361, 404, 711].xlsx 表格识别结果该保存逻辑对应 ppstructure/predict_system.py 中的save_structure_res表格区域通过to_excel写出为.xlsx图片区域通过cv2.imwrite保存为.jpg所有区域的完整 JSON 结构写入res_{img_idx}.txt。4.5 参数说明字段说明默认值output结果保存路径./output/tabletable_max_len表格结构模型输入图像缩放后的长边488table_model_dir表格结构模型推理模型路径Nonetable_char_dict_path表格结构模型字典路径../ppocr/utils/dict/table_structure_dict.txtmerge_no_span_structure表格识别模型中是否合并td与/tdFalseformula_model_dir公式识别模型推理模型路径Noneformula_char_dict_path公式识别模型字典路径../ppocr/utils/dict/latex_ocr_tokenizer.jsonlayout_model_dir版面分析模型推理模型路径Nonelayout_dict_path版面分析模型字典路径../ppocr/utils/dict/layout_publaynet_dict.txtlayout_score_threshold版面分析模型框置信度阈值0.5layout_nms_threshold版面分析模型 NMS 阈值0.5kie_algorithmKIE 模型算法LayoutXLMser_model_dirSER 模型推理模型路径Noneser_dict_pathSER 模型字典路径../train_data/XFUND/class_list_xfun.txtmode运行模式可选structure或kiestructureimage_orientation前向推理时是否进行图像方向分类Falselayout前向推理时是否进行版面分析Truetable前向推理时表格区域是否使用表格识别Trueformula前向推理时是否进行公式识别Falseocr版面分析中对非表格区域是否执行 OCR当 layout 为 False 时自动置为 FalseTruerecovery前向推理时是否执行版面恢复Falserecovery_to_markdown是否将版面恢复结果转换为 markdown 文件Falsesave_pdf版面恢复时是否将 docx 转换为 pdfFalsestructure_version结构版本可选 PP-structure 与 PP-structurev2PP-structure这些参数在源码中的解析入口位于 ppstructure/utility.py 的init_args()其中layout_score_threshold/layout_nms_threshold会直接传给版面分析后处理PicoDetPostProcess见 ppstructure/layout/predict_layout.py其余大部分参数与 PaddleOCR whl 包保持一致。若需使用自定义训练模型通过layout_model_dir、table_model_dir、ser_model_dir等字段指定本地推理模型目录即可。5. 源码视角PP-Structure 的运行原理5.1 主控类 StructureSystemPP-Structure 的核心调度逻辑在 ppstructure/predict_system.py 的StructureSystem类中构造阶段根据args.mode分支初始化structure模式会按需创建LayoutPredictor版面分析、TextSystemOCR、TableSystem表格识别、TextRecognizer公式识别由formula开关控制kie模式则初始化SerRePredictor若开启image_orientation会加载paddleclas.PaddleClas(model_nametext_image_orientation)做整图方向分类并根据返回的90 / 180 / 270角度调用cv2.rotate完成旋转校正前向调用__call__时ppstructure/predict_system.py依次执行方向矫正 → 版面分析 → 区域级处理table区域走表格识别equation区域在启用公式识别时走 LaTeX 输出其余区域通过_filter_text_res从全图 OCR 结果中按区域框做相交过滤得到该区域的文本。值得注意的一个实现细节_filter_text_res采用先对整图做一次 OCR再按版面区域框过滤的策略而不是对每个版面区域分别做 OCR。源码注释ppstructure/predict_system.py说明这是针对 issue #10270、#11665 的修复旧实现按区域分别识别存在识别精度问题先全图识别再按区域过滤可提升 OCR 准确率。5.2 版面分析 LayoutPredictor版面分析模块位于 ppstructure/layout/predict_layout.py。其预处理链为Resize([800, 608]) → NormalizeImage(ImageNet 均值 / 方差) → ToCHWImage → KeepKeys后处理使用PicoDetPostProcess并透传layout_dict_path、layout_score_threshold、layout_nms_threshold三个参数。因此layout_score_threshold控制区域框的置信度门槛值越高误检越少、漏检越多layout_nms_threshold控制重叠框的去重强度二者共同决定版面区域切分的质量。5.3 表格识别与文本匹配表格识别在 ppstructure/table/predict_table.py 中实现_structure负责用表格结构模型预测单元格结构_ocr复用文本检测 / 识别模型识别单元格内文字匹配逻辑由 ppstructure/table/matcher.py 完成将检测到的文字框与预测的单元格框做 IoU / 距离匹配最终生成带文字的 HTMLto_excel则将 HTML 表格导出为 xlsx。这也解释了为什么文档 4.4 节的结果中表格区域返回的是 HTML 字符串而落盘时却是 Excel。5.4 版面恢复与 PDF 转 Markdown版面恢复依赖两个模块 ppstructure/recovery/recovery_to_doc.py 中的sorted_layout_boxes按阅读顺序对版面区域排序与convert_info_docx生成 Word 文档ppstructure/recovery/recovery_to_markdown.py 中的convert_info_markdown生成 Markdown。命令行中的--use_pdf2docx_apitrue则是走pdf2docx库的 PDF 原生解析路径见 ppstructure/predict_system.py仅支持 PDF 输入。6. 模型选型指南部分任务需要同时使用结构化分析模型与 OCR 模型。例如表格识别任务既需要表格识别模型完成结构化分析也需要 OCR 模型识别表格中的文字。请根据具体需求选择合适模型。版面分析相关模型详见 PP-Structure 模型库模型说明推理模型大小picodet_lcnet_x1_0_fgd_layout基于 PicoDet LCNet_x1_0 FGD 在 PubLayNet 上训练的英文版面分析模型可识别Text、Title、Table、Picture、List5 类区域9.7Mppyolov2_r50vd_dcn_365e_publaynet基于 PP-YOLOv2 在 PubLayNet 上训练的英文版面分析模型221.0Mpicodet_lcnet_x1_0_fgd_layout_cdla基于 CDLA 数据集训练的中文版面分析模型可识别表格、图片、图注、表注、页眉、页脚、参考文献、公式等 10 类区域9.7Mpicodet_lcnet_x1_0_fgd_layout_table在表格数据集上训练的版面分析模型可检测中英文文档中的表格9.7Mppyolov2_r50vd_dcn_365e_tableBank_word在 TableBank Word 数据集上训练可检测英文文档中的表格221.0Mppyolov2_r50vd_dcn_365e_tableBank_latex在 TableBank Latex 数据集上训练可检测英文文档中的表格221.0MOCR 与表格识别模型表格场景可选用基于 PubTabNet 训练的en_ppocr_mobile_v2.0_table_det4.7M与en_ppocr_mobile_v2.0_table_rec6.9M分别做表格文本检测与识别表格结构识别可选en_ppocr_mobile_v2.0_table_structure基于 TableRec-RARE6.8M、en_ppstructure_mobile_v2.0_SLANet9.2M与ch_ppstructure_mobile_v2.0_SLANet中文9.3M。如需使用其他 OCR 模型可从 PP-OCR 模型库 下载或使用自行训练的模型并通过det_model_dir、rec_model_dir字段配置。KIE 模型官方在 XFUND_zh 数据集上给出了多个多模态模型的对比V100 GPU 评测环境SER 任务中 VI-LayoutXLMHmean 93.19%与 LayoutXLM90.38%表现靠前LayoutLMv2 为 85.44%LayoutLM 为 77.31%RE 任务中 VI-LayoutXLM 的 Hmean 为 83.92%LayoutXLM 为 74.83%LayoutLMv2 为 67.77%。此外在 wildreceipt 数据集上SDMGRVGG6 主干的 Hmean 为 86.70%。各模型的训练配置位于 configs/kie 目录KIE 详细训练教程见 KIE 训练文档。7. 总结通过本文你可以掌握 PaddleOCR PP-StructureV2 的完整能力图谱从图像方向矫正、版面分析、表格识别、公式识别到关键信息抽取SER / RE与版面恢复Word / PDF / Markdown既可以按需拆分单独使用某个模块也可以串联成一条完整的文档图像 → 结构化数据流水线。快速上手只需pip install paddleocr3.0后通过paddleocr --typestructure命令行或PPStructurePython 类两种方式调用深入定制时可通过 PP-Structure 模型库 选择或替换模型并结合 版面分析、表格识别、关键信息抽取、版面恢复 四份专项教程完成训练与部署。有关模型训练、推理与部署的更详细内容可继续查阅docs/version2.x/ppstructure目录下的对应文档。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考