docs/version3.x/module_usage/formula_recognition.md
公式识别模块是OCR（光学字符识别）系统中的关键组成部分，负责将图像中的数学公式转换为可编辑的文本或计算机可识别的格式。该模块的性能直接影响到整个OCR系统的准确性和效率。公式识别模块通常会输出数学公式的 LaTeX 或 MathML 代码，这些代码将作为输入传递给文本理解模块进行后续处理。
<table> <tr> <th>模型</th><th>模型下载链接</th> <th>En-BLEU(%)</th> <th>Zh-BLEU(%)</th> <th>GPU推理耗时（ms） [常规模式 / 高性能模式]</th> <th>CPU推理耗时（ms） [常规模式 / 高性能模式]</th> <th>模型存储大小（MB）</th> <th>介绍</th> </tr> <tr> <td>UniMERNet</td> <td><a href="https://paddle-model-ecology.bj.bcebos.com/paddlex/official_inference_model/paddle3.0.0/UniMERNet_infer.tar">推理模型</a>/<a href="https://paddle-model-ecology.bj.bcebos.com/paddlex/official_pretrained_model/UniMERNet_pretrained.pdparams">训练模型</a></td> <td>85.91</td> <td>43.50</td> <td>1311.84 / 1311.84</td> <td>- / 8288.07</td> <td>1530</td> <td>UniMERNet是由上海AI Lab研发的一款公式识别模型。该模型采用Donut Swin作为编码器，MBartDecoder作为解码器，并通过在包含简单公式、复杂公式、扫描捕捉公式和手写公式在内的一百万数据集上进行训练，大幅提升了模型对真实场景公式的识别准确率</td> </tr> <td>PP-FormulaNet-S</td> <td><a href="https://paddle-model-ecology.bj.bcebos.com/paddlex/official_inference_model/paddle3.0.0/PP-FormulaNet-S_infer.tar">推理模型</a>/<a href="https://paddle-model-ecology.bj.bcebos.com/paddlex/official_pretrained_model/PP-FormulaNet-S_pretrained.pdparams">训练模型</a></td> <td>87.00</td> <td>45.71</td> <td>182.25 / 182.25</td> <td>- / 254.39</td> <td>224</td> <td rowspan="2">PP-FormulaNet 是由百度飞桨视觉团队开发的一款先进的公式识别模型，支持5万个常见LateX源码词汇的识别。PP-FormulaNet-S 版本采用了 PP-HGNetV2-B4 作为其骨干网络，通过并行掩码和模型蒸馏等技术，大幅提升了模型的推理速度，同时保持了较高的识别精度，适用于简单印刷公式、跨行简单印刷公式等场景。而 PP-FormulaNet-L 版本则基于 Vary_VIT_B 作为骨干网络，并在大规模公式数据集上进行了深入训练，在复杂公式的识别方面，相较于PP-FormulaNet-S表现出显著的提升，适用于简单印刷公式、复杂印刷公式、手写公式等场景。 </td> </tr> <td>PP-FormulaNet-L</td> <td><a href="https://paddle-model-ecology.bj.bcebos.com/paddlex/official_inference_model/paddle3.0.0/PP-FormulaNet-L_infer.tar">推理模型</a>/<a href="https://paddle-model-ecology.bj.bcebos.com/paddlex/official_pretrained_model/PP-FormulaNet-L_pretrained.pdparams">训练模型</a></td> <td>90.36</td> <td>45.78</td> <td>1482.03 / 1482.03</td> <td>- / 3131.54</td> <td>695</td> </tr> <td>PP-FormulaNet_plus-S</td> <td><a href="https://paddle-model-ecology.bj.bcebos.com/paddlex/official_inference_model/paddle3.0.0/PP-FormulaNet_plus-S_infer.tar">推理模型</a>/<a href="https://paddle-model-ecology.bj.bcebos.com/paddlex/official_pretrained_model/PP-FormulaNet_plus-S_pretrained.pdparams">训练模型</a></td> <td>88.71</td> <td>53.32</td> <td>179.20 / 179.20</td> <td>- / 260.99</td> <td>248</td> <td rowspan="3">PP-FormulaNet_plus 是百度飞桨视觉团队在 PP-FormulaNet 的基础上开发的增强版公式识别模型。与原版相比，PP-FormulaNet_plus 在训练中使用了更为丰富的公式数据集，包括中文学位论文、专业书籍、教材试卷以及数学期刊等多种来源。这一扩展显著提升了模型的识别能力。推理耗时仅包含模型推理耗时，不包含前后处理耗时。表格中的“常规模式”耗时对应本地 <code>paddle_static</code> 推理引擎。
其中，PP-FormulaNet_plus-M 和 PP-FormulaNet_plus-L 模型新增了对中文公式的支持，并将公式的最大预测 token 数从 1024 扩大至 2560，大幅提升了对复杂公式的识别性能。同时，PP-FormulaNet_plus-S 模型则专注于增强英文公式的识别能力。通过这些改进，PP-FormulaNet_plus 系列模型在处理复杂多样的公式识别任务时表现更加出色。 </td>
</tr> <tr> <td>PP-FormulaNet_plus-M</td> <td><a href="https://paddle-model-ecology.bj.bcebos.com/paddlex/official_inference_model/paddle3.0.0/PP-FormulaNet_plus-M_infer.tar">推理模型</a>/<a href="https://paddle-model-ecology.bj.bcebos.com/paddlex/official_pretrained_model/PP-FormulaNet_plus-M_pretrained.pdparams">训练模型</a></td> <td>91.45</td> <td>89.76</td> <td>1040.27 / 1040.27</td> <td>- / 1615.80</td> <td>592</td> </tr> <tr> <td>PP-FormulaNet_plus-L</td> <td><a href="https://paddle-model-ecology.bj.bcebos.com/paddlex/official_inference_model/paddle3.0.0/PP-FormulaNet_plus-L_infer.tar">推理模型</a>/<a href="https://paddle-model-ecology.bj.bcebos.com/paddlex/official_pretrained_model/PP-FormulaNet_plus-L_pretrained.pdparams">训练模型</a></td> <td>92.22</td> <td>90.64</td> <td>1476.07 / 1476.07</td> <td>- / 3125.58</td> <td>698</td> </tr> <tr> <td>LaTeX_OCR_rec</td> <td><a href="https://paddle-model-ecology.bj.bcebos.com/paddlex/official_inference_model/paddle3.0.0/LaTeX_OCR_rec_infer.tar">推理模型</a>/<a href="https://paddle-model-ecology.bj.bcebos.com/paddlex/official_pretrained_model/LaTeX_OCR_rec_pretrained.pdparams">训练模型</a></td> <td>74.55</td> <td>39.96</td> <td>1088.89 / 1088.89</td> <td>- / -</td> <td>99</td> <td>LaTeX-OCR是一种基于自回归大模型的公式识别算法，通过采用 Hybrid ViT 作为骨干网络，transformer作为解码器，显著提升了公式识别的准确性。</td> </tr> </table> <strong>测试环境说明:</strong> <ul> <li><b>性能测试环境</b> <ul> <li><strong>测试数据集：</strong>PaddleOCR 内部自建公式识别测试集</li> <li><strong>硬件配置：</strong> <ul> <li>GPU：NVIDIA Tesla T4</li> <li>CPU：Intel Xeon Gold 6271C @ 2.60GHz</li> </ul> </li> <li><strong>软件环境：</strong> <ul> <li>Ubuntu 20.04 / CUDA 11.8 / cuDNN 8.9 / TensorRT 8.6.1.6</li> <li>paddlepaddle-gpu 3.0.0 / paddleocr 3.0.3</li> </ul> </li> </ul> </li> <li><b>推理模式说明</b></li> </ul> <table border="1"> <thead> <tr> <th>模式</th> <th>GPU配置</th> <th>CPU配置</th> <th>加速技术组合</th> </tr> </thead> <tbody> <tr> <td>常规模式</td> <td>FP32精度 / 无TRT加速</td> <td>FP32精度 / 8线程</td> <td>PaddleInference</td> </tr> <tr> <td>高性能模式</td> <td>选择先验精度类型和加速策略的最优组合</td> <td>FP32精度 / 8线程</td> <td>选择先验最优后端（Paddle/OpenVINO/TRT等）</td> </tr> </tbody> </table>❗ 在快速开始前，请先安装 PaddleOCR 的 wheel 包，详细请参考 安装教程。
使用一行命令即可快速体验：
paddleocr formula_recognition -i https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/general_formula_rec_001.png
上述示例默认使用 <code>paddle_static</code> 推理引擎，请先按照飞桨框架安装完成 PaddlePaddle 安装。
<b>注：</b>PaddleOCR 官方模型默认从 HuggingFace 获取，如运行环境访问 HuggingFace 不便，可通过环境变量修改模型源为 BOS：PADDLE_PDX_MODEL_SOURCE="BOS"，未来将支持更多主流模型源；
您也可以将公式识别的模块中的模型推理集成到您的项目中。运行以下代码前，请您下载示例图片到本地。
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")
上述示例默认使用 <code>paddle_static</code> 推理引擎，请先按照飞桨框架安装完成 PaddlePaddle 安装。
运行后，得到的结果为：
{'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的第几页，否则为 Nonerec_formula：表示公式图像的预测LaTeX源码可视化图片如下，左侧是待预测的公式图像，右边是预测的结果渲染后的公式图像：
<b> 注：如果您需要对公式识别模块进行可视化，需要运行如下命令来对LaTeX渲染环境进行安装。目前公式识别模块可视化只支持Ubuntu环境，其他环境暂不支持。对于复杂公式，LaTeX 结果可能包含部分高级的表示，Markdown等环境中未必可以成功显示：</b>
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为例），具体说明如下：<b>例如：</b><code>"cpu"</code>、<code>"gpu"</code>、<code>"npu"</code>、<code>"gpu:0"</code>、<code>"gpu:0,1"</code>。
如指定多个设备，将进行并行推理。
默认情况下，优先使用 GPU 0；若不可用则使用 CPU。
</td> <td><code>str|None</code></td> <td><code>None</code></td> </tr> <tr> <td><code>engine</code></td> <td><b>含义：</b>推理引擎。 <b>说明：</b>支持 <code>None</code>（默认值）、<code>paddle</code>、<code>paddle_static</code>、<code>paddle_dynamic</code>、<code>transformers</code>。保持为默认值 <code>None</code> 时，本地推理默认使用 <code>paddle_static</code> 引擎。详细说明、取值、兼容性规则与示例请参见 <a href="../inference_engine.md">推理引擎与配置说明</a>。</td> <td><code>str|None</code></td> <td><code>None</code></td> </tr> <tr> <td><code>engine_config</code></td> <td><b>含义：</b>推理引擎配置。 <b>说明：</b>推荐与 <code>engine</code> 搭配使用。详细字段、兼容性规则与示例请参见 <a href="../inference_engine.md">推理引擎与配置说明</a>。</td> <td><code>dict|None</code></td> <td><code>None</code></td> </tr> <tr> <td><code>enable_hpi</code></td> <td>是否启用高性能推理。</td> <td><code>bool</code></td> <td><code>False</code></td> </tr> <tr> <td><code>use_tensorrt</code></td> <td>是否启用 Paddle Inference 的 TensorRT 子图引擎。如果模型不支持通过 TensorRT 加速，即使设置了此标志，也不会使用加速。对于 CUDA 11.8 版本的飞桨，兼容的 TensorRT 版本为 8.x（x>=6），建议安装 TensorRT 8.6.1.6。
</td> <td><code>bool</code></td> <td><code>False</code></td> </tr> <tr> <td><code>precision</code></td> <td>当使用 Paddle Inference 的 TensorRT 子图引擎时设置的计算精度。 <b>可选项：</b><code>"fp32"</code>、<code>"fp16"</code>。</td> <td><code>str</code></td> <td><code>"fp32"</code></td> </tr> <tr> <td><code>enable_mkldnn</code></td> <td> 是否启用 MKL-DNN 加速推理。如果 MKL-DNN 不可用或模型不支持通过 MKL-DNN 加速，即使设置了此标志，也不会使用加速。 </td> <td><code>bool</code></td> <td><code>True</code></td> </tr> <tr> <td><code>mkldnn_cache_capacity</code></td> <td> MKL-DNN 缓存容量。 </td> <td><code>int</code></td> <td><code>10</code></td> </tr> <tr> <td><code>cpu_threads</code></td> <td>在 CPU 上推理时使用的线程数量。</td> <td><code>int</code></td> <td><code>10</code></td> </tr> </tbody> </table>predict() 方法进行推理预测，该方法会返回一个结果列表。另外，本模块还提供了 predict_iter() 方法。两者在参数接受和结果返回方面是完全一致的，区别在于 predict_iter() 返回的是一个 generator，能够逐步处理和获取预测结果，适合处理大型数据集或希望节省内存的场景。可以根据实际需求选择使用这两种方法中的任意一种。predict() 方法参数有 input 和 batch_size，具体说明如下：json文件的操作:如果以上模型在您的场景下效果仍然不理想，您可以尝试以下步骤进行二次开发，此处以训练 PP-FormulaNet-S 举例，其他模型替换对应配置文件即可。首先，您需要准备公式识别的数据集，可以参考公式识别 Demo 数据的格式准备，准备好后，即可按照以下步骤进行模型训练和导出，导出后，可以将模型快速集成到上述API中。此处以公式识别 Demo 数据示例。在训练模型之前，请确保已经按照安装文档安装了 PaddleOCR 所需要的依赖。
训练公式识别模型需要安装额外的Python依赖和linux依赖，执行如下命令安装：
sudo apt-get update
sudo apt-get install libmagickwand-dev
pip install tokenizers==0.19.1 imagesize ftfy Wand
# 下载示例数据集
wget https://paddle-model-ecology.bj.bcebos.com/paddlex/data/ocr_rec_latexocr_dataset_example.tar
tar -xf ocr_rec_latexocr_dataset_example.tar
# 下载 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
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
注意：
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
您可以评估已经训练好的权重，如，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
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 中。
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渲染工具。