天工开物（Open Explorer，OE）是基于地平线硬件开发的算法全生命周期开发平台，主要包括芯片算法工具链、芯片算法仓库和应用开发SDK三大功能模块。其中，芯片算法工具链覆盖了模型训练（浮点训练和量化训练，可选）、转换、性能/精度验证、部署和推理等关键步骤。为了方便用户快速体验和学习地平线芯片算法工具链，OE开发包中提供了丰富、全面的示例。为了方便用户了解和使用这些示例，本文将对这些示例进行详细介绍。-
首先，用户在获取OE开发包后，解压后的文件目录结构如下所示：
|-- bsp #系统镜像
|-- ddk #主要开发组件
| |-- package
| |-- samples #示例
| | |-- ai_benchmark #常见的分类、检测和分割模型的评测示例
| | |-- ai_forward_view_sample #全链路示例
| | |-- ai_toolchain #浮点模型训练、转换、部署示例
| | |-- model_zoo #模型文件
| | `-- vdsp_rpc_sample #DSP开发示例
| `-- tools
|-- doc
|-- run_docker.sh
`-- tools
其中，ddk/samples目录中提供了模型训练示例、浮点模型转定点模型示例、定点模型上板部署示例、AI Benchmark评测示例、目标检测全链路示例和DSP开发示例。下图为工具链使用的一般流程和示例的分布，让我们一起来看一下工具链各使用阶段分别有哪些示例吧：-
在上图工具链的使用流程中，这些示例对应着不同的使用阶段：
- 模型转换示例包含了模型PTQ转换阶段的模型检查、校准数据处理、模型量化编译、单张图片推理和精度评估等过程；
- 模型训练示例包含了**浮点模型训练（可选）和QAT量化训练（可选）**阶段的数据集打包脚本、模型config文件、训练脚本以及其它工具脚本，当应用模型精度调优手段后仍未达到预期精度时，可以尝试QAT量化训练策略；
- 板端部署示例包含了模型部署阶段的编译脚本、运行脚本和源代码；
- AI Benchmark示例提供了Runtime应用开发常见分类、检测、分割和光流估计模型的性能和精度评测示例；
- 目标检测全链路示例展示如何在芯片上运行从Camera接入到目标检测模型推理的过程，并在web端展示结果；
- DSP开发示例展示了如何在j5芯片上使用DSP进行模型推理任务。
1. 模型训练示例
通过部署地平线的海图（Horizon Algorithm Toolkit，HAT）训练环境，可以实现模型的浮点训练和量化感知训练。ddk/samples/ai_toolchain/horizon_model_train_sample/目录下提供了模型训练示例，示例包结构如下所示：
├─release_models #模型和权重文件
└─scripts
├─configs #模型配置文件
│ ├─classification
│ ├─detection
│ ├─opticalflow_pred
│ └─segmentation
└─tools #执行脚本
├─datasets
├─align_bpu_validation.py
├─calops.py
├─compile_perf.py
├─creat_data.py
├─dataset_mappings.py
├─datasets
├─export_onnx.py
├─infer.py
├─infer_lidar.py
├─model_checker.py
├─predict.py
└─train.py
通常只需要使用以下命令就可以实现模型的训练：
python3 tools/train.py --stages TRAINING_STAGES --config /PATH/TO/CONFIG
- TRAINING_STAGES指的是不同的训练阶段，可选为float, qat, int_infer，分别对应着浮点训练、量化训练和定点模型转化预测阶段。
- /PATH/TO/CONFIG 就是configs文件夹中模型训练对应的 config 文件，它定义了模型结构、数据集加载、以及整套的训练流程，示例中提供了包括分类、检测、分割和光流估计任务的模型。
- tools文件夹提供了包含数据集处理、模型训练、转换编译、计算量统计等执行脚本，相关脚本的功能如下:-
train.py：模型训练脚本，支持浮点模型训练、量化训练功能-
calops.py：网络模型计算量统计工具-
align_bpu_validation.py：精度验证工具，提供和板端完全对齐的结果-
compile_perf.py：模型编译和perf工具-
create_data.py：数据集预处理工具-
export_onnx.py：onnx模型导出工具-
infer.py：单图预测和结果可视化工具-
infer_lidar.py：点云模型可视化工具-
model_checker.py：模型检查工具-
predict.py：模型精度验证工具 - tools/dataset 文件夹下还提供了数据集打包和数据可视化脚本。
- release_models文件夹下包含了模型的权重文件和板端部署的模型。
模型训练示例的使用教程可以参考用户手册进阶内容-Horizon Torch Samples。
2. 模型转换示例
ddk/samples/ai_toolchain/horizon_model_convert_sample文件夹下提供了模型转换示例，示例包目录结构如下所示：
|-- 01_common #校准数据、数据加载、预处理代码
|-- 02_preq_examples #QAT转换示例
|-- 03_classification #分类模型转换示例
|-- 04_detection #检测模型转换示例
|-- 05_miscellaneous #杂项示例，gray/feathermap输入，api使用
|-- 06_custom_op #自定义算子示例
|-- 07_segmentation #分割模型转换示例
OE包里不仅提供了PTQ模型、QAT模型、特别输入、自定义算子模型转换示例，另外还包含了模型检查、校准数据预处理、转换编译、推理等一键运行脚本。如下为目录中相关示例的分布：
-
本文以
horizon_model_convert_sample/03_classification/01_mobilenet/mapper目录下的mobilenet为例，介绍相关脚本的作用：
|-- 01_check.sh #模型检查脚本
|-- 02_preprocess.sh #校准数据预处理脚本
|-- 03_build.sh #模型量化编译脚本
|-- 04_inference.sh #单张图片推理脚本
|-- 05_evaluate.sh #精度评测脚本
|-- mobilenet_config.yaml #模型编译yaml配置文件
|-- postprocess.py #模型后处理代码
|-- preprocess.py #数据预处理代码
`-- README.cn.md
PTQ模型转换示例的使用教程请参考PTQ模型转换示例手册。
3. 板端部署示例
ddk/samples/ai_toolchain/horizon_runtime_sample目录下提供了模型部署示例的源代码和运行脚本，示例包结构如下所示：
+---horizon_runtime_sample
├── code # 示例源码
│ ├── 00_quick_start # 快速入门示例,用mobilenetv1读取单张图片进行推理的示例代码
│ ├── 01_api_tutorial # dnn API使用示例代码
│ │ ├── CMakeLists.txt
│ │ ├── mem #内存处理相关api使用示例
│ │ ├── model #模型信息读取相关api使用示例
│ │ ├── roi_infer #roi infer api使用示例
│ │ └── tensor #准备模型输入和输出的tensor api使用示例
│ ├── 02_advanced_samples # 特殊功能示例
│ │ ├── CMakeLists.txt
│ │ ├── custom_identity #自定义算子推理示例
│ │ ├── multi_input #多输入模型推理示例
│ │ ├── multi_model_batch #多个小模型批量推理示例
│ │ └── nv12_batch #batch模型推理示例
│ ├── 03_misc # 杂项示例
│ │ ├── CMakeLists.txt
│ │ ├── lenet_gray #gray输入示例
│ │ └── resnet_feature #featuremap输入示例
│ ├── build_j5.sh # 编译脚本
│ ├── build_x86.sh # x86仿真平台编译脚本
│ ├── CMakeLists.txt
│ ├── CMakeLists_x86.txt
│ └── deps_gcc9.3 # 编译依赖库
├── j5
│ ├── data # 预置数据文件
│ ├── model #模型文件
│ └── script # aarch64示例运行脚本
│ │ ├── 00_quick_start # 快速入门示例
│ │ ├── 01_api_tutorial # dnn API使用示例代码
│ │ ├── 02_advanced_samples # 特殊功能示例
│ │ ├── 03_misc # 杂项示例
│ │ ├── aarch64 # 编译产生aarch64可执行程序及依赖库
│ │ └── README.md
│ └── script_x86 # x86示例运行脚本
│ ├── 00_quick_start
│ ├── x86 # 编译产生x86可执行程序及依赖库
│ └── README.md
└── README.md
- 00_quick_start：快速入门示例，基于 dnn API，以mobilenetv1模型为例进行单张图片模型推理和结果解析。
- 01_api_tutorial：dnn API使用教学代码， 包括:-
-- mem：内存使用相关API（ hbSysAllocMem、hbSysFlushMem 和 hbSysFreeMem ）示例-
--model：模型信息读取API示例-
--roi_infer ：roi推理API示例-
--tensor ：模型输入和输出tensor准备API示例 - 02_advanced_samples：特殊功能示例，包括：-
--custom_identity：自定义算子推理示例-
--multi_input：多输入模型推理示例-
--multi_model_batch：多个小模型批量推理示例-
--nv12_batch ：batch模型推理示例 - 03_misc：非NV12输入模型的杂项示例。
- j5：示例运行脚本，预置了数据集和相关模型。
- build_j5.sh：程序一键编译脚本。
- build_x86.sh：x86仿真环境一键编译脚本。
- deps_gcc9.3：示例代码所需要的三方依赖, 用户在开发自己代码程序的时候可以根据实际情况替换或者裁剪。
模型部署示例使用教程可以参考用户手册基础示例包使用说明。
4. AI Benchmark评测示例
AI Benchmark示例包提供了Runtime应用开发常见分类、检测、分割和光流估计模型的性能和精度评测示例。 示例包中预置了模型推理和后处理源码、可执行程序和评测脚本，开发者可以在地平线开发板上进行体验，并基于这些示例直接进行应用开发，降低开发门槛。AI Benchmark示例使用教程可以参考用户手册AI-Benchmark使用说明。-
AI Benchmark示例包位于ddk/samples/ai_benchmark/ 目录下，主要包括以下内容：
编号
名称
内容
1
code
包含示例源码和编译脚本
2
j5
示例包上板运行环境
示例包结构如下所示：
ai_benchmark/code/ # 示例源码文件夹
├── build_ptq_j5.sh #ptq示例编译脚本
├── build_qat_j5.sh #qat示例编译脚本
├── CMakeLists.txt
├── deps_gcc9.3 # 第三方依赖库
├── include # 源码头文件
└── src # 示例源代码
ai_benchmark/j5 # 示例包运行环境
├── ptq # PTQ方案模型示例
│ ├── data # 模型精度评测数据集
│ ├── mini_data # 模型性能评测数据集
│ ├── model # PTQ方案nv12模型
│ ├── script # 执行脚本
│ │ ├── aarch64 # 编译产生可执行文件及依赖库
│ │ ├── classification # 分类模型示例
| │ │ ├── efficientnasnet_m
| | | | |-- accuracy.sh #板端精度评测脚本
| | | | |-- fps.sh #板端fps评测脚本
| | | | |-- latency.sh #板端latency评测脚本
| | | | |-- workflow_accuracy.json
| | | | |-- workflow_fps.json
| | | | |-- workflow_latency.json
| │ │ ├── ..... #其他示例
│ │ ├── config # 模型推理配置文件
│ │ ├── detection # 检测模型示例
│ │ ├── segmentation # 分割模型示例
│ │ ├── env.sh # 基础环境脚本
│ └── tools # 精度评测工具
└── qat # QAT方案模型示例
├── data # 模型精度评测数据集
├── mini_data # 模型性能评测数据集
├── model # QAT方案nv12模型
├── script # 执行脚本
│ ├── aarch64 # 编译产生可执行文件及依赖库
│ ├── classification # 分类模型示例
| | |-- mobilenetv1
| | | |-- accuracy.sh #板端精度评测脚本
| | | |-- fps.sh #板端fps评测脚本
| | | |-- latency.sh #板端latency评测脚本
| | | |-- workflow_accuracy.json
| | | |-- workflow_fps.json
| | | |-- workflow_latency.json
| | |-- ..... #其他示例
│ ├── config # 模型推理配置文件
│ ├── detection # 检测模型示例
│ ├── opticalflow # 光流模型示例
│ ├── segmentation # 分割模型示例
│ ├── env.sh # 基础环境脚本
└── tools # 前处理及精度评测工具
5. 目标检测全链路示例
目标检测全链路示例包展示如何在芯片上运行一个检测模型并在web端展示结果。全链路示例包位于ddk/samples/ai_forward_view_sample/目录下，主要包括以下内容：
ai_forward_view_sample/
|-- build_and_deploy.sh #编译脚本
|-- CMakeLists.txt
|-- configs #配置文件
| |-- codec #摄像头图像编码配置文件
| |-- data #数据
| |-- model #hbm模型和后处理配置文件
| |-- vio #输入配置文件
|-- deps #依赖库
|-- include #源码头文件
|-- README.md
|-- run_sample.sh #示例运行脚本
|-- src #源代码
`-- tools #web端展示和回灌工具
- configs/vio/vin/camera:Camera输入数据模式配置
- configs/vio/vin/network:网络回灌输入模式配置
全链路示例使用教程请参考社区文章J5全流程示例解读。
6. DSP开发示例
地平线J5芯片中包含两个拥有强大的计算能力的DSP核，可以将一些不能用BPU加速且ARM低效的计算部署到DSP上，从而可以大大提高模型的推理性能。ddk/samples/vdsp_rpc_sample目录下提供了DSP开发示例，展示了如何在j5上采用自定义算子进行mobilenetv1的推理，示例包结构如图所示：
+---vdsp_rpc_sample
├── arm # arm侧
│ ├── mobilenetv1_with_custom_dsp_softmax
│ │ ├── custom_dsp_softmax.cpp # arm侧自定义算子实现
│ │ ├── custom_dsp_softmax.h
│ │ ├── main.cpp # main函数
│ │ └── CMakeLists.txt
│ ├── script # 示例运行脚本
│ ├── util
│ ├── build.sh #编译脚本
│ └── CMakeLists.txt
├── dsp # dsp侧
│ ├── build.sh #编译脚本
│ ├── CMakeLists.txt
│ ├── common.h
│ ├── dequantize # dsp侧dequantize算子实现
│ ├── main.cc
│ ├── output_image
│ ├── quantize # dsp侧quantize算子实现
│ └── softmax # dsp侧softmax算子实现
├── dsp_wrap
│ ├── build
│ ├── build.sh
│ ├── CMakeLists.txt
│ ├── output
│ └── src
├── deps # 示例依赖库
│ ├── aarch64 # arm侧库目录
│ └── vdsp # dsp侧库目录
└── README.md
- arm：arm侧自定义softmax算子实现示例，主要负责发起rpc调用dsp执行任务。
- dsp：dsp侧自定义softmax算子实现示例，主要负责接收arm侧发来的任务，完成计算后将结果发送给arm。
- dsp_wrap：dsp自定义算子封装，用于libdnn发起rpc调用。
- deps：arm和dsp程序的依赖文件。
DSP开发示例使用教程可以参考社区文章DSP开发快速上手。