aclnnMoeDistributeDispatchV2

产品支持情况

产品	是否支持
[object Object]Atlas A3 训练系列产品/Atlas A3 推理系列产品[object Object]	√
[object Object]Atlas A2 训练系列产品/Atlas 800I A2 推理产品/A200I A2 Box 异构组件[object Object]	√
[object Object]Atlas 200I/500 A2 推理产品[object Object]	×
[object Object]Atlas 推理系列产品 [object Object]	×
[object Object]Atlas 训练系列产品[object Object]	×

功能说明

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

$$agOut = AllGatherV(X)\\ expandXOut = AllToAllV(agOut)\\$$

• [object Object]Atlas A2 训练系列产品/Atlas 800I A2 推理产品/A200I A2 Box 异构组件[object Object]：该接口必须与aclnnMoeDistributeCombineV2配套使用。
• [object Object]Atlas A3 训练系列产品/Atlas A3 推理系列产品[object Object]：该接口必须与aclnnMoeDistributeCombineV2或aclnnMoeDistributeCombineAddRmsNorm配套使用。

说明：

aclnnMoeDistributeCombineV2、aclnnMoeDistributeCombineAddRmsNorm算子在后续文档中统称为CombineV2系列算子。

相较于aclnnMoeDistributeDispatch接口，该接口变更如下：

• 输出了更详细的token信息辅助CombineV2系列算子高效地进行全卡同步，因此原接口中shape为(Bs * K,)的expandIdx出参替换为shape为(A * 128,)的assistInfoForCombineOut参数；
• 新增commAlg入参，代替HCCL_INTRA_PCIE_ENABLE和HCCL_INTRA_ROCE_ENABLE环境变量。

详细说明请参考以下参数说明。

函数原型

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

• aclnnStatus aclnnMoeDistributeDispatchV2GetWorkspaceSize(const aclTensor* x, const aclTensor* expertIds, const aclTensor* scalesOptional, const aclTensor* xActiveMaskOptional, const aclTensor* expertScalesOptional, const char* groupEp, int64_t epWorldSize, int64_t epRankId, int64_t moeExpertNum, const char* groupTp, int64_t tpWorldSize, int64_t tpRankId, int64_t expertShardType, int64_t sharedExpertNum, int64_t sharedExpertRankNum, int64_t quantMode, int64_t globalBs, int64_t expertTokenNumsType, const char* commAlg, aclTensor* expandXOut, aclTensor* dynamicScalesOut, aclTensor* assistInfoForCombineOut, aclTensor* expertTokenNumsOut, aclTensor* epRecvCountsOut, aclTensor* tpRecvCountsOut, aclTensor* expandScalesOut, uint64_t* workspaceSize, aclOpExecutor** executor)
• aclnnStatus aclnnMoeDistributeDispatchV2(void *workspace, uint64_t workspaceSize, aclOpExecutor *executor, aclrtStream stream)

aclnnMoeDistributeDispatchV2GetWorkspaceSize

