aclnnMoeDistributeDispatchV4-Transformer类接口-算子接口（aclnn）-算子库-API参考-CANN社区版9.1.0-beta.3开发文档-昇腾社区

[object Object]

[object Object][object Object]undefined

[object Object]

接口功能：对token数据进行量化（可选），当存在TP域通信时，先进行EP（Expert Parallelism）域的AllToAllV通信，再进行TP（Tensor Parallelism）域的AllGatherV通信；当不存在TP域通信时，进行EP（Expert Parallelism）域的AllToAllV通信。

相较于[object Object]接口，该接口变更如下：

新增采集通信耗时功能，记录每张卡的通信时间，通过传入[object Object]参数开启该特性。该功能推荐结合工具使用。单次算子调用各卡通信耗时会累加到该Tensor上，用户使用前按需清零。
计算公式：
- 情形1：如果不存在tp域通信。
$expandXOut = AllToAllV(X)\\$
- 情形2：如果存在tp域通信。
$allToAllOut = AllToAllV(X)\\ expandXOut = AllGatherV(allToAllOut)\\$
[object Object]Atlas A2 训练系列产品/Atlas A2 推理系列产品[object Object]：该接口必须与[object Object]配套使用。
Atlas 350 加速卡：该接口必须与[object Object]或[object Object]配套使用。

说明：[object Object]、[object Object]算子在后续文档中统称为CombineV4系列算子。

[object Object]

每个算子分为，必须先调用 “aclnnMoeDistributeDispatchV4GetWorkspaceSize”接口获取计算所需workspace大小以及包含了算子计算流程的执行器，再调用“aclnnMoeDistributeDispatchV4”接口执行计算。

[object Object]

