mindspore.communication

集合通信接口。

注意，集合通信接口需要预先设置环境变量。对于Ascend，用户需要配置rank_table，设置rank_id和device_id，相关教程可参考： Ascend指导文档。对于GPU，用户需要预先配置host_file以及mpi，相关教程参考： GPU指导文档。

目前尚不支持CPU。

class mindspore.communication.GlobalComm[源代码]

GlobalComm 是一个储存通信信息的全局类。成员包含：BACKEND、WORLD_COMM_GROUP。

BACKEND：使用的通信库，HCCL或者NCCL。
WORLD_COMM_GROUP：全局通信域。

mindspore.communication.init(backend_name=None)[源代码]

初始化通信服务需要的分布式后端，例如 HCCL 或 NCCL 服务。

Note

HCCL的全称是华为集合通信库（Huawei Collective Communication Library），NCCL的全称是英伟达集合通信库（NVIDIA Collective Communication Library）。
init 方法应该在 set_context 方法之后使用。
在运行以下示例之前，用户需要预设通信环境变量，请查看mindspore.communication的文档注释。

参数：

backend_name (str) – 分布式后端的名称，可选HCCL或NCCL。如果未设置则根据硬件平台类型（device_target）进行推断，默认值为None。

异常：

TypeError – 参数 backend_name 不是字符串。
RuntimeError – 1）硬件设备类型无效；2）后台服务无效；3）分布式计算初始化失败；4）后端是HCCL的情况下，未设置环境变量 RANK_ID 或 MINDSPORE_HCCL_CONFIG_PATH 的情况下初始化HCCL服务。

支持平台：: Ascend GPU

样例：

>>> from mindspore.communication import init
>>> init()

mindspore.communication.release()[源代码]

释放分布式资源，例如 HCCL 或 NCCL 服务。

Note

release 方法应该在 init 方法之后使用。
在运行以下示例之前，用户需要预设通信环境变量，请查看mindspore.communication的文档注释。

异常：

RuntimeError - 在释放分布式资源失败时抛出。

支持平台：: Ascend GPU

样例：

>>> from mindspore.communication import init, release
>>> init()
>>> release()

mindspore.communication.get_rank(group=GlobalComm.WORLD_COMM_GROUP)[源代码]

在指定通信组中获取当前的设备序号。

Note

get_rank 方法应该在 init 方法之后使用。
在运行以下示例之前，用户需要预设通信环境变量，请查看mindspore.communication的文档注释。

参数：

group (str) - 通信组名称，通常由 create_group 方法创建，否则将使用默认组。默认值： GlobalComm.WORLD_COMM_GROUP 。

返回：

int, 调用该方法的进程对应的组内序号。

异常：

TypeError – 在参数 group 不是字符串时抛出。
ValueError – 在后台不可用时抛出。
RuntimeError – 在 HCCL 或 NCCL 服务不可用时抛出。

支持平台：: Ascend GPU

样例：

>>> from mindspore.communication import init, get_rank
>>> init()
>>> rank_id = get_rank()
>>> print(rank_id)
>>> # the result is the rank_id in world_group

mindspore.communication.get_group_size(group=GlobalComm.WORLD_COMM_GROUP)[源代码]

获取指定通信组实例的rank_size。

Note

get_group_size 方法应该在 init 方法之后使用。
在运行以下示例之前，用户需要预设通信环境变量，请查看mindspore.communication的文档注释。

参数：

group (str) - 指定工作组实例（由 create_group 方法创建）的名称，支持数据类型为str，默认值为 WORLD_COMM_GROUP 。

返回：

指定通信组实例的rank_size，数据类型为int。

异常：

TypeError – 在参数 group 不是字符串时抛出。
ValueError – 在后台不可用时抛出。
RuntimeError – 在 HCCL 或 NCCL 服务不可用时抛出。

支持平台：: Ascend GPU

样例：

