PaddlePaddle PP-YOLOE 模型中心使用指南：下载、训练、推理与部署全流程

本文基于 PaddlePaddle 官方模型中心（modelcenter）中 PP-YOLOE 目标检测模型的文档与配套代码（下载说明、Benchmark、FastDeploy 部署说明、使用教程）整理而成，并补充了仓库内 APP 目录下推理应用的源码级实现细节。你将掌握 PP-YOLOE 系列模型的模型库构成与权重下载方式、训练与导出的完整命令、Paddle Inference / TensorRT / FastDeploy 三种部署路径，以及模型中心内基于 Gradio 的本地推理应用的运行原理，可直接在实战中复现或按需改造。

PP-YOLOE 是百度飞桨 PaddlePaddle 团队推出的单阶段 Anchor-free 目标检测模型，基于 PP-YOLOv2 演进而来。其技术报告为《PP-YOLOE: An evolved version of YOLO》（arXiv:2203.16250），在 COCO 数据集上具备优异的精度-速度权衡，同时避免使用 Deformable Convolution、Matrix NMS 等特殊算子，从而可以轻松部署在多种多样的硬件上。

1. 模型库构成与下载

下载说明给出了官方维护的 4 个规格权重及其骨干网络，全部基于 COCO 数据集训练 300 epoch：

模型	骨干网络	模型下载	配置文件
PP-YOLOE-s	cspresnet-s	model	config
PP-YOLOE-m	cspresnet-m	model	config
PP-YOLOE-l	cspresnet-l	model	config
PP-YOLOE-x	cspresnet-x	model	config

s / m / l / x 四个规格通过 depth multiplier 和 width multiplier 配置缩放模型容量，训练与推理命令中以配置文件区分。模型元信息可在 info.yaml 中查看：来源为 PaddleDetection，任务为计算机视觉（Computer Vision）下的目标检测（Object Detection），许可协议为 Apache 2.0，训练数据集包括 COCO train2017 / val2017 / test-dev2017 与 Pascal VOC。

2. 模型精度与速度 Benchmark

Benchmark 文档记录了四个规格在 COCO 上的精度（Box AP）与 V100 单卡、batch size = 1 的推理速度：

模型	Epoch	GPU 数	每 GPU 图片数	骨干网络	输入尺寸	Box AP(val 0.5:0.95)	Box AP(test 0.5:0.95)	Params(M)	FLOPs(G)	V100 FP32(FPS)	V100 TensorRT FP16(FPS)
PP-YOLOE-s	300	8	32	cspresnet-s	640	43.0	43.2	7.93	17.36	208.3	333.3
PP-YOLOE-m	300	8	28	cspresnet-m	640	49.0	49.1	23.43	49.91	123.4	208.3
PP-YOLOE-l	300	8	20	cspresnet-l	640	51.4	51.6	52.20	110.07	78.1	149.2
PP-YOLOE-x	300	8	16	cspresnet-x	640	52.3	52.4	98.42	206.59	45.0	95.2

使用注意事项（原文档原文要点）：

• PP-YOLOE 使用 COCO train2017 作为训练集，val2017 和 test-dev2017 作为测试集；
• 训练采用 8 张 GPU 混合精度训练。若 GPU 卡数或 batch size 改变，需按公式 lr_new = lr_default * (batch_size_new * GPU_number_new) / (batch_size_default * GPU_number_default) 线性调整学习率；
• 推理速度测试环境为单卡 V100、batch size = 1，CUDA 10.2、CUDNN 7.6.5；TensorRT 推理速度测试使用 TensorRT 6.0.1.8；
• 若设置 --run_benchmark=True，需先安装依赖 pip install pynvml psutil GPUtil。

3. 模型原理简介

根据 使用教程 第 4 节，PP-YOLOE 由以下方法组成：

• 可扩展的 backbone 和 neck（CSPResNet + CSPRepResStage）；
• Task Alignment Learning（任务对齐学习，源自 arXiv:2108.07755），用于对齐分类与回归分支的预测；
• 带 DFL（Distribution Focal Loss，arXiv:2006.04388）和 VFL（Varifocal Loss，arXiv:2008.13367）的高效 Task-aligned head；
• SiLU(Swish) 激活函数（arXiv:1710.05941）。