• 参数说明：

  • x（aclTensor*，计算输入）：表示本卡发送的token数据，Device侧的aclTensor。要求为一个2D的Tensor，shape为 (Bs, H)，其中Bs为batch size，H为hidden size，即隐藏层大小，数据类型支持FLOAT16、BFLOAT16，undefined要求为ND，支持undefined。
  • expertIds（aclTensor*，计算输入）：每个token的topK个专家索引，Device侧的aclTensor，要求为一个2D的Tensor，shape为 (Bs, K)。数据类型支持INT32，undefined要求为ND，支持undefined
  • scalesOptional（aclTensor*，计算输入）：每个专家的量化平滑参数，Device侧的aclTensor，要求是一个2D的Tensor，shape (sharedExpertNum + moeExpertNum, H)。非量化场景传空指针，动态量化可选择传入有效数据或传入空指针。数据类型支持FLOAT32，undefined要求为ND，支持undefined。
    • [object Object]Atlas A2 训练系列产品/Atlas 800I A2 推理产品/A200I A2 Box 异构组件[object Object]：当commAlg配置为"hierarchy"或配置HCCL_INTRA_PCIE_ENABLE=1&&HCCL_INTRA_ROCE_ENABLE=0时，要求传nullptr。
    • [object Object]Atlas A3 训练系列产品/Atlas A3 推理系列产品[object Object]：无特殊要求。
  • xActiveMaskOptional（aclTensor*，计算输入）：表示token是否参与通信，Device侧的aclTensor。
    • [object Object]Atlas A2 训练系列产品/Atlas 800I A2 推理产品/A200I A2 Box 异构组件[object Object]：当前版本不支持，传空指针即可。
    • [object Object]Atlas A3 训练系列产品/Atlas A3 推理系列产品[object Object]：要求是一个1D或者2D Tensor。当输入为1D时，shape为(BS, ); 当输入为2D时，shape为(BS, K)。数据类型支持BOOL；可选择传入有效数据或传入空指针。当输入为1D时，参数为true表示对应的token参与通信，true必须排到false之前，例：{true, false, true} 为非法输入；当输入为2D时，参数为true表示当前token对应的expert_x参与通信，全false的token之后不能出现true，例：{{false, false, false}, {true, false, false}} 为非法输入。 默认所有token都会参与通信。当每张卡的BS数量不一致时，所有token必须全部有效。undefined要求为ND，支持undefined。
  • expertScalesOptional（aclTensor*，计算输入）：每个token的topK个专家权重，Device侧的aclTensor。
    • [object Object]Atlas A2 训练系列产品/Atlas 800I A2 推理产品/A200I A2 Box 异构组件[object Object]：要求是一个2D的shape (Bs, K)。数据类型支持FLOAT32，undefined要求为ND，支持undefined。
    • [object Object]Atlas A3 训练系列产品/Atlas A3 推理系列产品[object Object]：当前版本不支持，传空指针即可。
  • groupEp（char*，计算输入）：EP通信域名称，专家并行的通信域，string数据类型。字符串长度范围为[1, 128)，不能和groupTp相同。
  • epWorldSize（int64_t，计算输入）：EP通信域size，数据类型支持INT64。
    • [object Object]Atlas A2 训练系列产品/Atlas 800I A2 推理产品/A200I A2 Box 异构组件[object Object]：取值支持16、32、64。
    • [object Object]Atlas A3 训练系列产品/Atlas A3 推理系列产品[object Object]：取值区间[2, 768]。
  • epRankId（int64_t，计算输入）: EP域本卡Id，数据类型支持INT64，取值范围[0, epWorldSize)。同一个EP通信域中各卡的epRankId不重复。
  • moeExpertNum（int64_t，计算输入）: MoE专家数量，数据类型支持INT64，并且满足moeExpertNum % (epWorldSize - sharedExpertRankNum) = 0。
    • [object Object]Atlas A2 训练系列产品/Atlas 800I A2 推理产品/A200I A2 Box 异构组件[object Object]: 取值范围(0, 512], 还需满足moeExpertNum / (epWorldSize - sharedExpertRankNum) <= 24。
    • [object Object]Atlas A3 训练系列产品/Atlas A3 推理系列产品[object Object]：取值范围(0, 1024], 还需满足moeExpertNum / (epWorldSize - sharedExpertRankNum) * epWorldSize <= 1280。
  • groupTp（char*，计算输入）：TP通信域名称，数据并行的通信域，string数据类型。
    • [object Object]Atlas A2 训练系列产品/Atlas 800I A2 推理产品/A200I A2 Box 异构组件[object Object]：当前版本不支持，传空字符即可。
    • [object Object]Atlas A3 训练系列产品/Atlas A3 推理系列产品[object Object]：字符串长度范围为[1, 128)，不能和groupEp相同。
  • tpWorldSize（int64_t，计算输入）：TP通信域size，int数据类型。
    • [object Object]Atlas A2 训练系列产品/Atlas 800I A2 推理产品/A200I A2 Box 异构组件[object Object]：当前版本不支持，传0即可。
    • [object Object]Atlas A3 训练系列产品/Atlas A3 推理系列产品[object Object]：取值范围[0, 2]，0和1表示无TP域通信，有TP域通信时仅支持2。
  • tpRankId（int64_t，计算输入）：TP域本卡Id，数据类型支持INT64。
    • [object Object]Atlas A2 训练系列产品/Atlas 800I A2 推理产品/A200I A2 Box 异构组件[object Object]：当前版本不支持，传0即可。
    • [object Object]Atlas A3 训练系列产品/Atlas A3 推理系列产品[object Object]：取值范围[0, 1]，同一个TP通信域中各卡的tpRankId不重复。无TP域通信时，传0即可。
  • expertShardType（int64_t，计算输入）：表示共享专家卡分布类型，数据类型支持INT64。
    • [object Object]Atlas A2 训练系列产品/Atlas 800I A2 推理产品/A200I A2 Box 异构组件[object Object]：当前版本不支持，传0即可。
    • [object Object]Atlas A3 训练系列产品/Atlas A3 推理系列产品[object Object]：当前仅支持传0，表示共享专家卡排在MoE专家卡前面。
  • sharedExpertNum（int64_t，计算输入）：表示共享专家数量，一个共享专家可以复制部署到多个卡上，数据类型支持INT64。
    • [object Object]Atlas A2 训练系列产品/Atlas 800I A2 推理产品/A200I A2 Box 异构组件[object Object]：当前版本不支持，传0即可。
    • [object Object]Atlas A3 训练系列产品/Atlas A3 推理系列产品[object Object]：当前取值范围[0, 4]。
  • sharedExpertRankNum（int64_t，计算输入）：表示共享专家卡数量，数据类型支持INT64。
    • [object Object]Atlas A2 训练系列产品/Atlas 800I A2 推理产品/A200I A2 Box 异构组件[object Object]：当前版本不支持，传0即可。
    • [object Object]Atlas A3 训练系列产品/Atlas A3 推理系列产品[object Object]：当前取值范围[0, epWorldSize)，为0时需满足sharedExpertNum为0或1，不为0时需满足sharedExpertRankNum % sharedExpertNum = 0。
  • quantMode（int64_t，计算输入）：表示量化模式，支持0：非量化，2：动态量化。
  • globalBs（int64_t，计算输入）：EP域全局的batch size大小，数据类型支持INT64。当每个rank的Bs数一致时，globalBs = Bs * epWorldSize 或 globalBs = 0；当每个rank的Bs数不一致时，globalBs = maxBs * epWorldSize，其中maxBs表示单卡Bs最大值。
  • expertTokenNumsType（int64_t，计算输入）：输出expertTokenNums中值的语义类型。支持0：expertTokenNums中的输出为每个专家处理的token数的前缀和，1：expertTokenNums中的输出为每个专家处理的token数量。
  • commAlg（char*，计算输入）：表示通信亲和内存布局算法，string数据类型。
    • [object Object]Atlas A2 训练系列产品/Atlas 800I A2 推理产品/A200I A2 Box 异构组件[object Object]：当前版本支持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通信。
    • [object Object]Atlas A3 训练系列产品/Atlas A3 推理系列产品[object Object]：当前版本不支持，传空指针即可。
  • expandXOut（aclTensor*，计算输出）：根据expertIds进行扩展过的token特征，Device侧的aclTensor，要求为一个2D的Tensor，shape为 (max(tpWorldSize, 1) * A, H)，数据类型支持FLOAT16、BFLOAT16、INT8，undefined要求为ND，支持undefined。
  • dynamicScalesOut（aclTensor*，计算输出）：数据类型FLOAT32，要求为一个1D的Tensor，shape为 (A, )，undefined要求为ND，支持undefined。当quantMode为2时，才有该输出。
  • assistInfoForCombineOut（aclTensor*，计算输出）：表示给同一专家发送的token个数，对应CombineV2系列算子中的assistInfoForCombine，Device侧的aclTensor，要求是一个1D的Tensor，shape要求为 (A*128, )，数据类型支持INT32，undefined要求为ND，支持undefined。
  • expertTokenNumsOut（aclTensor*，计算输出）：表示每个专家收到的token个数，Device侧的aclTensor，数据类型INT64，要求为一个1D的Tensor，shape为 (localExpertNum, )，undefined要求为ND，支持undefined。
  • epRecvCountsOut（aclTensor*，计算输出）：从EP通信域各卡接收的token数，对应CombineV2系列算子中的epSendCounts，Device侧的aclTensor，数据类型INT32，要求为一个1D的Tensor，undefined要求为ND，支持undefined。
    • [object Object]Atlas A2 训练系列产品/Atlas 800I A2 推理产品/A200I A2 Box 异构组件[object Object]：要求shape为 (moeExpertNum + 2 * globalBs * K * serverNum, )，前moeExpertNum个数表示从EP通信域各卡接收的token数，2 * globalBs * K * serverNum存储了机间机内做通信前combine可以提前做reduce的token个数和token在通信区中的偏移，globalBs传入0时在此处应当按照Bs * epWorldSize计算。
    • [object Object]Atlas A3 训练系列产品/Atlas A3 推理系列产品[object Object]：要求shape为 (epWorldSize * max(tpWorldSize, 1) * localExpertNum, )。
  • tpRecvCountsOut（aclTensor*，计算输出）：从TP通信域各卡接收的token数，对应CombineV2系列算子中的tpSendCounts，Device侧的aclTensor。若有TP域通信则有该输出，若无TP域通信则无该输出。
    • [object Object]Atlas A2 训练系列产品/Atlas 800I A2 推理产品/A200I A2 Box 异构组件[object Object]：当前不支持TP域通信。
    • [object Object]Atlas A3 训练系列产品/Atlas A3 推理系列产品[object Object]：当有TP域通信时，要求是一个1D的Tensor，shape为 (tpWorldSize, )。数据类型支持INT32，undefined要求为ND，支持undefined。
  • expertScalesOut（aclTensor*，计算输出）：表示本卡输出token的权重，对应CombineV2系列算子中的expertScalesOptional，Device侧的aclTensor。
    • [object Object]Atlas A2 训练系列产品/Atlas 800I A2 推理产品/A200I A2 Box 异构组件[object Object]：要求是一个1D的Tensor，shape为 (A, )，数据类型支持FLOAT32，undefined要求为ND，支持undefined。
    • [object Object]Atlas A3 训练系列产品/Atlas A3 推理系列产品[object Object]：当前版本不支持该输出。
  • workspaceSize（uint64_t*，出参）：返回需要在Device侧申请的workspace大小。
  • executor（aclOpExecutor**，出参）：返回op执行器，包含了算子计算流程。

