CANN ops-nn ForeachExpm1 算子实战指南:aclnnForeachExpm1 两段式接口从原理到调用示例

原创2026-09-20 21:34:171,384 阅读
文章标签:人工智能深度学习算子库高性能计算模型量化AscendCANN

CANN ops-nn ForeachExpm1 算子实战指南:aclnnForeachExpm1 两段式接口从原理到调用示例

本文是 CANN ops-nn 算子库中 ForeachExpm1(张量列表逐元素 e^x - 1 运算)算子的完整技术指南,围绕官方接口文档 aclnnForeachExpm1.md 展开,结合仓库中的算子定义、Kernel 实现、Tiling 与单算子 API 调用样例,系统讲解产品支持范围、接口参数约束、两段式调用流程、返回码语义与可编译运行的完整示例。读完本文,你将掌握如何在 Ascend NPU 上通过 aclnn 单算子 API 对一组张量批量执行 expm1 运算,并理解该算子在库内的实现机制。

一、算子功能与适用场景

ForeachExpm1 是一个典型的 foreach 系列批量一元算子:它接收一个**张量列表(TensorList)**作为输入,对列表中每个张量逐元素执行指数运算后再减 1,并将结果写入对应的输出张量列表。其数学定义如下:

x=[x0,x1,...xn−1]x = [{x_0}, {x_1}, ... {x_{n-1}}]

y=[y0,y1,...yn−1]y = [{y_0}, {y_1}, ... {y_{n-1}}]

yi=exi−1(i=0,1,...n−1){y_i}=e^{x_i}-1 \quad (i=0,1,...n-1)

与逐个调用单张量算子的方式相比,Foreach 系列接口把多个张量的同构运算合并为一次算子下发,显著减少 Host 侧调用开销,适合在 PyTorch 等框架的 foreach_ 优化器/梯度裁剪场景中批量处理参数张量列表。

产品支持情况

根据接口文档与 foreach_expm1/README.md 的说明,ForeachExpm1 在不同昇腾产品上的支持情况如下:

产品 是否支持
Ascend 950PR / Ascend 950DT 支持
Atlas A3 训练系列产品 / Atlas A3 推理系列产品 支持
Atlas A2 训练系列产品 / Atlas A2 推理系列产品 支持
Atlas 200I/500 A2 推理产品 不支持
Atlas 推理系列产品 不支持
Atlas 训练系列产品 不支持
Kirin X90 处理器系列产品 支持
Kirin 9030 处理器系列产品 支持

注意:Kirin X90 / Kirin 9030 处理器系列不支持 BFLOAT16、INT16、INT8、UINT8 数据类型,仅支持 FLOAT16、FLOAT32。

从源码看,这一支持矩阵与 foreach_expm1_def.cpp 中通过 AICore().AddConfig(...) 注册的硬件配置一一对应:ascend910_93、ascend910b、ascend950 使用完整的数据类型列表(FLOAT16/FLOAT32/BFLOAT16/INT16/INT8/UINT8),而 Kirin 系列(kirinx90、kirin9030)通过 GetKirinCoreConfig() 仅注册了 FLOAT16 与 FLOAT32 两种类型。

二、两段式接口与函数原型

ForeachExpm1 遵循 CANN 单算子 API 的两段式接口规范(详见 两段式接口说明):必须先调用第一段接口 aclnnForeachExpm1GetWorkspaceSize 获取计算所需 workspace 大小以及封装了算子计算流程的执行器,再调用第二段接口 aclnnForeachExpm1 真正执行计算。

2.1 第一段接口

aclnnStatus aclnnForeachExpm1GetWorkspaceSize(
  const aclTensorList *x,
  const aclTensorList *out,
  uint64_t            *workspaceSize,
  aclOpExecutor      **executor)

该接口完成入参校验与 workspace 大小估算,输出 workspaceSize(Device 侧临时内存大小)和 executor(op 执行器,包含算子计算流程)。

2.2 第二段接口

aclnnStatus aclnnForeachExpm1(
  void          *workspace,
  uint64_t       workspaceSize,
  aclOpExecutor *executor,
  aclrtStream    stream)

第二段接口负责在指定 stream 上异步下发计算任务。需要特别注意的是:第二段接口不能重复调用,同一 executor 不允许连续执行多次 aclnnForeachExpm1(...),否则会出现异常。

三、第一段接口参数详解

3.1 参数说明

