企业官网建设流程全解析

PaddleOCR PP-Structure 版面分析完全指南：从 PP-PicoDet 训练、FGD 蒸馏到推理部署

【免费下载链接】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

版面分析（Layout Analysis）是文档结构化的第一步，也是 PP-Structure 文档理解流水线的入口：它把一页图片形式的文档划分为文字、标题、表格、图片等语义区域，为后续表格识别、OCR 与文档还原提供区域级上下文。本文以 ppstructure/layout/README_ch.md 为核心骨架，结合仓库源码深入讲解 PaddleOCR 版面分析模型的原理、数据准备、训练（含 FGD 蒸馏）、评估预测、动转静导出与推理部署全流程，读者读完可独立完成从 PubLayNet 数据到可部署 inference 模型的完整实战闭环。

1. 版面分析简介与模型能力

版面分析指对图片形式的文档进行区域划分，定位其中的关键区域（文字、标题、表格、图片等）。PaddleOCR 的版面分析算法基于 PaddleDetection 的轻量检测模型PP-PicoDet开发，官方提供英文、中文、表格版面分析 3 类模型：

• 英文模型：支持 5 类区域检测，即 Text、Title、List、Table、Figure（对应 layout_publaynet_dict.txt 中的类别顺序 text/title/list/table/figure）；
• 中文模型：基于 CDLA 数据集，支持 10 类区域检测：Text、Title、Figure、Figure caption、Table、Table caption、Header、Footer、Reference、Equation（见 layout_cdla_dict.txt）；
• 表格版面分析模型：仅检测 Table 区域（见 layout_table_dict.txt）。

从源码看，类别字典文件直接决定了后处理阶段的标签映射。在 predict_layout.py 中，后处理参数通过args.layout_dict_path指向上述字典文件，PicoDetPostProcess会依据该字典将模型输出的类别 id 翻译为区域类型名，例如class_id: 0在 PubLayNet 字典下即对应text。

模型名称中的lcnet_x1_0指以 LCNet（MobileNetV3 的改进版）为骨干网络、宽度倍率 1.0 的 PP-PicoDet 结构，fgd表示该模型是经由 FGD 蒸馏训练得到（详见 5.2 节），在轻量的同时保证了较高的检测精度。

2. 快速开始

PP-Structure 提供中文、英文、表格三类文档版面分析模型，模型下载链接见 models_list（新版文档参见 docs/version3.x/module_usage/layout_analysis.md）。同时官方也提供 whl 包形式便于快速使用，详见 quickstart。

在 PaddleOCR 仓库内，也可以直接使用脚本完成版面分析推理，例如：

# 以 PP-Structure 系统预测脚本为例，开启版面分析 python3 ppstructure/predict_system.py \ --layout_model_dir=path/to/layout_infer \ --image_dir=docs/images/layout.jpg \ --layout=true

从 predict_system.py 可以看出，当args.layout=True时系统会实例化LayoutPredictor，对输入图片先做版面分析，再根据每个区域类型分发到 OCR 或表格识别子流程；当args.layout=False时则强制ocr=False（predict_system.py），保证版面分析与后续识别的一致性。这是版面分析在完整文档理解流水线中的真实调用位置。

3. 安装环境

3.1 安装 PaddlePaddle

python3 -m pip install --upgrade pip # GPU 安装 python3 -m pip install "paddlepaddle-gpu>=2.3" -i https://mirror.baidu.com/pypi/simple # CPU 安装 python3 -m pip install "paddlepaddle>=2.3" -i https://mirror.baidu.com/pypi/simple

更多安装需求请参照 PaddlePaddle 官方安装文档。注意：训练版面分析模型要求 PaddlePaddle 版本不低于 2.3；推理部署阶段则与 PaddleOCR 主库依赖保持一致（可参考仓库根目录 requirements.txt）。

3.2 安装 PaddleDetection

训练脚本位于 PaddleDetection 仓库，因此需要单独获取其源码并安装依赖：

# （1）下载 PaddleDetection 源码 git clone https://github.com/PaddlePaddle/PaddleDetection.git # （2）安装其他依赖 cd PaddleDetection python3 -m pip install -r requirements.txt

