PaddleSeg 语义分割模型部署 RKNPU2:基于 FastDeploy 的 RK3588 NPU C++ 部署实战指南
PaddleSeg 语义分割模型部署 RKNPU2:基于 FastDeploy 的 RK3588 NPU C++ 部署实战指南
本文围绕 PaddleSeg 仓库中 RKNPU2 C++ 部署示例文档 展开,系统讲解如何将 PaddleSeg 语义分割模型(以 PP-HumanSeg 人像分割为例)在瑞芯微 RKNPU2(RK3566/RK3568/RK3588 等)上完成 C++ 端侧部署。读完后,你将掌握从模型准备、CMake 编译到 infer_demo 运行验证的完整流程,并能理解示例源码中后端选择、预处理器禁用归一化与数据格式转换等关键细节。
1. RKNPU2 部署方案概览与支持的硬件
PaddleSeg 的 FastDeploy 部署体系中,RKNPU2 是面向瑞芯微新一代 NPU 的部署通道。根据 RKNPU2 部署总览文档,RKNPU2 提供一个高性能接口来访问 Rockchip NPU,支持以下硬件:
- RK3566/RK3568
- RK3588/RK3588S
- RV1103/RV1106
官方示例以 RK3588(文档中写作 RV3588 开发板) 为基准平台,演示如何使用 FastDeploy 部署 PaddleSeg 模型。整体链路为:PaddleSeg 训练/导出静态图推理模型 → 转换为 ONNX → 转换为 RKNN 模型 → 在 FastDeploy 中通过 RuntimeOption::UseRKNPU2() 加载推理。
FastDeploy 在语义分割方向支持的硬件矩阵(X86 CPU、NVIDIA GPU、飞腾 CPU、ARM CPU、Intel GPU、昆仑、昇腾、瑞芯微、晶晨、算能等)可在 FastDeploy 部署总览 中查阅,RKNPU2 通道同时提供 Python 与 C++ 两种部署示例。
1.1 预导出模型列表
部署 RKNPU2 时可以直接使用 FastDeploy 预导出并转换好的模型。根据 RKNPU2 部署总览文档 给出的模型列表:
| 模型 | 参数文件大小 | 输入 Shape | mIoU | mIoU (flip) | mIoU (ms+flip) |
|---|---|---|---|---|---|
| Unet-cityscapes | 52MB | 1024x512 | 65.00% | 66.02% | 66.89% |
| PP-LiteSeg-T(STDC1)-cityscapes | 31MB | 1024x512 | 77.04% | 77.73% | 77.46% |
| PP-HumanSegV1-Lite(通用人像分割模型) | 543KB | 192x192 | 86.2% | - | - |
| PP-HumanSegV2-Lite(通用人像分割模型) | 12MB | 192x192 | 92.52% | - | - |
| PP-HumanSegV2-Mobile(通用人像分割模型) | 29MB | 192x192 | 93.13% | - | - |
| PP-HumanSegV1-Server(通用人像分割模型) | 103MB | 512x512 | 96.47% | - | - |
| Portait-PP-HumanSegV2_Lite(肖像分割模型) | 3.6M | 256x144 | 96.63% | - | - |
| FCN-HRNet-W18-cityscapes | 37MB | 1024x512 | 78.97% | 79.49% | 79.74% |
| Deeplabv3-ResNet101-OS8-cityscapes | 150MB | 1024x512 | 79.90% | 80.22% | 80.47% |
各模型的下载地址以该文档中的列表为准。C++ 部署示例选用的正是列表中体积最小、mIoU 最高的 Portait-PP-HumanSegV2_Lite(肖像分割模型,256x144 输入)。
2. 部署环境准备
按照 C++ 部署示例文档,部署前需确认两个步骤:
- 软硬件环境满足要求:包括开发板系统、RKNPU2 驱动与 SDK 等;
- 获得 FastDeploy 部署库:根据开发环境,下载预编译部署库,或从头编译 FastDeploy 仓库。
以上步骤参考 FastDeploy 仓库中 RKNPU2 部署库编译文档(docs/cn/faq/rknpu2/rknpu2.md)完成。编译本仓库的 C++ 示例时,FastDeploy 库的安装目录会通过 CMake 变量 FASTDEPLOY_INSTALL_DIR 注入,具体见下文第 4 节对 CMakeLists.txt 的分析。
3. 部署模型准备:从 Paddle 模型到 RKNN 模型
模型转换的完整流程见 RKNPU2 模型转换总览,链路为:
- PaddleSeg 训练模型导出为推理模型(参考 PaddleSeg 模型导出文档),也可以使用上表中的预导出模型;
- 通过 Paddle2ONNX 将 Paddle 静态图模型转换为 ONNX 模型;
- 在 FastDeploy 中执行 ONNX 转 RKNN。
需要注意:PaddleSeg 导出的模型包含 model.pdmodel、model.pdiparams 和 deploy.yaml 三个文件,FastDeploy 会从 deploy.yaml 中获取模型在推理时需要的预处理信息(如 Resize、Normalize 等 transforms)。导出时还应注意 output_op 参数(是否带 argmax/softmax 算子),按部署需求选择对应版本的模型。
3.1 转换示例:Portrait-PP-HumanSegV2-Lite
仓库提供了 PP-HumanSeg 模型转换示例,以肖像分割模型为例,完整命令如下:
# 下载Paddle2ONNX仓库
git clone https://github.com/PaddlePaddle/Paddle2ONNX
# 下载Paddle静态图模型并为Paddle静态图模型固定输入shape
## 进入为Paddle静态图模型固定输入shape的目录
cd Paddle2ONNX/tools/paddle
## 下载Paddle静态图模型并解压
wget https://bj.bcebos.com/paddlehub/fastdeploy/Portrait_PP_HumanSegV2_Lite_256x144_infer.tgz
tar xvf Portrait_PP_HumanSegV2_Lite_256x144_infer.tgz
python paddle_infer_shape.py --model_dir Portrait_PP_HumanSegV2_Lite_256x144_infer/ \
--model_filename model.pdmodel \
--params_filename model.pdiparams \
--save_dir Portrait_PP_HumanSegV2_Lite_256x144_infer \
--input_shape_dict="{'x':[1,3,144,256]}"
# 静态图转ONNX模型,注意,这里的save_file请和压缩包名对齐
paddle2onnx --model_dir Portrait_PP_HumanSegV2_Lite_256x144_infer \
--model_filename model.pdmodel \
--params_filename model.pdiparams \
--save_file Portrait_PP_HumanSegV2_Lite_256x144_infer/Portrait_PP_HumanSegV2_Lite_256x144_infer.onnx \
--enable_dev_version True
# ONNX模型转RKNN模型
# 将ONNX模型目录拷贝到Fastdeploy根目录
cp -r ./Portrait_PP_HumanSegV2_Lite_256x144_infer /path/to/Fastdeploy
# 转换模型,模型将生成在Portrait_PP_HumanSegV2_Lite_256x144_infer目录下
python tools/rknpu2/export.py \
--config_path tools/rknpu2/config/Portrait_PP_HumanSegV2_Lite_256x144_infer.yaml \
--target_platform rk3588
其中 paddle_infer_shape.py 一步用于给动态 shape 的静态图模型固定输入 shape([1,3,144,256],即 NHWC 语义下的 256x144 输入)。固定 shape 之后,deploy.yaml 中的 input_shape 必须同步修改,否则预处理信息与实际模型输入不一致。原 yaml 与修改后 yaml 对比:
原 yaml 文件
Deploy:
input_shape:
- -1
- 3
- -1
- -1
model: model.pdmodel
output_dtype: float32
output_op: none
params: model.pdiparams
transforms:
- target_size:
- 256
- 144
type: Resize
- type: Normalize
修改后的 yaml 文件
Deploy:
input_shape:
- 1
- 3
- 144
- 256
model: model.pdmodel
output_dtype: float32
output_op: none
params: model.pdiparams
transforms:
- target_size:
- 256
- 144
type: Resize
- type: Normalize
从这份 yaml 结构可以推断 FastDeploy 预处理器的数据来源:transforms 中的 Resize(target_size=[256,144]) 对应推理时的图像缩放,Normalize 对应归一化参数。这也解释了后文第 5 节中为什么要禁用归一化与 permute——因为这两项操作在 RKNN 转换时已经被内嵌进模型内部。
4. 运行 C++ 部署示例
按 C++ 部署示例文档 的完整操作步骤:
# 下载部署示例代码
git clone https://gitcode.com/gh_mirrors/pa/PaddleSeg.git
# 注意:如果当前分支找不到下面的fastdeploy测试代码,请切换到develop分支
# git checkout develop
cd PaddleSeg/deploy/fastdeploy/semantic_segmentation/rockchip/rknpu2/cpp
# 编译部署示例
mkdir build && cd build
cmake .. -DFASTDEPLOY_INSTALL_DIR=${PWD}/fastdeploy-linux-x64-x.x.x
make -j8
wget https://paddleseg.bj.bcebos.com/dygraph/pp_humanseg_v2/images.zip
unzip -qo images.zip
# 运行部署示例
./infer_demo model/Portrait_PP_HumanSegV2_Lite_256x144_infer/ images/portrait_heng.jpg
4.1 编译工程结构解析
CMakeLists.txt 内容非常简洁,仅 11 行,可看出该示例对环境的唯一外部依赖就是 FastDeploy SDK:
CMAKE_MINIMUM_REQUIRED(VERSION 3.10)、C++14 标准;option(FASTDEPLOY_INSTALL_DIR "Path of downloaded fastdeploy sdk."):通过该变量指定 FastDeploy 安装目录;include(${FASTDEPLOY_INSTALL_DIR}/FastDeployConfig.cmake):加载 SDK 自带的 CMake 配置,导出FastDeploy_INCLUDE_DIRS与FastDeploy_LIBS;add_executable(infer_demo infer.cc)+target_link_libraries:唯一的源文件就是 infer.cc。
也就是说,编译时只需把 FASTDEPLOY_INSTALL_DIR 指向下载好的 FastDeploy 预编译库目录(文档中写作 fastdeploy-linux-x64-x.x.x,实际以所下载 SDK 的目录名替换)。
4.2 运行参数与后端选择
结合 infer.cc 中 main 函数的实现,infer_demo 接受如下形式的参数:
./infer_demo path/to/model_dir path/to/image run_option
第三个参数 run_option 决定推理后端:取 0 时走 ONNXInfer(CPU + ONNX,用于精度验证),取 1 时走 RKNPU2Infer(RKNN + RKNPU2 NPU 推理)。因此在 NPU 上做部署验证时,建议显式传入 1:
./infer_demo model/Portrait_PP_HumanSegV2_Lite_256x144_infer/ images/portrait_heng.jpg 1
运行后,可视化结果会写入当前目录的 infer_onnx.jpg(ONNX 路径)或 infer_rknn.jpg(RKNPU2 路径)。
5. infer_demo 源码级实现解析
infer.cc 共 102 行,包含两条并行的推理路径,是理解 FastDeploy 分割 API 的关键样例。
5.1 RKNPU2 推理路径
RKNPU2Infer(infer.cc#L51-L84)的核心流程:
std::string model_file = model_dir + "/Portrait_PP_HumanSegV2_Lite_256x144_infer_rk3588.rknn";
std::string params_file; // RKNN 无需独立参数文件
std::string config_file = model_dir + "/deploy.yaml"; // 预处理信息仍来自 deploy.yaml
auto option = fastdeploy::RuntimeOption();
option.UseRKNPU2(); // 指定 RKNPU2 后端
auto format = fastdeploy::ModelFormat::RKNN; // 模型格式为 RKNN
auto model = fastdeploy::vision::segmentation::PaddleSegModel(
model_file, params_file, config_file, option, format);
if (!model.Initialized()) { /* ... */ }
model.GetPreprocessor().DisablePermute(); // 关闭 NHWC->NCHW 转换
model.GetPreprocessor().DisableNormalize(); // 关闭归一化
要点有三:
- 模型命名约定:RKNN 文件为
Portrait_PP_HumanSegV2_Lite_256x144_infer_rk3588.rknn,带平台后缀(rk3588),与转换时--target_platform rk3588一致,跨芯片部署需使用对应平台后缀的模型; - params_file 置空:RKNN 是单文件模型,参数已内嵌,但仍传入
deploy.yaml作为 config_file 以复用预处理信息; - 预处理器定制:通过
GetPreprocessor()拿到预处理器对象,分别调用DisablePermute()与DisableNormalize(),这正是原文档第 4 节"更多指南"所述注意事项的代码落地。
推理与可视化部分:
auto im = cv::imread(image_file);
fastdeploy::vision::SegmentationResult res;
model.Predict(im, &res);
auto vis_im = fastdeploy::vision::VisSegmentation(im, res);
tc.PrintInfo("PPSeg in RKNPU2"); // TimeCounter 打印耗时
cv::imwrite("infer_rknn.jpg", vis_im);
从源码结构看,Predict 内部会按 deploy.yaml 中的 transforms 完成 Resize 等预处理后送入 NPU,SegmentationResult 承载逐像素的分割结果,VisSegmentation 负责将结果叠加回原图。
5.2 ONNX/CPU 对照路径
ONNXInfer(infer.cc#L18-L49)与 RKNPU2 路径结构几乎相同,差异在于:
option.UseCpu()+fastdeploy::ModelFormat::ONNX,加载Portrait_PP_HumanSegV2_Lite_256x144_infer.onnx;- 不调用
DisablePermute/DisableNormalize,即由 FastDeploy 预处理器按deploy.yaml完整执行归一化与格式转换。
这一对照设计很实用:同一套 deploy.yaml,CPU/ONNX 路径完整执行预处理,而 NPU 路径只保留 Resize,用于 NPU 结果与 CPU 结果的精度对齐验证。
6. 关键注意事项:为什么必须禁用归一化与数据格式转换
这是本部署方案最容易踩坑的点,原文档(cpp/README.md 第 4 节与 python/README.md 第 4 节)均有强调:
RKNPU 上对模型的输入要求是使用 NHWC 格式,且图片归一化操作会在转 RKNN 模型时,内嵌到模型中,因此在使用 FastDeploy 部署时,需要先调用
DisableNormalizeAndPermute(C++)或disable_normalize_and_permute(Python),在预处理阶段禁用归一化以及数据格式的转换。
背后的原因在于转换流程:ONNX 转 RKNN 时,归一化算子与 NHWC 输入布局会被固化进 RKNN 模型图。如果 FastDeploy 预处理器在喂给 NPU 之前又执行一遍 Normalize 和 NCHW→NHWC permute,就会造成重复归一化与布局错乱,推理结果完全错误。仓库中的两种实现对应关系为:
- C++:
model.GetPreprocessor().DisablePermute()+model.GetPreprocessor().DisableNormalize()(infer.cc#L65-L66); - Python:
model.preprocessor.disable_normalize()+model.preprocessor.disable_permute()(infer.py#L52-L53)。
对应的 Python 示例(python/infer.py)整体 API 与 C++ 一一对应:fd.RuntimeOption() → option.use_rknpu2(),fd.vision.segmentation.PaddleSegModel(..., model_format=fd.ModelFormat.RKNN),运行方式为:
python3 infer.py --model_file ./Portrait_PP_HumanSegV2_Lite_256x144_infer/Portrait_PP_HumanSegV2_Lite_256x144_infer_rk3588.rknn \
--config_file ./Portrait_PP_HumanSegV2_Lite_256x144_infer/deploy.yaml \
--image images/portrait_heng.jpg
7. 适用前提、限制与延伸阅读
- 适用前提:目标硬件为 RK3566/RK3568/RK3588/RK3588S/RV1103/RV1106(RKNPU2 通道),且已按 FastDeploy 文档完成对应环境的部署库准备;模型需先完成 Paddle → ONNX → RKNN 转换并固定输入 shape。
- 转换限制:RKNPU2 部署链路要求模型输入 shape 固定(如本文示例的
[1,3,144,256]),动态 shape 场景不适用该转换流程;deploy.yaml的input_shape必须与实际转换后的模型保持一致。 - 模型选择:优先使用预导出模型列表中的模型,或将自训模型按 模型导出文档 导出后走相同转换链路;导出时需根据部署需求确定
output_op(带/不带 argmax/softmax)。
延伸阅读(仓库内相对路径):