3.2. AI算法模型PTQ量化+上板快速上手¶

本章节中，我们为您介绍浮点转换工具链PTQ方案的基本使用流程，便于您实现快速上手。这里我们以 MobileNet-v1 模型为例，为您进行使用演示，详细内容将在后续章节为您展开介绍，基本工作流程如下图所示。

3.2.1. 准备开发环境¶

开发环境准备包括开发机 host 端（用于模型转换）和开发板 board 端（用于模型部署），地平线的 OE包分别提供了一键安装脚本。地平线建议您使用Docker方式，以避免在安装过程中出现问题。以下示例以docker方式为例，完整的环境部署相关内容请您参考环境部署章节。

开发机环境安装指令：

# 进入OE包首层路径
cd horizon_j5_open_explorer_{version}_{date}

# 运行脚本启动Docker容器，/data请在使用时替换为您的校准/评测数据集路径
# 容器启动后，默认会将OE包挂载在/open_explorer，数据集挂载在/data/horizon_j5/data
bash run_docker.sh /data

Docker 容器成功启动后，可以在开发机端键入 ddk_vcs list 命令查看工具链各模块的版本号。

开发板环境安装指令：

# 进入板端安装包路径
cd ddk/package/board

# {board_ip}为开发板IP地址，执行前请确保您的开发机能够访问
bash install.sh {board_ip}

执行完成后，可以在板端键入 hrt_model_exec --help 确认相关工具已成功安装。

3.2.2. 浮点模型准备¶

地平线在OE包的 ddk/samples/ai_toolchain/model_zoo/mapper 路径下为您提供了丰富的示例模型。如您需要转换私有模型，请参考浮点模型准备章节内容提前准备好 caffe1.0 或 opset=10/11 的 onnx 模型。

3.2.3. 模型检查¶

模型正式转换前，请先使用 hb_mapper checker 工具进行模型验证，确保其符合芯片支持约束，详细说明请您参考验证模型章节。

# 进入浮点模型转换示例目录
cd ddk/samples/ai_toolchain/horizon_model_convert_sample/

# 进入MobileNet-v1模型目录
cd 03_classification/01_mobilenet/mapper

# 模型检查，确认模型结构及算子是否支持，并提供每个算子执行硬件的分配情况（BPU/CPU）
bash 01_check.sh

如果模型检查不通过，请根据终端打印或在当前路径下生成的 hb_mapper_checker.log 日志文件确认报错信息和修改建议。

3.2.4. 模型转换¶

模型检查通过后，请使用 hb_mapper makertbin 工具进行模型转换， yaml配置文件和校准数据集的具体准备工作请参考校准数据准备章节和模型量化与编译章节的相关内容。

# 校准数据预处理
bash 02_preprocess.sh

# 模型转换（转换时所需的配置文件请参考mobilenet_config.yaml）
bash 03_build.sh

模型转换完成后，会在yaml文件配置的 working_dir 路径下保存模型文件和静态性能评估文件，详细说明请参考转换产出物解读部分的相关内容。