正是由于避免使用 Deformable Convolution 与 Matrix NMS 等特殊算子，PP-YOLOE 才能兼容 TensorRT、FastDeploy 及各类 AI 加速硬件的常规算子实现。

4. 训练与模型导出（PaddleDetection 方式）

4.1 环境准备

在使用教程（notebook 形式）中，按以下步骤准备环境（默认运行在 AI Studio Jupyter 上；若运行在终端，去掉行首的 % 或 !）：

# 克隆 PaddleDetection 仓库
mkdir -p ~/work
cd ~/work/
git clone https://github.com/PaddlePaddle/PaddleDetection.git

# 安装依赖
cd PaddleDetection
mkdir -p demo_input demo_output
pip install -r requirements.txt

数据集存放在 dataset/coco/ 目录下。

4.2 单卡 / 多卡训练

# 单卡训练（l 规格示例）
python tools/train.py -c configs/ppyoloe/ppyoloe_crn_l_300e_coco.yml --eval --amp

# 多卡训练（8 卡示例）
python -m paddle.distributed.launch --gpus 0,1,2,3,4,5,6,7 tools/train.py -c configs/ppyoloe/ppyoloe_crn_l_300e_coco.yml --eval --amp

注意：

• 需要边训练边评估时添加 --eval；
• PP-YOLOE 支持混合精度训练，请添加 --amp；
• 修改 GPU 卡数或 batch size 时，按第 2 节的公式同步调整学习率。

4.3 导出推理模型

使用 Paddle-TRT 部署时（TensorRT FP16），先参考 Paddle Inference 官方文档，下载安装与自身 CUDA、CUDNN、TensorRT 匹配的 wheel 包，然后导出：

python tools/export_model.py -c configs/ppyoloe/ppyoloe_crn_l_300e_coco.yml -o weights=https://paddledet.bj.bcebos.com/models/ppyoloe_crn_l_300e_coco.pdparams trt=True

直接使用 PaddleInference 部署时，导出命令去掉 trt=True 即可：

python tools/export_model.py -c configs/ppyoloe/ppyoloe_crn_l_300e_coco.yml -o weights=https://paddledet.bj.bcebos.com/models/ppyoloe_crn_l_300e_coco.pdparams

5. 推理部署：Paddle Inference 与 TensorRT

5.1 TensorRT FP16 推理

# 下载测试图片
wget -P demo_input -N https://paddledet.bj.bcebos.com/modelcenter/images/General/000000014439.jpg

# TensorRT FP16 推理单张图片
CUDA_VISIBLE_DEVICES=0 python deploy/python/infer.py --model_dir=output_inference/ppyoloe_crn_l_300e_coco --image_file=demo_input/000000014439.jpg --device=gpu --run_mode=trt_fp16 --output_dir=demo_output

5.2 Paddle Inference 推理

# 直接使用 PaddleInference 推理单张图片
CUDA_VISIBLE_DEVICES=0 python deploy/python/infer.py --model_dir=output_inference/ppyoloe_crn_l_300e_coco --image_file=demo_input/000000014439.jpg --device=gpu --run_mode=paddle --output_dir=demo_output

注意事项（原文档要点）：

• TensorRT 会依据网络定义针对当前硬件平台执行优化，生成并序列化推理引擎，该引擎仅适用于当前软硬件平台；若平台不变，可设置 enable_tensorrt_engine 参数 use_static=True，序列化文件保存在 output_inference 目录下，下次推理时直接加载；
• PaddleDetection release/2.4 及之后版本支持 NMS 调用 TensorRT，需要依赖 PaddlePaddle release/2.3 及之后版本。

6. 快速部署：FastDeploy 全场景方案

FastDeploy 部署说明 提供了更简单的云边端一体化部署方式，三步即可完成：安装预编译包 → 调用 API 写部署代码 → 推理部署。

1. 安装 FastDeploy 预编译包

pip install fastdeploy-gpu-python==0.0.0 -f https://www.paddlepaddle.org.cn/whl/fastdeploy_nightly_build.html

2. 运行部署示例

# 下载部署示例代码
git clone https://github.com/PaddlePaddle/FastDeploy.git
cd FastDeploy/examples/vision/detection/paddledetection/python/

