PaddleDetection 全场景高性能部署指南：基于 FastDeploy 的云边端推理实践

• 人工智能
• 深度学习
• 计算机视觉

本指南以 PaddleDetection 仓库 deploy/fastdeploy 下的部署文档为骨架，系统讲解如何借助 FastDeploy 将 PaddleDetection 训练出的检测、实例分割与关键点模型，部署到 X86 CPU、NVIDIA GPU、飞腾/ARM CPU、Intel GPU、昆仑、昇腾、瑞芯微、晶晨、算能等 10 余类硬件上，并覆盖模型导出、Python/C++ 示例、服务化部署、量化部署与常见问题。读完本文，你将掌握一条从"训练好的 PaddleDetection 模型"到"可对外提供推理服务的生产部署链路"的完整实操路径。

1. FastDeploy 是什么：面向 PaddleDetection 的全场景推理部署工具

FastDeploy 是一款面向 AI 推理部署的工具，定位是全场景、易用灵活、极致高效，支持云、边、端三类部署形态。对 PaddleDetection 用户而言，它的核心价值在于：同一套 API 与同一份导出模型，可以在不同硬件上以不同推理后端运行，而无需为每种硬件单独编写推理代码。

从仓库目录结构看，deploy/fastdeploy 下按硬件平台组织了完整示例：

• cpu-gpu/：X86 CPU、NVIDIA GPU、飞腾 CPU、ARM CPU、Intel GPU（集成/独立显卡）的 Python 与 C++ 部署示例；
• kunlunxin/：昆仑芯（K100/K200、R200 等加速卡）部署示例；
• ascend/：华为昇腾部署示例；
• rockchip/：瑞芯微 RKNPU2 与 RV1126 部署示例；
• amlogic/：晶晨 A311D 部署示例（C++）；
• sophgo/：算能部署示例；
• serving/：服务化部署（基于 FastDeploy Serving）；
• quantize/：量化模型部署与模型自动化压缩说明。

FastDeploy 在推理时支持多种后端引擎，包括 Paddle Inference、Paddle Lite、TensorRT、OpenVINO、ONNXRuntime、RKNPU2、SOPHGO 等，因此同一份 PaddleDetection 模型可以按部署环境灵活选择后端，例如 GPU 上选 TensorRT、CPU 上选 ONNXRuntime 或 OpenVINO、边缘盒子选 RKNPU2。

2. 硬件支持总览与各平台使用入口

主文档 deploy/fastdeploy/README.md 给出了完整硬件支持矩阵，整理如下：

各硬件目录内部都遵循统一的组织约定：顶层 README 说明该硬件支持范围与模型列表，python/与cpp/子目录分别提供推理示例。例如 CPU/GPU 平台下，Python 示例位于 deploy/fastdeploy/cpu-gpu/python，C++ 示例位于 deploy/fastdeploy/cpu-gpu/cpp；瑞芯微 RKNPU2 的示例则在 deploy/fastdeploy/rockchip/rknpu2。

除了上述各硬件平台，主文档还列出了更多部署形态：

• Android ARM CPU 部署（通过 FastDeploy Java Android 示例）；
• 服务化 Serving 部署：基于 FastDeploy Serving 镜像提供 HTTP/gRPC 服务；
• web 部署；
• 模型自动化压缩工具：对模型进行量化压缩后部署。

3. 部署模型从哪里来：预导出模型与自行导出两种途径

3.1 直接使用预导出模型（快速验证）

为方便开发者快速验证，各平台文档提供了 FastDeploy 预导出的 PaddleDetection 模型，可直接下载解压使用。以 deploy/fastdeploy/cpu-gpu/README.md 中列出的目标检测与实例分割模型为例（精度指标均来源于 PaddleDetection 对应模型介绍，此处节选）：

