CANN/asc-devkit DropOut API文档

DropOut

【免费下载链接】asc-devkit本项目是CANN 推出的昇腾AI处理器专用的算子程序开发语言，原生支持C和C++标准规范，主要由类库和语言扩展层构成，提供多层级API，满足多维场景算子开发诉求。项目地址: https://gitcode.com/cann/asc-devkit

产品支持情况

• Ascend 950PR/Ascend 950DT：支持

• Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持

• Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持

• Atlas 200I/500 A2 推理产品：不支持

• Atlas 推理系列产品AI Core：支持
• Atlas 推理系列产品Vector Core：不支持

• Atlas 训练系列产品：不支持

• Kirin X90：支持

• Kirin 9030：支持

功能说明

提供根据MaskTensor对SrcTensor（源操作数，输入Tensor）进行过滤的功能，得到DstTensor（目的操作数、输出Tensor）。仅支持输入shape为ND格式。

该过滤功能包括两种模式，字节模式和比特模式。

• 字节模式

  MaskTensor中存储的数值为布尔类型，每个布尔数值代表是否取用SrcTensor对应位置的数值：如果是，则选取SrcTensor中的数值存入DstTensor；否则，对DstTensor中的对应位置赋值为零。DstTensor，SrcTensor和MaskTensor的shape相同。示例如下：

  SrcTensor=[1，2，3，4，5，6，7，8，9，10]

  MaskTensor=[1，0，1，0，1，0，0，1，1，0]（每个数的数据类型为uint8_t）

  DstTensor=[1，0，3，0，5，0，0，8，9，0]

• 比特模式

  MaskTensor的每个bit数值，代表是否取用SrcTensor对应位置的数值：如果是，则选取SrcTensor中的数值存入DstTensor；否则，对DstTensor中的对应位置赋值为零。SrcTensor和DstTensor的shape相同，假设均为[height ， width]，MaskTensor的shape为[height ，(width / 8)]。示例如下：

  SrcTensor=[1，2，3，4，5，6，7，8]

  MaskTensor=[169]（转换为二进制表示为1010 1001）

  DstTensor=[1，0，3，0，5，0，0，8]

  • 特殊情况1：当MaskTensor有效数据非连续存放时，MaskTensor的width轴，为了满足32B对齐，需要填充无效数值，SrcTensor的width轴，需满足32Byte对齐。示例如下：

    SrcTensor=[1，2，3，4，5，6，7，8，11，12，13，14，15，16，17，18]

    MaskTensor=[1，0，1，0，1，0，0，1，X，X，1，0，1，0，1，0，0，1，X，X]（X为无效数值，假设数据已满足对齐要求，示例数值为二进制形式表示）

    DstTensor=[1，0，3，0，5，0，0，8，11，0， 13， 0， 15， 0， 0，18]

  • 特殊情况2：当MaskTensor有效数据连续存放，maskTensor_size不满足32B对齐时，需要在MaskTensor的尾部补齐32B对齐时，对应SrcTensor的尾部也需要补充无效数据，使得srcTensor_size满足32B对齐。示例如下：

    SrcTensor=[1，2，3，4，5，6，7，8，11，12，13，14，15，16，17，18]

    MaskTensor=[1，0，1，0，1，0，0，1， 1， 0， 1， 0， 1， 0， 0， 1，X，X，X，X]（X为无效数值，假设数据已满足对齐要求，示例数值为二进制形式表示）

    DstTensor= [1，0，3，0，5，0，0，8， 11， 0， 13， 0， 15， 0， 0， 18]

实现原理

以float类型，ND格式，shape为[srcM, srcN]的SrcTensor，shape为[maskM, maskN]的MaskTensor，比特模式场景为例，描述Dropout高阶API内部算法框图，如下图所示。

