PaddleSeg 语义分割模型华为昇腾 Ascend NPU C++ 部署实战指南(FastDeploy 方案)

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

PaddleSeg 语义分割模型华为昇腾 Ascend NPU C++ 部署实战指南(FastDeploy 方案)

导读

本文以 deploy/fastdeploy/semantic_segmentation/ascend/cpp 目录下的部署示例为核心,完整讲解如何基于 FastDeploy 将 PaddleSeg 语义分割模型(以 PP-LiteSeg 为例)部署到华为昇腾 Ascend NPU 上,并给出 C++ 推理的完整链路:环境准备 → 模型准备 → 编译 infer_demo → 昇腾推理 → 结果可视化。读完本文,你将掌握 infer.cc 的代码结构与核心 API 调用方式,能够自行编译基于昇腾 NPU 的 C++ 推理程序,并复现 PP-LiteSeg 在 Cityscapes 数据上的端到端分割演示。

说明:昇腾(Ascend)是华为推出的 AI 处理器(NPU)产品线。PaddleSeg 通过 FastDeploy 这一全场景推理部署工具对昇腾提供支持,仓库中同时提供 Python 部署示例 与本篇的 C++ 部署示例,二者模型准备与运行流程基本一致,可互为参考。


1. 部署环境准备:编译基于昇腾 NPU 的 FastDeploy 预测库

昇腾 NPU 的推理依赖 FastDeploy 自带的昇腾后端(Ascend Backend)。因此部署前必须先自行编译基于昇腾 NPU 的 FastDeploy 预测库(官方二进制包默认不包含昇腾支持),编译指导参考 FastDeploy 文档中的"华为昇腾NPU部署环境编译"章节(自行编译安装部分)。

环境准备的核心要点如下:

  • 需要一台安装了昇腾 CANN(Compute Architecture for Neural Networks)工具链的昇腾设备(如 Atlas 系列推理卡/服务器),具备完整的昇腾 NPU 驱动与运行环境;
  • 编译 FastDeploy 时需开启昇腾支持并链接 CANN 相关依赖库;
  • 编译产物是一个包含 FastDeploy.cmake、头文件与库文件的 SDK 目录,后续 C++ 示例通过 -DFASTDEPLOY_INSTALL_DIR 指向该目录完成编译(见第 3 节)。

这一步骤对应仓库中 deploy/fastdeploy/semantic_segmentation/ascend/cpp/README.md 的第 1 节说明,是后续所有部署步骤的前置条件。


2. 部署模型准备:预导出模型与自行导出两种方式

2.1 方式一:使用预导出的推理模型

仓库在 deploy/fastdeploy/semantic_segmentation/ascend/README.md 中提供了多组已经导出好、可直接用于昇腾推理的模型,覆盖语义分割与人像分割两类任务,例如:

模型 参数文件大小 输入 Shape mIoU mIoU (flip) mIoU (ms+flip)
PP-LiteSeg-B (STDC2)-Cityscapes(with/without-argmax) 31MB 1024x512 79.04% 79.52% 79.85%
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% - -
Portrait-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%
SegFormer-B0-Cityscapes 15MB 1024x1024 76.73% 77.16% -

补充说明(对应文档原文):

  • 文件名标记 without-argmax 的模型,导出方式为:不指定 --input_shape,指定 --output_op none;
  • 文件名标记 with-argmax 的模型,导出方式为:不指定 --input_shape,指定 --output_op argmax。

2.2 方式二:自行导出 PaddleSeg 部署模型

PaddleSeg 支持2.6 以上版本训练的语义分割模型导出。仓库中经 FastDeploy 验证可成功部署的模型系列包括:

模型导出使用仓库提供的 tools/export.py,完整说明见 docs/model_export_cn.md。典型导出命令如下:

python tools/export.py \
    --config configs/pp_liteseg/pp_liteseg_stdc2_cityscapes_1024x512_scale1.0_160k.yml \
    --save_dir output_dir \
    --output_op argmax

