昇腾多机分布式训练:HCCL故障深度定位排查与案例复盘
2026/6/3 17:00:57 网站建设 项目流程

1. 引言

在昇腾 NPU 的双机/多机分布式训练中,很容易出现HCCL(Huawei Collective Communication Library)通信相关问题:HCCL就像个报警器,虽然它在叫,但真正坏掉的根因可能藏在很深——网络链路异常、ranktable 配置不一致、残留进程占用资源、软件栈版本不匹配,甚至某个rank 计算卡死,都有可能会把HCCL拉下水。所以,本文结合在双机RL训练中的HCCL错误排查处理经验,尝试给出一套可落地的完整排查方法论,希望能带大家从HCCL的报错迷雾中走出来。

延伸阅读

本文聚焦HCCL 集合通信相关故障,主要来自在昇腾 NPU 双机强化学习训练中的真实踩坑与排障复盘。

2. 昇腾分布式训练里的“集合通信”在干什么

分布式训练里,模型参数/梯度/激活会在不同设备间不断交换。(Collective Communication, CC)是进程组内的全局数据交换操作模板,其中最基本操作包括:发送(send)、接收(receive)、复制(copy)、组内进程同步(barrier)、节点间进程同步(signal wait)
而根据上面基础操作经过组合,便可以构成一组通信模版(即,通信原语),在分布式训练(如深度学习的大规模模型训练)和高性能计算(HPC)中,通信原语是设备之间交换数据的“基本语言”。包括:

  1. broadcast: 一对多广播(一个 rank 把同一份数据发给所有 rank)。举例老师手里有一份讲义,印了多份,分发给班里所有同学。最后每个人手里都有一份一模一样的讲义。
  2. gather: 多对一收集。举例老师手里有一份讲义,印了多份,分发给班里所有同学。最后每个人手里都有一份一模一样的讲义。
  3. all-gather: 多对多收集 。举例:全班开分享会。每个同学写了一条成语,最后每个人都抄写了全班所有人的成语,每个人手里都有一本完整的成语大全
  4. scatter: 一对多发散。举例:老师手里有一套试卷(包含A、B、C、D四道大题),老师把第一题给小明,第二题给小红……每个同学只拿到属于自己的一部分
  5. reduce: 多对一汇聚 。举例统计总分。每个同学报出自己的分数,班长(Root)把所有人的分数加起来,最后只有班长知道全班的总分是多少。
  6. all-reduce: 多对多规约。举例AA制算账。每个人报出自己花了多少钱,大家一起算出一个总数,然后每个人都记下了这个总数是多少。
  7. reduce-scatter: 组合的规约与发散,先对所有节点的数据进行reduce(计算),然后将结果拆分(Scatter)分给各个节点。举例:班里分组做实验。大家先共同计算出了一堆实验数据(Reduce),然后老师说:“小明你负责看管第一部分结果,小红你负责第二部分…”(Scatter)
  8. all-to-all: 多对多。每个节点都有一份数据,这份数据被拆分,分别发送给其他所有节点。举例换名片/发牌。每个人手里都有一叠针对不同人的名片,我把给你的名片给你,你把给我的名片给我。最后,每个人手里依然是一叠名片,但这些名片来自不同的人。

3. HCCL在昇腾训练栈里的位置

HCCL(Huawei Collective Communication Library),看英文全称也知道,其实它就是华为自研的集合通信库,对标的就是NVIDIA的NCCL,是专为昇腾AI处理器设计的高性能集合通信库,专为昇腾NPU设计,它负责在多卡、多机环境下高效地进行数据通信,是分布式训练的核心组件。一个典型调用链大致是:
训练框架(PyTorch / Tensorflow…)HCCL驱动/固件/网络(RoCE、交换机、光模块、NPU 网口)

4. 常见问题类型

日志定位:
昇腾 NPU 上的日志文件通常位于/root/ascend/log目录。
关键排查建议: 在复现问题前,可以备份,或者直接清理该目录下的旧日志,然后重新运行任务。这样可以帮助精准定位当前会话的错误,避免被历史信息干扰。

