企业官网建设流程全解析

PaddleOCR PP-Structure 基于 Python 预测引擎的推理实战：版面分析、表格识别与关键信息抽取

【免费下载链接】PaddleOCR飞桨多语言OCR工具包（实用超轻量OCR系统，支持80+种语言识别，提供数据标注与合成工具，支持服务器、移动端、嵌入式及IoT设备端的训练与部署） Awesome multilingual OCR toolkits based on PaddlePaddle (practical ultra lightweight OCR system, support 80+ languages recognition, provide data annotation and synthesis tools, support training and deployment among server, mobile, embedded and IoT devices)项目地址: https://gitcode.com/paddlepaddle/PaddleOCR

PP-Structure 是 PaddleOCR 提供的文档智能分析系统，可将版面分析（Layout Analysis）、表格识别（Table Recognition）、OCR 文本识别与关键信息抽取（KIE）串成一条可复用的 Python 推理流水线。本文基于 python_infer.md 的官方说明，结合ppstructure/目录下的实际源码，完整讲解模型下载、predict_system.py两种模式（structure/kie）的用法、全部关键参数含义与结果文件组织方式。读完本文，你可以独立完成从图片到“版面区域 + 可编辑表格 + 结构化信息”的整套 Python 推理任务。

1. 环境准备：进入ppstructure目录并下载推理模型

所有推理命令都基于仓库中的ppstructure目录执行，因此第一步是切换到该目录：

cd ppstructure

与 PP-OCR 纯 OCR 推理不同，PP-Structure 推理需要按需准备四类模型：版面分析模型、文本检测模型、文本识别模型、表格识别模型。官方提供的一键下载命令如下：

mkdir 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/下应包含四个模型目录：

说明：关键信息抽取（KIE）所需的 SER / RE 模型不在这批模型中，将在第 3 节单独下载。所有模型均为 Paddle Inference 格式（_infer目录），可直接被预测引擎加载，无需再执行导出步骤。

2. 版面信息抽取（--mode=structure）

predict_system.py是 PP-Structure 的入口脚本，其核心类是StructureSystem（定义于 ppstructure/predict_system.py）。当--mode=structure时，系统按“版面分析 → 区域分流（表格走表格识别、其余区域走 OCR）→ 结果输出”的流程工作。

2.1 完整流程：版面分析 + 表格识别

同时启用版面分析、OCR 与表格识别，可以一次性输出文档的版面区域划分、表格 Excel 与文本识别结果：

python3 predict_system.py --det_model_dir=inference/PP-OCRv3_mobile_det_infer \ --rec_model_dir=inference/PP-OCRv3_mobile_rec_infer \ --table_model_dir=inference/ch_ppstructure_mobile_v2.0_SLANet_infer \ --layout_model_dir=inference/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 文件，图片区域会被裁剪后保存，Excel 文件与裁剪图片的文件名即为其在原始图片中的坐标（[x1,y1,x2,y2]形式）；详细的版面与识别结果统一写入res.txt文件。

从源码save_structure_res（ppstructure/predict_system.py）可以确认输出细节：

• excel_save_folder = os.path.join(save_folder, img_name)，即output/structure/<图片名>/；
• 每个区域的 JSON 行写入res_{idx}.txt，字段包含type（区域类型）、bbox（坐标）、img（裁剪图）、res（识别结果）、score等；
• type为table且结果含html时，将 HTML 表格转存为{bbox}_{idx}.xlsx（调用to_excel，见 ppstructure/table/predict_table.py）；
• type为figure时，将裁剪区域保存为{bbox}_{idx}.jpg。

2.2 单独版面分析

若只想得到版面区域划分、不执行表格识别与 OCR，可关闭--table与--ocr：

python3 predict_system.py --layout_model_dir=inference/picodet_lcnet_x1_0_layout_infer \ --image_dir=./docs/table/1.png \ --output=../output \ --table=false \ --ocr=false

运行完成后，每张图片在output/structure/<图片名>/下保留同名目录，图片区域被裁剪保存（文件名为坐标），版面分析结果写入res.txt。

版面分析由LayoutPredictor承担（ppstructure/layout/predict_layout.py）：输入图片先按Resize（800×608）与 ImageNet 归一化预处理，经 PicoDet 检测后，由PicoDetPostProcess结合字符表、--layout_score_threshold（默认 0.5）与--layout_nms_threshold（默认 0.5）输出区域框。默认的版面类别词典位于 ppocr/utils/dict/layout_dict/layout_publaynet_dict.txt。

2.3 单独表格识别

若图片已知只包含表格（或想对整图直接做表格识别），可只启用表格链路、关闭版面分析：

python3 predict_system.py --det_model_dir=inference/PP-OCRv3_mobile_det_infer \ --rec_model_dir=inference/PP-OCRv3_mobile_rec_infer \ --table_model_dir=inference/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 \ --layout=false

此时整图被当作一个表格区域处理。源码中有对应逻辑：当--layout=false时，StructureSystem.__call__会构造一个bbox=None、label="table"的默认区域（ppstructure/predict_system.py），随后交给TableSystem完成表格结构识别与单元格文字填充，最终表格输出为 Excel 文件，文件名为[0,0,img_h,img_w]（即整图坐标范围）。

表格识别核心参数来自 ppstructure/utility.py：--table_algorithm（默认TableAttn）、--table_max_len（默认 488）、--merge_no_span_structure（默认 True），以及表格结构字符表--table_char_dict_path（默认 ppocr/utils/dict/table_structure_dict_ch.txt）。

