PaddleOCR/docs/version3.x/module_usage/formula_recognition.md

comments
true

公式识别模块使用教程

一、概述

公式识别模块是OCR（光学字符识别）系统中的关键组成部分，负责将图像中的数学公式转换为可编辑的文本或计算机可识别的格式。该模块的性能直接影响到整个OCR系统的准确性和效率。公式识别模块通常会输出数学公式的 LaTeX 或 MathML 代码，这些代码将作为输入传递给文本理解模块进行后续处理。

二、支持模型列表

模型	模型下载链接	En-BLEU(%)	Zh-BLEU(%)	GPU推理耗时（ms） [常规模式 / 高性能模式]	CPU推理耗时（ms） [常规模式 / 高性能模式]	模型存储大小 (M)	介绍
UniMERNet	推理模型/训练模型	85.91	43.50	2266.96/-	-/-	1.53 G	UniMERNet是由上海AI Lab研发的一款公式识别模型。该模型采用Donut Swin作为编码器，MBartDecoder作为解码器，并通过在包含简单公式、复杂公式、扫描捕捉公式和手写公式在内的一百万数据集上进行训练，大幅提升了模型对真实场景公式的识别准确率
PP-FormulaNet-S	推理模型/训练模型	87.00	45.71	202.25/-	-/-	224 M	PP-FormulaNet 是由百度飞桨视觉团队开发的一款先进的公式识别模型，支持5万个常见LateX源码词汇的识别。PP-FormulaNet-S 版本采用了 PP-HGNetV2-B4 作为其骨干网络，通过并行掩码和模型蒸馏等技术，大幅提升了模型的推理速度，同时保持了较高的识别精度，适用于简单印刷公式、跨行简单印刷公式等场景。而 PP-FormulaNet-L 版本则基于 Vary_VIT_B 作为骨干网络，并在大规模公式数据集上进行了深入训练，在复杂公式的识别方面，相较于PP-FormulaNet-S表现出显著的提升，适用于简单印刷公式、复杂印刷公式、手写公式等场景。
PP-FormulaNet-L	推理模型/训练模型	90.36	45.78	1976.52/-	-/-	695 M
PP-FormulaNet_plus-S	推理模型/训练模型	88.71	53.32	191.69/-	-/-	248 M	PP-FormulaNet_plus 是百度飞桨视觉团队在 PP-FormulaNet 的基础上开发的增强版公式识别模型。与原版相比，PP-FormulaNet_plus 在训练中使用了更为丰富的公式数据集，包括中文学位论文、专业书籍、教材试卷以及数学期刊等多种来源。这一扩展显著提升了模型的识别能力。 其中，PP-FormulaNet_plus-M 和 PP-FormulaNet_plus-L 模型新增了对中文公式的支持，并将公式的最大预测 token 数从 1024 扩大至 2560，大幅提升了对复杂公式的识别性能。同时，PP-FormulaNet_plus-S 模型则专注于增强英文公式的识别能力。通过这些改进，PP-FormulaNet_plus 系列模型在处理复杂多样的公式识别任务时表现更加出色。
PP-FormulaNet_plus-M	推理模型/训练模型	91.45	89.76	1301.56/-	-/-	592 M
PP-FormulaNet_plus-L	推理模型/训练模型	92.22	90.64	1745.25/-	-/-	698 M
LaTeX_OCR_rec	推理模型/训练模型	74.55	39.96	1244.61/-	-/-	99 M	LaTeX-OCR是一种基于自回归大模型的公式识别算法，通过采用 Hybrid ViT 作为骨干网络，transformer作为解码器，显著提升了公式识别的准确性。

测试环境说明:

• 性能测试环境
  • 测试数据集：PaddleOCR 内部自建公式识别测试集
  • 硬件配置：
    • GPU：NVIDIA Tesla T4
    • CPU：Intel Xeon Gold 6271C @ 2.60GHz
    • 其他环境：Ubuntu 20.04 / cuDNN 8.6 / TensorRT 8.5.2.2
• 推理模式说明

模式	GPU配置	CPU配置	加速技术组合
常规模式	FP32精度 / 无TRT加速	FP32精度 / 8线程	PaddleInference
高性能模式	选择先验精度类型和加速策略的最优组合	FP32精度 / 8线程	选择先验最优后端（Paddle/OpenVINO/TRT等）

三、快速开始

❗ 在快速开始前，请先安装 PaddleOCR 的 wheel 包，详细请参考 安装教程。

使用一行命令即可快速体验：

paddleocr formula_recognition -i https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/general_formula_rec_001.png

您也可以将公式识别的模块中的模型推理集成到您的项目中。运行以下代码前，请您下载示例图片到本地。

from paddleocr import FormulaRecognition
model = FormulaRecognition(model_name="PP-FormulaNet_plus-M")
output = model.predict(input="general_formula_rec_001.png", batch_size=1)
for res in output:
    res.print()
    res.save_to_img(save_path="./output/")
    res.save_to_json(save_path="./output/res.json")

运行后，得到的结果为：

