PaddleSeg 语义分割模型在华为昇腾 NPU 上的 FastDeploy 部署指南
PaddleSeg 语义分割模型在华为昇腾 NPU 上的 FastDeploy 部署指南
本文基于 deploy/fastdeploy/semantic_segmentation/ascend/README.md 及其配套示例,系统讲解如何借助 FastDeploy 将 PaddleSeg 的语义分割模型部署到华为昇腾(Ascend)NPU 上完成推理。文章覆盖预导出模型清单、PaddleSeg 模型导出要点(含
output_op与deploy.yaml的原理分析)、Python 与 C++ 两套完整部署示例及源码级解读,读者读完即可在昇腾环境复现 PP-LiteSeg 等模型的分割推理。
1. 方案说明:为什么选择 FastDeploy 部署到昇腾
PaddleSeg 官方支持通过 FastDeploy 在华为昇腾上部署 Segmentation 相关模型。FastDeploy 是一个全场景、易用灵活的 AI 推理部署工具,在昇腾硬件上通过 Ascend NPU 后端完成模型推理,用户无需关心昇腾 CANN 底层的算子与内存管理细节,只需用统一的 RuntimeOption 切换后端即可。
从仓库的整体部署矩阵(见 deploy/fastdeploy/semantic_segmentation/README.md)可以看到,PaddleSeg 语义分割模型在昇腾、昆仑、瑞芯微、晶晨、算能等 10+ 款硬件上均有 Python 与 C++ 部署指南,昇腾是其中的重要一环。本文聚焦昇腾一条路线展开。
部署前需要明确一点:昇腾部署需要自行编译带昇腾后端的 FastDeploy 运行库(Python wheel 包或 C++ 预测库),官方预编译包通常不包含昇腾支持,这是与 CPU/GPU 路线最大的环境差异。
2. 使用预导出的模型列表
若不想自己走训练、导出流程,可以直接使用 FastDeploy 预导出的推理模型。下表整理了昇腾部署场景下可用的预导出模型(含带/不带 argmax 两个版本),其中 mIoU 为对应模型在 Cityscapes 或人像数据集上的分割精度指标:
| 模型 | 参数文件大小 | 输入 Shape | mIoU | mIoU (flip) | mIoU (ms+flip) |
|---|---|---|---|---|---|
| PP-LiteSeg-B(STDC2)-cityscapes-with-argmax / without-argmax | 31MB | 1024x512 | 79.04% | 79.52% | 79.85% |
| PP-HumanSegV1-Lite-with-argmax / without-argmax(通用人像分割模型) | 543KB | 192x192 | 86.2% | - | - |
| PP-HumanSegV2-Lite-with-argmax / without-argmax(通用人像分割模型) | 12MB | 192x192 | 92.52% | - | - |
| PP-HumanSegV2-Mobile-with-argmax / without-argmax(通用人像分割模型) | 29MB | 192x192 | 93.13% | - | - |
| PP-HumanSegV1-Server-with-argmax / without-argmax(通用人像分割模型) | 103MB | 512x512 | 96.47% | - | - |
| Portrait-PP-HumanSegV2-Lite-with-argmax / without-argmax(肖像分割模型) | 3.6MB | 256x144 | 96.63% | - | - |
| FCN-HRNet-W18-cityscapes-with-argmax / without-argmax | 37MB | 1024x512 | 78.97% | 79.49% | 79.74% |
| Deeplabv3-ResNet101-OS8-cityscapes-with-argmax / without-argmax | 150MB | 1024x512 | 79.90% | 80.22% | 80.47% |
| SegFormer_B0-cityscapes-with-argmax / without-argmax | 15MB | 1024x1024 | 76.73% | 77.16% | - |
补充说明(导出方式与文件命名的对应关系):
- 文件名标记
without-argmax的模型,导出方式为:不指定--input_shape,指定--output_op none; - 文件名标记
with-argmax的模型,导出方式为:不指定--input_shape,指定--output_op argmax。
下载对应 tgz 压缩包后解压,即可得到含 model.pdmodel、model.pdiparams、deploy.yaml 的模型目录,直接用于第 4、5 节的部署示例。
3. 自行导出 PaddleSeg 部署模型
3.1 模型版本与已验证系列
FastDeploy 支持 PaddleSeg 高于 2.6 版本的 Segmentation 模型。如果你要部署的是 PP-Matting、PP-HumanMatting、ModNet 这类抠图模型,请参考 Matting 模型部署 文档,不属于本文语义分割范畴。
官方文档中明确测试过成功部署的模型系列(对应配置均可在本仓库找到):
3.2 模型导出流程
PaddleSeg 训练完成后,最高精度的权重保存在 save_dir/best_model/model.pdparams。使用 tools/export.py 导出预测模型:
python tools/export.py \
--config configs/pp_liteseg/pp_liteseg_stdc1_cityscapes_1024x512_scale0.5_160k.yml \
--model_path model.pdparams \
--save_dir output/inference_model
导出脚本的关键参数如下(与 tools/export.py 中 argparse 定义一致):
| 参数名 | 用途 | 是否必选 | 默认值 |
|---|---|---|---|
| config | 配置文件的路径 | 是 | - |
| model_path | 模型权重的路径 | 否 | - |
| save_dir | 预测模型保存的目录 | 否 | ./output/inference_model |
| input_shape | 设置模型的输入 shape(N*C*H*W),如 --input_shape 1 3 1024 1024;不设置时默认导出 [-1, 3, -1, -1]。预测 shape 固定时建议指定 |
否 | None |
| output_op | 在模型末端添加的输出算子,支持 argmax / softmax / none |
否 | argmax |
| for_fd | 导出 FastDeploy 兼容格式(--for_fd 标志) |
否 | False |
导出成功后得到如下文件结构:
output/inference_model
├── deploy.yaml # 部署配置:预处理方式、输入 shape、输出 op 等信息
├── model.pdmodel # 预测模型的拓扑结构文件
├── model.pdiparams # 预测模型的权重文件
└── model.pdiparams.info # 参数额外信息,一般无需关注
注意:如果部署时出现与 shape 相关的问题,请尝试显式指定 --input_shape。
3.3 导出须知:output_op 与 deploy.yaml 的配合
output_op 直接决定推理输出的形态,选择依据是下游使用方式:
argmax(默认):网络末端添加 argmax 算子,输出每个像素的分割类别,维度为N*H*W、数据类型int32;softmax:输出每个像素每类的概率,维度为N*C*H*W、数据类型float32;none:保留 PaddleSeg 组网默认的 logits(N*C*H*W),不带任何后处理算子。
从源码看,paddleseg/core/export.py 在 output_op != 'none' 时用 WrappedModel(model, args.output_op) 包装网络末端算子,并在 paddleseg/core/export.py 中将 output_dtype(argmax 时为 int32,否则为 float32)与 output_op 一并写入 deploy.yaml。
deploy.yaml 是 FastDeploy 推理时读取预处理与输出信息的唯一依据,仓库中的实际示例(见 deploy/fastdeploy/semantic_segmentation/serving/fastdeploy_serving/PP_LiteSeg_B_STDC2_cityscapes_with_argmax_infer/deploy.yaml)内容如下:
Deploy:
input_shape:
- -1
- 3
- -1
- -1
model: model.pdmodel
output_dtype: int32
output_op: argmax
params: model.pdiparams
transforms:
- type: Normalize
可以看到,FastDeploy 会从 yaml 中解析模型文件名、输入 shape、输出算子类型与预处理 transforms(如 Normalize),自动完成与训练时一致的数据预处理。因此导出后请勿随意改动 deploy.yaml,也不要只拷贝 model.pdmodel/model.pdiparams 而遗漏该文件。
4. Python 部署示例(Ascend NPU)
4.1 部署环境准备
在部署前,需自行编译基于华为昇腾 NPU 的 FastDeploy Python wheel 包并安装。参考 FastDeploy 官方文档中「华为昇腾 NPU 部署环境编译」章节,编译时需要本机已安装好昇腾 CANN 工具链与 NPU 驱动。
4.2 部署模型准备
准备好推理模型目录(含 model.pdmodel、model.pdiparams、deploy.yaml),可使用第 2 节的预导出模型,或按第 3 节自行导出。Matting 类模型请走 Matting 部署目录。
4.3 运行部署示例
完整示例代码位于 deploy/fastdeploy/semantic_segmentation/ascend/python/infer.py。运行步骤如下:
# 下载部署示例代码(若当前分支找不到 fastdeploy 测试代码,请切换到 develop 分支)
git clone https://gitcode.com/gh_mirrors/pa/PaddleSeg.git
# git checkout develop
cd PaddleSeg/deploy/fastdeploy/semantic_segmentation/ascend/python
# 下载 PP-LiteSeg 模型文件(with/without argmax 版本均可)与测试图片并解压
# (模型包下载地址见第 2 节预导出模型清单)
tar -xvf PP_LiteSeg_B_STDC2_cityscapes_without_argmax_infer.tgz
# 华为昇腾推理
python infer.py --model PP_LiteSeg_B_STDC2_cityscapes_without_argmax_infer --image cityscapes_demo.png
4.4 示例源码解读
infer.py 的核心逻辑非常精简,其调用链如下(见 infer.py):
runtime_option = fd.RuntimeOption()
runtime_option.use_ascend() # ① 声明使用昇腾 NPU 后端
model = fd.vision.segmentation.PaddleSegModel( # ② 加载 PaddleSeg 模型
model_file, params_file, config_file, runtime_option=runtime_option)
im = cv2.imread(args.image)
result = model.predict(im) # ③ 推理,返回 SegmentationResult
print(result)
vis_im = fd.vision.vis_segmentation(im, result, weight=0.5) # ④ 可视化
cv2.imwrite("vis_img.png", vis_im)
关键点:
- 后端切换只需一行:
runtime_option.use_ascend(),FastDeploy 会自动选择合适的昇腾推理引擎; - 模型加载三件套:
model.pdmodel(结构)、model.pdiparams(权重)、deploy.yaml(预处理配置),三者缺一不可; - 预测与可视化分离:
predict()返回的SegmentationResult可直接print查看结构;如需转为 numpy 格式做二次开发,可参考 FastDeploy 常见问题中关于 SegmentationResult 转换的说明。
5. C++ 部署示例(Ascend NPU)
5.1 部署环境准备
C++ 路线需自行编译基于华为昇腾 NPU 的 FastDeploy 预测库,参考 FastDeploy 官方文档「华为昇腾 NPU 部署环境编译」章节,编译产出物为 FastDeploy 的 C++ 库目录(下例中为 fastdeploy-ascend)。
5.2 运行部署示例
以 Linux 为例,在 deploy/fastdeploy/semantic_segmentation/ascend/cpp 目录执行如下命令即可完成编译与测试:
# 下载部署示例代码
git clone https://gitcode.com/gh_mirrors/pa/PaddleSeg.git
# 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
# 下载 PP-LiteSeg 模型文件与测试图片并解压
tar -xvf PP_LiteSeg_B_STDC2_cityscapes_without_argmax_infer.tgz
# 华为昇腾推理
./infer_demo PP_LiteSeg_B_STDC2_cityscapes_without_argmax_infer cityscapes_demo.png
其中 FASTDEPLOY_INSTALL_DIR 需指向你编译好的昇腾版 FastDeploy 库安装目录,具体 CMake 配置可查看 cpp/CMakeLists.txt。
5.3 示例源码解读
C++ 示例(见 cpp/infer.cc)与 Python 版一一对应,核心流程为:
auto option = fastdeploy::RuntimeOption();
option.UseAscend(); // ① 指定昇腾 NPU 后端
auto model = fastdeploy::vision::segmentation::PaddleSegModel(
model_file, params_file, config_file, option); // ② 加载模型
if (!model.Initialized()) { // ③ 检查模型初始化是否成功
std::cerr << "Failed to initialize." << std::endl;
return;
}
auto im = cv::imread(image_file);
fastdeploy::vision::SegmentationResult res;
if (!model.Predict(im, &res)) { // ④ 推理,失败时返回 false
std::cerr << "Failed to predict." << std::endl;
return;
}
std::cout << res.Str() << std::endl;
auto vis_im = fastdeploy::vision::VisSegmentation(im, res, 0.5); // ⑤ 可视化
cv::imwrite("vis_result.jpg", vis_im);
与 Python 版差异点:
- 显式初始化检查:
model.Initialized()用于确认模型与后端加载成功,失败时打印错误并退出,便于在昇腾环境排查驱动/CANN 问题; - 结果输出:
res.Str()输出文本描述,VisSegmentation(im, res, 0.5)中0.5为分割掩码叠加在原图上的透明度权重; - 命令行约定:程序接受两个参数
path/to/model_dir与path/to/image,对应运行命令中的模型目录与图片路径。
6. 更多指南与常见问题
- 其他硬件路线(CPU/GPU、昆仑、瑞芯微等)的部署示例,可参考 deploy/fastdeploy/semantic_segmentation 下的各子目录;
- 服务化部署可直接复用仓库中 fastdeploy_serving 已配置好的 PP-LiteSeg 模型目录(含
deploy.yaml与 Triton 前后处理配置)作为模板; - 常见问题:如需将
SegmentationResult转为 numpy 数组,可参考 FastDeploy 官方 FAQ 中「vision result 相关问题」;遇到部署问题可在 FastDeploy 仓库搜索 issue 或提交 issue 反馈。
7. 总结
将 PaddleSeg 语义分割模型部署到华为昇腾 NPU,核心链路只有三步:准备模型(预导出或自行导出)→ 编译昇腾版 FastDeploy 运行库 → 运行 Python/C++ 部署示例。其中最容易踩坑的两个环节是:昇腾后端必须自行编译(官方预编译包不含昇腾支持),以及模型目录必须完整携带 deploy.yaml(FastDeploy 依赖它解析预处理与输出算子配置)。掌握本文介绍的 output_op 选择与两套示例源码,即可在此基础上扩展到 PP-HumanSeg 人像分割、SegFormer 等更多模型的实际业务部署。