此外还提供 PP-TinyPose 关键点检测模型（PP-TinyPose-128x96、PP-TinyPose-256x192）以及"PicoDet 行人检测 + PP-TinyPose"串联配置，用于单人/多人关键点检测场景。需要注意的是，表中标注"暂不支持 TensorRT、ORT"的模型，意味着该模型在原生 TensorRT 或 ONNX Runtime 后端上有算子兼容限制，部署时应选择其他后端（如 Paddle Inference）。

3.2 自行导出 PaddleDetection 部署模型

如果你的模型不在预导出列表中，需要自行导出。导出命令参考仓库根目录下的 deploy/EXPORT_MODEL.md。导出的模型包含三个文件：

• model.pdmodel：静态图模型结构；
• model.pdiparams：模型权重参数；
• infer_cfg.yml：部署配置，FastDeploy 会从该 yaml 中解析模型推理时需要的预处理信息（如归一化 mean/std、输入尺寸、NMS 参数等）。

主文档明确给出三条"导出须知"，务必遵守，否则部署会出错：

1. 导出模型时不要做去除 NMS 的操作，正常导出即可；
2. 如果打算跑原生 TensorRT 后端（非 Paddle Inference 后端），不要加--trt参数；
3. 导出时不要添加fuse_normalize=True参数。

从仓库看，PaddleDetection 支持导出的模型系列覆盖非常广，包括 PP-YOLOE（含 PP-YOLOE+）、PicoDet、PP-YOLO（含 v2）、YOLOv3、YOLOX、Faster RCNN、Mask RCNN、SSD、Cascade RCNN、RetinaNet、FCOS、TTFNet、TOOD、GFL、PPYOLOESOD 等，其训练配置分别位于 configs/ppyoloe、configs/picodet、configs/faster_rcnn、configs/mask_rcnn、configs/ssd 等目录下，可对照选择。

4. CPU/GPU 平台实战：Python 部署示例

以最通用的 CPU/GPU 平台为例，deploy/fastdeploy/cpu-gpu/python/README.md 提供了以 PP-YOLOE 为范例的完整流程。文档特别强调：FastDeploy 支持的模型系列，其构造函数和预测函数的参数完全一致，只需参考 PP-YOLOE 的示例，即可快速调用其他所有模型。

4.1 环境与模型准备

• 确认软硬件环境，安装 FastDeploy 预编译库（版本要求>= 1.0.4）；
• 准备推理模型：使用预导出模型，或按上文 3.2 节自行导出。

4.2 目标检测推理命令

# 下载部署示例代码（若当前分支找不到 fastdeploy 测试代码，请切换到 develop 分支） git clone https://github.com/PaddlePaddle/PaddleDetection.git cd PaddleDetection/deploy/fastdeploy/cpu-gpu/python # 下载 PPYOLOE 模型文件和测试图片 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.py --model_dir ppyoloe_crn_l_300e_coco --image_file 000000014439.jpg --device cpu # GPU 推理 python infer.py --model_dir ppyoloe_crn_l_300e_coco --image_file 000000014439.jpg --device gpu # GPU 上 Paddle-TensorRT 推理 # （注意：TensorRT 推理第一次运行时有序列化模型的操作，会耗时，需要耐心等待） python infer.py --model_dir ppyoloe_crn_l_300e_coco --image_file 000000014439.jpg --device gpu --use_trt True

4.3 关键点检测推理命令

cd PaddleDetection/deploy/fastdeploy/cpu-gpu/python # 下载 PP-TinyPose 模型文件和测试图片 wget https://bj.bcebos.com/paddlehub/fastdeploy/PP_TinyPose_256x192_infer.tgz tar -xvf PP_TinyPose_256x192_infer.tgz wget https://bj.bcebos.com/paddlehub/fastdeploy/hrnet_demo.jpg # CPU 推理 python pptinypose_infer.py --model_dir PP_TinyPose_256x192_infer --image_file hrnet_demo.jpg --device cpu # GPU 推理 python pptinypose_infer.py --model_dir PP_TinyPose_256x192_infer --image_file hrnet_demo.jpg --device gpu # GPU 上 Paddle-TensorRT 推理 python pptinypose_infer.py --model_dir PP_TinyPose_256x192_infer --image_file hrnet_demo.jpg --device gpu --use_trt True

