收集和了解 NCCL/gIB 日志

本文档介绍了如何收集和解读 NCCL/gIB 日志,以排查 AI Hypercomputer 上的稳定性和性能问题,并提供了有关如何实现以下目标的指导:

  • 收集 NCCL 日志。
  • 了解 NCCL 日志条目的结构。
  • 验证 NCCL/gIB 插件是否已正确加载。
  • 检查 NCCL 和 gIB 版本是否正确。
  • 排查常见 NCCL 警告和错误。

收集 NCCL 日志

您可以使用 NVIDIA Collective Communications Library (NCCL) 日志来调试 NCCL 故障。对于任何稳定性或性能调试,请在运行有问题的负载时收集所有日志记录级别的 NCCL 日志。避免将日志条目转储到控制台,因为日志量过大可能会导致作业无法继续。

如需收集 NCCL 日志,请设置以下环境变量:

NCCL_DEBUG=INFO
NCCL_DEBUG_SUBSYS=INIT,ENV,GRAPH,NET,COLL,TUNING
NCCL_DEBUG_FILE=DESIRED_PATH/nccl_logs.VM_NAME.RANK_PROCESS_ID

替换以下内容:

DESIRED_PATH:您要存储日志文件的路径

VM_NAME:虚拟机名称

RANK_PROCESS_ID:排名的进程 ID

NCCL 日志格式

NCCL 日志类似于以下内容:

# A sample log entry from NCCL core.
a3ultra-vm-0:606:642 [6] NCCL INFO Using network gIB

# A sample log entry from the gIB network plugin.
a3ultra-vm-0:606:642 [6] NCCL INFO NET/gIB : Initializing gIB v1.0.2

无论来源如何,NCCL 日志都具有类似于以下内容的前缀:

<VM name>:<pid>:<tid> [<GPU device ID>] <log level> <log content>

验证 NCCL/gIB 插件是否已正确加载

NCCL/gIB 由多个 Google 开发的插件组成。未能加载任何插件都可能导致性能不佳,在某些情况下还会导致严重错误。

我们建议您使用 gIB 安装程序随附的 NCCL,以确保获得最新功能、最佳性能和最高稳定性。如果您选择使用自定义 NCCL 版本进行测试(例如与您选择的机器学习框架捆绑在一起的 NCCL 版本),则还必须安装 nccl-gib-plugins 软件包。

网络插件 (libnccl-net.so)

如果 gIB 网络插件已正确加载,您应该会看到类似于以下内容的 NCCL 日志条目:

... NCCL INFO Using network gIB

如果您看到类似于以下任何内容的日志条目,请按照无法加载共享对象部分中的步骤解决问题。

# Cannot find the gIB network plugin.
... NCCL INFO NET/Plugin: Could not find: libnccl-net.so. Using internal network plugin.

# Using the built-in TCP plugin.
... NCCL INFO Using network Socket

# Using the built-in IB plugin.
... NCCL INFO Using network IB

调谐器插件 (libnccl-tuner.so)

如果 gIB Tuner 插件已正确加载,您应该会看到类似于以下内容的 NCCL 日志条目:

NCCL INFO TUNER/Plugin: Failed to find ncclTunerPlugin_v3 symbol.
NCCL INFO TUNER/Plugin: Using tuner plugin A3xTunerPlugin_v2

如果您看到类似于以下内容的日志条目,请按照无法加载共享对象部分中的步骤解决问题。

NCCL INFO TUNER/Plugin: Failed to find ncclTunerPlugin_v2 symbol, using internal tuner instead.

CollNet 插件

虽然这些日志条目表示失败,但它们是预期的,不值得担心:

NCCL INFO NET/Plugin: Failed to find ncclCollNetPlugin_v8 symbol.
NCCL INFO NET/Plugin: Failed to find ncclCollNetPlugin symbol (>= v5). ncclCollNetPlugin symbols v4 and lower are not supported.

检查 NCCL 和 gIB 版本

我们建议您使用 gIB 安装程序随附的 NCCL,以确保获得最新功能、最佳性能和最高稳定性。不过,您可以选择使用自定义 NCCL 版本进行测试,例如与您选择的机器学习框架捆绑在一起的 NCCL 版本。在这种情况下,请安装 nccl-gib-plugins 软件包。

如需查看工作负载使用的 NCCL 和 gIB 版本,请在 NCCL 日志中查找以下条目:

# NCCL version.
... NCCL INFO NCCL version 2.23.4+cuda12.2

# gIB version.
... NCCL INFO NET/gIB : Initializing gIB v1.0.2

