PaddleSeg 基于 FastDeploy 在晶晨 A311D NPU 上部署 PP-LiteSeg 量化模型：C++ 交叉编译与 ADB 部署实战-平芜编程栈

人工智能
计算机视觉
预训练

【免费下载链接】PaddleSeg

Easy-to-use image segmentation library with awesome pre-trained model zoo, supporting wide-range of practical tasks in Semantic Segmentation, Interactive Segmentation, Panoptic Segmentation, Image Matting, 3D Segmentation, etc.

项目地址：https://gitcode.com/gh_mirrors/pa/PaddleSeg

点击查看免费下载

本指南以 PaddleSeg 仓库中deploy/fastdeploy/semantic_segmentation/amlogic/a311d/cpp/目录为骨架，系统讲解如何将 PP-LiteSeg 量化分割模型部署到晶晨（Amlogic）A311D 开发板上的芯原（VeriSilicon）NPU，涵盖 FastDeploy 交叉编译环境准备、INT8 量化模型获取、CMake 交叉编译、以及基于 ADB 的板端运行全流程。读完本文，你将掌握一套可直接复制的"PC 交叉编译 + A311D 板端推理"部署方案，并能通过阅读infer.cc源码理解 TimVX 后端、异构计算（subgraph.txt）与结果可视化的底层实现。

1. 部署方案概览：A311D 与芯原 NPU 的 FastDeploy 支持

晶晨 A311D 是一款面向 AI 应用的处理器，其内置 NPU 的 IP 来自芯原（VeriSilicon）。值得注意的是，芯原作为 IP 设计厂商并不直接提供实体 SoC，而是将 NPU IP 授权给晶晨、瑞芯微（Rockchip）等芯片厂商。因此，只要芯片没有大幅修改芯原底层库，均可参考同一套部署方案。在 PaddleSeg 的 FastDeploy 部署体系中，晶晨与瑞芯微 SoC 中的 NPU 被统称为"芯原 NPU"。

根据 amlogic 部署总览，当前支持部署的芯片包括：

Amlogic A311D
Amlogic C308X
Amlogic S905D3

在部署语言支持上，A311D 目前仅支持 C++ 部署（不支持 Python），这也正是本文聚焦 C++ 示例的原因。PaddleSeg 通过 FastDeploy 在 A311D 上基于 Paddle-Lite 部署语义分割模型，核心链路为：

PaddleSeg 训练/导出模型 → INT8 量化 → FastDeploy 交叉编译产物 → adb 推送至 A311D → Paddle-Lite + TimVX 后端推理

该目录下的infer.cc帮助用户快速完成 PP-LiteSeg 量化模型在 A311D 上的部署推理加速，配套文件还包括 CMakeLists.txt（交叉编译配置）与 run_with_adb.sh（板端部署脚本）。

2. 部署环境准备：FastDeploy 交叉编译环境

在开始编译部署示例之前，需要先完成两件事：

确认软硬件环境满足要求：交叉编译通常在 x86 Linux 主机上进行，目标产物运行在 ARM64 架构的 A311D 开发板上。
准备 FastDeploy 的晶晨交叉编译环境：需要自行交叉编译 FastDeploy，生成面向 TimVX/A311D 的 SDK 产物。相关编译细节可参考 FastDeploy 官方文档中"晶晨 A311D 自行编译安装"一节。

交叉编译完成后，会得到一个fastdeploy-timvx目录，其中包含toolchain.cmake（交叉编译工具链文件）以及编译好的库文件。这是后续 CMake 编译部署示例的关键输入。

3. 部署模型准备：获取或导出 INT8 量化模型

A311D 的 NPU 仅支持 INT8 推理，因此部署前必须准备好量化模型。模型准备有三种途径，按优先级排列：

3.1 直接使用 FastDeploy 提供的量化模型

FastDeploy 官方提供了 PP-LiteSeg-T（STDC1）在 Cityscapes 数据集上训练并量化好的模型。根据 amlogic 部署总览，该模型的关键信息如下：

