# 基准测试

## 概述

ModelConverter 的[基准测试工具](https://github.com/luxonis/modelconverter#benchmarking) 提供了一种在支持的平台（RVC2 和 RVC4）上测量已转换模型设备端性能的方法。它的目的是生成与
[HubAI 模型库](https://models.luxonis.com/) 模型卡中通常显示的性能结果相同的类型。

## 安装

要使用基准测试工具，请安装 ModelConverter 并确保包含其基准测试依赖项。您可以按照 [ModelConverter 仓库](https://github.com/luxonis/modelconverter#installation)
中的安装步骤或相应的 [ModelConverter
文档部分](https://docs.luxonis.com/software-v3/ai-inference/conversion/rvc-conversion/offline/modelconverter.md) 进行操作。

要从 PyPI 安装 支持基准测试 的 ModelConverter，请使用：

```bash
pip install modelconv[bench]
```

## 用法

您可以按如下方式对模型进行基准测试：

```bash
modelconverter benchmark <target> --model-path <path_or_slug>
```

该命令将结果表打印到控制台。如果传递 --save，它还会将结果写入当前工作目录中的 CSV 文件。

### 基本示例

要在 RVC4 上对 [YOLOv6 Nano](https://models.luxonis.com/luxonis/yolov6-nano/face58c4-45ab-42a0-bafc-19f9fee8a034?backTo=%2F)
模型进行基准测试，请运行：

```bash
modelconverter benchmark rvc4 --model-path yolov6-nano:r2-coco-512x288 --save
```

这将对模型进行基准测试，将结果打印到控制台，并保存为 yolov6-nano_benchmark_results.csv。

有关更高级的示例和选项，请参阅 [高级示例](#Advanced%20Examples) 部分。

### 支持的平台

基准测试命令通过位置参数 <target> 支持多个平台：

 * RVC2：DepthAI (DAI) 管道基准测试。
 * RVC4：DepthAI (DAI) 管道基准测试（默认）或通过 ADB 连接到 RVC4 设备的基于 SNPE 的基准测试。

### 模型来源

--model-path 参数是 必需的，并接受以下模型来源：

 * 本地模型产物：.blob 文件（用于 RVC2）或 .dlc 文件（用于 RVC4）
 * 本地 NN 归档：[Luxonis NN 归档](https://docs.luxonis.com/software-v3/ai-inference/nn-archive.md)（包含模型可执行文件和配置的 .tar.xz 文件）
 * HubAI 模型 slug：来自 [HubAI 模型库](https://models.luxonis.com/) 的模型 slug，例如 yolov6-nano:r2-coco-512x288

注意： 使用 HubAI slug 时，请确保您的 HUBAI_API_KEY 环境变量已配置有效的凭据。

### 输出结果

默认情况下，结果以表格形式打印到控制台。

如果提供 --save，结果将写入 CSV 文件。文件名源自模型名称，格式为：<model_name>_benchmark_results.csv。

### CLI 选项

您可以使用额外的命令行选项自定义基准测试过程：

| 参数 | 描述 | 默认值 | 平台 |
| --- | --- | --- | --- |
| `full` | 运行涵盖所有配置的完整基准测试。 | `False` | RVC2, RVC4 |
| `save` | 将基准测试结果保存到 CSV 文件。 | `False` | RVC2, RVC4 |
| `repetitions` | DAI 基准测试的重复次数。 | `10` | RVC2, RVC4 |
| `benchmark-time` | 基准测试持续时间（秒）。 | `20` | RVC2, RVC4 |
| `num-threads` | 推理的线程数（仅 DAI）。 | `2` | RVC2, RVC4 |
| `num-messages` | 每次推理运行发送的消息数（仅 DAI）。 | `50` | RVC2, RVC4 |
| `profile` | 要使用的 SNPE 性能配置文件。 | `balanced` | RVC4 |
| `runtime` | 用于推理的 SNPE 运行时。 | `dsp` | RVC4 |
| `num-images` | SNPE 推理的图像数量。 | `1000` | RVC4 |
| `device-ip` | 目标设备的 IP 地址。 | `None` | RVC4 |
| `device-id` | 目标设备的唯一 ID。 | `None` | RVC4 |
| `dai-benchmark` | 使用 DAI 基准测试而不是 SNPE 工具。 | `True` | RVC4 |
| `power-benchmark` | 测量功耗（需要 ADB）。 | `False` | RVC4 |
| `dsp-benchmark` | 测量 DSP 利用率（需要 ADB）。 | `False` | RVC4 |

### 控制基准测试持续时间

您可以通过两种方式控制基准测试运行的时长：

 * 基于时间（推荐用于稳定的平均值）：--benchmark-time <seconds>
 * 固定重复次数：--repetitions <N>

默认情况下，启用基于时间的基准测试（--benchmark-time 20），并且对于 RVC2 和 RVC4 目标，它优先于 --repetitions。

要改为运行固定重复次数，请禁用基于时间的基准测试：

```bash
modelconverter benchmark rvc4 \
  --model-path <path_or_slug> \
  --benchmark-time -1 \
  --repetitions 50
```

### RVC4 相关选项

#### 选择设备

在 RVC4 上，您可以通过以下方式之一定位特定设备：

 * --device-ip <ip>：指定目标 RVC4 设备的 IP 地址。
 * --device-id <id>：指定目标 RVC4 设备的唯一 ID。

如果两者均未提供，设备将自动从可用设备中选择。如果同时提供了两者，则 device-id 优先。

#### 电源和DSP监控

在RVC4上，该工具可选择在基准测试运行期间记录额外的指标：

 * --power-benchmark：启用后，基准测试会从设备hwmon节点（可用时）收集功耗读数，并报告基准测试运行期间系统和处理器的平均功耗统计信息。
 * --dsp-benchmark：启用后，基准测试会从设备收集DSP利用率数据，并报告基准测试运行期间的平均DSP利用率。

这些选项需要对设备具有（root）ADB访问权限。

#### DAI与SNPE基准测试对比

RVC4支持两种基准测试方法：

 * DAI基准测试（默认）：通过 --dai-benchmark 启用。
 * 基于ADB的SNPE工具：通过 --no-dai-benchmark 启用。

何时使用每种方法：

 * 对于大多数用例，使用默认的DAI基准测试。
 * 当需要手动SNPE风格的基准测试或想直接对 .dlc 文件进行基准测试时，使用SNPE路径。

SNPE基准测试要求：

SNPE路径需要对设备具有ADB访问权限。该工具内部使用 snpe-parallel-run，行为如下：

 * 准备一组图像并将其发送到设备进行推理（通过 --num-images 配置）。
 * 通过 --runtime 和 --profile 选项支持运行时和性能定制。
 * 默认在两个线程上运行（以匹配DAI默认值）。

## 手动SNPE基准测试

对于高级用例或自定义工作流程，可以直接使用SNPE工具对模型进行基准测试，无需 modelconverter benchmark。这在以下情况下很有用：

 * 构建自定义基准测试脚本或自动化
 * 与现有SNPE管道集成
 * 需要对基准测试参数进行细粒度控制

### 工作流程

 1. 检查DLC模型 提取输入张量元数据，包括张量名称、形状和数据类型。使用 snpe-dlc-info 来获取这些信息。
 2. 准备输入数据
    * 创建与预期张量形状和类型匹配的输入 .raw 文件。
    * 生成一个 input_list.txt 文件，列出所有待处理的输入文件。
 3. 运行SNPE基准测试工具 根据基准测试目标选择合适的工具：
    * [snpe-parallel-run](https://docs.qualcomm.com/nav/home/SNPE_general_tools.html?product=1601111740010412#snpe-parallel-run)。
    * [snpe-throughput-net-run](https://docs.qualcomm.com/nav/home/SNPE_general_tools.html?product=1601111740010412#snpe-throughput-net-run)。

有关这些工具的详细用法和选项，请参考[SNPE通用工具文档](https://docs.qualcomm.com/nav/home/SNPE_general_tools.html?product=1601111740010412)。

## 高级示例

### 自定义持续时间的NN Archive

在RVC2上对导出的NN Archive进行基准测试，测试时间更长，并保存结果以便后续比较。

```bash
modelconverter benchmark rvc2 \
  --model-path path/to/model_archive.tar.xz \
  --benchmark-time 60 \
  --save
```

关键点：

 * 运行60秒基于时间的基准测试，以获得更稳定的结果
 * 将结果打印到控制台并保存为CSV以便比较

### 带电源监控的HubAI模型

在RVC4上使用HubAI Model Slug对Model Zoo模型进行基准测试，同时监控功耗和DSP利用率指标。

```bash
modelconverter benchmark rvc4 \
  --model-path yolov6-nano:r2-coco-512x288 \
  --device-ip 192.168.1.50 \
  --power-benchmark \
  --dsp-benchmark
```

关键点：

 * 使用 --device-id <id> 替代 --device-ip <ip>
 * 电源和DSP监控需要ADB访问权限和设备支持

### 通过SNPE进行本地DLC基准测试

使用SNPE工具对本地 .dlc 文件进行基准测试，并控制工作负载大小。

```bash
modelconverter benchmark rvc4 \
  --model-path path/to/model.dlc \
  --no-dai-benchmark \
  --device-ip 192.168.1.50 \
  --num-images 500
```

关键点：

 * 使用SNPE基准测试路径而非DAI（通过 --no-dai-benchmark）
 * 处理500个生成的输入图像
 * 通过IP地址定位特定设备