MoeDistributeCombineV2

产品支持情况

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

功能说明

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

  相较于MoeDistributeCombine算子，该算子变更如下：

  • 输入了更详细的token信息辅助MoeDistributeCombineV2高效地进行全卡同步，因此原算子中shape为(BS * K,)的expandIdx入参替换为shape为(A * 128,)的assistInfoForCombine参数；
  • 新增sharedExpertXOptional入参，支持在sharedExpertNum为0时，由用户输入共享专家计算后的token；
  • 新增commAlg入参，代替HCCL_INTRA_PCIE_ENABLE和HCCL_INTRA_ROCE_ENABLE环境变量。 详细说明请参考以下参数说明。

• 计算公式：

  • 不存在TP域通信时：

  $$\begin{gathered} ataOut=AllToAllV(expandX) \\ xOut=Sum(expertScales\ast ataOut+expertScales\ast sharedExpertX) \end{gathered}$$

  • 存在TP域通信时：

  $$\begin{gathered} rsOut=ReduceScatterV(expandX) \\ ataOut=AllToAllV(rsOut) \\ xOut=Sum(expertScales\ast ataOut+expertScales\ast sharedExpertX) \end{gathered}$$

  注意该算子必须与MoeDistributeDispatchV2配套使用，相当于按MoeDistributeDispatchV2算子收集数据的路径原路返还。

参数说明

参数名	输入/输出/属性	描述	数据类型	数据格式
expandX	输入	根据expertIds进行扩展过的token特征。	FLOAT16、BFLOAT16	ND
expertIds	输入	每个token的topK个专家索引。	INT32	ND
assistInfoForCombine	输入	表示同一专家收到的token个数，对应MoeDistributeDispatchV2中的assistInfoForCombineOut输出。	INT32	ND
epSendCounts	输入	从EP通信域各卡接收的token数，对应MoeDistributeDispatchV2中的epRecvCounts输出。	INT32	ND
expertScales	输入	每个token的topK个专家的权重。	FLOAT32	ND
tpSendCountsOptional	可选输入	从TP通信域各卡接收的token数，对应MoeDistributeDispatchV2中的tpRecvCounts输出，有TP域通信需传参，无TP域通信传空指针。	INT32	ND
xActiveMaskOptional	可选输入	表示token是否参与通信，可传有效数据或空指针；1D时true需排在false前（例：{true, false, true}非法），2D时token对应K个值全为false则不参与通信；默认所有token参与通信；各卡BS不一致时所有token需有效。	BOOL	ND
activationScaleOptional	可选输入	预留参数，当前版本不支持，传空指针即可。	-	ND
weightScaleOptional	可选输入	预留参数，当前版本不支持，传空指针即可。	-	ND
groupListOptional	可选输入	预留参数，当前版本不支持，传空指针即可。	-	ND
expandScalesOptional	可选输入	表示本卡token的权重，对应MoeDistributeDispatchV2中的expandScales输出。	FLOAT32	ND
sharedExpertXOptional	可选输入	表示共享专家计算后的token，数据类型需与expandX一致。	FLOAT16、BFLOAT16	ND
elasticInfoOptional	可选输入	EP通信域动态缩容信息。	INT32	ND
oriXOptional	可选输入	表示未经过FFN（Feed-Forward Neural network）的token数据，在使能copyExpert或使能constExpert的场景下需要本输入数据。	FLOAT16、BFLOAT16	ND
constExpertAlpha1Optional	可选输入	在使能constExpert的场景下需要输入的计算系数。	FLOAT16、BFLOAT16	ND
constExpertAlpha2Optional	可选输入	在使能constExpert的场景下需要输入的计算系数。	FLOAT16、BFLOAT16	ND
constExpertVOptional	可选输入	在使能constExpert的场景下需要输入的计算系数。	FLOAT16、BFLOAT16	ND
performanceInfoOptional	可选输入	表示本卡等待各卡数据的通信时间，单位为us（微秒）。单次算子调用各卡通信耗时会累加到该Tensor上，算子内部不进行自动清零，因此用户每次启用此Tensor开始记录耗时前需对Tensor清零。	INT64	ND
groupEp	属性	EP通信域名称（专家并行通信域），字符串长度范围为[1, 128)，不能和groupTp相同。	STRING	ND
epWorldSize	属性	EP通信域大小。	INT64	ND
epRankId	属性	EP域本卡ID，取值范围[0, epWorldSize)，同一个EP通信域中各卡的epRankId不重复。	INT64	ND
moeExpertNum	属性	MoE专家数量，满足moeExpertNum % (epWorldSize - sharedExpertRankNum) = 0。	INT64	ND
groupTp	可选属性	TP通信域名称（数据并行通信域）。 默认值为""。	STRING	ND
tpWorldSize	可选属性	TP通信域大小。 默认值为0。	INT64	ND
tpRankId	可选属性	TP域本卡ID，无TP域通信时传0即可。 默认值为0。	INT64	ND
expertShardType	可选属性	表示共享专家卡分布类型，当前仅支持传0，表示共享专家卡排在MoE专家卡前面。 默认值为0。	INT64	ND
sharedExpertNum	可选属性	表示共享专家数量（一个共享专家可复制部署到多个卡上）。 默认值为1。	INT64	ND
sharedExpertRankNum	可选属性	表示共享专家卡数量，取值范围[0, epWorldSize)；为0时需满足sharedExpertNum为0或1，不为0时需满足sharedExpertRankNum % sharedExpertNum = 0。 默认值为0。	INT64	ND
globalBS	可选属性	EP域全局的batch size大小；各rank BS一致时，globalBS = BS * epWorldSize 或 0；各rank BS不一致时，globalBS = maxBS * epWorldSize（maxBS为单卡BS最大值）。 默认值为0。	INT64	ND
outDtype	可选属性	用于指定输出x的数据类型，预留参数，当前版本不支持，传0即可。 默认值为0。	INT64	ND
commQuantMode	可选属性	通信量化类型，取值范围0或2；0表示通信不量化，2表示通信int8量化。 默认值为0。	INT64	ND
groupListType	可选属性	groupList格式，预留参数，当前版本不支持，传0即可。 默认值为0。	INT64	ND
commAlg	可选属性	表示通信亲和内存布局算法。 默认值为""。	STRING	ND
zeroExpertNum	可选属性	零专家数量。 默认值为0。	INT64	ND
copyExpertNum	可选属性	copy专家数量。 默认值为0。	INT64	ND
constExpertNum	可选属性	常量专家数量。 默认值为0。	INT64	ND
xOut	输出	表示处理后的token，数据类型、数据格式与expandX保持一致。	FLOAT16、BFLOAT16	ND

