PaddleClas 量化模型在晶晨 A311D(芯原 NPU)上的 FastDeploy C++ 部署实战
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. 部署环境准备
在开始部署前,必须完成两步环境准备:
- 确认目标板为 A311D(或上述兼容芯片),并确保板卡可正常通过 USB 被主机识别(后续 adb 调试依赖这一点)。
- 自行编译基于 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. 常见问题与排查要点
基于上文对源码与配置的分析,总结部署时的关键排查点:
- 模型未量化:A311D(TimVX 后端)只接受量化模型,直接部署 FP32 模型会报算子不支持或初始化失败。确认模型来自 FastDeploy 预量化产物或 auto_compression 产出。
- 缺少
inference_cls.yaml:自行量化的模型目录通常没有该文件,需从 FP32 模型目录复制,否则 infer.cc 加载PaddleClasModel时无法获得预处理/后处理配置(报Initialized()失败)。 - 交叉编译环境不匹配:务必使用 FastDeploy 官方 A311D 交叉编译流程产出
fastdeploy-timvx,并用其自带的toolchain.cmake编译示例,避免宿主工具链导致 ABI 不兼容。 - NPU 运行异常:优先检查 run_with_adb.sh 中导出的
VIV_VX_*/TIMVX_*环境变量是否生效;GLOG_v与VSI_NN_LOG_LEVEL设为 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 的一键模型自动化压缩工具自行产出。