• 返回值

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

  [object Object]

aclnnMoeDistributeDispatchV2

• 参数说明：

  • workspace（void*，入参）：在Device侧申请的workspace内存地址。
  • workspaceSize（uint64_t，入参）：在Device侧申请的workspace大小，由第一段接口aclnnMoeDistributeDispatchV2GetWorkspaceSize获取。
  • executor（aclOpExecutor*，入参）：op执行器，包含了算子计算流程。
  • stream（aclrtStream，入参）：指定执行任务的Stream。

• 返回值：

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

约束说明

• aclnnMoeDistributeDispatchV2接口与CombineV2系列算子接口必须配套使用，具体参考undefined。

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

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

• [object Object]Atlas A3 训练系列产品/Atlas A3 推理系列产品[object Object]：该场景下单卡包含双DIE（简称为“晶粒”或“裸片”），因此参数说明里的“本卡”均表示单DIE。

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

  • A：表示本卡可能接收的最大token数量，取值范围如下：
    • 对于共享专家，要满足A = Bs * epWorldSize * sharedExpertNum / sharedExpertRankNum。
    • 对于MoE专家，当globalBs为0时，要满足A >= Bs * epWorldSize * min(localExpertNum, K)；当globalBs非0时，要满足A >= globalBs * min(localExpertNum, K)。
  • H：表示hidden size隐藏层大小。
    • [object Object]Atlas A2 训练系列产品/Atlas 800I A2 推理产品/A200I A2 Box 异构组件[object Object]：取值范围(0, 7168]，且保证是32的整数倍。
    • [object Object]Atlas A3 训练系列产品/Atlas A3 推理系列产品[object Object]：取值范围[1024, 8192]。
  • Bs：表示batch sequence size，即本卡最终输出的token数量。
    • [object Object]Atlas A2 训练系列产品/Atlas 800I A2 推理产品/A200I A2 Box 异构组件[object Object]：取值范围为0 < Bs ≤ 256。
    • [object Object]Atlas A3 训练系列产品/Atlas A3 推理系列产品[object Object]：取值范围为0 < Bs ≤ 512。
  • K：表示选取topK个专家，取值范围为0 < K ≤ 16同时满足0 < K ≤ moeExpertNum。
  • serverNum：表示服务器的节点数，取值只支持2、4、8。
  • localExpertNum：表示本卡专家数量。
    • 对于共享专家卡，localExpertNum = 1
    • 对于MoE专家卡，localExpertNum = moeExpertNum / (epWorldSize - sharedExpertRankNum)，localExpertNum > 1时，不支持TP域通信。

• HCCL_BUFFSIZE： 调用本接口前需检查HCCL_BUFFSIZE环境变量取值是否合理，该环境变量表示单个通信域占用内存大小，单位MB，不配置时默认为200MB。

  • [object Object]Atlas A2 训练系列产品/Atlas 800I A2 推理产品/A200I A2 Box 异构组件[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]：要求 >= 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。

• HCCL_INTRA_PCIE_ENABLE和HCCL_INTRA_ROCE_ENABLE：

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

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

• 通信域使用约束：

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

调用示例

以[object Object]Atlas A3 训练系列产品/Atlas A3 推理系列产品[object Object]单机为例，调起MoeDistributeCombineV2和MoeDistributeDispatchV2算子。

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

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

• 编译脚本

  [object Object]

• 编译与运行：

  [object Object]

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

  [object Object]