多人关键点检测需要"行人检测 + 关键点"串联，可参考 deploy/fastdeploy/cpu-gpu/python/det_keypoint_unite 下的 Pipeline 示例。

4.4 命令行参数说明

deploy/fastdeploy/cpu-gpu/python/README.md 给出了 infer.py 的参数定义，整理如下：

对应 infer.py 的源码，可以看到--use_trt通过ast.literal_eval解析为布尔值；当启用 TRT 时，代码先option.use_paddle_infer_backend()并打开paddle_infer_option.enable_trt，再通过trt_option.set_shape显式设置输入张量image（[1,3,640,640]）与scale_factor（[1,2]）的 min/max/opt 三个维度——这正是 TensorRT 引擎构建所需的输入 shape 信息，也是 PP-YOLOE 这类带scale_factor输入的模型在 TensorRT 后端必须配置的原因。若想使用原生 TensorRT 而非 Paddle-TensorRT，源码注释提示可改用option.use_trt_backend()。

4.5 Python 推理接口一览

所有检测模型的构造函数签名统一为（以 PPYOLOE 为例）：

fastdeploy.vision.detection.PPYOLOE(model_file, params_file, config_file, runtime_option=None, model_format=ModelFormat.PADDLE)

其中model_file、params_file对应导出的model.pdmodel与model.pdiparams，config_file对应infer_cfg.yml。同签名模型包括PicoDet、PaddleYOLOX、YOLOv3、PPYOLO、FasterRCNN、MaskRCNN、SSD、PaddleYOLOv5/v6/v7、RTMDet、CascadeRCNN、PSSDet、RetinaNet、PPYOLOESOD、FCOS、TTFNet、TOOD、GFL等。关键点检测模型为：

fastdeploy.vision.keypointdetection.PPTinyPose(model_file, params_file, config_file, runtime_option=None, model_format=ModelFormat.PADDLE)

从 infer.py 可以看到完整的推理骨架：构造RuntimeOption（按 device/trt 参数配置）→ 组装三个模型文件路径 → 实例化模型并校验Initialized()→model.predict(im)得到DetectionResult→fd.vision.vis_detection(im, result, score_threshold=0.5)可视化并保存visualized_result.jpg。

5. CPU/GPU 平台实战：C++ 部署示例

C++ 部署流程位于 deploy/fastdeploy/cpu-gpu/cpp，同样要求 FastDeploy 版本 >= 1.0.4，并且所有模型类构造/预测接口参数一致。

5.1 编译与运行

# 下载 FastDeploy 预编译库（在 FastDeploy 预编译库页面选择合适版本） wget https://bj.bcebos.com/fastdeploy/release/cpp/fastdeploy-linux-x64-gpu-x.x.x.tgz tar xvf fastdeploy-linux-x64-gpu-x.x.x.tgz cd PaddleDetection/deploy/fastdeploy/cpu-gpu/cpp # 编译部署示例 mkdir build && cd build mv ../fastdeploy-linux-x64-gpu-x.x.x . cmake .. -DFASTDEPLOY_INSTALL_DIR=${PWD}/fastdeploy-linux-x64-gpu-x.x.x make -j # 下载 PPYOLOE 模型与测试图片 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 推理 ./infer_demo ./ppyoloe_crn_l_300e_coco 000000014439.jpg 0 # GPU 推理 ./infer_demo ./ppyoloe_crn_l_300e_coco 000000014439.jpg 1 # GPU + TensorRT 推理（首次运行含序列化耗时） ./infer_demo ./ppyoloe_crn_l_300e_coco 000000014439.jpg 2

