接口列表

HCCL提供了通信算子接口与通信域管理接口，支持框架开发者实现分布式能力。

通信算子接口：提供了集合通信与点对点通信两大类接口。
通信域管理接口：提供通信域的创建、销毁、异常处理等接口。
其中通信域管理支持C与Python两种语言：
- C语言接口用于实现单算子模式下的框架适配，实现分布式能力。
- Python语言的接口用于实现图模式下的框架适配，当前仅用于实现TensorFlow网络在NPU执行分布式优化，可配合TF Adapter提供的集合通信算子接口完成集合通信功能。

HCCL接口定义文件如下：

${INSTALL_DIR}/include/hccl/hccl_types.h：数据类型定义文件。
${INSTALL_DIR}/include/hccl/hccl.h：通信算子接口定义文件。
${INSTALL_DIR}/include/hccl/hccl_comm.h：C语言的通信域管理接口定义文件。
${INSTALL_DIR}/python/site-packages/hccl路径下的“manage/api.py”与“split/api.py”：Python语言的通信域管理接口定义文件。

通信算子接口

接口	简介
HcclAllReduce	集合通信算子AllReduce的操作接口，将通信域内所有节点的输入数据进行相加（或其他归约操作）后，再把结果发送到所有节点的输出buffer，其中归约操作类型由op参数指定。
HcclBroadcast	集合通信算子Broadcast的操作接口，将通信域内root节点的数据广播到其他rank。
HcclAllGather	集合通信算子AllGather的操作接口，将通信域内所有节点的输入按照rank id重新排序，然后拼接起来，再将结果发送到所有节点的输出。
HcclAllGatherV	集合通信算子AllGatherV的操作接口，将通信域内所有节点的输入按照rank id重新排序，然后拼接起来，再将结果发送到所有节点的输出。与AllGather算子不同的是，AllGatherV算子支持通信域内不同节点的输入配置不同大小的数据量。
HcclReduceScatter	集合通信算子ReduceScatter的操作接口，将通信域内所有rank的输入数据均分成rank size份，然后分别取每个rank的rank size之一份数据进行归约操作（如sum、prod、max、min）。最后，将结果按照编号分散到各个rank的输出buffer。
HcclReduceScatterV	集合通信算子ReduceScatterV的操作接口，与ReduceScatter操作类似，不同点是支持为通信域内不同的节点配置不同大小的数据量（同一rank不同编号的数据大小可设置，但不同rank间相同编号的数据大小需保持一致），取每个rank对应编号的数据进行归约操作后（支持sum、prod、max、min）后，再把结果按照编号分散到各个rank的输出buffer。
HcclReduce	集合通信算子Reduce的操作接口，将所有rank的数据相加（或其他归约操作）后，再把结果发送到root节点的指定位置上。
HcclAlltoAll	集合通信算子AlltoAll操作接口，向通信域内所有rank发送相同数据量的数据，并从所有rank接收相同数据量的数据。
HcclAlltoAllV	集合通信算子AlltoAllV操作接口，向通信域内所有rank发送数据（数据量可以定制），并从所有rank接收数据。
HcclAlltoAllVC	集合通信算子AlltoAllVC操作接口，向通信域内所有rank发送数据（数据量可以定制），并从所有rank接收数据。相比于AlltoAllV，AlltoAllVC通过输入参数sendCountMatrix传入所有rank的收发参数。
HcclScatter	集合通信算子Scatter操作接口，将root节点的数据均分并散布至其他rank。
HcclSend	点对点通信Send操作接口，将当前节点指定位置的数据发送至目的节点。
HcclRecv	点对点通信Receive操作接口，从源节点接收数据到当前节点的指定位置上。
HcclBatchSendRecv	异步批量点对点通信操作接口，调用一次接口可以完成本rank上的多个收发任务，本rank发送和接收之间是异步的，发送和接收任务之间不会相互阻塞。

通信域管理接口

C语言接口

