PaddleDetection 模型导出(动转静)完整指南:从权重到可部署推理模型
PaddleDetection 模型导出(动转静)完整指南:从权重到可部署推理模型
本文是 PaddleDetection 模型导出教程的中文深度解读,围绕仓库 tools/export_model.py 的动转静导出流程展开,完整覆盖导出模型的输入/输出约定、启动参数、YOLOv3 导出实例、输入尺寸设置以及导出配置项(infer_cfg.yml、export.post_process 等)的底层实现。读完本文,你将能够把训练得到的 .pdparams 权重一键转换为 model.pdmodel + model.pdiparams + infer_cfg.yml 的标准推理产物,并正确设置导出模型的输入形状,为 Python 预测、TensorRT、Serving 等下游部署环节铺平道路。
一、模型导出是什么:动转静与部署产物的关系
PaddleDetection 的模型导出是指通过 PaddlePaddle 的**动转静(Dynamic-to-Static)**机制,将基于动态图训练得到的网络结构固化(paddle.jit.to_static / paddle.jit.save)为可供预测引擎加载的静态图模型。这一步是训练与部署之间的桥梁:训练阶段产出的是 model_final.pdparams 权重文件,而部署阶段需要的是包含完整网络结构、输入输出规格和推理配置的静态图模型。
从源码看,导出的核心入口在 ppdet/engine/trainer.py 的 Trainer.export() 方法,整体流程为:
- 将模型切换为
eval()模式并深拷贝,避免影响原始训练状态; - 依据配置文件名确定模型名
model_name,默认输出到{output_dir}/{model_name}/目录; - 通过
_get_infer_cfg_and_input_spec生成输入规格(InputSpec)并落盘infer_cfg.yml; - 执行动转静(
paddle.jit.save),产出model.pdmodel(网络结构)与model.pdiparams(参数)。
python tools/export_model.py -c 配置文件.yml -o weights=权重路径.pdparams
适用范围:检测、实例分割、多目标跟踪(如 DeepSORT、ByteTrack 会在导出时走 load_weights_sde 同时加载检测与 ReID 权重)以及关键点检测等 PaddleDetection 支持的全部架构;半监督 ARSL 方法则由 ppdet/engine/trainer_ssod.py 中的 Trainer_ARSL 负责导出。
二、导出模型的输入与输出约定
2.1 输入变量与输入形状
PaddleDetection 统一约定的模型输入为三个张量,含义如下:
| 输入名称 | 输入形状 | 表示含义 |
|---|---|---|
image |
[None, 3, H, W] |
输入网络的图像,None 表示 batch 维度;若输入图像为变长(动态 shape),则 H、W 为 None |
im_shape |
[None, 2] |
图像经过 resize 后的大小,表示为 H, W,None 表示 batch 维度 |
scale_factor |
[None, 2] |
输入图像尺寸与真实图像尺寸的缩放比例,表示为 scale_y, scale_x |
其中 im_shape 与 scale_factor 用于在推理后处理阶段将模型输出坐标还原回原图坐标系(例如 NMS 之后的框坐标从 resize 后尺寸映射到原始尺寸)。
注意:具体的预处理方式(包括归一化均值/方差、resize 方式等)请参考配置文件中 TestReader 部分,例如 YOLOv3 的预处理定义在 configs/yolov3/base/yolov3_reader.yml(Resize 到 [608, 608]、NormalizeImage 等),导出后的推理阶段会依据 infer_cfg.yml 中的预处理信息对输入图片做同样处理。
2.2 输出约定(统一输出格式)
动转静导出后的模型输出统一为:
bbox:NMS 的输出,形状为[N, 6],其中N为预测框的个数,6 个维度为[class_id, score, x1, y1, x2, y2];bbox_num:每张图片对应的预测框个数。例如 batch_size 为 2 时输出为[N1, N2],表示第一张图包含N1个预测框、第二张图包含N2个预测框,且预测框总个数与 NMS 输出第一维N相同(N1 + N2 = N);mask:如果网络中包含 mask 分支(如 Mask R-CNN、SOLOv2、PP-YOLOE-seg 等实例分割模型),则会额外输出 mask 分支结果。
重要限制:模型动转静导出不支持模型结构中包含 numpy 相关操作的情况。如果你的自定义模型在 forward 中混用了 numpy 运算,需要先改写成纯 Paddle 算子,否则导出会失败。
三、导出入口与启动参数详解
导出脚本 tools/export_model.py 的参数定义位于 parse_args()(tools/export_model.py),在文档给出的 -c 与 --output_dir 之外,源码中还注册了若干实用参数:
| FLAG | 用途 | 默认值 | 备注 |
|---|---|---|---|
-c |
指定配置文件(必填) | None |
传入 configs/ 下的模型 YAML 配置 |
--output_dir |
模型保存路径 | ./output_inference |
模型默认保存在 output/配置文件名/ 路径下({output_dir}/{model_name}/) |
--export_serving_model |
是否同时导出 Paddle Serving 模型 | False |
置 True 时会额外生成 serving_server / serving_client 目录 |
--slim_config |
裁剪/量化等瘦身方法的配置文件 | None |
与 ppdet/slim 配合使用(如 QAT 量化导出) |
--for_fd |
是否以 FastDeploy 约定格式导出 | False |
置 True 时保存为 inference.pdmodel 与 inference.yml |
-o |
覆盖配置文件中的任意字段 | 无 | 通过 key=value 形式传入,如 -o weights=... |
其中 -o 参数非常关键:导出时通常用它指定待导出的权重路径(例如 -o weights=weights/yolov3_darknet53_270e_coco.pdparams),也可以用它直接覆盖 TestReader.inputs_def.image_shape 等配置项(见第五节)。
配置文件的加载与覆盖由 ppdet/core/workspace.py 的 load_config / merge_config 完成:load_config 会递归解析 YAML 中的 _BASE_ 继承字段(例如 configs/yolov3/yolov3_darknet53_270e_coco.yml 继承自 datasets、runtime 与 _base_ 子配置),merge_config 负责将 -o 传入的键值合并进全局配置。
四、导出实例:以 YOLOv3 为例
使用训练得到的模型进行导出,脚本如下:
# 导出 YOLOv3 模型
python tools/export_model.py -c configs/yolov3/yolov3_darknet53_270e_coco.yml --output_dir=./inference_model \
-o weights=weights/yolov3_darknet53_270e_coco.pdparams
执行完成后,预测模型会导出到 inference_model/yolov3_darknet53_270e_coco 目录下,共包含 4 个文件:
| 文件 | 作用 |
|---|---|
infer_cfg.yml |
推理配置文件(模式、指标、动态 shape 标志、后处理/TRT 相关信息等) |
model.pdmodel |
静态图网络结构文件 |
model.pdiparams |
模型参数文件 |
model.pdiparams.info |
参数信息描述文件 |
其中目录名 yolov3_darknet53_270e_coco 正是由配置文件名推断而来(见 ppdet/engine/trainer.py 中 model_name = os.path.splitext(os.path.split(self.cfg.filename)[-1])[0]),导出的日志会输出 Export model and saved in ... 提示保存路径。
4.1 infer_cfg.yml 是怎么生成的
infer_cfg.yml 由 ppdet/engine/export_utils.py 的 _dump_infer_config 生成,包含以下关键字段:
mode:固定为paddle;draw_threshold:可视化阈值,默认0.5;metric:从训练配置继承(如COCO);use_dynamic_shape:根据image_shape[2]是否为-1判定,用于告知推理端是否启用动态 shape;arch与min_subgraph_size:TensorRT 子图切分相关的架构标记(PPYOLOE、YOLOX、YOLOF、S2ANet 等架构均有对应配置);mask:当架构包含 mask 分支(如mask_head或with_mask为真)时置为True。
4.2 导出后的 Python 推理验证
导出产物可直接由 deploy/python/infer.py 加载推理(参数定义见 deploy/python/utils.py):
python deploy/python/infer.py --model_dir=./inference_model/yolov3_darknet53_270e_coco \
--image_file=demo/000000014439.jpg --device=GPU
推理端会读取 infer_cfg.yml 自动匹配预处理与后处理方式;--device 支持 CPU/GPU/XPU/NPU/MLU,配合 --run_mode(paddle/trt_fp32/trt_fp16/trt_int8)以及 --trt_min_shape/--trt_max_shape/--trt_opt_shape 可切换 TensorRT 动态 shape 推理。
五、设置导出模型的输入大小
5.1 为什么需要设置输入尺寸
使用 TensorRT 进行预测时,由于 ≤ TensorRT 5.1 的版本仅支持定长输入,保存模型的 data 层图片尺寸必须与实际输入图片尺寸一致;而 Fluid C++ 预测引擎没有此限制。因此需要显式设置导出模型的输入尺寸。
5.2 通过 TestReader.inputs_def.image_shape 设置
设置 TestReader 中的 image_shape 可以修改保存模型中的输入图片大小。示例如下:
# 导出 YOLOv3 模型,输入是 3x640x640
python tools/export_model.py -c configs/yolov3/yolov3_darknet53_270e_coco.yml --output_dir=./inference_model \
-o weights=weights/yolov3_darknet53_270e_coco.pdparams TestReader.inputs_def.image_shape=[3,640,640]
这里 image_shape=<a href="https://link.gitcode.com/i/1c3baad9228cc9ce6962e6be54560bca" target="_blank">3, 640, 640] 的含义是 [C, H, W](channel、高、宽),不含 batch 维度。YOLOv3 默认配置中该值为 [3, 608, 608](见 [configs/yolov3/base/yolov3_reader.yml)。
5.3 底层 shape 处理逻辑
从源码看,输入规格的组装发生在 ppdet/engine/trainer.py 的 _get_infer_cfg_and_input_spec 中:
- 若未显式设置
image_shape,默认取[None, 3, -1, -1],即默认导出为动态 shape 模型(-1表示可变长); - 若传入的
image_shape长度为 3(如[3, 640, 640]),会自动在头部补上 batch 维度变为[None, 3, 640, 640],此时im_shape与scale_factor保持[None, 2]; - 若传入的
image_shape长度为 4(如[1, 3, 640, 640]),则im_shape与scale_factor会跟随 batch 维度([image_shape[0], 2]); - 当配置了
export.post_process=True且非 benchmark 模式时,image_shape的H、W会被置为None,保证后处理内嵌模型支持动态输入。
同时,导出过程还会做以下模型优化:
- 算子融合:当配置
export.fuse_conv_bn=True时,调用ppdet/utils/fuse_utils.py中的fuse_conv_bn做 Conv-BN 融合(见 configs/runtime.yml); - 部署模式切换:遍历模型子层调用
convert_to_deploy(),并置model.deploy = True; - 输入规格裁剪:通过 ppdet/engine/export_utils.py 的
_prune_input_spec依据静态图实际输入裁剪InputSpec,去掉未使用的输入(例如 PicoDet 在后处理外置时仅保留image输入)。
5.4 与 export 配置项的配合
模型导出的后处理行为由 configs/runtime.yml 中的 export 段控制:
# Exporting the model
export:
post_process: True # 导出模型时是否将后处理包含进网络
nms: True # 导出模型时是否将 NMS 包含进网络
benchmark: False # 用于测试模型性能;置 True 时不导出后处理与 NMS
fuse_conv_bn: False
post_process=True时,NMS、框解码等后处理会被固化进静态图,推理端拿到的是干净的[N, 6]输出(即第二节的统一输出格式);post_process=False(或benchmark=True)时导出的是纯网络结构,输出为原始预测特征,适合自行实现后处理或在 FastDeploy 中做端到端优化;- MOT 系列架构(JDE、FairMOT、DeepSORT、ByteTrack、CenterTrack)导出时会读取
TestMOTReader而非TestReader,并在infer_cfg.yml中写入 tracker 配置(见 ppdet/engine/export_utils.py)。
六、导出产物如何对接更多部署场景
除默认格式外,tools/export_model.py 还支持两种扩展导出:
- Paddle Serving 导出:加
--export_serving_model=True,会在导出目录下额外生成serving_server与serving_client子目录,供 deploy/serving 使用; - FastDeploy 格式导出:加
--for_fd,模型会保存为inference.pdmodel与inference.yml,可直接对接 deploy/fastdeploy 各平台示例。
此外,导出的静态图模型还可通过 deploy/EXPORT_ONNX_MODEL.md 中介绍的方式进一步转换为 ONNX 格式,用于 OpenVINO、ONNX Runtime、TensorRT 等第三方推理引擎(RCNN 系列架构导出 ONNX 时仅支持 batch_size = 1,相关限制在 _dump_infer_config 中有明确告警)。
七、常见问题与注意事项
- 动转静报错:确认模型 forward 中不含 numpy 运算;若自定义算子不支持动转静,请检查是否使用了 Paddle 官方 API 实现;
- 输入尺寸不匹配:TensorRT 定长模式下,部署时输入图片尺寸必须与导出时设置的
image_shape一致,否则需重新导出;动态 shape 模型则通过trt_min_shape/trt_opt_shape/trt_max_shape指定范围; - 权重路径:
-o weights=...指向.pdparams权重文件;训练产物默认位于output/{配置文件名}/model_final(见 configs/runtime.yml 中save_dir: output); - 多阶段架构:DeepSORT / ByteTrack 导出时需同时提供检测权重与 ReID 权重(
load_weights_sde),注意配置中的det_weights与reid_weights字段; - 半监督模型:ARSL 方法需走
Trainer_ARSL导出路径(ppdet/engine/trainer_ssod.py),脚本会根据配置中的ssod_method自动分发。
通过合理组合 -o 参数覆盖、export 配置项与 --output_dir,你可以为检测、实例分割、跟踪、关键点等各类任务一键产出标准、可复用的部署模型,无缝衔接 Paddle Inference、TensorRT、Serving 与 FastDeploy 等推理链路。