参数说明
[object Object][object Object]
- dynamicScalesOut仅quantMode取值为2时有输出。
- commAlg支持nullptr、""、"fullmesh"、"hierarchy"；推荐配置"hierarchy"并搭配≥25.0.RC1.1版本驱动；nullptr和""依HCCL环境变量选择算法（不推荐）；"fullmesh"通过RDMA直传token；"hierarchy"经跨机、机内两次发送优化通信。
- commAlg为"hierarchy"或HCCL_INTRA_PCIE_ENABLE=1且HCCL_INTRA_ROCE_ENABLE=0时，scalesOptional需传nullptr；commAlg为"fullmesh"时，scalesOptional可传有效数据或空指针。
- xActiveMaskOptional依commAlg取值，"fullmesh"要求为1D Tensor，shape为(BS, )；true需排在false前（例：{true, false, true}非法）；"hierarchy"当前版本不支持，传空指针即可。
- expertScalesOptional要求为2D Tensor，shape为(BS, K)。
- epWorldSize依commAlg取值，"fullmesh"支持2、3、4、5、6、7、8、16、32、64、128、192、256、384；"hierarchy"支持16、32、64。
- moeExpertNum依commAlg取值，"fullmesh"支持(0, 1024]，"hierarchy"支持(0, 512]。
- groupTp当前版本不支持，传空字符即可。
- tpWorldSize、tpRankId、expertShardType、sharedExpertNum、sharedExpertRankNum当前版本不支持，传0即可。
- epRecvCountsOut的shape为(moeExpertNum + 2 * globalBS * K * serverNum,)（前moeExpertNum个为接收token数，剩余为通信前reduce相关信息）。
- 当前不支持TP域通信。
- expandScalesOut要求为1D Tensor，shape为(A,)。
- quantMode支持0（非量化）、2（动态量化）。
- elasticInfoOptional当前版本不支持，传空指针即可。
- zeroExpertNum当commAlg="fullmesh"时，取值范围:[0, MAX_INT32)，MAX_INT32 = 2^31 - 1,合法的零专家的ID的值是[[object Object]moeExpertNum[object Object], [object Object]moeExpertNum + zeroExpertNum[object Object])。
- copyExpertNum当commAlg="fullmesh"时，取值范围:[0, MAX_INT32)，MAX_INT32 = 2^31 - 1,合法的拷贝专家的ID的值是[[object Object]moeExpertNum + zeroExpertNum[object Object], [object Object]moeExpertNum + zeroExpertNum + copyExpertNum[object Object])。
- constExpertNum当前版本不支持，传0即可。
- performanceInfoOptional可选择传入有效数据或填空指针，传入空指针时表示不开启记录通信耗时功能；当传入有效数据时，要求是一个1D的Tensor，shape为(epWorldSize,)，数据类型支持int64；数据格式要求为ND。[object Object]
[object Object]
- dynamicScalesOut仅quantMode取值为2时有输出。
- commAlg支持""，"fullmesh_v1"，"fullmesh_v2", "hierarchy"三种输入方式。""：默认值，不开启fullmesh_v2模板；"fullmesh_v1"：不开启fullmesh_v2模板；"fullmesh_v2"：开启fullmesh_v2模板，该模板仅支持tpWorldSize为1场景；"hierarchy": 开启跨超模板，该模板仅支持tpWorldSize为1、共享专家为0的场景，且不支持可变BS、二维mask、特殊专家、performanceInfo场景。
- xActiveMaskOptional要求为1D或2D Tensor（1D时shape为(BS, )，2D时shape为(BS, K)）；1D时true需排在false前，2D时token对应K个值全为false则不参与通信。
- expertScalesOptional当commAlg="hierarchy"场景时，要求为2D Tensor，shape为(BS, K)；当commAlg=""，"fullmesh_v1"，"fullmesh_v2"场景时，暂不支持该参数，传空指针即可。
- epWorldSize取值范围[2, 768]；当commAlg="hierarchy"场景时，取值范围为[16, 256]，且为16的整数倍。
- moeExpertNum取值范围(0, 1024]；当commAlg="hierarchy"场景时，取值范围为(0, 512]。
- groupTp字符串长度范围为[0, 128)，不能和groupEp相同，仅在无tp域通信时支持传空。
- tpWorldSize取值范围[0, 2]，0和1表示无TP域通信，有TP域通信时仅支持2。
- tpRankId取值范围[0, 1]，同一个TP通信域中各卡的tpRankId不重复；无TP域通信时传0即可。
- expertShardType当前仅支持传0，表示共享专家卡排在MoE专家卡前面。
- sharedExpertNum当前取值范围[0, 4]。
- sharedExpertRankNum取值范围[0, epWorldSize)；为0时需满足sharedExpertNum为0或1，不为0时需满足sharedExpertRankNum % sharedExpertNum = 0。
- epRecvCountsOut的shape为(epWorldSize * max(tpWorldSize, 1) * localExpertNum,)。
- 有TP域通信时tpRecvCountsOut为1D shape Tensor，shape为(tpWorldSize,)。
- expandScalesOut当commAlg="hierarchy"场景时，要求为1D Tensor，shape为(A,)；当commAlg=""，"fullmesh_v1"，"fullmesh_v2"场景时，暂不支持该输出。
- quantMode支持0（非量化）、2（动态量化）。
- elasticInfoOptional当前版本不支持，传空指针即可。
- zeroExpertNum取值范围:[0, MAX_INT32)，MAX_INT32 = 2^31 - 1,合法的零专家的ID的值是[object Object][moeExpertNum, moeExpertNum + zeroExpertNum)[object Object]。
- copyExpertNum取值范围:[0, MAX_INT32)，MAX_INT32 = 2^31 - 1，专家ID范围[object Object][moeExpertNum + zeroExpertNum, moeExpertNum + zeroExpertNum + copyExpertNum)[object Object]。
- constExpertNum取值范围:[0, MAX_INT32)，MAX_INT32 = 2^31 - 1，专家ID范围[object Object][moeExpertNum + zeroExpertNum + copyExpertNum, moeExpertNum + zeroExpertNum + copyExpertNum + constExpertNum)[object Object]。
- performanceInfoOptional可选择传入有效数据或填空指针，传入空指针时表示不开启记录通信耗时功能；当传入有效数据时，要求是一个1D的Tensor，shape为(epWorldSize,)，数据类型支持int64；数据格式要求为ND。
- scalesOptional 2D Tensor，非量化场景传空指针；动态量化可传有效数据或空指针。[object Object]
[object Object]
- dynamicScalesOut quantMode取值为2、3、4时有输出；quantMode取值为0且[object Object]的数据类型为[object Object]、[object Object]、[object Object]、[object Object]、[object Object]时也有输出。
- commAlg支持""，"fullmesh_v1"，"fullmesh_v2"三种输入方式。""：默认值，不开启fullmesh_v2模板；"fullmesh_v1"：不开启fullmesh_v2模板；"fullmesh_v2"：开启fullmesh_v2模板，其中commAlg仅支持tpWorldSize为1场景。
- xActiveMaskOptional要求为1D或2D Tensor（1D时shape为(BS, )，2D时shape为(BS, K)）；1D时true需排在false前，2D时token对应K个值全为false则不参与通信。
- expertScalesOptional当前版本不支持，传空指针即可。
- epWorldSize取值范围[2, 768]。
- moeExpertNum取值范围(0, 1024]。
- groupTp当前版本不支持，传空字符即可。
- tpWorldSize当前版本不支持，传0即可。
- tpRankId当前版本不支持，传0即可。
- expertShardType当前仅支持传0，表示共享专家卡排在MoE专家卡前面。
- sharedExpertNum当前取值范围[0, 4]。
- sharedExpertRankNum取值范围[0, epWorldSize)；为0时需满足sharedExpertNum为0或1，不为0时需满足sharedExpertRankNum % sharedExpertNum = 0。
- epRecvCountsOut的shape为(epWorldSize * max(tpWorldSize, 1) * localExpertNum,)。
- 有TP域通信时tpRecvCountsOut为1D shape Tensor，shape为(tpWorldSize,)。
- expandScalesOut当前版本不支持该输出。
- quantMode支持0（非量化）、1（静态量化）、2（pertoken动态量化）、3（pergroup动态量化）、4（mx动态量化）。
- elasticInfoOptional当前版本不支持，传空指针即可。
- zeroExpertNum取值范围:[0, MAX_INT32)，MAX_INT32 = 2^31 - 1,合法的零专家的ID的值是[object Object][moeExpertNum, moeExpertNum + zeroExpertNum)[object Object]。
- copyExpertNum取值范围:[0, MAX_INT32)，MAX_INT32 = 2^31 - 1，专家ID范围[object Object][moeExpertNum + zeroExpertNum, moeExpertNum + zeroExpertNum + copyExpertNum)[object Object]。
- constExpertNum取值范围:[0, MAX_INT32)，MAX_INT32 = 2^31 - 1，专家ID范围[object Object][moeExpertNum + zeroExpertNum + copyExpertNum, moeExpertNum + zeroExpertNum + copyExpertNum + constExpertNum)[object Object]。
- performanceInfoOptional可选择传入有效数据或填空指针，传入空指针时表示不开启记录通信耗时功能；当传入有效数据时，要求是一个1D的Tensor，shape为(epWorldSize,)，数据类型支持int64；数据格式要求为ND。
- scalesOptional quantMode取值为0时，若[object Object]的数据类型为[object Object]或[object Object]则传空指针，若[object Object]的数据类型为[object Object]、[object Object]、[object Object]、[object Object]、[object Object]则必传有效数据；quantMode取值为1时必传有效数据；quantMode取值为2或3时可传有效数据或空指针；quantMode取值为4时传空指针。[object Object]
返回值

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

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

