本文档介绍了如何收集和解读 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 开发的插件组成。如果未能加载任何插件，可能会导致性能不佳，在某些情况下还会导致严重错误。
网络插件 (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 调谐器插件已正确加载，您应该会看到类似于以下内容的 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 版本，请查找以下 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 性能，我们提供了一个脚本，您可以使用该脚本设置推荐的 NCCL 环境变量。在运行工作负载之前，请在与工作负载 相同的环境 中获取脚本的源代码。在 NCCL/gIB 安装程序中，该脚本位于 /usr/local/gib/set_nccl_env.sh。如果您不使用此脚本，导致 NCCL 环境变量设置不正确，则 gIB NCCL 配置检查器可能会终止工作负载，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：
- 清单必须将虚拟机上的
/home/kubernetes/bin/gib中的 NCCL/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）匹配。
如果上述任何一项为假，则 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
如需解决此问题，请执行以下操作：
- 确保共享对象已安装在您的环境中。
- 确保共享对象的目录位于
$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
客机配置检查器找不到配置文件
当客机配置检查器找不到要使用的配置文件时，会出现类似这样的日志条目。
... 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 来停用客机配置检查器。
客机配置检查器强制执行或推荐了某项设置
如果未按建议设置 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 或更高版本）。
消息被截断
如果您在不同排名中使用混合 NCCL 版本，则会发生以下错误。
... NCCL WARN Message truncated : received ### bytes instead of ###
如需解决此问题，请检查您的 NCCL 和 gIB 版本。如果您使用的是 GKE，请检查或重新安装 NCCL/gIB 安装程序守护进程集（请参阅 A3U 和 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 支持团队联系，以获取长期解决方案方面的帮助。
连接超时 (errno 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 支持团队联系以获取帮助。