导出完成后会得到三个文件:model.pdmodel(网络结构)、model.pdiparams(权重参数)、deploy.yaml(部署配置)。FastDeploy 会从 deploy.yaml 中读取模型在推理时所需的预处理信息,因此这三个文件必须放在同一模型目录下,缺一不可。

2.3 导出须知:output_op 参数的决定性作用

tools/export.py 中 --output_op 的取值与行为如下:

取值 效果 输出维度与类型
argmax(默认) 在模型末端添加 argmax 算子,输出每个像素的分割类别 N*H*W,int32
softmax 在模型末端添加 softmax 算子,输出每个像素每类的概率 N*C*H*W,float32
none 不添加任何输出算子,直接输出 logits N*C*H*W,float32

此外,--input_shape 参数可指定固定输入 Shape(例如 --input_shape 1 3 1024 1024),以便在导出阶段固化输入尺寸。C++ 部署示例中使用的预导出模型为 PP_LiteSeg_B_STDC2_cityscapes_without_argmax_infer,其 deploy.yaml 中 output_op 为 none、输入 Shape 为动态(-1),最终由 FastDeploy 在推理时根据模型配置自动完成预处理与后处理。


3. 模型格式约定:FastDeploy 如何加载 PaddleSeg 模型

无论采用哪种方式准备模型,C++ 示例 infer.cc 加载模型的逻辑是一致的——按固定命名约定拼接路径:

auto model_file = model_dir + sep + "model.pdmodel";
auto params_file = model_dir + sep + "model.pdiparams";
auto config_file = model_dir + sep + "deploy.yaml";
auto option = fastdeploy::RuntimeOption();
option.UseAscend();
auto model = fastdeploy::vision::segmentation::PaddleSegModel(
    model_file, params_file, config_file, option);

关键点拆解:

  • 文件命名约定:模型目录下必须有 model.pdmodel、model.pdiparams、deploy.yaml 三个文件,路径分隔符通过 #ifdef WIN32 宏自适应 Windows(\\)与 Linux(/);
  • option.UseAscend():这是与 CPU/GPU 部署的核心差异。对照 cpu-gpu/cpp/infer.cc 可见,CPU 部署调用 option.UseCpu()、GPU 部署调用 option.UseGpu(),而昇腾部署必须调用 option.UseAscend() 以启用昇腾 NPU 后端;
  • PaddleSegModel 构造:将三个文件路径与 RuntimeOption 一并传入 fastdeploy::vision::segmentation::PaddleSegModel 构造器,内部即完成模型加载与预处理配置解析;
  • 初始化校验:构造后通过 model.Initialized() 检查是否成功初始化,失败则打印 Failed to initialize. 并退出。

4. 编译 C++ 部署示例(infer_demo)

4.1 CMake 工程结构

示例的构建配置见 CMakeLists.txt,核心逻辑如下:

PROJECT(infer_demo C CXX)
CMAKE_MINIMUM_REQUIRED (VERSION 3.10)

option(FASTDEPLOY_INSTALL_DIR "Path of downloaded fastdeploy sdk.")

include(${FASTDEPLOY_INSTALL_DIR}/FastDeploy.cmake)

include_directories(${FASTDEPLOY_INCS})

add_executable(infer_demo ${PROJECT_SOURCE_DIR}/infer.cc)
target_link_libraries(infer_demo ${FASTDEPLOY_LIBS})

要点说明:

  • 工程名 infer_demo,要求 CMake 版本不低于 3.10;
  • 通过 -DFASTDEPLOY_INSTALL_DIR=<SDK路径> 指定编译好的 FastDeploy SDK 位置,工程会 include 其中的 FastDeploy.cmake,并自动使用它导出的 FASTDEPLOY_INCS(头文件路径)与 FASTDEPLOY_LIBS(库链接)两个变量;
  • 源文件仅一个 infer.cc,编译产物为可执行文件 infer_demo。

4.2 编译步骤(Linux)

在 deploy/fastdeploy/semantic_segmentation/ascend/cpp 目录下执行:

# 下载部署示例代码(若已克隆本仓库可跳过)
git clone https://github.com/PaddlePaddle/PaddleSeg.git
# 注意:如果当前分支找不到下面的 fastdeploy 测试代码,请切换到 develop 分支
# git checkout develop
cd PaddleSeg/deploy/fastdeploy/semantic_segmentation/ascend/cpp

