4. 性能调优指南

模型部署后，如果推理速度不达预期，需要先判断性能瓶颈类型，再采用针对性优化策略。性能瓶颈主要分为两类：

主机/数据传输性能瓶颈：平台环境、前后处理、数据搬移等引起的耗时，主要消耗CPU、内存或I/O带宽。
模型计算性能瓶颈：由模型算子、计算图结构、硬件算力利用率不足引起的耗时，主要消耗后摩M50设备的IPU计算资源。

4.1. 流程

针对不同模型类型，建议使用不同工具进行性能调优，性能评估和调优流程如图所示：

../_images/performance.png — 图 4.1 性能评估和调优流程

4.2. 性能评估工具

不同模型类型建议使用不同工具进行性能分析：

模型类型	推荐工具	主要用途
小模型（CV、检测、分类、分割等网络模型）	模型推理性能评测工具	评测编译后模型在后摩M50设备上的延迟和吞吐量，评测输入设置、模型推理和输出读取各阶段耗时。
LLM/VLM模型	LLM 推理性能评测工具	评测Prefill、Decode、Vision和端到端性能，分析Tokenization、Embedding、输入设置、模型推理和输出读取等阶段耗时。

4.3. 性能问题映射表

性能调优的第一步是比对各项监控指标。以下列出核心问题来源及其特征：

问题来源	典型表现
主机/数据传输性能瓶颈	Tokenization、Embedding、数据传输、输入设置、输出回传或后处理耗时较高。
模型计算性能问题	模型主体推理耗时较高，设备计算阶段成为瓶颈。
系统资源问题	温度、功耗、频率或内存影响性能稳定性。
测试配置问题	batch、输入长度、输出长度或 loop 配置不一致，导致结果不可比。

4.4. 小模型（CV/检测/分类/分割）性能瓶颈定位

模型推理性能评测工具用于评估编译后网络模型在M50后摩设备上的推理性能。工具会输出延迟和吞吐量指标，帮助判断耗时主要来自模型推理，还是来自输入输出和数据传输。

4.4.1. 使用方法

4.4.1.1. 环境依赖

该工具支持平台如下：

Linux系统：

Ubuntu 20.04及以上版本（x86_64或AArch64）
Windows系统：
- Windows11
Android系统：
- 操作系统：Android 15 (API level 35)
- CPU 架构：arm64‑v8a
- 内核版本：Linux 6.1
- 开发调试工具：adb (Android Debug Bridge)
  
  注：adb 工具默认不随系统安装。

4.4.1.2. 运行环境

工具可在下面环境中运行：

软件平台Docker镜像：

（仅支持Linux系统）软件平台提供的 Docker 镜像已预置工具运行所需环境。有关Docker镜像的安装与部署，参看《快速入门指南》。
运行时开发工具包：

可使用运行时开发工具包 houmo_tcim_runtime_<target_hw>_${distro}_$arch-<release>.tar.gz。详情参看《TCIM用户指南》。

4.4.1.3. Linux环境准备

工具使用前，执行下面指令配置运行环境：

下载应用开发示例包。
1. 登录后摩开发者社区。
2. 在 请先选择板级类别 下拉列表中选择使用的后摩板级产品。
3. 在版本列表中选择下载的版本号，再在 AI模型类别筛选器 、平台架构筛选器 、操作系统筛选器 下拉菜单中分别选择AI模型类型、平台架构和操作系统，找到资源名为示例代码的下载资源，选中该资源左边复选框。
4. 点击 直接下载、wget链接、批量直接下载 或 wget批量下载 按钮。
该工具位于应用开发示例包 houmo-examples-<target_hw>_<release>.zip 中 houmo-examples-xh2/tools/tcim_perf 目录下。

将应用开发示例包拷贝到可运行环境。
在 houmo-examples-xh2 目录下执行下面命令设置环境变量：
```
source env.sh
```
在 houmo-examples-xh2/tools/tcim_perf 目录下，执行下面命令编译：
```
cd tools/tcim_perf/
./build.sh
```
编译完成后，生成 tcim_perf 可执行文件，位于 tools/bin 目录下。

4.4.1.4. Android环境准备

工具使用前，执行下面指令配置运行环境：

Android设备端环境准备：配置最新版本Android驱动和固件镜像，详情参看《软件平台驱动安装指南》和《HmUpdateTool工具使用指南》。
主机端，设置Android NDK。
1. 下载官方Android NDK 软件包。该工具仅在 android-ndk-r28c 版本上验证通过。如使用其他版本，请根据实际环境进行适配。
2. 设置 NDK_PATH 环境变量，指向 Android NDK 软件包的解压路径。
主机端，配置应用开发示例：
1. download。
2. 执行下面指令解压应用开发示例包。
```
unzip houmo-examples-<target_hw>_<release>.zip
```
  解压后为 houmo-examples-xh2/ 文件夹。