如需确认您运行的是推荐版本,请将记录的 NCCL 和 gIB 版本与最新 nccl-gib 软件包中捆绑的版本进行比较。我们建议在所有节点上保持 nccl-gib 为最新版本;如需了解详情,请参阅安装 NCCL/gIB。

如果您手动升级了 NCCL Core,或者使用自定义 NCCL Core 库安装了 nccl-gib-plugins,请验证记录的 NCCL 版本是否与目标版本匹配,以及 NET/gIB 插件是否初始化:

# Target upgraded NCCL Core version, such as NCCL 2.28 or later.
... NCCL INFO NCCL version 2.28.3+cuda12.8

# gIB network plugin initializing alongside upgraded NCCL Core.
... NCCL INFO NET/gIB : Initializing gIB v1.1.2

如果日志显示的是早期捆绑的 NCCL 版本,而不是升级后的版本,则动态链接器仍在从 /usr/local/gib/lib64 或 /usr/local/gib/lib 加载 libnccl.so.2。确保您已按照在现有安装上升级 NCCL Core 中的说明移除了捆绑的 libnccl.so* 文件。

验证 NCCL/gIB 环境变量

为了实现良好的 NCCL 性能,我们提供了一个脚本,您可以使用该脚本设置推荐的 NCCL 环境变量。在运行工作负载之前,请在工作负载所在的同一环境中运行该脚本。在 NCCL/gIB 安装程序中,该脚本位于 /usr/local/gib/set_nccl_env.sh。如果您不使用此脚本,导致 NCCL 环境变量设置不正确,则 gIB NCCL Config Checker 可能会终止工作负载,NCCL 可能会崩溃,或者 NCCL 性能可能会不佳。

如需检查 NCCL/gIB 环境变量是否已正确应用,请查找类似于以下内容的 NCCL 日志条目:

# Explicitly set values.
... NCCL INFO NCCL_P2P_PCI_CHUNKSIZE set by environment to 131072.

# Using default values because the set value is invalid.
... NCCL INFO Invalid value INVALID_VALUE for NCCL_P2P_PCI_CHUNKSIZE, using default 131072.

将以下值与推荐的 NCCL 环境变量进行比较。

检查 GKE 工作负载清单

在 GKE 上,您的 Kubernetes 工作负载清单需要进行多项设置,才能顺利使用 NCCL/gIB:

  • 清单必须将 NCCL/gIB 二进制文件从虚拟机上的 /home/kubernetes/bin/gib 装载到工作负载容器中的 /usr/local/gib。请注意,虚拟机上的 /home/kubernetes/bin/nvidia 会自动装载到工作负载容器中的 /usr/local/nvidia。
  • 您的工作负载容器必须将 LD_LIBRARY_PATH 设置为 /usr/local/gib/lib64:/usr/local/nvidia/lib64。
  • 您的集群和节点池必须设置 GKE 多网络,并且您的工作负载清单必须包含多网络注解,以避免需要设置 hostNetwork: true。

GKE 上的实际 Kubernetes 工作负载清单类似于以下内容:

...
metadata:
  annotations:
    networking.gke.io/default-interface: 'eth0'
    networking.gke.io/interfaces: |
      [
        {"interfaceName":"eth0","network":"default"},
        {"interfaceName":"eth1","network":"gvnic-1"},
        {"interfaceName":"gpu0rdma0","network":"rdma-0"},
        {"interfaceName":"gpu1rdma0","network":"rdma-1"},
        {"interfaceName":"gpu2rdma0","network":"rdma-2"},
        {"interfaceName":"gpu3rdma0","network":"rdma-3"},
        {"interfaceName":"gpu4rdma0","network":"rdma-4"},
        {"interfaceName":"gpu5rdma0","network":"rdma-5"},
        {"interfaceName":"gpu6rdma0","network":"rdma-6"},
        {"interfaceName":"gpu7rdma0","network":"rdma-7"}
      ]
spec:
  volumes:
    - name: gib
      hostPath:
        path: /home/kubernetes/bin/gib
...
containers:
  - name: my-container
    volumeMounts:
      - name: gib
     mountPath: /usr/local/gib
    env:
      - name: LD_LIBRARY_PATH
        value: /usr/local/gib/lib64:/usr/local/nvidia/lib64
    resources:
      limits:
        nvidia.com/gpu: 8

检查 GID 表

在 RoCE 中,全局标识符 (GID) 表用于唯一寻址 RDMA 流量。如果 GID 表损坏,则无法通过任何 RDMA 流量。

我们提供了一个脚本 show_gids.sh,用于显示 GID 表。在安装程序中,它位于 /usr/local/gib/scripts。如果您使用了我们的安装程序且未进行任何修改,则该代理会安装到虚拟机上的 /var/lib/gib/scripts。

