aclnnMoeGatingTopKBackward

产品支持情况

产品	是否支持
Ascend 950PR/Ascend 950DT	×
Atlas A3 训练系列产品/Atlas A3 推理系列产品	√
Atlas A2 训练系列产品/Atlas A2 推理系列产品	√
Atlas 200I/500 A2 推理产品	×
Atlas 推理系列产品	×
Atlas 训练系列产品	×

功能说明

接口功能：完成MoE（Mixture of Experts）门控Top-K选择的反向梯度计算。该算子是aclnnMoeGatingTopK的反向算子，根据前向算子输出的归一化得分（xNorm）、上游梯度（gradY）和专家索引（expertIdx），计算输入得分矩阵的梯度（gradX）。支持sigmoid模式（normType=1）。
计算公式（sigmoid模式，normType=1）：
1. 缩放梯度
$gradYScaledip=routedScalingFactor⋅gradYipgradYScaled_{ip} = routedScalingFactor \cdot gradY_{ip}$
1. 正向renorm的反向传播
$wPrime_{ip} = xNorm_{i,\ expertIdx_{ip}}$

$Di=∑pwPrimeip+epsD_i = \sum_{p} wPrime_{ip} + eps$

$wip=wPrimeipDiw_{ip} = \frac{wPrime_{ip}}{D_i}$

$betai=∑pwip⋅gradYScaledipbeta_i = \sum_{p} w_{ip} \cdot gradYScaled_{ip}$

$gradWPrimeip=gradYScaledip−betaiDigradWPrime_{ip} = \frac{gradYScaled_{ip} - beta_i}{D_i}$
1. 散射到完整维度
$expertIdxip=jgradWPrimeipgradNormX_{ij} = \sum_{p:\ expertIdx_{ip}=j} gradWPrime_{ip}$
1. Sigmoid反向传播
$gradXij=xNormij⋅(1−xNormij)⋅gradNormXijgradX_{ij} = xNorm_{ij} \cdot (1 - xNorm_{ij}) \cdot gradNormX_{ij}$

函数原型

每个算子分为两段式接口，必须先调用"aclnnMoeGatingTopKBackwardGetWorkspaceSize"接口获取计算所需workspace大小以及包含了算子计算流程的执行器，再调用"aclnnMoeGatingTopKBackward"接口执行计算。

aclnnStatus aclnnMoeGatingTopKBackwardGetWorkspaceSize(
  const aclTensor  *xNorm,
  const aclTensor  *gradY,
  const aclTensor  *expertIdx,
  int64_t           renorm,
  int64_t           normType,
  double            routedScalingFactor,
  double            eps,
  const aclTensor  *out,
  uint64_t         *workspaceSize,
  aclOpExecutor   **executor)

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

aclnnMoeGatingTopKBackwardGetWorkspaceSize

参数说明

参数名	输入/输出	描述	使用说明	数据类型	数据格式	维度(shape)	非连续Tensor
xNorm（aclTensor*）	输入	计算的输入，对应公式中的xNorm。	不支持空Tensor。要求是一个2D的Tensor，维度为[M,N]。最后一维（专家数N）要求大于等于2，并小于等于2048。	FLOAT32	ND	2	√
gradY（aclTensor*）	输入	表示前向算子输出yOut的上游梯度，对应公式中的gradY。	不支持空Tensor。要求是一个2D的Tensor，维度为[M,K]，K的范围要求大于等于1，并小于等于N。	FLOAT16、BFLOAT16、FLOAT32	ND	2	√
expertIdx（aclTensor*）	输入	表示前向算子输出的top-k专家索引，对应公式中的expertIdx。	不支持空Tensor。 shape要求与gradY一致，维度为[M,K]。	INT32	ND	2	×
renorm（int64_t）	输入	表示前向算子在softmax模式下renorm标记。	0：不做renorm；1：需要做renorm；预留参数，当前仅支持sigmoid模式。	-	-	-	-
normType（int64_t）	输入	表示norm函数类型。	1表示使用Sigmoid函数，0表示Softmax函数。当前仅支持1。	-	-	-	-
routedScalingFactor（double）	输入	表示前向算子使用的routed_scaling_factor系数，对应公式中的routedScalingFactor。		-	-	-	-
eps（double）	输入	表示前向计算使用的防除零常数，对应公式中的eps。		-	-	-	-
out（aclTensor*）	输出	表示前向算子输入参数x的梯度，对应公式中的gradX。	不支持空Tensor。数据类型与gradY需要保持一致。 shape与xNorm需要一致，维度为[M,N]。	FLOAT16、BFLOAT16、FLOAT32	ND	2	×
workspaceSize（uint64_t*）	输出	返回需要在Device侧申请的workspace大小。	-	-	-	-	-
executor（aclOpExecutor**）	输出	返回op执行器，包含了算子计算流程。	-	-	-	-	-

返回值

aclnnStatus：返回状态码，具体参见aclnn返回码。

第一段接口完成入参校验，出现以下场景时报错：

返回值	错误码	描述
ACLNN_ERR_PARAM_NULLPTR	161001	xNorm、gradY、expertIdx、out存在空指针。
ACLNN_ERR_PARAM_INVALID	161002	xNorm、gradY或expertIdx的数据类型不在支持的范围之内。
		out的数据类型与xNorm不一致。
		xNorm、gradY或expertIdx的shape维度不在支持的范围之内。
		gradY与expertIdx的shape不一致。
		out与xNorm的shape不一致。