>>> import mindspore as ms
>>> from mindspore.communication.management import init, get_group_size
>>> ms.set_auto_parallel_context(device_num=8)
>>> init()
>>> group_size = get_group_size()
>>> print("group_size is: ", group_size)
group_size is: 8

mindspore.communication.get_world_rank_from_group_rank(group, group_rank_id)[源代码]

由指定通信组中的设备序号获取通信集群中的全局设备序号。

Note

GPU 版本的MindSpore不支持此方法。
参数 group 不能是 hccl_world_group。
get_world_rank_from_group_rank 方法应该在 init 方法之后使用。
在运行以下示例之前，用户需要预设通信环境变量，请查看mindspore.communication的文档注释。

参数：

group (str) - 传入的通信组名称，通常由 create_group 方法创建。
group_rank_id (int) - 通信组内的设备序号。

返回：

int, 通信集群中的全局设备序号。

异常：

TypeError – 参数 group 不是字符串或参数 group_rank_id 不是数字。
ValueError – 参数 group 是 hccl_world_group 或后台不可用。
RuntimeError – HCCL 服务不可用时，或者使用了GPU版本的MindSpore。

支持平台：: Ascend

样例：

>>> from mindspore import set_context
>>> from mindspore.communication.management import init, create_group, get_world_rank_from_group_rank
>>> set_context(device_target="Ascend")
>>> init()
>>> group = "0-4"
>>> rank_ids = [0,4]
>>> create_group(group, rank_ids)
>>> world_rank_id = get_world_rank_from_group_rank(group, 1)
>>> print("world_rank_id is: ", world_rank_id)
world_rank_id is: 4

mindspore.communication.get_group_rank_from_world_rank(world_rank_id, group)[源代码]

由通信集群中的全局设备序号获取指定用户通信组中的rank ID。

Note

GPU 版本的MindSpore不支持此方法。
参数 group 不能是 hccl_world_group。
get_group_rank_from_world_rank 方法应该在 init 方法之后使用。
在运行以下示例之前，用户需要预设通信环境变量，请查看mindspore.communication的文档注释。

参数：

world_rank_id (int) - 通信集群内的全局rank ID。
group (str) - 指定通信组实例（由 create_group 方法创建）的名称。

返回：

当前通信组内的rank_ID，数据类型为int。

异常：

TypeError – 在参数 group_rank_id 不是数字或参数 group 不是字符串时抛出。
ValueError – 在参数 group 是 hccl_world_group 或后台不可用时抛出。
RuntimeError – HCCL 服务不可用时，或者使用了GPU版本的MindSpore。

支持平台：: Ascend

样例：

>>> from mindspore import set_context
>>> from mindspore.communication.management import init, create_group, get_group_rank_from_world_rank
>>> set_context(device_target="Ascend")
>>> init()
>>> group = "0-4"
>>> rank_ids = [0,4]
>>> create_group(group, rank_ids)
>>> group_rank_id = get_group_rank_from_world_rank(4, group)
>>> print("group_rank_id is: ", group_rank_id)
group_rank_id is: 1

mindspore.communication.create_group(group, rank_ids)[源代码]

创建用户自定义的通信组实例。

Note

GPU 版本的MindSpore不支持此方法。
列表rank_ids的长度应大于1。
列表rank_ids内不能有重复数据。
create_group 方法应该在 init 方法之后使用。
PyNative模式下仅支持全局单通信组。
在运行以下示例之前，用户需要预设通信环境变量，请查看mindspore.communication的文档注释。

参数：

group (str) - 输入用户自定义的通信组实例名称，支持数据类型为str。
rank_ids (list) - 设备编号列表。

异常：

TypeError – 参数 group_rank_id 不是数字或参数 group 不是字符串。
ValueError – 列表rank_ids的长度小于1，或列表rank_ids内有重复数据，以及后台无效。
RuntimeError – HCCL 服务不可用时，或者使用了GPU版本的MindSpore。

