PaddleSeg 语义分割模型华为昇腾 Ascend NPU C++ 部署实战指南(FastDeploy 方案)
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 验证可成功部署的模型系列包括:
- PP-LiteSeg 系列(配置见 configs/pp_liteseg);
- PP-HumanSeg 系列(见 contrib/PP-HumanSeg);
- FCN 系列(配置见 configs/fcn);
- DeepLabV3 系列(配置见 configs/deeplabv3);
- SegFormer 系列(配置见 configs/segformer)。
模型导出使用仓库提供的 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):
- 组装模型三件套路径并创建
RuntimeOption,调用UseAscend()启用昇腾后端; - 构造
PaddleSegModel并校验初始化; - 使用 OpenCV
cv::imread读取测试图片; - 调用
model.Predict(im, &res)执行推理,结果写入fastdeploy::vision::SegmentationResult; - 将
res.Str()打印到终端(包含分割类别统计等结构化信息); - 调用
fastdeploy::vision::VisSegmentation(im, res, 0.5)以 0.5 的叠加权重将分割结果可视化; - 通过
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 函数作为模板,快速接入自己的昇腾设备推理流程。