aclnnMoeGatingTopKBackward

参数说明

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

返回值

aclnnStatus：返回状态码，具体参见aclnn返回码。

约束说明

确定性计算：
- aclnnMoeGatingTopKBackward默认确定性实现。

调用示例

示例代码如下，仅供参考，具体编译和执行过程请参考编译与运行样例。

#include <iostream>
#include <vector>
#include "acl/acl.h"
#include "aclnnop/aclnn_moe_gating_top_k_backward.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);
    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);
    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);
    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];
    }
    *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初始化
    int32_t deviceId = 0;
    aclrtStream stream;
    auto ret = Init(deviceId, &stream);
    CHECK_RET(ret == 0, LOG_PRINT("Init acl failed. ERROR: %d\n", ret); return ret);

    // 2.构造输入与输出
    // xNorm: [M, N] = [4, 8], float32, sigmoid输出值在(0,1)之间
    std::vector<int64_t> xNormShape = {4, 8};
    std::vector<float> xNormHostData = {0.5f, 0.7f, 0.3f, 0.8f, 0.2f, 0.6f, 0.9f, 0.4f, 0.6f, 0.4f, 0.8f,
                                        0.1f, 0.7f, 0.5f, 0.3f, 0.9f, 0.2f, 0.9f, 0.5f, 0.6f, 0.8f, 0.3f,
                                        0.7f, 0.4f, 0.8f, 0.3f, 0.6f, 0.5f, 0.4f, 0.7f, 0.2f, 0.9f};
    // gradY: [M, K] = [4, 2], float32
    std::vector<int64_t> gradYShape = {4, 2};
    std::vector<float> gradYHostData = {1.0f, 0.5f, 0.8f, 0.3f, 0.6f, 0.9f, 0.4f, 0.7f};
    // expertIdx: [M, K] = [4, 2], int32
    std::vector<int64_t> expertIdxShape = {4, 2};
    std::vector<int32_t> expertIdxHostData = {3, 6, 2, 7, 1, 4, 0, 7};
    // gradX: [M, N] = [4, 8], float32
    std::vector<int64_t> gradXShape = {4, 8};
    std::vector<float> gradXHostData(32, 0);

    void *xNormDeviceAddr = nullptr;
    void *gradYDeviceAddr = nullptr;
    void *expertIdxDeviceAddr = nullptr;
    void *gradXDeviceAddr = nullptr;
    aclTensor *xNorm = nullptr;
    aclTensor *gradY = nullptr;
    aclTensor *expertIdx = nullptr;
    aclTensor *gradX = nullptr;

    ret = CreateAclTensor(xNormHostData, xNormShape, &xNormDeviceAddr, aclDataType::ACL_FLOAT, &xNorm);
    CHECK_RET(ret == ACL_SUCCESS, return ret);
    ret = CreateAclTensor(gradYHostData, gradYShape, &gradYDeviceAddr, aclDataType::ACL_FLOAT, &gradY);
    CHECK_RET(ret == ACL_SUCCESS, return ret);
    ret = CreateAclTensor(expertIdxHostData, expertIdxShape, &expertIdxDeviceAddr, aclDataType::ACL_INT32, &expertIdx);
    CHECK_RET(ret == ACL_SUCCESS, return ret);
    ret = CreateAclTensor(gradXHostData, gradXShape, &gradXDeviceAddr, aclDataType::ACL_FLOAT, &gradX);
    CHECK_RET(ret == ACL_SUCCESS, return ret);

    // 3.调用aclnnMoeGatingTopKBackward
    int64_t renorm = 0;
    int64_t normType = 1; // sigmoid模式
    double routedScalingFactor = 2.5;
    double eps = 1e-20;
    uint64_t workspaceSize = 0;
    aclOpExecutor *executor;

    ret = aclnnMoeGatingTopKBackwardGetWorkspaceSize(xNorm, gradY, expertIdx, renorm, normType, routedScalingFactor,
                                                     eps, gradX, &workspaceSize, &executor);
    CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclnnMoeGatingTopKBackwardGetWorkspaceSize failed. ERROR: %d\n", ret);
              return ret);

    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;);
    }

    ret = aclnnMoeGatingTopKBackward(workspaceAddr, workspaceSize, executor, stream);
    CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclnnMoeGatingTopKBackward 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.获取输出的值
    auto size = GetShapeSize(gradXShape);
    std::vector<float> resultData(size, 0);
    ret = aclrtMemcpy(resultData.data(), resultData.size() * sizeof(resultData[0]), gradXDeviceAddr,
                      size * sizeof(float), 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("gradX[%ld] is: %f\n", i, resultData[i]);
    }

    // 6.释放aclTensor
    aclDestroyTensor(xNorm);
    aclDestroyTensor(gradY);
    aclDestroyTensor(expertIdx);
    aclDestroyTensor(gradX);

    // 7.释放device资源
    aclrtFree(xNormDeviceAddr);
    aclrtFree(gradYDeviceAddr);
    aclrtFree(expertIdxDeviceAddr);
    aclrtFree(gradXDeviceAddr);
    if (workspaceSize > 0) {
        aclrtFree(workspaceAddr);
    }
    aclrtDestroyStream(stream);
    aclrtResetDevice(deviceId);
    aclFinalize();
    return 0;
}