• Atlas A2 训练系列产品/Atlas A2 推理系列产品：
  • 不支持共享专家场景，不支持expertShardType、sharedExpertNum、sharedExpertRankNum、sharedExpertXOptional。
  • 仅支持EP域，无TP域，不支持groupTp、tpWorldSize、tpRankId属性，且tpRecvCounts输出为无效内容。
  • 不支持动态缩容场景，不支持elasticInfoOptional。
  • 当commAlg = "hierarchy"，必须传入expandScalesOptional。
  • 不支持常量专家场景，不支持constExpertNum、constExpertAlpha1Optional、constExpertAlpha2Optional和constExpertVOptional，使用默认值即可。

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

  • 当commAlg = "hierarchy"，必须传入expandScalesOptional。
  • 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场景。
  • epWorldSize 取值范围[2, 768]；当commAlg="hierarchy"场景时，取值范围为[16, 256]，且为16的整数倍。
  • moeExpertNum 取值范围(0, 1024]；当commAlg="hierarchy"场景时，取值范围为(0, 512]。

• Ascend 950PR/Ascend 950DT：

  • 不支持expandScalesOptional。
  • 不支持commAlg。
  • 仅支持EP域，无TP域，不支持groupTp、tpWorldSize、tpRankId属性，且tpRecvCounts输出为无效内容。

约束说明

• MoeDistributeDispatchV2与CombineV2系列算子必须配套使用，具体参考调用示例。

• 算子通信域各节点的驱动版本应当相同。

• 在不同产品型号、不同通信算法或不同版本中，MoeDistributeDispatchV2的Tensor输出assistInfoForCombineOut、epRecvCountsOut、tpRecvCountsOut、expandScalesOut中的元素值可能不同，使用时直接将上述Tensor传给CombineV2系列算子对应参数即可，模型其他业务逻辑不应对其存在依赖。

• 调用算子过程中使用的groupEp、epWorldSize、moeExpertNum、groupTp、tpWorldSize、expertShardType、sharedExpertNum、sharedExpertRankNum、globalBS、commAlg参数，HCCL_BUFFSIZE取值所有卡需保持一致，网络中不同层中也需保持一致，且和MoeDistributeDispatchV2算子对应参数也保持一致。