关键点检测示例使用infer_tinypose_demo PP_TinyPose_256x192_infer hrnet_demo.jpg 0/1/2，三个数字分别表示 CPU、GPU、GPU+TensorRT 三种运行模式。上述命令适用于 Linux 或 macOS；Windows 下使用 C++ SDK 的方式请参考 FastDeploy 官方 FAQ。

5.2 C++ 接口与实现要点

C++ 侧模型构造函数同样统一，例如：

fastdeploy::vision::detection::PPYOLOE(const string& model_file, const string& params_file, const string& config_file, const RuntimeOption& runtime_option = RuntimeOption(), const ModelFormat& model_format = ModelFormat::PADDLE);

infer.cc 展示了三种运行模式的组织方式：CpuInfer使用option.UseCpu()；GpuInfer使用option.UseGpu()；TrtInfer则在UseGpu()基础上调用option.UsePaddleInferBackend()并设置paddle_infer_option.enable_trt = true、collect_trt_shape = true，再通过trt_option.SetShape指定image与scale_factor的输入 shape（与 Python 示例一一对应）。每个函数都包含model.Initialized()校验与model.Predict(im, &res)调用，最终用fastdeploy::vision::VisDetection(im, res, 0.5)可视化保存为vis_result.jpg。main根据第三个命令行参数（0/1/2）分发到三种推理函数，这段源码可以作为移植到自有 C++ 工程的模板。

C++ 侧额外支持SOLOv2（实例分割）模型，接口同样为fastdeploy::vision::detection::SOLOv2(...)。

6. 其他硬件平台部署要点

6.1 昆仑芯（kunlunxin）

deploy/fastdeploy/kunlunxin/README.md 说明支持昆仑 818-100（推理芯片）与 818-300（训练芯片），设备包括 K100/K200 昆仑 AI 加速卡与 R200 昆仑芯 AI 加速卡。其预导出模型列表与 CPU/GPU 平台基本一致，Python 与 C++ 示例分别在 deploy/fastdeploy/kunlunxin/python 与 deploy/fastdeploy/kunlunxin/cpp。

6.2 华为昇腾（ascend）

deploy/fastdeploy/ascend/README.md 支持在昇腾上快速部署检测模型，预导出模型列表与 CPU/GPU 一致，示例位于 deploy/fastdeploy/ascend/python 与 deploy/fastdeploy/ascend/cpp。

6.3 瑞芯微 RKNPU2（rockchip）

RKNPU2 是高性能的 Rockchip NPU 访问接口，支持 RK3566/RK3568、RK3588/RK3588S、RV1103/RV1106 等硬件，已在 RKNPU2 上通过测试的 PaddleDetection 模型包括 PicoDet、PPYOLOE（int8）、YOLOV8。与通用平台不同，RKNPU2 部署需要模型转换：

1. Paddle 静态图模型通过paddle2onnx转为 ONNX（导出时需设置export.nms=True，因为 RKNPU2 不支持 NMS，输出节点必须裁剪到 NMS 之前；同时受 RKNPU2 Div 算子限制，输出节点需裁剪到 Div 算子之前）；
2. 使用python -m paddle2onnx.optimize固定输入 shape，例如{'image':[1,3,416,416], 'scale_factor':[1,2]}；
3. 编写 yaml 配置：如需在 NPU 上执行 normalize，配置 mean/std（如 mean[123.675, 116.28, 103.53]、std[58.395, 57.12, 57.375]）；输出节点名需用 Netron 可视化模型后，找到 NonMaxSuppression 节点之前的算子名填入outputs_nodes，例如['p2o.Mul.179', 'p2o.Concat.9']；
4. 通过tools/rknpu2/export.py --config_path ... --target_platform rk3588将 ONNX 转为 RKNN 模型。

详细示例位于 deploy/fastdeploy/rockchip/rknpu2 下的cpp/与python/子目录。

6.4 晶晨（amlogic）与算能（sophgo）

