---
title: 接口列表
description: "HCCL提供了通信算子接口、通信域管理接口与组调用接口，支持框架开发者实现分布式能力。- 通信算子接口：提供了集合通信与点对点通信两大类接口。"
url: https://www.hiascend.com/document/detail/zh/canncommercial/latest/API/hcclug/hcclcpp_07_0001.html
sourcePath: /source/zh/canncommercial/900/API/hcclug/hcclcpp_07_0001.html
indexId: 770895f18c9e3cd9ce92e397f02306e505afda115c6986a10edad4904302324361
---
# 接口列表

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}/include/hccl/hccl_sym_win.h：对称内存接口。
- ${INSTALL_DIR}/python/site-packages/hccl路径下的“manage/api.py”与“split/api.py”：Python语言的通信域管理接口定义文件。


#### 通信算子接口

| 接口 | 简介 |
| --- | --- |
| HcclBroadcast | 集合通信算子Broadcast的操作接口，将通信域内root节点的数据广播到其他rank。 |
| HcclAllGather | 集合通信算子AllGather的操作接口，将通信域内所有节点的输入按照rank id重新排序，然后拼接起来，再将结果发送到所有节点的输出。 |
| HcclAllGatherV | 集合通信算子AllGatherV的操作接口，将通信域内所有节点的输入按照rank id重新排序，然后拼接起来，再将结果发送到所有节点的输出。 与AllGather算子不同的是，AllGatherV算子支持通信域内不同节点的输入配置不同大小的数据量。 |
| HcclReduce | 集合通信算子Reduce的操作接口，将所有rank的数据相加（或其他归约操作）后，再把结果发送到root节点的指定位置上。 |
| HcclAllReduce | 集合通信算子AllReduce的操作接口，将通信域内所有节点的输入数据进行相加（或其他归约操作）后，再把结果发送到所有节点的输出buffer，其中归约操作类型由op参数指定。 |
| HcclScatter | 集合通信算子Scatter操作接口，将root节点的数据均分并散布至其他rank。 |
| 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。 |
| HcclAlltoAll | 集合通信算子AlltoAll操作接口，向通信域内所有rank发送相同数据量的数据，并从所有rank接收相同数据量的数据。 |
| HcclAlltoAllV | 集合通信算子AlltoAllV操作接口，向通信域内所有rank发送数据（数据量可以定制），并从所有rank接收数据。 |
| HcclAlltoAllVC | 集合通信算子AlltoAllVC操作接口，向通信域内所有rank发送数据（数据量可以定制），并从所有rank接收数据。相比于AlltoAllV，AlltoAllVC通过输入参数sendCountMatrix传入所有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 | 获取指定通信操作所在的通信域的名称。 |
| HcclCommGetHandleWithName | 根据通信域名称获取指向对应通信域的句柄。 |
| 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(https://www.hiascend.comdocument/detail/zh/canncommercial/900/API/runtimeapi/aclcppdevg\_03\_0114.html)接口成功申请虚拟内存后，可调用此接口通知HCCL预留的虚拟内存地址。调用此接口后，该虚拟内存对当前进程中的所有通信域可见。 注意：零拷贝功能接口，仅支持Ascend Extension for PyTorch插件后端代码调用，且为试用接口，暂不支持应用于生产环境。 |
| HcclCommUnsetMemoryRange | 该接口用于通知HCCL通信域取消使用预留的虚拟内存。 注意：零拷贝功能接口，仅支持Ascend Extension for PyTorch插件后端代码调用，且为试用接口，暂不支持应用于生产环境。 |
| HcclCommActivateCommMemory | 激活预留的虚拟内存，只有使用激活后的内存作为通信算子的输入、输出才可启用零拷贝功能。 注意：零拷贝功能接口，仅支持Ascend Extension for PyTorch插件后端代码调用，且为试用接口，暂不支持应用于生产环境。 |
| HcclCommDeactivateCommMemory | 将已经激活的虚拟内存反激活，反激活后如果再使用该地址进行集合通信，将不会启用零拷贝功能。 注意：零拷贝功能接口，仅支持Ascend Extension for PyTorch插件后端代码调用，且为试用接口，暂不支持应用于生产环境。 |
| HcclCommSymWinRegister | 用户在申请虚拟内存和物理内存并完成映射后，可调用此接口将虚拟内存注册为对称内存。 |
| HcclCommSymWinDeregister | 将注册过的对称窗口对应的虚拟内存解除注册，释放对称窗口资源。 |
| HcclCommSymWinGet | 根据已注册对称内存的虚拟地址指针，返回对应的窗口资源句柄及其在窗口内的偏移量。 |
| HcclSymWinGetPeerPointer | 根据对称内存窗口资源句柄和偏移，获取指定rank ID在对称内存上的虚拟地址指针。 |


- 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的融合，用于进行集合通信的性能调优。 |


#### 组调用接口

| 接口 | 简介 |
| --- | --- |
| HcclGroupStart | 开始一个组调用。 |
| HcclGroupEnd | 结束一个组调用。 |