参数名 输入/输出 描述 使用说明 数据类型 数据格式 维度(shape) 非连续Tensor
x(aclTensorList*) 输入 表示进行指数运算然后减 1 运算的输入张量列表,对应公式中的 x 支持空 Tensor;该参数中所有 Tensor 的数据类型保持一致;数据类型和数据格式与出参 out 的数据类型和数据格式一致 BFLOAT16、FLOAT16、FLOAT32、INT16、INT8、UINT8 ND 0-8 √
out(aclTensorList*) 输出 表示进行指数运算然后减 1 运算的输出张量列表,对应公式中的 y 支持空 Tensor;该参数中所有 Tensor 的数据类型保持一致;当 x 的数据类型为 INT16、INT8、UINT8 时,数据类型为 FLOAT32,其他情况下与入参 x 的数据类型一致;数据格式与入参 x 的数据格式一致,shape size 大于等于入参 x 的 shape size BFLOAT16、FLOAT16、FLOAT32 ND 0-8 √
workspaceSize(uint64_t*) 输出 返回需要在 Device 侧申请的 workspace 大小 - - - - -
executor(aclOpExecutor**) 输出 返回 op 执行器,包含了算子计算流程 - - - - -

几点关键约束值得注意:

  • 整数输入自动提升:当输入 x 是 INT16/INT8/UINT8 整数类型时,输出 out 必须为 FLOAT32;浮点输入(BFLOAT16/FLOAT16/FLOAT32)则输出与输入同类型。这一点在算子定义 foreach_expm1_def.cpp 中有直接体现——output_dtype_list 为 {FLOAT16, FLOAT, BF16, FLOAT, FLOAT, FLOAT},与输入类型列表逐索引配对,整数类型的输出统一为 FLOAT。
  • 支持非连续 Tensor:参数表中"非连续 Tensor"列为 √,表示输入输出允许存在非连续内存布局。
  • shape 兼容规则:输出 shape size 需大于等于输入 shape size,各张量维度不超过 8 维(0-8)。

3.2 返回值与错误码

第一段接口返回 aclnnStatus 状态码(完整返回码含义参见 aclnn 返回码说明),在入参校验不通过时报错场景如下:

返回码 错误码 描述
ACLNN_ERR_PARAM_NULLPTR 161001 传入的 x 或 out 是空指针
ACLNN_ERR_PARAM_INVALID 161002 x 或 out 的数据类型不在支持的范围之内
ACLNN_ERR_PARAM_INVALID 161002 x 和 out 的数据类型不一致
ACLNN_ERR_INNER_TILING_ERROR 561002 x 与 out 的 shape 不满足约束
ACLNN_ERR_INNER_TILING_ERROR 561002 x 或 out 中的 Tensor 的数据类型不一致
ACLNN_ERR_INNER_TILING_ERROR 561002 x 或 out 中的 Tensor 维度超过 8 维

四、第二段接口参数详解

参数名 输入/输出 描述
workspace 输入 在 Device 侧申请的 workspace 内存地址
workspaceSize 输入 在 Device 侧申请的 workspace 大小,由第一段接口 aclnnForeachExpm1GetWorkspaceSize 获取
executor 输入 op 执行器,包含了算子计算流程
stream 输入 指定执行任务的 Stream

第二段接口同样返回 aclnnStatus 状态码。

五、约束说明

  • 确定性计算:aclnnForeachExpm1 为默认确定性实现,即相同输入、相同环境条件下多次执行结果一致,适合对可复现性有要求的训练与调试场景。

六、完整调用示例(可编译运行)

以下示例代码演示如何在 Host 侧通过两段式接口调用 ForeachExpm1 算子,对两个不同 shape 的张量执行 e^x - 1 运算。完整代码同样收录于仓库 examples/test_aclnn_foreach_expm1.cpp,具体编译与执行过程请参考 编译与运行样例。

#include <iostream>
#include <vector>
#include "acl/acl.h"
#include "aclnnop/aclnn_foreach_expm1.h"

#define CHECK_RET(cond, return_expr) \
  do {                               \
    if (!(cond)) {                   \
      return_expr;                   \
    }                                \
  } while (0)

