PaddleSeg 语义分割模型部署 RKNPU2:基于 FastDeploy 的 RK3588 NPU C++ 部署实战指南

原创2026-09-24 09:37:391,976 阅读
文章标签:计算机视觉深度学习人工智能图像处理预训练模型量化模型蒸馏模型优化数据标注机器学习

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++ 部署示例文档,部署前需确认两个步骤:

  1. 软硬件环境满足要求:包括开发板系统、RKNPU2 驱动与 SDK 等;
  2. 获得 FastDeploy 部署库:根据开发环境,下载预编译部署库,或从头编译 FastDeploy 仓库。

以上步骤参考 FastDeploy 仓库中 RKNPU2 部署库编译文档(docs/cn/faq/rknpu2/rknpu2.md)完成。编译本仓库的 C++ 示例时,FastDeploy 库的安装目录会通过 CMake 变量 FASTDEPLOY_INSTALL_DIR 注入,具体见下文第 4 节对 CMakeLists.txt 的分析。

3. 部署模型准备:从 Paddle 模型到 RKNN 模型

模型转换的完整流程见 RKNPU2 模型转换总览,链路为:

  1. PaddleSeg 训练模型导出为推理模型(参考 PaddleSeg 模型导出文档),也可以使用上表中的预导出模型;
  2. 通过 Paddle2ONNX 将 Paddle 静态图模型转换为 ONNX 模型;
  3. 在 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(); // 关闭归一化

要点有三:

  1. 模型命名约定:RKNN 文件为 Portrait_PP_HumanSegV2_Lite_256x144_infer_rk3588.rknn,带平台后缀(rk3588),与转换时 --target_platform rk3588 一致,跨芯片部署需使用对应平台后缀的模型;
  2. params_file 置空:RKNN 是单文件模型,参数已内嵌,但仍传入 deploy.yaml 作为 config_file 以复用预处理信息;
  3. 预处理器定制:通过 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)。

延伸阅读(仓库内相对路径):

登录后查看全文
PaddleSeg