mkdir build
cd build
# 使用编译完成的 FastDeploy 库编译 infer_demo
cmake .. -DFASTDEPLOY_INSTALL_DIR=${PWD}/fastdeploy-ascend
make -j

${PWD}/fastdeploy-ascend 即第 1 节中编译出的昇腾版 FastDeploy SDK 目录,编译成功后在 build/ 下会生成 infer_demo 可执行文件。


5. 运行昇腾推理:下载模型与测试图片

5.1 下载模型与测试图片

# 下载 PP-LiteSeg 模型文件和测试图片
wget https://bj.bcebos.com/paddlehub/fastdeploy/PP_LiteSeg_B_STDC2_cityscapes_without_argmax_infer.tgz
tar -xvf PP_LiteSeg_B_STDC2_cityscapes_without_argmax_infer.tgz
wget https://paddleseg.bj.bcebos.com/dygraph/demo/cityscapes_demo.png

下载完成后目录下应包含:

  • PP_LiteSeg_B_STDC2_cityscapes_without_argmax_infer/:模型目录(内含 model.pdmodel、model.pdiparams、deploy.yaml);
  • cityscapes_demo.png:Cityscapes 风格测试图片。

5.2 执行昇腾 NPU 推理

./infer_demo PP_LiteSeg_B_STDC2_cityscapes_without_argmax_infer cityscapes_demo.png

命令行参数含义(见 infer.cc 的 main 函数):

  • argv[1]:模型目录路径(字符串);
  • argv[2]:待推理图片路径(字符串);
  • 参数不足 3 个时,程序打印用法提示 Usage: infer_demo path/to/model_dir path/to/image 并返回 -1。

程序运行流程(对应 AscendInfer 函数,infer.cc):

  1. 组装模型三件套路径并创建 RuntimeOption,调用 UseAscend() 启用昇腾后端;
  2. 构造 PaddleSegModel 并校验初始化;
  3. 使用 OpenCV cv::imread 读取测试图片;
  4. 调用 model.Predict(im, &res) 执行推理,结果写入 fastdeploy::vision::SegmentationResult;
  5. 将 res.Str() 打印到终端(包含分割类别统计等结构化信息);
  6. 调用 fastdeploy::vision::VisSegmentation(im, res, 0.5) 以 0.5 的叠加权重将分割结果可视化;
  7. 通过 cv::imwrite 将可视化结果保存为 vis_result.jpg。

VisSegmentation 的第三个参数 0.5 表示原图与分割掩膜的叠加透明度权重,可依据视觉效果调整。整个推理与可视化链路不依赖 OpenCV 之外的第三方推理库,全部由 FastDeploy 昇腾后端完成。

5.3 运行结果

运行完成后,程序会在当前目录输出 vis_result.jpg 可视化结果图,终端同时打印分割结果的结构化摘要(res.Str())与提示信息 Visualized result saved in ./vis_result.jpg。


6. 代码级解读:infer.cc 的完整调用链

为便于读者将其移植到自己的工程,这里给出 infer.cc 的完整骨架与注释版解读:

#include "fastdeploy/vision.h"

#ifdef WIN32
const char sep = '\\';
#else
const char sep = '/';
#endif

void AscendInfer(const std::string& model_dir, const std::string& image_file) {
  // 1. 按约定拼接模型三件套路径
  auto model_file = model_dir + sep + "model.pdmodel";
  auto params_file = model_dir + sep + "model.pdiparams";
  auto config_file = model_dir + sep + "deploy.yaml";

  // 2. 创建运行时选项并启用昇腾 NPU
  auto option = fastdeploy::RuntimeOption();
  option.UseAscend();

  // 3. 构造 PaddleSeg 模型
  auto model = fastdeploy::vision::segmentation::PaddleSegModel(
      model_file, params_file, config_file, option);

  if (!model.Initialized()) {
    std::cerr << "Failed to initialize." << std::endl;
    return;
  }

  // 4. 读取图片并推理
  auto im = cv::imread(image_file);
  fastdeploy::vision::SegmentationResult res;
  if (!model.Predict(im, &res)) {
    std::cerr << "Failed to predict." << std::endl;
    return;
  }

  // 5. 打印并保存可视化结果
  std::cout << res.Str() << std::endl;
  auto vis_im = fastdeploy::vision::VisSegmentation(im, res, 0.5);
  cv::imwrite("vis_result.jpg", vis_im);
  std::cout << "Visualized result saved in ./vis_result.jpg" << std::endl;
}

