单算子调用流程

本节介绍调用单算子的两种方式、以及这两种方式下的接口调用流程。

开发应用时，如果涉及执行单个算子，请先参见AscendCL接口调用流程了解整体流程，再查看本节中的流程说明。

系统支持的算子请参见《算子加速库接口参考》中的“CANN算子规格说明>简介”。

对于系统不支持的算子，用户需先参见《Ascend C算子开发指南》完成自定义算子开发。

对于TIK自定义动态Shape算子，需要先注册算子选择器，请参见执行动态Shape算子示例代码（注册算子选择器）。

单算子调用方式：单算子模型执行、单算子API执行

单算子API执行：基于C语言的API执行算子，无需提供IR（Intermediate Representation）定义，直接调用单算子API执行下的算子接口，包括NN算子、融合算子、DVPP算子等。针对每个算子，都需要先调用aclxxXxxGetWorkspaceSize接口获取算子执行需要的workspace内存大小，再调用aclxxXxx接口执行计算。
- 调用单算子API执行中NN算子和融合算子接口时，会直接调用算子二进制包（Ascend-cann-kernels）中已经编译好的算子，无需再编译算子。算子二进制包的安装请参见《CANN软件安装指南》。
- 调用单算子API执行中DVPP算子接口时，无需再编译算子。
单算子模型执行：基于图IR执行算子，先编译算子（例如，使用ATC工具将Ascend IR定义的单算子描述文件编译成算子om模型文件），再调用AscendCL接口加载算子模型（例如aclopSetModelDir接口），最后调用AscendCL接口执行算子（例如aclopExecuteV2接口）。

昇腾AI处理器对两种单算子调用方式的支持度如下表所示。

-	单算子API执行	单算子模型执行
Atlas 200/300/500 推理产品	x	√
Atlas 200/500 A2推理产品	√（部分支持）	√
Atlas 训练系列产品	√（部分支持）	√
Atlas A2训练系列产品/Atlas 800I A2推理产品	√	√
Atlas 推理系列产品	√（部分支持）	√

单算子API执行接口调用流程

图1 单算子API执行接口调用流程

关键接口的说明如下：

AscendCL初始化。

调用aclInit接口实现初始化AscendCL。
运行管理资源申请。

依次申请运行管理资源，具体流程请参见运行管理资源申请与释放。
数据内存申请和传输。
1. 调用aclrtMalloc接口申请Device上的内存，存放待执行算子的输入、输出数据。
2. 调用aclCreateTensor、aclCreateIntArray等接口构造算子的输入、输出数据，如aclTensor、aclIntArray等，详细接口请参见单算子API执行。
如果需要将Host上数据传输到Device，则需要调用aclrtMemcpy接口（同步接口）或aclrtMemcpyAsync接口（异步接口）通过内存复制的方式实现数据传输。
计算workspace并执行算子。
1. 调用aclxxXxxGetWorkspaceSize接口获取算子入参，并计算该算子执行流程需要多少的workspace内存。
2. 调用aclrtMalloc接口，根据workspaceSize大小申请Device侧内存。
3. 调用aclxxXxx接口执行计算并得到结果。
单算子API执行的接口一般定义为“两段式接口”，即aclxxXxxGetWorkspaceSize和aclxxXxx，详细的接口功能和使用方法请参见单算子API执行章节。
调用aclrtSynchronizeStream接口阻塞应用运行，直到指定Stream中的所有任务都完成。
调用aclrtFree接口释放内存。
如果需要将Device上的算子执行结果数据传输到Host，则需要调用aclrtMemcpy接口（同步接口）或aclrtMemcpyAsync接口（异步接口）通过内存复制的方式实现数据传输，然后再释放内存。
运行管理资源释放。
1. 调用aclDestroyTensor、aclDestroyIntArray等接口释放算子的输入、输出，相关接口请参见单算子API执行。
2. 所有数据释放后，需要依次释放运行管理资源，具体流程请参见运行管理资源申请与释放。
AscendCL去初始化。
调用aclFinalize接口实现AscendCL去初始化。