HCCL 报错的“级联效应”:

  • 真正的根因出现在某条最早的 [ERROR][HCCL](例如初始化域失败、某卡 link down、端口 bind 失败);
  • 后续所有 rank 会因为同步/等待而连续报出“看起来都差不多”的错误。

下面就先简单介绍下常见的引发通信问题的类型

4.1. 端口占用 / 残留进程问题(非常高频)

典型日志:

  • Failed to bind the IP port. Reason: The IP address and port have been bound already.
    高概率原因:

  • 上一次训练异常退出,某些 rank 进程没死

  • 同机器上并发跑了多个分布式任务,端口冲突

处理思路:

# 找端口占用netstat-tunlp|grep<port>lsof-i:<port># 找残留进程ps-ef|grep-E"torchrun|python|ray|deepspeed"|grep-vgrep# 清理(按需)kill-9<pid># 暴力法重启大法

4.2. 物理链路问题(link down / 光模块 / 交换机)

交换机/链路信息(示例):

# 看 lldp(交换机侧信息)foriin{0..7};dohccn_tool-i$i-lldp-g;done# 看 link 状态:UP 才正常,DOWN 重点怀疑光模块故障foriin{0..7};dohccn_tool-i$i-link-g;done

典型根因:

  • 光模块松动/损坏
  • 交换机端口异常
  • 某张卡链路异常导致全局通信失败

4.3. NPU IP / RoCE 网络不通(net_health 非 Success)

RoCE 场景每张 NPU 卡都有独立 IP。检查 IP 配置与连通性:

# 查看每卡 IPforiin{0..7};dohccn_tool-i$i-ip-g;done# 跨机探测(示例:按你们网段写循环)foriin{0..7};doforipin{26..33};doecho"NPU_$i-> 10.20.0.$ip"hccn_tool-i$i-netdetect-saddress10.20.0.$ipdonedone# 查看 net_health(Success 才算过)foriin{0..7};dohccn_tool-i$i-net_health-g;done

