19-01 Profiling数据采集接口

本章节描述Profiling数据采集的核心接口，用于性能采集的初始化、配置、启停控制。Profiling产物路径、解析命令和字段含义请参见Profiling产物解读。

• aclError aclprofInit(const char *profilerResultPath, size_t length)：初始化Profiling，目前用于设置保存性能数据的文件的路径。
• aclError aclprofSetConfig(aclprofConfigType configType, const char *config, size_t configLength)：aclprofCreateConfig接口的扩展接口，用于设置性能数据采集参数。
• aclError aclprofStart(const aclprofConfig *profilerConfig)：下发Profiling请求，使能对应数据的采集。
• aclError aclprofStop(const aclprofConfig *profilerConfig)：停止Profiling数据采集。
• aclError aclprofFinalize()：结束Profiling。

数据采集说明

总体约束

不能与订阅算子信息的接口交叉调用：aclprofInit接口和aclprofFinalize接口之间不能调用aclprofModelSubscribe接口、aclprofGet*接口、aclprofModelUnSubscribe接口。

接口约束说明

• 调用接口要求：

  • aclprofInit接口必须在aclInit接口之后、模型加载之前调用。

    如果已经通过aclInit接口配置了Profiling信息，则调用aclprofInit接口、aclprofStart接口、aclprofStop接口、aclprofFinalize时，会返回报错。

    如果没有调用aclprofInit接口，调用aclprofStart接口、aclprofStop接口、aclprofFinalize时，会返回报错。

  • aclprofStart接口在模型执行之前调用，若在模型执行过程中调用aclprofStart接口，Profiling采集到的数据为调用aclprofStart接口之后的数据，可能导致数据不完整。

    调用aclprofStart接口时，可以指定从一个Device上采集性能数据，也可以指定从多个Device上采集性能数据。

    一个用户APP进程内，如果连续调用多次aclprofStart接口，指定重复的Profiling配置，或指定的Device重复，会返回报错。

  • 在用户APP的进程生命周期内，aclprofInit接口与aclprofFinalize接口配对使用，建议只调用一次，如该组合多次调用可以改变保存性能数据的文件的路径。

  • aclprofStart接口与aclprofStop接口需配对使用。

  • aclprofSetConfig接口必须在aclprofStart接口之前调用。一个APP进程内，可以根据需要选择一次或多次调用aclprofSetConfig接口。

  • 调用aclFinalize并接收到正常退出码后为执行完毕，其他情况为非正常。由于性能数据采集不支持多进程并发执行，为确保驱动关闭正常，需要在前一个性能数据采集用例完全执行完毕之后再执行下一轮采集。建议在aclFinalize接口返回值上加入异常处理操作，方便展示执行状态与问题定位。

• 接口调用顺序：

  • 建议的接口调用顺序如下，以“一个用户APP进程内采集多个模型推理时的性能数据”为例：

    aclInit接口-->aclprofInit接口-->aclprofStart接口(指定Device 0和Device 1)-->模型1加载-->模型1执行-->aclprofStop接口(与aclprofStart接口的aclprofConfig数据保持一致)-->aclprofStart接口(指定Device 1和Device 2)-->模型2加载-->模型2执行-->aclprofStop接口(与aclprofStart接口的aclprofConfig数据保持一致)-->aclprofFinalize接口-->执行其它任务-->模型卸载-->aclFinalize接口

  • 错误的接口调用顺序示例如下，以“一个用户APP进程内，如果连续调用多次aclprofStart接口，指定的Device重复”为例：

    aclInit接口-->aclprofInit接口-->aclprofStart接口(指定Device 0和Device 1)-->aclprofStart接口(指定Device 1和Device 2)-->模型1加载-->模型1执行-->模型2加载-->模型2执行-->aclprofStop接口-->aclprofStop接口-->aclprofFinalize-->执行其它任务-->模型卸载-->aclFinalize接口

---

aclprofInit

aclError aclprofInit(const char *profilerResultPath, size_t length)

产品支持情况

• Ascend 950PR/Ascend 950DT：支持

• Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持

• Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持