图1Dropout算法框图
![](https://raw.gitcode.com/cann/asc-devkit/raw/31ce9050dad608bdfebdabcb0f6e883a02388806/docs/zh/api/figures/Dropout算法框图.png "Dropout算法框图"?utm_source=gitcode_repo_files)

计算过程分为如下几步，均在Vector上进行：

1. GatherMask步骤：对输入的MaskTensor做脏数据清理，使得MaskTensor中只保留有效数据；
2. Select步骤：根据输入的MaskTensor对SrcTensor做数据选择，被选中的数据位置，保留原始数据，对舍弃的数据位置，设置为0；
3. Muls步骤：将输出数据每个元素除以keepProb。

图2Dropout算法框图
![](https://raw.gitcode.com/cann/asc-devkit/raw/31ce9050dad608bdfebdabcb0f6e883a02388806/docs/zh/api/figures/Dropout算法框图-55.png "Dropout算法框图-55"?utm_source=gitcode_repo_files)

计算过程在Vector上进行，循环srcM次，每次对srcN个元素进行如下操作：

1. Select步骤：根据输入的MaskTensor对SrcTensor做数据选择，被选中的数据位置，保留原始数据，对舍弃的数据位置，设置为0；
2. Muls步骤：将输出数据每个元素除以keepProb。

函数原型

template <typename T, bool isInitBitMode = false, uint32_t dropOutMode = 0> __aicore__ inline void DropOut(const LocalTensor<T>& dstLocal, const LocalTensor<T>& srcLocal, const LocalTensor<uint8_t>& maskLocal, const float keepProb, const DropOutShapeInfo& info)

template <typename T, bool isInitBitMode = false, uint32_t dropOutMode = 0> __aicore__ inline void DropOut(const LocalTensor<T>& dstLocal, const LocalTensor<T>& srcLocal, const LocalTensor<uint8_t>& maskLocal, const LocalTensor<uint8_t>& sharedTmpBuffer, const float keepProb, const DropOutShapeInfo& info)

参数说明

表1模板参数说明

表2接口参数说明

struct DropOutShapeInfo { __aicore__ DropOutShapeInfo() {}; uint32_t firstAxis = 0; uint32_t srcLastAxis = 0; uint32_t maskLastAxis = 0; };

返回值说明

无

约束说明

• srcTensor和dstTensor的Tensor空间可以复用。

• srcLocal和dstLocal地址对齐要求请见：通用说明和约束。

• 仅支持输入shape为ND格式。

• maskLocal含有脏数据的场景，要求info.maskLastAxis中有效数值的个数，应为2的整数倍。

• maskLocal含有脏数据的场景，maskLocal中的数据可能会被修改，脏数据可能会被舍弃。

• 支持的数据类型

  Ascend 950PR/Ascend 950DT，支持的数据类型为：half、bfloat16_t、float。

  Atlas A3 训练系列产品/Atlas A3 推理系列产品，支持的数据类型为：half、float。

  Atlas A2 训练系列产品/Atlas A2 推理系列产品，支持的数据类型为：half、float。

  Atlas 推理系列产品AI Core，支持的数据类型为：half、float。

  Kirin X90，支持的数据类型为：half、float。

  Kirin 9030，支持的数据类型为：half、float。

调用示例

// yLocal：DropOut结果 // xLocal：输入数据 // maskLocal：过滤掩码 // sharedTmpBuffer：临时空间 // probValue：srcLocal中数据被保留的概率，过滤后的结果会除以权重系数，存放至dstLocal中 // info：DropOutShapeInfo类型 AscendC::DropOutShapeInfo info; float probValue = 0.5; info.firstAxis = tilingData.firstAxis / tilingData.tileNum; info.srcLastAxis = tileLength; info.maskLastAxis = tileLength; AscendC::DropOut(yLocal, xLocal, maskLocal, sharedTmpBuffer, probValue, info);

示例结果如下：

输入数据(xLocal): [ 0. 1. 2. 3. 4. 5. 6. 7. 8. 9. 10. 11. 12. 13. 14. 15. 16. 17. 18. 19. 20. 21. 22. 23. 24. 25. 26. 27. 28. 29. 30. 31. ] 输入数据(maskLocal): [ 0 1 0 0 0 0 0 0 1 0 1 1 1 0 1 1 0 0 1 0 0 1 1 1 1 0 1 0 1 1 1 0 ] 输入数据(probValue): 0.5 输出数据(yLocal): [ 0. 2. 0. 0. 0. 0. 0. 0. 16. 0. 20. 22. 24. 0. 28. 30. 0. 0. 36. 0. 0. 42. 44. 46. 48. 0. 52. 0. 56. 58. 60. 0. ]

【免费下载链接】asc-devkit本项目是CANN 推出的昇腾AI处理器专用的算子程序开发语言，原生支持C和C++标准规范，主要由类库和语言扩展层构成，提供多层级API，满足多维场景算子开发诉求。项目地址: https://gitcode.com/cann/asc-devkit