3. 设置环境变量：
```
cd houmo-examples-xh2
source env.sh
```
主机端，配置Android驱动：
1. 下载新版本Android驱动安装包。
  1. 登录后摩开发者社区。
  2. 在 请先选择板级类别 下拉列表中选择使用的后摩板级产品。
  3. 在版本列表中选择下载的版本号，再在 AI模型类别筛选器 、平台架构筛选器 、操作系统筛选器 下拉菜单中分别选择AI模型类型、平台架构和操作系统，找到资源名为芯片驱动的下载资源，选中该资源左边复选框。
  4. 点击 直接下载、wget链接、批量直接下载 或 wget批量下载 按钮，下载驱动安装包。
2. 执行下面指令解压驱动安装包。
```
tar -xzf houmo-drv-<target_hw>_<release>_android_$arch.tar.gz
```
  解压后为 houmo-drv-xh2。
3. 设置 HOUMO_SDK_PATH 环境变量，指向驱动安装包的解压路径，示例如下：
```
export HOUMO_SDK_PATH=/home/houmo-drv-xh2
```
主机端，配置运行时开发工具包：
1. 下载新版本运行时开发工具包。
  1. 登录后摩开发者社区。
  2. 在 请先选择板级类别 下拉列表中选择使用的后摩板级产品。
  3. 在版本列表中选择下载的版本号，再在 AI模型类别筛选器 、平台架构筛选器 、操作系统筛选器 下拉菜单中分别选择AI模型类型、平台架构和操作系统，找到资源名为Runtime SDK的下载资源，选中该资源左边复选框。
  4. 点击 直接下载、wget链接、批量直接下载 或 wget批量下载 按钮。
2. 执行下面指令解压运行时开发工具包。
```
tar -xzf houmo-tcim-runtime-<target_hw>_<release>_${distro}_$arch.tar.gz
```
  解压后为 houmo-tcim-runtime-xh2。
3. 设置 TCIM_RUNTIME_PATH 环境变量，指向运行时开发工具包的解压路径，示例如下：
```
export TCIM_RUNTIME_PATH=/home/houmo-tcim-runtime-xh2
```
在主机端，进入 houmo-examples-xh2/tools/tcim_perf 目录下，执行下面指令编译工具：
```
./build_ndk.sh
```
编译完成后，生成 tcim_perf 可执行文件，位于 tools/android 目录下。
在主机端，将生成的 tcim_perf 传输到Android设备的 /data/houmo 目录：
```
adb push tcim_perf /data/houmo
```
在主机端，将运行时开发工具包解压后文件夹 houmo-tcim-runtime-xh2 传输到Android设备的 /data/houmo 目录：
```
adb push houmo-tcim-runtime-xh2 /data/houmo
```
在主机端，将要评测的模型文件传输到Android设备的 /data/houmo 目录，示例如下：
```
adb push resnet50.hmm /data/houmo
```
在主机端，通过 adb 进入Android设备开发板命令行，并获取 root 权限：
```
adb shell
su
```
在Android设备端，设置环境变量：
```
export TCIM_BACKEND=Xh2HalBackend
export TCIM_RUNTIME_PATH=$TCIM_RUNTIME
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/data/houmo/houmo_drv_xh2/hal/lib
```
其中 $TCIM_RUNTIME 为传输的运行时开发工具包的路径，如 /data/houmo/houmo-tcim-runtime-xh2。

执行以上步骤后，即可在 Android 环境下使用 tcim_perf 工具。

4.4.1.5. Windows环境准备

工具使用前，执行下面指令配置运行环境：

下载应用开发示例包。
1. 登录后摩开发者社区。
2. 在 请先选择板级类别 下拉列表中选择使用的后摩板级产品。
3. 在版本列表中选择下载的版本号，再在 AI模型类别筛选器 、平台架构筛选器 、操作系统筛选器 下拉菜单中分别选择AI模型类型、平台架构和操作系统，找到资源名为示例代码的下载资源，选中该资源左边复选框。
4. 点击 直接下载、wget链接、批量直接下载 或 wget批量下载 按钮。
该工具位于应用开发示例包 houmo-examples-<target_hw>_<release>.zip 中 houmo-examples-xh2\tools\tcim_perf 目录下。

将应用开发示例包拷贝到可运行环境。
在 houmo-examples-xh2 目录下执行下面命令设置环境变量：

注意

必须使用管理员权限打开命令行提示符窗口。
1. 清除历史环境变量设置：
```
env.bat --reset
```
  指令执行过程中可能需要设置 HOUMO_SDK_PATH、CMAKE_PATH、OPENCV_PATH 等环境变量。
2. 关闭命令行提示符窗口。
3. 使用管理员权限打开命令行提示符窗口，设置环境变量：
```
env.bat --set
```
  用户需要检查reset指令输出的Warning部分的路径是否正确。如果不正确需要自行删除。
