5.5.2. hrt_model_exec工具介绍¶

5.5.2.1. 工具简介¶

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

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

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

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

hrt_model_exec -v
hrt_model_exec --version

5.5.2.2. 输入参数描述¶

编号	参数	类型	说明
1	`model_file`	string	模型文件路径，多个路径可通过逗号分隔。
2	`model_name`	string	指定模型中某个模型的名称。
3	`core_id`	int	指定运行核。
4	`input_file`	string	模型输入信息，多个可通过逗号分隔。
5	`roi_infer`	bool	使能resizer模型推理。
6	`roi`	string	指定推理resizer模型时所需的roi区域。
7	`frame_count`	int	执行模型运行帧数。
8	`dump_intermediate`	string	dump模型每一层输入和输出。
9	`enable_dump`	bool	使能dump模型输入和输出。
10	`dump_precision`	int	控制txt格式输出float型数据的小数点位数。
11	`hybrid_dequantize_process`	bool	控制txt格式输出float类型数据。
12	`dump_format`	string	dump模型输入和输出的格式。
13	`dump_txt_axis`	int	控制txt格式输入输出的换行规则。
14	`enable_cls_post_process`	bool	使能分类后处理。
15	`perf_time`	int	执行模型运行时间。
16	`thread_num`	int	指定程序运行线程数。
17	`profile_path`	string	统计工具日志产生路径，运行产生profiler.log和profiler.csv，分析op耗时和调度耗时。

5.5.2.3. 使用说明¶

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

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

../../../../_images/hrt_model_exec_help.png

5.5.2.3.1. model_info¶

5.5.2.3.1.1. 概述¶

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

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

5.5.2.3.1.2. 示例¶

1.单模型

hrt_model_exec model_info --model_file=xxx.bin

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

hrt_model_exec model_info --model_file=xxx.bin,xxx.bin

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

hrt_model_exec model_info --model_file=xxx.bin --model_name=xx

5.5.2.3.2. infer¶

5.5.2.3.2.1. 概述¶

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

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

5.5.2.3.2.2. 示例¶

1.单模型

hrt_model_exec infer --model_file=xxx.bin --input_file=xxx.jpg

2.多模型

hrt_model_exec infer --model_file=xxx.bin,xxx.bin --model_name=xx --input_file=xxx.jpg

5.5.2.3.2.3. 可选参数¶

参数	说明
`core_id`	指定模型推理的核id，0：任意核，1：core0，2：core1；默认为 `0`。
`roi_infer`	使能resizer模型推理；若模型输入包含resizer源，设置为 `true`，默认为 `false`。
`roi`	`roi_infer` 为 `true` 时生效，设置推理resizer模型时所需的 `roi` 区域以分号间隔。
`frame_count`	设置 `infer` 运行帧数，单帧重复推理，可与 `enable_dump` 并用，验证输出一致性，默认为 `1`。
`dump_intermediate`	dump模型每一层输入数据和输出数据，默认值 `0`，不dump数据。 `1`：输出文件类型为 `bin`； `2`：输出类型为 `bin` 和 `txt`，其中BPU节点输出为aligned数据； `3`：输出类型为 `bin` 和 `txt`，其中BPU节点输出为valid数据。
`enable_dump`	dump模型输出数据，默认为 `false`。
`dump_precision`	控制txt格式输出float型数据的小数点位数，默认为 `9`。
`hybrid_dequantize_process`	控制txt格式输出float类型数据，若输出为定点数据将其进行反量化处理，目前只支持四维模型。
`dump_format`	dump模型输出文件的类型，可选参数为 `bin` 或 `txt`，默认为 `bin`。
`dump_txt_axis`	dump模型txt格式输出的换行规则；若输出维度为n，则参数范围为[0, n]，默认为 `-1`，一行一个数据。
`enable_cls_post_process`	使能分类后处理，目前只支持ptq分类模型，默认 `false`。

5.5.2.3.3. perf¶

