#hrt_model_exec工具介绍

#工具简介

hrt_model_exec 是一个模型执行工具，可直接在开发板上评测模型的推理性能、获取模型信息。 一方面可以让用户拿到模型时实际了解模型真实性能； 另一方面也可以帮助用户了解模型可以做到的速度极限，对于应用调优的目标极限具有指导意义。

hrt_model_exec 工具源码位于 horizon_j6_open_explorer 发布物的 samples/ucp_tutorial/tools/hrt_model_exec 路径下。结构如下所示：

hrt_model_exec 工具分别提供了模型推理 infer、模型性能分析 perf 和查看模型信息 model_info 三类功能，如下表：

编号	子命令	说明
1	model_info	获取模型信息，如：模型的输入输出信息等。
2	infer	执行模型推理，获取模型推理结果。
3	perf	执行模型性能分析，获取性能分析结果。

工具可以通过 -v 或者 --version 命令，查看工具的 dnn 预测库版本号。

#参数描述

参数	类型	说明
model_file	string	模型文件路径，多个路径可通过逗号分隔。
model_name	string	指定模型中某个模型的名称。
core_id	int	指定运行核。0：任意核，1：core0；默认为 0。
input_file	string	模型输入信息。 输入后缀必须为 PNG/JPG/JPEG/png/jpg/jpeg/bin/txt 中的一种。每个输入之间需要用英文字符的逗号隔开,，如：xxx.jpg,input.txt。
input_img_properties	string	模型图像输入的色彩空间信息。 input_file 中每一个图片类型输入都需要指定一个 Y/UV 类型，每个输入色彩空间之间需要用英文字符的逗号隔开,，如：Y,UV。
input_valid_shape	string	模型动态 validShape 输入信息。 若模型输入属性 validShape 中含有 -1，则需要将 -1 的部分进行补全，多个 validShape 间通过英文分号间隔。如：--input_valid_shape="1,376,376,1;1,188,188,2"
input_stride	string	模型动态 stride 输入信息。 若模型输入属性 stride 中含有 -1，则需要将 -1 的部分进行补全，多个 stride 间通过英文分号间隔。如：--input_stride="144384,384,1,1;72192,384,2,1"
roi_infer	bool	使能resizer模型推理。若模型存在resizer输入源的输入，需设置为 true，并且配置与输入源一一对应的 input_file 和 roi 参数。
roi	string	指定推理resizer模型时所需的roi区域，多个roi之间通过英文分号间隔。如：--roi="2,4,123,125;6,8,111,113"
frame_count	int	执行模型运行帧数。
dump_intermediate	string	dump模型每一层输入和输出。 dump_intermediate=0 时，默认dump功能关闭。 dump_intermediate=1 时，模型中每一层节点输入数据输出数据以 bin 方式保存， 其中节点输入输出为 stride 数据。 dump_intermediate=2 时，模型中每一层节点输入数据和输出数据以 bin 和 txt 两种方式保存，其中节点输入输出为 stride 数据。 dump_intermediate=3 时，型中每一层节点输入数据和输出数据以 bin 和 txt 两种方式保存，其中节点输入输出为 valid 数据。
enable_dump	bool	使能dump模型输入和输出，默认为 false。
dump_precision	int	控制txt格式输出float型数据的小数点位数，默认为 9。
dequantize_process	bool	对模型输出进行反量化处理，在 enable_dump 为 true 时生效，默认为 false。
remove_padding_process	bool	对模型输出进行去padding处理，在 enable_dump 为 true 时生效，默认为 false。
dump_format	string	dump模型输入和输出的格式。
dump_txt_axis	int	控制txt格式输入输出的换行规则。
enable_cls_post_process	bool	使能分类后处理，默认为 false。 子命令为 infer 时配合使用，目前只支持ptq分类模型的后处理，打印分类结果。
perf_time	int	执行模型运行时间。
thread_num	int	线程数(并行度)，数值可以表示最多有多少个任务在并行处理。 测试延时，数值需要设置为1，没有资源抢占发生，延时测试更准确。 测试吞吐，建议设置>2 (BPU核心个数)，调整线程数使BPU利用率尽量高，吞吐测试更准确。
profile_path	string	统计工具日志产生路径，运行产生profiler.log和profiler.csv，分析op耗时和调度耗时。一般设置 --profile_path="." 即可，代表在当前目录下生成日志文件。
dump_path	string	dump模型输入输出的路径，设置 enable_dump 或 dump_intermediate 时生效。

