企业官网建设流程全解析

PaddleOCR Paddle2ONNX 预测功能测试：TIPC 测试框架下的模型转换与 ONNX 推理验证

【免费下载链接】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 仓库中 TIPC（Test Infrastructure for PaddlePaddle）测试体系内的 Paddle2ONNX 预测功能测试：它通过test_paddle2onnx.sh将 Paddle 推理模型转换为 ONNX 格式，再用 PaddleOCR 自身的预测脚本以--use_onnx=True加载 ONNX 模型完成端到端正确性验证。读完本文，你将掌握 TIPC 中 Paddle2ONNX 测试的完整流程、17 行测试配置文件的每一项参数含义、测试脚本的底层实现逻辑，以及如何读懂运行结果日志并自主扩展到新的 OCR 模型。

1. 测试定位与覆盖范围

在 PaddleOCR 的 test_tipc 目录中，Paddle2ONNX 预测功能测试的主程序为test_paddle2onnx.sh，它承担两类验证职责：

1. 模型转化功能验证：调用paddle2onnx命令行工具，把 Paddle 的推理模型（inference.pdmodel+inference.pdiparams）转换为 ONNX 格式的model.onnx；
2. 转化结果正确性验证：使用 PaddleOCR 自带的预测脚本（如tools/infer/predict_det.py）以 ONNX Runtime 为后端加载转换后的模型进行推理，确认转换前后预测行为一致。

根据训练时是否使用量化，测试模型被划分为正常模型和量化模型两类，对应的测试覆盖矩阵如下（来自 test_paddle2onnx.md）：

即每一类模型都要求同时通过 GPU 与 CPU 两种设备上的转换 + 推理验证。从仓库现有配置文件看，test_tipc/configs/下各模型目录中均以model_linux_gpu_normal_normal_paddle2onnx_python_linux_cpu.txt形式命名配置（例如 ch_PP-OCRv2_det 的配置），命名中的两个normal分别对应"正常模型"与"正常训练"，linux_cpu则表明 ONNX 推理阶段以 CPU 环境为基线，同时配置内通过--use_gpu:True|False枚举 GPU/CPU 两种推理设备。

2. 测试整体流程

整个测试由两个脚本接力完成：

• prepare.sh：准备测试环境（安装paddle2onnx、onnxruntime、onnx三个依赖包）、下载对应模型的推理模型压缩包与测试图片数据并解压；
• test_paddle2onnx.sh：读取配置文件，依次执行模型转换与 ONNX 推理，并把每个步骤的结果写入日志。

bash test_tipc/prepare.sh ./test_tipc/configs/ch_PP-OCRv2_det/model_linux_gpu_normal_normal_paddle2onnx_python_linux_cpu.txt "paddle2onnx_infer" # 用法: bash test_tipc/test_paddle2onnx.sh ./test_tipc/configs/ch_PP-OCRv2_det/model_linux_gpu_normal_normal_paddle2onnx_python_linux_cpu.txt

注意prepare.sh的第二个参数是测试模式，必须显式传paddle2onnx_infer才会进入 Paddle2ONNX 的数据准备分支（见 prepare.sh）：该分支会先执行python -m pip install paddle2onnx onnxruntime onnx安装转换与推理所需依赖，再按model_name匹配下载对应模型，最后统一下载检测/识别测试图片数据ch_det_data_50.tar与rec_inference.tar到./inference/目录。

测试结束后，所有产物统一输出在test_tipc/output/{model_name}/paddle2onnx/目录下：

• trans_model_det.log/trans_model_rec.log：检测/识别模型的转换过程日志；
• paddle2onnx_infer_gpu.log/paddle2onnx_infer_cpu.log：GPU/CPU 两种设备上的 ONNX 推理日志；
• results_paddle2onnx.log：汇总每一步命令执行成功或失败的状态清单。

3. 配置文件逐行解析

TIPC 的 Paddle2ONNX 测试配置是一个 17 行的key:value文本文件，以 ch_PP-OCRv2_det 配置 为例：