模型	参数文件大小	输入 Shape	mIoU	mIoU (flip)	mIoU (ms+flip)
PP-LiteSeg-T(STDC1)-cityscapes-without-argmax	31MB	1024x512	77.04%	77.73%	77.46%

关于量化模型的文件构成，文档中特别说明：

PaddleSeg 量化模型包含model.pdmodel、model.pdiparams、deploy.yaml和subgraph.txt四个文件。FastDeploy 会从deploy.yaml中获取模型推理时需要的预处理信息；subgraph.txt是为异构计算而存储的配置文件。

其中deploy.yaml是 FastDeploy 推理时读取预处理参数的来源（归一化、均值、标准差、输入尺寸等），而subgraph.txt决定了哪些算子跑在 NPU、哪些算子回退到 ARM CPU（详见 3.3 节）。

3.2 自行导出并量化模型

若 FastDeploy 提供的模型不满足需求，可以按两步流程自行生产：

动态图模型导出为推理静态图：将 PaddleSeg 训练出的动态图模型导出为推理静态图模型，导出步骤详见 docs/model_export_cn.md。需要特别注意的是，A311D 仅支持 INT8 量化模型，这与 CPU/GPU 上常见的 FP32 部署有本质区别。
INT8 量化压缩：将推理模型量化为 INT8，可使用 FastDeploy 提供的一键模型自动化压缩工具。详见量化模型部署指南。

关于量化，量化部署文档还给出一个重要提示：自行量化的模型文件夹内不包含deploy.yaml，需要从 FP32 模型文件夹下复制deploy.yaml到量化模型文件夹内，FastDeploy 才能正确读取预处理信息。

模型支持范围方面，PaddleSeg 2.6 以上的分割模型均可尝试导出，目前已在 A311D 上验证过可成功部署的是 PP-LiteSeg 系列模型。PP-LiteSeg 是面向实时语义分割的轻量级模型，通过 Flexible and Lightweight Decoder（FLD）、Unified Attention Fusion Module（UAFM）和 Simple Pyramid Pooling Module（SPPM）三个模块在精度与速度之间取得平衡，很适合部署在 A311D 这类边缘设备上。

3.3 异构计算与 subgraph.txt：NPU 算子回退机制

如果自行导出或训练的模型出现精度下降或者报错，往往意味着 NPU 上某些算子支持不佳。此时需要使用异构计算方案：让模型中的部分算子跑在 A311D 的 ARM CPU 上进行调试和精度验证，其余算子仍跑在 NPU 上。

异构计算所需的文件正是subgraph.txt。在infer.cc中可以看到它的加载方式：

fastdeploy::RuntimeOption option; option.UseTimVX(); option.SetLiteSubgraphPartitionPath(subgraph_file);

SetLiteSubgraphPartitionPath指定了 Paddle-Lite 的算子子图划分路径文件，FastDeploy 依据该文件将模型图划分为"NPU 子图 + CPU 子图"分别执行。当整个模型在 NPU 上跑不通或精度不达标时，通过调整subgraph.txt将问题算子划入 CPU 子图，即可定位问题并逐步恢复精度。

4. 在 A311D 上部署 PP-LiteSeg 量化模型：完整实战流程

以下步骤对应原文档的核心操作流程，全部命令均可直接复制执行。假设你已经完成 FastDeploy 的 A311D 交叉编译，得到了fastdeploy-timvxSDK 目录。

4.1 获取 PaddleSeg 仓库与 FastDeploy 编译产物

git clone https://gitcode.com/gh_mirrors/pa/PaddleSeg.git # 注意：如果当前分支找不到下面的 fastdeploy 测试代码，请切换到 develop 分支 # git checkout develop # 将编译好的 FastDeploy 产物拷贝到部署示例目录 cp -r FastDeploy/build/fastdeploy-timvx/ path/to/PaddleSeg/deploy/fastdeploy/semantic_segmentation/amlogic/a311d/cpp

如果是在本仓库的 develop 分支操作，则该目录下应能看到infer.cc、CMakeLists.txt、run_with_adb.sh三个文件，与本指南完全对应。

