---
title: GroupedMatmulWithRoutingOperation
description: "| 硬件型号 | 是否支持 |"
url: https://www.hiascend.com/document/detail/zh/canncommercial/latest/API/ascendtb/ascendtb_01_0153.html
sourcePath: /source/zh/canncommercial/900/API/ascendtb/ascendtb_01_0153.html
indexId: dbe093d664edac11a5ce5a7db65e4849ba2dd1d313116e0c7a870d7c42ec27a064
---
# GroupedMatmulWithRoutingOperation

#### 产品支持情况

| 硬件型号 | 是否支持 |
| --- | --- |
| Atlas 350 加速卡 | x |
| Atlas A3 推理系列产品 / Atlas A3 训练系列产品 | √ |
| Atlas A2 训练系列产品 / Atlas A2 推理系列产品 | √ |
| Atlas 训练系列产品 | x |
| Atlas 推理系列产品 | x |
| Atlas 200I/500 A2 推理产品 | x |


#### 功能说明

在MOE中，实现topK个专家权重与token激活值的乘法。该算子不支持确定性计算。


#### 使用场景

UP：根据各个专家的权值，将token值分配给topK个专家。

DOWN：根据各个专家的权值，将topK个专家计算的结果重新整合。


#### 计算过程

- UP
UP过程的计算公式如下：
其中，AcTensor为激活token值，Expertindex为专家-token索引，ExpertWeight为专家权重，计算过程如下：

  1. 根据当前专家的索引，从AcTensor中获取当前专家的激活token值。
  2. 获取当前专家的权重，并与当前专家的激活token值做BatchMatmul。
- DOWN
DOWN过程的计算公式如下：
其中，AcTensor为激活token值，Expertindex为专家-token索引，ExpertWeight为专家权重，计算过程如下：

  1. 根据当前专家的索引，从AcTensor中获取当前专家的激活token值。
  2. 获取当前专家的权重，并与当前专家的激活token值做BatchMatmul。
  3. 将当前token在所有专家上的结果相加。


#### 定义

```
struct GroupedMatmulWithRoutingParam {
    enum GroupedMatmulType : int {
        GROUPED_MATMUL_UP = 0, 
        GROUPED_MATMUL_DOWN  
    };
    bool transposeB = true;
    int32_t topK = 0;
    GroupedMatmulType groupedMatmulType = GROUPED_MATMUL_UP;
    aclDataType outDataType = ACL_DT_UNDEFINED;
    uint8_t rsv[16] = {0};
};
```


#### 参数列表

| 成员名称 | 类型 | 默认值 | 取值范围 | 是否必选 | 描述 |
| --- | --- | --- | --- | --- | --- |
| groupedMatmulType | GroupedMatmulType | GROUP\_MATMUL\_UP | GROUP\_MATMUL\_UP GROUP\_MATMUL\_DOWN | 必选 | GroupedMatmulType类型参数： GROUP\_MATMUL\_UP：使用 UP 操作。 GROUP\_MATMUL\_DOWN：使用 DOWN 操作。 |
| transposeB | bool | true | false/true | 非必选 | 是否转置B矩阵。 |
| topK | int32\_t | 0 | 大于0 | 必选 | 选取topK个专家数量。 |
| outDataType | aclDataType | ACL\_DT\_UNDEFINED | ACL\_DT\_UNDEFINED ACL\_FLOAT16 ACL\_BF16 | 反量化场景必选 | 非量化场景时，数据类型必须与输入数据类型保持一致。 反量化场景时，必须设置输出数据类型。 可选输出类型：ACL\_FLOAT16，ACL\_BF16。 |
| rsv[16] | uint8\_t | {0} | [0] | \- | 预留参数。 |


#### 输入输出

- UP
非量化场景

  - 输入| 参数 | 维度 | 数据类型 | 格式 | 描述 |
| --- | --- | --- | --- | --- |
| AcTensor | [num\_tokens, hidden\_size\_in] | float16/bf16 | ND | 激活值。 |
| ExpertWeight | [num\_experts, hidden\_size\_in, hidden\_size\_out] | float16/bf16 | ND | 专家权重。如果设置“transposeB”为true，则hidden\_size\_in和hidden\_size\_out位置调换。 |
| ExpertCount | [num\_experts] | int32 | ND | 专家Token数量。 |
| Expertindex | [num\_tokens\*topK] | int32 | ND | 专家Token索引。 |


  - 输出| 参数 | 维度 | 数据类型 | 格式 | 描述 |
