link

Applicability

Product	Supported (√/x)
Ascend 950PR/Ascend 950DT	x
Atlas A3 training products/Atlas A3 inference products	√
Atlas A2 training products/Atlas A2 inference products	√
Atlas 200I/500 A2 inference products	x
Atlas inference products	x
Atlas training products	x

Note: For Atlas A2 training products/Atlas A2 inference products, only the Atlas 800I A2 inference server and A200I A2 Box heterogeneous subrack are supported.

Function Description

Establishes a bilateral link by creating a communicator. (The more user-friendly link_clusters API for unilateral link establishment is recommended, which does not require specifying rank table information.)

If RDMA NIC communication is required within a single server, set the environment variable HCCL_INTRA_ROCE_ENABLE=1.

Prototype

link(comm_name: str, cluster_rank_info: Dict[int, int], rank_table: str) -> int

Parameters

Parameter	Data Type	Value Description
comm_name	str	Communicator name. The value length must be less than 128 characters.
cluster_rank_info	Dict[int, int]	Mapping between cluster IDs and rank IDs. Example: {1: 0, 2: 1}
rank_table	str	Specifies the NPU resource information for collective communication. For details, see "Reference > Cluster Information Configuration" in Huawei Collective Communication Library (HCCL). The following is a configuration example: { "server_count": "2", "server_list": [ { "device": [ { "device_id": "0", "device_ip": "x.x.x.x", "rank_id": "0" }, ], "server_id": "xxxx" },{ "device": [ { "device_id": "0", "device_ip": "x.x.x.x", "rank_id": "1" }, ], "server_id": "xxxx" } ], "status": "completed", "version": "1.0" }

Parameter

Data Type

Value Description

comm_name

str

Communicator name.

The value length must be less than 128 characters.

cluster_rank_info

Dict[int, int]

Mapping between cluster IDs and rank IDs.

Example: {1: 0, 2: 1}

rank_table

str

Specifies the NPU resource information for collective communication. For details, see "Reference > Cluster Information Configuration" in Huawei Collective Communication Library (HCCL). The following is a configuration example:

{
    "server_count": "2",
    "server_list": [
        {
            "device": [
                {
                    "device_id": "0",
                    "device_ip": "x.x.x.x",
                    "rank_id": "0"
                },
            ],
            "server_id": "xxxx"
        },{
            "device": [
                {
                    "device_id": "0",
                    "device_ip": "x.x.x.x",
                    "rank_id": "1"
                },
            ],
            "server_id": "xxxx"
        }
    ],
    "status": "completed",
    "version": "1.0"
}

Example

Click GitCode, select the matching version, and obtain the sample from the examples/python directory.

Returns

In normal cases, a communicator ID is returned.

If a parameter is incorrect, a TypeError or ValueError may be thrown.

Constraints

All clusters in the communicator need to initiate the request at the same time.
A maximum of four nodes are supported in a communicator.
It is recommended that the number of communicator be less than or equal to 16. A maximum of 512 communicators are supported. Excessive links may cause OOM errors and deteriorate the cache transmission performance.
Memory descriptors are exchanged in the communicator at the bottom layer of the link. Before link establishment, configure memory pools or register the memory for cache to be transmitted.
Subprocesses cannot be called in fork mode.
A maximum of 16 links can be established concurrently. If more than 16 links are established, they will be queued at the bottom layer.
Ensure that cyclic dependency does not occur during multi-communicator link establishment.

Parent topic: LLMDataDist