PaddleClas 量化模型在晶晨 A311D(芯原 NPU)上的 FastDeploy C++ 部署实战

原创2026-10-05 10:54:512,255 阅读
文章标签:计算机视觉深度学习人工智能机器学习模型蒸馏

PaddleClas 量化模型在晶晨 A311D(芯原 NPU)上的 FastDeploy C++ 部署实战

导读:本文基于 PaddleClas 仓库中的 A311D C++ 部署示例,完整讲解如何在晶晨(Amlogic)A311D 开发板上通过 FastDeploy + Paddle-Lite + TimVX 完成 PaddleClas 分类模型的量化与推理加速。全文覆盖部署环境准备、量化模型来源、交叉编译、CMake 构建、adb 推送到真机、以及 infer.cc 与 run_with_adb.sh 的源码级解读。读完本文,你将能够在 A311D 上端到端跑通 ResNet50_vd / MobileNetV1_ssld 等量化分类模型,并获得可直接复用的工程脚本与故障排查思路。

1. 背景与适用范围:为什么是 A311D + 芯原 NPU

晶晨 A311D 是一款面向 AI 边缘应用的处理器,其内置 NPU 的 IP 由芯原(VeriSilicon)授权提供。这里需要澄清一个容易混淆的概念:芯原作为 IP 设计厂商并不直接出货 SoC,而是将 NPU IP 授权给晶晨、瑞芯微等芯片厂商。因此,本文的部署方案适用于所有“采用了芯原 NPU IP、且未大幅修改其底层库”的芯片产品。在本文语境下,晶晨 SoC 与瑞芯微 SoC 中的 NPU 统称为芯原 NPU。

根据仓库中 A311D 部署方案说明,目前 PaddleClas 通过 FastDeploy 支持在以下芯片上部署:

芯片 说明
Amlogic A311D 本文示例使用的开发板
Amlogic C308X 同属晶晨芯原 NPU 平台
Amlogic S905D3 同属晶晨芯原 NPU 平台

注意:A311D 平台上目前仅支持 C++ 部署,暂无 Python 部署示例,这一点在 目录说明 中有明确交代。

2. 部署环境准备

在开始部署前,必须完成两步环境准备:

  1. 确认目标板为 A311D(或上述兼容芯片),并确保板卡可正常通过 USB 被主机识别(后续 adb 调试依赖这一点)。
  2. 自行编译基于 A311D 的 FastDeploy 预测库。A311D 上无法直接使用宿主机的预编译库,必须交叉编译出面向 arm64 + TimVX 后端的预测库(详见原文档引用的“A311D 部署环境编译”与“交叉编译 FastDeploy”文档,属于 FastDeploy 官方构建流程,本文不再重复)。

编译产物中需要重点保留以下内容:

  • fastdeploy-timvx 目录:内含交叉编译出的 FastDeploy SDK(含 FastDeploy.cmake、头文件、lib*.so* 动态库);
  • toolchain.cmake:交叉编译工具链文件,后续编译部署示例时直接复用。

3. 量化模型准备:A311D 部署的前置条件

A311D 上部署的模型必须是量化后的模型,这是芯原 NPU(TimVX 后端)运行的硬性要求。原文档给出了两种获取量化模型的途径:

3.1 直接使用 FastDeploy 预量化模型

FastDeploy 官方提供了已经量化好的模型,可直接下载使用。仓库文档 A311D 部署方案说明 中列出了两个预量化模型:

模型 量化方式
ResNet50_vd(resnet50_vd_ptq.tar) 离线量化(PTQ)
MobileNetV1_ssld(mobilenetv1_ssld_ptq.tar) 离线量化(PTQ)

离线量化(Post-Training Quantization, PTQ)指模型训练完成后,利用少量校准数据对权重与激活进行定点化(通常为 INT8),从而获得可在 NPU 上高效运行的小体积模型。

3.2 使用 FastDeploy 一键模型自动化压缩工具自行量化

如果预量化模型无法满足需求,可以使用 FastDeploy 提供的一键模型自动化压缩工具(auto_compression)自行量化,再用产出的量化模型部署。