在虚拟机中运行脚本时,您应该会看到如下所示的输出:

DEV     PORT  INDEX  GID                                      IPv4         VER  DEV
---     ----  -----  ---                                      ----         ---  ---
mlx5_0  1     0      fe80:0000:0000:0000:689c:b8ff:fedf:3b01               v1   gp0rdma0
mlx5_0  1     1      fe80:0000:0000:0000:689c:b8ff:fedf:3b01               v2   gp0rdma0
mlx5_0  1     2      0000:0000:0000:0000:0000:ffff:c0a8:0202  192.168.2.2  v1   gp0rdma0
mlx5_0  1     3      0000:0000:0000:0000:0000:ffff:c0a8:0202  192.168.2.2  v2   gp0rdma0
...

查看输出并确认以下内容:

  • GID 表具有适当数量的条目:
    • 对于 A3 Ultra 或 A4,32 个条目,每个 CX-7 有 4 个条目。
    • 对于 A3 Mega,32 个条目,每个 CX-7 有 4 个条目。
    • 对于 A3 High(8 个 GPU),16 个条目,每个 CX-7 有 4 个条目。
    • 对于 A4X,16 个条目,每个 CX-7 有 4 个条目。
  • 每个 CX-7 的 GID 条目都有索引 0、1、2 和 3。
  • 对于每个 CX-7,索引 2 和 3 都有一个 IPv4 地址,并且该 IP 地址与该设备的 IPv4 地址(例如来自 ip a)匹配。

如果其中任何一项为 false,则表示 GID 表已损坏。请考虑重启虚拟机或重启客机操作系统中的网络管理器。

NCCL 警告

NCCL 日志有多个级别,其中 NCCL 警告 (NCCL WARN) 最为严重。NCCL 警告通常表示失败,这些失败可能是致命的,也可能不是。NCCL 没有会自动停止工作负载的日志级别。

无法加载共享对象

如果由于您的设置而无法加载共享对象,就会出现以下错误:

error while loading shared libraries: libnccl.so.2: cannot open shared object file: No such file or directory

如果您在手动 NCCL Core 升级期间,在安装兼容的 NCCL Core 库之前移除了捆绑的 libnccl.so* 文件,或者如果库的安装目录不在动态链接器搜索路径中,也会发生此错误。

如需解决此问题,请执行以下操作:

  1. 验证您的环境中是否已安装共享对象。
  2. 验证包含共享对象的目录是否位于动态链接器搜索路径或 $LD_LIBRARY_PATH 环境变量中。

未能映射共享对象中的细分受众群

当共享对象的目录不可执行时,会发生以下错误。

error while loading shared libraries: libnccl.so.2: failed to map segment from shared object: Operation not permitted

如需解决此问题,请运行以下命令(这些示例假设 gIB 二进制文件安装在虚拟机上的 /var/lib/gib 中):

sudo mount --bind /var/lib/gib /var/lib/gib
sudo mount -o remount,exec /var/lib/gib

Guest Config Checker 找不到配置文件

当客机配置检查器找不到要使用的配置文件时,就会出现此类日志条目。

... NCCL WARN cannot find config file at default paths; you must specify NCCL_SHIMNET_GUEST_CONFIG_CHECKER_CONFIG_FILE

... NCCL WARN NCCL_SHIMNET_GUEST_CONFIG_CHECKER_CONFIG_FILE does not exist: /path/to/guest_config.txtpb

如需解决此问题,您可以将环境变量 NCCL_SHIMNET_GUEST_CONFIG_CHECKER_CONFIG_FILE 设置为指向 guest_config.txtpb 的位置。NCCL/gIB 安装程序的配置文件默认位置为 /usr/local/gib/configs/guest_config.txtpb。

我们不建议您停用客机配置检查器,因为它有助于确保最佳实践和正确配置。不过,如有必要,您可以通过将环境变量 NCCL_SHIMNET_SHIM_LAYERS 设置为 UNUSED 来停用客机 Config Checker。

如果未按建议设置 NCCL/gIB 环境变量,则会发生以下错误。

# The guest Config Checker enforcing an environment variable.
# This ends the workload.
... NCCL WARN NCCL/NET (shim) mismatch enforced: NCCL_P2P_NVL_CHUNKSIZE=524288 (expected 262144)

# The guest Config Checker recommending an environment variable.
# This does not end the workload.
... NCCL WARN NCCL/NET (shim) mismatch recommended: NCCL_MAX_P2P_NCHANNELS=8 (expected unset)

若要解决此问题,请执行以下操作:

  1. 按照客机配置检查器日志的指导进行操作。
  2. 验证 NCCL/gIB 环境变量。

调优器找不到配置文件

