跳到主要内容

接口调用流程

简介​

单算子调用的使用场景​

如果AI应用中不仅仅包括模型推理，还有数学运算（例如BLAS基础线性代数运算）、数据类型转换等功能，也想使用昇腾的算力，昇腾CANN还能支持吗？

答案是肯定的，昇腾CANN提供了单算子调用的方式，直接通过pyACL接口加载并执行单个算子，省去模型构建、训练的过程，相对轻量级，又可以使用昇腾的算力。

另外，自定义的算子，也可以通过单算子调用的方式来验证算子的功能。

单算子调用与模型推理的差别​

在解释单算子调用与模型推理的差别前，我们先观察下面这个开发流程图，找出基本的共同点、不同点。

  • 共同点：
    • 需要pyACL初始化和去初始化、运行管理资源申请和释放。
    • 涉及加载、执行的步骤，但是要注意，两者的加载、执行是调用不同的pyACL接口。
  • 不同点：
    • 模型推理涉及模型卸载的步骤，单算子调用不涉及。

图1 单算子调用与模型推理的流程对比

父主题： 单算子调用

开发流程​

图1 开发流程

  1. 创建代码目录。

    在开发应用前，您需要先创建目录，存放代码文件、脚本、测试图片数据、模型文件等。

  2. 准备算子。

    使用ATC工具编译算子生成om模型文件。

    该种方式，需要先构造*.json格式单算子描述文件（描述算子的输入、输出及属性等信息），借助ATC工具，将单算子描述文件编译成om模型文件，再分别调用pyACL接口加载om模型文件、执行算子。

    关于ATC工具的使用说明，请参见《ATC工具使用指南》。

  3. 开发应用。

    单算子调用的流程请参见接口调用流程及相关的示例代码。

  4. 运行应用，请参见应用调试。

父主题： 单算子调用

接口调用流程​

开发应用时，如果涉及执行单个算子，则应用程序中必须包含执行单个算子的代码逻辑。关于执行单个算子的接口调用流程，请先参见pyACL接口调用流程了解整体流程，再查看本节中的流程说明。

系统支持的算子请参见《算子清单》。

图1 算子调用流程

关键接口的说明如下：

  1. 加载算子模型文件。

    支持以下2种方式中的一种加载单算子模型文件：

    • 调用acl.op.set_model_dir接口，设置加载模型文件的目录，目录下存放单算子模型文件（*.om文件）。
    • 调用acl.op.load接口，从内存中加载单算子模型数据，由用户管理内存。单算子模型数据是指“单算子编译成*.om文件后，再将om文件读取到内存中”的数据。

  2. 调用acl.rt.malloc接口申请Device上的内存，存放执行算子的输入、输出数据。

  3. 动态Shape场景，如果无法明确算子的输出Shape时，在执行算子前，还需推导或预估算子的输出Shape。

    需用户调用acl.op.infer_shape接口、acl.get_tensor_desc_num_dims接口、acl.get_tensor_desc_dim_v2接口、acl.get_tensor_desc_dim_range等接口，推导或预估算子的输出Shape，作为算子执行接口acl.op.execute_v2的输入。

  4. 执行算子。

    :::note 说明 不以handle方式执行算子时，每次执行算子时，系统内部都会根据算子描述信息匹配内存中的模型。

    以handle方式执行算子时，系统内部将算子描述信息匹配到内存中的模型，并缓存在Handle中，每次执行算子时，无需重复匹配算子与模型，因此在涉及多次执行同一个算子时，效率更高。但Handle使用结束后，需调用acl.op.destroy_handle接口释放。 :::

  5. 调用acl.rt.synchronize_stream接口阻塞应用运行，直到指定Stream中的所有任务都完成。

  6. 调用acl.rt.free接口释放内存。

父主题： 单算子调用

调用CBLAS接口​

基本原理​

目前，pyACL已将GEMM算子（用于矩阵-向量乘、矩阵-矩阵乘）、Cast算子（用于转换数据类型）封装成pyACL接口，可参见CBLAS接口，目前支持以下两种执行方式：

:::note 说明 不以handle方式执行算子时，每次执行算子时，系统内部都会根据算子描述信息匹配内存中的模型。

以handle方式执行算子时，系统内部将算子描述信息匹配到内存中的模型，并缓存在Handle中，每次执行算子时，无需重复匹配算子与模型，因此在涉及多次执行同一个算子时，效率更高。但Handle使用结束后，需调用acl.op.destroy_handle接口释放。 :::

示例代码​

本章以acl.blas.gemm_ex接口为例，该示例中矩阵乘的计算公式为：C = αAB + βC。

调用接口后，需增加异常处理的分支，并记录报错日志、提示日志，此处不一一列举。以下是关键步骤的代码示例，不可以直接拷贝运行，仅供参考。

import acl
## ......

ACL_MEM_MALLOC_NORMAL_ONLY = 2
ACL_TRANS_N = 0
ACL_COMPUTE_HIGH_PRECISION = 0
ACL_MEMCPY_HOST_TO_DEVICE = 1
ACL_MEMCPY_DEVICE_TO_HOST = 2

## 1.pyACL初始化。
ret = acl.init("test_data/config/acl.json")

## 2.设置单算子模型文件所在的目录。
ret = acl.op.set_model_dir("op_models")

## 3.指定用于运算的设备。
device_id = 0
ret = acl.rt.set_device(device_id)