如果 net_health 不成功,常见处理就是重新配置 IP/网关(参考文章https://support.huawei.com/carrier/docview?nid=DOC1101486505&path=PBI1-262732867/PBI1-262735886/PBI1-22892969/PBI1-23710427/PBI1-258915853&topicId=c1f06e2重新配置下)

确保两机 RoCE 网段一致、掩码一致、网关一致,并且 NPU 间互相可达。

4.4. RankTable 不一致 / 通信域初始化失败

典型现象:

  • hcclCommInitRootInfo失败
  • 某些 rank 初始化域失败后,其他 rank 级联报错

高概率原因:

  • ranktable 里的rank_size/world_size与实际不一致
  • rank_id / server_id / device_id 对不上
  • 本机实际使用卡(如ASCEND_RT_VISIBLE_DEVICES)与 ranktable 描述不一致
  • world_size == ranktable rank_size
  • 每台机器的 server_id 唯一
  • device_id 与实际卡号一致
  • IP 与实际 NPU IP 对应一致
  • rank 的排列顺序与启动方式一致

4.5. 软件栈不一致 / 超时 / 单 rank 卡死

  • 两机 CANN/固件/驱动/torch_npu/torch 版本不一致→ 可能引入不稳定通信
  • 某个 rank OOM / dataloader 卡住 / 进入死循环→ 其他 rank 在通信点等待,最终 timeout,看起来像“通信问题”

5. 问题排查

排查步骤概览

  • ✅ 单机能稳定跑通
  • ✅ 无残留进程、端口不冲突
  • hccn_tool -link -g全 UP
  • ✅ NPU IP 正确、跨机net_health全 Success
  • ✅ ranktable:rank_size/world_size、server_id、device_id、IP 全对齐
  • ✅ 两机 CANN/torch/torch_npu 版本一致
  • ✅ 各 rank step 同步推进(无卡死/无异常慢 rank)
  • ✅ 只看首报错定位根因(不要被最后一行误导)

5.1. 复现与日志准备

  • 清理/备份/root/ascend/log
  • 记录启动命令、ranktable、环境变量、端口

5.2. 单机闭环(排除代码/数据/模型)

  • 同样脚本、同样数据,单机8 卡跑通再上双机(多机)
  • 单机也挂 → 优先修代码/数据/框架兼容性,确保单机先能通

单机跑不报错并不代表双机一定没问题,但单机能稳定跑通能有效排除“脚本/数据/模型”的硬错误。

5.3. 进程与端口(排除“假通信问题”)

  • 查端口占用、残留进程(尤其是 launcher/ray/torchrun)
  • 保证每次启动环境干净

5.4. 物理链路(link / lldp)

  • hccn_tool -link -g必须全 UP
  • 若出现 DOWN,优先处理光模块/线缆/交换机

5.5. NPU IP 与 net_health

  • 每卡 IP 合法且在正确网段
  • 跨机 netdetect/net_health 全 Success

5.6. ranktable 与拓扑一致性

  • rank_size/world_size、server_id、device_id、IP 一致
  • ASCEND_RT_VISIBLE_DEVICES对齐

5.7. 版本一致性与超时

  • 两机 CANN/torch/torch_npu 版本一致
  • 排查是否存在某 rank 卡死(step 不推进)

5.8. 抓首报错 → 定点打击

  • 查看/root/ascend/log下面首报错日志
  • 只看首个[ERROR][HCCL]
  • 结合上述层级定位根因

6. 错误案例复盘

  • 在基于OpenRLHF以及Verl框架,做双机强化学习训练的时候,遇到hccl通信的问题比较多,比如下面这两种。这时候光看表面的错误,往往是不知道怎么去解决的
  • error code is 4
2025-11-19 17:59:04,050 INFO cli.py:86 -- Status message: Job entrypoint command failed with exit code 1, last available logs (truncated to 20,000 chars): return func(*args, **kwargs) File "/home/ma-user/anaconda3/envs/PyTorch-2.1.0/lib/python3.10/site-packages/torch/distributed/distributed_c10d.py", line 2421, in broadcast work = group.broadcast([tensor], opts) RuntimeError: create_config:build/CMakeFiles/torch_npu.dir/compiler_depend.ts:102 HCCL function error: hcclCommInitRootInfoConfig(numRanks, &rootInfo, rank, config, &(comm->hcclComm_)), error code is 4
  • error code is 7
(TaskRunner pid=54761) _sync_params_and_buffers( (TaskRunner pid=54761) File "/home/ma-user/anaconda3/envs/PyTorch-2.1.0/lib/python3.10/site-packages/torch/distributed/utils.py", line 328, in _ sync_params_and_buffers (TaskRunner pid=54761) dist._broadcast_coalesced( (TaskRunner pid=54761) RuntimeError: create_config:build/CMakeFiles/torch_npu.dir/compiler_depend.ts:102 HCCL function error: hcclCommInitRootInfo Config(numRanks, &rootInfo, rank, config, &(comm->hcclComm_)), error code is 7
  • 遇到这类错误的时候,可以通过查看/usr/local/Ascend/ascend-toolkit/latest/aarch64-linux/include/hccl/hccl_types.h,也可以粗略定位下问题可能的原因。
/** * @brief HCCL functions return value definition */ typedef enum { HCCL_SUCCESS = 0, /**< success */ HCCL_E_PARA = 1, /**< parameter error */ HCCL_E_PTR = 2, /**< empty pointer */ HCCL_E_MEMORY = 3, /**< memory error */ HCCL_E_INTERNAL = 4, /**< internal error */ HCCL_E_NOT_SUPPORT = 5, /**< not support feature */ HCCL_E_NOT_FOUND = 6, /**< not found specific resource */ HCCL_E_UNAVAIL = 7, /**< resource unavailable */ HCCL_E_SYSCALL = 8, /**< call system interface error */ HCCL_E_TIMEOUT = 9, /**< timeout */ HCCL_E_OPEN_FILE_FAILURE = 10, /**< open file fail */ HCCL_E_TCP_CONNECT = 11, /**< tcp connect fail */ HCCL_E_ROCE_CONNECT = 12, /**< roce connect fail */ HCCL_E_TCP_TRANSFER = 13, /**< tcp transfer fail */ HCCL_E_ROCE_TRANSFER = 14, /**< roce transfer fail */ HCCL_E_RUNTIME = 15, /**< call runtime api fail */ HCCL_E_DRV = 16, /**< call driver api fail */ HCCL_E_PROFILING = 17, /**< call profiling api fail */ HCCL_E_CCE = 18, /**< call cce api fail */ HCCL_E_NETWORK = 19, /**< call network api fail */ HCCL_E_AGAIN = 20, /**< try again */ HCCL_E_REMOTE = 21, /**< error cqe */ HCCL_E_SUSPENDING = 22, /**< error communicator suspending */ HCCL_E_RESERVED /**< reserved */ } HcclResult;

然后再根据第五节中的步骤进行检查,下面举了几个实际中的例子

6.1. 案例1:光模块松动

现象:error code 4错误,使用命令for i in {0..7}; do hccn_tool -i $i -lldp -g; done进行检查,发现某卡link status: DOWN
解决方案:重插光模块/检查交换机口,重启下机子,然后解决了

6.2. 案例 2:net_health 非 Success(最终是 IP/网关配置问题)

现象:error code 4错误,使用命令for i in {0..7}; do for ip in {26..33}; do echo "NPU_$i, IP: 10.20.0.$ip"; hccn_tool -i $i -netdetect -s address 10.20.0.$ip; done; done for i in {0..7}; do hccn_tool -i $i -net_health -g ; done,发现跨机net_health不通过

解决方案:
参考https://support.huawei.com/carrier/docview?nid=DOC1101486505&path=PBI1-262732867/PBI1-262735886/PBI1-22892969/PBI1-23710427/PBI1-258915853&topicId=c1f06e2,按网段重新配置-ip -s/-gateway -s,再跑netdetect/net_health→ 解决
配置示例:

(base) [root@A800T-910-node04 ~]# hccn_tool -i 0 -ip -s address 10.20.0.26 netmask 255.255.255.0 _tool -i 4 -ip -s address 10.20.0.30 netmask 255.255.255.0 hccn_tool -i 5 -ip -s address 10.20.0.31 netmask 255.255.255.0 hccn_tool -i 6 -ip -s address 10.20.0.32 netmask 255.255.255.0 hccn_tool -i 7 -ip -s address 10.20.0.33 netmask 255.255.255.0Cmd executed successfully! (base) [root@A800T-910-node04 ~]# hccn_tool -i 1 -ip -s address 10.20.0.27 netmask 255.255.255.0 Cmd executed successfully! (base) [root@A800T-910-node04 ~]# hccn_tool -i 2 -ip -s address 10.20.0.28 netmask 255.255.255.0 Cmd executed successfully! (base) [root@A800T-910-node04 ~]# hccn_tool -i 3 -ip -s address 10.20.0.29 netmask 255.255.255.0 Cmd executed successfully! (base) [root@A800T-910-node04 ~]# hccn_tool -i 4 -ip -s address 10.20.0.30 netmask 255.255.255.0 Cmd executed successfully! (base) [root@A800T-910-node04 ~]# hccn_tool -i 5 -ip -s address 10.20.0.31 netmask 255.255.255.0 Cmd executed successfully! (base) [root@A800T-910-node04 ~]# hccn_tool -i 6 -ip -s address 10.20.0.32 netmask 255.255.255.0 Cmd executed successfully! (base) [root@A800T-910-node04 ~]# hccn_tool -i 7 -ip -s address 10.20.0.33 netmask 255.255.255.0 Cmd executed successfully! (base) [root@A800T-910-node04 ~]# hccn_tool -i 0 -gateway -s gateway 10.20.0.1 way 10.20.0.1 hccn_tool -i 6 -gateway -s gateway 10.20.0.1 hccn_tool -i 7 -gateway -s gateway 10.20.0.1Cmd executed successfully! (base) [root@A800T-910-node04 ~]# hccn_tool -i 1 -gateway -s gateway 10.20.0.1 Cmd executed successfully! (base) [root@A800T-910-node04 ~]# hccn_tool -i 2 -gateway -s gateway 10.20.0.1 Cmd executed successfully! (base) [root@A800T-910-node04 ~]# hccn_tool -i 3 -gateway -s gateway 10.20.0.1 Cmd executed successfully! (base) [root@A800T-910-node04 ~]# hccn_tool -i 4 -gateway -s gateway 10.20.0.1 Cmd executed successfully! (base) [root@A800T-910-node04 ~]# hccn_tool -i 5 -gateway -s gateway 10.20.0.1 Cmd executed successfully! (base) [root@A800T-910-node04 ~]# hccn_tool -i 6 -gateway -s gateway 10.20.0.1 Cmd executed successfully! (base) [root@A800T-910-node04 ~]# hccn_tool -i 7 -gateway -s gateway 10.20.0.1 Cmd executed successfully! (base) [root@A800T-910-node04 ~]# hccn_tool -i 0 -netdetect -s address 10.20.0.1 -netdetect -s address 10.20.0.1 hccn_tool -i 6 -netdetect -s address 10.20.0.1 hccn_tool -i 7 -netdetect -s address 10.20.0.1Cmd executed successfully! (base) [root@A800T-910-node04 ~]# hccn_tool -i 1 -netdetect -s address 10.20.0.1 Cmd executed successfully! (base) [root@A800T-910-node04 ~]# hccn_tool -i 2 -netdetect -s address 10.20.0.1 Cmd executed successfully! (base) [root@A800T-910-node04 ~]# hccn_tool -i 3 -netdetect -s address 10.20.0.1 Cmd executed successfully! (base) [root@A800T-910-node04 ~]# hccn_tool -i 4 -netdetect -s address 10.20.0.1 Cmd executed successfully! (base) [root@A800T-910-node04 ~]# hccn_tool -i 5 -netdetect -s address 10.20.0.1 Cmd executed successfully! (base) [root@A800T-910-node04 ~]# hccn_tool -i 6 -netdetect -s address 10.20.0.1 Cmd executed successfully! (base) [root@A800T-910-node04 ~]# hccn_tool -i 7 -netdetect -s address 10.20.0.1 Cmd executed successfully! (base) [root@A800T-910-node04 ~]# for i in {0..7}; do hccn_tool -i $i -net_health -g ; done net health status: Success net health status: Success net health status: Success net health status: Success net health status: Success net health status: Success net health status: Success net health status: Success

6.3. 案例 3:ranktable 配置错误

现象:出现error code 4错误,日志首报错指向通信域初始化或Rank不匹配。具体表现为开头出现 [ERROR] HCCL。经过与接口人(接口人地址,)沟通,确认是Rank Table配置错误导致的。

解决方案:

  1. 参考官方文档进行配置: 参考 HCCL 用户指南,仔细核对 Rank Table 配置。
  2. 确保Rank Table与实际启动拓扑一致:Rank Table是一个 JSON 文件,需要确保其中定义的 IP 地址、端口、设备数量等信息与实际的计算节点和 NPU 分配情况完全匹配。
  3. 编写并运行HCCL测试脚本: 使用一个简单的脚本来验证HCCL的通信功能,确保Rank Table配置正确。HCCL测试脚本示例 (test_hccl.py):
importosimporttimeimporttorchimporttorch.distributedasdistimporttorch_npudefmain():rank=int(os.environ["RANK"])world_size=int(os.environ["WORLD_SIZE"])master_addr=os.environ["MASTER_ADDR"]master_port=os.environ["MASTER_PORT"]print(f"[RANK{rank}] MASTER_ADDR={master_addr}, MASTER_PORT={master_port}, "f"WORLD_SIZE={world_size}",flush=True)device_count=torch.npu.device_count()local_npu=rank%device_count torch.npu.set_device(local_npu)print(f"[RANK{rank}] use npu:{local_npu}, device_count={device_count}",flush=True)dist.init_process_group(backend="hccl",init_method=f"tcp://{master_addr}:{master_port}",world_size=world_size,rank=rank,)print(f"[RANK{rank}] init_process_group done",flush=True)x=torch.tensor([float(rank)],device=torch.npu.current_device())print(f"[RANK{rank}] before all_reduce, x={x.item()}",flush=True)dist.all_reduce(x,op=dist.ReduceOp.SUM)dist.barrier()print(f"[RANK{rank}] after all_reduce, x={x.item()}",flush=True)ifrank==0:y=torch.tensor([123.0],device=torch.npu.current_device())else:y=torch.tensor([0.0],device=torch.npu.current_device())dist.broadcast(y,src=0)dist.barrier()print(f"[RANK{rank}] after broadcast from rank 0, y={y.item()}",flush=True)time.sleep(2)dist.destroy_process_group()print(f"[RANK{rank}] finished and destroyed process group",flush=True)if__name__=="__main__":main()

HCCL 测试脚本调用示例:

# 设置 Master 节点 IP 和端口exportMASTER_ADDR=${host_ip}# 替换为实际的主节点 IP 地址exportMASTER_PORT=12345# 可自定义端口# 指定 Rank Table 配置文件路径exportHCCL_JSON_CONFIG=/path/to/your/rank_table.json# 替换为实际的 rank_table.json 文件路径exportRANK_TABLE_FILE=$HCCL_JSON_CONFIG# 设置可见的 NPU 设备 (根据实际情况修改)exportASCEND_VISIBLE_DEVICES=0,1,2,3,4,5,6,7# 使用 torchrun 启动脚本torchrun--nproc_per_node=8\--nnodes=2\--node_rank=1\--master_addr=$MASTER_ADDR\--master_port=$MASTER_PORT\test_hccl.py

6.4. 案例4:训练框架版本不适配问题

现象:error code 7错误,查看首报错,这时发现开头是RUNTIME错误,GetVisibleDevices:set ASCEND_RT_VISIBLE_DEVICES:[] error, input data rang[0-8)

解决方案:

  1. 排查ASCEND_RT_VISIBLE_DEVICES配置: 首先确认ASCEND_RT_VISIBLE_DEVICES环境变量是否已正确设置。
  2. 版本兼容性问题:经过排查,发现是 torch_npu 版本与环境不适配。查阅相关资料(如 W3 类似问题),需要将torch_npu升级到7.1.0版本。当时使用的torch_npu版本为2.5.1tips: 由于当时使用的OpenRLHF框架要求torch版本为2.5.1,直接升级torch_npu可能会导致其他不兼容问题,同时也了解到OpenRLHF公司已经不会再投入维护。所以最后决定切换到Verl框架,该问题在新框架中未再出现。

6.5. 案例5: 网卡配置错误

现象:首报错日志显示与网络通信相关的错误。

解决方案:

  1. 查看当前网卡信息: 使用 ifconfig 命令查看当前系统中可用的网络接口。
  2. 指定HCCL通信使用的网卡: 使用export HCCL_SOCKET_IFNAME环境变量来明确指定HCCL进行通信时要使用的网卡接口。示例: 我们机子查出来网卡名称为eth6,则执行以下命令:export HCCL_SOCKET_IFNAME=eth6

7. 资料

  • 易用昇腾(二):四机32卡基于MindSpeed-RL进行Qwen32B GRPO训练: https://zhuanlan.zhihu.com/p/1904304106216064652
  • 华为集合通信库开源了!HCCL开源链接、架构、拓扑算法、常用接口:https://blog.csdn.net/lianghuaju/article/details/141650064
  • hccl昇腾社区:https://www.hiascend.com/cann/hccl
  • HCCL资料书架总览: https://gitcode.com/cann/hccl/blob/master/docs/README.md
  • 昇腾领域接口人 :https://wiki.huawei.com/domains/96894/wiki/217207/WIKI202506287306946
  • 多机多卡相关配置:https://www.hiascend.com/document/detail/zh/canncommercial/700/modeldevpt/ptmigr/AImpug_000027.html
  • 深度学习并行训练算法简介:https://www.cnblogs.com/marsggbo/p/16871789.html

需要专业的网站建设服务?

联系我们获取免费的网站建设咨询和方案报价,让我们帮助您实现业务目标

立即咨询