PP-Structure 文档结构化推理实战基于 Python 预测引擎的版面分析、表格识别与关键信息抽取PaddleOCR【免费下载链接】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本文是 PaddleOCR PP-Structure 系列中关于Python 预测引擎推理的实战指南。它围绕predict_system.py这一统一入口系统讲解如何通过命令行完成「版面分析 表格识别」文档结构化流水线以及基于 LayoutXLM 的 SER语义实体识别与 RESER关系抽取 语义实体识别关键信息抽取任务。读完本文你将掌握模型下载组织方式、三类常见推理组合的参数写法、输出目录与文件命名规则以及这些命令背后的模块化实现原理可直接照搬到自己的文档结构化场景中。0. 写在前面一个入口两种模式PP-Structure 的 Python 预测引擎统一由ppstructure/predict_system.py提供内部通过--mode参数区分两条推理路径见 utility.py 中choices[structure, kie]默认structure--mode取值功能内部调用structure文档版面结构化版面分析、表格识别、公式识别、文本 OCRStructureSystem类kie关键信息抽取SER 或 RESERSerRePredictor类对应源码中StructureSystem.__init__依据self.mode分别初始化LayoutPredictorppstructure/layout/predict_layout.py、TextSystem、TableSystemppstructure/table/predict_table.py等组件kie分支则引入ppstructure/kie/predict_kie_token_ser_re.py中的SerRePredictor。理解这个入口结构后续所有命令就都能对号入座。1. 准备推理环境与模型文件首先进入ppstructure目录并按需下载推理模型到统一的inference目录中cd ppstructuremkdir inference cd inference # 下载 PP-StructureV2 版面分析模型并解压 wget https://paddleocr.bj.bcebos.com/ppstructure/models/layout/picodet_lcnet_x1_0_layout_infer.tar tar xf picodet_lcnet_x1_0_layout_infer.tar # 下载 PP-OCRv3 文本检测模型并解压 wget https://paddle-model-ecology.bj.bcebos.com/paddlex/official_inference_model/paddle3.0.0/PP-OCRv3_mobile_det_infer.tar tar xf PP-OCRv3_mobile_det_infer.tar # 下载 PP-OCRv3 文本识别模型并解压 wget https://paddle-model-ecology.bj.bcebos.com/paddlex/official_inference_model/paddle3.0.0/PP-OCRv3_mobile_rec_infer.tar tar xf PP-OCRv3_mobile_rec_infer.tar # 下载 PP-StructureV2 表格识别模型并解压 wget https://paddleocr.bj.bcebos.com/ppstructure/models/slanet/paddle3.0b2/ch_ppstructure_mobile_v2.0_SLANet_infer.tar tar xf ch_ppstructure_mobile_v2.0_SLANet_infer.tar cd ..解压后inference目录下应包含四个模型子目录picodet_lcnet_x1_0_layout_infer版面分析、PP-OCRv3_mobile_det_infer文本检测、PP-OCRv3_mobile_rec_infer文本识别、ch_ppstructure_mobile_v2.0_SLANet_infer表格结构识别后续命令中的--*_model_dir均指向它们。说明以下命令中的--image_dir如./docs/table/1.png为示例图片路径请替换为你本机的真实图片--rec_char_dict_path、--table_char_dict_path等字典文件位于仓库 ppocr/utils/ 目录下按命令中的相对路径以ppstructure目录为基准即可引用。2. 版面信息抽取modestructure版面信息抽取是 PP-Structure 的核心能力先用 PicoDet 版面分析模型ppstructure/layout/predict_layout.py把整页切分为文本、标题、表格、图片、公式等区域再按区域类型分流到 OCR、表格识别或公式识别子模型。源码中StructureSystem.__call__正是按「版面框 → 区域类型 → 对应子系统」的方式遍历layout_res完成推理。2.1 版面分析 表格识别完整流水线同时启用版面分析、文本 OCR 与表格识别得到完整的文档结构化结果python3 predict_system.py --det_model_dirinference/PP-OCRv3_mobile_det_infer \ --rec_model_dirinference/PP-OCRv3_mobile_rec_infer \ --table_model_dirinference/ch_ppstructure_mobile_v2.0_SLANet_infer \ --layout_model_dirinference/picodet_lcnet_x1_0_layout_infer \ --image_dir./docs/table/1.png \ --rec_char_dict_path../ppocr/utils/ppocr_keys_v1.txt \ --table_char_dict_path../ppocr/utils/dict/table_structure_dict_ch.txt \ --output../output \ --vis_font_path../doc/fonts/simfang.ttf运行完成后每张图片会在--output指定目录下的structure子目录中生成一个与图片同名的目录图片中的每个表格会被识别并存储为一个 Excel 文件文件名坐标即该表格在图片中的检测框坐标图片区域figure会被裁剪后保存为图片文件详细的逐区域结构化结果统一写入res.txt。该逻辑对应 predict_system.py 中的save_structure_res每个区域序列化为一行 JSON 写入res_{idx}.txt其中type table的区域通过to_excel导出为{bbox}_{idx}.xlsxtype figure的区域裁剪保存为{bbox}_{idx}.jpg。同时主流程会把可视化结果保存为show_{idx}.jpg便于人工核对。2.2 仅版面分析只需版面区域划分、不需要 OCR 与表格识别时显式关闭--table与--ocrpython3 predict_system.py --layout_model_dirinference/picodet_lcnet_x1_0_layout_infer \ --image_dir./docs/table/1.png \ --output../output \ --tablefalse \ --ocrfalse运行完成后每张图片在output/structure下生成同名目录图片区域被裁剪保存文件名为该区域在图片中的坐标版面分析结果写入res.txt。注意源码中的联动规则当--layoutfalse时--ocr会被自动置为false并给出警告日志见 predict_system.py因为 OCR 结果需要依赖版面区域做过滤而此处是保留版面、关闭 OCR是合法组合。2.3 仅表格识别跳过版面分析直接把整张图当作表格送入表格结构识别模型python3 predict_system.py --det_model_dirinference/PP-OCRv3_mobile_det_infer \ --rec_model_dirinference/PP-OCRv3_mobile_rec_infer \ --table_model_dirinference/ch_ppstructure_mobile_v2.0_SLANet_infer \ --image_dir./docs/table/table.jpg \ --rec_char_dict_path../ppocr/utils/ppocr_keys_v1.txt \ --table_char_dict_path../ppocr/utils/dict/table_structure_dict_ch.txt \ --output../output \ --vis_font_path../doc/fonts/simfang.ttf \ --layoutfalse运行完成后表格被识别并导出为 Excel文件名为[0,0,img_h,img_w]——即整张图片作为单个表格区域时的检测框坐标。从源码看--layoutfalse时LayoutPredictor不会被创建StructureSystem会为整图构造一个bboxNone, labeltable的默认区域predict_system.py从而把整图直接交给TableSystem处理。同时TableSystem内部会复用text_detector/text_recognizer完成单元格内文本的检测与识别ppstructure/table/predict_table.py。2.4 版面信息抽取核心参数速查以下参数定义于 ppstructure/utility.py 的init_args()是结构模式最常调整的开关参数默认值说明--output./output结果输出根目录实际结果落在output/structure/图片名/下--layoutTrue是否启用版面分析--tableTrue版面中的 table 区域是否走表格识别--ocrTrue版面中的非表格区域是否走 OCR--formulaFalse是否启用公式识别LaTeXOCR需额外指定--formula_model_dir--table_max_len488表格识别输入图像最长边限制--table_algorithmTableAttn表格结构算法可选TableMaster等--layout_score_threshold0.5版面区域置信度阈值--layout_nms_threshold0.5版面检测 NMS 阈值--table_char_dict_path../ppocr/utils/dict/table_structure_dict_ch.txt表格结构字符表仓库中实际存在该文件--rec_char_dict_path见tools/infer默认值OCR 识别字典常用 ppocr_keys_v1.txt--recoveryFalse是否进一步做版面恢复导出 docx/markdown需与--recovery_to_markdown配合其中layout_score_threshold/layout_nms_threshold会透传给 predict_layout.py 中的PicoDetPostProcess直接影响版面框的召回与去重效果table_max_len则约束表格图像送入 SLANet 前的大小。3. 关键信息抽取modekie关键信息抽取KIE用于从票据、证件、合同等文档中抽取出语义实体如发票号、金额、日期及实体间关系默认算法为 LayoutXLM底层依赖ppstructure/kie目录下的 SER / RESER 两个预测器。3.1 SER语义实体识别SER 负责给每个文本片段打上实体类别标签。先下载 SER 模型再执行推理cd ppstructure mkdir inference cd inference # 下载 SER XFUND 模型并解压 wget https://paddleocr.bj.bcebos.com/ppstructure/models/vi_layoutxlm/ser_vi_layoutxlm_xfund_infer.tar tar -xf ser_vi_layoutxlm_xfund_infer.tar cd .. python3 predict_system.py \ --kie_algorithmLayoutXLM \ --ser_model_dir./inference/ser_vi_layoutxlm_xfund_infer \ --image_dir./docs/kie/input/zh_val_42.jpg \ --ser_dict_path../ppocr/utils/dict/kie_dict/xfund_class_list.txt \ --vis_font_path../doc/fonts/simfang.ttf \ --ocr_order_methodtb-yx \ --modekie运行完成后每张图片会在--output指定目录下的kie目录中生成可视化图片图片名与输入图片名一致。关键参数说明--kie_algorithmLayoutXLM指定 KIE 算法对应 predict_kie_token_ser.py 中VQATokenLabelEncode预处理与VQASerTokenLayoutLMPostProcess后处理的算法名--ser_dict_path实体类别字典仓库中对应 xfund_class_list.txt--ocr_order_methodtb-yx指定 OCR 文本块的排序方式top-bottom / y-x 坐标排序它决定文本 token 序列进入 LayoutXLM 时的阅读顺序对抽取精度影响明显该参数默认值为None源码注释要求取值None或tb-yx内部流程SerPredictor先用内置PaddleOCR引擎predict_kie_token_ser.py做检测识别再经VQATokenPad、VQASerTokenChunk等算子组装成 LayoutXLM 的输入 token 序列。3.2 RE SER关系抽取 语义实体识别在 SER 基础上叠加关系抽取模型RE可以进一步输出实体两两之间的关系如「开票人—姓名」「金额—数值」cd ppstructure mkdir inference cd inference # 下载 SER、RE XFUND 模型并解压 wget https://paddleocr.bj.bcebos.com/ppstructure/models/vi_layoutxlm/ser_vi_layoutxlm_xfund_infer.tar tar -xf ser_vi_layoutxlm_xfund_infer.tar wget https://paddleocr.bj.bcebos.com/ppstructure/models/vi_layoutxlm/re_vi_layoutxlm_xfund_infer.tar tar -xf re_vi_layoutxlm_xfund_infer.tar cd .. python3 predict_system.py \ --kie_algorithmLayoutXLM \ --re_model_dir./inference/re_vi_layoutxlm_xfund_infer \ --ser_model_dir./inference/ser_vi_layoutxlm_xfund_infer \ --image_dir./docs/kie/input/zh_val_42.jpg \ --ser_dict_path../ppocr/utils/dict/kie_dict/xfund_class_list.txt \ --vis_font_path../doc/fonts/simfang.ttf \ --ocr_order_methodtb-yx \ --modekie运行完成后每张图片在output/kie下生成同名目录目录中存放可视化图片与预测结果文本res_{idx}_kie.txt见 predict_system.py。RESER 的串联机制在 predict_kie_token_ser_re.py 的SerRePredictor中实现先由SerPredictor产出 SER 结果与中间特征ser_inputs再通过make_input构造 RE 模型输入、执行第二次前向最后用VQAReTokenLayoutLMPostProcess后处理得到带关系三元组的实体列表。若只传--ser_model_dir而不传--re_model_dirSerRePredictor.predictor为None退化为纯 SER 模式输出可视化使用draw_ser_results同时传入两个模型时则输出draw_re_results的关系可视化。4. 常见问题与扩展阅读输出目录结构structure 模式的产出在output/structure/图片名/含show_*.jpg、res_*.txt、表格 Excel、裁剪图片kie 模式的产出在output/kie/图片名/含可视化图与res_*_kie.txt均由 predict_system.py 的main函数统一组织。多进程推理predict_system.py支持--use_mp与--total_process_num参数内部会为每个进程号拉起子进程并切片分配image_file_listpredict_system.py适合批量文档处理。更深入的方向本文聚焦「推理部署」。若需训练自定义模型可参考仓库 docs/version2.x/ppstructure/model_train 系列文档若需将推理封装为服务可参考 docs/version2.x/ppstructure/infer_deploy/paddle_server.mdC 部署则见 docs/version2.x/ppstructure/infer_deploy/cpp_infer.md。版面恢复导出 Word/Markdown可通过--recovery --recovery_to_markdown开关启用实现代码位于 ppstructure/recovery。以上命令与参数均可基于当前仓库直接复现入口脚本为 ppstructure/predict_system.py参数定义见 ppstructure/utility.pyKIE 相关实现见 ppstructure/kie 目录所需的字符表与类别字典位于 ppocr/utils 目录下。将本文的组合开关与真实图片结合即可快速搭建一套文档版面结构化或关键信息抽取的推理基线。【免费下载链接】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），仅供参考