===========================paddle2onnx_params=========================== model_name:ch_PP-OCRv2_det python:python3.7 2onnx: paddle2onnx --det_model_dir:./inference/ch_PP-OCRv2_det_infer/ --model_filename:inference.pdmodel --params_filename:inference.pdiparams --det_save_file:./inference/det_v2_onnx/model.onnx --rec_model_dir: --rec_save_file: --opset_version:10 --enable_onnx_checker:True inference:tools/infer/predict_det.py --use_gpu:True|False --det_model_dir: --rec_model_dir: --image_dir:./inference/ch_det_data_50/all-sum-510/

各字段含义如下：

对于同时包含检测与识别子模型的端到端配置（如 ch_PP-OCRv2 配置），第 4–9 行会全部填满：--det_model_dir:./inference/ch_PP-OCRv2_det_infer/、--rec_model_dir:./inference/ch_PP-OCRv2_rec_infer/、--det_save_file:./inference/det_v2_onnx/model.onnx、--rec_save_file:./inference/rec_v2_onnx/model.onnx，推理入口则为tools/infer/predict_system.py --rec_image_shape="3,32,320"，测试图片也换成单张00008790.jpg。表格结构识别（slanet、en_table_structure）则复用检测字段承载结构模型，推理入口改为ppstructure/table/predict_structure.py并附带--table_char_dict_path指定表格结构字典（分别见 slanet 配置 与 en_table_structure 配置）。

目前仓库共提供 14 份 Paddle2ONNX 测试配置，覆盖ch_PP-OCRv2、ch_PP-OCRv3、ch_ppocr_mobile_v2_0、ch_ppocr_server_v2_0四组模型的整体（det+rec）形态及其单独的_det/_rec形态，外加PP-OCRv3_mobile_rec、slanet、en_table_structure等专项模型。

4. 测试脚本实现拆解

test_paddle2onnx.sh通过 source 引入 common_func.sh 中的func_parser_key、func_parser_value、func_set_params、status_check等解析与状态检查工具函数，其主体逻辑（见 test_paddle2onnx.sh）可分为两段。

4.1 模型转换阶段

脚本先取配置前 17 行解析出全部字段，然后根据model_name决定转换哪些子模型：

• 端到端模型（ch_PP-OCRv2、ch_PP-OCRv3、ch_ppocr_mobile_v2_0、ch_ppocr_server_v2_0）：依次转换检测与识别两个模型，即执行两次paddle2onnx；
• 纯检测模型（名称含det）：仅转换检测模型；
• 纯识别模型（名称含rec）：仅转换识别模型；
• 表格结构模型（slanet、en_table_structure）：仅转换结构模型。

实际拼装的转换命令形如：

paddle2onnx --model_dir=./inference/ch_PP-OCRv2_det_infer/ \ --model_filename=inference.pdmodel \ --params_filename=inference.pdiparams \ --save_file=./inference/det_v2_onnx/model.onnx \ --opset_version=10 \ --enable_onnx_checker=True \ --enable_dev_version=False

细节上，转换命令统一追加--enable_dev_version参数：常规 OCR 模型使用False（跳过开发版本算子以提升兼容性），而slanet/en_table_structure分支使用True（见 test_paddle2onnx.sh），这反映了两类模型在算子层面的差异。每条转换命令执行后都会立即用status_check校验退出码并把结果追加进results_paddle2onnx.log。

4.2 ONNX 推理阶段

转换完成后，脚本遍历--use_gpu字段中True|False两个枚举值，在 GPU 与 CPU 下各执行一次推理。推理命令会复用配置第 2 行的python、第 12 行的推理脚本，并自动把第 7/9 行的转换产物路径回填为推理模型的--det_model_dir/--rec_model_dir参数，同时显式追加--use_onnx=True，例如：

python3.7 tools/infer/predict_det.py --use_gpu=True \ --image_dir=./inference/ch_det_data_50/all-sum-510/ \ --det_model_dir=./inference/det_v2_onnx/model.onnx \ --use_onnx=True