3. 关键信息抽取（--mode=kie）

关键信息抽取用于从票据、证件、报关单等文档中抽取“实体”与“实体关系”，PP-Structure 提供了两类任务：

• SER（语义实体识别）：标注每个文本 token 的语义类别（如姓名、金额、日期等）；
• RE（关系抽取）：在 SER 基础上进一步抽取实体之间的关系（如“发票号”指向具体编号）。

KIE 推理基于 LayoutXLM 模型。先下载 SER / RE 模型：

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 # 下载 RE 模型（RE+SER 场景需要） 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 ..

3.1 单独 SER

python3 predict_system.py \ --kie_algorithm=LayoutXLM \ --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_method="tb-yx" \ --mode=kie

运行完成后，每张图片的可视化结果会存放在--output指定目录下的kie目录中，文件名与输入图片一致。

3.2 SER + RE 联合推理

python3 predict_system.py \ --kie_algorithm=LayoutXLM \ --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_method="tb-yx" \ --mode=kie

与单独 SER 相比，多传一个--re_model_dir。此时输出目录下会为每张图片建立同名目录，其中包含可视化图片与预测结果文件（res_{idx}_kie.txt，见 ppstructure/predict_system.py）。

底层调用链：--mode=kie时，StructureSystem会实例化SerRePredictor（ppstructure/kie/predict_kie_token_ser_re.py），其流程为：先用SerPredictor得到 SER 结果与模型输入，再通过make_input组装 RE 输入，运行 RE 预测器后经VQAReTokenLayoutLMPostProcess后处理得到实体关系。若未传入--re_model_dir，SerRePredictor.predictor为None，此时自动退化为纯 SER 推理。

KIE 参数说明（定义于 ppstructure/utility.py）：

4. 关键推理参数速查表

predict_system.py的所有参数最终由 ppstructure/utility.py 的init_args统一解析（其中检测/识别类参数继承自 tools/infer/utility.py）。常用参数汇总如下：

5. 进阶：predict_system.py的执行流程解析

理解源码有助于按需裁剪流程。以structure模式为例，StructureSystem.__call__（ppstructure/predict_system.py）的核心步骤为：

1. （可选）图像方向校正：启用--image_orientation时，调用 PaddleClas 的text_image_orientation模型判断旋转角度并校正；
2. 版面分析：LayoutPredictor输出各区域框及其类别（table、figure、text、equation等）与置信度；
3. 全图 OCR：先用TextSystem对整图做检测 + 识别，再按版面区域框过滤出属于该区域的文本（源码注释说明：相比“逐区域单独 OCR”，先整图 OCR 再按区域过滤可显著提升识别精度）；
4. 区域分流：table区域送入TableSystem得到 HTML 结构并转为 Excel；equation区域送入公式识别器（--formula=true时启用）；其余区域直接使用步骤 3 过滤后的文本结果；
5. 结果落盘：每个区域写入res.txt，表格写为.xlsx，图片区域裁剪为.jpg，同时输出可视化图show_{idx}.jpg。

main函数（ppstructure/predict_system.py）还支持：

• 批量/多进程推理：--use_mp=true --total_process_num=N会按进程 ID 切分图片列表并行推理；
• 版面恢复：--recovery=true时将各区域按坐标排序（sorted_layout_boxes）并调用convert_info_docx/convert_info_markdown输出 Word / Markdown 文档；
• PDF 输入：check_and_read支持解析 PDF 为多页图像逐页推理，配合--use_pdf2docx_api可直接走pdf2docx转换。

6. 常见问题与使用建议

• --layout=false与--ocr的联动：源码中--layout=false时--ocr会被自动置为false并给出告警日志（ppstructure/predict_system.py），因为 OCR 文本需要依赖版面区域框做过滤，纯表格识别场景直接关闭即可。
• 中文可视化乱码：务必通过--vis_font_path指定中文字体（推荐仓库自带的 doc/fonts/simfang.ttf），否则draw_structure_result绘制的中文标签会显示为方块。
• 表格输出依赖字符表：SLANet 表格识别依赖--table_char_dict_path指定的结构字符表（ppocr/utils/dict/table_structure_dict_ch.txt），更换不同语言或版本的表格模型时需同步替换词典。
• KIE 的阅读顺序：--ocr_order_method="tb-yx"表示按“从上到下、从左到右”排列 OCR 文本，该排序结果会直接影响 LayoutXLM 对实体与关系的建模，处理多栏票据时应显式指定。
• 内存与显存：脚本默认设置FLAGS_allocator_strategy=auto_growth以按需分配显存；批量推理时可配合多进程参数控制单进程负载。

至此，你已经掌握了 PP-Structure 基于 Python 预测引擎的完整推理链路：下载四类模型 → 用--mode=structure完成版面分析、表格识别与混合文档解析 → 用--mode=kie完成 SER / RE 关键信息抽取，并能根据源码理解每个参数与输出文件的来龙去脉。更多部署形态（C++ 推理、Paddle Serving）可参考同目录下的 cpp_infer.md 与 paddle_server.md。

【免费下载链接】PaddleOCR飞桨多语言OCR工具包（实用超轻量OCR系统，支持80+种语言识别，提供数据标注与合成工具，支持服务器、移动端、嵌入式及IoT设备端的训练与部署） Awesome multilingual OCR toolkits based on PaddlePaddle (practical ultra lightweight OCR system, support 80+ languages recognition, provide data annotation and synthesis tools, support training and deployment among server, mobile, embedded and IoT devices)项目地址: https://gitcode.com/paddlepaddle/PaddleOCR