4.2 下载部署所需的模型与示例图片

cd path/to/PaddleSeg/deploy/fastdeploy/semantic_segmentation/amlogic/a311d/cpp mkdir models && mkdir images wget https://bj.bcebos.com/fastdeploy/models/rk1/ppliteseg.tar.gz tar -xvf ppliteseg.tar.gz cp -r ppliteseg models wget https://paddleseg.bj.bcebos.com/dygraph/demo/cityscapes_demo.png cp -r cityscapes_demo.png images

ppliteseg.tar.gz解压后即为 3.1 节表格中的 PP-LiteSeg-T 量化模型（包含model.pdmodel、model.pdiparams、deploy.yaml、subgraph.txt四个文件）；cityscapes_demo.png是用于验证推理效果的 Cityscapes 示例街景图。

4.3 交叉编译部署示例

cd path/to/PaddleSeg/deploy/fastdeploy/semantic_segmentation/amlogic/a311d/cpp mkdir build && cd build cmake -DCMAKE_TOOLCHAIN_FILE=${PWD}/../fastdeploy-timvx/toolchain.cmake \ -DFASTDEPLOY_INSTALL_DIR=${PWD}/../fastdeploy-timvx \ -DTARGET_ABI=arm64 .. make -j8 make install # 成功编译之后，会生成 install 文件夹，里面有一个运行 demo 和部署所需的库

三个 CMake 参数的含义：

参数	作用
`CMAKE_TOOLCHAIN_FILE`	指定 FastDeploy 提供的交叉编译工具链文件，决定编译器、链接器与 sysroot
`FASTDEPLOY_INSTALL_DIR`	FastDeploy SDK 安装目录，CMake 通过其中的`FastDeploy.cmake`引入头文件与库
`TARGET_ABI`	目标平台 ABI，A311D 为 64 位系统，填`arm64`

make install执行后，build/install目录下将生成：可执行程序infer_demo、models/与images/目录（由 CMakeLists 的 install 规则自动拷贝）、lib/（全部运行所需的.so动态库）以及run_with_adb.sh。

4.4 基于 ADB 部署到 A311D 并运行

# 进入 install 目录 cd path/to/PaddleSeg/deploy/fastdeploy/semantic_segmentation/amlogic/a311d/cpp/build/install/ cp ../../run_with_adb.sh . # 命令格式：bash run_with_adb.sh <需要运行的demo> <模型路径> <图片路径> <设备的DEVICE_ID> bash run_with_adb.sh infer_demo ppliteseg cityscapes_demo.png $DEVICE_ID

其中$DEVICE_ID是 adb 设备号（多设备场景下用adb devices查看）。脚本执行后会自动完成：清理并创建板端工作目录 → push 动态库、demo、模型与图片到 A311D → 设置 NPU 运行环境变量 → 在板端执行infer_demo完成推理。

部署成功后，程序会在板端输出SegmentationResult的字符串摘要，并在当前目录生成可视化结果文件vis_result.jpg，可将其adb pull回主机查看分割效果。

5. infer.cc 源码剖析：TimVX 后端与分割结果可视化

部署示例的核心逻辑集中在 infer.cc 的InitAndInfer函数中，代码量虽少，却完整覆盖了"模型加载 → 后端配置 → 推理 → 可视化"四个环节：

void InitAndInfer(const std::string& model_dir, const std::string& image_file) { 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 subgraph_file = model_dir + sep + "subgraph.txt"; fastdeploy::vision::EnableFlyCV(); fastdeploy::RuntimeOption option; option.UseTimVX(); option.SetLiteSubgraphPartitionPath(subgraph_file); auto model = fastdeploy::vision::segmentation::PaddleSegModel( model_file, params_file, config_file, option); assert(model.Initialized()); auto im = cv::imread(image_file); fastdeploy::vision::SegmentationResult res; if (!model.Predict(im, &res)) { 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); std::cout << "Visualized result saved in ./vis_result.jpg" << std::endl; }

逐段解读其中的关键设计：