训练所用的配置文件位于 PaddleDetection 的configs/picodet/legacy_model/application/layout_analysis目录下，评估与预测脚本（tools/train.py、tools/eval.py、tools/infer.py、tools/export_model.py）均在该仓库内执行。

4. 数据准备

如果希望直接体验预测过程，可以跳过本节，直接下载官方提供的预训练模型（见第 5 节）。

4.1 英文数据集 PubLayNet

PubLayNet 是目前规模最大的文档版面分析数据集（解压后约 96G），包含 5 个类别：{0: "Text", 1: "Title", 2: "List", 3: "Table", 4: "Figure"}。

# 下载数据 wget https://dax-cdn.cdn.appdomain.cloud/dax-publaynet/1.0.0/publaynet.tar.gz # 解压数据 tar -xvf publaynet.tar.gz

解压之后的目录结构：

|-publaynet |- test |- PMC1277013_00004.jpg |- PMC1291385_00002.jpg | ... |- train.json |- train |- PMC1291385_00002.jpg |- PMC1277013_00004.jpg | ... |- val.json |- val |- PMC538274_00004.jpg |- PMC539300_00004.jpg | ...

数据分布：

标注格式为 COCO 风格的嵌套字典，json 文件包含以下 key：

• info：标注文件 info。

• licenses：标注文件 licenses。