4. 关闭命令行提示符窗口。
执行下面命令编译：
```
build_win.bat
```
编译完成后，生成 tcim_perf.exe 可执行文件，位于 tools\tcim_perf\build\Release 目录下。

4.4.1.6. 指令说明

模型推理性能评测工具指令如下：

Linux / Android 系统：

./tcim_perf -m <binary_model_file_name> [OPTIONS]

Windows 系统：

tcim_perf.exe -m <binary_model_file_name> [OPTIONS]

指令参数说明如下：

-m，--model：必选参数，指定用于推理的模型文件路径（.hmm）。
-i，--input：可选参数，指定输入、输出和golden 数据所在文件夹。若未指定，默认为空。
-o，--output：可选参数，指定性能结果文件的输出目录，默认为当前工作目录。
-w，--warm_up：可选参数，指定 warm up 运行次数，用于在正式评测前预热模型，默认为 1。
-b，--batch：可选参数，指定模型 batch 数，仅用于计算正确的 QPS 值，默认为 1。
-l，--loops：可选参数，指定模型内部循环次数，仅用于内部测试，默认为 1。
-t，--threads：可选参数，指定推理线程数，默认为 1。
-d，--devices：可选参数，指定推理所使用的后摩设备数量，需与模型编译时的配置一致，默认为 1。
-s，--samples：可选参数，指定测试样本数，默认为 1。
-n，--name：可选参数，指定模型名称，用于匹配对应的参考输出数据。
-y，--infer_only [<boolean>]：可选参数，用于指定性能统计的时间范围。取值如下：
- false （默认值）：统计端到端完整流程的时间，包括模型推理及输入输出数据拷贝的时间。
- true：仅统计模型推理时间，不包括模型输入输出数据拷贝的时间。
-e, --streams：可选参数，模型推理使用的stream数量，默认为4。
-p, --module_pool：可选参数，启用模型池进行推理。默认值为关闭状态。设置为 true 可启用该功能。
-c, --modules：可选参数，指定实际加载的最大模型数量，默认值为 IPU 内核数。该参数仅在启用模型池推理时生效。
-v, --interval：可选参数，按指定时间间隔（毫秒）构造输入数据并推送至推理任务队列。默认不开启，即在推理开始前将所有输入数据一次性放入任务队列。
-q, --queue_length：可选参数，设置推理任务队列的最大长度。当队列中的任务数量超过该值时，程序将中止。该参数仅在配置了 --interval 参数时生效。
-h, --help：可选参数，打印参数说明信息。

4.4.2. 端到端耗时和纯推理耗时

模型推理性能评测工具支持以下测试模式，以用于快速定位性能问题：

默认模式：执行 tcim_perf -m <binary_model_file_name> 指令，统计模型推理端到端耗时。
纯推理模式：执行 tcim_perf -m <binary_model_file_name> -y true 指令，仅统计模型推理耗时。

测试方式	统计范围	用途
默认模式	模型推理及输入输出数据拷贝的时间。	评估真实端到端性能。
纯推理模式	仅统计模型推理时间，不包括模型输入输出数据拷贝的时间。	评估纯模型推理性能。

建议对同一模型分别执行默认模式和纯推理模式测试，并按以下方式判断：

如果默认模式下的 End2End 值明显高于纯推理模式下的 Inference 值，说明输入输出、数据传输或后处理占比较高。
如果默认模式下的 End2End 值与纯推理模式下的 Inference 值接近，说明主要瓶颈在模型计算阶段。
如果默认模式下 Input 或 Output 值占比较高，应优先优化主机处理、数据传输或输入输出管理，而不是直接调整模型结构或量化配置。

4.4.3. 关键指标与瓶颈判断

模型推理性能评测工具会输出输入设置、模型推理、输出读取和端到端性能相关指标。可通过这些指标判断性能瓶颈主要来自主机/数据传输阶段，还是来自模型计算阶段。