#define LOG_PRINT(message, ...)     \
  do {                              \
    printf(message, ##__VA_ARGS__); \
  } while (0)

int64_t GetShapeSize(const std::vector<int64_t>& shape) {
  int64_t shapeSize = 1;
  for (auto i : shape) {
    shapeSize *= i;
  }
  return shapeSize;
}

int Init(int32_t deviceId, aclrtStream *stream)
{
    // 固定写法,资源初始化
    auto ret = aclInit(nullptr);
    CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclInit failed. ERROR: %d\n", ret); return ret);
    ret = aclrtSetDevice(deviceId);
    CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclrtSetDevice failed. ERROR: %d\n", ret); return ret);
    ret = aclrtCreateStream(stream);
    CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclrtCreateStream failed. ERROR: %d\n", ret); return ret);
    return 0;
}

template <typename T>
int CreateAclTensor(const std::vector<T>& hostData, const std::vector<int64_t>& shape, void** deviceAddr,
                    aclDataType dataType, aclTensor** tensor) {
  auto size = GetShapeSize(shape) * sizeof(T);
  // 调用aclrtMalloc申请device侧内存
  auto ret = aclrtMalloc(deviceAddr, size, ACL_MEM_MALLOC_HUGE_FIRST);
  CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclrtMalloc failed. ERROR: %d\n", ret); return ret);
  // 调用aclrtMemcpy将host侧数据复制到device侧内存上
  ret = aclrtMemcpy(*deviceAddr, size, hostData.data(), size, ACL_MEMCPY_HOST_TO_DEVICE);
  CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclrtMemcpy failed. ERROR: %d\n", ret); return ret);

  // 计算连续tensor的strides
  std::vector<int64_t> strides(shape.size(), 1);
  for (int64_t i = shape.size() - 2; i >= 0; i--) {
    strides[i] = shape[i + 1] * strides[i + 1];
  }

  // 调用aclCreateTensor接口创建aclTensor
  *tensor = aclCreateTensor(shape.data(), shape.size(), dataType, strides.data(), 0, aclFormat::ACL_FORMAT_ND,
                            shape.data(), shape.size(), *deviceAddr);
  return 0;
}

int main() {
  // 1. (固定写法)device/stream初始化,参考acl API手册
  // 根据自己的实际device填写deviceId
  int32_t deviceId = 0;
  aclrtStream stream;
  auto ret = Init(deviceId, &stream);
  CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("Init acl failed. ERROR: %d\n", ret); return ret);

  // 2. 构造输入与输出,需要根据API的接口自定义构造
  std::vector<int64_t> selfShape1 = {2, 3};
  std::vector<int64_t> selfShape2 = {1, 3};
  std::vector<int64_t> outShape1 = {2, 3};
  std::vector<int64_t> outShape2 = {1, 3};
  void* input1DeviceAddr = nullptr;
  void* input2DeviceAddr = nullptr;
  void* out1DeviceAddr = nullptr;
  void* out2DeviceAddr = nullptr;
  aclTensor* input1 = nullptr;
  aclTensor* input2 = nullptr;
  aclTensor* out1 = nullptr;
  aclTensor* out2 = nullptr;
  std::vector<float> input1HostData = {1, 2, 3, 4, 5, 6};
  std::vector<float> input2HostData = {7, 8, 9};
  std::vector<float> out1HostData(6, 0);
  std::vector<float> out2HostData(3, 0);

  // 创建input1 aclTensor
  ret = CreateAclTensor(input1HostData, selfShape1, &input1DeviceAddr, aclDataType::ACL_FLOAT, &input1);
  CHECK_RET(ret == ACL_SUCCESS, return ret);

  // 创建input2 aclTensor
  ret = CreateAclTensor(input2HostData, selfShape2, &input2DeviceAddr, aclDataType::ACL_FLOAT, &input2);
  CHECK_RET(ret == ACL_SUCCESS, return ret);

  // 创建out1 aclTensor
  ret = CreateAclTensor(out1HostData, outShape1, &out1DeviceAddr, aclDataType::ACL_FLOAT, &out1);
  CHECK_RET(ret == ACL_SUCCESS, return ret);

  // 创建out2 aclTensor
  ret = CreateAclTensor(out2HostData, outShape2, &out2DeviceAddr, aclDataType::ACL_FLOAT, &out2);
  CHECK_RET(ret == ACL_SUCCESS, return ret);

  std::vector<aclTensor*> tempInput{input1, input2};
  aclTensorList* tensorListInput = aclCreateTensorList(tempInput.data(), tempInput.size());
  std::vector<aclTensor*> tempOutput{out1, out2};
  aclTensorList* tensorListOutput = aclCreateTensorList(tempOutput.data(), tempOutput.size());

  // 3. 调用CANN算子库API,需要修改为具体的API名称
  uint64_t workspaceSize = 0;
  aclOpExecutor* executor;
  // 调用aclnnForeachExpm1第一段接口
  ret = aclnnForeachExpm1GetWorkspaceSize(tensorListInput, tensorListOutput, &workspaceSize, &executor);
  CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclnnForeachExpm1GetWorkspaceSize failed. ERROR: %d\n", ret); return ret);
  // 根据第一段接口计算出的workspaceSize申请device内存
  void* workspaceAddr = nullptr;
  if (workspaceSize > 0) {
    ret = aclrtMalloc(&workspaceAddr, workspaceSize, ACL_MEM_MALLOC_HUGE_FIRST);
    CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("allocate workspace failed. ERROR: %d\n", ret); return ret);
  }
  // 调用aclnnForeachExpm1第二段接口
  ret = aclnnForeachExpm1(workspaceAddr, workspaceSize, executor, stream);
  CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclnnForeachExpm1 failed. ERROR: %d\n", ret); return ret);

  // 4. (固定写法)同步等待任务执行结束
  ret = aclrtSynchronizeStream(stream);
  CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclrtSynchronizeStream failed. ERROR: %d\n", ret); return ret);

  // 5. 获取输出的值,将device侧内存上的结果复制至host侧,需要根据具体API的接口定义修改
  auto size = GetShapeSize(outShape1);
  std::vector<float> out1Data(size, 0);
  ret = aclrtMemcpy(out1Data.data(), out1Data.size() * sizeof(out1Data[0]), out1DeviceAddr,
                    size * sizeof(out1Data[0]), ACL_MEMCPY_DEVICE_TO_HOST);
  CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("copy result from device to host failed. ERROR: %d\n", ret); return ret);
  for (int64_t i = 0; i < size; i++) {
    LOG_PRINT("out1 result[%ld] is: %f\n", i, out1Data[i]);
  }

  size = GetShapeSize(outShape2);
  std::vector<float> out2Data(size, 0);
  ret = aclrtMemcpy(out2Data.data(), out2Data.size() * sizeof(out2Data[0]), out2DeviceAddr,
                    size * sizeof(out2Data[0]), ACL_MEMCPY_DEVICE_TO_HOST);
  CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("copy result from device to host failed. ERROR: %d\n", ret); return ret);
  for (int64_t i = 0; i < size; i++) {
    LOG_PRINT("out2 result[%ld] is: %f\n", i, out2Data[i]);
  }

  // 6. 释放aclTensor,需要根据具体API的接口定义修改
  aclDestroyTensorList(tensorListInput);
  aclDestroyTensorList(tensorListOutput);

  // 7.释放device资源,需要根据具体API的接口定义修改
  aclrtFree(input1DeviceAddr);
  aclrtFree(input2DeviceAddr);
  aclrtFree(out1DeviceAddr);
  aclrtFree(out2DeviceAddr);
  if (workspaceSize > 0) {
    aclrtFree(workspaceAddr);
  }
  aclrtDestroyStream(stream);
  aclrtResetDevice(deviceId);
  aclFinalize();
  return 0;
}

