mindspore.communication

集合通信接口。

注意，集合通信接口需要先配置好通信环境变量。

针对Ascend/GPU/CPU设备，推荐使用msrun启动方式，无第三方以及配置文件依赖。详见 msrun启动 。

class mindspore.communication.GlobalComm

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

• BACKEND ：使用的通信库， "hccl" 、 "nccl" 或者 "mccl" 。 "hccl" 代表华为集合通信库HCCL， "nccl" 代表英伟达集合通信库NCCL， "mccl" 代表MindSpore集合通信库MCCL。

• WORLD_COMM_GROUP ：全局通信域， "hccl_world_group" 、 "nccl_world_group" 或者 "mccl_world_group" 。

mindspore.communication.init(backend_name=None)

初始化通信服务需要的分布式后端，例如 HCCL 、 NCCL 或 MCCL 服务。通常在分布式并行场景下使用，并在使用通信服务前设置。

说明

• HCCL的全称是华为集合通信库（Huawei Collective Communication Library）。

• NCCL的全称是英伟达集合通信库（NVIDIA Collective Communication Library）。

• MCCL的全称是MindSpore集合通信库（MindSpore Collective Communication Library）。

• 在Ascend硬件平台下，init() 接口的设置需要在创建Tensor和Parameter之前，以及所有算子和网络的实例化和运行之前。

参数：

• backend_name (str) - 分布式后端的名称，可选 "hccl" 、 "nccl" 或者 "mccl" 。在Ascend硬件平台下，应使用 "hccl" ，在GPU硬件平台下，应使用 "nccl" ，在CPU硬件平台下，应使用 "mccl" 。如果未设置则根据硬件平台类型（device_target）自动进行推断，默认值： None 。

异常：

• TypeError - 参数 backend_name 不是字符串。

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

支持平台：

Ascend GPU CPU

样例：

说明

运行以下样例之前，需要配置好通信环境变量。

针对Ascend/GPU/CPU设备，推荐使用msrun启动方式，无第三方以及配置文件依赖。详见 msrun启动 。

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

mindspore.communication.release()

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

说明

• release 方法应该在 init 方法之后使用。如果不使用，则在程序结束时资源才会自动释放。

异常：

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

支持平台：

Ascend GPU CPU

样例：

说明

运行以下样例之前，需要配置好通信环境变量。

针对Ascend/GPU/CPU设备，推荐使用msrun启动方式，无第三方以及配置文件依赖。详见 msrun启动 。

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

mindspore.communication.get_rank(group=GlobalComm.WORLD_COMM_GROUP)

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

说明

• get_rank 方法应该在 init 方法之后使用。

参数：

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

返回：

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

异常：

• TypeError - 在参数 group 不是字符串时抛出。

• ValueError - 在后台不可用时抛出。

• RuntimeError - 在 HCCL 或 NCCL 或 MCCL 服务不可用时抛出。

支持平台：

Ascend GPU CPU

样例：

说明

运行以下样例之前，需要配置好通信环境变量。

针对Ascend/GPU/CPU设备，推荐使用msrun启动方式，无第三方以及配置文件依赖。详见 msrun启动 。

>>> 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。

说明

• get_group_size 方法应该在 init 方法之后使用。

参数：

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

返回：

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

异常：

• TypeError - 在参数 group 不是字符串时抛出。

• ValueError - 在后台不可用时抛出。

• RuntimeError - 在 HCCL 或 NCCL 或 MCCL 服务不可用时抛出。

支持平台：

Ascend GPU CPU

样例：

说明

运行以下样例之前，需要配置好通信环境变量。

针对Ascend/GPU/CPU设备，推荐使用msrun启动方式，无第三方以及配置文件依赖。详见 msrun启动 。

>>> import mindspore as ms
>>> from mindspore.communication 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)

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

说明

• MindSpore的GPU和CPU版本不支持此方法。

• 参数 group 不能是 "hccl_world_group"。

• get_world_rank_from_group_rank 方法应该在 init 方法之后使用。

参数：

• group (str) - 传入的通信组名称，通常由 create_group 方法创建。

• group_rank_id (int) - 通信组内的设备序号。

返回：

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

异常：

• TypeError - 参数 group 不是字符串或参数 group_rank_id 不是数字。

