【免费下载链接】models
Officially maintained, supported by PaddlePaddle, including CV, NLP, Speech, Rec, TS, big models and so on.
本篇指南围绕 PaddlePaddle models 仓库的 TIPC（训推一体全流程）测试体系，讲解如何为任意 Paddle 模型搭建 Paddle2ONNX 全流程功能测试：通过 test_paddle2onnx.sh + prepare.sh + common_func.sh 三个脚本与 paddle2onnx_infer_python.txt 一个配置文件，一键跑通「Paddle 模型转 ONNX + ONNX 模型推理」两个环节。读完本文，你将掌握配置文件与运行命令的映射解析原理、逐行配置要领、六步开发流程以及结果核验方法，能够为自己的模型快速复制这套自动化测试能力。
1. 简介：Paddle2ONNX 全流程功能测试测什么
Paddle2ONNX 功能测试主要关注 Linux GPU/CPU 环境下模型的 Paddle2ONNX 全流程功能，具体测试点只有两个：
- 模型转换：使用 Paddle2ONNX 将 Paddle 静态图推理模型转换为 ONNX 模型，保证转换链路跑通；
- 模型推理：基于转换产出的 ONNX 模型，使用 Python 推理程序完成预测，保证推理链路跑通。
为了一键跑通上述全部功能，TIPC 体系提供了一套自动化测试工具，由 3 个脚本文件 + 1 个配置文件 组成：
| 文件 | 作用 | 是否需要修改 |
|---|---|---|
test_paddle2onnx.sh | 测试脚本，解析 paddle2onnx_infer_python.txt 得到具体执行命令，依次执行模型转换与模型推理 | 无需修改 |
prepare.sh | 准备测试所需的小数据集与预训练/推理模型 | 按需修改（模型名分支） |
common_func.sh | 公共函数库，提供配置解析、参数拼装、状态检查等通用函数 | 无需修改 |
paddle2onnx_infer_python.txt | 配置文件，内容会被 test_paddle2onnx.sh 解析成具体执行命令字段 | 按模型修改 |
这套工具在仓库中的完整落地示例位于 tutorials/mobilenetv3_prod/Step6/test_tipc 目录，其中 mobilenet_v3_small 的配置与测试脚本可直接作为开发模板。TIPC 系列文档的总览见 tutorials/tipc/paddle2onnx/README.md，它将该主题拆成「Paddle2ONNX 推理程序功能开发」与「Paddle2ONNX 推理测试程序开发」两步，本篇聚焦后者。
2. 命令与配置文件解析
2.1 命令解析：一切的起点是「三段式」
Paddle2ONNX 模型转换和模型预测的运行命令差别很大，但都可以拆解为三个部分：
python run_script set_configs
以通过 argparse 传参的场景为例，命令 python3.7 deploy/onnx_python/infer.py --onnx_file=./inference/mobilenetv3_model_onnx/model.onnx 的三段拆解如下：
python部分：python3.7（解释器）；run_script部分：deploy/onnx_python/infer.py（可执行脚本）；set_configs部分：--onnx_file=./inference/mobilenetv3_model_onnx/model.onnx（传给脚本的配置参数）。
其中可修改参数 set_configs 一般通过 = 分隔，= 前为 key，= 后为 value。于是，只要给定一个配置文件模板，解析出其中的 key 和 value，再结合固定的 python 与 run_script，就能拼装出一条完整可执行的命令——这正是 test_paddle2onnx.sh 的底层逻辑。
2.2 配置文件结构：13 行、两类内容、三种字段
完整的 paddle2onnx_infer_python.txt 配置文件共有 13 行，包含两方面的内容：
- Paddle2ONNX 模型转换：第 4~10 行（其中第 2、3 行为模型名与 python 环境）；
- 模型 Inference 推理：第 11~13 行。
具体内容见 paddle2onnx_infer_python.txt，完整 13 行如下：
===========================paddle2onnx_params===========================
model_name:mobilenet_v3_small
python:python3.7
2onnx: paddle2onnx
--model_dir:./inference/mobilenet_v3_small_infer/
--model_filename:inference.pdmodel
--params_filename:inference.pdiparams
--save_file:./inference/mobilenet_v3_small_onnx/model.onnx
--opset_version:10
--enable_onnx_checker:True
inference:deploy/onnx_python/infer.py
--onnx_file:./inference/mobilenetv3_model_onnx/model.onnx
--img_path:./lite_data/test/demo.jpg
配置文件中主要存在以下 3 种类型的字段：
- 一行内容以冒号
:为分隔符：该行可被解析为key:value格式，需要根据实际含义修改该行内容（下文详述）； - 一行内容为
======xxxxx=====：该行是注释信息，无需修改； - 一行内容以
##开头：表示段落分隔符，没有实际意义，无需修改。
2.3 模型转换配置参数
在配置文件中，可以通过 key:value 方式配置 Paddle 模型路径、ONNX 模型路径等常用超参数。模型转换部分（对应配置文件第 2~10 行）的参数说明如下：
| 行号 | 参考内容 | 含义 | key 是否需要修改 | value 是否需要修改 | 修改内容 |
|---|---|---|---|---|---|
| 2 | model_name:mobilenet_v3_small | 模型名字 | 否 | 是 | value 修改为自己的模型名字 |
| 3 | python:python3.7 | python 环境 | 否 | 是 | value 修改为自己的 python 环境 |
| 4 | 2onnx: paddle2onnx | paddle2onnx 命令 | 否 | 否 | - |
| 5 | --model_dir:./inference/mobilenet_v3_small_infer/ | Paddle inference 模型保存路径 | 否 | 是 | value 修改为自己 Inference 模型的路径 |
| 6 | --model_filename:inference.pdmodel | pdmodel 文件名 | 否 | 是 | value 修改为 pdmodel 文件名 |
| 7 | --params_filename:inference.pdiparams | pdiparams 文件名 | 否 | 是 | value 修改为 pdiparams 文件名 |
| 8 | --save_file:./inference/mobilenet_v3_small_onnx/model.onnx | 转换出的 onnx 模型目录 | 否 | 是 | value 修改为 onnx 模型保存路径 |
| 9 | --opset_version:10 | ONNX Opset 版本号 | 否 | 是（如需变更） | value 修改为目标 Opset，Paddle2ONNX 稳定支持 9~11，默认 10 |
| 10 | --enable_onnx_checker:True | 是否检查导出 ONNX 模型的正确性 | 否 | 是（如需关闭） | value 取 True/False |
以模型转换命令 paddle2onnx --model_dir=./inference/resnet50_infer/ --model_filename=inference.pdmodel --params_filename=inference.pdiparams --save_file=./inference/resnet50_onnx/model.onnx 为例，共包含 4 个超参数，映射到配置文件的方式为：
- inference 模型路径：对应
--model_dir=./inference/resnet50_infer/，修改第 5 行，内容改为--model_dir:./inference/resnet50_infer/； - pdmodel 文件名：对应
--model_filename=inference.pdmodel，修改第 6 行，内容改为--model_filename:inference.pdmodel； - pdiparams 文件名、onnx 输出路径：分别对应第 7、8 行，以此类推，将
=换成:写入即可。
2.4 模型 Inference 推理配置参数
推理部分（对应配置文件第 11~13 行）的参数说明如下：
| 行号 | 参考内容 | 含义 | key 是否需要修改 | value 是否需要修改 | 修改内容 |
|---|---|---|---|---|---|
| 11 | inference:deploy/onnx_python/infer.py | 启动 inference 预测命令 | 否 | 是 | value 修改为预测脚本路径 |
| 12 | --onnx_file:./inference/mobilenetv3_model_onnx/model.onnx | onnx 模型目录 | 否 | 是 | value 修改为待预测的 onnx 模型（与转换出的 onnx 模型目录一致） |
| 13 | --img_path:./lite_data/test/demo.jpg | 预测图片路径 | 否 | 是 | value 修改为预测图片路径 |
以推理命令 python3.7 deploy/onnx_python/infer.py --onnx_file=./inference/resnet50_model_onnx/model.onnx --img_path=./my_data/test_img.png 为例，共包含 2 个超参数：
- onnx 模型路径：
--onnx_file=./inference/resnet50_model_onnx/model.onnx，修改第 12 行，key为--onnx_file，value为./inference/resnet50_model_onnx/model.onnx，内容改为--onnx_file:./inference/resnet50_model_onnx/model.onnx； - 预测图片路径：
--img_path=./my_data/test_img.png，修改第 13 行，key为--img_path，value为./my_data/test_img.png，内容改为--img_path:./my_data/test_img.png。
2.5 源码级解析机制：脚本如何把配置文件变成命令
从源码看，配置文件之所以能被解析成命令，依赖 common_func.sh 中两个核心函数：
func_parser_key：以:为分隔符（IFS=":"），取数组第一个元素作为 key；func_parser_value：以:为分隔符，取数组第二个元素作为 value；func_set_params：将key、value拼装为key=value，当 key 或 value 为null/空串时输出空，从而支持可选参数。
而 test_paddle2onnx.sh 的执行流程为：
source test_tipc/common_func.sh引入公共函数；- 用
awk 'NR==1, NR==13{print}'截取配置文件前 13 行，按换行拆分为数组； - 依次解析
model_name、python、padlle2onnx_cmd（第 3 行2onnx:的值）、转换参数（第 4~9 行）与推理参数（第 10~12 行）； - 在
func_paddle2onnx函数中，先用func_set_params拼出trans_model_cmd（模型转换命令），执行并通过status_check记录状态；再用${python} ${inference_py} ${set_img_dir} ${set_model_dir}拼出推理命令并执行。
值得注意的是，脚本将日志统一写入 ./test_tipc/output/${model_name}/paddle2onnx_infer/ 目录，包括结果汇总日志 results_paddle2onnx.log、转换日志 trans_model.log 与推理日志 paddle2onnx_infer_cpu.log，运行失败时可通过这些日志精确定位到具体命令。
3. Paddle2ONNX 功能测试开发六步流程
完整的 Paddle2ONNX 链路（含推理程序功能开发）可参考下图流程：
测试程序开发共分 6 个步骤，其中设置了 2 个核验点（验证配置正确性、验证目录结构与文档齐全），下面逐步展开。
3.1 步骤一：准备待测试的命令
【基本内容】
准备模型转换、模型推理两条命令，后续会按照第 2 节所述内容，将命令中的可变参数映射到配置文件中。
【实战】
MobileNetV3 的 Paddle2ONNX 模型转换、推理示例运行命令如下：
# Paddle2ONNX 模型转换
paddle2onnx --model_dir=./inference/mobilenet_v3_small_infer/ \
--model_filename=inference.pdmodel \
--params_filename=inference.pdiparams \
--save_file=./inference/mobilenet_v3_small_onnx/model.onnx \
--opset_version=10 \
--enable_onnx_checker=True
# ONNX 模型推理
python3.7 deploy/onnx_python/infer.py --onnx_file=./inference/mobilenetv3_model_onnx/model.onnx --img_path=./lite_data/test/demo.jpg
转换命令中的 --model_dir/--model_filename/--params_filename/--save_file 对应配置第 5~8 行；推理命令中的 --onnx_file/--img_path 对应配置第 12~13 行。参考的 ONNX Python 推理实现见 deploy/onnx_python/infer.py 及其 README。
3.2 步骤二：准备数据与环境
【基本内容】
- 数据集：为方便快速验证转换与推理过程，需要准备一个小数据集（训练集和验证集各 8~16 张图像即可，压缩后数据大小建议在 20M 以内），放在
lite_data文件夹下。小数据集准备思路可参考论文复现赛指南中的数据章节。 - 环境：安装好 PaddlePaddle 后，再安装 Paddle2ONNX 与 ONNXRuntime 即可进行功能测试开发：
python -m pip install paddle2onnxpython -m pip install onnxruntime==1.9.0（建议版本，可根据环境更换）
【注意事项】
- 为方便管理，建议在上传 repo 前先将
lite_data文件夹压缩为 tar 包，直接上传 tar 包；测试时先解压再使用。- 压缩命令：
tar -zcf lite_data.tar lite_data - 解压命令：
tar -xf lite_data.tar
- 压缩命令：
- 从 prepare.sh 的
paddle2onnx_infer分支可以看到，该脚本会自动完成三件事：安装paddle2onnx与onnxruntime==1.9.0、解压./test_images/lite_data.tar、下载并解压 mobilenet_v3_small 的 inference 模型包（mobilenet_v3_small_infer.tar），因此新模型接入时需要在prepare.sh中补充对应的模型获取分支。
3.3 步骤三：准备开发所需脚本
【基本内容】
在 repo 中新建 test_tipc 目录，将文件 common_func.sh、prepare.sh 和 test_paddle2onnx.sh 分别拷贝到 test_tipc 目录中。
【注意事项】
- 上述 3 个脚本文件无需改动，在实际使用时直接修改配置文件即可。其中
prepare.sh在接入新模型时需按模型名补充数据/模型下载分支。
3.4 步骤四：填写配置文件
【基本内容】
在 repo 的 test_tipc/ 目录中新建 configs/model_name 目录，将文件 paddle2onnx_infer_python.txt 拷贝到该目录中，其中 model_name 需要修改为您自己的模型名称。
【实战】
配置文件的含义解析参考第 2.2 节「配置文件解析」：将两条待测命令的可变参数按 key:value 格式逐行填入，例如把 model_name 改为自己的模型名、python 改为实际解释器、--model_dir 等改为自己模型推理文件的真实路径、--img_path 改为测试图片路径。
3.5 步骤五：验证配置正确性
【基本内容】
基于修改完的配置，依次运行以下两条命令：
bash test_tipc/prepare.sh ${your_params_file} paddle2onnx_infer
bash test_tipc/test_paddle2onnx.sh ${your_params_file} paddle2onnx_infer
【注意事项】
如果运行失败，脚本会输出具体的报错命令，可根据输出的报错命令排查配置文件的问题并修改，示例报错如下：
Run failed with command - paddle2onnx --model_dir=./inference/mobilenet_v3_small_infer/ --model_filename=inference.pdmodel --params_filename=inference.pdiparams --save_file=./inference/mobilenet_v3_small_onnx/model.onnx --opset_version=10 --enable_onnx_checker=True!
排查要点：核对第 5~8 行的路径是否存在且正确、第 3 行 python 环境是否可用、第 9~10 行 Opset 与 checker 参数是否被目标模型支持；同时可查看 ./test_tipc/output/${model_name}/paddle2onnx_infer/ 下的 trans_model.log 与 paddle2onnx_infer_cpu.log 定位具体原因。
【实战】
以 mobilenet_v3_small 的 Linux GPU/CPU Paddle2ONNX 功能测试为例，完整命令如下：
bash test_tipc/prepare.sh ./test_tipc/configs/mobilenet_v3_small/paddle2onnx_infer_python.txt paddle2onnx_infer
bash test_tipc/test_paddle2onnx.sh ./test_tipc/configs/mobilenet_v3_small/paddle2onnx_infer_python.txt paddle2onnx_infer
输出结果如下，表示命令运行成功：
Run successfully with command - paddle2onnx --model_dir=./inference/mobilenet_v3_small_infer/ --model_filename=inference.pdmodel --params_filename=inference.pdiparams --save_file=./inference/mobilenet_v3_small_onnx/model.onnx --opset_version=10 --enable_onnx_checker=True!
Run successfully with command - python3.7 deploy/onnx_python/infer.py --img_path=./lite_data/test/demo.jpg --onnx_file=./inference/mobilenet_v3_small_onnx/model.onnx > ./log/mobilenet_v3_small/paddle2onnx_infer_cpu.log 2>&1 !
【核验】
基于修改后的配置文件，测试通过，全部命令成功——即模型转换命令与推理命令均以退出码 0 结束（status_check 依据退出码写入 results_paddle2onnx.log）。
3.6 步骤六：撰写说明文档
【基本内容】
撰写 TIPC 功能总览与测试流程说明文档，分别为：
- TIPC 功能总览文档：
test_tipc/README.md； - Paddle2ONNX 测试说明文档：
test_tipc/docs/test_paddle2onnx.md。
两个文档模板分别位于下述位置，可直接拷贝到自己的 repo 中，再根据自己的模型进行修改：
【实战】
mobilenet_v3_small 的 test_tipc 文档即上述两处模板来源，其中 README 对该模型支持的功能（含 Paddle2ONNX）做总体介绍，docs 下的说明文档对 Paddle2ONNX 功能支持情况进行详细介绍。
【核验】
repo 中最终目录结构如下：
test_tipc
|--configs # 配置目录
| |--model_name # 您的模型名称
| |--paddle2onnx_infer_python.txt # paddle2onnx测试配置文件
|--docs # 文档目录
| |--test_paddle2onnx.md # paddle2onnx测试说明文档
|----README.md # TIPC说明文档
|----test_paddle2onnx.sh # TIPC paddle2onnx解析脚本，无需改动
|----common_func.sh # TIPC基础训练推理测试常用函数，无需改动
基于 test_paddle2onnx.md 文档，即可完整跑通「Paddle2ONNX 功能测试」流程。
4. FAQ 与常见问题排查
- 模型转换失败如何排查？ 转换阶段失败时脚本会打印
Run failed with command - ...并附上完整命令，先核对命令中--model_dir/--model_filename/--params_filename指向的文件是否存在、是否为动转静导出的静态图推理模型；同时检查trans_model.log中 Paddle2ONNX 的具体报错。 - ONNX Opset 版本如何选择？ Paddle2ONNX 目前稳定支持导出 ONNX Opset 9~11，默认值为 10，部分 Paddle 算子支持更低的 Opset 转换；若算子转换报错，可尝试调整
--opset_version后重新验证。 - 推理阶段报错如何定位？ 推理日志写入
paddle2onnx_infer_cpu.log，常见原因包括：--onnx_file指向的 onnx 模型与转换产物路径不一致、--img_path图片路径缺失、onnxruntime 版本与转换产物的算子不兼容（prepare 阶段默认安装 1.9.0）。 - 环境依赖如何准备？ 功能测试需要 PaddlePaddle、Paddle2ONNX 与 ONNXRuntime 三者就绪；
prepare.sh的paddle2onnx_infer分支会自动完成 paddle2onnx 与 onnxruntime==1.9.0 的安装，小数据集与推理模型也会一并下载解压，新模型只需在prepare.sh中补充对应下载分支。
至此，从命令准备、数据环境、脚本拷贝、配置填写、结果验证到文档撰写，一条完整的 Paddle2ONNX 功能测试开发链路即全部打通。
【免费下载链接】models
Officially maintained, supported by PaddlePaddle, including CV, NLP, Speech, Rec, TS, big models and so on.
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