• 晶晨 A311D 提供 C++ 部署示例，位于 deploy/fastdeploy/amlogic/a311d/cpp，包含 CMakeLists、infer.cc与run_with_adb.sh（可通过 adb 推送运行）；
• 算能平台提供 Python 与 C++ 示例，位于 deploy/fastdeploy/sophgo。

7. 服务化部署：基于 FastDeploy Serving

当需要把检测模型封装为可对外提供 HTTP/gRPC 的服务时，可使用 deploy/fastdeploy/serving/README.md 介绍的服务化部署方案。该文档以 PP-YOLOE（ppyoloe_crn_l_300e_coco）为例，其他 PaddleDetection 模型只需替换模型与配置名即可。

7.1 目录结构与模型放置

服务目录包含models/下的四个子目录：preprocess（预处理）、runtime（模型运行时）、postprocess（后处理）、ppdet（模型配置）。启动前需要把模型文件与配置文件放到约定位置：

cd PaddleDetection/deploy/fastdeploy/serving # 下载 PPYOLOE 模型 wget https://bj.bcebos.com/paddlehub/fastdeploy/ppyoloe_crn_l_300e_coco.tgz tar xvf ppyoloe_crn_l_300e_coco.tgz # 将 infer_cfg.yml 放入预处理目录 mv ppyoloe_crn_l_300e_coco/infer_cfg.yml models/preprocess/1/ # 将模型放入 models/runtime/1 目录，并重命名为 model.pdmodel / model.pdiparams mv ppyoloe_crn_l_300e_coco/model.pdmodel models/runtime/1/model.pdmodel mv ppyoloe_crn_l_300e_coco/model.pdiparams models/runtime/1/model.pdiparams # 将 ppdet 和 runtime 下的 ppyoloe 配置重命名为标准 config.pbtxt # （其他模型如 faster_rcnn 则将 faster_rcnn_config.pbtxt 重命名为 config.pbtxt） cp models/ppdet/ppyoloe_config.pbtxt models/ppdet/config.pbtxt cp models/runtime/ppyoloe_runtime_config.pbtxt models/runtime/config.pbtxt

注意：mask_rcnn 模型多一个输出，需要将后处理目录（models/postprocess）中的mask_config.pbtxt重命名为config.pbtxt。仓库中 models/ppdet 提供了 faster_rcnn、mask_rcnn、ppyolo、ppyoloe 四套 pbtxt 模板，models/runtime 下则有对应的 runtime 配置模板，可直接参考替换。

7.2 拉取镜像并启动服务

# GPU 镜像 docker pull registry.baidubce.com/paddlepaddle/fastdeploy:x.y.z-gpu-cuda11.4-trt8.4-21.10 # CPU 镜像 docker pull paddlepaddle/fastdeploy:z.y.z-cpu-only-21.10 # 运行容器，容器名为 fd_serving，挂载当前目录到容器的 /serving 目录 nvidia-docker run -it --net=host --name fd_serving --shm-size="1g" -v `pwd`/:/serving \ registry.baidubce.com/paddlepaddle/fastdeploy:x.y.z-gpu-cuda11.4-trt8.4-21.10 bash # 启动服务（不设置 CUDA_VISIBLE_DEVICES 时拥有所有 GPU 的调度权限） CUDA_VISIBLE_DEVICES=0 fastdeployserver --model-repository=/serving/models

服务启动成功后会有如下输出，表示 HTTP（8000）、gRPC（8001）与 Metrics（8002）端口均已就绪：

I0928 04:51:15.784517 206 grpc_server.cc:4117] Started GRPCInferenceService at 0.0.0.0:8001 I0928 04:51:15.785177 206 http_server.cc:2815] Started HTTPService at 0.0.0.0:8000 I0928 04:51:15.826578 206 http_server.cc:167] Started Metrics Service at 0.0.0.0:8002

若启动时报Address already in use，可改用--grpc-port指定端口，并同步修改客户端示例中的请求端口号；其他启动参数可用fastdeployserver --help查看。客户端请求示例见 paddledet_grpc_client.py，配合tritonclient[all]依赖即可发送 gRPC 请求。