指标	说明	瓶颈判断	优化方向
`Input`	数据从主机内存传输到后摩设备内存，并设置到模型输入的耗时。	值占比较高时，说明数据传输或输入设置开销较大。	减少重复拷贝，优化输入内存布局，使用数据预拷贝，复用输入 buffer。
`Inference`	模型推理耗时，即从数据进入推理引擎到结果输出的时间。	值占比较高时，说明模型计算阶段可能是主要瓶颈。	可通过 IPU 指令级性能分析、模型编译参数调优、量化策略优化或计算图优化等方法继续调优。详情参看模型计算性能瓶颈。
`Output`	推理结果从设备内存回传到主机内存，并进行结果解析的耗时。	值占比较高时，说明输出回传、结果读取或后处理开销较大。	减少不必要输出读取，优化输出 buffer 管理、后处理和结果解析流程。
`End2End`	默认表示端到端总耗时，包括模型推理及输入输出数据拷贝的时间。	值较高但 `Inference` 值不高时，通常说明主机处理、数据传输或输入输出管理是主要瓶颈。	优先排查输入设置、输出读取、数据传输、CPU 前处理和 CPU 后处理。详情参看主机/数据传输性能瓶颈。
`qps`	每秒处理样本数，用于评估模型吞吐能力。	`qps` 值较低但单次 `Inference` 值正常时，通常说明 batch、并发或业务调度利用不足。	调整 batch、样本数、loop、并发方式或业务调度策略。
`avg`	多次推理或多条样本测量的平均耗时。	用于判断典型性能表现。	以 `avg` 作为主要对比指标，评估不同配置下的整体性能变化。
`max`	测量中的最大耗时。	与 `avg` 差异较大时，可能存在性能抖动、系统资源竞争或偶发数据传输开销。	检查系统负载、温度、频率、内存占用和测试环境稳定性。
`min`	测量中的最小耗时。	用于观察模型在较理想状态下的最优运行表现。	可与 `avg`、`max` 对比，用于判断性能波动范围。

其中，Input 和 Output 通常属于 主机/数据传输性能指标，Inference 通常属于 模型计算性能指标。

4.5. LLM/VLM模型性能瓶颈定位

可通过LLM 推理性能评测工具评估LLM和VLM模型在M50后摩设备上的实际推理性能。工具按Prefill、Decode、Vision和端到端阶段输出性能数据，可用于定位CPU 前处理、Embedding、数据传输、模型推理和生成阶段瓶颈。

4.5.1. 使用方法

4.5.1.1. 环境依赖

该工具支持平台如下：

Linux系统：

Ubuntu 20.04及以上版本（x86_64或AArch64）
Windows系统：
- Windows11
Android系统：
- 操作系统：Android 15 (API level 35)
- CPU 架构：arm64‑v8a
- 内核版本：Linux 6.1
- 开发调试工具：adb (Android Debug Bridge)
  
  注：adb 工具默认不随系统安装。

4.5.1.2. 运行环境

工具可在下面环境中运行：

软件平台Docker镜像：

（仅支持Linux系统）软件平台提供的 Docker 镜像已预置工具运行所需环境。有关Docker镜像的安装与部署，参看《快速入门指南》。
运行时开发工具包：

可使用运行时开发工具包 houmo_tcim_runtime_<target_hw>_${distro}_$arch-<release>.tar.gz。详情参看《TCIM用户指南》。

4.5.1.3. Linux环境准备

工具使用前，执行下面指令配置运行环境：

下载应用开发示例包。
1. 登录后摩开发者社区。
2. 在 请先选择板级类别 下拉列表中选择使用的后摩板级产品。
3. 在版本列表中选择下载的版本号，再在 AI模型类别筛选器 、平台架构筛选器 、操作系统筛选器 下拉菜单中分别选择AI模型类型、平台架构和操作系统，找到资源名为示例代码的下载资源，选中该资源左边复选框。
4. 点击 直接下载、wget链接、批量直接下载 或 wget批量下载 按钮。
该工具位于应用开发示例包 houmo-examples-<target_hw>_<release>.zip 中 houmo-examples-xh2/tools/tcim_perf 目录下。

将应用开发示例包拷贝到可运行环境。
在 houmo-examples-xh2 目录下执行下面命令设置环境变量：
```
source env.sh
```
在 houmo-examples-xh2 目录下，执行下面命令编译：
```
cd tools/llm_perf
./build_linux.sh
```
编译完成后，生成 llm_perf 可执行文件，位于 tools/bin 目录下。

4.5.1.4. Windows环境准备

工具使用前，执行下面指令配置运行环境：

下载应用开发示例包。
1. 登录后摩开发者社区。
2. 在 请先选择板级类别 下拉列表中选择使用的后摩板级产品。
3. 在版本列表中选择下载的版本号，再在 AI模型类别筛选器 、平台架构筛选器 、操作系统筛选器 下拉菜单中分别选择AI模型类型、平台架构和操作系统，找到资源名为示例代码的下载资源，选中该资源左边复选框。
4. 点击 直接下载、wget链接、批量直接下载 或 wget批量下载 按钮。
该工具位于应用开发示例包 houmo-examples-<target_hw>_<release>.zip 中 houmo-examples-xh2\tools\tcim_perf 目录下。

将应用开发示例包拷贝到可运行环境中。详情参看工具支持的运行环境。
在 houmo-examples-xh2 目录下执行下面命令设置环境变量：

注意

必须使用管理员权限打开命令行提示符窗口。
1. 清除历史环境变量设置：
```
env.bat --reset
```
  指令执行过程中可能需要设置 HOUMO_SDK_PATH、CMAKE_PATH、OPENCV_PATH 等环境变量。
2. 关闭命令行提示符窗口。
3. 使用管理员权限打开命令行提示符窗口，设置环境变量：
```
env.bat --set
```
  用户需要检查reset指令输出的Warning部分的路径是否正确。如果不正确需要自行删除。
