HCCL故障定位思路三阶段定界、多级检索关键字与故障码体系详解【免费下载链接】hccl集合通信库Huawei Collective Communication Library简称HCCL是基于昇腾AI处理器的高性能集合通信库为计算集群提供高性能、高可靠的通信方案项目地址: https://gitcode.com/cann/hccl本篇技术文章基于 HCCL 用户指南中的《定位思路》文档展开系统讲解昇腾集群上 HCCL 通信故障的定位方法论如何借助故障码体系与 CANN 日志完成快速定界如何依据通信域初始化、参数面建链、通信算子执行三大阶段划分排查路径以及如何运用 HCCL 多级检索关键字、算子级入参日志与环境变量生效值查询等手段锁定根因。读完后你将掌握一套从看到报错到定位根节点的完整故障诊断工作流并了解各诊断能力在 HCCL 源码中的实现落点。一、定位前必须掌握的基础认知在开始故障定位之前需要先建立两个基础认知。故障码覆盖大部分常见问题。HCCL 的故障码EI****/EJ****覆盖了大部分常见故障场景。如果报错中未包含故障码信息或故障码为EI9999则可能是较为少见的故障场景或 HCCL 内部问题此时需要基于实际的 CANN 日志和代码进行分析如果仍无法解决应联系技术支持。大集群需要定位根节点。对于没有清晰首报错的问题尤其是大集群需要梳理每个 rank 的行为通过 rank 之间的依赖关系找到根节点——即真正先出错的 rank其余 rank 往往只是被等待方超时。面对这个难题HCCL 提供了建链根节点定位能力和集群心跳能力并会在对应的常见问题章节中给出诊断结果相关原理可参见 建链失败定位思路 与 集群心跳机制。此外需要注意该定位方法文档的适用边界文档中对 HCCL 实现机制的描述仅用于解释各类故障模式的机理辅助分析故障现象和定位原因若运行机制方面的内容与运行机制对应介绍文档不符请优先参考运行机制文档部分 CANN 日志示例会随版本更新而调整用户可重点关注日志中的关键信息如有较大差异请以实际日志信息为准当业务发生 HCCL 异常时CANN 日志中会有 HCCL 组件的报错日志若在 CANN 日志中没有发现 HCCL 组件的报错日志需排查是否有其他组件的报错信息若无任何报错则要注意训练脚本本身有无异常、是否存在 core dump 或进程卡住等情况。二、故障诊断相关环境变量故障定位依赖的关键环境变量共有四个它们决定了 HCCL 在异常场景下的上报行为与可观测性。2.1 HCCL_CONNECT_TIMEOUT 与 HCCL_EXEC_TIMEOUTHCCL_CONNECT_TIMEOUT 和 HCCL_EXEC_TIMEOUT 分别控制 HCCL 在建链阶段和执行阶段的超时时间。官方建议HCCL_CONNECT_TIMEOUT 配置的时间小于 HCCL_EXEC_TIMEOUT以保证在复杂场景下能够正确上报首报错信息从而区分异常业务进程被阻塞的原因是本端还是远端。这一点在定位大集群问题时尤为关键如果执行超时时间配置得过短算子执行阶段的超时会先于建链阶段的超时触发首报错就会指向执行阶段误导排查方向。2.2 HCCL_ENTRY_LOG_ENABLE算子级入参记录HCCL_ENTRY_LOG_ENABLE 是 HCCL 的算子级入参记录开关默认关闭。当集群行为一致性问题无法通过其他手段锁定异常原因时可以开启此环境变量记录不同 rank 上的集合通信行为通过卡间横向比对辅助找到行为差异的引入点。在源码层面该开关由环境变量解析模块 ParseEntryLogEnable 解析仅接受0或1非法取值会回退默认值并打印告警解析结果通过 GetExternalInputHcclEnableEntryLog 对外提供。以 AllReduce 为例AllReduceEntryLog 会在开关打开或强制记录时通过HCCL_RUN_INFO打印形如Entry-HcclAllReduce: tag[...], sendBuf[...], recvBuf[...], count[...], dataType[...], streamId[...], deviceId[...]的入参日志对于 AllToAllV 等携带变长数组参数的算子src/common/hccl_common.h 中的 PrintEntryArrayLog 会按 rank 区间分片打印 u64 数组以规避 512 字节栈缓冲截断。这一实现细节说明开启该开关后日志体积会随 rank 数增长建议在定位行为不一致问题时按需开启。2.3 HCCL_DEBUG_CONFIG模块级日志开关HCCL_DEBUG_CONFIG 是 HCCL 模块级日志开关进行算子开发调试时可以通过此配置分析算子内部的算法选择、任务编排等日志信息。需要注意的是该环境变量仅支持以下产品Atlas A3 训练系列产品/Atlas A3 推理系列产品Atlas A2 训练系列产品/Atlas A2 推理系列产品2.4 HCCL_DFS_CONFIG高级故障探测HCCL_DFS_CONFIG 是 HCCL 的高级故障探测配置能力详见环境变量说明建议保持默认值。三、HCCL 相关日志说明HCCL 的日志信息会记录在 CANN 日志中CANN 的相关日志说明可参考官方《日志参考》文档。HCCL 的日志分布有以下规律debug 目录HCCL 报错时会在 CANN 日志的 debug 目录下打印关键的故障信息同时在使用部分训练框架的业务场景下HCCL 也会在业务日志中打印关键的报错信息run 目录HCCL 在 CANN 日志的 run 目录下会默认记录一些关键运行日志如通信域的初始化与析构默认打印、通信算子的下发需开启HCCL_ENTRY_LOG_ENABLE等。3.1 通信域初始化日志通信域初始化时会打印如下关键日志Entry-HcclGetRootInfo:rootInfo[0x7fffcd65f130], deviceLogicId[0] Entry-HcclCommInitRootInfoConfigInner:ranks[16], rank[0], rootinfo: host ip[127.10.0.1] port[60000] nicDeploy[1] identifier[group_name_0], deviceLogicId[0]各字段含义字段含义ranks通信域大小rank当前 rank 在通信域内的 rank 编号rootinforoot 节点的信息identifier通信域名3.2 通信域析构日志Entry-HcclCommDestroy: op_base comm destroy begin该日志可作为判断某 rank 是否正常进入通信域销毁流程的依据。3.3 通信算子下发日志需开启 HCCL_ENTRY_LOG_ENABLEEntry-HcclAllReduce: tag[AllReduce_127.10.0.1%eth1_30000_0_1736576907435382], sendBuf[0x12e7bf550000], recvBuf[0x12e7bf550000], count[531260224], dataType[float32], op[sum], localRank[0], streamId[5],comm[0x331c9c00], deviceLogicId[0]各字段含义字段含义tag通信算子标识符sendBuf输入数据地址指针recvBuf输出数据地址指针count数据量dataType数据类型opreduce 计算类型localRank本端 rank 号streamId通信算子执行流comm通信域指针deviceLogicId通信算子下发的设备逻辑 ID横向比对不同 rank 上同一通信域的算子下发日志tag、count、streamId 是否一致是定位集群行为不一致类问题最常用的手段。3.4 快速检索关键字Communicator Key Info 与 LocalRank Key Info为了方便快速检索和识别通信域及本端的相关信息HCCL 提供了两个快速检索关键字Communicator Key Info和LocalRank Key Info。例如执行grep -r Communicator Key Info可得到如下信息run/plog/plog-858941_20251210195327204.log:[INFO] HCCL(858941,all_reduce_test):2025-12-10-19:53:28.131.350 [hccl_communicator_attrs.cc:327] [858941][Communicator Key Info]identifier[127.0.0.1%enp_60000_0_1765367607599032] rankSize[8] serverNum[1] moduleNum[1] superPodNum[0] multiModuleDiffDeviceNumMode[0] multiSuperPodDiffServerNumMode[0]通信域关键信息字段identifier通信域名rankSize通信域大小serverNum通信域内节点数moduleNum通信域内模组个数superPodNum通信域内超节点个数multiModuleDiffDeviceNumMode是否模组间卡数不一致multiSuperPodDiffServerNumMode是否超节点间节点数不一致信息中1表示是0表示否。从日志示例可见该信息由通信属性模块hccl_communicator_attrs.cc在通信域建立时打印一次检索即可拿到该 rank 所处通信域的完整拓扑画像。例如执行grep -r LocalRank Key Info可得到如下信息run/plog/plog-858941_20251210195327204.log:[INFO] HCCL(858941,all_reduce_test):2025-12-10-19:53:28.131.357 [hccl_communicator_attrs.cc:330] [858941][LocalRank Key Info]userRank[6] hostIp[127.0.0.1] devicePhyId[6] server[127.0.0.1] deviceIp[0.0.0.0] superPodId[0] useSuperPodMode[0] isStandardCard[0]本端关键信息字段userRank通信域内的 Rank 号hostIphost 侧 IPdevicePhyId物理 IDserver节点信息deviceIpdevice 侧 IPsuperPodId超节点 IDuseSuperPodMode是否为超节点模式isStandardCard是否为标卡场景同样地1表示是0表示否。两个关键字配合使用可以无需逐个翻日志就确认这个 rank 属于哪个通信域、在哪个节点上、拓扑形态是否正常。3.5 查询环境变量实际生效值如果想要查询已经配置成功的环境变量其配置及实际生效值会被打印在 CANN 日志的 run/plog 目录下。针对 Atlas A3/A2 训练与推理系列产品、Atlas 训练系列、Atlas 推理系列产品可以通过检索HCCL_ENV关键字查询每个进程的环境变量实际生效值例如执行grep -r HCCL_ENV run/plog/plog-xxx.log命令执行后得到类似如下信息从日志示例看这些信息由环境变量解析模块externalinput.cc在进程启动初始化阶段统一打印既包含set by default的默认值也包含set by environment的用户配置值[INFO] HCCL(1595259,alltoall_test):2026-01-06-15:38:29.881.877 [externalinput.cc:598] [1595259][HCCL_ENV] HCCL_CONNECT_TIMEOUT set by default to [120]s [INFO] HCCL(1595259,alltoall_test):2026-01-06-15:38:29.881.882 [externalinput.cc:558] [1595259][HCCL_ENV] HCCL_EXEC_TIMEOUT set by default to [1836]s [INFO] HCCL(1595259,alltoall_test):2026-01-06-15:38:29.881.886 [externalinput.cc:663] [1595259][HCCL_ENV] HCCL_INTRA_PCIE_ENABLE set by default to [1], HCCL_INTRA_ROCE_ENABLE set by default to [0] [INFO] HCCL(1595259,alltoall_test):2026-01-06-15:38:29.881.895 [externalinput.cc:833] [1595259][HCCL_ENV] HCCL_WHITELIST_DISABLE set by environment to [0] [INFO] HCCL(1595259,alltoall_test):2026-01-06-15:38:29.881.912 [externalinput.cc:880] [1595259][HCCL_ENV] HCCL_IF_IP is not set [INFO] HCCL(1595259,alltoall_test):2026-01-06-15:38:29.881.915 [externalinput.cc:936] [1595259][HCCL_ENV] HCCL_SOCKET_IFNAME set by default to [EmptyString] [INFO] HCCL(1595259,alltoall_test):2026-01-06-15:38:29.881.917 [externalinput.cc:903] [1595259][HCCL_ENV] HCCL_SOCKET_FAMILY is not set and is used by default [AF_INET] [INFO] HCCL(1595259,alltoall_test):2026-01-06-15:38:29.881.920 [externalinput.cc:865] [1595259][HCCL_ENV] HCCL_IF_BASE_PORT set by default to [60000] [INFO] HCCL(1595259,alltoall_test):2026-01-06-15:38:29.882.148 [externalinput.cc:1736] [1595259][HCCL_ENV] HCCL_OP_RETRY_PARAMS is not set, default value MaxCnt is [1], HoldTime is [5000]ms, IntervalTime is [1000]ms [INFO] HCCL(1595259,alltoall_test):2026-01-06-15:38:29.882.180 [externalinput.cc:1800] [1595259][HCCL_ENV] HCCL_DEBUG_CONFIG is not set, debugConfig set by default to 0x0以上示例为节选完整列表中还包括HCCL_RDMA_TC、HCCL_RDMA_SL、HCCL_RDMA_TIMEOUT、HCCL_RDMA_RETRY_CNT、HCCL_BUFFSIZE、HCCL_DETERMINISTIC、HCCL_DIAGNOSE_ENABLE、HCCL_ENTRY_LOG_ENABLE、HCCL_INTER_HCCS_DISABLE、HCCL_OP_EXPANSION_MODE、HCCL_RDMA_QPS_PER_CONNECTION、HCCL_MULTI_QP_THRESHOLD、HCCL_OP_RETRY_ENABLE、HCCL_LOGIC_SUPERPOD_ID、HCCL_RDMA_PCIE_DIRECT_POST_NOSTRICT、HCCL_RDMA_QP_PORT_CONFIG_PATH等变量的生效值。针对Ascend 950PR/Ascend 950DT则可通过检索关键字base_config查询当前已设置的环境变量[INFO] HCCL(229424,python3.8):2025-12-23-22:31:40.239.170[base_config.cc:33][229424][Init][EnvVarParam]Env config HCCL_IF_IP is not set. Default value is used. [INFO] HCCL(229424,python3.8):2025-12-23-22:31:40.239.166[base_config.cc:33][229424][Init][EnvVarParam]Env config HCCL_CONNECT_TIMEOUT is parsed.这一步可以确认你以为配置的环境变量进程实际是否真的收到了对多节点环境配置不一致类问题非常有用。四、快速定位定界思路HCCL 故障定位的主流程分为三步。4.1 第一步确认是否为 HCCL 相关的异常报错HCCL 针对常见的报错场景会在业务打屏日志中上报错误信息及故障信息。若在业务日志中存在EI****或EJ****的故障码则可根据对应的故障信息排查故障或结合 CANN 日志中的报错信息到对应章节排查故障码列表见本文 第六节。除了打屏的故障码信息HCCL 在 CANN 日志中会打印 HCCL 组件的 ERROR 级别日志。因此若 CANN 日志中没有 HCCL 组件的报错日志需排查是否有其他组件的报错信息若无任何报错则注意训练脚本本身有无异常、是否存在 core dump 或进程卡住等其他异常。4.2 第二步收集全量 CANN 日志由于 HCCL 集合通信是通信域下全局的协同行为某个节点上有 HCCL 异常报错往往是因为在等待某个对端超时——报错节点未必是根因节点。此时需要结合对端的日志信息一起排查根因。因此对 HCCL 问题的定位定界需要收集集群下所有节点的 CANN 日志包括 debug 目录和 run 目录的日志。4.3 第三步确认当前报错阶段HCCL 业务存在三个阶段通信域初始化、参数面建链和通信算子执行。由于不同阶段使用的硬件资源、通信拓扑和同步方式有明显差异因此可先确认当前 HCCL 报错所在的阶段再根据不同阶段找到对应章节做进一步排查。HCCL 在常见的报错场景增加了多级检索关键字可以根据报错日志中的关键字快速识别当前报错阶段。多级检索关键字详见 第五节。例如如下日志表明在算子执行阶段发生了超时报错且当前算子展开方式为 HOST 模式[ERROR] HCCL(858209,all_reduce_test):2025-12-10-19:52:32.589.097 [task_exception_handler.cc:27] [858274][TaskExecStage][Timeout][HOST]Task run failed, base information is streamID:[1740], taskID[23], tag[AllReduce_127.0.0.1%enp_60000_0_1765367469951573], AlgType(level 0-1-2):[fullmesh-ring-NHR].注意多级检索关键字功能仅在 CANN 8.5.0 版本及后续版本支持对于不支持的版本或没有检索到关键字的场景可根据其他方法判断当前报错阶段。除了检索关键字HCCL 提供了通信域创建接口和通信算子接口且接口均为同步下发、异步执行因此也可按以下接口行为场景判断阶段若业务在调用通信域创建接口失败时或在报错日志中有topoinfo、ranktable关键字打印可参考 通信域初始化阶段 章节进一步排查若业务在调用通信算子接口失败时或在报错日志中有transport关键字打印可参考 参数面建链阶段 章节进一步排查若业务创建通信域接口和通信算子下发均成功而是在触发流同步时有 HCCL 的算子执行失败或在报错日志中有TaskExceptionHandler、FFTS run failed、Task run failed关键字打印可参考 任务下发执行阶段 章节做进一步排查。除此三个阶段的关键信息外若业务打屏日志中有明确的错误码信息如EI0001可直接根据错误码在故障码表中找到对应章节并进一步排查。五、HCCL 多级检索关键字以下表格汇总了 HCCL 报错日志中的多级检索关键字一级关键字标识报错阶段二级关键字标识具体故障场景一级关键字二级检索关键字故障场景InitGroupStageEnvConfig通信域初始化阶段环境变量配置异常RanktableConfig通信域初始化阶段 rankTable 文件读取失败RanktableCheck通信域初始化阶段 rankTable 集群信息校验失败RanktableDetect通信域初始化阶段集群信息探测失败Resource通信域初始化节点资源初始化失败InitChannelStageParameterConflict参数面建链阶段参数一致性校验失败VersionConflict参数面建链阶段 HCCL 版本不一致校验失败Timeout参数面建链阶段超时报错TaskExecStageInvalidArgument算子执行阶段入参校验失败Not Supported算子执行阶段不支持场景Timeout算子执行阶段执行超时RunFailed算子执行阶段执行失败HeartbeatAbnormal算子执行阶段发现心跳异常事件六、HCCL 相关故障码故障码故障码说明EI0001环境变量配置异常EI0002通信算子执行超时EI0003集合通信算子入参校验失败请根据报错信息中的具体入参判断EI0004rankTable 文件加载失败EI0005参数一致性校验失败EI0006通信算子参数面建链超时EI0007资源初始化失败请根据报错信息判断具体失败原因EI0008HCCL 版本不一致校验失败请根据报错信息中的版本信息判断EI0011QP 内存资源申请失败EI0012算子执行时发生 SDMA 任务异常EI0013算子执行时发生 ROCE CQE ERROR 异常EI0014集群信息校验失败EI0015通信域集群信息协商阶段超时EI0019通信域创建阶段 server 节点端口绑定失败 或 参数面建链阶段端口绑定失败七、实战排查路径小结将上述能力组合起来一次典型的 HCCL 故障排查可以按以下顺序执行看打屏日志业务日志中是否出现EI****/EJ****故障码有则直接对照 故障码表 跳转对应章节确认报错阶段在 CANN 日志 debug 目录中检索一级关键字InitGroupStage/InitChannelStage/TaskExecStage或topoinfo、ranktable、transport、Task run failed等特征字确定是通信域初始化、参数面建链还是算子执行阶段的问题收集全量日志拉取集群所有节点的 CANN 日志debug run 目录避免只看报错节点比对环境配置用grep -r HCCL_ENV run/plog/逐节点核对超时、网络等关键变量的实际生效值确认HCCL_CONNECT_TIMEOUT小于HCCL_EXEC_TIMEOUT锁定行为差异对行为不一致类问题开启 HCCL_ENTRY_LOG_ENABLE 复现用grep -r Communicator Key Info与grep -r LocalRank Key Info确认各 rank 的通信域画像与算子下发入参横向比对找出第一个出现偏差的 rank深挖根节点对无清晰首报错的大集群问题结合建链根节点定位能力与集群心跳机制沿 rank 依赖关系回溯到首个异常 rank再依据该 rank 的日志与源码级日志做深入分析。掌握这套故障码 → 阶段定界 → 全量日志 → 关键字比对 → 根节点回溯的流程后绝大多数 HCCL 通信问题都能在有限步骤内收敛到具体阶段与具体节点再配合各阶段对应的专题排查文档完成最终定位。【免费下载链接】hccl集合通信库Huawei Collective Communication Library简称HCCL是基于昇腾AI处理器的高性能集合通信库为计算集群提供高性能、高可靠的通信方案项目地址: https://gitcode.com/cann/hccl创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
