aclnnMoeDistributeCombine

产品支持情况

产品	是否支持
[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]	×

功能说明

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

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

函数原型

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

aclnnStatus aclnnMoeDistributeCombineGetWorkspaceSize(const aclTensor* expandX, const aclTensor* expertIds, const aclTensor* expandIdx, const aclTensor* epSendCounts, const aclTensor* expertScales, const aclTensor* tpSendCounts, const aclTensor* xActiveMask, const aclTensor* activationScale, const aclTensor* weightScale, const aclTensor* groupList, const aclTensor* expandScales, 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 globalBs, int64_t outDtype, int64_t commQuantMode, int64_t groupListType, aclTensor* x, uint64_t* workspaceSize, aclOpExecutor** executor)
aclnnStatus aclnnMoeDistributeCombine(void *workspace, uint64_t workspaceSize, aclOpExecutor *executor, aclrtStream stream)

aclnnMoeDistributeCombineGetWorkspaceSize

参数说明：
- expandX（aclTensor*，计算输入）：根据expertIds进行扩展过的token特征，Device侧的aclTensor，要求为一个2D的Tensor，shape为 (max(tpWorldSize, 1) * A , H)，数据类型支持FLOAT16、BFLOAT16，undefined要求为ND，支持undefined。
  - [object Object]Atlas A2 训练系列产品/Atlas 800I A2 推理产品/A200I A2 Box 异构组件[object Object]：不支持共享专家场景。
- expertIds（aclTensor*，计算输入）：每个token的topK个专家索引，Device侧的aclTensor，要求为一个2D的Tensor，shape为 (BS, K)。数据类型支持INT32，undefined要求为ND，支持undefined。
- expandIdx（aclTensor*，计算输入）：对应aclnnMoeDistributeDispatch中的expandIdx输出，Device侧的aclTensor，要求是一个1D的Tensor，shape为 (BS*K, )。数据类型支持INT32，undefined要求为ND，支持undefined。
- epSendCounts（aclTensor*，计算输入）：对应aclnnMoeDistributeDispatch中的epRecvCounts输出，Device侧的aclTensor，要求是一个1D的Tensor。数据类型支持INT32，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, )。
- expertScales（aclTensor*，计算输入）：每个token的topK个专家的权重，Device侧的aclTensor，要求是一个2D的Tensor，shape为 (BS, K)。类型支持FLOAT32，undefined要求为ND，支持undefined。
- tpSendCounts（aclTensor*，计算输入）：对应aclnnMoeDistributeDispatch中的tpRecvCounts输出，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。
- xActiveMask（aclTensor*，计算输入）：Device侧的aclTensor，预留参数。
  - [object Object]Atlas A2 训练系列产品/Atlas 800I A2 推理产品/A200I A2 Box 异构组件[object Object]、[object Object]Atlas A3 训练系列产品/Atlas A3 推理系列产品[object Object]：当前版本不支持，传空指针即可。
- activationScale（aclTensor*，计算输入）：Device侧的aclTensor，预留参数。
  - [object Object]Atlas A2 训练系列产品/Atlas 800I A2 推理产品/A200I A2 Box 异构组件[object Object]、[object Object]Atlas A3 训练系列产品/Atlas A3 推理系列产品[object Object]：当前版本不支持，传空指针即可。
- weightScale（aclTensor*，计算输入）：Device侧的aclTensor，预留参数。
  - [object Object]Atlas A2 训练系列产品/Atlas 800I A2 推理产品/A200I A2 Box 异构组件[object Object]、[object Object]Atlas A3 训练系列产品/Atlas A3 推理系列产品[object Object]：当前版本不支持，传空指针即可。
- groupList（aclTensor*，计算输入）：Device侧的aclTensor，预留参数。
  - [object Object]Atlas A2 训练系列产品/Atlas 800I A2 推理产品/A200I A2 Box 异构组件[object Object]、[object Object]Atlas A3 训练系列产品/Atlas A3 推理系列产品[object Object]：当前版本不支持，传空指针即可。