• 参数说明里shape格式说明：

  • A：表示本卡可能接收的最大token数量，取值范围如下：
    • 对于共享专家，要满足A = BS * epWorldSize * sharedExpertNum / sharedExpertRankNum。
    • 对于MoE专家，当globalBS为0时，要满足A >= BS * epWorldSize * min(localExpertNum, K)；当globalBS非0时，要满足A >= globalBS * min(localExpertNum, K)。
  • K：表示选取topK个专家，取值范围为0 < K ≤ 16同时满足0 < K ≤ moeExpertNum + zeroExpertNum + copyExpertNum + constExpertNum。
  • localExpertNum：表示本卡专家数量。
    • 对于共享专家卡，localExpertNum = 1
    • 对于MoE专家卡，localExpertNum = moeExpertNum / (epWorldSize - sharedExpertRankNum)，localExpertNum > 1时，不支持TP域通信。

• 参数约束：

  • zeroExpertNum：取值范围：[0, MAX_INT32)，MAX_INT32 = 2^31 - 1, 合法的零专家的ID的值是[moeExpertNum, moeExpertNum + zeroExpertNum)。
  • copyExpertNum：取值范围：[0, MAX_INT32)，MAX_INT32 = 2^31 - 1, 合法的copy专家的ID的值是[moeExpertNum + zeroExpertNum, moeExpertNum + zeroExpertNum + copyExpertNum)。
  • constExpertNum：取值范围：[0, MAX_INT32)，MAX_INT32 = 2^31 - 1, 合法的常量专家的ID的值是[moeExpertNum + zeroExpertNum + copyExpertNum, moeExpertNum + zeroExpertNum + copyExpertNum + constExpertNum)。
  • oriXOptional：可选择传入有效数据或填空指针，当copyExpertNum不为0或constExpertNum不为0时必须传入有效输入；当传入有效数据时，要求shape为 (BS, H)，数据类型需与expandX保持一致。
  • constExpertAlpha1Optional：可选择传入有效数据或填空指针，当constExpertNum不为0或constExpertNum不为0时必须传入有效输入；当传入有效数据时，要求shape为(constExpertNum, )，数据类型需与expandX保持一致。
  • constExpertAlpha2Optional：可选择传入有效数据或填空指针，当constExpertNum不为0或constExpertNum不为0时必须传入有效输入；当传入有效数据时，要求shape为(constExpertNum, )，数据类型需与expandX保持一致。
  • constExpertVOptional：可选择传入有效数据或填空指针，当constExpertNum不为0或constExpertNum不为0时必须传入有效输入；当传入有效数据时，要求shape为(constExpertNum, H)，数据类型需与expandX保持一致。

• 本文公式中的"/"表示整除。

