aclnnMoeDistributeCombineV4

产品支持情况

[object Object]undefined

功能说明

• 接口功能：当存在TP域通信时，先进行ReduceScatterV通信，再进行AllToAllV通信，最后将接收的数据整合（乘权重再相加）；当不存在TP域通信时，进行AllToAllV通信，最后将接收的数据整合（乘权重再相加）。

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

  新增采集通信耗时功能，记录每张卡的通信时间，通过传入[object Object]参数使能该特性。该功能推荐结合工具使用。单次算子调用各卡通信耗时会累加到该Tensor上，用户使用前按需清零。

• 计算公式：

$$rsOut = ReduceScatterV(expandX)\\ ataOut = AllToAllV(rsOut)\\ xOut = Sum(expertScales * ataOut + expertScales * sharedExpertX)$$

注意：该接口必须与[object Object]配套使用，相当于按[object Object]接口收集数据的路径原路返还。

函数原型

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

aclnnMoeDistributeCombineV4GetWorkspaceSize

• 参数说明

  [object Object]

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

    • commAlg 支持nullptr、""、"fullmesh"、"hierarchy"；推荐配置"hierarchy"并搭配≥25.0.RC1.1版本驱动；nullptr和""依HCCL环境变量选择算法（不推荐）；"fullmesh"通过RDMA直传token；"hierarchy"经机内、跨机两次发送减少跨机数据量。
    • 不支持共享专家场景。
    • epSendCounts 的shape为 (moeExpertNum + 2 * globalBs * K * serverNum, )，其中K指topK个专家数，前moeExpertNum个数表示从EP通信域各卡接收的token数，后2 * globalBs * K * serverNum个数用于存储机间/机内通信前，combine可提前做reduce的token个数和通信区偏移，globalBs=0时按Bs * epWorldSize计算。
    • 当前不支持TP域通信。
    • xActiveMaskOptional 依commAlg取值，"fullmesh"要求为1D Tensor，shape为(Bs, )；true需排在false前（例：{true, false, true}非法）；"hierarchy"当前版本不支持，传空指针即可。
    • exapndScalesOptional 要求为1D Tensor，shape为 (A, )。
    • sharedExpertXOptional 为预留参数，当前版本不支持，传空指针即可。
    • epWorldSize 依commAlg取值，"fullmesh"支持16、32、64、128、192、256；"hierarchy"支持16、32、64。
    • moeExpertNum 取值范围(0, 512]，还需满足moeExpertNum / (epWorldSize - sharedExpertRankNum) <= 24。
    • groupTp 当前版本不支持，传空字符即可。
    • tpWorldSize 当前版本不支持，传0即可。
    • tpRankId 当前版本不支持，传0即可。
    • expertShardType 当前版本不支持，传0即可。
    • sharedExpertNum 当前版本不支持，传0即可。
    • sharedExpertRankNum 当前版本不支持，传0即可。
    • commQuantMode 取值范围0或2（0表示不量化，2表示int8量化），取值为2仅当commAlg为"hierarchy"或HCCL_INTRA_PCIE_ENABLE=1且HCCL_INTRA_ROCE_ENABLE=0且驱动版本≥25.0.RC1.1时支持。
    • expandScalesOptional 要求是一个1D的Tensor。
    • elasticInfoOptional 当前版本不支持，传空指针即可。
    • oriXOptional 当commAlg="hierarchy"时，当前版本不支持，传空指针即可。
    • constExpertAlpha1Optional 预留参数，当前版本不支持，传空指针即可。
    • constExpertAlpha2Optional 预留参数，当前版本不支持，传空指针即可。
    • constExpertVOptional 预留参数，当前版本不支持，传空指针即可。
    • 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为(ep_world_size,)，数据类型支持int64；数据格式要求为ND。

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

    • commAlg 当前版本不支持，传空指针即可。
    • epSendCounts 的shape为 (epWorldSize * max(tpWorldSize, 1) * localExpertNum, )。
    • 有TP域通信时 tpSendCountsOptional 为1D Tensor，shape为 (tpWorldSize, )。
    • xActiveMaskOptional 要求为1D或2D Tensor（1D时shape为(BS, )，2D时shape为(BS, K)）；1D时true需排在false前，2D时token对应K个值全为false则不参与通信。
    • exapndScalesOptional 预留参数，当前版本不支持，传空指针即可。
    • sharedExpertXOptional 要求为2D或3D Tensor（2D时shape为 (Bs, H)；3D时前两位乘积等于Bs、第三维等于H）；可传或不传，传入时sharedExpertRankNum需为0。
    • epWorldSize 取值支持[2, 768]。
    • moeExpertNum 取值范围(0, 1024]。
    • 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。
    • commQuantMode 取值范围0或2（0表示不量化，2表示int8量化），取值为2仅当tpWorldSize < 2时可使能。
    • expandScalesOptional 预留参数，当前版本不支持，传空指针即可。
    • elasticInfoOptional 可选择传入有效数据或传空指针，传入空指针时表示不使能动态缩容功能；当传入有效数据时，要求是一个1D的Tensor，shape为 [object Object](4 + 2 * epWorldSize, )[object Object]。Tensor中的前四个数字分别表示（是否缩容，缩容后实际rank数，缩容后共享专家使用的rank数，缩容后moe专家的个数），后2 * epWorldSize表示2个rank映射表，缩容后本卡中因部分rank异常而从EP通信域中剔除，第一个Table的映射关系为[object Object]Table1[epRankId]=localEpRankId或-1[object Object]，localEpRankId表示新EP通信域中的rank Index，-1表示epRankId这张卡从通信域中被剔除，第二个Table映射关系为[object Object]Table2[localEpRankId] = epRankId[object Object]。
    • constExpertAlpha1Optional 可选择传入有效数据或传空指针，当constExpertNum不为0时必须传入有效输入；当传入有效数据时，要求是一个2D的Tensor，shape为[object Object](constExpertNum, H)[object Object]，数据类型需跟expandX保持一致。
    • constExpertAlpha2Optional 可选择传入有效数据或传空指针，当constExpertNum不为0时必须传入有效输入；当传入有效数据时，要求是一个2D的Tensor，shape为[object Object](constExpertNum, H)[object Object]，数据类型需跟expandX保持一致。
    • constExpertVOptional 可选择传入有效数据或传空指针，当constExpertNum不为0时必须传入有效输入；当传入有效数据时，要求是一个2D的Tensor，shape为 [object Object](constExpertNum, H)[object Object]，数据类型需跟expandX保持一致。
    • zeroExpertNum 取值范围:[0, MAX_INT32)，MAX_INT32 = 2^31 - 1，合法的零专家的ID的值是[[object Object]moeExpertNum[object Object], [object Object]moeExpertNum + zeroExpertNum[object Object])。
    • copyExpertNum 取值范围:[0, MAX_INT32)，MAX_INT32 = 2^31 - 1，合法的拷贝专家的ID的值是[[object Object]moeExpertNum + zeroExpertNum[object Object], [object Object]moeExpertNum + zeroExpertNum + copyExpertNum[object Object])。
    • constExpertNum 取值范围:[0, MAX_INT32)，MAX_INT32 = 2^31 - 1, 合法的常量专家的ID的值是[[object Object]moeExpertNum + zeroExpertNum + copyExpertNum[object Object], [object Object]moeExpertNum + zeroExpertNum + copyExpertNum + constExpertNum[object Object])。
    • performanceInfoOptional 预留参数，当前版本不支持，传空指针即可。

