CANN ops-math 随机算子 aclnnDropout 接口详解:两段式调用、参数约束与 NPU 实战示例
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),与上表一一对应:
CheckNotNull:检查 input/out/maskOut 是否为空指针(对应 161001);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);CheckProbability:校验0 <= p <= 1(对应 161002);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,其关键调用链为:
CREATE_EXECUTOR()创建 OpExecutor,随后执行CheckParams四步校验;- 若
input为空 tensor,直接返回workspaceSize = 0的ACLNN_SUCCESS; - 根据
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);
l0op::Contiguous将 input 连续化(保证底层 kernel 可直接按行访问);DoMaskWithTrain→DoMask完成置零与1/(1-p)缩放(p=0直接透传,p=1全零,否则DropoutDoMask);l0op::Cast将结果转换为out声明的数据类型;l0op::ViewCopy分别将计算结果拷入out、将 mask 拷入maskOut,从而天然支持非连续 tensor 的输出;- 最终
*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 的取值,执行器采用 TensorFlowStatelessRandomUniformV2生成与 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 算子的接入与调优。