（1）模型文件四件套的拼装。model.pdmodel（网络结构）、model.pdiparams（权重）、deploy.yaml（预处理配置）、subgraph.txt（异构子图划分）四者缺一不可，恰好对应 3.1 节关于量化模型文件构成的说明。sep变量兼容 Windows 与 Linux 的路径分隔符，便于跨平台调试。

（2）EnableFlyCV()与图像解码加速。FlyCV 是 FastDeploy 内置的高性能图像处理库，在移动端/嵌入式平台用于加速imread等图像编解码操作，这是边缘端推理性能优化的常用手段。

（3）option.UseTimVX()开启 NPU 后端。TimVX 是芯原 NPU 的运行时接口，这一行是"算力落到 NPU"的关键开关；配合SetLiteSubgraphPartitionPath(subgraph_file)完成异构计算配置（见 3.3 节）。从源码结构看，该示例通过 Paddle-Lite 的 RuntimeOption 完成后端选择，体现了 FastDeploy"一套 API 多后端切换"的设计理念。

（4）PaddleSegModel与SegmentationResult。PaddleSegModel是 FastDeploy 视觉分割模块的统一封装，构造函数依次接收模型、参数、配置与运行时选项；推理结果封装在SegmentationResult中，通过res.Str()打印类别分布等摘要信息，通过fastdeploy::vision::VisSegmentation(im, res, 0.5)将分割掩膜以 0.5 透明度叠加到原图并保存为vis_result.jpg。

（5）main 函数的命令行约定：

if (argc < 3) { std::cout << "Usage: infer_demo path/to/quant_model " "path/to/image " "e.g ./infer_demo ./ResNet50_vd_quant ./test.jpeg" << std::endl; return -1; } std::string model_dir = argv[1]; std::string test_image = argv[2];

infer_demo接收两个必选参数：量化模型目录路径与测试图片路径，这正是 4.4 节run_with_adb.sh infer_demo ppliteseg cityscapes_demo.png中后两个参数的直接消费方。

6. CMakeLists.txt 与 run_with_adb.sh：工程化部署细节

6.1 CMakeLists.txt 的交叉编译组织

CMakeLists.txt 展示了 FastDeploy 嵌入式部署的标准工程组织方式：

include(${FASTDEPLOY_INSTALL_DIR}/FastDeploy.cmake) include_directories(${FASTDEPLOY_INCS}) include_directories(${FastDeploy_INCLUDE_DIRS}) add_executable(infer_demo ${PROJECT_SOURCE_DIR}/infer.cc) target_link_libraries(infer_demo ${FASTDEPLOY_LIBS}) set(CMAKE_INSTALL_PREFIX ${CMAKE_SOURCE_DIR}/build/install) install(TARGETS infer_demo DESTINATION ./) install(DIRECTORY models DESTINATION ./) install(DIRECTORY images DESTINATION ./) file(GLOB_RECURSE FASTDEPLOY_LIBS ${FASTDEPLOY_INSTALL_DIR}/lib/lib*.so*) file(GLOB_RECURSE ALL_LIBS ${FASTDEPLOY_INSTALL_DIR}/third_libs/install/lib*.so*) list(APPEND ALL_LIBS ${FASTDEPLOY_LIBS}) install(PROGRAMS ${ALL_LIBS} DESTINATION lib) file(GLOB ADB_TOOLS run_with_adb.sh) install(PROGRAMS ${ADB_TOOLS} DESTINATION ./)

要点解读：

通过FastDeploy.cmake统一引入头文件搜索路径（FASTDEPLOY_INCS、FastDeploy_INCLUDE_DIRS）与链接库（FASTDEPLOY_LIBS），使用者无需手动管理复杂的依赖关系；
install规则将可执行程序、模型目录、图片目录与全部.so动态库（含 FastDeploy 自身及third_libs中的第三方依赖）统一收集到build/install，使得 install 目录成为自包含的"可整体推送到板端"的部署包；
脚本run_with_adb.sh也被纳入 install，方便直接进入install目录后一键部署。

