快速定位定界思路

• HCCL针对常见的报错场景，会在业务打屏日志中上报错误信息及故障信息，若在业务日志中存在"EI****"或"EJ****"的故障码，则可根据对应的故障信息排查故障，或结合CANN日志中的报错信息对相应章节进行排查，故障码列表可见HCCL相关故障码。
• 除了打屏的故障码信息，HCCL在CANN日志中会打印HCCL组件的ERROR级别日志，因此若在CANN日志中没有发现HCCL组件的报错日志，需排查是否有其他组件的报错信息，若无报错，请注意训练脚本本身有无异常、是否存在core dump或进程卡住等其他异常

由于HCCL集合通信是一个通信域下全局的协同行为，某个节点上有HCCL的异常报错往往是因为在等待某个对端超时，此时需要结合对端的日志信息一起排查问题的根因。对于HCCL问题的定位定界需要收集集群下所有节点的CANN日志，包括debug目录和run目录的日志。

HCCL业务存在三个阶段，分别是通信域初始化、参数面建链和通信算子执行，由于不同阶段使用的硬件资源、通信拓扑和同步方式有明显差异，因此可先确认当前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"，可直接根据错误码在后续内容中找到对应的故障码，并进一步排查。