• images：标注文件中图像信息列表，每个元素是一张图像的信息：

  { 'file_name': 'PMC4055390_00006.jpg', # file_name 'height': 601, # image height 'width': 792, # image width 'id': 341427 # image id }

• annotations：标注文件中目标物体的标注信息列表，每个元素是一个目标物体的标注信息：

  { 'segmentation': # 物体的分割标注 'area': 60518.099043117836, # 物体的区域面积 'iscrowd': 0, # iscrowd 'image_id': 341427, # image id 'bbox': [50.58, 490.86, 240.15, 252.16], # bbox [x1,y1,w,h] 'category_id': 1, # category_id 'id': 3322348 # image id }

这一标注格式与 PaddleDetection 的COCODataSet读取器完全兼容，训练配置中TrainDataset: !COCODataSet即按此格式解析anno_path指向的 json 文件。

4.2 更多数据集

官方同时提供了 CDLA（中文版面分析）、TableBank（表格版面分析）等数据集的获取方式。只要把数据整理为上述 COCO 风格 json 标注格式，即可按相同方式训练：

训练自定义数据集时，除了将标注整理为上述格式，还需同步修改类别字典文件（仓库中对应 ppocr/utils/dict/layout_dict 目录下的三个 txt 文件），保证字典顺序与category_id一致，否则推理阶段标签会错位。

5. 开始训练

官方提供了训练、评估、预测脚本，本节以 PubLayNet 模型为例讲解。如果不希望训练，可直接下载预训练模型并跳过 5.1 和 5.2：

mkdir pretrained_model cd pretrained_model # 下载PubLayNet预训练模型（直接体验模型评估、预测、动转静） wget https://paddleocr.bj.bcebos.com/ppstructure/models/layout/picodet_lcnet_x1_0_fgd_layout.pdparams # 下载PubLaynet推理模型（直接体验模型推理） wget https://paddleocr.bj.bcebos.com/ppstructure/models/layout/picodet_lcnet_x1_0_fgd_layout_infer.tar

如果测试图片为中文，可下载中文 CDLA 数据集的预训练模型picodet_lcnet_x1_0_fgd_layout_cdla（训练模型 + 推理模型）；如果只检测表格区域，可下载picodet_lcnet_x1_0_fgd_layout_table模型，两者均见 models_list。

5.1 启动训练

使用 PaddleDetection 的版面分析配置文件启动训练，先修改配置文件中的数据配置与类别数。以configs/picodet/legacy_model/application/layout_analysis/picodet_lcnet_x1_0_layout.yml为例：

metric: COCO # 类别数 num_classes: 5 TrainDataset: !COCODataSet # 修改为你自己的训练数据目录 image_dir: train # 修改为你自己的训练数据标签文件 anno_path: train.json # 修改为你自己的训练数据根目录 dataset_dir: /root/publaynet/ data_fields: ['image', 'gt_bbox', 'gt_class', 'is_crowd'] EvalDataset: !COCODataSet # 修改为你自己的验证数据目录 image_dir: val # 修改为你自己的验证数据标签文件 anno_path: val.json # 修改为你自己的验证数据根目录 dataset_dir: /root/publaynet/ TestDataset: !ImageFolder # 修改为你自己的测试数据标签文件 anno_path: /root/publaynet/val.json

开始训练（训练时会默认下载 PP-PicoDet 预训练模型，无需预先下载）：

# GPU训练 支持单卡，多卡训练 # 训练日志会自动保存到 log 目录中 # 单卡训练 export CUDA_VISIBLE_DEVICES=0 python3 tools/train.py \ -c configs/picodet/legacy_model/application/layout_analysis/picodet_lcnet_x1_0_layout.yml \ --eval # 多卡训练，通过--gpus参数指定卡号 export CUDA_VISIBLE_DEVICES=0,1,2,3 python3 -m paddle.distributed.launch --gpus '0,1,2,3' tools/train.py \ -c configs/picodet/legacy_model/application/layout_analysis/picodet_lcnet_x1_0_layout.yml \ --eval

注意：如果训练时显存不足（out of memory），将TrainReader中batch_size调小，同时将LearningRate中base_lr等比例减小。官方发布的 config 均由 8 卡训练得到，如果改为单卡训练，base_lr需减小 8 倍。

正常启动训练后，会看到以下 log 输出：

[08/15 04:02:30] ppdet.utils.checkpoint INFO: Finish loading model weights: /root/.cache/paddle/weights/LCNet_x1_0_pretrained.pdparams [08/15 04:02:46] ppdet.engine INFO: Epoch: [0] [ 0/1929] learning_rate: 0.040000 loss_vfl: 1.216707 loss_bbox: 1.142163 loss_dfl: 0.544196 loss: 2.903065 eta: 17 days, 13:50:26 batch_cost: 15.7452 data_cost: 2.9112 ips: 1.5243 images/s [08/15 04:03:19] ppdet.engine INFO: Epoch: [0] [ 20/1929] learning_rate: 0.064000 loss_vfl: 1.180627 loss_bbox: 0.939552 loss_dfl: 0.442436 loss: 2.628206 eta: 2 days, 12:18:53 batch_cost: 1.5770 data_cost: 0.0008 ips: 15.2184 images/s [08/15 04:03:47] ppdet.engine INFO: Epoch: [0] [ 40/1929] learning_rate: 0.088000 loss_vfl: 0.543321 loss_bbox: 1.071401 loss_dfl: 0.457817 loss: 2.057003 eta: 2 days, 0:07:03 batch_cost: 1.3190 data_cost: 0.0007 ips: 18.1954 images/s [08/15 04:04:12] ppdet.engine INFO: Epoch: [0] [ 60/1929] learning_rate: 0.112000 loss_vfl: 0.630989 loss_bbox: 0.859183 loss_dfl: 0.384702 loss: 1.883142 eta: 1 day, 19:01:29 batch_cost: 1.2177 data_cost: 0.0006 ips: 19.7087 images/s

日志中的loss_vfl、loss_bbox、loss_dfl分别是 PicoDet 的 Varifocal 分类损失、边界框回归损失与 DFL（Distribution Focal Loss）损失，--eval表示训练同时进行评估，评估过程中默认将最佳模型保存为output/picodet_lcnet_x1_0_layout/best_accuracy。

注意，预测/评估时的配置文件请务必与训练一致。

5.2 FGD 蒸馏训练

PaddleDetection 支持基于 FGD（Focal and Global Knowledge Distillation for Detectors）的目标检测蒸馏训练。FGD 蒸馏分为Focal与Global两部分：

• Focal 蒸馏：分离图像的前景和背景，让学生模型分别关注教师模型前景、背景特征中的关键像素；
• Global 蒸馏：重建不同像素之间的关系并将其从教师转移到学生，以补偿 Focal 蒸馏中丢失的全局信息。

更换数据集时，参照 4.1 修改配置文件中的数据配置与类别数（教师模型picodet_lcnet_x2_5_layout.yml的num_classes也需同步修改），然后启动训练：

# 单卡训练 export CUDA_VISIBLE_DEVICES=0 python3 tools/train.py \ -c configs/picodet/legacy_model/application/layout_analysis/picodet_lcnet_x1_0_layout.yml \ --slim_config configs/picodet/legacy_model/application/layout_analysis/picodet_lcnet_x2_5_layout.yml \ --eval

• -c：指定模型配置文件（学生模型，如 x1_0）。
• --slim_config：指定压缩策略配置文件（教师模型，如 x2_5）。

官方发布的 PubLayNet 英文版面分析模型picodet_lcnet_x1_0_fgd_layout正是该蒸馏流程的产物，教师模型为更大的lcnet_x2_5，学生模型在保持轻量的同时获得了接近大模型的精度。

6. 模型评估与预测

6.1 指标评估

训练中模型参数默认保存在output/picodet_lcnet_x1_0_layout目录下。评估时需设置weights指向保存的参数文件，评估数据集可通过配置文件中的EvalDataset（image_dir、anno_path、dataset_dir）设置：

# GPU 评估， weights 为待测权重 python3 tools/eval.py \ -c configs/picodet/legacy_model/application/layout_analysis/picodet_lcnet_x1_0_layout.yml \ -o weights=./output/picodet_lcnet_x1_0_layout/best_model

评估完成后会输出 COCO 风格的 mAP、AP0.5 等信息：

Average Precision (AP) @[ IoU=0.50:0.95 | area= all | maxDets=100 ] = 0.935 Average Precision (AP) @[ IoU=0.50 | area= all | maxDets=100 ] = 0.979 Average Precision (AP) @[ IoU=0.75 | area= all | maxDets=100 ] = 0.956 Average Precision (AP) @[ IoU=0.50:0.95 | area= small | maxDets=100 ] = 0.404 Average Precision (AP) @[ IoU=0.50:0.95 | area=medium | maxDets=100 ] = 0.782 Average Precision (AP) @[ IoU=0.50:0.95 | area= large | maxDets=100 ] = 0.969 Average Recall (AR) @[ IoU=0.50:0.95 | area= all | maxDets= 1 ] = 0.539 Average Recall (AR) @[ IoU=0.50:0.95 | area= all | maxDets= 10 ] = 0.938 Average Recall (AR) @[ IoU=0.50:0.95 | area= all | maxDets=100 ] = 0.949 Average Recall (AR) @[ IoU=0.50:0.95 | area= small | maxDets=100 ] = 0.495 Average Recall (AR) @[ IoU=0.50:0.95 | area=medium | maxDets=100 ] = 0.818 Average Recall (AR) @[ IoU=0.50:0.95 | area= large | maxDets=100 ] = 0.978 [08/15 07:07:09] ppdet.engine INFO: Total sample number: 11245, averge FPS: 24.405059207157436 [08/15 07:07:09] ppdet.engine INFO: Best test bbox ap is 0.935.

若使用官方提供的预训练模型评估，或使用 FGD 蒸馏训练的模型，更换weights模型路径并追加蒸馏配置：

python3 tools/eval.py \ -c configs/picodet/legacy_model/application/layout_analysis/picodet_lcnet_x1_0_layout.yml \ --slim_config configs/picodet/legacy_model/application/layout_analysis/picodet_lcnet_x2_5_layout.yml \ -o weights=output/picodet_lcnet_x2_5_layout/best_model

• -c：指定模型配置文件。
• --slim_config：指定蒸馏策略配置文件。
• -o weights：指定蒸馏算法训好的模型路径。

6.2 测试版面分析结果

预测使用的配置文件必须与训练一致。使用 PaddleDetection 训练好的模型进行预测：

python3 tools/infer.py \ -c configs/picodet/legacy_model/application/layout_analysis/picodet_lcnet_x1_0_layout.yml \ -o weights='output/picodet_lcnet_x1_0_layout/best_model.pdparams' \ --infer_img='docs/images/layout.jpg' \ --output_dir=output_dir/ \ --draw_threshold=0.5

• --infer_img：推理单张图片，也可以通过--infer_dir推理目录中的所有图片。
• --output_dir：指定可视化结果保存路径。
• --draw_threshold：指定绘制结果框的 NMS 阈值。

若使用官方预训练模型或 FGD 蒸馏模型进行预测，更换weights并追加--slim_config：

python3 tools/infer.py \ -c configs/picodet/legacy_model/application/layout_analysis/picodet_lcnet_x1_0_layout.yml \ --slim_config configs/picodet/legacy_model/application/layout_analysis/picodet_lcnet_x2_5_layout.yml \ -o weights='output/picodet_lcnet_x2_5_layout/best_model.pdparams' \ --infer_img='docs/images/layout.jpg' \ --output_dir=output_dir/ \ --draw_threshold=0.5

7. 模型导出与推理部署

7.1 模型导出（动转静）

inference 模型（paddle.jit.save保存的模型）是训练完成后把模型结构和参数固化到文件中的模型，多用于预测部署场景；checkpoints 模型只保存模型参数，多用于恢复训练。相比 checkpoints，inference 模型额外保存了结构信息，预测部署、加速推理性能更优，适合实际系统集成。

版面分析模型转 inference 模型的步骤：

python3 tools/export_model.py \ -c configs/picodet/legacy_model/application/layout_analysis/picodet_lcnet_x1_0_layout.yml \ -o weights=output/picodet_lcnet_x1_0_layout/best_model \ --output_dir=output_inference/

导出选项说明：

• 如无需导出后处理，请指定：-o export.benchmark=True（若-o已出现过，此处删掉-o）。
• 如无需导出 NMS，请指定：-o export.nms=False。

转换成功后，目录下有三个文件：

output_inference/picodet_lcnet_x1_0_layout/ ├── model.pdiparams # inference模型的参数文件 ├── model.pdiparams.info # inference模型的参数信息，可忽略 └── model.pdmodel # inference模型的模型结构文件

若使用官方预训练模型或 FGD 蒸馏模型转 inference 模型，更换weights并追加--slim_config：

python3 tools/export_model.py \ -c configs/picodet/legacy_model/application/layout_analysis/picodet_lcnet_x1_0_layout.yml \ --slim_config configs/picodet/legacy_model/application/layout_analysis/picodet_lcnet_x2_5_layout.yml \ -o weights=./output/picodet_lcnet_x2_5_layout/best_model \ --output_dir=output_inference/

7.2 模型推理

使用导出的 inference 模型进行推理（更换model_dir为对应模型路径）：

python3 deploy/python/infer.py \ --model_dir=output_inference/picodet_lcnet_x1_0_layout/ \ --image_file=docs/images/layout.jpg \ --device=CPU

• --device：指定 GPU、CPU 设备。

推理完成会看到以下 log 输出：

------------------------------------------ ----------- Model Configuration ----------- Model Arch: PicoDet Transform Order: --transform op: Resize --transform op: NormalizeImage --transform op: Permute --transform op: PadStride -------------------------------------------- class_id:0, confidence:0.9921, left_top:[20.18,35.66],right_bottom:[341.58,600.99] class_id:0, confidence:0.9914, left_top:[19.77,611.42],right_bottom:[341.48,901.82] class_id:0, confidence:0.9904, left_top:[369.36,375.10],right_bottom:[691.29,600.59] class_id:0, confidence:0.9835, left_top:[369.60,608.60],right_bottom:[691.38,736.72] class_id:0, confidence:0.9830, left_top:[369.58,805.38],right_bottom:[690.97,901.80] class_id:0, confidence:0.9716, left_top:[383.68,271.44],right_bottom:[688.93,335.39] class_id:0, confidence:0.9452, left_top:[370.82,34.48],right_bottom:[688.10,63.54] class_id:1, confidence:0.8712, left_top:[370.84,771.03],right_bottom:[519.30,789.13] class_id:3, confidence:0.9856, left_top:[371.28,67.85],right_bottom:[685.73,267.72] save result to: output/layout.jpg Test iter 0 ------------------ Inference Time Info ---------------------- total_time(ms): 2196.0, img_num: 1 average latency time(ms): 2196.00, QPS: 0.455373 preprocess_time(ms): 2172.50, inference_time(ms): 11.90, postprocess_time(ms): 11.60

输出字段解读：

• Model：模型结构，此处为 PicoDet。
• Transform Order：预处理操作序列，此处为 Resize → NormalizeImage → Permute → PadStride。
• class_id、confidence、left_top、right_bottom：分别表示类别 id、置信度、左上角坐标、右下角坐标。注意 class_id 需结合推理时使用的类别字典解读（见第 1 节）。
• save result to：可视化版面分析结果保存路径，默认保存到./output文件夹。
• Inference Time Info：推理耗时拆分，其中preprocess_time为预处理耗时、inference_time为模型预测耗时、postprocess_time为后处理耗时。

8. 结合源码理解版面分析的实现链路

除 PaddleDetection 训练链路外，PaddleOCR 仓库内还提供了可直接调用的版面分析推理实现，可作为理解原理的参考：

• 推理入口：predict_layout.py 中的LayoutPredictor类完成版面分析的完整推理。其预处理与 PaddleDetection 保持一致：先将图像 Resize 到[800, 608]，再做 ImageNet 均值/方差归一化（mean=[0.485, 0.456, 0.406]、std=[0.229, 0.224, 0.225]）、转 CHW、保留 image key；后处理使用PicoDetPostProcess，并通过layout_score_threshold（默认 0.5）与layout_nms_threshold（默认 0.5）两个阈值控制检测框输出（见 ppstructure/utility.py）。
• 参数定义：ppstructure/utility.py 定义了--layout_model_dir、--layout_dict_path、--layout_score_threshold、--layout_nms_threshold等版面分析专属参数，其中layout_dict_path默认指向layout_publaynet_dict.txt。
• 系统集成：predict_system.py 展示了版面分析结果如何驱动后续流程：先调用layout_predictor(img)得到各区域 bbox 与 label，再按区域类型分发——table 区域进入表格识别，其余区域进入 OCR，并依据 bbox 过滤与区域相交的文本结果。这也解释了为何 PP-Structure 能基于版面分析实现"按区域还原"的文档结构化能力。

9. 参考引用

版面分析模型训练与 FGD 蒸馏分别基于以下两篇论文，引用格式如下：

@inproceedings{zhong2019publaynet, title={PubLayNet: largest dataset ever for document layout analysis}, author={Zhong, Xu and Tang, Jianbin and Yepes, Antonio Jimeno}, booktitle={2019 International Conference on Document Analysis and Recognition (ICDAR)}, year={2019}, volume={}, number={}, pages={1015-1022}, doi={10.1109/ICDAR.2019.00166}, ISSN={1520-5363}, month={Sep.}, organization={IEEE} } @inproceedings{yang2022focal, title={Focal and global knowledge distillation for detectors}, author={Yang, Zhendong and Li, Zhe and Jiang, Xiaohu and Gong, Yuan and Yuan, Zehuan and Zhao, Danpei and Yuan, Chun}, booktitle={Proceedings of the IEEE/CVF Conference on Computer Vision and Pattern Recognition}, pages={4643--4652}, year={2022} }

结语

版面分析是 PP-Structure 文档理解能力的基石。通过本文，你可以掌握从 PubLayNet 数据准备、PicoDet 配置文件修改、单卡/多卡训练、FGD 蒸馏，到 mAP 评估、可视化预测、动转静导出与 inference 推理的完整闭环；同时结合仓库源码（predict_layout.py、predict_system.py、layout_dict）理解其底层实现，为后续接入表格识别、文档还原甚至 RAG 数据管道打好基础。

【免费下载链接】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