link

Applicability

Product	Supported
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 the Atlas A2 training products/Atlas A2 inference products, only the Atlas 800I A2 inference server, Atlas 300I A2 inference card, and A200I A2 Box heterogeneous components 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 ranktable 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	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 the "Reference" > "Cluster Information Configuration" in HCCL User Guide. 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

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 the "Reference" > "Cluster Information Configuration" in HCCL User Guide. 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.

Restrictions

All clusters in the communicator must initiate the request simultaneously.
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 underlying layer of the link. Before link establishment, configure memory pools or register the memory for the cache to be transmitted.
This API does not support being called in a forked child process.
Up to 16 links can be established concurrently; additional requests are queued at the underlying layer.
Ensure that no circular dependencies exist when establishing links for multiple communicators.
If links are established concurrently and a device involved in the link establishment is in a down state, some link establishment processes may time out. To ensure successful link establishment using non-down devices, run the hccn_tool -i ${device_id} -tls -s enable 1 command for all devices involved in the link establishment.

Parent topic: LLMDataDist