4. 关闭命令行提示符窗口。
执行下面命令编译：
```
build_win.bat
```
编译完成后，生成 llm_perf.exe 可执行文件，位于 tools\bin 目录下。

4.5.1.5. Android环境准备

工具使用前，执行下面指令配置运行环境：

Android设备端环境准备：配置最新版本Android驱动和固件镜像，详情参看《软件平台驱动安装指南》和《HmUpdateTool工具使用指南》。
主机端，设置Android NDK。
1. 下载官方Android NDK 软件包。该工具仅在 android-ndk-r28c 版本上验证通过。如使用其他版本，请根据实际环境进行适配。
2. 设置 NDK_PATH 环境变量，指向 Android NDK 软件包的解压路径。
主机端，配置应用开发示例：
1. download。
2. 执行下面指令解压应用开发示例包。
```
unzip houmo-examples-<target_hw>_<release>.zip
```
  解压后为 houmo-examples-xh2。
3. 设置环境变量：
```
cd houmo-examples-xh2
source env.sh
```
主机端，配置Android驱动：
1. 下载新版本 Android驱动安装包。
  1. 登录后摩开发者社区。
  2. 在 请先选择板级类别 下拉列表中选择使用的后摩板级产品。
  3. 在版本列表中选择下载的版本号，再在 AI模型类别筛选器 、平台架构筛选器 、操作系统筛选器 下拉菜单中分别选择AI模型类型、平台架构和操作系统，找到资源名为芯片驱动的下载资源，选中该资源左边复选框。
  4. 点击 直接下载、wget链接、批量直接下载 或 wget批量下载 按钮，下载驱动安装包。
2. 执行下面指令解压驱动安装包。
```
tar -xzf houmo-drv-<target_hw>_<release>_android_$arch.tar.gz
```
  解压后为 houmo-drv-xh2。
3. 设置 HOUMO_SDK_PATH 环境变量，指向驱动安装包的解压路径，示例如下：
```
export HOUMO_SDK_PATH=/home/houmo-drv-xh2
```
主机端，配置运行时开发工具包：
1. 下载新版本运行时开发工具包。
  1. 登录后摩开发者社区。
  2. 在 请先选择板级类别 下拉列表中选择使用的后摩板级产品。
  3. 在版本列表中选择下载的版本号，再在 AI模型类别筛选器 、平台架构筛选器 、操作系统筛选器 下拉菜单中分别选择AI模型类型、平台架构和操作系统，找到资源名为Runtime SDK的下载资源，选中该资源左边复选框。
  4. 点击 直接下载、wget链接、批量直接下载 或 wget批量下载 按钮。
2. 执行下面指令解压运行时开发工具包。
```
tar -xzf houmo-tcim-runtime-<target_hw>_<release>_${distro}_$arch.tar.gz
```
  解压后为 houmo-tcim-runtime-xh2。
3. 设置 TCIM_RUNTIME_PATH 环境变量，指向运行时开发工具包的解压路径，示例如下：
```
export TCIM_RUNTIME_PATH=/home/houmo-tcim-runtime-xh2
```
在主机端，进入 houmo-examples-xh2/tools/llm_perf 目录下，执行下面指令编译工具：
```
./build_ndk.sh
```
编译完成后，生成 llm_perf 可执行文件，位于 tools/android 目录下。
在主机端，将生成的 llm_perf 传输到Android设备的 /data/houmo 目录：
```
adb push llm_perf /data/houmo
```
在主机端，将运行时开发工具包解压后文件夹 houmo-tcim-runtime-xh2 传输到Android设备的 /data/houmo 目录：
```
adb push houmo-tcim-runtime-xh2 /data/houmo
```
在主机端，将要评测的模型文件传输到Android设备的 /data/houmo 目录，示例如下：
```
adb push prefill_model.hmm /data/houmo
adb push decode_model.hmm /data/houmo
```
在主机端，通过 adb 进入Android设备开发板命令行，并获取 root 权限：
```
adb shell
su
```
在Android设备端，设置环境变量：
```
export TCIM_BACKEND=Xh2HalBackend
export TCIM_RUNTIME_PATH=$TCIM_RUNTIME
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/data/houmo/houmo_drv_xh2/hal/lib
```
其中 $TCIM_RUNTIME 为传输的运行时开发工具包的路径，如 /data/houmo/houmo-tcim-runtime-xh2。

执行以上步骤后，即可在 Android 环境下使用 llm_perf 工具。

4.5.1.6. 指令说明

模型推理性能评测工具指令如下：

Linux / Android 系统：
```
./llm_perf [OPTIONS]
```
Windows 系统：
```
llm_perf.exe [OPTIONS]
```

指令参数说明如下：

