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配置示例如下：
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 |
{ "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配置示例如下：
1 2 3 4 5 6 7 8 |
{ "dump":{ "dump_path":"output", "dump_list":[], "dump_op_switch":"on", "dump_data":"tensor" } } |
单算子Dump场景下，单算子API执行方式的Dump配置示例如下：
1 2 3 4 5 6 7 |
{ "dump":{ "dump_path":"output", "dump_list":[], "dump_data":"tensor" } } |
配置项 |
参数说明 |
||
|---|---|---|---|
dump_list |
（必选）待dump数据的整网模型列表。 创建模型dump配置信息，当存在多个模型需要dump时，需要每个模型之间用英文逗号隔开。 在单算子调用场景（包括单算子模型执行和单算子API执行）下，dump_list为空。 |
||
model_name |
模型名称，各个模型的model_name值须唯一。
|
||
layer |
IO性能相对较差时，可能会出现由于数据量过大导致执行超时，所以不建议全量dump，请指定算子进行dump。通过该字段可以指定需要dump的算子名，支持指定为ATC模型转换后的算子名，也支持指定为转换前的原始算子名，配置时需注意：
|
||
dump_path |
（必选）dump数据文件存储到运行环境的目录，该目录需要提前创建且确保安装时配置的运行用户具有读写权限。
支持配置绝对路径或相对路径：
|
||
dump_mode |
dump数据模式。 |
||
dump_level |
dump数据级别，取值：
默认配置下，dump数据文件会比较多，例如有一些aclnn开头的dump文件，若用户对dump性能有要求或内存资源有限时，则可以将该参数设置为op级别，以便提升dump性能、精简dump数据文件数量。
说明：
算子是一个运算逻辑的表示（如加减乘除运算），kernel是运算逻辑真正进行计算处理的实现，需要分配具体的计算设备完成计算。 |
||
dump_op_switch |
单算子Dump场景下，单算子模型执行方式的dump数据开关。
|
||
dump_step |
指定采集哪些迭代的Dump数据。推理场景无需配置。 不配置该参数，默认所有迭代都会产生dump数据，数据量比较大，建议按需指定迭代。 多个迭代用“|”分割，例如：0|5|10；也可以用“-”指定迭代范围，例如：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文件内容，先将dump文件转换为numpy格式文件后，再通过Python查看numpy格式文件，详细转换步骤请参见《精度调试工具指南》中的“dump数据文件查看”章节。
配置文件示例（溢出算子Dump配置）
- 将dump_debug配置为on表示开启溢出算子配置，不配置dump_debug或将dump_debug配置为off表示不开启溢出算子配置。
- 若开启溢出算子配置，则dump_path必须配置，表示导出dump文件的存储路径。
- 溢出算子Dump配置，不能与模型Dump配置或单算子Dump配置同时开启，否则会返回报错。
- 仅支持采集AI Core算子的溢出数据。
{
"dump":{
"dump_path":"output",
"dump_debug":"on"
}
}
配置文件示例（算子Dump Watch模式配置）
将dump_scene参数设置为watcher，开启算子Dump Watch模式，详细配置说明及约束如下：
- 若开启算子Dump Watch模式，则不支持同时开启溢出算子Dump（配置dump_debug参数）或开启单算子模型Dump（配置dump_op_switch参数），否则报错。该模式在单算子API Dump场景下不生效。
- 在dump_list中，通过layer参数配置可能踩踏其它算子内存的算子名称，通过watcher_nodes参数配置可能被其它算子踩踏输出内存导致精度有问题的算子名称。
- 若不指定layer，则模型内所有支持Dump的算子在执行后，都会将watcher_nodes中配置的算子的输出Dump出来。
- layer和watcher_node处配置的算子都必须是静态图、静态子图中的算子，否则不生效。
- 若layer和watcher_node处配置的算子名称相同，或者layer处配置的是集合通信类算子（算子类型以Hcom开头，例如HcomAllReduce），则不导出dump文件。
- 对于融合算子，watcher_node处配置的算子名称必须是融合后的算子名称，若配置融合前的算子名称，则不导出dump文件。
- dump_list内暂不支持配置model_name。
- 开启算子Dump Watch模式，则dump_path必须配置，表示导出dump文件的存储路径。
- 通过dump_mode参数控制导出watcher_nodes中所配置算子的哪部分数据，当前仅支持配置为output。
配置文件中的示例内容如下，配置效果为：当执行完A算子和B算子时，会把C算子和D算子的输出Dump出来，导出C算子opType.A_To_C.*、D算子opType.A_To_D.*、C算子opType.B_To_C.*、D算子opType.B_To_D.*四个dump文件，用于排查A算子、B算子是否会踩踏C算子、D算子的输出内存。
{
"dump":{
"dump_list":[
{
"layer":["A", "B"],
"watcher_nodes":["C", "D"]
}
],
"dump_path":"/home/",
"dump_mode":"output",
"dump_scene":"watcher"
}
}
此处收集的dump文件无法通过文本工具直接查看其内容，若需查看dump文件内容，先将dump文件转换为numpy格式文件后，再通过Python查看numpy格式文件，详细转换步骤请参见《精度调试工具指南》中的“dump数据文件查看”章节。
配置文件示例（算子缓存信息老化配置）
算子缓存信息老化配置的相关约束说明如下：
- 对于静态加载的算子，调用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"
}
默认Device配置示例
default_device参数处设置Device ID，Device ID可设置为0或十进制正整数，用户可调用aclrtGetDeviceCount接口获取可用的Device数量后，这个Device ID的取值范围：[0, (可用的Device数量-1)]。
配置文件中的示例内容如下：
{
"defaultDevice":{
"default_device":"0"
}
}
相关接口
AscendCL还提供了其它使能Dump或Profiling的接口，如下，与aclInit不同的是，以下这些接口相对灵活，可以在一个进程内调用多次接口，每次调用接口时可以基于不同的Dump配置或Profiling配置。
- 获取Dump数据，参见aclmdlInitDump、aclmdlSetDump、aclmdlFinalizeDump。
- 获取Profiling数据，参见Profiling数据采集。