int main(int argc, char* argv[]) {
  if (argc < 3) {
    std::cout << "Usage: infer_demo path/to/model_dir path/to/image"
              << std::endl;
    return -1;
  }
  AscendInfer(argv[1], argv[2]);
  return 0;
}

几个可以按需调整的扩展点:

  • 更换模型:只需将 argv[1] 换成其他符合三件套约定的模型目录即可,例如第 2.1 节表格中的任意一个预导出模型;
  • 调整可视化:修改 VisSegmentation 的透明度参数(0.0~1.0),或改用其他输出文件名;
  • 多模型/批量推理:可在 main 中循环调用 AscendInfer,或在单次推理中连续调用 Predict。

7. 与 Python 部署的对照

昇腾部署的 Python 版本见 ascend/python/infer.py,其调用链与 C++ 版一一对应,便于理解 C++ API 的语义:

C++ API(infer.cc) Python API(infer.py) 作用
fastdeploy::RuntimeOption + UseAscend() fd.RuntimeOption() + use_ascend() 启用昇腾 NPU 后端
PaddleSegModel(model, params, config, option) fd.vision.segmentation.PaddleSegModel(...) 加载模型与预处理配置
model.Predict(im, &res) model.predict(im) 执行单张图片推理
VisSegmentation(im, res, 0.5) fd.vision.vis_segmentation(im, result, weight=0.5) 叠加可视化分割结果

运行命令对照:

# Python 部署(对应 python 目录)
python infer.py --model PP_LiteSeg_B_STDC2_cityscapes_without_argmax_infer --image cityscapes_demo.png

Python 版会输出 vis_img.png,C++ 版输出 vis_result.jpg,可视化效果一致。


8. 更多指南与常见问题

  • C++ API 文档:fastdeploy::vision::segmentation 命名空间下的 PaddleSegModel、SegmentationResult、VisSegmentation 等接口说明,可查阅 FastDeploy C++ API 文档;
  • 模型准备总体说明见 deploy/fastdeploy/semantic_segmentation/ascend/README.md;
  • PaddleSeg 语义分割 FastDeploy 部署总览见 deploy/fastdeploy/semantic_segmentation/README.md,其中包含昇腾、昆仑、瑞芯微、晶晨、算能等 10+ 硬件平台的支持列表;
  • Matting 类模型(PP-Matting、PP-HumanMatting、ModNet)不适用于本文流程,需参考 deploy/fastdeploy/matting 下的专门部署示例;
  • 若部署过程中遇到模型加载或推理失败,优先检查:昇腾版 FastDeploy 库是否编译正确、CANN 环境是否就绪、模型三件套是否齐全、导出时 output_op 与 input_shape 是否与推理需求匹配。

9. 总结

本文基于 deploy/fastdeploy/semantic_segmentation/ascend/cpp 目录完整还原了 PaddleSeg 语义分割模型在华为昇腾 NPU 上的 C++ 部署流程:从编译昇腾版 FastDeploy 预测库,到准备预导出或自导出的模型三件套(model.pdmodel / model.pdiparams / deploy.yaml),再到 cmake + make 编译 infer_demo 并执行推理,最终通过 VisSegmentation 输出可视化结果。核心只需一行 option.UseAscend() 即可将同一份 PaddleSeg C++ 推理代码从 CPU/GPU 无缝切换到昇腾 NPU,这正是 FastDeploy 全场景部署能力的直接体现。读者可将本文的 AscendInfer 函数作为模板,快速接入自己的昇腾设备推理流程。

登录后查看全文
PaddleSeg