• ValueError - 参数 group 是 "hccl_world_group" 或后台不可用。

• RuntimeError - HCCL 服务不可用时，或者使用了MindSpore的GPU或CPU版本。

支持平台：

Ascend GPU CPU

样例：

说明

运行以下样例之前，需要配置好通信环境变量。

针对Ascend/GPU/CPU设备，推荐使用msrun启动方式，无第三方以及配置文件依赖。详见 msrun启动 。

>>> import mindspore as ms
>>> from mindspore import set_context
>>> from mindspore.communication import init, create_group, get_world_rank_from_group_rank, get_rank
>>> set_context(mode=ms.GRAPH_MODE, device_target="Ascend")
>>> init()
>>> group = "0-4"
>>> rank_ids = [0,4]
>>> if get_rank() in rank_ids:
...     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。

说明

• MindSpore的GPU和CPU版本不支持此方法。

• 参数 group 不能是 "hccl_world_group"。

• get_group_rank_from_world_rank 方法应该在 init 方法之后使用。

参数：

• world_rank_id (int) - 通信集群内的全局rank ID。

• group (str) - 指定通信组实例（由 create_group 方法创建）的名称。

返回：

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

异常：

• TypeError - 在参数 world_rank_id 不是数字或参数 group 不是字符串时抛出。

• ValueError - 在参数 group 是 "hccl_world_group" 或后台不可用时抛出。

• RuntimeError - HCCL 服务不可用时，或者使用了MindSpore的GPU或CPU版本。

支持平台：

Ascend GPU CPU

样例：

说明

运行以下样例之前，需要配置好通信环境变量。

针对Ascend/GPU/CPU设备，推荐使用msrun启动方式，无第三方以及配置文件依赖。详见 msrun启动 。

>>> import mindspore as ms
>>> from mindspore import set_context
>>> from mindspore.communication import init, create_group, get_group_rank_from_world_rank, get_rank
>>> set_context(mode=ms.GRAPH_MODE, device_target="Ascend")
>>> init()
>>> group = "0-4"
>>> rank_ids = [0,4]
>>> if get_rank() in rank_ids:
...     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)

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

说明

• MindSpore的GPU和CPU版本不支持此方法。

• 列表rank_ids的长度应大于1。

• 列表rank_ids内不能有重复数据。

• create_group 方法应该在 init 方法之后使用。

• 如果没有使用mpirun启动，PyNative模式下仅支持全局单通信组。

参数：

• group (str) - 输入用户自定义的通信组实例名称，支持数据类型为str。

• rank_ids (list) - 设备编号列表。

异常：

• TypeError - 参数 group 不是字符串或参数 rank_ids 不是列表。

• ValueError - 列表rank_ids的长度小于1，或列表 rank_ids 内有重复数据，以及后台无效。

• RuntimeError - HCCL 服务不可用时，或者使用了MindSpore的GPU或CPU版本。

支持平台：

Ascend GPU CPU

样例：

说明

运行以下样例之前，需要配置好通信环境变量。

针对Ascend/GPU/CPU设备，推荐使用msrun启动方式，无第三方以及配置文件依赖。详见 msrun启动 。

>>> import mindspore as ms
>>> from mindspore import set_context
>>> from mindspore import ops
>>> from mindspore.communication import init, create_group, get_rank
>>> set_context(mode=ms.GRAPH_MODE, device_target="Ascend")
>>> init()
>>> group = "0-7"
>>> rank_ids = [0,7]
>>> if get_rank() in rank_ids:
...     create_group(group, rank_ids)
...     allreduce = ops.AllReduce(group)

mindspore.communication.get_local_rank(group=GlobalComm.WORLD_COMM_GROUP)

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

说明

• MindSpore的GPU和CPU版本不支持此方法。

• get_local_rank 方法应该在 init 方法之后使用。

参数：

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

返回：

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

异常：

• TypeError - 在参数 group 不是字符串时抛出。

• ValueError - 在后台不可用时抛出。

• RuntimeError - HCCL 服务不可用时，或者使用了MindSpore的GPU或CPU版本。

支持平台：

Ascend GPU CPU

样例：

说明

运行以下样例之前，需要配置好通信环境变量。

