4. 使用指南

为便于用户快速完成模型性能评测，模型转换与评估工具支持一键执行量化、编译、推理、性能测试和精度评估等全流程操作，也支持按需仅执行其中的单项任务。

下面以 YOLOv5s 模型为例，介绍如何使用工具完成模型性能评测。

4.1. 一键运行

下面以YOLOv5s模型样例为例，介绍如何一键执行模型转换与评估工具：

  1. 运行前准备。

    1. 配置运行环境。

    2. 准备验证集。coco2017 验证集下载后可存放在 MODELZOO_PATH/data/datasets/coco2017 目录下。

    3. 在 MODELZOO_PATH/models/detection/yolov5s 目录下，执行下面指令下载原始输入模型：

      python3 get_model.py --type raw

  2. 执行下面指令一键运行开发样例，包括量化、编译、推理、评测以及精度评估等：

    ./test.sh

用户也可分别量化、编译、推理和评测YOLOv5s模型样例，详情可见下面章节。

4.2. 量化模型

运行前准备后，在 MODELZOO_PATH/models/detection/yolov5s 目录下，执行下面指令量化模型：

注意

Ubuntu 22.04 x86_64、Ubuntu 20.04 x86_64和Ubuntu 20.04 AArch64平台不支持模型量化，请在Ubuntu 24.04 x86_64平台上执行本节操作。

hmatc quant -c config.yml

其中 config.yml 为配置文件，用户可按需进行设置。如果尚未准备配置文件，可按默认配置，生成配置文件，详情参看生成配置文件（可选）。

如果量化成功，量化后模型文件 yolov5s_clip_xh2_w8a8h1_sefp.onnx 保存在：

MODELZOO_PATH/models/detection/yolov5s/output/xh2/hmquant

返回信息示例如下：

02:43:09.613280 xh2_exec.py:139 [INFO] Quantize done. and save hmonnx: output/xh2/hmquant/yolov5s_clip_xh2_w8a8h1_sefp.onnx

4.2.1. 生成配置文件（可选）

使用以下命令根据 ONNX 模型自动生成默认配置文件：

hmatc gen --onnx onnx_path --output yml_file_path

其中：

  • onnx_path：原始 ONNX 模型文件路径。

  • yml_file_path：生成的配置文件保存路径。

用户可根据模型需求修改生成的配置文件。

4.3. 编译模型

模型量化成功后，在 MODELZOO_PATH/models/detection/yolov5s 目录下，执行下面指令编译模型：

注意

Ubuntu 22.04 x86_64、Ubuntu 20.04 x86_64和Ubuntu 20.04 AArch64平台不支持模型编译，请在Ubuntu 24.04 x86_64平台上执行本节操作。

hmatc build -c config.yml

其中 config.yml 为配置文件，用户可按需进行设置。

如果不使用配置文件，也可以直接指定量化模型进行编译：

hmatc build --hmonnx hmonnx_path --hmm_name model_name --output hmm_path

其中：

  • hmonnx_path：量化后模型文件路径。

  • model_name：模型名称。

  • hmm_path：编译后模型文件名（.hmm）。

如果编译成功，编译后模型文件 yolov5s_clip_xh2_b1_1core_O2.hmm 保存在：

MODELZOO_PATH/models/detection/yolov5s/output/xh2

此外，示例还会将编译后的模型推理结果，与量化后模型推理结果进行比对，并输出Cosine Distance（余弦距离），作为验证编译结果正确性的重要指标。

返回信息示例如下：

...
02:45:59.144781 api.py:260 [INFO] <=== hdpl compile completed.
02:45:59.147104 main.py:137 [INFO] Build yolov5s_clip done.
02:45:59.147169 xh1_infer.py:20 [INFO] load model from output/xh2/yolov5s_clip_xh2_b1_1core_O2.hmm
02:45:59.159056 xh1_infer.py:22 [INFO] load xh1 model successfully.
02:45:59.159215 xh1_infer.py:33 [INFO] [xh2] input[images] shape = [1, 3, 640, 640], dtype = float16, format = ND
...
02:45:59.197605 xh2_exec.py:211 [INFO] Check golden...
+--------------------+
|   xh2 vs hmquant   |
+------+-------------+
| name | cosine_dist |
+------+-------------+
| 340  |   0.945376  |
| 378  |   0.883403  |
| 416  |   0.952633  |
+------+-------------+