这里有一个非常容易踩的坑,原文档特别强调:推理量化后的分类模型时,仍然需要 FP32 模型文件夹下的 inference_cls.yaml 文件。原因在于:自行量化产出的模型文件夹内通常只包含 inference.pdmodel 与 inference.pdiparams,并不包含推理所需的 YAML 预处理/后处理配置;而 PaddleClas 模型推理时,预处理(resize、crop、归一化)与后处理(Topk 映射类别)都依赖这份 YAML。解决办法是:从 FP32 模型文件夹下复制 inference_cls.yaml 到量化后的模型文件夹内即可。

至于这份 inference_cls.yaml 长什么样,可以对照仓库中的 deploy/configs/inference_cls.yaml,其核心内容如下:

Global:
  infer_imgs: "./images/ImageNet/ILSVRC2012_val_00000010.jpeg"
  inference_model_dir: "./models"
  batch_size: 1
  ...
PreProcess:
  transform_ops:
    - ResizeImage:
        resize_short: 256
    - CropImage:
        size: 224
    - NormalizeImage:
        scale: 0.00392157
        mean: [0.485, 0.456, 0.406]
        std: [0.229, 0.224, 0.225]
        order: ""
        channel_num: 3
    - ToCHWImage:
PostProcess:
  main_indicator: Topk
  Topk:
    topk: 5
    class_id_map_file: "../ppcls/utils/imagenet1k_label_list.txt"

其中 PreProcess 定义了 ImageNet 分类标准的预处理流水线(先缩放到短边 256,再中心裁剪 224×224,随后按 ImageNet 均值方差归一化,最后转为 CHW 布局);PostProcess 中的 Topk 定义了输出 Top-5 类别,并通过 class_id_map_file 指向 imagenet1k_label_list.txt 完成类别 ID 到标签名的映射。这份 YAML 是 infer.cc 加载模型时的必读配置文件。

4. 部署量化后的 ResNet50_vd:完整操作步骤

以下步骤以 ResNet50_vd 量化模型为例,完整串联“交叉编译库 → 下载示例代码与模型 → 编译示例 → adb 部署”全流程。

4.1 获取部署示例代码

可以从 FastDeploy 仓库或 PaddleClas 仓库获取示例代码:

# 方式一:从 FastDeploy 仓库获取
git clone https://github.com/PaddlePaddle/FastDeploy.git
cd FastDeploy/examples/vision/classification/paddleclas/amlogic/a311d/cpp/

# 方式二:从 PaddleClas 仓库获取(本仓库即对应目录)
git clone https://github.com/PaddlePaddle/PaddleClas.git
# 注意:如果当前分支找不到 fastdeploy 测试代码,请切换到 develop 分支
git checkout develop
cd PaddleClas/deploy/fastdeploy/amlogic/a311d/cpp/

以本仓库为准:示例位于 deploy/fastdeploy/amlogic/a311d/cpp/,内含 infer.cc、CMakeLists.txt、run_with_adb.sh 与 README.md 四个文件。

4.2 拷贝交叉编译产物

将第 2 步交叉编译好的 FastDeploy 库拷贝到当前目录:

cp -r FastDeploy/build/fastdeploy-timvx/ ./

执行后,当前目录下应出现 fastdeploy-timvx/ 目录(内含 toolchain.cmake 与完整的 FastDeploy SDK)。

4.3 下载模型与示例图片

mkdir models && mkdir images
wget https://bj.bcebos.com/paddlehub/fastdeploy/resnet50_vd_ptq.tar
tar -xvf resnet50_vd_ptq.tar
cp -r resnet50_vd_ptq models
wget https://gitee.com/paddlepaddle/PaddleClas/raw/release/2.4/deploy/images/ImageNet/ILSVRC2012_val_00000010.jpeg
cp -r ILSVRC2012_val_00000010.jpeg images

该示例图片与本仓库 deploy/images/ImageNet/ 目录下的 ILSVRC2012_val_00000010.jpeg 为同一张 ImageNet 验证集图片。若你的量化模型是自己用 auto_compression 产出的,请记得按第 3.2 节补充 inference_cls.yaml 到 models 目录。

4.4 编译部署示例

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

三个 CMake 参数的含义如下:

参数 作用
CMAKE_TOOLCHAIN_FILE 指定交叉编译工具链文件(来自 fastdeploy-timvx)
FASTDEPLOY_INSTALL_DIR 指向已下载/编译的 FastDeploy SDK 根目录
TARGET_ABI=arm64 目标平台 ABI,A311D 为 64 位 ARM 平台

