ViTPose 模型导出 ONNX 实战指南:从 PyTorch 权重到可部署的 ONNX 模型

原创2026-10-14 13:22:501,690 阅读
文章标签:人工智能计算机视觉深度学习机器学习

ViTPose 模型导出 ONNX 实战指南:从 PyTorch 权重到可部署的 ONNX 模型

导读:本文基于 ViTPose(MMPose 姿态估计代码库)官方教程「Tutorial 5: Exporting a model to ONNX」,系统讲解如何将仓库中训练好的 PyTorch 人体姿态估计模型导出为标准 ONNX 格式。你将掌握 tools/deployment/pytorch2onnx.py 脚本的完整用法、每个命令行参数的含义与默认值、导出前的环境准备,以及如何通过数值比对验证导出模型与原始 PyTorch 模型的一致性,为后续在 TensorRT、ONNX Runtime 等推理引擎上的部署打下基础。

一、ONNX 导出能力概览:支持哪些模型

ONNX(Open Neural Network Exchange)是一种开放式的神经网络交换格式,它让 AI 开发者可以在模型训练的整个生命周期中自由选择最合适的工具:模型在 PyTorch 中训练,导出为 ONNX 后,即可被 ONNX Runtime、TensorRT、OpenVINO 等众多推理框架直接加载运行,实现"一次导出、多处部署"。

根据本仓库的官方教程文档 5_export_model.md,当前代码库支持将基于 MMPose 训练得到的 PyTorch 模型导出为 ONNX,官方明确验证过的主干网络(backbone)包括:

  • ResNet:经典卷积主干网络,实现见 resnet.py,在 COCO 等数据集上的 top-down 热力图配置可直接参考 configs/body/2d_kpt_sview_rgb_img/topdown_heatmap/coco 下的 resnet*_coco_*.py 系列配置;
  • HRNet:高分辨率网络,实现见 hrnet.py,全程保持高分辨率特征,关键点定位精度更高;
  • HigherHRNet:HRNet 的 bottom-up 变体,适合多人场景的自底向上关键点检测。

需要说明的是,"支持导出"并不等同于"导出后能在任意目标框架中完美运行"。仓库 FAQ(faq.md)中明确指出:目前只能保证 MMPose 训练出的模型与 ONNX 兼容,但 ONNX 中的某些算子可能在目标部署框架(例如 TensorRT)中不受支持。只要 pytorch2onnx.py 能正常完成导出且通过数值验证,遇到这类问题时应向社区提交 issue 寻求帮助。

此外,从源码结构看,由于导出脚本依赖各检测器实现的 forward_dummy 接口(见下文第四节),仓库中实现该接口的检测器包括 top_down.py、associative_embedding.py、mesh.py、pose_lifter.py 等,可以推断:除官方列出的三类主干外,其他搭配这些检测器的模型也具备导出潜力,但以官方文档列出的 ResNet、HRNet、HigherHRNet 为最稳妥的选择。

二、准备工作:安装 ONNX 运行时依赖

导出脚本依赖两个 Python 包,且导出后必须用它们完成验证:

pip install onnx onnxruntime
  • onnx:用于模型文件本身的加载与结构检查(onnx.checker.check_model);
  • onnxruntime:用于实例化推理会话(rt.InferenceSession),以运行 ONNX 模型并与 PyTorch 输出做数值比对。

从源码 pytorch2onnx.py 可以看到,脚本在模块导入阶段就会强制检查这两个包:

try:
    import onnx
    import onnxruntime as rt
except ImportError as e:
    raise ImportError(f'Please install onnx and onnxruntime first. {e}')

若未安装,脚本会直接以 Please install onnx and onnxruntime first 报错退出,不会进入导出流程。另外脚本还会尝试导入 mmcv.onnx.symbolic.register_extra_symbolics,如果当前 mmcv 版本低于 1.0.4,会提示 please update mmcv to version>=1.0.4,因此请确保 mmcv 版本满足要求。

三、导出命令与全部参数详解