从 PaddleOCR 推理侧源码看，--use_onnx是tools/infer/utility.py中注册的公共参数（默认False），检测、识别、分类、端到端等预测器都会读取它。以 predict_det.py 为例：当use_onnx=True时，预测器会从 ONNX 输入张量中读取固定的[N, C, H, W]形状，并把预处理阶段的DetResizeForTest锁定为该形状（image_shape: [img_h, img_w]），从而保证送入 ONNX Runtime 的图片尺寸与模型静态输入严格一致——这正是 ONNX 推理与 Paddle 动态 shape 推理的关键差异点，也是转换后正确性验证的核心所在。

5. 运行结果解读

每一步转换与推理命令的成败都会实时写入汇总日志test_tipc/output/{model_name}/paddle2onnx/results_paddle2onnx.log。

运行成功时输出形如：

Run successfully with command - ch_PP-OCRv2_det - paddle2onnx --model_dir=./inference/ch_PP-OCRv2_det_infer/ --model_filename=inference.pdmodel --params_filename=inference.pdiparams --save_file=./inference/det_v2_onnx/model.onnx --opset_version=10 --enable_onnx_checker=True! Run successfully with command - ch_PP-OCRv2_det - python3.7 tools/infer/predict_det.py --use_gpu=True --image_dir=./inference/ch_det_data_50/all-sum-510/ --det_model_dir=./inference/det_v2_onnx/model.onnx --use_onnx=True > ./test_tipc/output/ch_PP-OCRv2_det/paddle2onnx/paddle2onnx_infer_gpu.log 2>&1 ! Run successfully with command - ch_PP-OCRv2_det - python3.7 tools/infer/predict_det.py --use_gpu=False --image_dir=./inference/ch_det_data_50/all-sum-510/ --det_model_dir=./inference/det_v2_onnx/model.onnx --use_onnx=True > ./test_tipc/output/ch_PP-OCRv2_det/paddle2onnx/paddle2onnx_infer_cpu.log 2>&1 !

运行失败时输出形如：

Run failed with command - ch_PP-OCRv2_det - paddle2onnx --model_dir=./inference/ch_PP-OCRv2_det_infer/ --model_filename=inference.pdmodel --params_filename=inference.pdiparams --save_file=./inference/det_v2_onnx/model.onnx --opset_version=10 --enable_onnx_checker=True! ...

status_check的判断依据是上一条命令的退出码（PIPESTATUS[0]），因此只要转换或推理进程以非零码退出就会被记为Run failed。需要说明的是，这里"成功"仅代表命令正常执行完毕；若想进一步核对 OCR 识别质量，可查看paddle2onnx_infer_gpu.log/paddle2onnx_infer_cpu.log中的预测文本输出，与 Paddle 原生推理（不带--use_onnx）的结果进行人工比对。

6. 扩展新模型的测试配置

若要在 TIPC 中为新的 OCR 模型增加 Paddle2ONNX 测试，只需按第 3 节的 17 行格式在test_tipc/configs/{model_name}/下新增一份配置文件，并遵循以下约定：

1. 命名：沿用model_linux_gpu_normal_normal_paddle2onnx_python_linux_cpu.txt的命名风格，便于 CI 识别；
2. 模型类型命名：转换分支按model_name匹配，名称中含det/rec分别走单模型分支，表格结构模型需要在slanet/en_table_structure分支（或新增等价分支）中登记并设置--enable_dev_version=True；
3. 前置数据：在 prepare.sh 的paddle2onnx_infer分支中补充对应模型的wget下载与解压逻辑，保证--det_model_dir/--rec_model_dir指向的推理模型真实存在；
4. 图片目录：--image_dir指向已下载的测试图片路径，检测任务建议使用多图目录以覆盖批量场景。

7. 延伸阅读

• 完整 Paddle2ONNX 转换与使用教程可参考 deploy/paddle2onnx 与 deploy/paddle2onnx/readme_ch.md，其中给出了 ONNX 模型在移动端、服务端等场景的进一步部署方式；
• TIPC 其他功能测试（Serving、C++ 推理、PTQ 量化推理等）说明位于 test_tipc/docs 目录，可对照 test_serving.md、test_inference_cpp.md 理解统一的测试框架风格；
• 推理侧--use_onnx的完整解析逻辑见 tools/infer/utility.py，各预测器的 ONNX 分支实现见 tools/infer/predict_det.py、tools/infer/predict_rec.py。

【免费下载链接】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