示例中，name 列指推理后模型输出节点名称。

上面示例是运行在模拟器的结果，并非在后摩设备上的运行结果，因此仅供参考。

4.4. 模型推理

模型编译后，在 MODELZOO_PATH/models/detection/yolov5s 目录下，执行下面指令推理模型。示例包含图像前后处理和推理结果可视化：

# 使用配置文件对编译后的模型进行推理
hmatc demo -c config.yml

# 使用配置文件对原始 ONNX 模型进行推理
hmatc demo -c config.yml -t xh2 --onnx

其中 config.yml 为配置文件，用户可按需进行设置。

如果模型推理成功，输出推理后图形到 MODELZOO_PATH/models/detection/yolov5s/vis_xh2 目录下，并且返回预测结果包括cls（目标类别）、score、检测框左上角 (x1, y1) 和右下角坐标 (x2, y2) 等信息。返回信息示例如下：

...
02:58:49.652403 model_impl.py:77 [INFO] Image[9] /usr/local/src/houmo-examples/data/datasets/coco2017/val2017/000000001490.jpg
02:58:49.674848 model_impl.py:86 [INFO] Detection[ 0] x1:  449, y1:  119, x2:  501, y2:  239, score: 0.900, cls:  0
02:58:49.675680 model_impl.py:89 [INFO] Save result to vis_xh2/000000001490.jpg

其中：

  • cls：表示目标类别。

  • score：表示检测框的置信度分数。分数越接近 1，说明模型认为这个预测框里包含目标的可能性越大。

  • x1, y1：检测框左上角的坐标。

  • x2, y2：检测框右下角的坐标。

../_images/hmassist_demo.jpg

图 4.1 模型转换与评估工具推理后图像示例

上面示例是运行在模拟器的结果，并非在后摩设备上的运行结果，因此仅供参考。

4.5. 单样本精度评估

单样本精度评估旨在通过比较不同模型对单个输入样本的推理结果，来快速验证模型转换过程中的精度保持情况。该过程主要衡量以下三种模型的推理结果：

注意

Ubuntu 22.04 x86_64、Ubuntu 20.04 x86_64 和 Ubuntu 20.04 AArch64平台不支持模型量化和模型编译。由于本节操作依赖量化后模型和编译后模型，请在Ubuntu 24.04 x86_64平台上执行本节操作。

  • 原始ONNX模型

  • 量化后模型

  • 编译后模型

通过比对这些模型的推理结果，工具会计算并输出Cosine Distance（余弦距离），该值是衡量编译结果正确性的重要指标。

下面以 YOLOv5s 模型为例，介绍如何对单样本进行精度评估。

配置运行环境后，在 houmo-examples-xh2/models/detection/yolov5s 目录下，执行下面指令进行单样本评估，需要指定配置文件和数据路径：

注意

执行指令前，需确保原始ONNX模型、量化后模型以及编译后模型已存放在指定路径。
hmatc compare -c config.yml --data_path coco2017/val2017/000000000139.jpg

其中 config.yml 为配置文件，用户可按需进行设置。

返回结果示例如下：

...
02:50:53.310326 xh2_exec.py:310 [INFO]
+-------------------------------------------------------+
|                    Cosine Distance                    |
+------+-----------------+-------------+----------------+
| name | onnx vs hmquant | onnx vs xh2 | hmquant vs xh2 |
+------+-----------------+-------------+----------------+
| 340  |     0.984035    |   0.999404  |    0.984125    |
| 378  |     0.975255    |   0.999342  |    0.974900    |
| 416  |     0.944464    |   0.999268  |    0.943158    |
+------+-----------------+-------------+----------------+

其中：

  • name：表示推理后模型输出节点名称。

  • onnx vs hmquant：表示原始ONNX模型与量化后模型推理结果比对。用于判断量化是否引入精度损失。

  • onnx vs xh2：表示原始ONNX模型与编译后模型推理结果比对。判断完整转换链路的总体偏差。

  • hmquant vs xh2：表示量化后模型与编译后模型推理结果比对。判断编译后模型是否保持量化模型结果。

上面示例是运行在模拟器的结果，并非在后摩设备上的运行结果，因此仅供参考。

4.6. 模型结果与 Golden 数据比对

