接口列表

HCCL Python语言的接口用于实现图模式下的框架适配，当前仅用于TensorFlow网络在昇腾AI处理器执行分布式优化。其中TF Adapter提供的分布式优化器（TF Adapter 1.x：NPUDistributedOptimizer和npu_distributed_optimizer_wrapper；TF Adapter 2.x：npu_distributed_keras_optimizer_wrapper）可以让用户在不需要感知allreduce的情况下自动完成梯度聚合功能，实现数据并行训练方式。但为了能够同时满足用户灵活的使用方式，HCCL提供了常用的rank管理、梯度切分功能等接口，可配合TF Adapter提供的集合通信算子接口完成集合通信功能。

HCCL Python接口列表

HCCL提供了“通信域管理”与“梯度切分”的Python API：

“通信域管理”相关接口的定义在文件“${install_path}/python/site-packages/hccl/manage/api.py”中。
“梯度切分”相关接口的定义在文件“${install_path}/python/site-packages/hccl/split/api.py”中。

接口	简介
通信域管理
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的融合，用于进行集合通信的性能调优。

以上接口可以配合TF Adapter提供的集合通信操作接口使用，实现集合通信功能。

TF Adapter 1.x通信算子接口列表

TF Adapter 1.x提供的集合通信算子接口如下表所示，接口详细介绍可参见”。

表1 TF Adapter 1.x提供的集合通信算子接口
接口	简介
allreduce	集合通信算子AllReduce的操作接口，将group内所有节点的输入数据进行reduce操作后，再把结果发送到所有节点的输出buf，其中reduce操作类型由reduction参数指定。
allgather	集合通信算子AllGather的操作接口，将通信域内所有节点的输入按照rank id重新排序，然后拼接起来，再将结果发送到所有节点的输出。
broadcast	集合通信算子Broadcast的操作接口，将通信域内root节点的数据广播到其他rank。
reduce_scatter	集合通信算子ReduceScatter的操作接口。将所有rank的输入相加（或其他归约操作）后，再把结果按照rank编号均匀分散到各个rank的输出buffer，每个进程拿到其他进程1/rank_size份的数据进行归约操作。
reduce	集合通信算子Reduce的操作接口，将所有rank的数据相加（或其他归约操作）后，再把结果发送到root节点的指定位置上。
send	提供group内点对点通信发送数据的send功能。
receive	提供group内点对点通信发送数据的receive功能。
alltoallv	集合通信AlltoAllV操作接口。向通信域内所有rank发送数据（数据量可以定制），并从所有rank接收数据。
alltoallvc	集合通信alltoallvc操作接口。向通信域内所有rank发送数据（数据量可以定制），并从所有rank接收数据。 alltoallvc通过输入参数send_count_matrix传入所有rank的收发参数，与alltoallv相比，性能更优。

TF Adapter 2.x通信算子接口列表

TF Adapter 2.x提供的集合通信算子接口如下表所示，接口详细介绍可参见《TF Adapter接口 (2.x)》。

表2 TF Adapter 2.x提供的集合通信操作接口
接口	简介
npu.distribute.all_reduce	集合通信算子AllReduce的操作接口，用于NPU分布式部署场景下，worker间的聚合运算。
npu.distribute.broadcast	集合通信算子Broadcast的操作接口，用于NPU分布式部署场景下，worker间的变量同步。

相关概念

概念	介绍
group	指参与集合通信的进程组，包括： hccl_world_group：默认的全局group，包含所有参与集合通信的rank，通过rank table文件创建。自定义group：hccl_world_group包含的进程组的子集，可以通过create_group接口将rank table中的rank定义成不同的group，并行执行集合通信算法。
rank	group中的每个通信实体称为一个rank，每个rank都会分配一个介于0~n-1（n为NPU的数量）的唯一标识。
rank size	rank size，指整个group的rank数量。 local rank size，指group内进程在其所在Server内的rank数量。
rank id	rank id，指进程在group中对应的rank标识序号。范围：0~（rank size-1）。对于用户自定义group，rank在本group内从0开始进行重排；对于hccl_world_group，rank id和world rank id相同。 world rank id，指进程在hccl_world_group中对应的rank标识序号，范围：0~（rank size-1）。 local rank id，指group内进程在其所在Server内的rank编号，范围：0~（local rank size-1）。

父主题： HCCL API (Python)