• Atlas 200I/500 A2 推理产品：支持

• Atlas 推理系列产品：支持

• Atlas 训练系列产品：支持

• IPV350：不支持

功能说明

初始化Profiling，目前用于设置保存性能数据的文件的路径。

参数说明

参数名	输入/输出	说明
profilerResultPath	输入	指定保存性能数据的文件的路径，支持配置为绝对路径或相对路径。
length	输入	profilerResultPath的长度，单位为Byte，最大长度不超过4096字节。

返回值说明

返回0表示成功，返回其他值表示失败，请参见aclError。

约束说明

与aclprofFinalize接口配对使用，先调用aclprofInit接口再调用aclprofFinalize接口。

aclprofSetConfig

aclError aclprofSetConfig(aclprofConfigType configType, const char *config, size_t configLength)

产品支持情况

• Ascend 950PR/Ascend 950DT：支持

• Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持

• Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持

• Atlas 200I/500 A2 推理产品：支持

• Atlas 推理系列产品：支持

• Atlas 训练系列产品：支持

• IPV350：不支持

功能说明

aclprofCreateConfig接口的扩展接口，用于设置性能数据采集参数。

该接口支持多次调用，用户需要保证数据的一致性和准确性。

参数说明

参数名	输入/输出	说明
configType	输入	性能数据采集参数类型。每个枚举表示不同采集配置，若要使用该接口下不同的选项采集多种性能数据，则需要多次调用该接口，详细请参见aclprofConfigType。
config	输入	指定配置项参数值。
configLength	输入	config的长度，单位为Byte，最大长度不超过256字节。

返回值说明

返回0表示成功，返回其他值表示失败，请参见aclError。

约束说明

先调用aclprofSetConfig接口再调用aclprofStart接口，可根据需求选择调用该接口。

aclprofStart

aclError aclprofStart(const aclprofConfig *profilerConfig)

产品支持情况

• Ascend 950PR/Ascend 950DT：支持

• Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持

• Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持

• Atlas 200I/500 A2 推理产品：支持

• Atlas 推理系列产品：支持

• Atlas 训练系列产品：支持

• IPV350：不支持

功能说明

下发Profiling请求，使能对应数据的采集。

用户可根据需要，在模型执行时按需调用aclprofStart接口，Profiling采集到的数据为调用该接口之后的数据。

参数说明

参数名	输入/输出	说明
profilerConfig	输入	指定Profiling配置数据。类型定义请参见aclprofConfig。 需提前调用aclprofCreateConfig接口创建aclprofConfig类型的数据。

返回值说明

返回0表示成功，返回其他值表示失败，请参见aclError。

约束说明

与aclprofStop接口配对使用，先调用aclprofStart接口再调用aclprofStop接口。

aclprofStop

aclError aclprofStop(const aclprofConfig *profilerConfig)

产品支持情况

• Ascend 950PR/Ascend 950DT：支持

• Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持

• Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持

• Atlas 200I/500 A2 推理产品：支持

• Atlas 推理系列产品：支持

• Atlas 训练系列产品：支持

• IPV350：不支持

功能说明

停止Profiling数据采集。

参数说明

参数名	输入/输出	说明
profilerConfig	输入	指定停止Profiling数据采集的配置。类型定义请参见aclprofConfig。 与aclprofStart接口中的aclprofConfig类型数据保持一致。

返回值说明

返回0表示成功，返回其他值表示失败，请参见aclError。

约束说明

与aclprofStart接口配对使用，先调用aclprofStart接口再调用aclprofStop接口。

aclprofFinalize

aclError aclprofFinalize()

产品支持情况

• Ascend 950PR/Ascend 950DT：支持

• Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持

• Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持

• Atlas 200I/500 A2 推理产品：支持

• Atlas 推理系列产品：支持

• Atlas 训练系列产品：支持

• IPV350：不支持

功能说明

结束Profiling。

参数说明

无

返回值说明

返回0表示成功，返回其他值表示失败，请参见aclError。

约束说明

与aclprofInit接口配对使用，先调用aclprofInit接口再调用aclprofFinalize接口。