针对Ascend/GPU/CPU设备，推荐使用msrun启动方式，无第三方以及配置文件依赖。详见 msrun启动 。

>>> import mindspore as ms
>>> from mindspore.communication 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)

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

说明

• MindSpore的GPU和CPU版本不支持此方法。

• get_local_rank_size 方法应该在 init 方法之后使用。

参数：

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

返回：

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

异常：

• TypeError - 在参数 group 不是字符串时抛出。

• ValueError - 在后台不可用时抛出。

• RuntimeError - HCCL 服务不可用时，或者使用了MindSpore的GPU或CPU版本。

支持平台：

Ascend GPU CPU

样例：

说明

运行以下样例之前，需要配置好通信环境变量。

针对Ascend/GPU/CPU设备，推荐使用msrun启动方式，无第三方以及配置文件依赖。详见 msrun启动 。

>>> import mindspore as ms
>>> from mindspore.communication 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)

注销用户通信组。

说明

• MindSpore的GPU和CPU版本不支持此方法。

• 参数 group 不能是 "hccl_world_group"。

• destroy_group 方法应该在 init 方法之后使用。

参数：

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

异常：

• TypeError - 在参数 group 不是字符串时抛出。

• ValueError - 在参数 group 是 "hccl_world_group" 或后台不可用时抛出。

• RuntimeError - HCCL 服务不可用时，或者使用了MindSpore的GPU或CPU版本。

支持平台：

Ascend GPU CPU

样例：

说明

运行以下样例之前，需要配置好通信环境变量。

针对Ascend/GPU/CPU设备，推荐使用msrun启动方式，无第三方以及配置文件依赖。详见 msrun启动 。

>>> import mindspore as ms
>>> from mindspore import set_context
>>> from mindspore import ops
>>> from mindspore.communication import init, create_group, destroy_group, get_rank
>>> set_context(mode=ms.GRAPH_MODE, device_target="Ascend")
>>> init()
>>> group = "0-2"
>>> rank_ids = [0,2]
>>> if get_rank() in rank_ids:
...     create_group(group, rank_ids)
...     destroy_group(group)

mindspore.communication.get_process_group_ranks(group=GlobalComm.WORLD_COMM_GROUP)

获取指定通信组中的进程，并将通信组中的进程编号以列表方式返回。

参数：

• group (str，可选) - 工作的通信组。默认值：GlobalComm.WORLD_COMM_GROUP （即Ascend平台为 "hccl_world_group" ，GPU平台为 "nccl_world_group" ）。

返回：

List (List[int]) - 指定通信组中的进程编号列表。

异常：

• TypeError - group 不是字符串。

• RuntimeError - 如果目标设备无效，或者后端无效，或者分布式初始化失败。

支持平台：

Ascend GPU

样例：

说明

运行以下样例之前，需要配置好通信环境变量。

针对Ascend/GPU/CPU设备，推荐使用msrun启动方式，无第三方以及配置文件依赖。详见 msrun启动 。

该样例需要在4卡环境下运行。

>>> import numpy as np
>>> from mindspore.communication import init, get_process_group_ranks
>>>
>>> init()
>>> output = get_process_group_ranks()
>>> print(output)
[0, 1, 2, 3]

mindspore.communication.HCCL_WORLD_COMM_GROUP

"hccl_world_group" 字符串，指的是由HCCL创建的默认通信组。在Ascend硬件平台下，初始化通信服务后该字符串与 GlobalComm.WORLD_COMM_GROUP 等价，推荐使用 GlobalComm.WORLD_COMM_GROUP 获取当前全局通信组。

mindspore.communication.NCCL_WORLD_COMM_GROUP

"nccl_world_group" 字符串，指的是由NCCL创建的默认通信组。在GPU硬件平台下，初始化通信服务后该字符串与 GlobalComm.WORLD_COMM_GROUP 等价，推荐使用 GlobalComm.WORLD_COMM_GROUP 获取当前全局通信组。

mindspore.communication.MCCL_WORLD_COMM_GROUP

"mccl_world_group" 字符串，指的是由MCCL创建的默认通信组。在CPU硬件平台下，初始化通信服务后该字符串与 GlobalComm.WORLD_COMM_GROUP 等价，推荐使用 GlobalComm.WORLD_COMM_GROUP 获取当前全局通信组。