{'res': {'input_path': '/root/.paddlex/predict_input/general_formula_rec_001.png', 'page_index': None, 'rec_formula': '\\zeta_{0}(\\nu)=-\\frac{\\nu\\varrho^{-2\\nu}}{\\pi}\\int_{\\mu}^{\\infty}d\\omega\\int_{C_{+}}d z\\frac{2z^{2}}{(z^{2}+\\omega^{2})^{\\nu+1}}\\breve{\\Psi}(\\omega;z)e^{i\\epsilon z}\\quad,'}}

运行结果参数含义如下：

• input_path：表示输入待预测公式图像的路径
• page_index：如果输入是PDF文件，则表示当前是PDF的第几页，否则为 None
• rec_formula：表示公式图像的预测LaTeX源码

可视化图片如下，左侧是待预测的公式图像，右边是预测的结果渲染后的公式图像：

注：如果您需要对公式识别模块进行可视化，需要运行如下命令来对LaTeX渲染环境进行安装。目前公式识别模块可视化只支持Ubuntu环境，其他环境暂不支持。对于复杂公式，LaTeX 结果可能包含部分高级的表示，Markdown等环境中未必可以成功显示：

sudo apt-get update
sudo apt-get install texlive texlive-latex-base texlive-xetex latex-cjk-all texlive-latex-extra -y

相关方法、参数等说明如下：

• FormulaRecognition实例化公式识别模型（此处以PP-FormulaNet_plus-M为例），具体说明如下：

参数	参数说明	参数类型	默认值
model_name	模型名称	str	PP-FormulaNet_plus-M
model_dir	模型存储路径	str	None
device	用于推理的设备。 例如：cpu、gpu、npu、gpu:0、gpu:0,1。 如指定多个设备，将进行并行推理。 默认情况下，优先使用 GPU 0；若不可用则使用 CPU。	str	None
enable_hpi	是否启用高性能推理。	bool	False
use_tensorrt	是否启用 Paddle Inference 的 TensorRT 子图引擎。	bool	False
min_subgraph_size	当使用 Paddle Inference 的 TensorRT 子图引擎时，设置的最小子图大小。	int	3
precision	当使用 Paddle Inference 的 TensorRT 子图引擎时设置的计算精度。 可选项：fp32、fp16 等。	str	fp32
enable_mkldnn	是否启用MKL-DNN加速库。	bool	True
cpu_threads	在 CPU 上推理时使用的线程数量。	int	10

* 其中，`model_name` 必须指定，指定 `model_name` 后，默认使用内置的模型参数，在此基础上，指定 `model_dir` 时，使用用户自定义的模型。

• 调用公式识别模型的 predict() 方法进行推理预测，该方法会返回一个结果列表。另外，本模块还提供了 predict_iter() 方法。两者在参数接受和结果返回方面是完全一致的，区别在于 predict_iter() 返回的是一个 generator，能够逐步处理和获取预测结果，适合处理大型数据集或希望节省内存的场景。可以根据实际需求选择使用这两种方法中的任意一种。predict() 方法参数有 input 和 batch_size，具体说明如下：

参数	参数说明	参数类型	默认值
input	待预测数据，支持多种输入类型，必填。 Python Var：如 numpy.ndarray 表示的图像数据 str：如图像文件或者PDF文件的本地路径：/root/data/img.jpg；如URL链接，如图像文件或PDF文件的网络URL：示例；如本地目录，该目录下需包含待预测图像，如本地路径：/root/data/(当前不支持目录中包含PDF文件的预测，PDF文件需要指定到具体文件路径) List：列表元素需为上述类型数据，如[numpy.ndarray, numpy.ndarray]，["/root/data/img1.jpg", "/root/data/img2.jpg"]，["/root/data1", "/root/data2"]	Python Var|str|list
batch_size	批大小，可设置为任意正整数。	int	1

• 对预测结果进行处理，每个样本的预测结果均为对应的Result对象，且支持打印、保存为图片、保存为json文件的操作:

方法	方法说明	参数	参数类型	参数说明	默认值
print()	打印结果到终端	format_json	bool	是否对输出内容进行使用 JSON 缩进格式化	True
		indent	int	指定缩进级别，以美化输出的 JSON 数据，使其更具可读性，仅当 format_json 为 True 时有效	4
		ensure_ascii	bool	控制是否将非 ASCII 字符转义为 Unicode。设置为 True 时，所有非 ASCII 字符将被转义；False 则保留原始字符，仅当format_json为True时有效	False
save_to_json()	将结果保存为json格式的文件	save_path	str	保存的文件路径，当为目录时，保存文件命名与输入文件类型命名一致	无
		indent	int	指定缩进级别，以美化输出的 JSON 数据，使其更具可读性，仅当 format_json 为 True 时有效	4
		ensure_ascii	bool	控制是否将非 ASCII 字符转义为 Unicode。设置为 True 时，所有非 ASCII 字符将被转义；False 则保留原始字符，仅当format_json为True时有效	False
save_to_img()	将结果保存为图像格式的文件	save_path	str	保存的文件路径，当为目录时，保存文件命名与输入文件类型命名一致	无