Golden 数据是一组用于验证模型推理结果的参考输出数据，作为模型推理结果的基准。通过将当前量化后模型或编译后模型的推理结果与 Golden 数据进行比对，并计算两者之间的 Cosine Distance（余弦距离），可以评估推理结果与参考结果之间的相似度，从而判断模型在编译或部署过程中是否保持了正确的计算结果。

量化和编译模型成功后，模型转换与评估工具会生成对应的 Golden 数据。用户也可以自行提供 Golden 数据用于结果比对。

4.6.1. 验证量化模型和编译模型

该方式会分别将量化后模型和编译后模型的推理结果与对应的 Golden 数据进行比对。

模型编译成功后，在 MODELZOO_PATH/models/detection/yolov5s 目录下，执行以下命令完成Golden 数据比对：

hmatc check -c config.yml

其中 config.yml 为配置文件，用户可按需进行设置。

也可以按算子级别进行 Golden 数据比对：

hmatc check -c config.yml --layers

4.6.2. 仅验证编译模型

如果只验证编译后模型的推理结果，可直接指定模型文件和 Golden 数据路径进行比对。

模型编译成功后，在 MODELZOO_PATH/models/detection/yolov5s 目录下，执行以下命令完成Golden 数据比对：

hmatc check --hmm hmm_path --golden golden_path

其中：

  • hmm_path：编译后模型文件（.hmm）。

  • golden_path：Golden 数据存放路径。

该方式仅比较编译后模型的推理结果与 Golden 数据之间的一致性，因此需要用户提供 Golden 数据路径。

4.6.3. 生成 Golden 数据（可选）

模型转换与评估工具提供 Golden 数据生成功能，可用于模型调试和精度验证。

注意

Ubuntu 22.04 x86_64、Ubuntu 20.04 x86_64 和 Ubuntu 20.04 AArch64平台不支持模型量化和模型编译。由于本节操作依赖量化后模型，并涉及模型重新编译流程，请在 Ubuntu 24.04 x86_64平台上执行本节操作。

模型量化成功后，在 MODELZOO_PATH/models/detection/yolov5s 目录下，执行以下命令生成 Golden 数据：

hmatc golden --hmonnx hmonnx_path --output golden_path --data_path npz_path

其中：

  • hmonnx_path：表示量化后模型文件。

  • golden_path：表示生成的golden数据存放路径。

  • npz_path：输入数据文件路径，文件格式为 NumPy .npz。该文件用于存放模型推理所需的输入数据，文件中每个数组对应模型的一个输入张量，且数据需为预处理后的输入数据。如果未指定，将使用随机数据作为输入。

    当使用自定义输入数据时，需要提供 预处理后的输入数据，并按指定格式保存，示例如下：

    import numpy as np
a = np.random.rand(1, 3, 28, 28)  # 预处理后数据
b = np.random.rand(1, 3, 64, 64)  # 预处理后数据
in_datas = {'input_a': a, 'input_b': b, ...}

也可以按算子级别生成golden数据：

hmatc golden --hmonnx hmonnx_path --output golden_path --data_path npz_path --layers

执行该命令后，会生成调试模型 ${hmonnx_name}_debug.onnx。

生成golden数据后，需要使用该调试模型重新编译后，再执行 Golden 数据比对：

hmatc build --hmonnx hmonnx_path
hmatc check --hmm hmm_path --golden golden_path

其中：

  • hmonnx_path：表示量化后模型文件。

  • hmm_path：编译后模型文件（.hmm）。

  • golden_path：表示生成的golden数据存放路径。

4.7. 多样本精度评估

多样本精度评估是对模型整体性能的权威评测。它通过在完整的测试数据集上进行推理，计算出模型的平均精度（AP）和平均召回率（AR）等指标，以反映其真实性能。

配置运行环境后，在 MODELZOO_PATH/models/detection/yolov5s 目录下，执行以下指令，对模型在指定数据集上的精度进行评估：

注意

执行指令前，需确保编译后模型已存放在指定路径。
hmatc eval -c config.yml

其中 config.yml 为配置文件，用户可按需进行设置。

