PaddleOCR 中 UniMERNet 通用数学公式识别算法：训练、评估与源码解析

PaddleOCR 中 UniMERNet 通用数学公式识别算法训练、评估与源码解析【免费下载链接】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 仓库中 UniMERNet 通用数学公式识别算法的官方文档为核心系统讲解该算法在 PaddleOCR 中的完整落地流程从算法精度表现、环境配置、数据集准备到训练 / 评估 / 预测的完整命令行操作并结合 UniMERNet.yaml 配置文件与 解码器源码、数据增强实现 等仓库源码剖析其模型结构与数据管线原理。读完本文你将能够独立完成 UniMERNet 模型在 PaddleOCR 中的训练、评测与推理部署。1. 算法简介UniMERNet 是一个通用的数学公式识别OCR for Mathematical Expressions算法其原始项目由 OpenDataLab 开源。PaddleOCR 将其完整移植并接入自身模块化的训练 / 评估 / 预测体系中使用UniMERNet通用公式识别数据集进行训练模型配置统一收敛在 UniMERNet.yaml 中。在对应测试集上的精度如下模型骨干网络配置文件SPE-BLEU↑SPE-EditDis↓CPE-BLEU↑CPE-EditDis↓SCE-BLEU↑SCE-EditDis↓HWE-BLEU↑HWE-EditDis↓下载链接UniMERNetDonut SwinUniMERNet.yaml0.91870.05840.92520.05960.60680.22970.91570.0546训练模型其中SPE 表示简单公式Simple Printed EquationsCPE 表示复杂公式Complex Printed EquationsSCE 表示扫描捕捉公式Scanned/Captured EquationsHWE 表示手写公式Hand-Written Equations。可以看到模型在打印体公式SPE、CPE上表现最佳BLEU 均超过 0.91、编辑距离Edit DistanceEditDis低于 0.06在扫描捕捉公式SCE上由于图像噪声与形变精度相对较低在手写公式HWE上同样保持了较高的识别水平。从源码结构看该算法在 PaddleOCR 中的定位是图像 → LaTeX 序列的序列到序列生成任务属于model_type: rec识别分支与 PP-FormulaNet 等公式识别模型并列可服务于论文公式抽取、文档结构化等场景。2. 环境配置训练与推理前请先参考 《运行环境准备》 配置 PaddleOCR 运行环境并参考 《项目克隆》 克隆项目代码。此外UniMERNet 的数据增强与图像预处理依赖额外的系统库与 Python 包需要额外安装sudo apt-get update sudo apt-get install libmagickwand-dev pip install -r docs/version2.x/algorithm/formula_recognition/requirements.txt其中libmagickwand-dev是 ImageMagick 的 Wand 绑定所需的系统依赖docs/version2.x/algorithm/formula_recognition/requirements.txt中固定了以下 Python 依赖版本tokenizers0.19.1用于 LaTeX tokenizer 词表加载与文本 token 化imagesize用于读取图像尺寸信息ftfy用于修复 Unicode 文本编码问题Wand用于实现雪花Snow等需要动感模糊的高阶数据增强见 unimernet_aug.py 中Snow变换的实现。注意由于训练数据增强中的Snow变换在运行时通过wand.image处理图像若未正确安装libmagickwand-dev训练时会在该变换处报错。3. 模型训练、评估、预测3.1 准备数据集UniMERNet 训练采用 UniMERNet 通用公式识别数据集UniMER-1M与好未来手写公式数据集 HME100K 混合训练测试则使用 UniMER-Test 的 SPE / CPE / SCE / HWE 四个子集分别评测。数据集下载地址UniMER-1M.zip 与 UniMER-Test.zip从 OpenDataLab 的 UniMER-Dataset 页面下载HME100K从好未来平台下载。下载完成后使用如下命令创建数据集目录并对数据进行转换# 创建 UniMERNet 数据集目录 mkdir -p train_data/UniMERNet # 解压 UniMERNet 、 UniMER-Test.zip 和 HME100K.zip unzip -d train_data/UniMERNet path/UniMER-1M.zip unzip -d train_data/UniMERNet path/UniMER-Test.zip unzip -d train_data/UniMERNet/HME100K train_data/UniMERNet/HME100K/train.zip unzip -d train_data/UniMERNet/HME100K train_data/UniMERNet/HME100K/test.zip # 训练集转换 python ppocr/utils/formula_utils/unimernet_data_convert.py \ --image_dirtrain_data/UniMERNet \ --datatypeunimernet_train \ --unimernet_txt_pathtrain_data/UniMERNet/UniMER-1M/train.txt \ --hme100k_txt_pathtrain_data/UniMERNet/HME100K/train_labels.txt \ --output_pathtrain_data/UniMERNet/train_unimernet_1M.txt # 测试集转换 # SPE python ppocr/utils/formula_utils/unimernet_data_convert.py \ --image_dirtrain_data/UniMERNet/UniMER-Test/spe \ --datatypeunimernet_test \ --unimernet_txt_pathtrain_data/UniMERNet/UniMER-Test/spe.txt \ --output_pathtrain_data/UniMERNet/test_unimernet_spe.txt # CPE python ppocr/utils/formula_utils/unimernet_data_convert.py \ --image_dirtrain_data/UniMERNet/UniMER-Test/cpe \ --datatypeunimernet_test \ --unimernet_txt_pathtrain_data/UniMERNet/UniMER-Test/cpe.txt \ --output_pathtrain_data/UniMERNet/test_unimernet_cpe.txt # SCE python ppocr/utils/formula_utils/unimernet_data_convert.py \ --image_dirtrain_data/UniMERNet/UniMER-Test/sce \ --datatypeunimernet_test \ --unimernet_txt_pathtrain_data/UniMERNet/UniMER-Test/sce.txt \ --output_pathtrain_data/UniMERNet/test_unimernet_sce.txt # HWE python ppocr/utils/formula_utils/unimernet_data_convert.py \ --image_dirtrain_data/UniMERNet/UniMER-Test/hwe \ --datatypeunimernet_test \ --unimernet_txt_pathtrain_data/UniMERNet/UniMER-Test/hwe.txt \ --output_pathtrain_data/UniMERNet/test_unimernet_hwe.txt从转换脚本 unimernet_data_convert.py 的源码可以确认转换逻辑datatypeunimernet_train时调用latexocr2paddleocr_trainUniMER-1M 的标注按行读取图像按行号格式化为{0:07d}.png从UniMER-1M/images子目录下查找HME100K 的标注为img_name\tmath_gt格式从HME100K/train_images子目录下查找。两类数据统一转换为 PaddleOCR 标准的图像相对路径\t公式LaTeX标注两列 TSV 格式datatypeunimernet_test时调用unimernet2paddleocr_test测试集图像按{0:07d}.png命名与spe.txt/cpe.txt/sce.txt/hwe.txt中的标注按行一一对应。脚本仅保留图像实际存在且标注能正确对齐的样本生成的文件即可直接作为 UniMERNet.yaml 中Train.dataset.label_file_list与Eval.dataset.label_file_list使用。3.2 下载预训练模型UniMERNet 的解码器基于 mBART 结构官方推荐从 Texify 预训练权重初始化而非从零开始训练下载命令如下# 下载 Texify 预训练模型 wget -P ./pretrain_models/ https://paddleocr.bj.bcebos.com/pretrained/texify.pdparams3.3 模型训练训练整体流程请参考 文本识别训练教程。PaddleOCR 对代码进行了模块化训练 UniMERNet 识别模型时需要更换配置文件为 UniMERNet 的 配置文件。启动训练具体地在完成数据准备后便可以启动训练训练命令如下# 单卡训练 (默认训练方式) python3 tools/train.py -c configs/rec/UniMERNet.yaml \ -o Global.pretrained_model./pretrain_models/texify.pdparams # 多卡训练通过--gpus参数指定卡号 python3 -m paddle.distributed.launch --gpus 0,1,2,3 --ips127.0.0.1 tools/train.py -c configs/rec/UniMERNet.yaml \ -o Global.pretrained_model./pretrain_models/texify.pdparams注意默认每训练 1 个 epoch37880 次 iteration进行 1 次评估若您更改训练的 batch_size或更换数据集请在训练时作出如下修改python3 -m paddle.distributed.launch --gpus 0,1,2,3 --ips127.0.0.1 tools/train.py -c configs/rec/UniMERNet.yaml \ -o Global.eval_batch_step[0,{length_of_dataset//batch_size//4}] \ Global.pretrained_model./pretrain_models/texify.pdparamsGlobal.eval_batch_step[0, N]表示从第 0 个 iteration 开始每隔 N 个 iteration 评估一次其中{length_of_dataset//batch_size//4}为一个占位表达式含义为数据集长度 ÷ batch_size ÷ 4即每个 epoch 内评估 4 次实际使用时应替换为计算后的具体数值。3.4 评估可下载已训练完成的模型文件使用如下命令进行评估# 注意将pretrained_model的路径设置为本地路径。若使用自行训练保存的模型请注意修改路径和文件名为{path/to/weights}/{model_name}。 # SPE 测试集评估 python3 tools/eval.py -c configs/rec/UniMERNet.yaml -o \ Eval.dataset.data_dir./train_data/UniMERNet/UniMER-Test/spe \ Eval.dataset.label_file_list[./train_data/UniMERNet/test_unimernet_spe.txt] \ Global.pretrained_model./rec_unimernet_train/best_accuracy.pdparams # CPE 测试集评估 python3 tools/eval.py -c configs/rec/UniMERNet.yaml -o \ Eval.dataset.data_dir./train_data/UniMERNet/UniMER-Test/cpe \ Eval.dataset.label_file_list[./train_data/UniMERNet/test_unimernet_cpe.txt] \ Global.pretrained_model./rec_unimernet_train/best_accuracy.pdparams # SCE 测试集评估 python3 tools/eval.py -c configs/rec/UniMERNet.yaml -o \ Eval.dataset.data_dir./train_data/UniMERNet/UniMER-Test/sce \ Eval.dataset.label_file_list[./train_data/UniMERNet/test_unimernet_sce.txt] \ Global.pretrained_model./rec_unimernet_train/best_accuracy.pdparams # HWE 测试集评估 python3 tools/eval.py -c configs/rec/UniMERNet.yaml -o \ Eval.dataset.data_dir./train_data/UniMERNet/UniMER-Test/hwe \ Eval.dataset.label_file_list[./train_data/UniMERNet/test_unimernet_hwe.txt] \ Global.pretrained_model./rec_unimernet_train/best_accuracy.pdparams评估时通过-o覆盖配置文件中的Eval.dataset.data_dir与Eval.dataset.label_file_list即可在不修改 YAML 的情况下轮换四个测试子集。评估指标由配置中的Metric.name: LaTeXOCRMetric决定主指标为exp_rate见下文源码解析。3.5 预测使用如下命令进行单张图片预测# 注意将pretrained_model的路径设置为本地路径。 python3 tools/infer_rec.py -c configs/rec/UniMERNet.yaml \ -o Global.infer_img./docs/datasets/images/pme_demo/0000099.png \ Global.pretrained_model./rec_unimernet_train/best_accuracy.pdparams # 预测文件夹下所有图像时可修改infer_img为文件夹如 Global.infer_img./doc/datasets/pme_demo/。即把Global.infer_img指向单张图片或一个图片文件夹模型会对每张公式图片输出对应的 LaTeX 序列结果保存在Global.save_res_path指定的文件中默认./output/rec/predicts_unimernet.txt。4. 配置文件核心参数解读UniMERNet.yaml 是 UniMERNet 在 PaddleOCR 中的完整训练配置各模块参数如下Global全局model_name: UniMERNet模型名用于静态图inference model导出与推理epoch_num: 40总训练轮数save_model_dir: ./output/rec/unimernet/模型保存目录save_epoch_step: 5每 5 个 epoch 保存一次 checkpointeval_batch_step: [0, 37880]评估间隔37880 即 1M 训练数据在默认 batch_size7 下的 iteration 数rec_char_dict_path: ppocr/utils/dict/unimernet_tokenizerLaTeX tokenizer 词表路径注意此处是目录/前缀形式的 tokenizer 文件由tokenizers库加载而非普通 txt 词典input_size: [192, 672]模型输入尺寸高 192宽 672max_seq_len: 1024标签序列最大长度d2s_train_image_shape: [1,192,672]动态图转静态图动态转静态时的输入 shape。Optimizer优化器name: AdamWbeta1: 0.9beta2: 0.999weight_decay: 0.05学习率采用LinearWarmupCosine调度初始learning_rate: 1e-4start_lr: 1e-5min_lr: 1e-8warmup_steps: 5000。Architecture网络结构model_type: recalgorithm: UniMERNetin_channels: 3Backbone.name: DonutSwinModelSwin Transformer 视觉编码器hidden_size: 1024、num_layers: 4、num_heads: [4, 8, 16, 32]、add_pooling_layer: True、use_mask_token: FalseHead.name: UniMERNetHead自回归解码头max_new_tokens: 1536单次生成最大 token 数、decoder_start_token_id: 0、temperature: 0.2、do_sample: False贪心解码、top_p: 0.95、encoder_hidden_size: 1024、is_export: False、length_aware: True长度感知生成。Loss / PostProcess / MetricLoss.name: UniMERNetLoss交叉熵式序列损失实现在 rec_unimernet_loss.pyPostProcess.name: UniMERNetDecode将解码 logits 转为 LaTeX 文本实现在 rec_postprocess.py同时指定rec_char_dict_pathMetric.name: LaTeXOCRMetricmain_indicator: exp_ratecal_bleu_score: True即同时统计公式级正确率exp_rate与 BLEU 分数。Train / Eval 数据集与数据管线训练集data_dir: ./train_data/UniMERNet/label_file_list指向train_unimernet_1M.txt变换链UniMERNetImgDecode输入尺寸 [192,672]→UniMERNetTrainTransform→UniMERNetImageFormat→UniMERNetLabelEncode词表 max_seq_len→KeepKeys保留[image, label, attention_mask]训练 loaderbatch_size_per_card: 7collate_fn: UniMERNetCollator评估集默认指向 CPE 子集UniMER-Test/cpe变换链为UniMERNetImgDecode→UniMERNetTestTransform→UniMERNetImageFormat→UniMERNetLabelEncode→KeepKeys评估时batch_size_per_card: 30。5. 源码级实现解析5.1 编码器Donut Swin 骨干骨干网络实现在 rec_donut_swin.pyDonutSwinModel。它将公式图像编码为视觉 token 序列其配置hidden_size1024、4 层、多头 [4,8,16,32]与单测用例tests/ppocr/test_formula_model.py中的test_unimernet_backbone完全一致输入[1, 1, 192, 672]的灰度图像输出特征形状为[1, 126, 1024]即 126 个 1024 维的视觉 token。5.2 解码器UniMERNetHeadmBART 序列生成解码头实现在 rec_unimernet_head.py共 2674 行。从源码结构看它复刻了 HuggingFace mBART 的解码器体系MBartConfig含bos_token_id0、eos_token_id2、pad_token_id1、forced_eos_token_id2等、MBartAttention因果自注意力 编码器交叉注意力、MBartDecoderLayer、MBartDecoder与MBartForCausalLM等模块被逐一以 Paddle 实现。训练时以公式图像特征为 encoder hidden states以 LaTeX token 序列为 decoder input通过自回归方式逐步生成公式的 token 序列推理时依据do_sampleFalse执行贪心解码并用length_aware机制辅助控制生成长度。单测test_unimernet_head验证了UniMERNetHead的输入输出给定[1, 126, 1024]的编码特征在max_new_tokens5时输出[1, 6]的 token 序列。5.3 数据管线与增强策略UniMERNet 的专属数据变换集中在 unimernet_aug.py包含UniMERNetImgDecode读取图像后先做crop_margin按灰度阈值裁掉空白边距并限制宽高比不超过 200 以避免极端形变再按最短边缩放并thumbnail到 192×672最后在空白区域 padding 到固定尺寸支持random_padding、random_resize、random_crop三个随机开关UniMERNetTrainTransform训练增强采用 albumentations 组合包括Bitmap二值化概率 0.05、Fog/Frost/Snow/Rain/Shadow恶劣天气扰动OneOfp0.2、Erosion/Dilation形态学腐蚀膨胀p0.2、ShiftScaleRotate微小平移缩放旋转rotate_limit1、GridDistortion网格畸变p0.5、RGBShift、GaussNoise、RandomBrightnessContrast、ImageCompression最后ToGray转灰度并使用固定的归一化均值/方差(0.7931, 0.1738)UniMERNetTestTransform评估时仅做ToGray Normalize保证评测稳定性UniMERNetImageFormat将图像 pad 到 32 的整数倍适配 Swin 下采样取单通道并转成[C, H, W]布局UniMERNetCollatorcollate_fn.py对一个 batch 内的图像与标签分别做动态 padding 到 batch 内最大尺寸同时生成label_masks供损失函数屏蔽 padding 位。5.4 指标与评测逻辑评测指标LaTeXOCRMetric实现在 rec_metric.py。从源码可见主指标exp_rate逐条比对预测序列与 GT 序列是否完全一致统计公式级正确率当cal_bleu_scoreTrue时额外计算 BLEU 分数并输出exp_rate1 / 2 / 3的容错统计允许预测序列与 GT 相差 1/2/3 个 token 时仍记为正确。这解释了官方精度表中同时报告 BLEU 与 EditDis编辑距离两类指标的原因——它们分别衡量生成序列的语义相似度与逐 token 差异。6. FAQUniMERNet 数据集来自于 UniMERNet 源 repoOpenDataLab 的 UniMER-DatasetHME100K 手写公式数据集来自好未来平台。两者通过 unimernet_data_convert.py 统一转换为 PaddleOCR 标准标注格式后即可直接用于训练。若训练时报 Wand / ImageMagick 相关错误请确认已按第 2 节安装libmagickwand-dev与WandPython 包。若需要将 UniMERNet 模型导出为静态图用于推理部署需在配置中设置Global.save_inference_dir与Global.pretrained_model并通过tools/export_model.py导出Head.is_export等参数会相应切换解码路径。【免费下载链接】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），仅供参考