支持平台：: Ascend

样例：

>>> from mindspore import set_context
>>> from mindspore.ops import operations as ops
>>> from mindspore.communication.management import init, create_group
>>> set_context(device_target="Ascend")
>>> init()
>>> group = "0-8"
>>> rank_ids = [0,8]
>>> create_group(group, rank_ids)
>>> allreduce = ops.AllReduce(group)

mindspore.communication.get_local_rank(group=GlobalComm.WORLD_COMM_GROUP)[源代码]

获取指定通信组中当前设备的本地设备序号。

Note

GPU 版本的MindSpore不支持此方法。
get_local_rank 方法应该在 init 方法之后使用。
在运行以下示例之前，用户需要预设通信环境变量，请查看mindspore.communication的文档注释。

参数：

group (str) - 通信组名称，通常由 create_group 方法创建，否则将使用默认组名称。默认值： WORLD_COMM_GROUP 。

返回：

int, 调用该方法的进程对应的通信组内本地设备序号。

异常：

TypeError – 在参数 group 不是字符串时抛出。
ValueError – 在后台不可用时抛出。
RuntimeError – HCCL 服务不可用时，或者使用了GPU版本的MindSpore。

支持平台：: Ascend

样例：

>>> import mindspore as ms
>>> from mindspore.communication.management import init, get_rank, get_local_rank
>>> ms.set_context(device_target="Ascend")
>>> ms.set_auto_parallel_context(device_num=16) # 2 server, each server with 8 NPU.
>>> init()
>>> world_rank = get_rank()
>>> local_rank = get_local_rank()
>>> print("local_rank is: {}, world_rank is {}".format(local_rank, world_rank))
local_rank is: 1, world_rank is 9

mindspore.communication.get_local_rank_size(group=GlobalComm.WORLD_COMM_GROUP)[源代码]

获取指定通信组的本地设备总数。

Note

GPU 版本的MindSpore不支持此方法。
get_local_rank_size 方法应该在 init 方法之后使用。
在运行以下示例之前，用户需要预设通信环境变量，请查看mindspore.communication的文档注释。

参数：

group (str) - 传入的通信组名称，通常由 create_group 方法创建，或默认使用 WORLD_COMM_GROUP 。

返回：

int, 调用该方法的进程对应的通信组设备总数。

异常：

TypeError – 在参数 group 不是字符串时抛出。
ValueError – 在后台不可用时抛出。
RuntimeError – HCCL 服务不可用时，或者使用了GPU版本的MindSpore。

支持平台：: Ascend

样例：

>>> import mindspore as ms
>>> from mindspore.communication.management import init, get_local_rank_size
>>> ms.set_context(device_target="Ascend")
>>> ms.set_auto_parallel_context(device_num=16) # 2 server, each server with 8 NPU.
>>> init()
>>> local_rank_size = get_local_rank_size()
>>> print("local_rank_size is: ", local_rank_size)
local_rank_size is: 8

mindspore.communication.destroy_group(group)[源代码]

注销用户通信组。

Note

GPU 版本的MindSpore不支持此方法。
参数 group 不能是 hccl_world_group。
destroy_group 方法应该在 init 方法之后使用。

参数：

group (str) - 被注销通信组实例（通常由 create_group 方法创建）的名称。

异常：

TypeError – 在参数 group 不是字符串时抛出。
ValueError – 在参数 group 是 hccl_world_group 或后台不可用时抛出。
RuntimeError – HCCL 服务不可用时，或者使用了GPU版本的MindSpore。

支持平台：: Ascend

mindspore.communication.HCCL_WORLD_COMM_GROUP: “hccl_world_group”字符串，指的是由HCCL创建的默认通信组。

mindspore.communication.NCCL_WORLD_COMM_GROUP: “nccl_world_group”字符串，指的是由NCCL创建的默认通信组。