• 通信域使用约束：

  • 一个模型中的MoeDistributeCombineV2和MoeDistributeDispatchV2仅支持相同EP通信域，且该通信域中不允许有其他算子。
  • 一个模型中的MoeDistributeCombineV2和MoeDistributeDispatchV2仅支持相同TP通信域或都不支持TP通信域，有TP通信域时该通信域中不允许有其他算子。

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

  • commAlg：当前版本支持nullptr， ""， "fullmesh"， "hierarchy"四种输入方式，若配置"hierarchy"，建议搭配25.0.RC1.1及以上版本驱动使用。
    • nullptr和""：仅在此场景下，HCCL_INTRA_PCIE_ENABLE和HCCL_INTRA_ROCE_ENABLE配置生效。当HCCL_INTRA_PCIE_ENABLE=1&&HCCL_INTRA_ROCE_ENABLE=0时，调用"hierarchy"算法，否则调用"fullmesh"算法。不推荐使用该方式。
    • "fullmesh"：token数据直接通过RDMA方式发往topk个目标专家所在的卡。
    • "hierarchy"：token数据经过跨机、机内两次发送，仅不同server同号卡之间使用RDMA通信，server内使用HCCS通信。
  • HCCL_INTRA_PCIE_ENABLE和HCCL_INTRA_ROCE_ENABLE：不推荐使用该环境变量控制通信算法，原HCCL_INTRA_PCIE_ENABLE=1&&HCCL_INTRA_ROCE_ENABLE=0场景，下文均通过commAlg="hierarchy"替代，默认场景使用commAlg="fullmesh"替代。
  • commAlg = "hierarchy"时，不支持xActiveMaskOptional、oriXOptional、zeroExpertNum、copyExpertNum。
  • 参数说明里shape格式说明：
    • H：表示hidden size隐藏层大小，取值范围(0, 10240]且为32的整数倍。
    • BS：表示batch sequence size，即本卡最终输出的token数量。
      • commAlg = "fullmesh"：取值范围为[1, 256]。
      • commAlg = "hierarchy"：取值范围为[1, 512]。
    • performanceInfoOptional：可选择传入有效数据或填空指针，传入空指针时表示不使能记录通信耗时功能；当传入有效数据时，要求是一个1D的Tensor，shape为(ep_world_size,)，数据类型支持int64；数据格式要求为ND。
  • 属性约束：
    • 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]。
    • commQuantMode：2，开启通信int8量化，仅当commAlg = "hierarchy"且驱动版本不低于25.0.RC1.1时支持。
  • HCCL_BUFFSIZE：调用本算子前需检查HCCL_BUFFSIZE环境变量取值是否合理，该环境变量表示单个通信域占用内存大小，单位MB，不配置时默认为200MB。
    • commAlg = "fullmesh"：要求 >= (BS * epWorldSize * min(localExpertNum, K) * H * 4B + 4MB)。
    • commAlg = "hierarchy"：要求 >= (moeExpertNum + epWorldSize / 4) * Align512(maxBS * (H * 2 + 16 * Align8(K))) * 1B + 8MB，其中Align8(x) = ((x + 8 - 1) / 8) * 8，Align512(x) = ((x + 512 - 1) / 512) * 512。

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

  • 该场景下单卡包含双DIE（简称为“晶粒”或“裸片”），因此参数说明里的“本卡”均表示单DIE。
  • 参数说明里shape格式说明：
    • H：表示hidden size隐藏层大小，取值范围[1024, 8192]。
    • BS：表示batch sequence size，即本卡最终输出的token数量，取值范围为[1, 512]。
  • 参数约束：
    • epWorldSize：取值支持8、16、32、64、128、144、256、288。
    • moeExpertNum：取值范围(0, 1024]。
    • groupTp：字符串长度范围为[1, 128)，不能和groupEp相同。
    • tpWorldSize：取值范围[0, 2]，0和1表示无TP域通信，有TP域通信时仅支持2。
    • tpRankId：取值范围[0, 1]，同一个TP通信域中各卡的tpRankId不重复。无TP域通信时，传0即可。
    • sharedExpertNum：当前取值范围[0, 4]。
    • commQuantMode：int8量化当且仅当tpWorldSize < 2时可使能。
    • performanceInfoOptional：预留参数，当前版本不支持，传空指针即可。
    • commAlg：当前支持""，"hierarchy"两种输入方式。
      • ""：默认值，使能通信域不跨超模板。
      • "hierarchy": 使能ROCE分层直驱能力，需要根据不同的逻辑超节点设置环境变量HCCL_LOGIC_SUPERPOD_ID，例如两机分别设为export HCCL_LOGIC_SUPERPOD_ID=0和export HCCL_LOGIC_SUPERPOD_ID=1。
  • HCCL_BUFFSIZE：调用本算子前需检查HCCL_BUFFSIZE环境变量取值是否合理，该环境变量表示单个通信域占用内存大小，单位MB，不配置时默认为200MB。要求 >= 2且满足>= 2 * (localExpertNum * maxBS * epWorldSize * Align512(Align32(2 * H) + 64) + (K + sharedExpertNum) * maxBS * Align512(2 * H))，localExpertNum需使用MoE专家卡的本卡专家数，其中Align512(x) = ((x + 512 - 1) / 512) * 512，Align32(x) = ((x + 32 - 1) / 32) * 32。

• Ascend 950PR/Ascend 950DT：

  • 参数说明里shape格式说明：
    • H：表示hidden size隐藏层大小，取值范围[1024, 8192]。
    • BS：表示batch sequence size，即本卡最终输出的token数量，依commAlg取值，"fullmesh_v2"和"hierarchy"取值范围为 (0 < BS ≤ 256), "fullmesh_v1"和""取值范围为 (0 < BS ≤ 512)。
  • 参数约束：
    • 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。
    • commQuantMode取值范围0或2（0表示不量化，2表示int8量化）。
    • performanceInfoOptional：预留参数，当前版本不支持，传空指针即可。
  • HCCL_BUFFSIZE：调用本算子前需检查HCCL_BUFFSIZE环境变量取值是否合理，该环境变量表示单个通信域占用内存大小，单位MB，不配置时默认为200MB。要求 >= 2且满足>= 2 * (localExpertNum * maxBS * epWorldSize * Align512(Align32(2 * H) + 64) + (K + sharedExpertNum) * maxBS * Align512(2 * H))，localExpertNum需使用MoE专家卡的本卡专家数，其中Align512(x) = ((x + 512 - 1) / 512) * 512，Align32(x) = ((x + 32 - 1) / 32) * 32。

调用说明

调用方式	样例代码	说明
aclnn接口	test_aclnn_moe_distribute_combine_v2.cpp	通过aclnnMoeDistributeCombineV2接口方式调用moe_distribute_combine_v2算子。