--prefill <prefill_model>：必选参数，指定prefill模型文件路径（.hmm或.hmms）。
--decode <decode_model>：必选参数，指定decode模型文件路径（.hmm或.hmms）。
--visual <vlm_model>：可选参数，用于指定VLM（Vision Large Language Model，视觉语言模型）模型文件路径。默认为LLM模型路径。
--embedding <embedding_model>：必选参数，指定embedding模型文件路径（.bin）。用户需通过 convert_embed.py 工具将embedding的PT模型转换为 bin 文件。详情参看 embedding。
--input <prefill_token_num>：必选参数，指定prefill 阶段输入token 数。
--output <decode_token_num>：必选参数，指定 decode 阶段需要生成的 token 数，即推理输出序列的长度。
--devices <device_id>：可选参数，指定推理使用的后摩逻辑设备ID列表。

后摩逻辑设备ID表示单颗M50芯片在系统中的唯一逻辑编号；一个后摩设备中可能包含多颗M50芯片，因此可对应多个逻辑设备ID；多个后摩设备通过HM-Link（CTC）互联后，也会统一映射为多个逻辑设备 ID。

多个设备ID需使用逗号分隔，例如：--devices 0,1。取值规则（优先级从高到低）如下：
- --devices 参数显式指定的值。
- 环境变量 HOUMO_VISIBLE_DEVICES 取值。
- 默认值 0 （逻辑设备 0）。
注：--devices 指定多个设备（≥ 2）时，仅支持加载 .hmms格式的模型文件；.hmm格式在多设备场景下不支持。
--loop <loop_num>：可选参数，指定性能评测中重复执行同一模型的次数。默认值为1。
--batch <batch_num>：可选参数，指定模型的batch数，默认值为1。该参数取值必须与模型编译接口 build_from_hmonnx 中 modify_llm 参数中设置的 batch 字段取值相同，否则将导致推理失败。
--no_warm_up：可选参数，默认在正式测试前执行若干次推理过程，用于消除模型初始化和运行时冷启动带来的影响（warm up）。配置该参数后，将跳过 warm up，直接进入性能测试。
--warm_up_output <warmup_decode_token_num>: 设置warm up阶段decode模型输出的token数量，默认值为 --output <decode_token_num> 参数取值。若设置 --no_warm_up，则该参数值无效。
--warm_up_input <warmup_prefill_token_num>: 设置warm up阶段prefill模型输出的token数量，默认值为 --input <prefill_token_num> 参数取值。若设置 --no_warm_up，则该参数值无效。
--LazyMode: 启用 LazyMode 模式。在该模式下，模型加载过程中会延迟分配和初始化主机端缓冲区，以降低加载阶段的峰值内存占用，但可能会增加模型加载时间。默认情况下该模式关闭。
--interval <interval>: 设置后摩逻辑设备监控信息（Device Stats）的采样间隔，包括后摩逻辑设备温度、IPU 频率、功率以及主机内存信息。单位为毫秒（ms）。默认值为 500 ms，取值范围为 100 ms ~ 60000 ms 。
--skip_perf: 默认会执行性能评估。启用该参数后将跳过性能评估，仅完成模型加载，不执行模型推理。
--dump_file <filename.yaml>: 将性能数据保存到 YAML 文件。默认不导出性能数据；配置该参数后，性能数据会写入指定的 YAML 文件。
--config, -c：可选参数，通过JSON或YAML配置文件设置性能评测参数。该参数不能与其他命令行参数同时使用。若需要对多个模型进行评测，则必须使用该参数配置。详情参看 json。
--help, -h：可选参数，打印工具帮助信息。

4.5.2. 瓶颈判断

4.5.2.1. Prefill阶段瓶颈判断

Prefill阶段主要处理输入prompt。长输入场景下，Prefill耗时会直接影响 TTFT。

指标	问题判断	优化方向
`Tokenization total Time` 值较高	分词耗时较高，属于CPU前处理瓶颈。	优化tokenizer调用，减少重复分词，增加CPU并发。
`Embedding total Time` 值较高	主机侧Embedding生成耗时较高，属于主机/数据传输性能瓶颈。	优化CPU资源、线程绑定、并发策略或Embedding实现。
`API SetInput total Time` 值较高	输入设置或主机侧到后摩设备侧数据传输耗时较高。	减少输入拷贝，使用数据预拷贝，优化输入buffer管理。
`API Inference total Time` 值较高	Prefill模型推理耗时高，属于模型计算瓶颈。	可通过算子级优化、编译参数性能优化、调整量化策略或图优化等方法优化性能。详情参看模型计算性能瓶颈。
`API GetOutput total Time` 值较高	输出回传或结果读取耗时高。	减少不必要输出，优化输出读取和解析流程。
`Prefill Speed` 值较低	Prefill阶段整体处理速度低。	结合Tokenization、Embedding、输入设置、模型推理和输出读取阶段数据判断具体瓶颈。