表1 HCCL（C）接口列表
接口	简介
HcclCommInitClusterInfo	基于rank table初始化HCCL，创建HCCL通信域。
HcclCommInitClusterInfoConfig	基于rank table初始化HCCL，创建具有特定配置的HCCL通信域。
HcclGetRootInfo	此接口需要在HCCL初始化接口HcclCommInitRootInfo或HcclCommInitRootInfoConfig前调用，仅需在root节点调用，用于生成root节点的rank标识信息（HcclRootInfo）。
HcclCommInitRootInfo	根据rootInfo初始化HCCL，创建HCCL通信域。
HcclCommInitRootInfoConfig	根据rootInfo初始化HCCL，创建具有特定配置的HCCL通信域。
HcclCommConfigInit	初始化通信域配置项，并将其中的可配置参数设为默认值。
HcclCommInitAll	单机通信场景中，通过一个进程统一创建多张卡的通信域（其中一张卡对应一个线程）。在初始化通信域的过程中，devices[0]作为root rank自动收集集群信息。
HcclCommDestroy	销毁指定的HCCL通信域。
HcclGetRankSize	查询指定通信域的rank总数。
HcclGetRankId	获取device在通信域中对应的rank序号。
HcclBarrier	将指定通信域内所有rank的stream阻塞，直到所有rank都下发执行该操作为止。
HcclSetConfig	进行集合通信相关配置，当前仅支持配置是否支持确定性计算。
HcclGetConfig	获取集合通信相关配置。
HcclGetCommName	获取指定通信操作所在的通信域的名称。
HcclGetCommConfigCapability	该接口用于判断当前版本软件是否支持某项通信域初始化配置。
HcclCommSuspend	当片上内存UCE（uncorrect error）故障时（ACL接口返回ACL_ERROR_RT_DEVICE_MTE_ERROR错误码），可调用本接口将通信域置为挂起状态。注意：本接口为预留接口，后续有可能变更，不支持开发者使用。
HcclCommResume	本接口用于恢复通信域的状态。注意：本接口为预留接口，后续有可能变更，不支持开发者使用。
HcclCreateSubCommConfig	基于既有的全局通信域，切分具有特定配置的子通信域。
HcclCommWorkingDevNicSet	在集群场景下，配置通信域内的通信网卡。支持在同一NPU下，在某一Device网卡和备用网卡之间切换通信，备用网卡为同一NPU中的另一个Die网卡。
HcclGetCommAsyncError	当集群信息中存在Device网口通信链路不稳定、出现网络拥塞的情况时，Device日志中会存在“error cqe”的打印，我们称这种错误为“RDMA ERROR CQE”错误。当前版本，此接口仅支持查询通信域内是否存在“RDMA ERROR CQE”的错误。
HcclGetErrorString	解析HcclResult类型的错误码。
HcclCommSetMemoryRange	用户通过aclrtReserveMemAddress接口成功申请虚拟内存后，可调用此接口通知HCCL预留的虚拟内存地址。调用此接口后，该虚拟内存对当前进程中的所有通信域可见。注意：零拷贝功能接口，仅支持Ascend Extension for PyTorch插件后端代码调用，且为试用接口，暂不支持应用于商用产品。
HcclCommUnsetMemoryRange	该接口用于通知HCCL通信域取消使用预留的虚拟内存。注意：零拷贝功能接口，仅支持Ascend Extension for PyTorch插件后端代码调用，且为试用接口，暂不支持应用于商用产品。
HcclCommActivateCommMemory	激活预留的虚拟内存，只有使用激活后的内存作为通信算子的输入、输出才可使能零拷贝功能。注意：零拷贝功能接口，仅支持Ascend Extension for PyTorch插件后端代码调用，且为试用接口，暂不支持应用于商用产品。
HcclCommDeactivateCommMemory	将已经激活的虚拟内存反激活，反激活后如果再使用该地址进行集合通信，将不会使能零拷贝功能。注意：零拷贝功能接口，仅支持Ascend Extension for PyTorch插件后端代码调用，且为试用接口，暂不支持应用于商用产品。

Python语言接口

接口	简介
create_group	创建用户自定义group。
destroy_group	销毁用户自定义group。
get_rank_size	获取group内的rank数量（即Device数量）。
get_local_rank_size	获取group内device所在服务器内的local rank数量。
get_rank_id	获取device在group中对应的rank序号。
get_local_rank_id	获取device在group中对应的local rank序号。
get_world_rank_from_group_rank	根据进程在group中的rank id，获取对应的world rank id。
get_group_rank_from_world_rank	从world rank id，获取该进程在group中的group rank id。
set_split_strategy_by_idx	基于梯度的索引id，在集合通信group内设置反向梯度切分策略，实现allreduce的融合，用于进行集合通信的性能调优。
set_split_strategy_by_size	基于梯度数据量百分比，在集合通信group内设置反向梯度切分策略，实现allreduce的融合，用于进行集合通信的性能调优。

父主题： HCCL API