aclInit
函数功能
AscendCL初始化函数。
约束说明
- 使用AscendCL接口开发应用时，必须先调用aclInit接口，否则可能会导致后续系统内部资源初始化出错，进而导致其它业务异常。
- 一个进程内只能调用一次aclInit接口，且与aclFinalize去初始化接口配对使用。
函数原型
aclError aclInit(const char *configPath)
参数说明
参数名 |
输入/输出 |
说明 |
|---|---|---|
configPath |
输入 |
配置文件所在路径（包含文件名）的指针。配置文件内容为json格式（json文件内的“{”的层级最多为10，“[”的层级最多为10）。 初始化AscendCL时，可通过该配置文件开启或设置以下功能，如果以下的默认配置已满足需求，无需修改，可向aclInit接口中传入NULL，或者可将配置文件配置为空json串（即配置文件中只有{}）。
说明：
建议不要同时配置dump信息和Profiling采集信息，否则dump操作会影响系统性能，导致Profiling采集的性能数据指标不准确。 |
返回值说明
返回0表示成功，返回其他值表示失败。
配置文件示例（模型Dump配置、单算子Dump配置）
约束说明：在训练场景下，若通过本接口的dump_step参数指定采集哪些迭代的Dump数据，同时配置了其它采集指定迭代Dump数据的session参数，则以最后配置的参数为准。
模型Dump配置示例如下：
{
"dump":{
"dump_list":[
{ "model_name":"ResNet-101"
},
{
"model_name":"ResNet-50",
"layer":[
"conv1conv1_relu",
"res2a_branch2ares2a_branch2a_relu",
"res2a_branch1",
"pool1"
]
}
],
"dump_path":"$HOME/output",
"dump_mode":"output",
"dump_op_switch":"off",
"dump_data":"tensor"
}
}
单算子Dump配置示例如下：
{
"dump":{
"dump_path":"output",
"dump_list":[],
"dump_op_switch":"on",
"dump_data":"tensor"
}
}
配置项 |
参数说明 |
备注 |
|---|---|---|
dump |
- |
|
dump_list |
（必填）待dump数据的整网模型列表。 创建模型dump配置信息，当存在多个模型需要dump时，需要每个模型之间用英文逗号隔开。 在单算子执行场景下，dump_list为空。 |
- |
model_name |
模型名称。
|
|
layer |
算子名。可以指定为ATC模型转换后的算子名，也支持指定为转换前的原始算子名。
在指定算子dump时，用户可以无需设置model_name，此时会默认dump所有model下的相应算子。如果配置了model_name，则dump对应model下的相应算子。 |
IO性能相对较差时，可能会出现由于数据量过大导致执行超时，所以不建议全量dump，请指定算子进行dump。 |
dump_path |
（必填）dump数据文件存储到运行环境的目录。
支持配置绝对路径或相对路径：
|
该参数指定的目录需要提前创建且确保安装时配置的运行用户具有读写权限。 |
dump_mode |
dump数据模式。
|
- |
dump_level |
dump数据级别，取值：
默认配置下，dump数据文件会比较多，例如有一些aclnn开头的dump文件，若用户对dump性能有要求或内存资源有限时，则可以将该参数设置为op级别，以便提升dump性能、精简dump数据文件数量。
说明：
算子是一个运算逻辑的表示（如加减乘除运算），kernel是运算逻辑真正进行计算处理的实现，需要分配具体的计算设备完成计算。 |
- |
dump_op_switch |
单算子模型dump数据开关。
|
- |
dump_step |
指定采集哪些迭代的Dump数据。推理场景无需配置。 不配置该参数，默认所有迭代都会产生dump数据，数据量比较大，建议按需指定迭代。 多个迭代用“|”分割，例如：0|5|10；也可以用“-”指定迭代范围，例如：0|3-5|10。 配置示例： {
"dump":{
"dump_list":[
......
],
"dump_path":"$HOME/output",
"dump_mode":"output",
"dump_op_switch":"off"
"dump_step": "0|3-5|10"
}
} |
- |
dump_data |
算子dump内容类型，取值：
通常dump数据量太大并且耗时长，可以先dump算子统计数据，根据统计数据识别可能异常的算子，然后再dump算子数据。 模型Dump场景下，会根据dump_mode处的配置统计算子输入或算子输出或算子输入&输出的信息。 |
- |
配置文件示例（异常算子Dump配置）
将dump_scene参数设置为lite_exception，启用异常算子Dump功能，同时可配合使用ASCEND_WORK_PATH环境变量配置落盘路径，否则落盘在应用程序的当前执行目录下。注意，异常算子Dump配置，不能与模型Dump配置或单算子Dump配置同时开启，否则模型Dump或单算子Dump不生效。
配置文件中的示例内容如下：
{
"dump":{
"dump_scene":"lite_exception"
}
}
配置文件示例（溢出算子Dump配置）
- 将dump_debug配置为on表示开启溢出算子配置，不配置dump_debug或将dump_debug配置为off表示不开启溢出算子配置。
- 若开启溢出算子配置，则dump_path必须配置，表示导出数据文件的存储路径。
- 溢出算子Dump配置，不能与模型Dump配置或单算子Dump配置同时开启，否则会返回报错。
- 当前不支持单算子API执行场景下的溢出算子Dump。
- 仅支持采集AI Core算子的溢出数据。
{
"dump":{
"dump_path":"output",
"dump_debug":"on"
}
}
配置文件示例（算子缓存信息老化配置）
算子缓存信息老化配置的相关约束说明如下：
- 对于静态加载的算子，调用aclopSetModelDir接口加载指定目录下的单算子模型或调用aclopLoad接口加载指定单算子模型时，老化配置无效，不会对该部分的算子信息做老化。
- 在线编译算子的场景下，调用aclopCompile接口编译算子或调用aclopCompileAndExecute接口编译执行算子时，接口内部会按照入参加载单算子模型，老化配置有效。
如果用户调用aclopCompile接口编译算子、调用aclopExecuteV2接口执行算子，则在编译算子后需及时执行算子，否则可能导致执行算子时，算子信息已被老化，需要重新编译。建议调用aclopCompileAndExecuteV2接口编译执行算子。
- AscendCL内部分开维护固定Shape和动态Shape算子的映射队列，最大长度都为max_opqueue_num参数值。
- max_opqueue_num参数值为静态加载算子的单算子模型个数和在线编译算子的单算子模型个数的总和，因此max_opqueue_num参数值应大于当前进程中可用的、静态加载算子的单算子模型个数，否则会导致在线编译算子的信息无法老化。
配置文件中的示例内容如下：
{
"max_opqueue_num": "10000"
}
配置文件示例（错误信息上报模式配置）
err_msg_mode参数取值范围：0为默认值，表示按线程级别获取错误信息；1表示按进程级别获取错误信息。
配置文件中的示例内容如下：
{
"err_msg_mode": "1"
}
相关接口
AscendCL还提供了其它使能Dump或Profiling的接口，如下，与aclInit不同的是，以下这些接口相对灵活，可以在一个进程内调用多次接口，每次调用接口时可以基于不同的Dump配置或Profiling配置。
- 获取Dump数据，参见aclmdlInitDump、aclmdlSetDump、aclmdlFinalizeDump。
- 获取Profiling数据，参见Profiling数据采集。