4.5.2.2. Decode阶段瓶颈判断

Decode阶段逐token生成输出，通常直接影响TPOT和生成速度。

指标	问题判断	优化方向
`API Inference avg Time` 值较高	Decode阶段每生成一个输出token所需的模型推理耗时较高。	检查Decode模型编译配置是否匹配实际运行场景；必要时评估量化配置或图优化策略。
`API SetInput avg Time` 值较高	Decode阶段每生成一个输出token时，输入设置或KV Cache设置开销较高。	复用已分配的输入buffer和KV Cache buffer，减少每轮Decode的重复绑定、重复初始化或重复数据拷贝。
`API GetOutput avg Time` 值较高	Decode阶段每生成一个输出token时，输出读取耗时较高。	减少非必要输出读取，优化logits读取、采样和token解码流程。
`Decode Speed` 值较低	Decode生成速度低。	结合 `API Inference avg Time`、`API SetInput avg Time` 和 `API GetOutput avg Time` 判断瓶颈来自模型推理、输入设置还是输出读取。
`TPOT` 值较高	每个输出token延迟高。	重点排查Decode阶段的模型推理耗时、KV Cache buffer复用、输出读取和采样逻辑。

4.5.2.3. Vision 阶段瓶颈判断

对于VLM模型，还需要关注Vision阶段。纯LLM模型不包含图像输入时，该阶段指标通常为0或不显示。

指标	问题判断	优化方向
`Preprocessing Time` 值较高	图像预处理耗时较高。	检查图像处理、归一化和格式转换流程，减少重复处理和不必要的数据格式转换。
`API SetInput total Time` 值较高	图像输入设置或主机到后摩设备的数据传输耗时较高。	复用图像输入buffer，减少重复申请、释放和拷贝；对固定或可复用图像输入，可考虑提前完成数据准备或数据预拷贝。
`API Inference total Time` 值较高	视觉编码模型推理耗时较高。	检查视觉模型编译配置是否匹配实际输入尺寸、batch、ncore、nchip等运行配置；必要时可通过算子级优化、编译参数性能优化、调整量化策略或图优化等方法优化性能。详情参看模型计算性能瓶颈。
`API GetOutput total Time` 值较高	视觉特征读取或结果传递耗时较高。	检查是否读取了非必要输出；减少视觉特征回传数据量，优化输出buffer复用和结果读取流程。

4.6. 性能调优方法

4.6.1. 主机/数据传输性能瓶颈

主机/数据传输性能瓶颈通常在推理工具输出中表现为数据传输、Embedding或Tokenization阶段耗时异常。确认这些指标合理后，再关注模型计算性能。

可以采用以下优化策略：

CPU前处理优化

对Tokenizer、Embedding和图像预处理增加并发执行。
对CPU密集型任务进行线程绑定，减少线程切换开销。
对重复输入或固定输入，复用Tokenization或Embedding结果。
对图像输入，优化图像resize、crop、padding、归一化和格式转换流程。
可通过增加并发或绑定线程优化多线程性能。
确认CPU负载均衡、线程亲和性合理。

数据传输和输入设置优化

对固定或重复输入使用数据预拷贝，将数据提前放到后摩设备端。
优化输入buffer管理，减少频繁申请、释放和格式转换。
确认输入shape、layout、dtype与模型一致，避免运行时转换。
对LLM Decode阶段，优化KV Cache输入管理，减少每步数据搬移。

输出读取和后处理优化

减少不必要的输出节点读取。
优化输出buffer管理，避免重复申请和拷贝。
优化后处理逻辑，例如NMS、分类阈值过滤、类别映射或结果解析。
对LLM Decode阶段，优化logits读取、采样和token解码流程。

系统资源优化

检查设备温度、功耗和IPU频率，保证运行稳定。
保证主机CPU、内存和IO资源充足。
避免同时运行高负载任务。
检查模型加载和推理内存使用情况，避免峰值过高。

4.6.2. 模型计算性能瓶颈

针对模型推理阶段的瓶颈，可采用以下方法：

算子级优化

使用Profiler性能调试工具定位计算图中耗时最高的IPU核指令。
由于该工具当前展示IPU核指令的性能数据，目前无法与模型算子对应，用户需将信息反馈给技术支持工程师，进行算子实现、图优化或编译策略优化。

量化策略优化

调整量化精度或混合精度配置。
对性能瓶颈层进行重点量化，平衡精度和速度。
优化量化配置后重新执行精度评测。

详情参看量化策略优化。

计算图优化

图优化的目的就是让IPU硬件高效执行同样的计算逻辑，减少开销、提升吞吐。
使用模型转换与评估工具内置图优化功能，包括算子融合、节点合并和冗余节点移除。

详情参看计算图优化。

LLM分阶段优化