5.5.2.3.3.1. 概述¶

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

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

5.5.2.3.3.2. 示例¶

1.单模型

hrt_model_exec perf --model_file=xxx.bin

2.多模型

hrt_model_exec perf --model_file=xxx.bin,xxx.bin --model_name=xx

5.5.2.3.3.3. 可选参数¶

参数	说明
`core_id`	指定模型推理的核id，0：任意核，1：core0，2：core1；默认为 `0`。
`input_file`	模型输入信息，多个可通过逗号分隔。
`roi_infer`	使能resizer模型推理；若模型输入包含resizer源，设置为 `true`，默认为 `false`。
`roi`	`roi_infer` 为 `true` 时生效，设置推理resizer模型时所需的 `roi` 区域以分号间隔。
`frame_count`	设置 `perf` 运行帧数，当perf_time为0时生效，默认为 `200`。
`dump_intermediate`	dump模型每一层输入数据和输出数据，默认值 `0`，不dump数据。 `1`：输出文件类型为 `bin`； `2`：输出类型为 `bin` 和 `txt`，其中BPU节点输出为aligned数据； `3`：输出类型为 `bin` 和 `txt`，其中BPU节点输出为valid数据。
`perf_time`	设置 `perf` 运行时间，单位：分钟，默认为 `0`。
`thread_num`	设置程序运行线程数，范围[1, 8], 默认为 `1`, 设置大于8时按照8个线程处理。
`profile_path`	统计工具日志产生路径，运行产生profiler.log和profiler.csv，分析op耗时和调度耗时。

5.5.2.3.4. 多线程Latency数据说明¶

多线程的目的是为了充分利用BPU资源，多线程共同处理 frame_count 帧数据或执行perf_time时间，直至数据处理完成/执行时间结束程序结束。在多线程 perf 过程中可以执行以下命令，实时获取BPU资源占用率情况。

hrut_somstatus -n 10000 -d 1

输出见以下截图：

注解

在 perf 模式下，单线程的latency时间表示模型的实测上板性能，而多线程的latency数据表示的是每个线程的模型单帧处理时间，相对于单线程的时间要长，但是多线程的总体处理时间减少，其帧率是提升的。

5.5.2.3.5. 多输入模型说明¶

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

示例:

hrt_model_exec infer --model_file=xxx.bin --input_file=xxx.jpg,input.txt

5.5.2.3.6. 输入参数补充说明¶

5.5.2.3.6.1. input_file¶

图片类型的输入。

其文件名后缀必须为 bin / JPG / JPEG / jpg / jpeg 中的一种， feature输入后缀名必须为 bin / txt 中的一种。每个输入之间需要用英文字符的逗号隔开 ,，如： xxx.jpg,input.txt。

5.5.2.3.6.2. roi_infer¶

若模型包含resizer输入源， infer 和 perf 功能都需要设置 roi_infer 为true，并且配置与输入源一一对应的 input_file 和 roi 参数。如：模型有三个输入，输入源顺序分别为[ddr, resizer, resizer]，则推理两组输入数据的命令行如下：

// infer
hrt_model_exec infer --roi_infer=true --model_file=xxx.bin --input_file="xx0.bin,xx1.jpg,xx2.jpg,xx3.bin,xx4.jpg,xx5.jpg"  --roi="2,4,123,125;6,8,111,113;27,46,143,195;16,28,131,183"
// perf
hrt_model_exec perf --roi_infer=true --model_file=xxx.bin --input_file="xx0.bin,xx1.jpg,xx2.jpg,xx3.bin,xx4.jpg,xx5.jpg"   --roi="2,4,123,125;6,8,111,113;27,46,143,195;16,28,131,183"

每个 roi 输入之间需要用英文字符的分号隔开。

5.5.2.3.6.3. dump_intermediate¶

dump模型每一层节点的输入数据和输出数据。