[object Object]

参数说明
[object Object]
返回值

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

[object Object]

确定性计算：
- aclnnMoeDistributeDispatchV4默认确定性实现。
驱动约束：
- 算子通信域各节点的驱动版本应当相同。
接口配套约束：
- [object Object]与CombineV4系列算子必须配套使用，前者输出的[object Object]、[object Object]、[object Object]、[object Object]需直接传入后者对应参数，业务逻辑不可依赖这些Tensor的具体值。
参数一致性约束：
- 所有卡的[object Object]、[object Object]、[object Object]、[object Object]、[object Object]、[object Object]、[object Object]、[object Object]、[object Object]、[object Object]参数及[object Object]取值需保持一致，且与CombineV4系列算子对应参数一致。
产品特定约束：
- [object Object]Atlas A3 训练系列产品/Atlas A3 推理系列产品[object Object]：该场景下单卡包含双DIE（简称为“晶粒”或“裸片”），因此参数说明中的“本卡”均表示单DIE。
Shape变量约束：
[object Object]undefined
quantMode相关约束：
- [object Object]Atlas A2 训练系列产品/Atlas A2 推理系列产品[object Object]：
  - [object Object]取值为0时，表示非量化场景，输入[object Object]传空指针，[object Object]的数据类型支持[object Object]、[object Object]。
  - [object Object]取值为2时，表示pertoken动态量化场景，[object Object]的数据类型支持[object Object]。
    - 输入[object Object]可传入空指针。
    - 若输入[object Object]传入有效数据时，其shape为([object Object], [object Object])。
    - 输出[object Object]shape为[object Object]
