【HarmonyOS 6.0】CANN Kit 新增支持获取 AI 模型 Dump 维测数据功能详解

文章目录

[1 -> 背景与概述](#1 -> 背景与概述)
[2 -> 功能定位：Dump 模式解决什么问题](#2 -> 功能定位：Dump 模式解决什么问题)
- [2.1 -> 与已有 Profiling 能力的关系](#2.1 -> 与已有 Profiling 能力的关系)
[3 -> 技术原理：Dump 数据是如何生成的](#3 -> 技术原理：Dump 数据是如何生成的)
- [3.1 -> 底层机制](#3.1 -> 底层机制)
[4 -> 核心 API：HiAI_OmType 详细解析](#4 -> 核心 API：HiAI_OmType 详细解析)
- [4.1 -> 类型定义原型](#4.1 -> 类型定义原型)
- [4.2 -> 配套的配置辅助函数](#4.2 -> 配套的配置辅助函数)
[5 -> 代码集成示例](#5 -> 代码集成示例)
- [5.1 -> 头文件引用](#5.1 -> 头文件引用)
- [5.2 -> 创建选项对象并配置 Dump 模式](#5.2 -> 创建选项对象并配置 Dump 模式)
- [5.3 -> 将选项对象应用到模型加载](#5.3 -> 将选项对象应用到模型加载)
- [5.4 -> 调用编译和执行流程](#5.4 -> 调用编译和执行流程)
- [5.5 -> 资源释放](#5.5 -> 资源释放)
[6 -> 应用层集成注意事项](#6 -> 应用层集成注意事项)
[7 -> 数据解析与问题定位](#7 -> 数据解析与问题定位)
- [7.1 -> 数据导出](#7.1 -> 数据导出)
- [7.2 -> 数据解析方式](#7.2 -> 数据解析方式)
[8 -> 约束与限制](#8 -> 约束与限制)
[9 -> 总结与展望](#9 -> 总结与展望)

1 -> 背景与概述

在 AI 模型端侧部署过程中，开发者面临的一大痛点就是模型在端上与训练时的精度差异难以定位。传统的调试手段大多依赖日志输出，无法深入到模型的每一层进行计算结果的逐级比对，这使得问题的排查效率十分低下。

HarmonyOS 6.0 的 CANN Kit 在维测能力层面新增了 Dump 模式支持。维测调优是 CANN Kit 提供的数据统计划分能力，能够让开发人员分析模型和单算子的性能数据，并通过模型的层级输出对比精度来完成问题定位。该功能并非 HarmonyOS 6.0 的全新独创，而是基于已有 Profiling 能力的一次重要横向扩展。在此之前，CANN Kit 主要侧重于模型的推理执行，开发者能够获取到的调试信息较为有限。Dump 维测数据的加入填补了模型精度调试领域的空白。

本文将从功能定位、技术原理、使用流程、代码实现及数据解析等多个维度，对这一新增能力进行全面深入的讲解。

2 -> 功能定位：Dump 模式解决什么问题

CANN Kit 主要提供了两种维测模式：

Profiling 模式：支持单算子及整网模型的耗时统计，可分析单算子及整网的执行耗时，并提供性能数据可视化；
Dump 模式：获取模型的层级输出，实现推理过程中间结果的逐层导出。

Profiling 模式解决的是"模型跑得慢"的问题，通过分析各算子的执行耗时来定位性能瓶颈；而 Dump 模式解决的是"模型跑得不准"的问题，通过导出每一层的计算结果与标杆数据进行比对，快速定位精度异常的算子层。两者分别从性能和精度两个维度构成了完整的模型维测体系。

2.1 -> 与已有 Profiling 能力的关系

在此之前，CANN Kit 已经有了较为完善的 Profiling 性能统计能力。开发者可以通过配置 Profiling 选项来获取模型推理过程中各阶段的执行耗时。Dump 功能的加入使得维测能力由"量"的统计向"质"的检验进行了拓展。两种能力共用同一套配置框架，同样通过 HiAI_OmType 进行设置。开发者可以根据实际需要选择单独开启 Profiling、单独开启 Dump，或者同时开启两者。

3 -> 技术原理：Dump 数据是如何生成的

3.1 -> 底层机制

CANN 在执行离线模型推理时，NPU 内部会执行一个由多个算子节点构成的计算图。Dump 模式的核心机制，就是在推理引擎执行计算图的过程中，在每一个算子执行完成后将输出 Tensor 的内容导出到指定存储位置。

对于开发者而言，整个 Dump 过程需要经历三个关键阶段：

模型转换阶段：开发者需使用 CANN 提供的 DDK 工具将源模型（Caffe、TensorFlow、ONNX、MindSpore 等）转换为 OM 离线模型格式。

配置与编译阶段：在应用代码中通过设置维测选项，指示推理引擎在编译和运行模型时插入 Dump 逻辑。此阶段并不实际产生 Dump 数据，而是为运行时的数据导出做好准备。

推理与导出阶段：当模型在设备端实际执行推理时，CANN 运行时根据编译阶段设定的配置，在指定路径生成 Dump 数据文件，包含各层的输出结果。

生成的 Dump 数据以二进制格式落盘，存储于设备的特定目录下（通常为 /data/local/tmp/ 下与应用相关的路径），开发者可将其拉取至 PC 端进行后续的精度比对分析。

4 -> 核心 API：HiAI_OmType 详细解析

Dump 功能的核心配置接口是 HiAI_OmType。这一类型定义（Type Definition）是对原有性能统计能力的扩展。

4.1 -> 类型定义原型

HiAI_OmType 本质上是一个枚举类型，用于表示不同的维测模式组合：

模式取值	含义
`HiAI_OM_TYPE_GENERAL`（默认模式）	不进行任何维测数据的收集
`HiAI_OM_TYPE_PROFILING`	仅进行 Profiling 数据收集
`HiAI_OM_TYPE_DUMP`（新增）	Dump 模式下保留模型层级输出
`HiAI_OM_TYPE_PROFILING_DUMP`	同时进行 Profiling 与 Dump 数据收集

默认值为 HiAI_OM_TYPE_GENERAL。

4.2 -> 配套的配置辅助函数

配置 Dump 行为的主要函数为 HMS_HiAIOptions_SetOmOptions，其函数原型如下：

c 复制代码

OH_NN_ReturnCode HMS_HiAIOptions_SetOmOptions(
    HiAI_Options *options,
    HiAI_OmType type,
    const char *outputDir
);

参数说明：

options：模型选项对象的指针，需要通过 HMS_HiAIOptions_Create 预先创建；
type：维测类型标识，取自 HiAI_OmType 枚举值；
outputDir：输出的目标目录，用于指定 Dump 数据的持久化存储路径。

5 -> 代码集成示例

5.1 -> 头文件引用

在 Native 模块中实现 Dump 功能时，首先需要引入必需的 CANNKit/hiai_options.h 头文件：

c 复制代码

#include "neural_network_runtime/neural_network_core.h"
#include "CANNKit/hiai_options.h"

5.2 -> 创建选项对象并配置 Dump 模式

c 复制代码

// 创建选项对象（通常在加载或编译模型之前完成）
HiAI_Options *options = HMS_HiAIOptions_Create();
if (options == NULL) {
    // 选项创建失败的相关处理逻辑
    // ......
    return;
}

// 设置维测选项为 DUMP 模式并指定输出目录
OH_NN_ReturnCode ret = HMS_HiAIOptions_SetOmOptions(
    options,
    HiAI_OM_TYPE_DUMP,           // 指定模式：Dump模式
    "/data/local/tmp/dump_data"  // 输出目录
);
if (ret != OH_NN_SUCCESS) {
    // 选项设置失败时的相关处理逻辑
    HMS_HiAIOptions_Destroy(options);
    // ......
    return;
}

5.3 -> 将选项对象应用到模型加载

在使用 OH_NNCompilation_ConstructWithOfflineModelBuffer 加载离线模型时需传入 options 参数。当前 CANN Kit NAPI 层接口需要一个承载此结构化配置的功能封装：

c 复制代码

// 构建编译实例并传入选项对象
OH_NNCompilation *compilation = NULL;
ret = OH_NNCompilation_ConstructWithOfflineModelBuffer(
    modelBuffer, 
    modelBufferSize, 
    OH_NN_DEVICE_TYPE_NPU, 
    options, 
    &compilation
);
if (ret != OH_NN_SUCCESS) {
    // 失败处理逻辑
    // ......
    return;
}

5.4 -> 调用编译和执行流程

当 options 中包含 HiAI_OM_TYPE_DUMP 标识并且 outputDir 路径有效时，CANN 运行时会开启 Dump 功能，并在推理完成后将各算子的输出写入对应的文件中。

c 复制代码

// 执行编译（编译过程中即会根据 options 配置确定 Dump 相关的运行时行为）
ret = OH_NNCompilation_Build(compilation);
// ......（后接创建执行器、同步推理、输出解析等常规流程）

5.5 -> 资源释放

c 复制代码

// 释放编译实例
OH_NNCompilation_Destroy(compilation);
// 释放选项对象
HMS_HiAIOptions_Destroy(options);

6 -> 应用层集成注意事项

在通过 Codelab 等样例工程集成 Dump 功能时需要注意以下要点：

文件预置路径 ：离线模型文件、模型输入文件需要预置于手机固定路径下，通常是与应用的 bundleName 对应的 /data/local/tmp/ 路径下。

多输入节点的输入匹配 ：若模型存在多个输入节点，开发者需为每个输入节点分别指定对应的输入二进制文件。在 Netron 或其他模型可视化工具中查看 Inputs 的顺序，确保文件选择的顺序与模型输入定义顺序严格一致。

权限考量 ：应用运行过程中访问 outputDir 时涉及到文件系统的访问权限问题。建议所使用的路径位于应用的沙箱范围或已获得用户许可的公共数据区域。

7 -> 数据解析与问题定位

Dump 数据生成后，开发者需要进行以下几个操作完成精度对齐定位。

7.1 -> 数据导出

通过 hdc file recv 指令将 Dump 数据文件从设备端拉取至 PC 执行解析。例如：

bash 复制代码

hdc file recv /data/local/tmp/dump_data/ ./dump_analysis/

7.2 -> 数据解析方式

Dump 生成的数据为 Tensor 序列化的二进制文件。想要读懂这些数据，需要知道各个 Tensor 的形状和数据类型。目前业界典型的解析方案（经验之谈层面）包括：

依托已有的 CANN ToolKit 工具链对二进制输出进行反序列化（参考 AscendC 溢出算子数据采集与解析流程）；
编写自定义转换脚本（如 Python NumPy）将二进制文件还原为可读的张量结果；
结合标杆数据（如 ONNX 模型的 CPU/GPU 中间结果）执行逐层 MSE（均方误差）对比，确定精度异常的算子范围。

8 -> 约束与限制

系统版本要求 ：当前 Dump 功能仅支持 HarmonyOS 6.0.0(20) 及以上版本的华为手机设备。开发调试时需确保使用的设备系统版本满足该约束条件。

开发工具版本要求：DevEco Studio 需要 6.0.0 Release 及以上版本，HarmonyOS SDK 同样需要 6.0.0 Release SDK 及以上。

仅用于调试目的 ：Dump 模式在推理执行中会增加文件 I/O 操作，对模型推理的实时性能有一定影响，因此仅在开发者调试和精度校准阶段开启。正式发布的 Release 版本中应关闭此选项，设置为 HiAI_OM_TYPE_GENERAL。

9 -> 总结与展望

CANN Kit 在 HarmonyOS 6.0 中新增的模型 Dump 维测数据获取能力，是对鸿蒙端侧 AI 调试工具箱的一次重要补全。通过将 Profiling（性能数据获取）与 Dump（精度数据获取）两套体系融为一体，开发者可以更高效地完成从模型转换、端侧部署到故障定位的完整调优流程。

核心价值回顾：

精度定位可视化：通过层级输出与标杆对比，让原来抽象的精度失配问题在算子级别变得透明可见；
数据比对自动化：结合 Profiling 性能视角形成跨维度闭环，显著降低了 AI 应用开发的门槛；
易于扩展 ：基于统一的 HiAI_OmType 框架，未来可进一步扩展更多维测场景。

随着端侧 AI 应用计算密度的逐步提升------从 CV 图像处理到 AIGC 端侧模型场景------精度调试和性能优化将愈发依赖完备的数据维测能力。Dump 功能的加入不仅解决了一个具体的调试问题，更代表了 CANN Kit 从"单纯推理执行框架"向"全链路 AI 应用开发支撑平台"演进的关键一步。

感谢各位大佬支持！！！
互三啦！！！