成功编译并执行 make install 后,会生成 install/ 文件夹,里面包含一个可运行的 demo(infer_demo)以及部署所需的全部动态库。这一步的具体逻辑可对照 CMakeLists.txt:工程通过 include(${FASTDEPLOY_INSTALL_DIR}/FastDeploy.cmake) 引入 FastDeploy 构建体系,链接 infer.cc 生成 infer_demo,并把 models/、images/ 目录、全部 lib*.so* 动态库(含第三方依赖库)以及 run_with_adb.sh 统一安装进 build/install。

4.5 基于 adb 部署到 A311D

# 进入 install 目录
cd build/install/
# 用法:bash run_with_adb.sh 需要运行的demo 模型路径 图片路径 设备的DEVICE_ID
bash run_with_adb.sh infer_demo resnet50_vd_ptq ILSVRC2012_val_00000010.jpeg $DEVICE_ID

其中 $DEVICE_ID 是 adb 设备号,可通过 adb devices 查看,不填则默认使用唯一设备(此时脚本内部将 ADB_DEVICE_NAME 置空)。

部署成功后的运行结果示意图参见原文档(FastDeploy 仓库中的运行截屏),其输出为 Top-5 分类结果(类别 ID、标签名与置信度)。该结果由 infer.cc 中的 std::cout << res.Str() << std::endl; 打印。

5. 源码级解读:infer.cc 的推理链路

infer.cc 虽然只有约 60 行,但完整覆盖了“启用图像加速 → 配置 NPU 后端 → 加载量化模型 → 预测 → 输出结果”的整条链路。核心函数 InitAndInfer 逐段拆解如下:

void InitAndInfer(const std::string &model_dir, const std::string &image_file) {
  // 1. 拼接模型文件路径:量化模型目录下的固定文件名
  auto model_file = model_dir + sep + "inference.pdmodel";
  auto params_file = model_dir + sep + "inference.pdiparams";
  auto config_file = model_dir + sep + "inference_cls.yaml";
  // 2. 启用 FlyCV 图像加速库(ARM 平台常用的高性能图像处理库)
  fastdeploy::vision::EnableFlyCV();
  // 3. 创建推理运行时选项,并显式指定 TimVX(芯原 NPU)后端
  fastdeploy::RuntimeOption option;
  option.UseTimVX();
  // 4. 构建 PaddleClas 分类模型
  auto model = fastdeploy::vision::classification::PaddleClasModel(
      model_file, params_file, config_file, option);
  // 5. 校验模型是否初始化成功
  assert(model.Initialized());
  // 6. 读取输入图片并执行预测
  auto im = cv::imread(image_file);
  fastdeploy::vision::ClassifyResult res;
  if (!model.Predict(im, &res)) {
    std::cerr << "Failed to predict." << std::endl;
    return;
  }
  // 7. 输出分类结果(Top-5 文本)
  std::cout << res.Str() << std::endl;
}

几个关键点值得展开说明:

  • 模型文件命名约定:inference.pdmodel / inference.pdiparams 是 Paddle 推理模型的标准导出文件名,inference_cls.yaml 则是 PaddleClas 推理配置(见第 3.2 节,自行量化的模型务必补齐该文件)。
  • option.UseTimVX():这是整条链路中“上 NPU”的关键一行。TimVX 是芯原 NPU 的运行时抽象层,FastDeploy 通过它把算子调度到 NPU 硬件上执行,从而实现加速。
  • EnableFlyCV():启用 FlyCV 后,图像预处理(resize/crop/normalize)可在 CPU 侧使用 SIMD 优化加速,与 NPU 推理形成“CPU 预处理 + NPU 推理”的协同流水线。
  • res.Str():ClassifyResult 的字符串化输出,直接打印 Top-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];
InitAndInfer(model_dir, test_image);

即运行时需要两个参数:量化模型目录路径 + 测试图片路径,与 run_with_adb.sh 中传递的 MODEL_NAME、IMAGE_NAME 一一对应。

6. 源码级解读:run_with_adb.sh 的部署编排

run_with_adb.sh 是一个“一键部署”脚本,支持最多 4 个位置参数,且全部带默认值:

参数 默认值 含义
$1 DEMO_NAME image_classification_demo 可执行 demo 名(本示例传 infer_demo)
$2 MODEL_NAME mobilenet_v1_fp32_224 模型目录名(位于 models/ 下)
$3 IMAGE_NAME 0001.jpg 测试图片名(位于 images/ 下)
$4 ADB_DEVICE_NAME 空(不指定) adb 设备号,传值时自动加 -s 前缀

脚本的关键逻辑分为四步:

1. 设置板端环境变量(这是 NPU 稳定运行的隐藏关键):

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 LD_LIBRARY_PATH=${WORK_SPACE}/lib:$LD_LIBRARY_PATH;

这些变量分别控制 TimVX/NPU 驱动日志级别、图变换(PCQ 量化图优化)、逐通道熵校准、BN 融合容差以及动态库搜索路径。如果部署时出现 NPU 算子编译失败或精度异常,优先检查这组环境变量是否已正确导出。

2. 清理并创建板端工作目录:

set -e
adb $ADB_DEVICE_NAME shell "rm -rf $WORK_SPACE"
adb $ADB_DEVICE_NAME shell "mkdir -p $WORK_SPACE"

WORK_SPACE 固定为 /data/local/tmp/test,set -e 保证任一步失败即中止,避免脏环境残留。

3. 推送依赖到板端:通过 adb push 依次上传动态库目录 lib/、可执行 demo、models/ 与 images/ 到 /data/local/tmp/test。其中 lib/ 正是 make install 时由 CMake 收集的全部 lib*.so*(含 FastDeploy 主库与 third_libs 第三方依赖)。

4. 在板端执行推理:

adb $ADB_DEVICE_NAME shell "cd $WORK_SPACE; ${EXPORT_ENVIRONMENT_VARIABLES} chmod +x ./${DEMO_NAME}; ./${DEMO_NAME} ./models/${MODEL_NAME} ./images/$IMAGE_NAME"

即在板端 cd 到工作目录、导出环境变量、赋予执行权限,然后以“模型目录 + 图片路径”为参数运行 demo,与 infer.cc 的 main 参数约定完全吻合。

7. 常见问题与排查要点

基于上文对源码与配置的分析,总结部署时的关键排查点:

  1. 模型未量化:A311D(TimVX 后端)只接受量化模型,直接部署 FP32 模型会报算子不支持或初始化失败。确认模型来自 FastDeploy 预量化产物或 auto_compression 产出。
  2. 缺少 inference_cls.yaml:自行量化的模型目录通常没有该文件,需从 FP32 模型目录复制,否则 infer.cc 加载 PaddleClasModel 时无法获得预处理/后处理配置(报 Initialized() 失败)。
  3. 交叉编译环境不匹配:务必使用 FastDeploy 官方 A311D 交叉编译流程产出 fastdeploy-timvx,并用其自带的 toolchain.cmake 编译示例,避免宿主工具链导致 ABI 不兼容。
  4. NPU 运行异常:优先检查 run_with_adb.sh 中导出的 VIV_VX_* / TIMVX_* 环境变量是否生效;GLOG_v 与 VSI_NN_LOG_LEVEL 设为 5 时日志最详细,可据此定位具体算子。
  5. adb 设备未识别:在主机上执行 adb devices 确认 $DEVICE_ID,多设备时必须显式传入;不要在 Docker 容器内运行 adb(脚本注释中已明确提示)。

8. 小结

本文以仓库内 A311D C++ 部署示例 为主线,完整覆盖了晶晨 A311D(芯原 NPU)上部署 PaddleClas 量化分类模型的全部环节:从环境与量化模型准备、交叉编译与 CMake 构建、adb 一键部署,到 infer.cc 与 run_with_adb.sh 的逐行源码解读。核心要点可归纳为三句话:

  • NPU 后端决定了模型必须量化,且量化后仍需补齐 FP32 模型中的 inference_cls.yaml;
  • TimVX 是芯原 NPU 的推理通道,UseTimVX() 一行即完成后端切换,EnableFlyCV() 则加速预处理;
  • run_with_adb.sh 把交叉编译产物与板端环境变量编排成一条命令,是快速复现与验证部署流程的最短路径。

如需在 C308X、S905D3 等其他芯原 NPU 芯片上部署,方法与 A311D 完全一致;若需更多量化模型,可借助 FastDeploy 的一键模型自动化压缩工具自行产出。

登录后查看全文
PaddleClas