• 返回值：

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

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

  [object Object]

aclnnMoeDistributeCombineV4

• 参数说明

  [object Object]

• 返回值

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

约束说明

• 确定性计算：

  • aclnnMoeDistributeCombineV4默认确定性实现。

• 接口配套约束：

  • [object Object]与[object Object]必须配套使用，前者输出的[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]取值需保持一致，且与[object Object]对应参数一致。
  • 动态缩容后的部署信息通过[object Object]参数传递给算子，无需修改其他参数。动态缩容后，MOE专家卡上的本卡部署MOE专家数需与缩容前保持一致，不支持缩容后无MOE专家卡。

• 产品特定约束：

  • [object Object]Atlas A3 训练系列产品/Atlas A3 推理系列产品[object Object]：单卡包含双DIE（晶粒/裸片），参数说明中的“本卡”均指单DIE。
  • 动态缩容功能不支持在TP并行场景下使能，即仅在 [object Object] 取值为 1 时生效。

• Shape变量约束：

  [object Object]undefined

• 环境变量约束：

  • 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": 设置大小要求 >= moeExpertNum * Bs * (H * sizeof(dtypeX) + 4 * ((K + 7) / 8 * 8) * sizeof(uint32)) + 4MB + 100MB，不要求moeExpertNum / (epWorldSize - sharedExpertRankNum) <= 24。
    • [object Object]Atlas A3 训练系列产品/Atlas A3 推理系列产品[object Object]：
      • ep通信域内，当commAlg为"fullmesh_v1"或空字符串或空指针时：设置大小要求取值满足 ≥ 2 * (localExpertNum * maxBs * epWorldSize * Align512(Align32(2 * H) + 64) + (K + sharedExpertNum) * maxBs * Align512(2 * H))。
      • ep通信域内，当commAlg为"fullmesh_v2"时：设置大小要求取值满足 ≥ 2 * (localExpertNum * maxBs * epWorldSize * 480Align512(Align32(2 * H) + 64) + (K + sharedExpertNum) * maxBs * Align512(2 * H))。
      • tp通信域内：设置大小要求 >= (A * Align512(Align32(h * 2) + 44) + A * Align512(h * 2)) * 2。
      • 其中[object Object]，[object Object]，[object Object]。

  • HCCL_INTRA_PCIE_ENABLE/HCCL_INTRA_ROCE_ENABLE：

    • [object Object]Atlas A2 训练系列产品/Atlas A2 推理系列产品[object Object]：该环境变量不再推荐使用，建议commAlg配置"hierarchy"。