单算子模型执行接口调用流程

图2 单算子模型执行接口调用流程
点击放大

关键接口的说明如下：

编译算子。
根据算子编译的方式，可分为以下两种：
- 编译算子后，算子相关数据保存在*.om模型文件中
   该种方式下编译算子，需使用ATC工具，详细描述请参见《ATC工具使用指南》，将单算子定义文件（*.json）编译成适配昇腾AI处理器的离线模型（*.om文件）。
  
  编译算子后，依次进行2、3、4、5、6、7。
- 编译算子后，算子相关数据保存在内存中
   该种方式下编译算子，需调用AscendCL提供的接口，根据不同场景调用不同的接口：
  - 对于同一个算子，编译一次，多次执行的场景，建议调用aclopCompile接口编译算子。编译算子后，依次进行3、4、5、6、7。
  - 对于编译算子、执行算子次数相同的场景，建议先执行3，再调用aclopCompileAndExecute接口编译算子。编译算子后，再依次进行6、7。
加载算子模型文件。
支持以下2种方式中的一种加载单算子模型文件：
- 调用aclopSetModelDir接口，设置加载模型文件的目录，目录下存放单算子模型文件（*.om文件）。
- 调用aclopLoad接口，从内存中加载单算子模型数据，由用户管理内存。单算子模型数据是指“单算子编译成*.om文件后，再将om文件读取到内存中”的数据。
调用aclrtMalloc接口申请Device上的内存，存放执行算子的输入、输出数据。
如果需要将Host上数据传输到Device，则需要调用aclrtMemcpy接口（同步接口）或aclrtMemcpyAsync接口（异步接口）通过内存复制的方式实现数据传输。
动态Shape场景，如果无法明确算子的输出Shape时，在执行算子前，还需推导或预估算子的输出Shape。
需用户调用aclopInferShape接口、aclGetTensorDescNumDims接口、aclGetTensorDescDimV2接口、aclGetTensorDescDimRange等接口，推导或预估算子的输出Shape，作为算子执行接口aclopExecuteV2的输入。
执行算子。
- 对于被封装成AscendCL接口的算子（参见CBLAS接口），包括GEMM算子、Cast算子，目前支持以下两种执行方式：
  - 不以handle方式执行算子，接口名称中不包含“Handle”关键字，例如，调用aclblasGemmEx接口（封装GEMM算子）、aclopCast接口（封装Cast算子）等执行算子。
  - 以handle方式执行算子，接口名称中包含“Handle”关键字，例如，调用aclblasCreateHandleForGemmEx接口、aclopCreateHandleForCast接口等创建handle后，还需要调用aclopExecWithHandle接口执行算子。
- 对于未被封装成AscendCL接口的算子，目前支持以下两种执行方式：
  - 不以handle方式执行算子，调用aclopExecuteV2接口执行算子。
  - 以handle方式执行算子，调用aclopCreateHandle接口创建handle，再调用aclopExecWithHandle接口执行算子。
不以handle方式执行算子时，每次执行算子时，系统内部都会根据算子描述信息匹配内存中的模型。

以handle方式执行算子时，系统内部将算子描述信息匹配到内存中的模型，并缓存在Handle中，每次执行算子时，无需重复匹配算子与模型，因此在涉及多次执行同一个算子时，效率更高，但该方式不支持动态Shape算子，且Handle使用结束后，需调用aclopDestroyHandle接口释放。
调用aclrtSynchronizeStream接口阻塞应用运行，直到指定Stream中的所有任务都完成。
调用aclrtFree接口释放内存。
如果需要将Device上的算子执行结果数据传输到Host，则需要调用aclrtMemcpy接口（同步接口）或aclrtMemcpyAsync接口（异步接口）通过内存复制的方式实现数据传输，然后再释放内存。

父主题： 单算子调用