PP-Structure Quick Start with PaddleOCR: Layout Analysis, Table Recognition and Layout Recovery【免费下载链接】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 提供的智能文档分析系统本指南面向 PaddleOCR 2.x 的paddleocr3.0whl 包完整讲解版面分析Layout Analysis、表格识别Table Recognition、公式识别Formula Recognition、版面恢复Layout Recovery含 PDF/图片转 Word 与转 Markdown的安装、命令行调用、Python 脚本调用、返回结果结构与全部参数含义。读完本文你将能够独立把一张文档图片或一份 PDF 一键解析为结构化结果HTML/Excel/Markdown/Word并理解每个开关参数背后的源码实现逻辑。PP-Structure 的整体流程是文档图像首先经过图像方向矫正模块随后并行/串行完成版面信息分析与关键信息抽取KIE两类任务。在版面分析任务中图像先经版面分析模型划分为文本、表格、图片等区域再对区域分别处理——表格区域送入表格识别模块做结构化识别文本区域送入 OCR 引擎做文字识别最后由版面恢复模块还原为与原始图像排版一致的 Word/PDF 文件。在 KIE 任务中先经 OCR 抽取文本再由 SER语义实体识别与 RE关系抽取模块抽取关键信息。完整流程说明可参考 PP-Structure 总览。说明本指南对应 PaddleOCR 2.x 时代的 PP-StructureV2使用的 whl 包版本约束为paddleocr3.0。当前仓库已演进到 3.xppstructure 目录说明 明确指出第二代代码与文档后续将停止维护推荐通过新版集成 whl 包使用 PP-StructureV3。因此本文所有命令仅适用于 PaddleOCR 2.x 环境。1. 环境准备1.1 安装 PaddlePaddle如果你还没有 Python 环境请先参考 环境准备文档 完成 Python 环境搭建。PaddlePaddle 按硬件情况选择安装方式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/注意上述命令都带有2.6的版本上限约束这是与paddleocr3.0对应的兼容性要求。更详细的软件版本要求请查阅 PaddlePaddle 官方安装文档。1.2 安装 PaddleOCR whl 包python3 -m pip install paddleocr3.0 # 安装图像方向分类依赖包 paddleclas如果不用图像方向分类可跳过 python3 -m pip install paddleclaspaddleclas仅在开启image_orientation图像方向矫正时才需要。从源码看方向矫正通过paddleclas.PaddleClas(model_nametext_image_orientation)完成见 ppstructure/predict_system.py 中StructureSystem.__init__的实现。2. 命令行快速使用whl 包安装完成后直接使用paddleocr命令即可。以下各小节覆盖 PP-Structure 的全部使用模式。2.1 图像方向矫正 版面分析 表格识别# 临时关闭新 IR 特性2.x 环境下部分算子需要 export FLAGS_enable_pir_api0 paddleocr --image_dirppstructure/docs/table/1.png --typestructure --image_orientationtrue该命令串起最完整的流水线先做图像方向分类与矫正再做版面分析最后对表格区域做表格识别。2.2 版面分析 表格识别paddleocr --image_dirppstructure/docs/table/1.png --typestructure这是默认行为layout、table、ocr三个开关默认均为True即版面分析后非表格区域走 OCR表格区域走表格识别。2.3 仅版面分析paddleocr --image_dirppstructure/docs/table/1.png --typestructure --tablefalse --ocrfalse关闭表格与 OCR 后只输出各区域的type与bbox。注意在源码中若layoutFalse而ocrTrue系统会强制把ocr置为False并给出警告逻辑见 ppstructure/predict_system.py。2.4 仅表格识别paddleocr --image_dirppstructure/docs/table/table.jpg --typestructure --layoutfalse关闭版面分析后整张图默认按“表格区域”处理源码中当layout_predictor is None时会构造一个bboxNone, labeltable的默认区域即整图作为表格输入见 ppstructure/predict_system.py。2.5 关键信息抽取KIE关键信息抽取目前不支持通过 whl 包使用详细使用教程请参考 关键信息抽取。不过从源码看modekie分支是存在的会加载ppstructure.kie.predict_kie_token_ser_re.SerRePredictor输出(re_res, time_dict)参见 ppstructure/predict_system.py。仓库内也提供了独立脚本 predict_kie_token_ser.py 与 predict_kie_token_ser_re.py 供源码方式使用。2.6 版面恢复Layout Recovery版面恢复提供两种方法详见 版面恢复文档PDF 解析PDF parse仅支持 PDF 输入基于 PyMuPDF 提取数据并生成 docxpaddleocr --image_dirppstructure/docs/recovery/UnrealText.pdf --typestructure --recoverytrue --use_pdf2docx_apitrueOCR 识别OCR支持 PDF 与图片输入通过版面分析 表格识别还原图像、表格、标题等paddleocr --image_dirppstructure/docs/table/1.png --typestructure --recoverytrue --langen两种方法各有适用场景PDF 解析对非纸质文档恢复效果更好、每页保持同页OCR 方法更适合纸质文档内容恢复、OCR 识别效果更好但排版效果依赖版面分析质量且目前基于规则间距字体等排版效果仍有改进空间。2.7 版面恢复PDF 转 Markdown在恢复的同时直接输出 Markdown 文件需要配合--recovery_to_markdowntrue不使用 LaTeXOCR 模型做公式识别paddleocr --image_dirppstructure/docs/recovery/UnrealText.pdf --typestructure --recoverytrue --recovery_to_markdowntrue --langen使用 LaTeXOCR 模型做公式识别此时必须使用中文版面模型paddleocr --image_dirppstructure/docs/recovery/UnrealText.pdf --typestructure --recoverytrue --formulatrue --recovery_to_markdowntrue --langch3. Python 脚本调用在脚本中使用PPStructure类可以获得与命令行等价甚至更灵活的能力。以下示例与命令行各小节一一对应。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)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)3.3 仅版面分析 / 版面分析 OCR仅版面分析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)版面分析 OCR关闭表格对 PDF 多页处理结果按页保存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自行渲染成图像列表再逐页送入引擎。渲染时若宽或高超过 2000 像素则不再放大避免超大图像影响识别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)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)3.5 关键信息抽取关键信息抽取暂不支持通过 whl 包使用详细教程请参考 Python 推理文档。3.6 版面恢复转 Word调用PPStructure(recoveryTrue)后再用sorted_layout_boxes排序区域、convert_info_docx生成 docximport 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])sorted_layout_boxes会按“从上到下、从左到右”排序各区域并依据区域与页面中线的位置关系为每个区域打上single/double版面标记convert_info_docx据此决定 Word 中是单栏还是双栏排版实现与原始图像一致的版式还原实现见 ppstructure/recovery/recovery_to_doc.py。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])convert_info_markdown实现见 ppstructure/recovery/recovery_to_markdown.py会把各区域映射为 Markdown 语法figure区域输出居中的img标签title输出#标题table直接输出表格 HTMLequation输出$$latex$$块text区域则通过check_merge_method根据首行与文本框的缩进关系自动判断段落合并方式段首两空格或段尾空格两种规则并对*~$等特殊字符做转义。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)]) } ]各字段含义如下字段说明type图像区域类型Text、Title、Table、Figure、Equation 等。bbox图像区域在原图中的坐标依次为 [左上角 x, 左上角 y, 右下角 x, 右下角 y]。res该区域的 OCR 或表格识别结果。table 类型一个 dict字段说明如下html表格的 HTML 字符串。在代码使用模式下调用时设置return_ocr_result_in_tableTrue可额外获得表格区域内每个文字的检测与识别结果对应字段boxes文字检测框。rec_res文字识别结果。OCR 类型包含每个单行文字的检测框与识别结果的元组。除type/bbox/res外源码中的每个区域 dict 还包含img该区域的像素裁剪、img_idx页码索引多页 PDF 时区分页与score区域置信度组装逻辑见 ppstructure/predict_system.py。识别完成后每张图像会在output指定的目录下生成一个同名子目录。图像中的每个表格保存为一个 Excel图片区域会被裁剪保存Excel 与图片的文件名即其坐标/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将 HTML 转为 xlsxfigure区域用cv2.imwrite保存裁剪图全部区域序列化为res.txt。关键信息抽取的结果格式请参考 关键信息抽取。5. 参数说明PP-Structure whl 包主要参数如下字段说明默认值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.txtmodestructure 或 kiestructureimage_orientation前向推理时是否进行图像方向分类Falselayout前向推理时是否进行版面分析Truetable前向推理时是否进行表格识别Trueformula前向推理时是否进行公式识别Falseocr版面分析中是否对非表格区域做 OCR当 layout 为 False 时自动置为 FalseTruerecovery前向推理时是否进行版面恢复Falserecovery_to_markdown是否将版面恢复结果转为 Markdown 文件Falsesave_pdf恢复时是否将 docx 转为 pdfFalsestructure_version结构版本可选 PP-structure 与 PP-structurev2PP-structure绝大多数参数与 PaddleOCR whl 包一致参见 whl 包文档。从源码parse_args见 ppstructure/utility.py可以看到命令行层的对应实现与补充参数--table_algorithm默认TableAttn、--formula_algorithm默认LaTeXOCR、--formula_batch_num默认 1、--ser_dict_path默认../train_data/XFUND/class_list_xfun.txt以及--use_pdf2docx_api、--invert推理前反色、--binarize推理前二值化、--alphacoloralpha 通道替换色等。其中layout_score_threshold与layout_nms_threshold会直接注入版面分析后处理PicoDetPostProcess见 ppstructure/layout/predict_layout.py调低layout_score_threshold可召回更多低置信度区域调高则可减少误检。6. 源码视角一次完整调用的内部链路以paddleocr --typestructure为例whl 最终会走到 ppstructure/predict_system.py 的main读取输入文件列表支持图片、图片目录、PDF、PDF 目录StructureSystem在初始化时按开关惰性创建各子模块——开启image_orientation时创建 PaddleClas 方向分类器开启layout时创建LayoutPredictorlayout与ocr同时开启时创建TextSystem复用tools/infer/predict_system.py的 OCR 系统开启table时创建TableSystem并复用 OCR 的检测器与识别器开启formula时用formula_*参数克隆一份TextRecognizer作为公式识别器。前向推理时StructureSystem.__call__见 ppstructure/predict_system.py大致经历图像方向矫正 → 版面分析得到区域列表 → 全图先做一次 OCR 得到全部文本 → 按区域裁剪roi_img→ 表格区域走TableSystem、公式区域走formula_system、其余区域用_filter_text_res按 bbox 相交判定筛出属于该区域的文本 → 汇总为结果列表。其中“先全图 OCR 再按版面区域过滤”的补丁方案是为了规避按区域分别 OCR 导致的识别精度下降问题对应 issue #10270、#11665。整个调用过程还会累计image_orientation/layout/table/formula/det/rec/all等分项耗时便于性能分析。7. 总结通过本文内容你可以完整掌握使用 PaddleOCR 2.x whl 包调用 PP-Structure 版面分析、表格识别、公式识别、版面恢复Word/Markdown以及图像方向矫正的全部方式理解返回的 dict 结构与每个开关参数的默认行为并能在源码层定位 ppstructure/predict_system.py、ppstructure/utility.py、ppstructure/layout/predict_layout.py、ppstructure/recovery/recovery_to_doc.py、ppstructure/recovery/recovery_to_markdown.py 中对应的实现。如需模型训练、推理与部署等更详细的使用教程可继续阅读 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考