设置profile_path参数且工具正常运行后会产生profiler.log和profiler.csv文件，文件中包括如下参数：

• perf_result：记录perf结果。

参数	说明
FPS	每秒处理的帧数。
average_latency	指定模型中某个模型平均一帧运行所花费的时间。

• running_condition：运行环境信息。

参数	说明
core_id	程序运行设置的bpu核。
frame_count	程序运行的总帧数。
model_name	评测模型的名字。
run_time	程序运行时间。
thread_num	程序运行的线程数。

• model_latency：模型节点耗时统计。

参数	说明
Node-pad	模型输入padding耗时。
Node-NodeIdx-NodeType-NodeName	模型节点耗时信息。注：NodeIdx为模型节点拓扑排序的序号，NodeType为具体的节点类型，如Dequantize，NodeName为具体的节点名称。

• processor_latency：模型处理器耗时统计。

参数	说明
BPU_inference_time_cost	每帧推理BPU处理器耗时。
CPU_inference_time_cost	每帧推理CPU处理器耗时。

• task_latency：模型任务耗时统计。

参数	说明
TaskRunningTime	任务实际运行耗时，耗时时间包括UCP框架耗时。

#使用说明

工具提供三类功能：模型信息获取、单帧推理功能、多帧性能评测。

运行 hrt_model_exec、hrt_model_exec -h 或 hrt_model_exec --help 获取工具使用详情。如下所示：

#model_info

#概述

该参数用于获取模型信息，模型支持范围：qat模型，ptq模型。该参数与 model_file 一起使用，用于获取模型的详细信息，信息包括模型输入输出信息 hbDNNTensorProperties。

不指定 model_name 输出模型中所有模型信息，指定 model_name 则只输出对应模型的信息。

#示例

1. 单模型

2. 多模型（输出所有模型信息）

3. 多模型--pack模型（输出指定模型信息）

#infer

#概述

该参数用于模型推理，用户自定义输入图片，推理一帧。该参数需要与 input_file 一起使用，指定输入图片路径，工具根据模型信息resize图片，整理模型输入信息。

程序单线程运行单帧数据，输出模型运行的时间。

#示例

1. 单模型

2. 多模型

3. resizer模型

模型有三个输入，输入源顺序分别为[ddr, resizer, resizer]。

推理两帧数据，假设第一帧输入为[xx0.bin,xx1.jpg,xx2.jpg]，roi为[2,4,123,125;6,8,111,113]，第二帧输入为[xx3.bin,xx4.jpg,xx5.jpg]，roi为[27,46,143,195;16,28,131,183]，则推理命令如下：

#可选参数

参数	说明
core_id	指定模型推理的核id。
input_img_properties	模型图像输入的色彩空间信息。
input_valid_shape	模型动态 validShape 输入信息。
input_stride	模型动态 stride 输入信息。
roi_infer	使能resizer模型推理。
roi	roi_infer 为 true 时生效，设置推理resizer模型时所需的 roi 区域。
frame_count	设置 infer 运行帧数，单帧重复推理，可与 enable_dump 并用，验证输出一致性，默认为 1。
dump_intermediate	dump模型每一层输入数据和输出数据，默认值 0。
enable_dump	dump模型输入和输出数据，默认为 false。
dump_precision	控制txt格式输出float型数据的小数点位数，默认为 9。
dequantize_process	对模型输出进行反量化处理，在 enable_dump 为 true 时生效，默认为 false。
remove_padding_process	对模型输出进行去padding处理，在 enable_dump 为 true 时生效，默认为 false。
dump_format	dump模型输出文件的类型，可选参数为 bin 或 txt，默认为 bin。
dump_txt_axis	dump模型txt格式输出的换行规则；若输出维度为n，则参数范围为[0, n]， 默认为 -1，一行一个数据。
enable_cls_post_process	使能分类后处理，目前只支持ptq分类模型，默认 false。
dump_path	dump模型输入输出的路径，设置 enable_dump 或 dump_intermediate 时生效。

#perf

#概述

该参数用于测试模型性能。 该模式下，用户无需输入数据，程序根据模型信息自动构造输入tensor，tensor数据为随机数。 程序默认单线程运行200帧数据，当指定perf_time参数时，frame_count参数失效，程序会执行指定时间后退出。 输出模型运行的latency、以及帧率信息。程序每200帧打印一次性能信息： latency的最大、最小、平均值，不足200帧程序运行结束打印一次。