返回结果示例如下：

 ...
 Average Precision  (AP) @[ IoU=0.50:0.95 | area=medium | maxDets=100 ] = 0.576
 Average Precision  (AP) @[ IoU=0.50:0.95 | area= large | maxDets=100 ] = 0.668
 Average Recall     (AR) @[ IoU=0.50:0.95 | area=   all | maxDets=  1 ] = 0.395
 Average Recall     (AR) @[ IoU=0.50:0.95 | area=   all | maxDets= 10 ] = 0.548
 Average Recall     (AR) @[ IoU=0.50:0.95 | area=   all | maxDets=100 ] = 0.555
 Average Recall     (AR) @[ IoU=0.50:0.95 | area= small | maxDets=100 ] = 0.366
 Average Recall     (AR) @[ IoU=0.50:0.95 | area=medium | maxDets=100 ] = 0.638
 Average Recall     (AR) @[ IoU=0.50:0.95 | area= large | maxDets=100 ] = 0.712
03:07:19.981860 base_exec.py:276 [INFO] {'input_size': [1, 3, 640, 640], 'dataset': 'coco_2017Val', 'num': 32, 'map50_95': '0.472628', 'map50': '0.669394', 'latency': '12.119196'}

其中：

  • AP：为Average Precision（平均精度），用于衡量的是模型预测的准确性。AP 值越高，表示模型的预测结果越值得信赖。

  • AR：为Average Recall（平均召回率），用于衡量的是模型预测的完整性。

  • IoU：为Intersection over Union（交并比），在目标检测任务中，IoU 是一个用来衡量预测框和真实框之间重叠程度的指标。IoU=0.50:0.95 表示在 IoU 阈值从 0.50 到 0.95 的 10 个不同水平下，对 AP 和 AR 进行计算并取其平均值。

  • area：表示目标面积，将目标根据其尺寸大小分为不同类别。

    • small: 小型目标。

    • medium: 中等尺寸目标。

    • large: 大型目标。

    • all: 所有尺寸的目标。

  • maxDets：表示最大检测数量，即每张图片最多考虑的预测框数量。

上面示例是运行在模拟器的结果，并非在后摩设备上的运行结果，因此仅供参考。

4.8. 性能评测

配置运行环境后，在 MODELZOO_PATH/models/detection/yolov5s 目录下，执行下面指令测试模型推理性能，该命令能够测量模型在不同配置下的推理Latency（延迟）和Throughput（吞吐量）等关键性能指标：

注意

执行指令前，需确保编译后模型已存放在指定路径。
hmatc perf -c config.yml -wn 1 -sn 1 -tn 1

其中 config.yml 为配置文件，用户可按需进行设置。

其中：

  • wn：表示热身次数，指在正式测试前，模型推理的次数。

  • sn：表示指用于性能测试的样本总数。

  • tn：表示用于执行推理任务的线程数量。

返回信息示例如下：

...
Device 0 Thread 0 output/xh2/yolov5s_clip_xh2_b1_1core_O2.hmm model loaded. Cost 13.133 ms.
Device 0 Thread 0 Warm Up 1 average cost 5.667 ms.
Device 0 Thread 0 infer start...
Device 0 Thread 0 completed. 1 samples tested.
[latency] Inference     avg:   5.539 ms,        max:   5.539 ms
[latency] Input         avg:   1.179 ms,        max:   1.179 ms
[latency] Output        avg:   0.000 ms,        max:   0.000 ms
[latency] End2End       avg:   6.719 ms,        max:   6.719 ms
[Throughput] total: 6.762 ms, avg: 6.762 ms
[Throughput] qps: 147.885

其中：

  • latency：衡量从输入到输出所需的时间，单位为毫秒（ms），其值越低越好。以下是具体的延迟指标：

    • Inference: 模型推理时间，即从数据进入推理引擎到结果输出的时间。

    • Input: 数据传输到模型输入端的时间。这部分耗时主要指将数据从主机内存移动到设备内存，并设置到模型输入所需的总时间。

    • Output: 推理结果后处理所需的时间。这部分耗时包括将推理结果从设备内存传回主机内存，以及对结果进行解析等操作。

    • End2End: 整个流程的总耗时，即 Input、Inference 和 Output 三部分耗时的总和。

每个延迟指标都包含两个数值：

  • avg：所有线程处理的所有样本的平均耗时。

  • max：所有线程处理的所有样本中，单个样本耗时的最大值。

上面示例是运行在模拟器的结果，并非在后摩设备上的运行结果，因此仅供参考。