|-- MOBILENET_subgraph_0.html        # 静态性能评估文件（可读性更好）
|-- MOBILENET_subgraph_0.json        # 静态性能评估文件
|-- mobilenetv1_224x224_nv12.bin     # 用于在地平线AI芯片上加载运行的模型
|-- mobilenetv1_224x224_nv12_optimized_float_model.onnx
|-- mobilenetv1_224x224_nv12_original_float_model.onnx
`-- mobilenetv1_224x224_nv12_quantized_model.onnx

3.2.5. 性能快速验证¶

针对 xxx.bin 模型文件，地平线支持先在开发机端预估模型的静态性能，在板端也提供给了无代码开发量的工具快速评测动态性能，具体说明和性能调优建议可参考模型性能分析与调优章节。

静态性能评估：

1.查看模型转换日志了解逐层算子的执行硬件和因CPU算子导致的模型分段情况。

2.查看模型转换生成的 html 文件获取模型 BPU 部分的预估性能和模型整体带宽占用情况。

3.可以使用 hb_perf 工具再次获取模型的性能预估文件，具体可参考 hb_perf工具使用说明。

动态性能评估：

1.请首先确保已按照准备开发环境小节内容完成开发板环境部署。

2.将转换生成的 xxx.bin 模型拷贝至开发板 /userdata 文件夹下任意路径。

3.通过 hrt_model_exec perf 工具快捷评估模型的耗时和帧率，具体说明请参考 hrt_model_exec工具使用说明。

# 将模型拷贝至开发板
scp model_output/mobilenetv1_224x224_nv12.bin root@{board_ip}:/userdata

# 登录开发板评测性能
ssh root@{board_ip}
cd /userdata

# 单BPU核单线程串行状态下评测latency
hrt_model_exec perf --model_file mobilenetv1_224x224_nv12.bin --core_id 1 --thread_num 1 --frame_count 1000

# 双BPU核多线程并发状态下评测FPS
hrt_model_exec perf --model_file mobilenetv1_224x224_nv12.bin --core_id 0 --thread_num 4 --frame_count 1000

3.2.6. 精度验证¶

在正式进行精度评测前，请确保您已经准备好相关评测数据集，并挂载在Docker容器中。示例模型所依赖的评测数据集请联系地平线工程师或开发者社区助手进行获取。详细的精度验证和优化建议您可以参考模型精度分析与调优章节的内容。

3.2.6.1. 开发机Python环境验证¶

地平线建议您优先在开发机Python环境中评测 xxx_quantized_model.onnx 模型的量化精度，其输出与 xxx.bin 模型是保持数值一致的，而评测方式却更加简单快捷，参考示例如下：

##### 开发机Python环境评测 #####

# 测试量化模型单张图片推理结果
bash 04_inference.sh

# 测试浮点模型单张图片推理结果（可选）
bash 04_inference.sh origin

# 测试量化模型精度，请确保您的评测数据集已正确挂载在Docker容器中
bash 05_evaluate.sh

# 测试浮点模型精度（可选）
bash 05_evaluate.sh origin

3.2.6.2. 开发板C++环境验证¶

在开发板端，地平线提供了一套适配所有硬件平台的嵌入式端预测库LibDNN，来帮助用户快速完成模型的部署工作，并提供了相关示例。预测库API介绍请参考 BPU SDK API手册。常用API示例可参考基础示例包使用说明。 MobileNet-v1 模型推理单张图片的板端示例运行方式如下：

# 开发机环境执行交叉编译，生成可执行程序
cd /open_explorer/ddk/samples/ai_toolchain/horizon_runtime_sample/code
bash build_j5.sh

# 拷贝j5目录至板端
cd ../j5/model
mkdir runtime
scp -r ../../j5/ root@{board_ip}:/userdata
# 拷贝模型文件至板端
scp -r ../../../model_zoo/runtime/mobilenetv1/ root@{board_ip}:/userdata/j5/model/runtime

# 登录开发板环境
ssh root@{board_ip}
# 进入j5/script/目录下，执行相应运行脚本即可
cd /userdata/j5/script/00_quick_start/
bash run_mobilenetV1.sh

此外，我们还在 ddk/samples/ai_benchmark/ 路径下提供了典型分类、检测、分割模型的性能和精度评测示例，以便于开发者快速复现Benchmark指标，具体操作可参考 AI-Benchmark使用说明。

# 开发机环境完成交叉编译
cd /open_explorer/ddk/samples/ai_benchmark/code
bash build_ptq_j5.sh
scp -r ../j5/ptq root@{board_ip}:/userdata

# 将模型文件也拷贝至板端
scp -r ../../model_zoo/runtime root@{board_ip}:/userdata/ptq/model

接着我们需要完成一些精度验证前的准备工作，包括：

1.数据预处理

以 ImageNet 数据集为例，开发机端运行MobileNet-v1模型的预处理命令如下：

hb_eval_preprocess -m mobilenetv1 -i imagenet/val -o ./pre_mobilenetv1

hb_evel_preprocess 工具封装了地平线示例模型的前处理操作，如resize、crop、padding等，工具常用参数包括：

-m 传入模型名称。
-i 传入输入图片路径。
-o 传入输出路径。

详细说明可参考 hb_eval_preprocess 工具使用说明。

2.数据挂载

由于数据集较大，不适合直接存放在开发板上，所以我们可以采用挂载的方式（服务器PC端需要root权限）供开发板读取，挂载步骤如下：

开发机端

1). 服务器PC端编辑 /etc/exports ，增加一行 /nfs *(insecure,rw,sync,all_squash,anonuid=1000,anongid=1000,no_subtree_check) 。其中， /nfs 表示的是本机挂载路径，可替换为用户指定目录。

2). 执行命令 exportfs -a -r ，使 /etc/exports 生效。

开发板端

1). 开发板端创建需要挂载的目录： mkdir -p /mnt 。

2). 输入指令完成挂载： mount -t nfs {PC端ip}:/nfs /mnt -o nolock 。

完成后需要再将 /mnt 目录下的预处理数据路径软连接替换至开发板 /userdata/ptq/data 路径下。

# 进入到开发板ptq文件夹下
cd /userdata/ptq
rm -rf ./data
ln -s /mnt/data ./data

3.生成 lst 文件

最后在板端执行以下命令完成lst文件的生成，lst文件包含了每一个预处理文件的路径。

find /userdata/ptq/data/imagenet/pre_mobilenetv1 -name "*bin" > /userdata/ptq/data/imagenet/pre_mobilenetv1/imagenet.lst

以上准备工作完成后的板端目录结构应如下所示：

|-- ptq
|   |-- data
|   |   |-- imagenet
|   |   |   |-- pre_mobilenetv1
|   |   |   |   |-- xxxx.bin         # 预处理好的二进制文件
|   |   |   |   |-- ...
|   |   |   |   |-- imagenet.lst     # lst文件：记录每一个预处理文件的路径
|   |-- model
|   |   |-- runtime
|   |   |   |-- mobilenetv1
|   |   |   |-- ...
|   |-- script
|   |   |-- ...

接着，我们便可以在板端执行相关脚本完成模型的精度评测。

注意

下方脚本执行前请先确认workflow_accuracy.json中的lst文件路径正确。

精度评测脚本的执行命令参考如下：

cd /userdata/ptq/script/classification/mobilenetv1
bash accuracy.sh

脚本执行完成后，会在当前路径生成模型预测结果文件eval.log。

3.2.6.3. 精度计算¶

计算模型精度请将eval.log文件拷贝回开发机端OE包的任意位置，并执行以下脚本：

python3 /open_explorer/ddk/samples/ai_benchmark/j5/ptq/tools/python_tools/accuracy_tools/cls_eval.py --log_file ./eval.log --gt_file /data/imagenet/val.txt

3.2.7. 应用开发¶

当模型的性能和精度验证都符合预期后，即可参考 runtime应用开发指导章节实现上层应用的具体开发。

3.2. AI算法模型PTQ量化+上板 快速上手¶