- expandScales（aclTensor*，计算输入）：对应aclnnMoeDistributeDispatch中的expandScales输出，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]：预留参数，当前版本不支持，传空指针即可。
- 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]：取值支持8、16、32、64、128、144、256、288。
- epRankId（int64_t，计算输入）：EP域本卡Id，数据类型支持INT64，取值范围[0, epWorldSize)。同一个EP通信域中各卡的epRankId不重复。
- moeExpertNum（int64_t，计算输入）: MoE专家数量，数据类型支持INT64，取值范围(0, 512]，并且满足moeExpertNum % (epWorldSize - sharedExpertRankNum) = 0。
  - [object Object]Atlas A2 训练系列产品/Atlas 800I A2 推理产品/A200I A2 Box 异构组件[object Object]：还需满足moeExpertNum / (epWorldSize - sharedExpertRankNum) <= 24。
- 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, 1]，0表示无共享专家，1表示一个共享专家，当前版本仅支持1。
- 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时需满足epWorldSize % sharedExpertRankNum = 0。
- globalBs（int64_t，计算输入）：EP域全局的batch size大小，数据类型支持INT64。
  - [object Object]Atlas A2 训练系列产品/Atlas 800I A2 推理产品/A200I A2 Box 异构组件[object Object]：当每个rank的Bs数一致时，globalBs = Bs * epWorldSize 或 globalBs = 0；当每个rank的Bs数不一致时，globalBs = maxBs * epWorldSize或者globalBs = 256 * epWorldSize，其中maxBs表示表示单rank BS最大值，建议按maxBs * epWorldSize传入，固定按256 * epWorldSize传入在后续版本bs支持大于256的场景下会无法支持。
  - [object Object]Atlas A3 训练系列产品/Atlas A3 推理系列产品[object Object]：当每个rank的Bs数一致时，globalBs = Bs * epWorldSize 或 globalBs = 0；当每个rank的Bs数不一致时，globalBs = maxBs * epWorldSize，其中maxBs表示单卡Bs最大值。
- outDtype（int64_t，计算输入）：用于指定输出x的数据类型，预留参数，当前版本不支持，传0即可。
- commQuantMode（int64_t，计算输入）：通信量化类型。
  - [object Object]Atlas A2 训练系列产品/Atlas 800I A2 推理产品/A200I A2 Box 异构组件[object Object]：取值范围0或者2，0表示通信时不进行量化，2表示通信时进行int8量化，2仅当HCCL_INTRA_PCIE_ENABLE为1且HCCL_INTRA_ROCE_ENABLE为0且驱动版本不低于25.0.RC1.1时支持。
  - [object Object]Atlas A3 训练系列产品/Atlas A3 推理系列产品[object Object]：取值范围0或者2，0表示通信时不进行量化，2表示通信时进行int8量化。
- groupListType（int64_t，计算输入）：group List格式，预留参数，当前版本不支持，传0即可。
- x（aclTensor*，计算输出）：表示处理后的token，Device侧的aclTensor，要求是一个2D的Tensor，shape为(BS, H)，数据类型、数据格式与expandX保持一致。
- workspaceSize（uint64_t*，出参）：返回需要在Device侧申请的workspace大小。
- executor（aclOpExecutor**，出参）：返回op执行器，包含了算子计算流程。
返回值

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

[object Object]

aclnnMoeDistributeCombine

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

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

约束说明