该示例的执行流程可归纳为六步:

  1. 初始化:aclInit → aclrtSetDevice → aclrtCreateStream;
  2. 构造张量:通过 aclrtMalloc/aclrtMemcpy 准备 Device 侧数据,用 aclCreateTensor 创建 aclTensor,再用 aclCreateTensorList 组装输入/输出张量列表(示例中两个输入张量 shape 分别为 {2,3} 和 {1,3},输出 shape 与之对应);
  3. 两段式调用:先调 aclnnForeachExpm1GetWorkspaceSize 拿到 workspaceSize 与 executor,按需 aclrtMalloc 申请 workspace,再调 aclnnForeachExpm1 下发计算;
  4. 同步等待:aclrtSynchronizeStream 确保任务完成;
  5. 取回结果:aclrtMemcpy 将输出从 Device 复制到 Host 并打印(例如输入 {1,2,3,4,5,6} 对应输出约为 {1.718, 6.389, 19.085, 53.598, 147.413, 402.429});
  6. 释放资源:销毁 TensorList、释放 Device 内存与 workspace、销毁 stream 并 aclFinalize。

七、源码级实现剖析

为了让读者更深入理解该算子的底层行为,本节结合仓库源码补充几个关键实现事实。

7.1 算子定义:数据类型配对与平台注册