8. 量化模型部署与自动化压缩

deploy/fastdeploy/quantize/README.md 说明 FastDeploy 支持部署量化模型，并提供一键模型自动化压缩工具：用户输入一个配置文件即可对模型完成量化，随后像部署 FP32 模型一样部署量化模型。

量化模型的部署流程与 FP32 基本一致，只是模型是否量化的区别；若某硬件在量化部署上有特殊处理，各硬件文档会特别标明。仓库中的 Benchmark 数据（以 ppyoloe_crn_l_300e_coco 量化蒸馏训练模型为例，测试环境为 Intel Xeon Gold 6271C 单线程 CPU、Tesla T4 GPU、TensorRT 8.4.15）显示，在 TensorRT 后端上 INT8 量化可将 Runtime 时延从 FP32 的 27.90ms 降到 6.39ms，加速比约 4.67 倍，同时 mAP 从 51.4 仅降至 50.7；端到端（含前后处理）时延则从 35.75ms 降到 15.42ms，加速比约 2.32 倍。需要说明的是，这些数据是文档给出的特定环境测量值，实际加速效果取决于硬件、模型与量化配置。另外文档指出：TensorRT 比 Paddle-TensorRT 快的原因是在 runtime 中移除了 multiclass_nms3 算子；INT8+FP16 组合指推理 INT8 量化模型的同时开启 FP16 推理，INT8+FP16+PM 则额外开启 Pinned Memory 以加速 GPU→CPU 数据拷贝。

量化模型部署同样覆盖 X86 CPU、NVIDIA GPU、飞腾/ARM CPU、Intel GPU、昆仑等硬件平台，参考链接与 FP32 部署相同。

9. 常见问题与排查思路

主文档建议遇到问题时按以下顺序排查：先查阅 FastDeploy 的常见问题集合，再搜索 FastDeploy issue 仓库，若无匹配可提交新 issue。仓库内各平台文档也沉淀了高频问题，例如：

• TensorRT 首次运行慢：TensorRT 首次推理需要序列化/构建引擎，耗时较长属正常现象；
• 如何切换推理后端：同一份模型可通过RuntimeOption在 Paddle Inference、TensorRT、ONNX Runtime、OpenVINO 等后端间切换，CPU/GPU 部署文档的 FAQ 一节对此有专门说明；
• Intel GPU 使用：Intel 集成/独立显卡的启用有专门的教程与运行时要求；
• RKNPU2 转换失败：需确认输出节点裁剪到 NMS/Div 之前，且 normalize 参数与模型训练配置一致；
• 服务端口冲突：Address already in use时使用--grpc-port更换端口。

10. 小结：一条从训练到生产的完整部署链路

综合以上内容，PaddleDetection + FastDeploy 的部署链路可以总结为四步：

1. 模型准备：直接下载预导出模型，或使用tools/export_model.py导出model.pdmodel、model.pdiparams、infer_cfg.yml三件套（导出时保留 NMS、不加--trt、不加fuse_normalize）；
2. 环境准备：安装对应平台的 FastDeploy 预编译库（版本 >= 1.0.4）或拉取 Serving 镜像；
3. 选择部署形态：单机推理选 Python/C++ 示例，服务化选 Serving，边缘端按硬件选 RKNPU2/晶晨/算能等示例；所有检测模型类接口参数一致，可套用 PP-YOLOE 模板快速切换；
4. 性能优化：GPU 上开启 TensorRT，或在精度允许范围内使用自动化压缩工具量化模型以获得加速。

无论目标是云端的 TensorRT 加速推理、服务化的 HTTP/gRPC 接口，还是边缘盒子上的 NPU 部署，本仓库 deploy/fastdeploy 下的文档与示例代码都提供了可复用的落地模板，是 PaddleDetection 模型生产化部署的首选参考入口。

• 人工智能
• 深度学习
• 计算机视觉