PaddleOCR 关键信息抽取(KIE)实战:LayoutXLM 多模态文档语义实体识别与关系抽取全流程指南
PaddleOCR 关键信息抽取(KIE)实战:LayoutXLM 多模态文档语义实体识别与关系抽取全流程指南
本文以 PaddleOCR 中 LayoutXLM 算法为主线,系统讲解语义实体识别(SER)与关系抽取(RE)两个关键信息抽取任务在视觉富文档(如票据、登记表、合同)上的数据准备、模型训练、评估、导出与 Python 推理部署全流程,并深入剖析其配置文件结构与源码实现原理。读完本文,你将掌握如何使用 configs/kie/layoutlm_series 下的配置,在 XFUND 等数据集上独立完成 LayoutXLM 的 SER/RE 模型训练与推理部署。
1. 算法概述与复现效果
LayoutXLM 是面向多语言视觉富文档理解(Visually-rich Document Understanding)的多模态预训练模型,在 LayoutLM 与 LayoutLMv2 的基础上进一步支持多语言场景。其核心思想是将文本(text)、布局(layout/bbox)与视觉(image)三种模态信息联合建模,从而在 OCR 识别出的文本行基础上,进一步完成语义级的信息抽取。
- 论文:LayoutXLM: Multimodal Pre-training for Multilingual Visually-rich Document Understanding(Yiheng Xu 等,2021)
- 相关前作:LayoutLM: Pre-training of Text and Layout for Document Image Understanding(2019)、LayoutLMv2: Multi-modal Pre-training for Visually-Rich Document Understanding(2020)
PaddleOCR 在 XFUND_zh 数据集上复现了 LayoutXLM-base 在 SER 与 RE 两个任务上的效果(hmean 为综合衡量精确率与召回率的 F1 指标):
| 模型 | 骨干网络 | 任务 | 配置文件 | hmean |
|---|---|---|---|---|
| LayoutXLM | LayoutXLM-base | SER | ser_layoutxlm_xfund_zh.yml | 90.38% |
| LayoutXLM | LayoutXLM-base | RE | re_layoutxlm_xfund_zh.yml | 74.83% |
其中:
- SER(Semantic Entity Recognition,语义实体识别):为每个文本行(token)分配一个语义类别标签,例如
QUESTION(问题/标签)、ANSWER(答案/值)、HEADER(页眉)、OTHER(其他)。 - RE(Relation Extraction,关系抽取):在 SER 基础上进一步判断实体之间的关联关系,例如"证件类型 ↔ 证件号码"、"标签 ↔ 值"之间的链接关系。RE 任务通常以 SER 输出作为前置输入。
2. 模型结构与多模态输入设计
2.1 架构配置
在 ser_layoutxlm_xfund_zh.yml 中,LayoutXLM 的模型结构通过 Architecture 字段声明:
Architecture:
model_type: kie
algorithm: &algorithm "LayoutXLM"
Transform:
Backbone:
name: LayoutXLMForSer # SER 任务使用 LayoutXLMForSer,RE 任务使用 LayoutXLMForRe
pretrained: True # 训练时自动加载 PaddleNLP 中的 LayoutXLM 预训练权重
checkpoints: # 指定断点权重后其优先级高于 pretrained
num_classes: &num_classes 7 # SER 分类类别数,需与字典文件及 BIO 标注对应
RE 配置文件 re_layoutxlm_xfund_zh.yml 中 Backbone.name 为 LayoutXLMForRe,且不显式声明 num_classes(关系类别由标注数据中的 linking 信息动态确定)。
注意:LayoutXLM 系列模型加载与保存的逻辑与 PaddleNLP 保持一致(预训练权重来自 PaddleNLP),因此不需要设置
Global.pretrained_model或Global.checkpoints,权重路径统一通过Architecture.Backbone.checkpoints指定。
2.2 多模态输入张量
从 ppocr/modeling/architectures/init.py 中 LayoutXLM 分支的静态图输入规格可以看到模型接受的输入:
| 输入张量 | 形状 | dtype | 含义 |
|---|---|---|---|
input_ids |
[None, 512] | int64 | 文本 token 的 ID 序列(最大序列长度 512) |
bbox |
[None, 512, 4] | int64 | 每个 token 的布局坐标(归一化后的边界框) |
attention_mask |
[None, 512] | int64 | 注意力掩码 |
token_type_ids |
[None, 512] | int64 | 片段类型 ID |
image |
[None, 3, 224, 224] | float32 | 文档图像的视觉特征(缩放至 224×224) |
label |
[None, 512] | int64 | 序列标注标签(SER 训练时使用) |
可见 LayoutXLM 同时融合了文本模态(input_ids、token_type_ids)、布局模态(bbox)与视觉模态(image),这正是其能超越纯文本模型处理富文档的关键。上述输入由 ppocr/data/imaug/label_ops.py 中的 VQATokenLabelEncode 等算子从"OCR 结果 + 标注 JSON"构造生成。
3. 环境准备
开始前请按以下步骤准备运行环境:
- 参考《运行环境准备》配置 PaddleOCR 运行环境(PaddlePaddle 框架及依赖)。
- 参考《项目克隆》克隆项目代码,并确保工作目录为仓库根目录。
- 如需训练或推理,还需下载 XFUND 数据集(见下文数据准备)。
4. 数据准备
4.1 数据集下载与转换
PaddleOCR 提供了已处理好的 XFUND_zh 数据集,可直接下载使用:
mkdir train_data
cd train_data
wget https://paddleocr.bj.bcebos.com/ppstructure/dataset/XFUND.tar && tar -xf XFUND.tar
cd ..
下载后得到 train_data/XFUND/ 目录,其中包含 zh_train/(训练集,含 image/ 图片目录与 train.json 标注文件)、zh_val/(验证集,含 image/ 与 val.json)、以及类别字典文件 class_list_xfun.txt。
如果你希望使用 XFUND 或 FUNSD 的原始数据,可以借助仓库中的转换脚本生成 PaddleOCR 训练格式:XFUND 转换脚本、FUNSD 转换脚本。更多公开数据集介绍参考关键信息抽取数据集说明。
4.2 标注数据格式
训练标注采用 JSON 列表格式,每行一个样本,图片路径与标注之间用 \t 分隔:
" 图像文件名 图像标注信息 "
zh_train_0.jpg [{"transcription": "汇丰晋信", "label": "other", "points": [[104, 114], [530, 114], [530, 175], [104, 175]], "id": 1, "linking": []}, {"transcription": "受理时间:", "label": "question", "points": [[126, 267], [266, 267], [266, 305], [126, 305]], "id": 7, "linking": [[7, 13]]}, {"transcription": "2020.6.15", "label": "answer", "points": [[321, 239], [537, 239], [537, 285], [321, 285]], "id": 13, "linking": [[7, 13]]}]
每个字段含义如下:
| 字段 | 含义 |
|---|---|
transcription |
该文本行的文字内容 |
label |
该文本行所属的语义类别(SER 标签) |
points |
文本行的四点(左上、右上、右下、左下)坐标 |
id |
文本行唯一 ID,用于 RE 任务 |
linking |
文本行之间的连接关系(实体对),用于 RE 任务 |
最终数据集目录结构如下:
|-train_data
|-XFUND
|- train.json
|- zh_train
|- image
|- zh_train_0.png
|- zh_train_1.jpg
| ...
|- val.json
|- zh_val
|- image
|- zh_val_0.png
|- zh_val_1.jpg
| ...
|- class_list_xfun.txt
4.3 类别字典文件
字典文件(如 class_list_xfun.txt)中每行一个类别名称。XFUND_zh 数据共 4 个类别:
OTHER
QUESTION
ANSWER
HEADER
注意事项:
- 标注中的
label不区分大小写,HEADER与header会被解析为相同类别 id,因此不能使用仅大小写不同的字符串表示不同类别。 - 建议将
other类别放在字典第一行,解析时其类别 id 为 0,可视化阶段不会对该类进行绘制。
4.4 SER 类别数与 BIO 标注的关系
SER 采用 BIO 序列标注范式,num_classes 需要与字典严格对应:
- 若字典包含 n 个字段(含
other),类别数为2n - 1; - 若字典包含 n 个字段(不含
other),类别数为2n + 1。
例如 XFUND_zh 字典含 4 个类别,配置中 num_classes: 7(对应 OTHER、B-QUESTION、I-QUESTION、B-ANSWER、I-ANSWER、B-HEADER、I-HEADER)。若设置错误,训练时会报 IndexError: (OutOfRange) label value should less than the shape of axis dimension。
5. 模型训练
PaddleOCR 对关键信息抽取代码进行了模块化,训练不同模型只需更换配置文件。完整训练流程见关键信息抽取教程。
5.1 启动训练
# SER 单卡训练
python3 tools/train.py -c configs/kie/layoutlm_series/ser_layoutxlm_xfund_zh.yml
# SER 多卡训练,通过 --gpus 指定卡号
python3 -m paddle.distributed.launch --gpus '0,1,2,3' tools/train.py -c configs/kie/layoutlm_series/ser_layoutxlm_xfund_zh.yml
# RE 任务单卡训练
python3 tools/train.py -c configs/kie/layoutlm_series/re_layoutxlm_xfund_zh.yml
要点:
- CPU 环境下请将配置文件中
Global.use_gpu改为false; - 训练时默认自动下载 LayoutXLM 预训练模型,无需手动准备;
- 训练日志自动保存到
Global.save_model_dir下的train.log中。
5.2 SER 训练配置逐项解析
以 ser_layoutxlm_xfund_zh.yml 为例:
Global:
use_gpu: True
epoch_num: &epoch_num 200 # 总训练轮数(YAML 锚点,供学习率调度引用)
log_smooth_window: 10
print_batch_step: 10
save_model_dir: ./output/ser_layoutxlm_xfund_zh
save_epoch_step: 2000
eval_batch_step: [0, 19] # 从第 0 个 iter 开始,每 19 个 iter 评估一次
cal_metric_during_train: False
seed: 2022
infer_img: ppstructure/docs/kie/input/zh_val_42.jpg # 预测用示例图片
save_res_path: ./output/ser_layoutxlm_xfund_zh/res
Loss:
name: VQASerTokenLayoutLMLoss # 基于 token 序列的交叉熵损失
num_classes: *num_classes
key: "backbone_out" # 从模型输出 dict 中取 backbone_out 计算损失
Optimizer:
name: AdamW
beta1: 0.9
beta2: 0.999
lr:
name: Linear
learning_rate: 0.00005 # 峰值学习率 5e-5
epochs: *epoch_num
warmup_epoch: 2 # 2 个 epoch 的线性 warmup
regularizer:
name: L2
factor: 0.00000
PostProcess:
name: VQASerTokenLayoutLMPostProcess
class_path: &class_path train_data/XFUND/class_list_xfun.txt
Metric:
name: VQASerTokenMetric
main_indicator: hmean # 以 hmean 作为选优指标
VQASerTokenLayoutLMLoss 的实现见 ppocr/losses/vqa_token_layoutlm_loss.py:它使用 CrossEntropyLoss,并通过 attention_mask 过滤掉 padding 位置的 token,仅对有效 token 计算损失。
训练数据预处理流水线(Train.dataset.transforms):
| 算子 | 作用 |
|---|---|
DecodeImage |
以 RGB 三通道读取图像 |
VQATokenLabelEncode |
将 OCR 文本行与类别标签编码为 input_ids/bbox/labels 等张量,contains_re: False 表示不包含关系标注 |
VQATokenPad |
将序列 padding 到 max_seq_len: 512,并生成 attention_mask |
VQASerTokenChunk |
对超长序列按 512 切分 |
Resize |
图像缩放至 [224, 224] |
NormalizeImage |
按 ImageNet 均值/方差归一化 |
ToCHWImage |
转为 CHW 通道顺序 |
KeepKeys |
仅保留模型所需字段,顺序为 ['input_ids', 'bbox', 'attention_mask', 'token_type_ids', 'image', 'labels'] |
5.3 RE 训练配置差异
RE 配置 re_layoutxlm_xfund_zh.yml 与 SER 的差异点:
Global:
epoch_num: &epoch_num 130
Loss:
name: LossFromOutput
key: loss
reduction: mean
Optimizer:
name: AdamW
clip_norm: 10 # 梯度裁剪
lr:
learning_rate: 0.00005
warmup_epoch: 10
PostProcess:
name: VQAReTokenLayoutLMPostProcess
Metric:
name: VQAReTokenMetric
main_indicator: hmean
Train:
dataset:
transforms:
- VQATokenLabelEncode: # contains_re: True,加载实体与关系标注
- VQATokenPad:
- VQAReTokenRelation: # 构造实体间关系矩阵
- VQAReTokenChunk:
- TensorizeEntitiesRelations: # 将实体与关系张量化
...
loader:
batch_size_per_card: 2 # RE 任务显存占用更大,batch 更小
num_workers: 8
5.4 训练日志解读
训练时会交替进行训练与评估,eval_batch_step: [0, 19] 表示每 19 个 iter 评估一次,并自动将 hmean 最优的模型保存为 output/ser_layoutxlm_xfund_zh/best_accuracy/:
[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 当前轮次、lr 学习率、loss 损失值、avg_reader_cost 数据读取耗时、avg_batch_cost 单 batch 总耗时、avg_samples 单 batch 样本数、ips 每秒处理样本数。若验证集很大导致评估耗时,可调大 eval_batch_step 的间隔或训练完成后再评估。
5.5 训练自定义数据集
将 ser_layoutxlm_xfund_zh.yml 中的以下字段替换为自定义路径:
Architecture:
Backbone:
num_classes: &num_classes 7 # 根据字典类别数调整
PostProcess:
class_path: &class_path train_data/XFUND/class_list_xfun.txt # 改为你的字典路径
Train:
dataset:
data_dir: train_data/XFUND/zh_train/image # 训练图片目录
label_file_list:
- train_data/XFUND/zh_train/train.json # 训练标注
loader:
batch_size_per_card: 8
Eval:
dataset:
data_dir: train_data/XFUND/zh_val/image # 验证图片目录
label_file_list:
- train_data/XFUND/zh_val/val.json # 验证标注
注意:预测/评估时的配置文件务必与训练一致。
5.6 断点训练
训练中断后可通过 Architecture.Backbone.checkpoints 加载权重恢复训练:
python3 tools/train.py -c configs/kie/layoutlm_series/ser_layoutxlm_xfund_zh.yml -o Architecture.Backbone.checkpoints=./output/ser_layoutxlm_xfund_zh/best_accuracy
checkpoints 的优先级高于 pretrained:微调、恢复训练、评估时用 checkpoints 指定路径;使用默认预训练模型训练时,保持 pretrained: True 且 checkpoints 为空。
5.7 其他训练环境
- Windows:仅支持单卡训练与预测,指定 GPU 用
set CUDA_VISIBLE_DEVICES=0;DataLoader 仅支持单进程,需将num_workers设为 0。 - macOS:不支持 GPU,需设置
use_gpu: False,其余命令与 Linux 相同。 - Linux DCU:需设置环境变量
export HIP_VISIBLE_DEVICES=0,1,2,3。 - 多机多卡:
python3 -m paddle.distributed.launch --ips="xx.xx.xx.xx,xx.xx.xx.xx" --gpus '0,1,2,3' tools/train.py -c ...,各机器分别启动,且需能相互 ping 通。
6. 模型评估
评估时通过 -o 指定待评估权重(配置文件需与训练一致):
python3 tools/eval.py -c configs/kie/layoutlm_series/ser_layoutxlm_xfund_zh.yml -o Architecture.Backbone.checkpoints=./output/ser_layoutxlm_xfund_zh/best_accuracy
输出示例:
[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
7. 模型导出为推理模型
训练保存的是 checkpoints 模型(仅含参数,用于恢复训练);部署前需通过 tools/export_model.py 导出为 inference 模型(paddle.jit.save 保存的固化模型,含结构与参数,便于加速推理与系统集成)。
7.1 SER 模型导出
wget https://paddleocr.bj.bcebos.com/pplayout/ser_LayoutXLM_xfun_zh.tar
tar -xf ser_LayoutXLM_xfun_zh.tar
python3 tools/export_model.py -c configs/kie/layoutlm_series/ser_layoutxlm_xfund_zh.yml -o Architecture.Backbone.checkpoints=./ser_LayoutXLM_xfun_zh Global.save_inference_dir=./inference/ser_layoutxlm_infer
7.2 RE 模型导出
wget https://paddleocr.bj.bcebos.com/pplayout/re_LayoutXLM_xfun_zh.tar
tar -xf re_LayoutXLM_xfun_zh.tar
python3 tools/export_model.py -c configs/kie/layoutlm_series/re_layoutxlm_xfund_zh.yml -o Architecture.Backbone.checkpoints=./re_LayoutXLM_xfun_zh Global.save_inference_dir=./inference/re_layoutxlm_infer
导出成功后目录下有三个文件:
inference/ser_layoutxlm_infer/
├── inference.pdiparams # inference 模型参数文件
├── inference.pdiparams.info # 参数信息,可忽略
└── inference.pdmodel # 模型结构文件
8. 推理部署
8.1 SER 任务 Python 推理
LayoutXLM 的 SER 推理入口为 ppstructure/kie/predict_kie_token_ser.py:
cd ppstructure
python3 kie/predict_kie_token_ser.py \
--kie_algorithm=LayoutXLM \
--ser_model_dir=../inference/ser_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
参数说明:
| 参数 | 说明 |
|---|---|
--kie_algorithm |
信息抽取算法名,LayoutXLM 系列统一为 LayoutXLM |
--ser_model_dir |
SER inference 模型目录 |
--image_dir |
待识别图片路径或目录 |
--ser_dict_path |
类别字典文件(如 class_list_xfun.txt) |
--vis_font_path |
可视化绘制使用的字体(仓库自带 doc/fonts/simfang.ttf) |
从 predict_kie_token_ser.py 的源码可以看到,推理时 SerPredictor 会自动创建 PaddleOCR 引擎完成检测与识别(默认加载 PP-OCRv3 检测识别模型),随后将 OCR 文本行结果送入 VQATokenLabelEncode 构造多模态输入;后处理使用 VQASerTokenLayoutLMPostProcess(实现见 ppocr/postprocess/vqa_token_ser_layoutlm_postprocess.py),它对每个 token 取 argmax 得到类别 id,再按 segment_offset_id 将 token 映射回文本行,并以**投票(bincount 众数)**的方式决定每个文本行的最终类别。
SER 可视化结果默认保存到 ./output 文件夹,效果示例如下(信息来源:XFUND_zh 验证集 zh_val_42 个人登记表,彩色框标注 QUESTION/ANSWER/HEADER 等实体):
8.2 RE 任务 Python 推理
RE 推理需要先获得 SER 结果,因此需同时指定 SER 与 RE 两个模型目录,入口为 ppstructure/kie/predict_kie_token_ser_re.py:
cd ppstructure
python3 kie/predict_kie_token_ser_re.py \
--kie_algorithm=LayoutXLM \
--re_model_dir=../inference/re_layoutxlm_infer \
--ser_model_dir=../inference/ser_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
参数说明:
| 参数 | 说明 |
|---|---|
--re_model_dir |
RE inference 模型目录 |
--ser_model_dir |
SER inference 模型目录(RE 的输入依赖) |
| 其余参数 | 与 SER 推理相同 |
从 predict_kie_token_ser_re.py 源码可见,SerRePredictor 内部先调用 SerPredictor 得到 SER 结果,再通过 make_input 将 SER 输出与实体索引字典构造为 RE 输入,运行 RE 模型后由 VQAReTokenLayoutLMPostProcess 输出实体关系对。RE 可视化结果同样默认保存到 ./output 文件夹,效果示例如下(连线表示实体间的语义关系,如"证件类型 ↔ 证件号码"、"标签 ↔ 值"):
8.3 使用已标注 OCR 结果进行推理
若希望跳过 OCR 引擎、直接使用预先获取的 OCR 结果进行信息抽取,可指定 Global.infer_img 为标注文件(内含图片路径与 OCR 信息),并设置 Global.infer_mode=False:
python3 tools/infer_kie_token_ser.py -c configs/kie/layoutlm_series/ser_layoutxlm_xfund_zh.yml \
-o Architecture.Backbone.checkpoints=./output/ser_layoutxlm_xfund_zh/best_accuracy \
Global.infer_img=./train_data/XFUND/zh_val/val.json Global.infer_mode=False
RE 任务同时加载 SER 与 RE 配置:
python3 tools/infer_kie_token_ser_re.py \
-c configs/kie/layoutlm_series/re_layoutxlm_xfund_zh.yml \
-o Architecture.Backbone.checkpoints=./output/re_layoutxlm_xfund_zh/best_accuracy \
Global.infer_img=./train_data/XFUND/zh_val/image/ \
-c_ser configs/kie/layoutlm_series/ser_layoutxlm_xfund_zh.yml \
-o_ser Architecture.Backbone.checkpoints=./output/ser_layoutxlm_xfund_zh/best_accuracy
其中 -c_ser 指定 SER 配置文件,-o_ser 指定 SER 权重的修改项。通常使用标注 OCR 结果时 RE 预测会更准确,因为检测框信息更完整。
8.4 其他部署方式
目前 LayoutXLM 的 C++ 推理部署、Serving 服务化部署及其他更多推理部署方式暂不支持,Python 推理是当前主要部署路径。
9. FAQ
Q1:训练模型转 inference 模型后预测效果不一致?
A:该问题多由 trained model 与 inference model 预测时的预处理、后处理参数不一致导致。请对比训练使用的配置文件中的预处理(Train.dataset.transforms)、后处理(PostProcess)与推理脚本 predict_kie_token_ser.py 中硬编码的预处理/后处理参数(如 max_seq_len: 512、Resize [224, 224]、归一化均值方差)是否存在差异,保持一致即可复现训练时效果。
10. 引用
@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}
}