foreach_expm1_def.cpp 通过 OpDef 声明了算子的输入输出原型:

  • 输入 x 支持 FLOAT16/FLOAT32/BFLOAT16/INT16/INT8/UINT8 六种类型,格式均为 ND,ParamType(DYNAMIC) 表示动态输入;
  • 输出 y 的类型列表与输入按索引配对,整数输入对应 FLOAT 输出(源码注释明确说明"整数输入按索引配对提升 float32 输出,浮点输入输出同 dtype");
  • 通过 AICore().AddConfig(...) 分别注册 ascend910_93、ascend910b、ascend950 及 Kirin 系列平台,其中 ascend950 配置开启了 DynamicRankSupportFlag、DynamicShapeSupportFlag、PrecisionReduceFlag 等动态能力。

7.2 Kernel 实现:向量流水与 SIMT 两种路径

不同架构的 Kernel 入口采用了不同的实现路径:

  • 通用路径 op_kernel/foreach_expm1.cpp 按 TILING_KEY 分发:FLOAT16/FLOAT32 走 ForeachImplictOutput 模板,BFLOAT16/INT16/INT8/UINT8 走 ForeachIntToFloatUnary 模板(来自 foreach_utils 公共实现),核心计算由 Expm1Adapter 完成——先在向量流水上执行 Exp 得到 e^x,再执行 Adds 加 -1,两次向量指令间以 PipeBarrier<PIPE_V>() 保证流水同步;
  • arch35(Ascend 950)路径 op_kernel/arch35/foreach_expm1.cpp 采用 **SIMT 向量函数(VF)**实现,见 foreach_expm1_simt.h:固定 1024 线程,先按 tensorId 从 TensorList 中解析每个张量的 GM 地址(SimtGetTensorAddr),再按线程网格步长遍历元素,对每个元素调用 expm1f 计算,整数输入在 SIMT 路径同样先转 float 计算再回写。

7.3 Tiling 与二进制配置

Host 侧 Tiling 在 foreach_expm1_tiling_arch35.cpp 中实现:从平台信息读取 AIV 核数与 UB 内存大小,遍历 TensorList 中每个张量,将其元素个数写入 ForeachExpm1TilingData(结构体见 foreach_expm1_tiling_data.h,包含 tensorCount、totalElements 与最多 256 个张量的 tensorElements 数组),供 Kernel 端按张量逐个调度。

此外,各平台目录下维护了算子二进制配置文件,例如 ascend910b/foreach_expm1_binary.json 按 dtype 组合(float16→float16、float32→float32、bfloat16→bfloat16、int16→float32、int8→float32、uint8→float32)各注册一条二进制记录,shape 为 [-2] 表示动态 shape,与文档参数表完全一致。

7.4 测试与验证

仓库为该算子提供了完整的 UT/ST 测试链:

  • Host 侧单测:foreach/foreach_expm1/tests/ut/op_host/ 下的 infershape 与 arch22/arch35 两套 tiling 测试,覆盖 shape 推导与多平台 Tiling 逻辑;
  • Kernel 侧单测:foreach/foreach_expm1/tests/ut/op_kernel/test_foreach_expm1.cpp 配合 expm1_data/gen_data.py、compare_data.py 生成/比对测试数据;
  • 系统测试:foreach/foreach_expm1/tests/st/aclnnForeachExpm1/ 下的 ATK 用例(atk_aclnnForeachExpm1.json 与 executor_aclnnForeachExpm1.py)用于端到端验证 aclnn 接口行为。

八、常见问题与注意事项

  • 第二段接口重复调用:同一 executor 不支持连续多次执行 aclnnForeachExpm1,每次执行应重新走一遍两段式流程;
  • workspace 内存:只有当 workspaceSize > 0 时才需要 aclrtMalloc 申请,示例代码对此做了判空处理;从 Kernel 源码看,foreach 向量路径 userWS = nullptr,即大部分场景无需额外 workspace;
  • 整数输入精度:INT16/INT8/UINT8 输入会先提升为 FLOAT32 计算,输出 dtype 为 FLOAT32,若业务要求半精度输出请自行 cast;
  • shape 匹配:输出 shape size 需不小于输入,各张量维度不得超过 8 维,且 TensorList 内所有张量 dtype 必须一致;
  • 平台差异:Atlas 200I/500 A2 推理产品、Atlas 推理系列产品与 Atlas 训练系列产品不支持本算子,调用前请确认目标硬件型号。

九、参考链接

登录后查看全文
ops-nn