CANN ops-math 随机算子 aclnnDropout 接口详解:两段式调用、参数约束与 NPU 实战示例

原创2026-09-21 17:01:231,628 阅读
文章标签:算子库人工智能深度学习高性能计算CANNAscend

CANN ops-math 随机算子 aclnnDropout 接口详解:两段式调用、参数约束与 NPU 实战示例

本篇技术指南聚焦 CANN 数学算子库 ops-math 中 random/dsa_gen_bit_mask 模块提供的 aclnnDropout 随机 Dropout 算子接口。文章完整继承官方接口文档的语义定义与参数约束,并深入结合仓库内 aclnn_dropout.cpp 的实现与 UT/ST 测试用例,帮助读者掌握两段式 aclnn 接口的调用流程、maskOut 位图 tensor 的 shape 推导规则、参数校验错误码,以及如何在 Atlas 训练/推理产品上直接编写可编译运行的 C++ 调用示例。

算子定位与产品支持情况

aclnnDropout 是训练过程中常用的正则化算子:按照概率 p 随机将输入张量中的元素置零,并将保留元素按照 1/(1-p) 的比例缩放,从而在期望上保持输出与输入均值一致。该接口位于本仓库 random/dsa_gen_bit_mask 目录(该目录仅包含 DSAGenBitMask 算子对应的 aclnn 接口,AscendC 算子实现贡献流程参见 CONTRIBUTING.md),其头文件声明见 aclnn_dropout.h。

产品支持情况(以当前仓库文档为准):

产品 支持情况
Ascend 950PR / Ascend 950DT 不支持
Atlas A3 训练系列产品 / Atlas A3 推理系列产品 支持
Atlas A2 训练系列产品 / Atlas A2 推理系列产品 支持
Atlas 200I/500 A2 推理产品 不支持
Atlas 推理系列产品 不支持
Atlas 训练系列产品 支持

需要特别注意的是,在 Atlas 训练系列产品上,input 的数据类型不支持 BFLOAT16(详见下文参数表与源码中按 SoC 版本区分的 dtype 支持列表)。

功能与计算公式

aclnnDropout 的接口功能定义为:训练过程中,按照概率 p 随机将输入中的元素置零,并将输出按照 1/(1-p) 的比例缩放,其数学表达式为:

out_i = 0,                     with probability p
out_i = (1/(1-p)) * input_i,   with probability 1-p

从源码实现(aclnn_dropout.cpp)可以进一步印证该语义被拆分成了“生成 mask”与“按 mask 缩放”两个阶段:

  • 当 p == 0 或 train == false 时,DoMaskWithTrain 直接返回连续化后的输入,不做任何置零处理(mask 原样透传);
  • 当 p == 1 时,使用 ZerosLike 将输出置为全零;
  • 当 0 < p < 1 且处于训练场景时,先由随机数生成 mask,再调用 DropoutDoMask(位于 dropout_common.h),以 1-p 作为 keep 概率完成缩放。

两段式接口与函数原型

CANN 的每个 aclnn 算子都采用两段式接口设计(通用规范见 docs/zh/context/two_phase_api.md):必须先调用第一段接口 aclnnDropoutGetWorkspaceSize 获取计算所需 workspace 大小以及包含了算子计算流程的执行器,再调用第二段接口 aclnnDropout 执行计算。

第一段接口原型:

aclnnStatus aclnnDropoutGetWorkspaceSize(
  const aclTensor*  input,
  double            p,
  bool              train,
  int64_t           seed,
  int64_t           offset,
  aclTensor*        out,
  aclTensor*        maskOut,
  uint64_t*         workspaceSize,
  aclOpExecutor**   executor)

第二段接口原型:

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

aclnnDropoutGetWorkspaceSize 参数详解

参数说明