仓库提供了一行式导出脚本 tools/deployment/pytorch2onnx.py,用法如下:

python tools/deployment/pytorch2onnx.py ${CONFIG_FILE} ${CHECKPOINT_FILE} [--shape ${SHAPE}] \
    [--verify] [--show] [--output-file ${OUTPUT_FILE}] [--opset-version ${VERSION}]

其中 ${CONFIG_FILE} 为模型的测试配置文件路径,${CHECKPOINT_FILE} 为训练得到的 PyTorch 权重文件路径,二者均为必填位置参数。

3.1 可选参数一览

参数 作用 默认值
--shape 模型输入张量的形状(batch channel height width) 1 3 256 192
--verify 是否验证导出模型:检查可运行性以及数值正确性 False(不传即不验证)
--show 是否打印导出模型的结构(ONNX 图) False
--output-file 导出的 ONNX 模型文件名 tmp.onnx
--opset-version ONNX 算子集(opset)版本,推荐使用较高版本(如 11)以保证兼容性 11

3.2 参数在源码中的具体实现

上述参数与 pytorch2onnx.py 中的 parse_args 一一对应,其中几个关键实现细节值得注意:

  • --shape:类型为 int,通过 nargs='+' 接收多个整数,默认值为 <a href="https://link.gitcode.com/i/d0a04dda5212baed832fa4a654fad84a" target="_blank">1, 3, 256, 192]。对于 2D 关键点检测模型(如 HRNet),输入形状应满足 $batch $channel $height $width,例如 1 3 256 192 表示 batch=1、RGB 三通道、高 256、宽 192,这与仓库中大量 COCO 配置的 image_size=[192, 256](宽×高)正好对应,例如 [ViTPose_base_coco_256x192.py 中 data_cfg 的 image_size=[192, 256]。若使用 384x288 等更高分辨率配置,则需同步改为 1 3 384 288。
  • --opset-version:类型为 int,默认 11。值得注意的是,脚本主流程中有硬性断言 assert args.opset_version == 11, 'MMPose only supports opset 11 now'(见 pytorch2onnx.py),即当前版本实际只支持 opset 11,即使传入其他值也会报错退出。这一点与文档中"推荐使用高版本如 11 以确保稳定性"的描述一致——11 就是当前代码支持的版本上限。
  • --verify 与 --show:均为 action='store_true' 的开关参数,不带值,出现即为 True。

3.3 与官方工具文档中的用法呼应

仓库的 useful_tools.md 也收录了这条导出命令,并给出了带验证的推荐写法:

python tools/deployment/pytorch2onnx.py $CONFIG_PATH $CHECKPOINT_PATH --shape $SHAPE --verify

同时该文档将模型转换标记为 experimental(实验性)功能,且 changelog.md 记录了这一系列部署工具已加入弃用提示,社区统一迁移方向为 OpenMMLab 的 MMDeploy 部署工具箱。对于本文面向的"将模型导出为 ONNX 文件"这一核心需求,pytorch2onnx.py 依然是最直接可用的官方脚本。

四、导出流程的底层原理:从模型加载到数值验证

pytorch2onnx.py 的 main 流程(pytorch2onnx.py)可以拆解为四个阶段,理解每一阶段有助于排查导出失败问题。

4.1 模型加载:init_pose_model

脚本通过 mmpose.apis 中的 init_pose_model 加载模型:解析配置构建姿态模型(build_posenet),加载 checkpoint 权重,并切换到 eval() 模式。导出时传入 device='cpu',因此权重会被加载到 CPU 上,保证导出过程不依赖 GPU 环境。

4.2 BatchNorm 兼容处理:_convert_batchnorm

导出的第一步是调用 _convert_batchnorm,将模型中的 torch.nn.SyncBatchNorm(同步批归一化,多卡训练时常用)递归替换为普通 torch.nn.BatchNorm3d,并逐项拷贝 weight、bias、running_mean、running_var、num_batches_tracked 等参数与统计量。这是 PyTorch 模型转 ONNX 时的经典兼容性问题——ONNX 导出对 SyncBN 的支持不完整,必须先降级为标准 BN 才能顺利导出。对应地,仓库测试 test_onnx.py 用一个包含 Conv3d + SyncBatchNorm 的 DummyModel 专门验证了这一转换与导出链路。

4.3 计算图替换:forward_dummy

torch.onnx.export 不支持 kwargs 形式的输入,而姿态检测器的常规 forward 需要接收 img 和 img_metas 等元信息。因此脚本会检查模型是否实现了 forward_dummy,若有则用其替换 forward(pytorch2onnx.py),否则抛出 NotImplementedError。

以 top-down 检测器为例,top_down.py 中的 forward_dummy 只接收一张图像张量,依次经过 backbone → neck → keypoint_head 直接输出热力图,剔除了 flip test、解码、可视化等推理后处理逻辑,恰好构成一个干净的、可导出为 ONNX 的"前向计算图"。这种只保留主干推理路径的设计,也正是该接口 docstring 中所说的"用于计算网络 FLOPs"(见 tools/analysis/get_flops.py 的用途)——同一个 dummy 接口同时服务于 FLOPs 统计与 ONNX 导出,是复用设计的典型体现。

4.4 导出与双重验证

核心导出调用 pytorch2onnx 完成以下工作:

  1. 导出:model.cpu().eval() 后用随机张量 torch.randn(input_shape) 作为示例输入,调用 torch.onnx.export,设置 export_params=True、keep_initializers_as_inputs=True、verbose=show、opset_version=opset_version,生成 ONNX 文件并打印 Successfully exported ONNX model: {output_file};
  2. 结构验证(--verify 时):用 onnx.load 加载文件、onnx.checker.check_model 检查模型结构合法性;
  3. 数值验证(--verify 时):分别用 PyTorch 模型和 ONNX Runtime 会话(rt.InferenceSession)以同一输入前向一次,通过 np.allclose(..., atol=1.e-5) 逐张量比对输出,任一输出不一致即断言失败并提示 The outputs are different between Pytorch and ONNX;全部一致则打印 The numerical values are same between Pytorch and ONNX。

验证环节之所以必要,是因为导出的 ONNX 图可能因算子映射差异产生微小精度偏差甚至结构性错误。官方以 1e-5 的绝对容差作为"导出无损"的判定标准,这个阈值也可以作为你排查精度损失问题的参考基线。

五、端到端导出示例(以 ViTPose COCO 配置为例)

结合仓库实际配置,给出一个完整的导出命令示例。假设已训练完成 ViTPose-Base 在 COCO 上的模型,配置与权重文件路径如下:

python tools/deployment/pytorch2onnx.py \
    configs/body/2d_kpt_sview_rgb_img/topdown_heatmap/coco/ViTPose_base_coco_256x192.py \
    /path/to/vitpose_base_coco_256x192.pth \
    --shape 1 3 256 192 \
    --verify \
    --show \
    --output-file vitpose_base_coco_256x192.onnx \
    --opset-version 11

各参数效果:

  • --shape 1 3 256 192:显式指定输入形状,与配置中 image_size=[192, 256]、heatmap_size=[48, 64] 的数据管线对应(注意 shape 的书写顺序是 height width,与配置中 image_size 的 width height 相反,这是新手最容易踩的坑);
  • --verify:导出后立即执行结构检查与数值比对,确认无精度损失;
  • --show:在导出过程中打印完整 ONNX 计算图结构(等价于 torch.onnx.export(..., verbose=True));
  • --output-file:指定输出文件名,避免覆盖默认的 tmp.onnx;
  • --opset-version 11:当前代码唯一支持的版本,显式写出更清晰。

若执行成功,控制台将依次看到 Successfully exported ONNX model: vitpose_base_coco_256x192.onnx 与(开启 --verify 时)The numerical values are same between Pytorch and ONNX。

六、常见问题与注意事项

6.1 导出报 "Please install onnx and onnxruntime first"

未安装依赖,或安装的 onnxruntime 与当前 Python 环境不兼容。执行 pip install onnx onnxruntime 后重试。

6.2 报 "please update mmcv to version>=1.0.4"

当前 mmcv 版本过低,缺少 mmcv.onnx.symbolic.register_extra_symbolics(用于注册 ONNX 导出所需的额外符号化算子)。升级 mmcv 至 1.0.4 及以上版本。

6.3 报 NotImplementedError / 提示实现 forward_dummy

所选检测器未实现 forward_dummy 接口。如前文所述,仓库中 TopDown、AssociativeEmbedding、Mesh 等主要检测器均已实现;若自定义了检测器,需自行补充该接口才能导出。

6.4 opset 版本传入非 11 报错

MMPose only supports opset 11 now 是脚本的硬性断言,当前版本请固定使用 --opset-version 11。

6.5 导出成功但数值不一致

The outputs are different between Pytorch and ONNX 意味着某些算子存在数值精度偏差。建议先确认是否开启了 --verify 之外的额外后处理(如 flip test 被误带入计算图),并将问题连同配置、checkpoint 一起提交 issue。

6.6 目标框架(如 TensorRT)加载报错

如第一节所述,ONNX 兼容不代表目标部署框架兼容,某些 ONNX 算子在 TensorRT 等框架中可能不受支持。只要 pytorch2onnx.py 导出并通过数值验证,此类问题应反馈到社区 issue 寻求协助(参考 faq.md)。

6.7 脚本的弃用状态

自 changelog.md 记录起,pytorch2onnx.py 已带有 DeprecationWarning,官方建议新项目迁移至 OpenMMLab 统一的 MMDeploy 部署工具箱。但对"快速把 MMPose/ViTPose 模型转成单文件 ONNX"这一场景,该脚本仍是一个零配置、开箱即用的选择;如需更完整的部署链路(如 TensorRT 后端、量化、服务化),可关注 MMDeploy 相关方案。

七、验证测试:仓库如何保证导出质量

仓库通过 tests/test_onnx.py 提供了自动化回归测试,验证导出链路的可靠性:

  • 测试构造了一个包含 Conv3d 和 SyncBatchNorm 的 DummyModel;
  • 依次调用 _convert_batchnorm 与 pytorch2onnx,在临时目录中完成一次完整导出;
  • 若导出抛出任何异常,测试即失败,从而守护后续对导出流程的改动不破坏基本功能。

这套测试与 tools/deployment/pytorch2onnx.py 共同构成了"导出脚本 + 数值验证 + 回归测试"的完整质量闭环,你在复现导出流程时也可以参考该测试的调用方式(直接 import _convert_batchnorm 和 pytorch2onnx 函数)编写自己的批量导出工具。

八、总结

本文完整梳理了 ViTPose/MMPose 仓库中将 PyTorch 姿态模型导出为 ONNX 的官方流程:支持的模型范围(ResNet、HRNet、HigherHRNet)、环境准备(pip install onnx onnxruntime,mmcv≥1.0.4)、pytorch2onnx.py 的全部参数与默认值、导出背后的四阶段原理(模型加载、SyncBN 转换、forward_dummy 图替换、结构与数值双重验证),以及基于仓库真实配置的端到端示例。核心要点可概括为三句话:

  1. 命令一行:python tools/deployment/pytorch2onnx.py ${CONFIG} ${CHECKPOINT} --shape 1 3 256 192 --verify;
  2. 验证必开:--verify 以 1e-5 容差保证 PyTorch 与 ONNX 输出一致,是部署安全性的最后防线;
  3. opset 固定为 11:当前代码仅支持 opset 11,无需也不应传入其他版本。

完成导出后,你可以将 ONNX 文件交由 ONNX Runtime、TensorRT 等推理引擎加载,或结合 top_down_img_demo.py 等 demo 脚本对比原始 PyTorch 推理与 ONNX 推理的结果,进一步确认部署链路的一致性。

登录后查看全文
ViTPose