程序最后输出running相关数据， 包括：程序线程数、帧数、模型推理总时间，模型推理平均latency，帧率信息。

#示例

1. 单模型

2. 多模型

3. resizer模型

模型有三个输入，输入源顺序分别为[ddr, resizer, resizer]。

推理两帧数据，假设第一帧输入为[xx0.bin,xx1.jpg,xx2.jpg]，roi为[2,4,123,125;6,8,111,113]，第二帧输入为[xx3.bin,xx4.jpg,xx5.jpg]，roi为[27,46,143,195;16,28,131,183]，则perf命令如下：

#可选参数

参数	说明
core_id	指定模型推理的核id。
input_file	模型输入信息，多个可通过逗号分隔。
input_img_properties	模型图像输入的色彩空间信息。
input_valid_shape	模型动态 validShape 输入信息。
input_stride	模型动态 stride 输入信息。
roi_infer	使能resizer模型推理；若模型输入包含resizer源，设置为 true，默认为 false。
roi	roi_infer 为 true 时生效，设置推理resizer模型时所需的 roi 区域以英文分号间隔。
frame_count	设置 perf 运行帧数，当perf_time为0时生效，默认为 200。
dump_intermediate	dump模型每一层输入数据和输出数据，默认值 0。
perf_time	设置 perf 运行时间，单位：分钟，默认为 0。
thread_num	设置程序运行线程数，范围[1, 8], 默认为 1, 设置大于8时按照8个线程处理。
profile_path	统计工具日志产生路径，运行产生profiler.log和profiler.csv，分析op耗时和调度耗时。

#多输入模型说明

工具 infer 推理功能支持多输入模型的推理，支持图片输入、二进制文件输入以及文本文件输入，输入数据用逗号隔开。 模型的输入信息可以通过 model_info 进行查看。

示例:

#动态输入说明

若模型的输入是动态的，此时需要您使用 input_valid_shape 和 input_stride 参数来补全动态信息。您可以选择以下两种方式指定参数：

• 只给定动态输入的 validShape 或 stride 信息。
• 给定所有输入的 validShape 或 stride 信息，非动态输入的信息必须与模型信息保持一致。

以 动态输入介绍 章节中的模型为例，您可以通过以下命令运行模型：

#图像类型输入说明

当 input_file 给定图像输入时，需要使用 input_img_properties 参数来指定您想使用该图片的哪个色彩空间当做模型的输入，目前只支持 Y 和 UV 两种色彩空间。

#工具运行说明

#构建

在 ucp_tutorial/tools/hrt_model_exec 目录下有预先配置好的编译脚本 build.sh，选项 -a x86 和 -a aarch64 分别支持两种编译方式，您可以使用该脚本并指定编译选项进行编译。 此外，目录中也包含了 build_aarch64.sh 和 build_x86.sh 两个编译脚本，分别对应了两个编译选项，使用这两个脚本进行编译与使用 build.sh 脚本并指定编译选项等效。

#运行

构建板端运行工具后，将生成 output_shared_J6_aarch64 文件夹。 您可以将文件夹复制到板端环境中并执行 output_shared_J6_aarch64/script/run_hrt_model_exec.sh 来使用该工具。

构建x86端运行工具后，将生成 output_shared_J6_x86 文件夹。 您可以在x86端直接执行 output_shared_J6_x86/script_x86/run_hrt_model_exec.sh 来使用该工具。

run_hrt_model_exec.sh 脚本分为设置环境变量和获取模型信息并推理模型两部分。

#常见问题

#Latency、FPS数据是如何统计的？

Latency是指单流程推理模型所耗费的平均时间，重在表示在资源充足的情况下推理一帧的平均耗时，体现在上板运行是单核单线程统计；统计方法伪代码如下：

FPS是指多流程同时进行模型推理平均一秒推理的帧数，重在表示充分使用资源情况下模型的吞吐，体现在上板运行为双核多线程；统计方法是同时起多个线程进行模型推理，计算平均1s推理的总帧数。

#通过Latency推算FPS与工具测出的FPS为什么不一致？

Latency与FPS的统计情景不同，Latency为单流程（单核单线程）推理，FPS为多流程（多核多线程）推理，因此推算不一致；若统计FPS时将流程（线程）数量设置为 1 ，则通过Latency推算FPS和测出的一致。