Prefill 阶段：优化输入长度、batch、输入设置（SetInput）调用和模型计算。
Decode 阶段：优化每步推理、KV Cache管理和输出读取。
Vision 阶段（VL模型）： 优化图像预处理、输入拷贝和视觉编码算子。

复杂模型或特殊算子

收集性能评测结果、Profiler性能调试工具测试结果、模型文件、编译配置和运行命令。
使用模型推理性能评测工具对比默认测试和纯推理模式的测试结果，确认瓶颈。
将信息反馈给技术支持工程师，进行算子实现、图优化或编译策略优化。

4.6.2.1. 量化策略优化

小模型（CV/检测/分类/分割）量化策略详情，参看量化调优。

LLM/vLM量化策略详情，参看量化调优。

4.6.2.2. 编译参数调优

部分编译参数对模型推理速度、吞吐率和资源利用效率有显著影响。通过合理调整这些参数，可以提升模型在M50后摩设备上的整体性能。

下面以qwen3模型为例，介绍编译参数调优方法。

在 houmo-examples-xh2/models/llm/qwen3 目录下，修改 config.yml 配置文件。示例如下：
```
...
build:
  ncore: 1
  opt_level: 2
  batch: 1
  roi_num: 1
  parallel_jobs: 4
...
```
其中，opt_level 参数表示优化等级，需要获得更优推理性能。优先使用 O2。O0 主要用于快速调试，不建议使用 O0 结果评估最终推理性能。
根据调整后的编译配置重新生成编译模型。执行以下命令：
```
hmatc build -c config.yml
```
使用性能评估工具复测模型性能。

4.6.2.3. 计算图优化

模型转换与评估工具内置图优化功能，包括算子融合、节点合并和冗余节点移除。

4.6.2.3.1. 适用场景

当模型中包含以下算子时，可启动图优化能力进行模型优化：

Slice
Gather
Unsqueeze
Squeeze
Transpose
Reshape
MaxPool
AveragePool
Conv

4.6.2.3.2. 开启图优化

对于已支持的算子，用户只需在 config.yml 中开启图优化功能即可。

下面以Yolov5s为例，介绍如何开启图优化功能：

在 houmo-examples-xh2/models/detection/yolov5s 目录下，设置 config.yml 配置文件。示例如下：

model:
  name: yolov5s
  save_dir: output
  model_path: yolov5s.onnx
  inputs:
    images:
      shape: [1, 3, 640, 640]  # NCHW
      data_format: RGB
      mean: [0.0, 0.0, 0.0]
      std: [255.0, 255.0, 255.0]
      resize_type: 1
      padding_mode: 1
      padding_values: [114, 114, 114]
      resizer:
        toYUV_format: YUV420SP
  model_impl_module: model_impl
  model_impl_cls: YoloV5

quant:
  calib_data: coco2017/val2017
  calib_num: 32

build:
  ncore: 1
  opt_level: 2

demo:
  data_dir: coco2017/val2017
  num: 10

eval:
  data_dir: coco2017
  num: 0
  dataset_module: dataset
  dataset_cls: Dataset

app_onnx_opt:
  optimizer: true
  log_level: 0

其中，图优化相关的关键配置如下：

optimizer：是否开启 ONNX 图优化。设置为 true 时，启动图优化功能。
log_level：图优化日志级别和工作模式。0 表示所有图优化完成后执行一次一致性比对，适合正常使用。 1 表示每类优化完成后执行一致性比对，适合排查问题。 2 表示每个优化函数每次完成优化后执行一致性比对，适合开发新优化规则。

执行图优化，需重新量化模型：
```
hmatc quant -c config.yml
```
指令执行时，工具会自动检查 model.app_onnx_opt 配置。如果 optimizer 设置为 true，工具会先对原始 ONNX 模型执行图优化，再进入量化流程。

用户可基于优化后的ONNX模型进一步进行编译、推理，并使用性能评测工具对比优化前后的 Inference、qps、TTFT、TPOT 或 E2E TPS。

有关模型转换与评估工具详细使用说明，参看《模型转换与评估工具用户指南》。

4.6.2.3.3. 扩展自定义图优化规则

如果模型中的热点算子或子图不在当前已支持范围内，可根据实际需求扩展自定义图优化规则。

扩展方式如下：

在 houmo-examples-xh2/hmatc/hmatc/optimizer 目录下新增或修改相关优化规则文件，实现算子替换、算子融合或冗余节点删除逻辑。
在 onnxXh2Optimizer.py 的 opt_loop() 中调用新增的优化规则。
执行开启图优化重新生成量化后模型。
编译和推理和使用性能评测工具对比优化前后的 Inference、qps、TTFT、TPOT 或 E2E TPS。
对比优化前后的模型性能和精度结果。

备注

自定义图优化规则会直接改变 ONNX 计算图结构。建议仅在充分理解模型结构、算子语义和后处理依赖关系的情况下使用。完成自定义优化后，必须重新执行精度评估和性能评测，确认优化结果符合预期。