参数面建链阶段【免费下载链接】hccl集合通信库Huawei Collective Communication Library简称HCCL是基于昇腾AI处理器的高性能集合通信库为计算集群提供高性能、高可靠的通信方案项目地址: https://gitcode.com/cann/hccl建链失败定位思路在调用通信算子时HCCL会通过参数面网络基于TCP协议进行socket连接创建以此来基于业务需要进行地址等信息交换此时如果出现某种故障导致部分rank未调用到预期的通信算子导致无法发起建链请求或由于网络连通性、行为一致性问题导致无法响应彼此之间的建链请求就会导致其他rank出现socket连接超时报错。由于HCCL的算法和算子调用顺序的原因建链超时会呈现在rank间有级联传递的情况因此如果发现建链超时需要优先找到故障点位置。HCCL在参数面建链阶段提供了下文所述机制来辅助问题快速定位。建链根节点定位机制考虑到建链问题的级联传播问题如rank0在和rank1建链等待超时而rank1在和rank2建链等待超时若此时rank1和rank2的建链由于网络或其他原因导致失败在rank0上最终也会上报和rank1的建链超时报错但失败的根因却在rank1和rank2之间。因此在集群中找到建链失败根节点位置是较为困难和繁琐的HCCL会在业务上建链失败后立即启动故障探测链路其主要的实现原理为建链失败根节点定位原理图如下所示每个rank在建链失败后会启动监听能够响应所有rank故障探测链路的server端。向无法响应自己业务建链请求的远端发起故障探测链路连接请求。如果远端无法响应自己的探测建链请求则认为和远端的链路或远端的业务进程存在问题产生探测失败事件。并向已经在server端建立成功的其他链路发送扩散该事件。如果远端建立起了探测链路则接收对端发送的探测失败事件并进行转发。这样如果出现任何单点问题导致的建链失败可以通过日志快速定位故障点的节点位置并进行下一步的问题定位。详细的定位流程可参考建链超时EI0006。如果经过探测无任何事件则很有可能是行为一致性问题也就是每个rank均已进入建链阶段并响应其他rank的故障探测请求但由于彼此调用的通信算子不一致导致链路互等超时一般是由于集群行为一致性问题请检查脚本、环境、版本、数据集等因素。如果需要参考通信算子的行为可以通过建链失败报错日志中关键字“Alloc transports failed”中对应的tag信息推测算子行为比如遍历每个rank的tag信息如果16rank通信域内15rank均为allgather1个rank为AllReduce则重点分析两个算子的调用逻辑差异。针对建链超时场景可快速判断是否为全量建链超时若非全量建链超时可先重点排查未上报建链超时报错的节点可参考的命令为for i in *;do cd $i;pwd;grep -rnc connection fail | grep -v :0 | wc -l; cd ..;done一致性校验机制HCCL在与对端成功创建socket链接后会互相交换算子入参、CANN版本等信息并与本端的信息做校验如果此时校验结果存在不一致的情况则会在CANN日志及打屏日志中上报错误并返回错误码。详细问题定位流程可参考参数一致性校验(EI0005)。单算子模式下为了保证性能HCCL仅在每个通信域新类型或算法的算子被首次调用时才会触发建链由于建链成功后才会进行一致性校验因此此特性无法拦截所有的下发不一致问题。报错阶段分析HCCL在通信算子参数面建链阶段会有以下几个常见的报错阶段场景针对Atlas A3 训练系列产品/Atlas A3 推理系列产品与Atlas A2 训练系列产品/Atlas A2 推理系列产品device网卡端口绑定失败可通过以下命令排查是否有端口绑定失败问题详细信息可参考参数面端口绑定失败EI0019。grep -rE socket type\[(0|1)\].*Please check the port status and whether the port is being used by other process参数面socket建链超时可通过以下命令排查是否有参数面建链失败问题详细信息可参考建链超时EI0006。grep -r wait socket establish timeout通信算子一致性校验失败可通过以下命令排查是否有一致性校验失败问题详细信息可参考参数一致性校验(EI0005)。grep -r CMD information .* check fail参数面端口绑定失败EI0019问题现象在CANN日志中存在关键字Please check the port status and whether the port is being used by other process.如下所示。此外需注意在通信域集群协商阶段也会有端口绑定失败问题可以根据报错日志中的socket type判断若type为0或者1则为参数面端口绑定失败若type为2则为通信域集群信息协商时host侧网卡端口绑定失败可参考server节点端口绑定失败EI0019。[ERROR] HCCL(1009464,all_reduce_test):2025-03-15-00:41:48.470.172 [hccl_socket.cc:110] [1009464][InitGroupStage][RanktableDetect] socket type[0], listen on ip[192.168.2.199] and specific port[16666] fail. Please check the port status and whether the port is being used by other process.可能原因当前rank或进程在通信算子参数面建链时需要绑定一个device侧网卡的端口但发现端口已被其他进程占用。解决方法HCCL使用device侧网卡的端口时默认需绑定16666端口因此若有多个进程执行在同一个device上且均会调用HCCL的通信算子接口那么就会出现端口已被其他进程绑定导致失败的问题。此时可先从业务上排查多个进程跑在同一个device上是否符合任务预期若符合任务预期结果可通过配置HCCL_NPU_SOCKET_PORT_RANGE环境变量启用多进程场景如export HCCL_NPU_SOCKET_PORT_RANGEautoQP内存资源申请相关EI0011在参数面建链阶段HCCL会创建QP如果device侧内存不足会上报OOM错误。请通过调整业务配置、减少ROCE链路的使用数量或释放部分内存解决问题。问题现象在打屏日志中存在关键字EI0011或Resource_Error_Insufficient_Device_Memory如下所示[PID: 2103452] 2025-11-03-20:18:46.447.213 Resource_Error_Insufficient_Device_Memory(EI0011): Failed to allocate [size: [0.25MB, 3MB], Affected by QP depth configuration.] bytes of NPU memory. Possible Cause: Allocation failure due to insufficient NPU memory. Solution: Stop unnecessary processes and ensure the required memory is available.解决方法调整业务配置如batchSize、减少ROCE链路的使用数量或释放部分内存解决问题。注意HCCL的其他内存申请如cclBuffer内存申请若出现OOM错误会由drv组件上报错误码并打印错误信息可根据报错信息或CANN日志中的堆栈判断是否为HCCL内存申请失败若为HCCL内存申请失败可通过配置HCCL_BUFFSIZE环境变量调整申请的内存大小。建链超时EI0006HCCL建链超时受环境变量HCCL_CONNECT_TIMEOUT的影响若在超时时间内对端无法响应业务建链请求则会上报“socket timeout”同时如果远端由于超时等故障退出已经建好的链路在等待数据交换的过程中也可能会出现“recv fail”的报错。问题现象在CANN日志中存在关键字“wait socket establish timeout”或“[InitChannelStage][Timeout]”如下所示[ERROR] HCCL(17528,python3):2026-03-18-10:33:52.113.403 [hccl_socket_manager.cc:797] [18744][Wait][LinkEstablish]wait socket establish timeout, role[1] rank[1] timeout[120 s] [ERROR] HCCL(17528,python3):2026-03-18-10:33:52.113.454 [hccl_socket_manager.cc:861] [18744][Wait][LinksEstablishCompleted] is failed. ret[9]. [ERROR] HCCL(17528,python3):2026-03-18-10:33:52.113.646 [hccl_socket_manager.cc:623] [18744] _________________________LINK_ERROR_INFO___________________________ [ERROR] HCCL(17528,python3):2026-03-18-10:33:52.113.650 [hccl_socket_manager.cc:624] [18744] | comm error, device[1] [ERROR] HCCL(17528,python3):2026-03-18-10:33:52.113.653 [hccl_socket_manager.cc:626] [18744] | dest_ip(user_rank) | dest_port | src_ip(user_rank) | src_port | MyRole | Status | TlsStatus | [ERROR] HCCL(17528,python3):2026-03-18-10:33:52.113.655 [hccl_socket_manager.cc:628] [18744] |----------------------|---------------|----------------------|--------------|------------|------------|----------------| [ERROR] HCCL(17528,python3):2026-03-18-10:33:52.113.706 [hccl_socket_manager.cc:583] [18744] | 192.0.2.199(0) | 16666 | 192.0.3.198(1) | 3234403008 | client | time out | DISABLE | LinkInfo [ERROR] HCCL(17528,python3):2026-03-18-10:33:52.113.942 [hccl_socket_manager.cc:836] [18744][Create][Sockets]Wait links establish completed failed, local role is client. ret[9][ERROR] HCCL(17528,python3):2026-03-18-10:33:52.113.964 [transport_manager.cc:1402] [18744][SetMachinePara]call trace: hcclRet - 9 [ERROR] HCCL(17528,python3):2026-03-18-10:33:52.114.027 [transport_manager.cc:1252] [18744][CreateLink][InitChannelStage][Timeout]SetMachinePara error. [ERROR] HCCL(17528,python3):2026-03-18-10:34:34.224.286 [detect_connect_anomalies.cc:494] [20039][CreateClientConnect]GetStatus fail, ret[9] [ERROR] HCCL(17528,python3):2026-03-18-10:34:43.141.949 [detect_connect_anomalies.cc:127] [18744]-------------------CONNECT TIMEOUT DETECT RESULT----------------------- [ERROR] HCCL(17528,python3):2026-03-18-10:34:43.141.966 [detect_connect_anomalies.cc:132] [18744]This node (server 192.168.200.100, device ID 1) detects that srcRank (server 192.168.200.100, device ID 1) fails to connect to dstRank (server 192.168.200.100, device ID 0). Continue to analyze the fault based on the logs of srcRank and dstRank. [ERROR] HCCL(17528,python3):2026-03-18-10:34:43.141.970 [detect_connect_anomalies.cc:135] [18744]1. If the link setup timeout is reported on both ends, check the network connectivity between the two ends.2. If dstRank reports other exceptions, locate the cause based on the exception information of dstRank.3. If dstRank does not report any error, the possible cause is that the service process is suspended or exits in advance [ERROR] HCCL(17528,python3):2026-03-18-10:34:43.141.977 [detect_connect_anomalies.cc:143] [18744]---------------------------------------------------------------------- [ERROR] HCCL(17528,python3):2026-03-18-10:34:43.142.013 [transport_manager.cc:1325] [18744][InitChannelStage][Timeout]Transport init error! createLink para:rank[1]-localUserrank[1]-localIpAddr[192.168.200.100/1], remoteRank[0]-remoteUserrank[0]-remoteIpAddr[192.168.200.100/0], machineType[1], linkMode[1], isUsedRdma[0], tag[HcomAllReduce_6629421139219749105_0] [ERROR] HCCL(17528,python3):2026-03-18-10:34:43.142.040 [transport_manager.cc:1214] [18744][TransportManager][PrintErrorInfo]local rank information: nicType[VNIC_TYPE], logicSuperPodId is not set, phySuperPodId[287454020]. [ERROR] HCCL(17528,python3):2026-03-18-10:34:43.142.095 [transport_manager.cc:256] [18111][checkSubCommLinkThreadsStatus]call trace: hcclRet - 9 [ERROR] HCCL(17528,python3):2026-03-18-10:34:43.142.101 [transport_manager.cc:363] [18111][AllocSubCommLinks]call trace: hcclRet - 9 [ERROR] HCCL(17528,python3):2026-03-18-10:34:43.142.105 [transport_manager.cc:672] [18111][Alloc]call trace: hcclRet - 9 [ERROR] HCCL(17528,python3):2026-03-18-10:34:43.142.108 [hccl_communicator_host.cc:6370] [18111][AllocAlgResource]Alloc transports failed, tag[HcomAllReduce_6629421139219749105_0_device] [ERROR] HCCL(17528,python3):2026-03-18-10:34:43.142.120 [hccl_communicator_host.cc:4325] [18111][HcclCommunicator][ExecOp] AllocAlgResource failed, algName[AllReduceRingFor91093Executor] [ERROR] HCCL(17528,python3):2026-03-18-10:34:43.142.145 [hccl_communicator_host.cc:2858] [18111][AllReduce]call trace: hcclRet - 9 [ERROR] HCCL(17528,python3):2026-03-18-10:34:43.142.152 [hccl_comm.cc:306] [18111][HcclComm][HcomAllReduce_6629421139219749105_0]errNo[0x0000000000000009] index[0] [ERROR] HCCL(17528,python3):2026-03-18-10:34:43.142.156 [hcom.cc:515] [18111][AllReduce][Result]errNo[0x0000000005010009] hcclComm AllReduce error, tag[HcomAllReduce_6629421139219749105_0], input_ptr[0x12e083e00200], output_ptr[0x12e086600400], count[10485888], data_type[float32], op[sum] [ERROR] HCCL(17528,python3):2026-03-18-10:34:43.142.164 [hcom_ops_kernel_info_store.cc:807] [18111][HcomAllReduceOpKernel]call trace: hcclRet - 9 [ERROR] HCCL(17528,python3):2026-03-18-10:34:43.142.169 [hcom_ops_kernel_info_store.cc:358] [18111][HCCLOpsKernel]call trace: hcclRet - 9根据日志确认需排查的建链对端若报错日志中打印了“DETECT EVENT LIST”可先重点关注日志中失败的建链对如上日志示例中需先排查“DETECT EVENT[1]”异常事件显示的127.10.0.1节点的device7和127.10.0.1节点的device6之间的建链失败根因。若报错日志中没有打印“DETECT EVENT LIST”可从报错日志的LINK_ERROR_INFO表格中获取建链两端的device ip同时可从“Transport init error! createLink para:”关键日志信息中获取本端和对端所在的节点信息格式为[hostIp/deviceId]如下所示执行grep -r Transport init error! createLink para: debug/plog/plog-*.log得到如下信息[ERROR] HCCL(3215542,all_reduce_test):2025-11-20-18:18:03.114.306 [transport_manager.cc:886] [3215599][InitChannelStage][Timeout]Transport init error! createLink para:rank[2]-localUserrank[2]-localIpAddr[127.10.0.1/2], remoteRank[1]-remoteUserrank[1]-remoteIpAddr[127.10.0.1/1], machineType[1], linkMode[1], isUsedRdma[0], tag[AllReduce_127.10.0.1%enp_60000_0_1763633852475745localUserrank本端rank编号。localIpAddr本端的节点Ip信息。remoteUserrank对端rank编号。remoteIpAddr对端的节点Ip信息。tag通信算子标识符。获取到需要排查的建链失败对端信息之后便可结合两端的CANN日志做进一步分析。确认对端行为排查是否有卡间行为不一致由于参数面建链是一个两端的互动流程需要两端在超时时间内均发起建链请求才能创建成功否则因为等待超时而报错因此可以根据本端的报错信息中找到对端的节点信息查看对端的日志做进一步的判断图 1排查思路排查点1若对端没有任何报错日志说明对端可能没有同步下发对应的通信算子因此本端无法等待到对端的建链请求反馈最终等待超时。需从业务上排查两端的通信算子下发行为是否一致。排查点2若对端发生了除了参数面建链超时外的其他报错则需要先排查对端的报错原因。排查点3若对端也发生了参数面建链超时报错但对端的报错信息中并不在和本端建链而是和其他节点建链则需要按照流程先排查对端的参数面建链超时原因。排查点4若对端也在和本端参数面建链超时可先排查两端的报错时间是否超过了建链等待时间如超过了建链超时时间需要业务上排查两端通信算子下发超时时间的根因。建链等待时间可通过HCCL_CONNECT_TIMEOUT指定默认为120秒可在CANN日志的run目录下通过grep -r HCCL_CONNECT_TIMEOUT run/plog/查询当前业务配置的超时时间。排查点5若对端和本端的参数面建链超时在建链超时时间内则需要进一步排查两端的网络连通性排查两端的tls开关是否一致若两端的tls开关不一致则socket创建时会校验失败导致两端均建链超时可以通过以下方法确认两端的tls开关报错日志的LINK_ERROR_INFO表格中的status表示的是当前卡的tls状态UNKNOWN表示未获取到DISABLE表示未开启ENABLE表示开启。在节点的log日志中执行grep -r TLS SWITCH log/run/device-*获取tls状态run/device-0/device-2849330_20251024153927364.log:[INFO] HCCP(2988,hccp_service.bin):2025-10-24-15:39:26.133.826 [rs_ssl.c:1529]tid:2988,rs_ssl_init(1529) : TLS SWITCH (1) run/device-1/device-2849331_20251024153928174.log:[INFO] HCCP(30877,hccp_service.bin):2025-10-24-15:39:25.142.466 [rs_ssl.c:1529]tid:30877,rs_ssl_init(1529) : TLS SWITCH (0)通过hccn_tool工具查看节点的tls配置for i in {0..7}; do hccn_tool -i $i -tls -g ; done | grep switch# for i in {0..1}; do hccn_tool -i $i -tls -g ; done | grep switch dev_id:0, tls switch[0](https://link.gitcode.com/i/64646583509339bd59f88a550df4a4eb), tls preconfigured[1](https://link.gitcode.com/i/c21c1fa8aeafe5763365647977fa5258), tls alarm time threshold[60]days dev_id:1, tls switch[1](https://link.gitcode.com/i/64646583509339bd59f88a550df4a4eb), tls preconfigured[1](https://link.gitcode.com/i/c21c1fa8aeafe5763365647977fa5258), tls alarm time threshold[60]days若建链的两端在不同的节点上则需要检查本端和对端的device网口之间的网络连通性使用hccn_tool命令在其中一个节点ping另外一个节点的device iphccn_tool -i {node} -ping -g address {对端ip}若两个rank之间ping不通或者有网口是down的请联系实验室管理员排查对应网卡及交换机的配置。若使用Atlas A3 训练系列产品/Atlas A3 推理系列产品中的超节点请注意检查是否错误地将不同物理超节点下的节点配置成为一个逻辑超节点这种情况下HCCL会错误地认为两个节点能够通过超节点内的vnic进行通信从而导致互等超时。可以通过如下日志确认两端的链路类型和物理超节点信息链路类型为vnic且两端的物理超节点ID不相同分别是0和1但由于配置了相同的逻辑超节点IDlogic_1因此选择vnic链路进行通信导致超时可以通过修改或者取消HCCL_LOGIC_SUPERPOD_ID配置进行修复。本端日志debug/plog/plog-3003627_20260205184335411.log:14:[ERROR] HCCL(3003627,scatter_test):2026-02-05-18:44:26.379.547 [transport_manager.cc:885] [3003959][TransportManager][PrintErrorInfo]local rank information: nicType[VNIC_TYPE], logicSuperPodId[logic_1], phySuperPodId[0]. Note: Do not configure ranks belonging to different physical superpod ID info a single logical superpod ID远端日志debug/plog/plog-3003628_20260205184354321.log:14:[ERROR] HCCL(3003628,scatter_test):2026-02-05-18:44:26.379.542 [transport_manager.cc:885] [3003959][TransportManager][PrintErrorInfo]local rank information: nicType[VNIC_TYPE], logicSuperPodId[logic_1], phySuperPodId[1]. Note: Do not configure ranks belonging to different physical superpod ID info a single logical superpod ID需注意当前故障链路产生探测失败事件的阈值默认为20s用户可以通过HCCL_DFS_CONFIG环境变量中connection_fault_detction_time的字段进行调整配置为0则关闭此功能。在集群规模较大或伴随严重的卡间不同步现象时可能需要增大此配置以确保探测结果正确性。在部分复杂业务场景下建链超时、执行超时可能同时出现在单次业务中需要基于探测结果进行多次跳转才能定位到故障点。因此请以探测节点的日志确认是否已经到达根节点。故障根节点通常会有其他报错、或无任何异常日志或和其他rank互等超时。参数一致性校验(EI0005)问题现象在打屏日志中存在关键字The arguments for collective communication are inconsistent between ranks如下所示EI0005: 2024-04-24-06:32:27.781.599 The arguments for collective communication are inconsistent between ranks:parameter count, local end 16512, remote end 8320 TraceBack (most recent call last): Transport init error. Reason: [Create] [DestLink]Create Dest error! createLink para:rank[5]-localUserrank[4]-localIpAddr[127.10.0.1], dst_rank[6]-remoteUserrank[7]-remote_ip_addr[127.10.0.1] Transport init error. Reason: [Create] [DestLink]Create Dest error! createLink para:rank[5]-localUserrank[4]-localIpAddr[127.10.0.1], dst_rank[4]-remoteUserrank[5]-remote_ip_addr[127.10.0.1] call hccl op:HcomAllReduce(HcomAllReduce) load task fail[FUNC:Distribute][FILE:hccl_task_info.cc] [LINE:329] [[{[node Ge0p3_0]}]]或在CANN日志中存在关键字CMD information *** check fail如下所示[ERROR] HCCL(3743927,all_reduce_test):2025-10-25-16:11:16.831.640 [rank_consistentcy_checker.cc:429] [3743951][InitChannelStage][ParameterConflict]CMD information tag check fail. local[AllGather_127.10.0.1%enp_60000_0_1761379874757928], remote[AllReduce_127.10.0.1%enp_60000_0_1761379874757928] [ERROR] HCCL(3743927,all_reduce_test):2025-10-25-16:11:16.831.666 [rank_consistentcy_checker.cc:439] [3743951][InitChannelStage][ParameterConflict]CMD information cmdType check fail. local[6], remote[2] [ERROR] HCCL(3743927,all_reduce_test):2025-10-25-16:11:16.831.679 [rank_consistentcy_checker.cc:439] [3743951][InitChannelStage][ParameterConflict]CMD information op check fail. local[255], remote[0]可能原因参数面建链时在socket建立完成后会进行两端的参数一致性校验校验的范围包括算子标识符tag、算子类型cmdType、规约类型op、数据量count、HCCL Buffer的大小cclbufferSize、数据类型dataType等可根据报错里的信息确定不一致的数据。例如下述示例中两端的算子标识符tag不一致导致通信算子在建链时一致性校验不通过local和remote中的数据为两端不一致的数据。其中参数不一致的两端节点信息可以通过Transport init error! createLink para:报错日志确认比如执行grep -r Transport init error! createLink para:查看结果如下[ERROR] HCCL(3215542,all_reduce_test):2025-11-20-18:18:03.114.306 [transport_manager.cc:886] [3215599][InitChannelStage][Timeout]Transport init error! createLink para:rank[2]-localUserrank[2]-localIpAddr[127.10.0.1/2], remoteRank[1]-remoteUserrank[1]-remoteIpAddr[127.10.0.1/1], machineType[1], linkMode[1], isUsedRdma[0], tag[AllReduce_127.10.0.1%enp_60000_0_1763633852475745localUserrank本端rank编号。localIpAddr本端的节点IP信息。remoteUserrank对端rank编号。remoteIpAddr对端的节点IP信息。tag通信算子标识符。解决方法如果在未启用SuperKernel时功能正常但启用了SuperKernel后出现初始化不一致的问题此时建议将HCCL算子移出SuperKernel的标定范围。具体操作方法可参考《PyTorch图模式使用指南》中的“max-autotune模式功能 图内标定SuperKernel范围”章节。根据报错信息从业务上排查参数校验不一致的两端下发的算子不一致的根因。注意日志中部分打印为枚举值其中cmdType为算子类型op为规约类型枚举值对应关系表格如下cmdType枚举值算子类型1BroadCast2AllReduce3Reduce4Send5Receive6AllGather7ReduceScatter8AlltoAllV9AlltoAllVC10AlltoAll11Gather12Scatter13BatchSendRecv16AllGatherV17ReduceScatterVop枚举值对应的规约类型如下表所示op枚举值规约类型0SUM1PROD2MAX3MIN255非Reduce算子【免费下载链接】hccl集合通信库Huawei Collective Communication Library简称HCCL是基于昇腾AI处理器的高性能集合通信库为计算集群提供高性能、高可靠的通信方案项目地址: https://gitcode.com/cann/hccl创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考