- [object Object]Atlas A3 训练系列产品/Atlas A3 推理系列产品[object Object]：
  - [object Object]取值为0时，表示非量化场景，输入[object Object]传空指针，[object Object]的数据类型支持[object Object]、[object Object]。
  - [object Object]取值为2时，表示pertoken动态量化场景，[object Object]的数据类型支持[object Object]。
    - 输入[object Object]可传入空指针。
    - 若输入[object Object]传入有效数据且存在共享专家卡时，其shape为([object Object] + [object Object], [object Object])。
    - 若输入[object Object]传入有效数据且不存在共享专家卡时，其shape为([object Object], [object Object])。
    - 输出[object Object]shape为[object Object]
- Atlas 350 加速卡：
  - [object Object]取值为0时，表示非量化场景。
    - 当[object Object]的数据类型为[object Object]或[object Object]时，[object Object]的数据类型可与[object Object]一致，也可为[object Object]，输入[object Object]必须传空指针。
    - 当[object Object]的数据类型为[object Object]、[object Object]、[object Object]、[object Object]、[object Object]时，输入[object Object]必须传入有效数据，[object Object]的数据类型与[object Object]一致。
      - [object Object]的数据类型为[object Object]时，[object Object]的数据类型为[object Object]。
      - [object Object]的数据类型为[object Object]或[object Object]时，[object Object]的数据类型为[object Object]或[object Object]。
      - [object Object]的数据类型为[object Object]或[object Object]时，[object Object]的数据类型为[object Object]，且H必须为偶数。
      - [object Object]的shape为([object Object], [object Object])，其中[object Object]需满足小于等于[object Object]。
  - [object Object]取值为1时，表示静态量化场景，[object Object]的数据类型支持[object Object]、[object Object]。
    - [object Object]的数据类型为[object Object]时有如下场景：
      - 输入的[object Object]代表量化系数，shape为(1, )；
      - 输入的[object Object]表示每个专家共享的平滑权重时，shape为([object Object]，)；
      - 输入的[object Object]代表融了每个专家的平滑权重的量化系数时，若有共享专家卡，其shape为([object Object] + [object Object], [object Object])，若无共享专家卡，其shape为([object Object], [object Object])。
    - [object Object]的数据类型为[object Object]时，[object Object]的shape必须为(1, )。
  - [object Object]取值为2时，表示pertoken动态量化场景，[object Object]的数据类型支持[object Object]、[object Object]、[object Object]。
    - 输入[object Object]可传入空指针。
    - 若输入[object Object]传入有效数据且存在共享专家卡时，其shape为([object Object] + [object Object], [object Object])。
    - 若输入[object Object]传入有效数据且不存在共享专家卡时，其shape为([object Object], [object Object])。
    - 输出[object Object]shape为[object Object]
  - [object Object]取值为3时，表示pergroup动态量化场景，expandX的数据类型支持[object Object]、[object Object]。
    - 输入[object Object]可传入空指针。
    - 若输入[object Object]传入有效数据且存在共享专家卡时，其shape为([object Object] + [object Object], [object Object])。
    - 若输入[object Object]传入有效数据且不存在共享专家卡时，其shape为([object Object], [object Object])。
    - 输出[object Object]shape为[object Object]，其中[object Object]
  - [object Object]取值为4时，表示mx量化场景，[object Object]的数据类型支持[object Object]、[object Object]、[object Object]、[object Object]，输入[object Object]必须传入空指针。输出[object Object]shape为[object Object]，其中[object Object]。当[object Object]的数据类型为[object Object]或[object Object]时，H必须为偶数。