• 此外，也支持通过属性获取带结果的可视化图像和预测结果，具体如下：

属性	属性说明
json	获取预测的json格式的结果
img	获取格式为dict的可视化图像

四、二次开发

如果以上模型在您的场景下效果仍然不理想，您可以尝试以下步骤进行二次开发，此处以训练 PP-FormulaNet-S 举例，其他模型替换对应配置文件即可。首先，您需要准备公式识别的数据集，可以参考公式识别 Demo 数据的格式准备，准备好后，即可按照以下步骤进行模型训练和导出，导出后，可以将模型快速集成到上述API中。此处以公式识别 Demo 数据示例。在训练模型之前，请确保已经按照安装文档安装了 PaddleOCR 所需要的依赖。

4.1 环境配置

训练公式识别模型需要安装额外的Python依赖和linux依赖，执行如下命令安装：

sudo apt-get update
sudo apt-get install libmagickwand-dev
pip install tokenizers==0.19.1 imagesize ftfy Wand

4.2 数据集、预训练模型准备

4.2.1 准备数据集

# 下载示例数据集
wget https://paddle-model-ecology.bj.bcebos.com/paddlex/data/ocr_rec_latexocr_dataset_example.tar
tar -xf ocr_rec_latexocr_dataset_example.tar

4.2.2 下载预训练模型

# 下载 PP-FormulaNet_plus-M 预训练模型
wget https://paddleocr.bj.bcebos.com/contribution/rec_ppformulanet_plus_m_train.tar 
tar -xf rec_ppformulanet_plus_m_train.tar

4.3 模型训练

PaddleOCR对代码进行了模块化，训练 PP-FormulaNet_plus-M 识别模型时需要使用 PP-FormulaNet_plus-M 的配置文件。

训练命令如下：

#单卡训练 (默认训练方式)
python3 tools/train.py -c configs/rec/PP-FormuaNet/PP-FormulaNet_plus-M.yaml \
   -o Global.pretrained_model=./rec_ppformulanet_plus_m_train/best_accuracy.pdparams
#多卡训练，通过--gpus参数指定卡号
python3 -m paddle.distributed.launch --gpus '0,1,2,3'  tools/train.py -c configs/rec/PP-FormuaNet/PP-FormulaNet_plus-M.yaml \
        -o Global.pretrained_model=./rec_ppformulanet_plus_m_train/best_accuracy.pdparams

注意：

• 默认每训练 1个 epoch 进行 1 次评估，若您更改训练的 batch_size，或更换数据集，请在训练时作出如下修改

python3  -m paddle.distributed.launch --gpus '0,1,2,3'  tools/train.py -c configs/rec/PP-FormuaNet/PP-FormulaNet_plus-M.yaml \
  -o Global.eval_batch_step=[0,{length_of_dataset//batch_size//4}] \
   Global.pretrained_model=./rec_ppformulanet_plus_m_train/best_accuracy.pdparams

4.4 模型评估

您可以评估已经训练好的权重，如，output/xxx/xxx.pdparams，也可以使用已经下载的模型文件，使用如下命令进行评估：

#注意将pretrained_model的路径设置为本地路径。若使用自行训练保存的模型，请注意修改路径和文件名为{path/to/weights}/{model_name}。
#demo 测试集评估
 python3 tools/eval.py -c configs/rec/PP-FormuaNet/PP-FormulaNet_plus-M.yaml -o \
 Global.pretrained_model=./rec_ppformulanet_plus_m_train/best_accuracy.pdparams

4.5 模型导出

python3 tools/export_model.py -c configs/rec/PP-FormuaNet/PP-FormulaNet_plus-M.yaml -o \
Global.pretrained_model=./rec_ppformulanet_plus_m_train/best_accuracy.pdparams \
Global.save_inference_dir="./PP-FormulaNet_plus-M_infer/"

导出模型后，静态图模型会存放于当前目录的./PP-FormulaNet_plus-M_infer/中，在该目录下，您将看到如下文件：

./PP-FormulaNet_plus-M_infer/
├── inference.json
├── inference.pdiparams
├── inference.yml

至此，二次开发完成，该静态图模型可以直接集成到 PaddleOCR 的 API 中。

五、FAQ

Q1: PaddleOCR 更推荐哪个公式识别模型？

A1: 更推荐使用 PP-FormulaNet 系列模型，如果是英文场景居多且不考虑推理耗时，则可以使用 PP-FormulaNet-L 或者 PP-FormulaNet_plus-L 模型，如果中文场景居多，则可以使用 PP-FormulaNet_plus-L 或者 PP-FormulaNet_plus-M，如果推理设备算力有限且是英文场景，则可以使用 PP-FormulaNet-S。

Q2: 为什么推理报错？

A2: 公式识别模型的推理强依赖于 Paddle 框架 3.0 正式版，请确保版本一致。

Q3: 为什么预测后没有可视化图像？

A3: 可能是因为没有安装LaTeX导致，您需要参考第三节安装LaTeX渲染工具。