PaddleSeg 语义分割模型在华为昇腾 NPU 上的 FastDeploy 部署指南

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

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 等更多模型的实际业务部署。

登录后查看全文
PaddleSeg