• 通信域使用约束：

  • 一个模型中的[object Object]和[object Object]仅支持相同EP通信域，且该通信域中不允许有其他算子。
  • 一个模型中的[object Object]和[object Object]仅支持相同TP通信域或都不支持TP通信域；有TP通信域时，该通信域中不允许有其他算子。
  • [object Object]Atlas A3 训练系列产品/Atlas A3 推理系列产品[object Object]：一个通信域内的节点需在一个超节点内，不支持跨超节点。

• 组网约束：

  • [object Object]Atlas A2 训练系列产品/Atlas A2 推理系列产品[object Object]：多机场景仅支持交换机组网，不支持双机直连组网。

• 其他约束：

  • 公式中的“/”表示整除。
  • [object Object]moeExpertNum + zeroExpertNum + copyExpertNum + constExpertNum < MAX_INT32[object Object]。

调用示例

[object Object]Atlas A2 训练系列产品/Atlas A2 推理系列产品[object Object]：类似下文[object Object]Atlas A3 训练系列产品/Atlas A3 推理系列产品[object Object]调用示例，其中V4接口相较于V3接口新增的场景参数按上述参数说明传值即可。

[object Object]Atlas A3 训练系列产品/Atlas A3 推理系列产品[object Object]：示例代码如下，仅供参考，调起aclnnMoeDistributeCombineV4和aclnnMoeDistributeDispatchV4接口。本示例代码仅支持Atlas A3。

• 文件准备： 1.新建combineDemo目录，按照下方指导在combineDemo下新建aclnnCombineDemo.cpp，buildCombine.sh，文件并参考如下代码修改。

  2.安装cann包，并根据下方指导编译运行combineDemo。

• 编译脚本

  [object Object]

• 编译与运行：

  [object Object]

• 示例代码如下，仅供参考

  [object Object]