# 下载 PP-YOLOE 模型文件和测试图片
wget https://bj.bcebos.com/paddlehub/fastdeploy/ppyoloe_crn_l_300e_coco.tgz
wget https://gitee.com/paddlepaddle/PaddleDetection/raw/release/2.4/demo/000000014439.jpg
tar xvf ppyoloe_crn_l_300e_coco.tgz

# CPU 推理
python infer_ppyoloe.py --model_dir ppyoloe_crn_l_300e_coco --image 000000014439.jpg --device cpu
# GPU 推理
python infer_ppyoloe.py --model_dir ppyoloe_crn_l_300e_coco --image 000000014439.jpg --device gpu
# GPU 上使用 TensorRT 推理（首次运行需序列化模型，有一定耗时，请耐心等待）
python infer_ppyoloe.py --model_dir ppyoloe_crn_l_300e_coco --image 000000014439.jpg --device gpu --use_trt True

FastDeploy 支持 X86 CPU、NVIDIA GPU、ARM CPU、XPU、NPU、IPU 等 10 类云边端硬件，通过一行代码即可切换推理后端和硬件。原文档仅展示 X86 CPU、NVIDIA GPU 推理，且默认已准备好 GPU 环境（如 CUDA >= 11.2 等）。

7. 模型中心的 Gradio 推理应用（源码级拆解）

本仓库 modelcenter/PP-YOLOE/APP 目录提供了一套可直接运行的 PP-YOLOE 推理应用，其结构为：

APP/
├── app.py                 # Gradio 前端入口
├── app.yml                # 应用部署元信息（Gradio SDK 配置）
├── requirements.txt       # 运行依赖
├── configs/
│   └── PP-YOLOE.yml       # 推理配置：预处理、标签、模型路径等
└── src/
    ├── detection.py       # 检测器封装：Paddle Inference 推理主体
    ├── download.py        # 权重按需下载与缓存
    ├── preprocess.py      # 预处理算子：Resize / NormalizeImage / Permute 等
    └── visualize.py       # 检测结果可视化绘制

7.1 推理配置解析

PP-YOLOE.yml 是推理核心配置，各字段含义如下：

字段	值	说明
mode	paddle	运行模式，可选 paddle / trt_int8 / trt_fp32 / trt_fp16
draw_threshold	0.5	可视化绘制阈值，仅显示置信度高于该值的框
metric	COCO	评测指标
use_dynamic_shape	false	是否使用 TensorRT 动态输入 shape
arch	YOLO	模型架构类型
min_subgraph_size	3	TensorRT 引擎最小子图大小
param_path / model_path	paddlecv://models/ppyoloe_crn_s_300e_coco/model.pdiparams / model.pdmodel	权重与网络文件，paddlecv:// 前缀表示按需自动下载
Preprocess	列表	预处理算子流水线，按顺序执行

预处理流水线（对应 preprocess.py 中的算子实现）：

1. Resize：target_size=[640, 640]、keep_ratio=false、interp=2（cv2.INTER_LINEAR），将图像缩放到固定 640×640，同时更新 im_shape 与 scale_factor；
2. NormalizeImage：is_scale=true（先除以 255），再按 mean=[0.485, 0.456, 0.406]、std=[0.229, 0.224, 0.225] 做标准化；
3. Permute：将 HWC 排列转置为 CHW，供 Paddle 模型输入。

label_list 为 COCO 80 类目标名称列表，与下载权重的训练标签一一对应。

7.2 推理主体：Detector 封装

detection.py 中的 Detector 类基于 Paddle Inference Python API（paddle.inference.Config / create_predictor）实现：