参数名 输入/输出 描述 使用说明 数据类型 数据格式 维度(shape) 非连续tensor
input(aclTensor*) 输入 表示待处理的张量,公式中的 input 不支持空 Tensor BFLOAT16、FLOAT16、FLOAT32 ND 1-8 √
p(double) 输入 元素置零的概率,公式中的 p 数值的值域为 [0, 1] - - - -
train(bool) 输入 是否为训练场景 - - - - -
seed(int64_t) 输入 随机数的种子,影响生成的随机数序列 - - - - -
offset(int64_t) 输入 随机数的偏移量,影响生成的随机数序列的位置 - - - - -
out(aclTensor*) 输出 输出的 tensor,公式中的 out 不支持空 Tensor;数据类型需要是 input 可转换的数据类型,shape 需要与 input 一致 BFLOAT16、FLOAT16、FLOAT32 ND 1-8 √
maskOut(aclTensor*) 输出 bit 类型并使用 UINT8 类型存储的 mask 数据 不支持空 Tensor;当 p=0、p=1 或 train=false 场景下,不对传入的 maskOut 做任何处理;其他场景下以给定的 p 为置零概率生成 mask;shape 需要为 align(input 的元素个数, 128)/8,表示比特数需要与 128 对齐(align 表示将 input 的元素个数向上对齐为 128 的倍数,如 align(1111, 128) 的结果为 1152) UINT8 ND 1 √
workspaceSize(uint64_t*) 输出 返回需要在 Device 侧申请的 workspace 大小 - - - - -
executor(aclOpExecutor**) 输出 返回 op 执行器,包括了算子计算流程 - - - - -

Atlas 训练系列产品限制:该产品上 input 数据类型不支持 BFLOAT16。

maskOut 的 shape 推导

maskOut 是理解该接口的关键:它以比特位(bit)为单位记录每个元素是否被置零,再用 UINT8 类型存储。因此其元素个数 = align(元素个数, 128) / 8。例如示例中 input shape 为 {4, 2}(8 个元素),align(8, 128) = 128,maskOut shape 即为 128 / 8 = 16(与 test_dropout.cpp 中的 maskOutShape = {16} 对应)。

该规则在源码 CheckShape 中有严格校验(aclnn_dropout.cpp):

int64_t inputSize = input->GetViewShape().GetShapeSize();
int64_t maskSize = maskOut->GetViewShape().GetShapeSize();
int64_t needMaskSizde = (inputSize + BIT_NUMBER - 1) / BIT_NUMBER * BIT_NUMBER / UINT8_BIT_NUMBER;

其中 BIT_NUMBER = 128、UINT8_BIT_NUMBER = 8,即先按 128 向上取整对齐,再除以 8 换算为字节数。UT 用例 case_008(test_aclnn_dropout_l2.cpp)专门构造了错误的 maskOut shape {32} 验证该校验逻辑返回 ACLNN_ERR_PARAM_INVALID。

返回值与第一段接口的入参校验

aclnnStatus:返回状态码,具体参见 docs/zh/context/aclnn_return_code.md。第一段接口完成入参校验,出现以下场景时报错:

返回码 错误码 描述
ACLNN_ERR_PARAM_NULLPTR 161001 传入的 input、out、maskOut 为空指针
ACLNN_ERR_PARAM_INVALID 161002 input、out、maskOut 的数据类型不在支持的范围之内
ACLNN_ERR_PARAM_INVALID 161002 p 的值不在 0 和 1 之间
ACLNN_ERR_PARAM_INVALID 161002 input 维度超过 8 维
ACLNN_ERR_PARAM_INVALID 161002 input 和 out 的 shape 不一致
ACLNN_ERR_PARAM_INVALID 161002 maskOut 的 shape 不满足条件

源码中 CheckParams 依次执行了四类校验(aclnn_dropout.cpp),与上表一一对应:

  1. CheckNotNull:检查 input/out/maskOut 是否为空指针(对应 161001);
  2. CheckDtypeValid:检查 out 可由 input 强转(OP_CHECK_RESULT_DTYPE_CAST_FAILED),并依据 SoC 版本选择 dtype 支持列表——ASCEND910 支持 DT_FLOAT、DT_FLOAT16,ASCEND910B/ASCEND910_93 额外支持 DT_BF16,maskOut 仅支持 DT_UINT8(对应 161002);
  3. CheckProbability:校验 0 <= p <= 1(对应 161002);
  4. CheckShape:校验最大维度不超过 8、input 与 out shape 一致、maskOut 大小满足 128 对齐公式(对应 161002)。

此外还有一层警告而非报错的校验:CheckFormat 检测到输入为 FORMAT_FRACTAL_NZ 格式时仅打印警告,提示该格式可能导致精度问题。UT 用例 case_001~case_009 覆盖了空指针、dtype 非法、p 越界、shape 不匹配等全部失败路径,可直接作为回归依据。