当调谐器插件找不到要使用的配置文件时,会发生以下错误。

... NCCL WARN No NCCL_TUNER_CONFIG_PATH provided. Please populate NCCL_TUNER_CONFIG_PATH to use config-based tuner plugin.

若要解决此问题,请执行以下操作:

  1. 将环境变量 NCCL_TUNER_CONFIG_PATH 设置为指向 tuner_config.txtpb 的位置。NCCL/gIB 安装程序的配置文件默认位置为 /usr/local/gib/configs/guest_config.txtpb。
  2. 验证 NCCL/gIB 环境变量。

glibc 版本不符合要求

如果您的本地发行版 glibc 版本过旧,则会发生以下错误,这很可能是因为您本地环境中的 Linux 发行版过旧。NCCL/gIB 二进制文件需要 glibc 2.29 版。

/usr/lib/x86_64-linux-gnu/libc.so.6: version `GLIBC_2.34' not found (required by /usr/local/gib/lib64/libnccl.so.2)

如需解决此问题,请升级映像发行版(例如 Ubuntu 20.04 或更高版本、RockyLinux 9 或更高版本)。

消息已被截断

如果您在不同 rank 之间使用混合 NCCL 版本,则会发生以下错误。例如,如果您仅在集群中的一部分节点上升级 NCCL Core,则会导致已升级和未升级的 rank 之间出现通信不匹配,从而发生此错误:

... NCCL WARN Message truncated : received ### bytes instead of ###

如需解决此问题,请检查您的 NCCL 和 gIB 版本,并验证所有集群节点是否运行完全相同的 NCCL 版本:

libibverbs 无法加载提供方配置

如果您未将包含 gIB 二进制文件的目录装载到 /usr/local/gib,则会发生以下错误。这不会导致工作负载失败。不过,NCCL 会回退到使用 TCP,这可能会导致性能不佳。

libibverbs: Warning: couldn't open config directory '/usr/local/gib/rdma-core/build/etc/libibverbs.d'.

如需解决此问题,如果您使用的是 GKE,请检查工作负载清单。

ibv_modify_qp 错误

在 gIB 网络插件为实际网络事务准备 QP 时,您可能会遇到许多错误。

参数无效 (errno 22)

发生以下错误的原因如下:

  1. QP 的另一端具有损坏的 GID 表。
  2. NCCL/gIB 环境变量配置不正确,尤其是 NCCL_IB_GID_INDEX、NCCL_IB_TC 和 NCCL_IB_FIFO_TC。
... NCCL WARN Call to ibv_modify_qp failed with error Invalid argument errno 22

若要解决此问题,请执行以下操作:

  1. 查找具有签名 No data available error 61 的其他 ibv_modify_qp 错误,并按照错误 61 的缓解说明进行操作。
  2. 验证 NCCL/gIB 环境变量。

无可用数据 (errno 61)

发生以下错误的原因如下:

  1. 此虚拟机的 GID 表已损坏。
  2. NCCL/gIB 环境变量配置不正确,尤其是 NCCL_IB_GID_INDEX、NCCL_IB_TC 和 NCCL_IB_FIFO_TC。
... NCCL WARN Call to ibv_modify_qp failed with error No data available errno 61

如需解决此问题,请先检查原因:

  1. 查看 GID 表。
  2. 验证 NCCL/gIB 环境变量。

如果 GID 表损坏,请尝试以下缓解措施:

  1. (短期)在虚拟机上重启网络管理器(例如 networkd),直到问题接口的 IP 地址刷新。
    1. 您可以使用 sudo systemctl restart systemd-networkd 在虚拟机上重启 networkd。
    2. 您可以使用 ip a 查看所有接口的 IP 地址。
    3. 检查 GID 表是否已恢复。
  2. 请与 Google 支持团队联系,寻求长期解决方案。

连接超时(错误代码 110)

当虚拟机之间存在基本连接问题时,会发生以下错误。

... NCCL WARN Call to ibv_modify_qp failed with error Connection timed out errno 110

如需解决此问题,请与 Google 支持团队联系以寻求帮助。

QP 收到错误完成

发生以下错误的原因如下:

  1. 底层 RDMA 连接问题(链路抖动等)。
  2. NCCL/gIB 环境变量配置错误,尤其是 NCCL_IB_TIMEOUT 和 NCCL_IB_RETRY_CNT。
... NCCL WARN NET/gIB : Got completion from peer 192.168.0.9<55224> with status=12 opcode=0 len=0 vendor err 129 (Recv) localGid ::ffff:192.168.3.6 remoteGids::ffff:192.168.3.9

如需解决此问题,请与 Google 支持团队联系以寻求帮助。