dump_intermediate=0 时，默认dump功能关闭；
dump_intermediate=1 时，模型中每一层节点输入数据和输出数据以 bin 方式保存，其中 BPU 节点输出为 aligned 数据；
dump_intermediate=2 时，模型中每一层节点输入数据和输出数据以 bin 和 txt 两种方式保存，其中 BPU 节点输出为 aligned 数据；
dump_intermediate=3 时，模型中每一层节点输入数据和输出数据以 bin 和 txt 两种方式保存，其中 BPU 节点输出为 valid 数据。

如：模型有两个输入，输入源顺序分别为[pyramid， ddr]，将模型每一层节点的输入和输出保存为 bin 文件，其中 BPU 节点输出按 aligned 类型保存，则推理命令行如下：

hrt_model_exec infer --model_file=xxx.bin --input_file="xx0.jpg,xx1.bin"  --dump_intermediate=1

dump_intermediate 参数支持 infer 和 perf 两种模式。

5.5.2.3.6.4. hybrid_dequantize_process¶

控制txt格式输出float类型数据。

hybrid_dequantize_process 参数在 enable_dump=true 时生效。

当 enable_dump=true 时：

若设置 hybrid_dequantize_process=true ，反量化整型输出数据，将所有输出按float类型保存为 txt 文件，其中模型输出为 valid 数据，支持配置 dump_txt_axis 和 dump_precision；
若设置 hybrid_dequantize_process=false ，直接保存模型输出的 aligned 数据，不做任何处理。

如：模型有3个输出，输出Tensor数据类型顺序分别为[float，int32，int16]，输出txt格式float类型的 valid 数据，则推理命令行如下：

// 输出float类型数据
hrt_model_exec infer --model_file=xxx.bin --input_file="xx.bin"  --enable_dump=true --hybrid_dequantize_process=true

hybrid_dequantize_process 参数目前只支持四维模型。

5.5.2.3.6.5. profile_path¶

profile日志文件产生目录。

该参数通过设置环境变量 HB_DNN_PROFILER_LOG_PATH 查看模型运行过程中OP以及任务调度耗时。一般设置 --profile_path="." 即可，代表在当前目录下生成日志文件，日志文件为profiler.log和profiler.csv。

5.5.2.3.6.6. enable_cls_post_process¶

使能分类后处理。

子命令为 infer 时配合使用，目前只支持ptq分类模型的后处理，为 true 时打印分类结果。参见下图：

../../../../_images/enable_cls_post_process.png

5.5.2.3.6.7. thread_num¶

线程数(并行度)，数值可以表示最多有多少个任务在并行处理。测试延时时，数值需要设置为1，没有资源抢占发生，延时测试更准确。测试吞吐时，建议设置>2 (BPU核心个数)，调整线程数使BPU利用率尽量高，吞吐测试更准确。

// 双核FPS
hrt_model_exec perf --model_file xxx.bin --thread_num 8 --core_id 0
// Latency
hrt_model_exec perf --model_file xxx.bin --thread_num 1 --core_id 1

5.5.2.4. 常见问题¶

5.5.2.4.1. Latency、FPS数据是如何统计的？¶

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

// Load model and prepare input and output tensor
...

// Loop run inference and get latency
{
  int32_t const loop_num{1000};
  start = std::chrono::steady_clock::now();
  for(int32_t i = 0; i < loop_num; i++){
      hbDNNInferCtrlParam infer_ctrl_param;
      HB_DNN_INITIALIZE_INFER_CTRL_PARAM(&infer_ctrl_param);
      hbDNNInfer(&task_handle,
                &output,
                input_tensors.data(),
                dnn_handle,
                &infer_ctrl_param);
      // wait task done
      hbDNNWaitTaskDone(task_handle, 0);
      // release task handle
      hbDNNReleaseTask(task_handle);
      task_handle = nullptr;
  }
  end = std::chrono::steady_clock::now();
  latency = (end - start) / loop_num;
}

// release tensor and model
...

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

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

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