aclnnDropout 参数说明

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

第二段接口在源码中的实现非常简洁,本质上是调用框架的统一执行入口完成 Device 侧计算:

aclnnStatus aclnnDropout(void* workspace, uint64_t workspaceSize, aclOpExecutor* executor, aclrtStream stream)
{
    L2_DFX_PHASE_2(aclnnDropout);
    return CommonOpExecutorRun(workspace, workspaceSize, executor, stream);
}

也就是说,真正的计算图编排(生成 mask → 连续化 → DoMask → Cast → ViewCopy)全部在第一段接口阶段完成并固化进 executor,第二段接口只负责提交执行。

约束说明

  • 确定性计算:aclnnDropout 默认确定性实现。这意味着给定相同的 seed、offset 与输入,多次调用可以得到一致的随机 mask 与输出,便于调试与复现。

调用示例(可直接编译运行)

以下完整示例来自 random/dsa_gen_bit_mask/docs/aclnnDropout.md,仓库中 examples/test_dropout.cpp 提供了同样的可运行代码。具体编译与执行过程请参考 docs/zh/context/compile_and_run_sample.md。

#include <iostream>
#include <vector>
#include "acl/acl.h"
#include "aclnnop/aclnn_dropout.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> selfShape = {4, 2};
  std::vector<int64_t> outShape = {4, 2};
  std::vector<int64_t> maskOutShape = {16};
  void* selfDeviceAddr = nullptr;
  void* outDeviceAddr = nullptr;
  void* maskOutDeviceAddr = nullptr;
  aclTensor* self = nullptr;
  aclTensor* out = nullptr;
  aclTensor* maskOut = nullptr;
  std::vector<float> selfHostData = {0, 1, 2, 3, 4, 5, 6, 7};
  std::vector<float> outHostData(8, 0);
  std::vector<uint8_t> maskOutHostData(16, 0);
  double p = 0.5;
  bool train = true;
  int64_t seed = 1234;
  int64_t offset = 0;
  // 创建self aclTensor
  ret = CreateAclTensor(selfHostData, selfShape, &selfDeviceAddr, aclDataType::ACL_FLOAT, &self);
  CHECK_RET(ret == ACL_SUCCESS, return ret);
  // 创建out aclTensor
  ret = CreateAclTensor(outHostData, outShape, &outDeviceAddr, aclDataType::ACL_FLOAT, &out);
  CHECK_RET(ret == ACL_SUCCESS, return ret);
  // 创建maskOut aclTensor
  ret = CreateAclTensor(maskOutHostData, maskOutShape, &maskOutDeviceAddr, aclDataType::ACL_UINT8, &maskOut);
  CHECK_RET(ret == ACL_SUCCESS, return ret);

  // 3. 调用CANN算子库API,需要修改为具体的API名称
  uint64_t workspaceSize = 0;
  aclOpExecutor* executor;
  // 调用aclnnDropout第一段接口
  ret = aclnnDropoutGetWorkspaceSize(self, p, train, seed, offset, out, maskOut, &workspaceSize, &executor);
  CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclnnDropoutGetWorkspaceSize 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);
  }
  // 调用aclnnDropout第二段接口
  ret = aclnnDropout(workspaceAddr, workspaceSize, executor, stream);
  CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclnnDropout 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(outShape);
  std::vector<float> resultData(size, 0);
  ret = aclrtMemcpy(resultData.data(), resultData.size() * sizeof(resultData[0]), outDeviceAddr,
                    size * sizeof(resultData[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("result[%ld] is: %f\n", i, resultData[i]);
  }

  // 6. 释放aclTensor和aclScalar,需要根据具体API的接口定义修改
  aclDestroyTensor(self);
  aclDestroyTensor(out);
  aclDestroyTensor(maskOut);

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

示例要点说明:

  • Init 完成 aclInit、aclrtSetDevice、aclrtCreateStream 的固定初始化流程;
  • CreateAclTensor 模板函数封装了“申请 Device 内存 → Host 到 Device 拷贝 → 计算连续 strides → aclCreateTensor 创建 ND 格式 aclTensor”的完整过程;
  • 第 3 步是两段式调用的核心:先通过 aclnnDropoutGetWorkspaceSize 得到 workspaceSize 与 executor,再根据 workspaceSize 用 aclrtMalloc 申请 workspace(workspaceSize > 0 时才需要申请),最后调用 aclnnDropout 提交执行;
  • 第 4~5 步用 aclrtSynchronizeStream 同步等待任务完成,再将 Device 侧结果拷回 Host 打印;
  • 第 6~7 步依次释放 aclTensor、Device 内存、stream,并 aclrtResetDevice + aclFinalize 收尾。

源码级实现原理:第一段接口内部的计算编排

第一段接口 aclnnDropoutGetWorkspaceSize(aclnn_dropout.cpp)内部并非只做参数校验,而是将整个计算流程编排为一系列底层 l0op 并记录进 executor,其关键调用链为:

  1. CREATE_EXECUTOR() 创建 OpExecutor,随后执行 CheckParams 四步校验;
  2. 若 input 为空 tensor,直接返回 workspaceSize = 0 的 ACLNN_SUCCESS;
  3. 根据 p 与 train 决定 mask 来源:
    • p == 0 || !train:mask 直接采用传入的 maskOut,不做生成;
    • p == 1:同样采用 maskOut,后续由 DoMask 的 ZerosLike 分支将输出置零;
    • 其他场景:调用 ComputeMask 生成随机 mask。其中在 ASCEND910B 上走 l0op::DSAGenBitMask(声明见 dsa_gen_bit_mask.h,count = align 后大小 / 4 个 float 位宽),其他 SoC 走 l0op::StatelessDropoutGenMask(seed 序列 {seed}、offset 序列 {0, offset}、概率 1-p);
  4. l0op::Contiguous 将 input 连续化(保证底层 kernel 可直接按行访问);
  5. DoMaskWithTrain → DoMask 完成置零与 1/(1-p) 缩放(p=0 直接透传,p=1 全零,否则 DropoutDoMask);
  6. l0op::Cast 将结果转换为 out 声明的数据类型;
  7. l0op::ViewCopy 分别将计算结果拷入 out、将 mask 拷入 maskOut,从而天然支持非连续 tensor 的输出;
  8. 最终 *workspaceSize = uniqueExecutor->GetWorkspaceSize(),并将 executor 所有权转移给调用方。

可以看到,Cast + ViewCopy 的组合是该接口支持“out 与 input 数据类型可转换、且 out 可为非连续 tensor”的关键:中间计算统一在 input 的连续表示上进行,最后按目标 dtype 转换并按 view 拷贝回用户提供的存储。

测试与精度验证

仓库为 aclnnDropout 提供了双层测试保障:

  • Host 侧 L2 单测(tests/ut/op_host/op_api/test_aclnn_dropout_l2.cpp):case_001~case_003 验证 input/out/maskOut 为 nullptr 时返回 ACLNN_ERR_PARAM_NULLPTR;case_004~case_006 验证 dtype 非法(如 FLOAT16 输入配 INT32 输出、maskOut 用 FLOAT)返回 ACLNN_ERR_PARAM_INVALID;case_007 验证 p=1.5 越界报错;case_008/case_009 验证 maskOut shape 错误与 out shape 不一致均报 ACLNN_ERR_PARAM_INVALID;
  • ATK 系统测试(tests/st/aclnnDropout/atk_aclnnDropout.json 与 executor_aclnnDropout.py):覆盖 fp16/fp32/bf16 三种 dtype、从 1 维到 8 维的多种 shape(含 [256]、[257] 等 128 对齐边界,以及含 1 的维度)、p 从 0.003 到 0.99 的取值,执行器采用 TensorFlow StatelessRandomUniformV2 生成与 seed/offset 对应的参考随机数,构造 golden 结果:output = input * scale * mask(scale = 1/(1-p)),并校验 maskOut 的比特位。

总结

aclnnDropout 是 CANN ops-math 中结构清晰、约束明确的随机化算子接口:以“概率置零 + 1/(1-p) 缩放”的数学语义为核心,通过两段式接口把计算编排与执行提交分离,其中 maskOut 的 128 位对齐 shape 规则与按 SoC 版本区分的 dtype 支持列表是实际使用中最容易踩坑的两点。结合仓库内的源码实现、L2 单测与 ATK 系统测试,开发者既可以快速写出可编译运行的调用示例,也能在精度异常或校验报错时快速定位到对应校验分支,从而在 Atlas 训练/推理产品上正确、高效地完成 Dropout 算子的接入与调优。

登录后查看全文
ops-math