## 4.申请内存。
## 4.1 申请Device上的内存存放执行算子的输入数据。
## 对于该矩阵乘示例，size_a表示矩阵A数据的大小，size_b表示矩阵B数据的大小，size_c表示矩阵C数据的大小。
in_dtype, out_dtype = 1, 1
size_a = m * k * acl.data_type_size(acl_dtype)
size_b = m * k * acl.data_type_size(acl_dtype)
size_c = m * k * acl.data_type_size(acl_dtype)
dev_matrix_a, ret = acl.rt.malloc(size_a, ACL_MEM_MALLOC_NORMAL_ONLY)
dev_matrix_b, ret = acl.rt.malloc(size_b, ACL_MEM_MALLOC_NORMAL_ONLY)
dev_matrix_c, ret = acl.rt.malloc(size_c, ACL_MEM_MALLOC_NORMAL_ONLY)
## 4.2 申请Host上的内存。
## 对于该矩阵乘示例，m表示矩阵A的行数与矩阵C的行数，n表示矩阵B的列数与矩阵C的列数。
## k表示矩阵A的列数与矩阵B的行数。
host_matrix_a, ret = acl.rt.malloc_host(size_a)
host_matrix_b, ret = acl.rt.malloc_host(size_b)
host_matrix_c, ret = acl.rt.malloc_host(size_c)

## 5.准备输入数据。
## 从文件读入到host_matrix_a和host_matrix_b中。
## 对于该矩阵乘示例，将矩阵A和矩阵B的数据从Host复制到Device。
ret = acl.rt.memcpy(dev_matrix_a, size_a, host_matrix_a, size_a, ACL_MEMCPY_HOST_TO_DEVICE)
ret = acl.rt.memcpy(dev_matrix_b, size_b, host_matrix_b, size_b, ACL_MEMCPY_HOST_TO_DEVICE)

## 6.执行单算子。
stream, ret = acl.rt.create_stream()
## 对于该示例，调用acl.blas.gemm_ex接口（异步接口）实现矩阵-矩阵的乘法。
ret = acl.blas.gemm_ex(ACL_TRANS_N, ACL_TRANS_N, ACL_TRANS_N, m, n, k, dev_alpha, dev_matrix_a, k, input_type, dev_matrix_b, n, input_type, dev_beta, dev_matrix_c, n, output_type, ACL_COMPUTE_HIGH_PRECISION, stream)
## 调用acl.rt.synchronize_stream接口阻塞Host运行，直到指定Stream中的所有任务都完成。
ret = acl.rt.synchronize_stream(stream)

## 7.将算子的输出数据从Device复制到Host。
ret = acl.rt.memcpy(host_matrix_c, size_c, dev_matrix_c, size_c, ACL_MEMCPY_DEVICE_TO_HOST)

## 8.释放运行管理资源。
ret = acl.rt.destroy_stream(stream)
ret = acl.rt.reset_device(device_id)
ret = acl.finalize()
## ......

父主题： 单算子调用

固定Shape算子​

对于昇腾AI处理器不支持的算子，用户需参考《TBE&AI CPU算子开发指南》先完成自定义算子的开发，再参考如下内容执行单算子。

父主题： 单算子调用

动态Shape算子（不注册算子选择器）​

基本原理​

对于支持动态Shape的算子：

示例代码​

调用接口后，需增加异常处理的分支，并记录报错日志、提示日志，此处不一一列举。以下是关键步骤的代码示例，不可以直接拷贝运行，仅供参考。

import acl
## ......

## 此处算子输入tensor数据的内存必须根据应用运行模式来确定，应用运行在Host时，此处需申请Host上的内存。
## 应用运行在Device时，此处需申请Device上的内存。
ret = acl.op.infer_shape(op_type, self.in_desc_list, self.in_list, num_outputs, self.out_desc_list, self.attr)

tensor_dims = []
## 循环算子的每一个输出，推导或预估Shape值：
for i in range(len(infer_desc_list)):
    dim_nums = acl.get_tensor_desc_num_dims(infer_desc_list[i])
    dim_size = []
    for j in range(dim_nums):
        dim, ret = acl.get_tensor_desc_dim_v2(infer_desc_list[i], j)
        # 表示动态Shape场景下维度值是动态的。
        if dim == -1:
            # 获取Shape范围，使用该范围的Shape最大值来构造输出tensor_desc，作为acl.op.execute_v2的输入。
            dim_range, ret = acl.get_tensor_desc_dim_range(infer_desc_list[i], j, 2)
            dim = dim_range[1]
        dim_size.append(dim)
    tensor_dims.append(dim_size)

## 以上给出了执行算子时输出的shape，根据tensor_dims中的dims构造输出tensor_desc（即self.out_desc_list参数值），用于调用acl.op.execute_v2。
ret = acl.op.execute_v2(op_type, self.in_desc_list, self.in_list, self.out_desc_list, self.out_list, self.attr, self.stream)

out_tensor_dims = []
## 针对上面用户预估Shape值以及使用Shape范围中的最大Shape的场景，设在算子执行结束后，需增加下面的调用，获取准确的shape。
for i in range(len(self.out_desc_list)):
    dim_nums = acl.get_tensor_desc_num_dims(self.out_desc_list[i])
    dim_size = []
    for j in range(dim_nums):
        dim, ret = acl.get_tensor_desc_dim_v2(self.out_desc_list[i], j)
        dim_size.append(dim)
    out_tensor_dims.append(dim_size)

## ......

父主题： 单算子调用

在线提单