本文档介绍了如何收集和解读 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* 文件,或者如果库的安装目录不在动态链接器搜索路径中,也会发生此错误。
如需解决此问题,请执行以下操作:
- 验证您的环境中是否已安装共享对象。
- 验证包含共享对象的目录是否位于动态链接器搜索路径或
$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。
Guest 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)
若要解决此问题,请执行以下操作:
- 按照客机配置检查器日志的指导进行操作。
- 验证 NCCL/gIB 环境变量。
调优器找不到配置文件
当调谐器插件找不到要使用的配置文件时,会发生以下错误。
... NCCL WARN No NCCL_TUNER_CONFIG_PATH provided. Please populate NCCL_TUNER_CONFIG_PATH to use config-based tuner plugin.
若要解决此问题,请执行以下操作:
- 将环境变量
NCCL_TUNER_CONFIG_PATH设置为指向tuner_config.txtpb的位置。NCCL/gIB 安装程序的配置文件默认位置为/usr/local/gib/configs/guest_config.txtpb。 - 验证 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 版本:
如果您在 Compute Engine 虚拟机上执行手动 NCCL Core 升级,请在运行工作负载之前在所有节点上应用升级。
如果您使用 GKE,请验证或重新安装 NCCL/gIB 安装程序 DaemonSet。如需了解详情,请参阅 A3 Ultra 和 A4 的说明或 A4X 的说明。
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)
发生以下错误的原因如下:
- QP 的另一端具有损坏的 GID 表。
- 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
若要解决此问题,请执行以下操作:
无可用数据 (errno 61)
发生以下错误的原因如下:
- 此虚拟机的 GID 表已损坏。
- 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
如需解决此问题,请先检查原因:
如果 GID 表损坏,请尝试以下缓解措施:
- (短期)在虚拟机上重启网络管理器(例如
networkd),直到问题接口的 IP 地址刷新。- 您可以使用
sudo systemctl restart systemd-networkd在虚拟机上重启networkd。 - 您可以使用
ip a查看所有接口的 IP 地址。 - 检查 GID 表是否已恢复。
- 您可以使用
- 请与 Google 支持团队联系,寻求长期解决方案。
连接超时(错误代码 110)
当虚拟机之间存在基本连接问题时,会发生以下错误。
... NCCL WARN Call to ibv_modify_qp failed with error Connection timed out errno 110
如需解决此问题,请与 Google 支持团队联系以寻求帮助。
QP 收到错误完成
发生以下错误的原因如下:
- 底层 RDMA 连接问题(链路抖动等)。
- 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 支持团队联系以寻求帮助。