6.2 run_with_adb.sh 的板端运行逻辑

run_with_adb.sh 定义了四个依次递增的输入参数（demo 名、模型名、图片名、设备 ID），均有默认值兜底。脚本核心分三部分：

设置 NPU 运行环境变量：

EXPORT_ENVIRONMENT_VARIABLES="export GLOG_v=5; export VIV_VX_ENABLE_GRAPH_TRANSFORM=-pcq:1; export VIV_VX_SET_PER_CHANNEL_ENTROPY=100; export TIMVX_BATCHNORM_FUSION_MAX_ALLOWED_QUANT_SCALE_DEVIATION=300000; export VSI_NN_LOG_LEVEL=5;" EXPORT_ENVIRONMENT_VARIABLES="${EXPORT_ENVIRONMENT_VARIABLES}export LD_LIBRARY_PATH=${WORK_SPACE}/lib:\$LD_LIBRARY_PATH;"

这些变量直接面向芯原 NPU 的运行时行为：VIV_VX_ENABLE_GRAPH_TRANSFORM控制图变换（含 per-channel quantization 优化，-pcq:1表示开启），VIV_VX_SET_PER_CHANNEL_ENTROPY调节逐通道熵量化参数，TIMVX_BATCHNORM_FUSION_MAX_ALLOWED_QUANT_SCALE_DEVIATION控制 BN 算子融合时允许的量化尺度偏差上限，GLOG_v与VSI_NN_LOG_LEVEL则控制 Paddle-Lite 与 NPU 驱动日志的详细程度。当模型精度异常时，调大这些日志级别可以拿到算子级调试信息，这是排查 NPU 推理问题的实用技巧。

数据推送：通过adb push将lib、demo、models、images依次推送到板端工作目录/data/local/tmp/test。
板端执行：设置好LD_LIBRARY_PATH指向板端lib目录后，运行./infer_demo ./models/${MODEL_NAME} ./images/$IMAGE_NAME，与 5 节中 main 函数的参数约定严格对应。

7. 部署结果验证与常见问题排查

成功判据：run_with_adb.sh执行后，板端输出SegmentationResult摘要并提示Visualized result saved in ./vis_result.jpg，将vis_result.jpg拉回主机即可目视检查分割掩膜与道路、车辆等 Cityscapes 类别的贴合度。

常见问题与对应解法：

现象	排查方向
模型推理报错或精度明显下降	按 3.3 节启用异构计算，调整`subgraph.txt`将异常算子划入 CPU 子图定位问题
找不到`deploy.yaml`或预处理信息异常	确认量化模型目录下是否缺失`deploy.yaml`，从 FP32 模型目录复制补齐（见 3.2 节）
板端运行库缺失	确认`install/lib`中所有`.so`均已 push，且`LD_LIBRARY_PATH`正确指向板端`lib`目录
需要算子级调试信息	调大`GLOG_v`、`VSI_NN_LOG_LEVEL`日志等级重新运行

8. 更多指南

部署方案总览与模型精度基准：amlogic 部署总览
量化模型部署总览与硬件支持矩阵：量化模型部署指南
全部 FastDeploy 部署 PaddleSeg 模型的入口：deploy/fastdeploy/semantic_segmentation
PP-LiteSeg 模型结构与训练配置：configs/pp_liteseg/README.md
PaddleSeg 静态图模型导出：docs/model_export_cn.md
PaddleSeg C++ API 文档：FastDeploy 视觉分割模块的 C++ API 参考（fastdeploy::vision::segmentation命名空间，涵盖本文使用的PaddleSegModel与SegmentationResult等类型）

本文完整覆盖了"环境准备 → 模型准备 → 交叉编译 → ADB 板端部署 → 源码解读 → 问题排查"的闭环，基于infer.cc、CMakeLists.txt、run_with_adb.sh三个仓库文件即可独立复现整套 A311D NPU 部署流程。若需适配其他芯原 NPU 芯片（如 C308X、S905D3），在满足"未大幅修改芯原底层库"前提下，本方案同样适用。