• 模型加载：读取配置中的 model_path / param_path（paddlecv:// 前缀由 download.py 解析为 https://bj.bcebos.com/v1/paddle-model-ecology/paddlecv/ 真实下载地址），通过 Config(infer_model, infer_params) 构造推理配置；
• 设备选择：device 为 CPU 时 disable_gpu() 并设置 CPU 线程数 cpu_threads（默认 1）；为 GPU 时 enable_use_gpu(200, 0) 并开启图优化 switch_ir_optim(True)；
• TensorRT 支持：run_mode 为 trt_int8 / trt_fp32 / trt_fp16 时，通过 enable_tensorrt_engine 启用 TensorRT，并依据 use_dynamic_shape 设置动态 shape（输入 image 从 640×640 到 1280×1280，优化 shape 1024×1024）；
• 性能优化开关：disable_glog_info() 关闭预测日志、enable_memory_optim() 开启共享内存、switch_use_feed_fetch_ops(False) 关闭 feed/fetch OP（配合 zero_copy 输入）；
• 输入组装：create_inputs 堆叠 im_shape、scale_factor、image 三个输入张量；
• 后处理：从输出句柄读取 boxes 与 boxes_num，按 draw_threshold 过滤低置信度框（np_boxes[:, 1] > draw_threshold 且 np_boxes[:, 0] > -1），最终返回 {'bboxes': np_boxes.tolist()} 与绘制后的图像。

7.3 权重按需下载机制

download.py 实现了模型的“首次运行时按需下载 + 本地缓存”机制：

• 缓存目录：权重缓存在 ~/.cache/paddlecv/models，配置缓存在 ~/.cache/paddlecv/configs，字典缓存在 ~/.cache/paddlecv/dicts；
• paddlecv:// 协议：parse_url 将 paddlecv:// 替换为 https://bj.bcebos.com/v1/paddle-model-ecology/paddlecv/；
• 断点续传：下载先写入 _tmp 临时文件，完成后 shutil.move 重命名为正式文件，防止中断导致文件损坏；
• 完整性校验：对 pdparams 类模型文件，通过请求头 content-md5 做 MD5 校验（_md5check_from_url）；
• 失败重试：DOWNLOAD_RETRY_LIMIT = 3，超过重试上限抛出 RuntimeError。

7.4 可视化绘制

visualize.py 中的 draw_det 使用 PIL 在图像上绘制检测框与标签：

• 通过位运算为每个类别生成稳定的 RGB 颜色（get_color_map_list）；
• 线宽按图像尺寸自适应（min(im.size) // 320）；
• 每个检测框左上角绘制 类别名 + 置信度 的实心标签，如 person 0.9821。

7.5 Gradio 前端与应用配置

app.py 使用 Gradio Blocks 构建交互界面，输入图片 → Detector('PP-YOLOE')(image) 推理 → 输出带框图像与 JSON 检测结果（含 Clear / Submit 按钮）。app.yml 声明应用元信息：SDK 为 Gradio 3.9.1、app_file: app.py、许可证 Apache-2.0、CPU 设备。requirements.txt 列出的运行依赖包括 gradio、opencv-python、paddlepaddle、PyYAML、shapely、scipy、Cython、numpy、pillow 等。安装依赖后执行 python app.py 即可在本机启动交互式目标检测演示。

8. 实战小结：从下载到部署的完整链路

综合本仓库 PP-YOLOE 模型中心各文档与 APP 源码，一条完整的落地链路为：

1. 选型：根据精度/速度需求从模型库表中选择 s/m/l/x 规格（参考 Benchmark 表格权衡）；
2. 获取权重：直接从表格中下载 .pdparams 权重，或使用 paddlecv:// 协议在推理时自动下载并缓存；
3. 训练（可选）：在 PaddleDetection 中按第 4 节命令训练并导出推理模型；
4. 推理部署：按需选择 Paddle Inference（--run_mode=paddle）、TensorRT（trt_fp16 等）或 FastDeploy 三种路径；
5. 交互演示：使用模型中心 APP 的 Gradio 应用快速体验检测效果，并可直接参考其 PP-YOLOE.yml 配置与 detection.py 源码理解预处理、推理与后处理的完整实现，便于迁移到自己的项目中。

相关引用（PP-YOLOE 技术报告 BibTeX）：

@article{xu2022pp,
  title={PP-YOLOE: An evolved version of YOLO},
  author={Xu, Shangliang and Wang, Xinxin and Lv, Wenyu and Chang, Qinyao and Cui, Cheng and Deng, Kaipeng and Wang, Guanzhong and Dang, Qingqing and Wei, Shengyu and Du, Yuning and others},
  journal={arXiv preprint arXiv:2203.16250},
  year={2022}
}