| --- | --- | --- | --- | --- |
| Result | [num\_tokens\*Topk, hidden\_size\_out] | float16/bf16 | ND | 输出。 |


量化场景

  - 输入| 参数 | 维度 | 数据类型 | 格式 | 描述 |
| --- | --- | --- | --- | --- |
| AcTensor | [num\_tokens, hidden\_size\_in] | int8 | ND | 激活值。 |
| ExpertWeight | [num\_experts, hidden\_size\_in, hidden\_size\_out] | int8 | ND/NZ | 专家权重。如果设置“transposeB”为true，则hidden\_size\_in和hidden\_size\_out位置调换。 |
| ExpertCount | [num\_experts] | int32 | ND | 专家Token数量。 |
| Expertindex | [num\_tokens\*topK] | int32 | ND | 专家Token索引。 |
| nscale | [num\_experts, hidden\_size\_out] | float | ND | ExpertWeight方向反量化系数。 |
| mscale | [num\_tokens] | float | ND | AcTensor方向反量化系数。 |


  - 输出| 参数 | 维度 | 数据类型 | 格式 | 描述 |
| --- | --- | --- | --- | --- |
| Result | [num\_tokens\*Topk, hidden\_size\_out] | float16/bf16 | ND | 输出。 |


- DOWN
非量化场景

  - 输入| 参数 | 维度 | 数据类型 | 格式 | 描述 |
| --- | --- | --- | --- | --- |
| AcTensor | [num\_tokens\*topK, hidden\_size\_in] | float16/bf16 | ND | 激活值。 |
| ExpertWeight | [num\_experts, hidden\_size\_in,hidden\_size\_out] | float16/bf16 | ND | 专家权重。如果设置“transposeB”为true，则hidden\_size\_in和hidden\_size\_out位置调换。 |
| ExpertCount | [num\_experts] | int32 | ND | 专家Token数量。 |
| Expertindex | [num\_tokens\*topK] | int32 | ND | 专家Token索引。 |


  - 输出| 参数 | 维度 | 数据类型 | 格式 | 描述 |
| --- | --- | --- | --- | --- |
| Result | [num\_tokens, hidden\_size\_out] | float16/bf16 | ND | 输出。 |


量化场景

  - 输入| 参数 | 维度 | 数据类型 | 格式 | 描述 |
| --- | --- | --- | --- | --- |
| AcTensor | [num\_tokens\*topK, hidden\_size\_in] | int8 | ND | 激活值。 |
| ExpertWeight | [num\_experts, hidden\_size\_in,hidden\_size\_out] | int8 | ND/NZ | 专家权重。如果设置“transposeB”为true，则hidden\_size\_in和hidden\_size\_out位置调换。 |
| ExpertCount | [num\_experts] | int32 | ND | 专家Token数量。 |
| Expertindex | [num\_tokens\*topK] | int32 | ND | 专家Token索引。 |
| nscale | [num\_experts, hidden\_size\_out] | float | ND | ExpertWeight方向反量化系数。 |
| mscale | [num\_tokens\*topK] | float | ND | AcTensor方向反量化系数。 |


  - 输出| 参数 | 维度 | 数据类型 | 格式 | 描述 |
| --- | --- | --- | --- | --- |
| Result | [num\_tokens, hidden\_size\_out] | float16/bf16 | ND | 输出。 |


#### 约束说明

- 当选择输出类型量化 ，则输入必须为int8类型；当选择输出类型不量化 ，则输入必须为bf16或float16。
- topK的数量不能超过专家数量。
- nTokens取值范围[128, 512]。
- nExperts取值范围[128, 256]。
- topK取值范围[2, 10]。
- hiddenSizeIn在UP模式下的取值范围[32, 5120]且为32的整数倍，在DOWN模式下取值范围[32, 256]且为32的整数倍。
- hiddenSizeOut在UP模式下的取值范围[32, 256]且为32的整数倍，在DOWN模式下取值范围[32, 5120]且为32的整数倍。