aclnnMoeDistributeDispatch接口与aclnnMoeDistributeCombine接口必须配套使用，具体参考undefined。
在不同产品型号、不同通信算法或不同版本中，aclnnMoeDistributeDispatch的Tensor输出expandIdx、epRecvCounts、tpRecvCounts、expandScales中的元素值可能不同，使用时直接将上述Tensor传给aclnnMoeDistributeCombine对应参数即可，模型其他业务逻辑不应对其存在依赖。
调用接口过程中使用的groupEp、epWorldSize、moeExpertNum、groupTp、tpWorldSize、expertShardType、sharedExpertNum、sharedExpertRankNum、globalBs参数取值所有卡需保持一致，网络中不同层中也需保持一致，且和aclnnMoeDistributeDispatch对应参数也保持一致。
[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]：取值为7168。
- 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 ≤ moeExpertNum。
  - [object Object]Atlas A2 训练系列产品/Atlas 800I A2 推理产品/A200I A2 Box 异构组件[object Object]：取值范围为0 < K ≤ 16。
  - [object Object]Atlas A3 训练系列产品/Atlas A3 推理系列产品[object Object]：取值范围为0 < K ≤ 8。
- 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]：要求 >= 2 * (BS * epWorldSize * min(localExpertNum, K) * H * sizeof(uint16) + 2MB)。
- [object Object]Atlas A3 训练系列产品/Atlas A3 推理系列产品[object Object]：要求 >= 2且满足1024 ^ 2 * (HCCL_BUFFSIZE - 2) / 2 >= BS * 2 * (H + 128) * (epWorldSize * localExpertNum + K + 1)，localExpertNum需使用MoE专家卡的本卡专家数。
HCCL_INTRA_PCIE_ENABLE和HCCL_INTRA_ROCE_ENABLE：
- [object Object]Atlas A2 训练系列产品/Atlas 800I A2 推理产品/A200I A2 Box 异构组件[object Object]：设置环境变量HCCL_INTRA_PCIE_ENABLE = 1和HCCL_INTRA_ROCE_ENABLE = 0可以减少跨机通信数据量，可能提升算子性能。此时，HCCL_BUFFSIZE要求 >= moeExpertNum * BS * (H * sizeof(dtypeX) + 4 * ((K + 7) / 8 * 8) * sizeof(uint32)) + 4MB + 100MB。并且，对于入参moeExpertNum，只要求moeExpertNum % (epWorldSize - sharedExpertRankNum) = 0，不要求moeExpertNum / (epWorldSize - sharedExpertRankNum) <= 24。
本文公式中的"/"表示整除。
通信域使用约束：
- 一个模型中的aclnnMoeDistributeCombine和aclnnMoeDistributeDispatch仅支持相同EP通信域，且该通信域中不允许有其他算子。
- 一个模型中的aclnnMoeDistributeCombine和aclnnMoeDistributeDispatch仅支持相同TP通信域或都不支持TP通信域，有TP通信域时该通信域中不允许有其他算子。

调用示例

[object Object]Atlas A3 训练系列产品/Atlas A3 推理系列产品[object Object]：示例代码请参考undefined调用过程，仅供参考，请根据实际情况配置；
[object Object]Atlas A2 训练系列产品/Atlas 800I A2 推理产品/A200I A2 Box 异构组件[object Object]：示例代码如下，调起combine和dispatch算子，仅供参考，请根据实际情况配置。
文件准备：
1.新建combineDemo目录，按照下方指导在combineDemo下新建aclnnCombineDemo.cpp，buildCombine.sh，rank_table_m2.json文件并修改。 2.将combineDemo项目拷贝到两台服务器中，并根据机器的device ip配置rank_table_m2.json文件内容。注意两机rank_table_m2.json文件保持一致。 3.安装cann包，并根据下方指导编译运行combineDemo。
关于rankTable: 开发者可以通过ranktable文件配置参与集合通信的NPU资源信息，详细配置请参考undefined中“通信功能开发>集群信息配置>ranktable文件配置资源信息”。

使用cat /etc/hccn.conf 或者for i in seq 0 7; do echo "===================> dev$i, NPU$((i+1))"; hccn_tool -i $i -ip -g; done查询机器的device ip。然后参考集合通信文档填写json文件。

注意：device_id范围是[0, 8)，且可自由选择几张卡； rank_id依次增加。以两机16卡为例，两机器的device ip都是0~~7，其中一机器rank_id为0~~7，则另一台机器的rank_id为8~15。
编译脚本

[object Object]
编译与运行：

[object Object]
示例代码如下，仅供参考