PaddleOCR VI-LayoutXLM 关键信息抽取(KIE)算法实战:从训练到推理部署全流程指南
PaddleOCR VI-LayoutXLM 关键信息抽取(KIE)算法实战:从训练到推理部署全流程指南
VI-LayoutXLM 是 PaddleOCR 中基于 LayoutXLM 改进的多模态文档理解算法,通过在下游微调阶段移除视觉骨干网络,在几乎无损精度的前提下显著提升推理速度。本文以 XFUND_zh 数据集上的 SER(语义实体识别)与 RE(关系抽取)两个任务为主线,完整讲解 VI-LayoutXLM 的数据准备、模型训练、评估、模型导出与 Python 推理部署全流程,并深入其配置文件与源码实现,帮助你快速将票据、证件、表单类文档中的关键信息结构化提取落地到实际业务中。
1. 算法概述
VI-LayoutXLM 是 LayoutXLM 的改进版本。LayoutXLM 是面向多语言视觉丰富文档理解的多模态预训练模型,在文本信息之外同时引入版面布局(layout)与视觉(visual)信息;而 VI-LayoutXLM 在下游微调(finetuning)过程中移除视觉骨干网络模块(visual backbone),在保持精度几乎无损的前提下,进一步提升了模型的推理速度。
在 XFUND_zh(中文表单理解数据集)上,PaddleOCR 复现的 VI-LayoutXLM 算法 Hmean 指标如下:
| Model | Backbone | Task | Config | Hmean |
|---|---|---|---|---|
| VI-LayoutXLM | VI-LayoutXLM-base | SER | ser_vi_layoutxlm_xfund_zh_udml.yml | 93.19% |
| VI-LayoutXLM | VI-LayoutXLM-base | RE | re_vi_layoutxlm_xfund_zh_udml.yml | 83.92% |
其中 SER(Semantic Entity Recognition)为语义实体识别,将文档中的文本行分类为预定义类别(如 QUESTION、ANSWER、HEADER 等);RE(Relation Extraction)为关系抽取,在实体基础上进一步抽取实体之间的关联关系(如"问题-答案"配对)。
从源码结构看,VI-LayoutXLM 在 PaddleOCR 中的实现位于 ppocr/modeling/backbones/vqa_layoutlm.py,它直接复用了 PaddleNLP 的 LayoutXLMForTokenClassification(SER)与 LayoutXLMForRelationExtraction(RE)模型。模型加载时通过 mode 参数区分预训练权重:
pretrained_model_dict = {
LayoutXLMModel: {
"base": "layoutxlm-base-uncased",
"vi": "vi-layoutxlm-base-uncased",
},
...
}
即 mode: vi 时加载 vi-layoutxlm-base-uncased 预训练权重,这正是 VI-LayoutXLM 的落地方式;而 mode: base 时则使用原始 LayoutXLM 权重。
2. 环境准备
使用 VI-LayoutXLM 之前,需要先完成 PaddleOCR 运行环境的配置与项目代码的克隆,请参考:
- 环境准备(Environment Preparation):安装 PaddlePaddle、PaddleOCR 及其依赖;
- 项目克隆(Project Clone):获取 PaddleOCR 仓库代码。
VI-LayoutXLM 系列模型依赖 PaddleNLP 提供的预训练模型与模型类(LayoutXLMForTokenClassification、LayoutXLMForRelationExtraction 等,见 vqa_layoutlm.py 的导入语句),因此环境中需要安装与 PaddleOCR 版本匹配的 PaddleNLP。
3. 数据准备
VI-LayoutXLM 的训练与评估使用 XFUND 数据集(包含中文等多语言表单数据),也可按相同格式构造自定义数据集。完整的数据准备流程(数据格式、字典文件、自定义数据集、下载与转换脚本)请参考 KIE 教程,其要点包括:
- 训练数据默认存放在
PaddleOCR/train_data,可通过软链接复用已有数据集; - 标注文件为文本文件,每行由
图片路径\tJSON标注组成,JSON 是文本行标注的列表,每个文本行包含transcription(文本内容)、label(类别)、points(四点坐标)、id(文本行 ID,RE 任务使用)、linking(文本行间关联信息,RE 任务使用)等字段; - 类别字典文件(如
class_list_xfun.txt)每行一个标签名,建议将other类别放在第一行(解析时其类别 ID 为 0,预测为other的文本行不会被可视化); - 可直接下载 XFUND 原始数据,并使用 trans_xfun_data.py 转换为 PaddleOCR 格式;FUNSD 数据则使用 trans_funsd_label.py 转换。
下载 XFUND_zh 数据的命令如下:
mkdir train_data
cd train_data
wget https://paddleocr.bj.bcebos.com/ppstructure/dataset/XFUND.tar && tar -xf XFUND.tar
cd ..
4. 模型训练
PaddleOCR 对代码结构进行了模块化,训练不同的 KIE 模型只需要替换配置文件即可。VI-LayoutXLM 的 SER 与 RE 训练配置分别位于 ser_vi_layoutxlm_xfund_zh.yml 与 re_vi_layoutxlm_xfund_zh.yml。
4.1 启动训练
使用 XFUND_zh 数据快速开始训练:
# 单卡训练 SER 模型
python3 tools/train.py -c configs/kie/vi_layoutxlm/ser_vi_layoutxlm_xfund_zh.yml
# 多卡训练 SER 模型,使用 --gpus 指定 GPU ID
python3 -m paddle.distributed.launch --gpus '0,1,2,3' tools/train.py -c configs/kie/vi_layoutxlm/ser_vi_layoutxlm_xfund_zh.yml
# 单卡训练 RE 模型
python3 tools/train.py -c configs/kie/vi_layoutxlm/re_vi_layoutxlm_xfund_zh.yml
训练启动后会输出类似如下的日志:
[2022/08/08 16:28:28] ppocr INFO: epoch: [1/200], global_step: 10, lr: 0.000006, loss: 1.871535, avg_reader_cost: 0.28200 s, avg_batch_cost: 0.82318 s, avg_samples: 8.0, ips: 9.71838 samples/s, eta: 0:51:59
[2022/08/08 16:28:45] ppocr INFO: save best model is to ./output/ser_vi_layoutxlm_xfund_zh/best_accuracy
[2022/08/08 16:28:45] ppocr INFO: best metric, hmean: 0.14564265817747712, precision: 0.11526348939743859, recall: 0.19776657060518732, fps: 34.008392345050055, best_epoch: 1
日志字段含义如下:
| 字段 | 含义 |
|---|---|
| epoch | 当前迭代轮数 |
| global_step | 当前迭代次数 |
| lr | 当前学习率 |
| loss | 当前损失函数值 |
| avg_reader_cost | 当前 batch 数据读取耗时 |
| avg_batch_cost | 当前 batch 总耗时 |
| avg_samples | 当前 batch 样本数 |
| ips | 每秒处理样本数 |
训练过程中默认每 19 个迭代执行一次评估(由 eval_batch_step: [0, 19] 控制),在验证集上取得最佳 hmean 的模型会自动保存为 output/ser_vi_layoutxlm_xfund_zh/best_accuracy/。若评估数据集较大,建议增大评估间隔或训练完成后单独评估。
4.2 关键配置项解析(SER 配置)
以 ser_vi_layoutxlm_xfund_zh.yml 为例,核心配置说明如下:
Global:
use_gpu: True
epoch_num: &epoch_num 200 # 训练总轮数
eval_batch_step: [0, 19] # 第 0 次迭代后每 19 次迭代评估一次
save_model_dir: ./output/ser_vi_layoutxlm_xfund_zh
infer_img: ppstructure/docs/kie/input/zh_val_42.jpg
# 如需使用预先标注好的 OCR 结果进行预测,可配置:
# infer_img: train_data/XFUND/zh_val/val.json
# infer_mode: False
Architecture:
model_type: kie
algorithm: "LayoutXLM"
Backbone:
name: LayoutXLMForSer # SER 任务模型头
pretrained: True # 使用 PaddleNLP 预训练权重
checkpoints: # 断点续训/微调时指定训练权重路径
mode: vi # one of base or vi(vi 即 VI-LayoutXLM)
num_classes: &num_classes 7 # 类别数,XFUND 为 4 类,按 2n-1 计算为 7
Loss:
name: VQASerTokenLayoutLMLoss
num_classes: *num_classes
key: "backbone_out"
Optimizer:
name: AdamW
lr:
name: Linear
learning_rate: 0.00005 # 学习率
epochs: *epoch_num
warmup_epoch: 2
PostProcess:
name: VQASerTokenLayoutLMPostProcess
class_path: &class_path train_data/XFUND/class_list_xfun.txt # 类别字典
Metric:
name: VQASerTokenMetric
main_indicator: hmean # 以 hmean 作为主指标
Train:
dataset:
name: SimpleDataSet
data_dir: train_data/XFUND/zh_train/image
label_file_list:
- train_data/XFUND/zh_train/train.json
transforms:
- VQATokenLabelEncode: # 将文本行标注编码为 token 级标签
contains_re: False
algorithm: "LayoutXLM"
class_path: *class_path
use_textline_bbox_info: &use_textline_bbox_info True
order_method: &order_method "tb-yx" # one of [None, "tb-yx"]
- VQATokenPad: # token 序列 padding 到 512
max_seq_len: &max_seq_len 512
return_attention_mask: True
- VQASerTokenChunk: # 序列切块
max_seq_len: *max_seq_len
- Resize: # 图像缩放 224x224(视觉特征输入)
size: [224,224]
- NormalizeImage: # ImageNet 风格归一化
mean: [123.675, 116.28, 103.53]
std: [58.395, 57.12, 57.375]
order: 'hwc'
loader:
shuffle: True
batch_size_per_card: 8
num_workers: 4
几个需要重点理解的配置:
num_classes:SER 采用 BIO 标注体系,若字典包含 n 个类别(含other),则num_classes设置为2n-1。XFUND_zh 的字典 class_list_xfun.txt 包含OTHER/QUESTION/ANSWER/HEADER四类,故配置为7;mode: vi:控制加载vi-layoutxlm-base-uncased预训练权重,是 VI-LayoutXLM 与普通 LayoutXLM(mode: base)的关键区分点;order_method: "tb-yx":控制 OCR 文本行按自上而下(top-bottom)再从左到右的顺序排列,保持文档阅读顺序与 token 序列一致;VQASerTokenChunk与max_seq_len: 512:当文档 token 数超过 512 时自动切块处理。
RE 配置 re_vi_layoutxlm_xfund_zh.yml 与 SER 的主要差异在于:Backbone 使用 LayoutXLMForRe、Loss 使用 LossFromOutput(取 pred_relations 输出)、数据变换中增加 VQAReTokenRelation(生成实体-关系对)与 TensorizeEntitiesRelations(将实体与关系张量化),且 contains_re: True。
4.3 断点续训
若训练中断,可通过 Architecture.Backbone.checkpoints 指定要加载的权重继续训练:
python3 tools/train.py -c configs/kie/vi_layoutxlm/ser_vi_layoutxlm_xfund_zh.yml -o Architecture.Backbone.checkpoints=./output/ser_vi_layoutxlm_xfund_zh/best_accuracy
注意:
Architecture.Backbone.checkpoints的优先级高于Architecture.Backbone.pretrained;微调、续训、评估都必须设置checkpoints;- 若想使用 PaddleNLP 预训练模型从头训练,需设置
Architecture.Backbone.pretrained=True且Architecture.Backbone.checkpoints=null; - LayoutXLM 系列模型的加载与保存逻辑与 PaddleNLP 一致,无需设置
Global.pretrained_model或Global.checkpoints; - 若使用知识蒸馏训练 LayoutXLM 系列模型,目前不支持断点续训。
4.4 分布式训练与知识蒸馏
多机多卡训练时,通过 --ips 指定参与训练的机器 IP,通过 --gpus 指定 GPU ID:
python3 -m paddle.distributed.launch --ips="xx.xx.xx.xx,xx.xx.xx.xx" --gpus '0,1,2,3' tools/train.py -c configs/kie/vi_layoutxlm/ser_vi_layoutxlm_xfund_zh.yml
使用多机训练时需将 ips 替换为实际机器地址,且各机器需要能够互相 ping 通,并分别在多台机器上启动训练。
PaddleOCR 还支持使用知识蒸馏训练 KIE 模型,对应的配置文件为 ser_vi_layoutxlm_xfund_zh_udml.yml(文档中表格所示的 93.19% 即来自该蒸馏配置)。蒸馏过程中只保存学生模型的参数,评估时需使用学生模型对应的配置(即 ser_vi_layoutxlm_xfund_zh.yml)。
4.5 其他平台说明
- Windows GPU/CPU:仅支持单 GPU 训练与推理,用
set CUDA_VISIBLE_DEVICES=0指定 GPU;DataLoader 仅支持单进程模式,需将num_workers设为 0; - macOS:不支持 GPU 模式,需在配置中将
use_gpu设为 False,其余命令与 Linux GPU 相同; - Linux DCU:需设置环境变量
export HIP_VISIBLE_DEVICES=0,1,2,3,其余命令与 Linux GPU 相同。
5. 模型评估与测试
5.1 评估
评估时需将 Architecture.Backbone.checkpoints 指向模型目录,评估数据集可通过修改 Eval.dataset.label_file_list 指定:
python3 tools/eval.py -c configs/kie/vi_layoutxlm/ser_vi_layoutxlm_xfund_zh.yml -o Architecture.Backbone.checkpoints=./output/ser_vi_layoutxlm_xfund_zh/best_accuracy
评估完成后会打印 precision、recall、hmean、fps 等指标:
[2022/08/09 07:59:28] ppocr INFO: metric eval ***************
[2022/08/09 07:59:28] ppocr INFO: precision:0.697476609016161
[2022/08/09 07:59:28] ppocr INFO: recall:0.8861671469740634
[2022/08/09 07:59:28] ppocr INFO: hmean:0.7805806758686339
[2022/08/09 07:59:28] ppocr INFO: fps:17.367364606899105
5.2 训练产物目录
训练完成后,Global.save_model_dir 目录下的产物结构如下:
output/ser_vi_layoutxlm_xfund_zh/
├── best_accuracy
│ ├── metric.states
│ ├── model_config.json
│ ├── model_state.pdparams
├── best_accuracy.pdopt
├── config.yml
├── train.log
├── latest
│ ├── metric.states
│ ├── model_config.json
│ ├── model_state.pdparams
├── latest.pdopt
其中 best_accuracy.* 是评估集上表现最佳的模型,latest.* 是最后一个 epoch 的模型。
5.3 测试(训练权重直接预测)
预测时默认读取 Global.infer_img 指定的图片,训练权重通过 -o Architecture.Backbone.checkpoints=... 指定:
python3 tools/infer_kie_token_ser.py -c configs/kie/vi_layoutxlm/ser_vi_layoutxlm_xfund_zh.yml -o Architecture.Backbone.checkpoints=./output/ser_vi_layoutxlm_xfund_zh/best_accuracy Global.infer_img=./ppstructure/docs/kie/input/zh_val_42.jpg
预测过程默认加载 PP-OCRv3 的检测与识别模型实时提取 OCR 信息;若想直接使用预先标注好的 OCR 结果,可指定 Global.infer_img 为包含图片路径与 OCR 信息的标注文件,并设置 Global.infer_mode=False 关闭 OCR 推理引擎:
python3 tools/infer_kie_token_ser.py -c configs/kie/vi_layoutxlm/ser_vi_layoutxlm_xfund_zh.yml -o Architecture.Backbone.checkpoints=./output/ser_vi_layoutxlm_xfund_zh/best_accuracy Global.infer_img=./train_data/XFUND/zh_val/val.json Global.infer_mode=False
RE 模型预测依赖 SER 模型的输出,因此需要同时加载 SER 的配置与权重(-c_ser 指定 SER 配置文件,-o_ser 指定覆盖 SER 配置的参数):
python3 ./tools/infer_kie_token_ser_re.py \
-c configs/kie/vi_layoutxlm/re_vi_layoutxlm_xfund_zh.yml \
-o Architecture.Backbone.checkpoints=./output/re_vi_layoutxlm_xfund_zh/best_accuracy \
Global.infer_img=./train_data/XFUND/zh_val/image/ \
-c_ser configs/kie/vi_layoutxlm/ser_vi_layoutxlm_xfund_zh.yml \
-o_ser Architecture.Backbone.checkpoints=./output/ser_vi_layoutxlm_xfund_zh/best_accuracy/
6. 模型导出与 Python 推理部署
6.1 导出推理模型
训练得到的 checkpoints 模型只保存参数,主要用于续训;推理模型由 paddle.jit.save 固化模型结构与参数,便于部署集成。导出命令如下:
# 导出 SER 推理模型
python3 tools/export_model.py -c configs/kie/vi_layoutxlm/ser_vi_layoutxlm_xfund_zh.yml \
-o Architecture.Backbone.checkpoints=./output/ser_vi_layoutxlm_xfund_zh/best_accuracy \
Global.save_inference_dir=./inference/ser_vi_layoutxlm_infer
# 导出 RE 推理模型
python3 tools/export_model.py -c configs/kie/vi_layoutxlm/re_vi_layoutxlm_xfund_zh.yml \
-o Architecture.Backbone.checkpoints=./output/re_vi_layoutxlm_xfund_zh/best_accuracy \
Global.save_inference_dir=./inference/re_vi_layoutxlm_infer
导出成功后目录下包含三个文件:
inference/ser_vi_layoutxlm_infer/
├── inference.pdiparams # 推理模型参数文件
├── inference.pdiparams.info # 参数信息文件,可忽略
└── inference.pdmodel # 推理模型结构文件
如果未自行训练,也可直接下载 PaddleOCR 提供的预训练权重(SER:ser_vi_layoutxlm_xfund_pretrained.tar,RE:re_vi_layoutxlm_xfund_pretrained.tar)再执行导出。
6.2 SER Python 推理
cd ppstructure
python3 kie/predict_kie_token_ser.py \
--kie_algorithm=LayoutXLM \
--ser_model_dir=../inference/ser_vi_layoutxlm_infer \
--image_dir=./docs/kie/input/zh_val_42.jpg \
--ser_dict_path=../train_data/XFUND/class_list_xfun.txt \
--vis_font_path=../doc/fonts/simfang.ttf \
--ocr_order_method="tb-yx"
SER 可视化结果默认保存在 ./output 目录:
6.3 RE Python 推理
RE 推理需要同时指定 SER 与 RE 推理模型,并通过 --use_visual_backbone=False 显式关闭视觉骨干网络(这正是 VI-LayoutXLM 相对 LayoutXLM 的核心改进,也是其在精度几乎无损的情况下提升推理速度的关键):
cd ppstructure
python3 kie/predict_kie_token_ser_re.py \
--kie_algorithm=LayoutXLM \
--re_model_dir=../inference/re_vi_layoutxlm_infer \
--ser_model_dir=../inference/ser_vi_layoutxlm_infer \
--use_visual_backbone=False \
--image_dir=./docs/kie/input/zh_val_42.jpg \
--ser_dict_path=../train_data/XFUND/class_list_xfun.txt \
--vis_font_path=../doc/fonts/simfang.ttf \
--ocr_order_method="tb-yx"
RE 可视化结果(实体间的连线表示抽取出的关系)默认保存在 ./output 目录:
6.4 推理脚本的源码级说明
上述两个推理入口分别是 ppstructure/kie/predict_kie_token_ser.py 与 ppstructure/kie/predict_kie_token_ser_re.py。
- SER 推理链路:
SerPredictor内部先构建PaddleOCR引擎对输入图片做检测与识别,再依次执行VQATokenLabelEncode → VQATokenPad → VQASerTokenChunk → Resize → NormalizeImage → ToCHWImage预处理,送入 SER 推理模型,最后经VQASerTokenLayoutLMPostProcess后处理输出 token 级标签,并通过draw_ser_results可视化; - RE 推理链路:
SerRePredictor先调用 SER 引擎获得实体结果,再通过make_input(来自 tools/infer_kie_token_ser_re.py)将 SER 输出组装成 RE 模型输入;若use_visual_backbone == False,则从输入中移除视觉特征通道(re_input.pop(4)),与训练时 VI 模式的行为保持一致;RE 输出经VQAReTokenLayoutLMPostProcess后处理并结合实体索引字典输出关系对。
从 ppocr/modeling/backbones/vqa_layoutlm.py 的实现可以看到,NLPBaseModel 中 use_visual_backbone 默认置为 True,而 LayoutXLMForSer(普通 LayoutXLM)中显式将其置为 False;VI-LayoutXLM 则通过 mode: vi 选择 vi-layoutxlm-base-uncased 权重并在训练/推理阶段统一去掉视觉骨干,可以推断这正是其加速的核心来源。
6.5 部署能力边界
按照官方文档说明,VI-LayoutXLM 的部署支持情况如下:
- C++ 推理:不支持;
- Serving 服务化部署:不支持;
- 更多部署形态:不支持。
即当前仅支持上述 Python 推理方式,部署前请评估该约束是否满足业务需求。
7. FAQ
Q1:训练模型转为推理模型后,预测效果不一致?
A:此类问题大多由训练时模型预测所用的前后处理参数与推理模型预测时的前后处理参数不一致导致。可以对比训练所用的配置文件与推理过程中的预处理、后处理及预测参数是否存在差异(例如 NormalizeImage 的 mean/std、VQATokenPad 的 max_seq_len、order_method 等)。
8. 引用文献
VI-LayoutXLM 依赖的 LayoutXLM、LayoutLM、LayoutLMv2 相关工作引用如下:
@article{DBLP:journals/corr/abs-2104-08836,
author = {Yiheng Xu and Tengchao Lv and Lei Cui and Guoxin Wang and
Yijuan Lu and Dinei Flor{\^{e}}ncio and Cha Zhang and Furu Wei},
title = {LayoutXLM: Multimodal Pre-training for Multilingual Visually-rich
Document Understanding},
journal = {CoRR},
volume = {abs/2104.08836},
year = {2021}
}
@article{DBLP:journals/corr/abs-1912-13318,
author = {Yiheng Xu and Minghao Li and Lei Cui and Shaohan Huang and
Furu Wei and Ming Zhou},
title = {LayoutLM: Pre-training of Text and Layout for Document Image Understanding},
journal = {CoRR},
volume = {abs/1912.13318},
year = {2019}
}
@article{DBLP:journals/corr/abs-2012-14740,
author = {Yang Xu and Yiheng Xu and Tengchao Lv and Lei Cui and Furu Wei and
Guoxin Wang and Yijuan Lu and Dinei A. F. Flor{\^{e}}ncio and
Cha Zhang and Wanxiang Che and Min Zhang and Lidong Zhou},
title = {LayoutLMv2: Multi-modal Pre-training for Visually-Rich Document Understanding},
journal = {CoRR},
volume = {abs/2012.14740},
year = {2020}
}