环境变量约束：
- HCCL_BUFFSIZE：调用本接口前需检查HCCL_BUFFSIZE环境变量取值是否合理，该环境变量表示单个通信域占用内存大小，单位MB，不配置时默认为200MB。
  - [object Object]Atlas A2 训练系列产品/Atlas A2 推理系列产品[object Object]：
    - commAlg配置为""或nullptr：依照HCCL_INTRA_PCIE_ENABLE和HCCL_INTRA_ROCE_ENABLE环境变量配置，选择"fullmesh"或"hierarchy"公式。
    - commAlg配置为"fullmesh": 要求 >= 2 * (BS * epWorldSize * min(localExpertNum, K) * H * sizeof(uint16) + 2MB)。
    - commAlg配置为"hierarchy": 要求 >= ([object Object] + [object Object] / 4) * Align512([object Object] * ([object Object] * 2 + 16 * Align8([object Object]))) * 1B + 8MB，其中Align8(x) = ((x + 8 - 1) / 8) * 8，Align512(x) = ((x + 512 - 1) / 512) * 512。
  - [object Object]Atlas A3 训练系列产品/Atlas A3 推理系列产品[object Object]：
    - 当commAlg为"fullmesh_v1"或空字符串或空指针时：要求取值满足 ≥ 2 * (localExpertNum * maxBS * epWorldSize * Align512(Align32(2 * H) + 64) + (K + sharedExpertNum) * maxBS * Align512(2 * H))。
    - 当commAlg为"fullmesh_v2"时：要求取值满足 ≥ 2 * (localExpertNum * maxBS * epWorldSize * 480Align512(Align32(2 * H) + 64) + (K + sharedExpertNum) * maxBS * Align512(2 * H))。
    - 其中[object Object]，[object Object]，[object Object]。
    - 当commAlg为"hierarchy"时：要求取值满足(moeExpertNum * maxBS * (H * 2 + (3 * (K + 7) / 8 * 8)) * 4 + 64) + 404 * 1024 * 1024。
  - Atlas 350 加速卡：
    - 当commAlg为"fullmesh_v1"或空字符串或空指针时：要求取值满足 ≥ 2 * (localExpertNum * maxBS * epWorldSize * Align512(Align32(2 * H) + 64) + (K + sharedExpertNum) * maxBS * Align512(2 * H))。
    - 当commAlg为"fullmesh_v2"时：要求取值满足 ≥ 2 * (localExpertNum * maxBS * epWorldSize * 480Align512(Align32(2 * H) + 64) + (K + sharedExpertNum) * maxBS * Align512(2 * H))。
    - 其中[object Object]，[object Object]，[object Object]。
- HCCL_INTRA_PCIE_ENABLE和HCCL_INTRA_ROCE_ENABLE：
  - [object Object]Atlas A2 训练系列产品/Atlas A2 推理系列产品[object Object]：该环境变量不再推荐使用，建议commAlg配置"hierarchy"。
  - Atlas 350 加速卡：不支持该环境变量。
通信域使用约束：
- 一个模型中的CombineV4系列算子和[object Object]仅支持相同EP通信域，且该通信域中不允许有其他算子。
- 一个模型中的CombineV4系列算子和[object Object]仅支持相同TP通信域或都不支持TP通信域，有TP通信域时该通信域中不允许有其他算子。
- [object Object]Atlas A3 训练系列产品/Atlas A3 推理系列产品[object Object]：仅在commAlg配置为"hierarchy"场景下通信域支持跨超节点，其余场景要求一个通信域内的节点需在一个超节点内，不支持跨超节点。
组网约束：
- [object Object]Atlas A2 训练系列产品/Atlas A2 推理系列产品[object Object]：多机场景仅支持交换机组网，不支持双机直连组网。
其他约束：
- 公式中的“/”表示整除。
- [object Object]moeExpertNum + zeroExpertNum + copyExpertNum + constExpertNum < MAX_INT32[object Object]。

[object Object]

[object Object]Atlas A2 训练系列产品/Atlas A2 推理系列产品[object Object] ：

本示例支持A2算子运行在卡数为[2, 8]的单机环境中，用户可以根据需要在示例代码中设置EP_WORLD_SIZE_A2为卡数，并更改moeExpertNum，使得moeExpertNum可以被EP_WORLD_SIZE_A2整除。
- 编译算子：算子编译命令如下，moe_distribute_dispatch_v2和moe_distribute_combine_v2算子都需要编译，这两个算子需要成对执行。
  
  [object Object]
- 创建A2示例代码：编译完成后请在算子目录下参考已有文件，用A2示例代码新建测试文件test_aclnn_moe_distribute_dispatch_v4.cpp。
- 执行算子样例：示例算子执行命令如下，该命令会执行算子目录下所有的示例代码文件。
  
  [object Object]
- A2示例代码：
  
  [object Object]
Atlas 350 加速卡：请参考中调用示例的准备部分和示例代码，按照上文的约束说明重新设置涉及的变量，V3接口相较于V2接口新增的场景参数按上述参数说明传值即可。
[object Object]Atlas A3 训练系列产品/Atlas A3 推理系列产品[object Object]：

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

[object Object]