NCCL-/gIB-Logs zur Fehlerbehebung erfassen und verstehen

In diesem Dokument wird beschrieben, wie Sie NCCL-/gIB-Logs erfassen und interpretieren können, um Stabilitäts- und Leistungsprobleme auf AI Hypercomputer zu beheben. Außerdem finden Sie Anleitungen dazu, wie Sie Folgendes erreichen können:

NCCL-Logs erfassen
Die Struktur von NCCL-Logeinträgen verstehen
Prüfen Sie, ob die NCCL-/gIB-Plug-ins korrekt geladen werden.
Prüfen Sie, ob die NCCL- und gIB-Versionen korrekt sind.
Häufige NCCL-Warnungen und ‑Fehler beheben

NCCL-Logs erfassen

Sie können NVIDIA Collective Communications Library-Logs (NCCL) verwenden, um NCCL-Fehler zu beheben. Sammeln Sie für das Debugging von Stabilitäts- oder Leistungsproblemen NCCL-Logs von allen Logging-Ebenen, während Sie die problematische Arbeitslast ausführen. Vermeiden Sie es, Logeinträge in die Console zu schreiben, da die schiere Menge der Logs verhindern kann, dass der Job fortgesetzt wird.

Um NCCL-Logs zu erfassen, legen Sie die folgenden Umgebungsvariablen fest:

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

Ersetzen Sie Folgendes:

DESIRED_PATH: der Pfad, unter dem Sie Ihre Logdateien speichern möchten

VM_NAME: der VM-Name

RANK_PROCESS_ID: die Prozess-ID des Rangs

NCCL-Logformat

NCCL-Logs sehen in etwa so aus:

# 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

Unabhängig von der Quelle haben NCCL-Logs ein Präfix, das in etwa so aussieht:

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

Prüfen, ob die NCCL-/gIB-Plug-ins korrekt geladen werden

NCCL/gIB besteht aus mehreren von Google entwickelten Plug-ins. Wenn keines der Plug-ins geladen wird, kann dies zu Leistungseinbußen und in einigen Fällen zu schwerwiegenden Fehlern führen.

Netzwerk-Plug-in (libnccl-net.so)

Wenn das gIB-Netzwerk-Plug-in korrekt geladen wurde, sollten NCCL-Logeinträge ähnlich den folgenden angezeigt werden:

... NCCL INFO Using network gIB

Wenn Sie Logeinträge sehen, die einem der folgenden ähneln, führen Sie die Schritte im Abschnitt Ein gemeinsam genutztes Objekt kann nicht geladen werden aus, um das Problem zu beheben.

# 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

Tuner-Plug‑in (libnccl-tuner.so)

Wenn das gIB-Tuner-Plug-in richtig geladen wurde, sollten NCCL-Logeinträge angezeigt werden, die in etwa so aussehen:

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

Wenn ein Logeintrag wie der folgende angezeigt wird, folgen Sie der Anleitung im Abschnitt Ein gemeinsam genutztes Objekt kann nicht geladen werden, um das Problem zu beheben.

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

CollNet-Plug-in

Obwohl diese Logeinträge auf einen Fehler hinweisen, sind sie zu erwarten und kein Grund zur Besorgnis:

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- und gIB-Version prüfen

Wir empfehlen, die im gIB-Installationsprogramm enthaltene NCCL-Version zu verwenden, um die neuesten Funktionen, die beste Leistung und die höchste Stabilität zu erzielen. Sie können jedoch eine benutzerdefinierte NCCL-Version für Tests verwenden, z. B. eine NCCL-Version, die mit dem von Ihnen ausgewählten Framework für maschinelles Lernen gebündelt ist.

Suchen Sie nach den folgenden NCCL-Logeinträgen, um die verwendete NCCL- und gIB-Version zu prüfen:

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

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

NCCL-/gIB-Umgebungsvariablen prüfen

Um eine gute NCCL-Leistung zu erzielen, stellen wir ein Skript bereit, mit dem Sie die empfohlenen NCCL-Umgebungsvariablen festlegen können. Bevor Sie Ihre Arbeitslast ausführen, müssen Sie das Skript in derselben Umgebung wie die Arbeitslast ausführen. Im NCCL-/gIB-Installationsprogramm befindet sich das Skript unter /usr/local/gib/set_nccl_env.sh. Wenn Sie dieses Script nicht verwenden und die NCCL-Umgebungsvariablen daher falsch festgelegt sind, kann es sein, dass der gIB NCCL Config Checker den Arbeitslastprozess beendet, NCCL abstürzt oder die NCCL-Leistung schlecht ist.

Suchen Sie nach NCCL-Logeinträgen, die den folgenden ähneln, um zu prüfen, ob die NCCL-/gIB-Umgebungsvariablen richtig angewendet werden:

# 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.

Vergleichen Sie die folgenden Werte mit den empfohlenen NCCL-Umgebungsvariablen.

GKE-Arbeitslastmanifest prüfen

In GKE muss Ihr Kubernetes-Arbeitslastmanifest mehrere erforderliche Einstellungen enthalten, damit NCCL/gIB reibungslos verwendet werden kann:

Im Manifest müssen die NCCL-/gIB-Binärdateien von /home/kubernetes/bin/gib auf der VM in /usr/local/gib in Ihrem Arbeitslast-Container bereitgestellt werden. /home/kubernetes/bin/nvidia auf der VM wird automatisch in /usr/local/nvidia in Ihrem Arbeitslastcontainer bereitgestellt.
In Ihrem Arbeitslastcontainer muss LD_LIBRARY_PATH auf /usr/local/gib/lib64:/usr/local/nvidia/lib64 gesetzt sein.
In Ihrem Cluster und Ihren Knotenpools muss GKE Multi-Networking eingerichtet sein und Ihr Arbeitslastmanifest muss die Multi-Networking-Annotationen enthalten, damit hostNetwork: true nicht festgelegt werden muss.

Ein tatsächliches Kubernetes-Arbeitslastmanifest in GKE sieht in etwa so aus:

...
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-Tabelle prüfen

In RoCE wird die GID-Tabelle (Global Identifier) verwendet, um RDMA-Traffic eindeutig zu adressieren. Wenn die GID-Tabelle beschädigt ist, kann kein RDMA-Traffic übertragen werden.

Wir stellen ein Script show_gids.sh zur Verfügung, mit dem die GID-Tabelle angezeigt wird. Im Installationsprogramm befindet es sich unter /usr/local/gib/scripts. Wenn Sie unser Installationsprogramm ohne Änderungen verwendet haben, wird es auf der VM unter /var/lib/gib/scripts installiert.

Wenn Sie das Skript in der VM ausführen, sollte eine Ausgabe ähnlich der folgenden angezeigt werden:

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
...

Prüfen Sie die Ausgabe und bestätigen Sie Folgendes:

Die GID-Tabelle hat die richtige Anzahl von Einträgen:
- Für A3 Ultra oder A4: 32 Einträge mit 4 Einträgen pro CX-7.
- Für A3 Mega: 32 Einträge mit 4 Einträgen pro CX-7.
- Für A3 High (8 GPUs) sind 16 Einträge mit 4 Einträgen pro CX-7 vorhanden.
- Für A4X: 16 Einträge mit 4 Einträgen pro CX-7.
Die GID-Einträge der einzelnen CX‑7 haben die Indexe 0, 1, 2 und 3.
Für jeden CX‑7 haben die Indexe 2 und 3 eine IPv4-Adresse, die mit der IPv4-Adresse des jeweiligen Geräts übereinstimmt (z. B. aus ip a).

Wenn einer dieser Punkte falsch ist, ist die GID-Tabelle beschädigt. Starten Sie Ihre VM neu oder starten Sie den Netzwerkmanager in Ihrem Gastbetriebssystem neu.

NCCL-Warnungen

NCCL-Logs haben mehrere Ebenen, wobei NCCL-Warnungen (NCCL WARN) die schwerwiegendsten sind. NCCL-Warnungen weisen in der Regel auf Fehler hin, die schwerwiegend sein können. NCCL hat keine Protokollebene, die die Arbeitslast automatisch beendet.

Ein freigegebenes Objekt kann nicht geladen werden

Der folgende Fehler tritt auf, wenn ein freigegebenes Objekt aufgrund Ihrer Einrichtung nicht geladen werden kann.

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

So beheben Sie das Problem:

Prüfen Sie, ob das freigegebene Objekt in Ihrer Umgebung installiert ist.
Das Verzeichnis des freigegebenen Objekts muss in der Umgebungsvariable $LD_LIBRARY_PATH enthalten sein.

Segment konnte nicht aus freigegebenem Objekt zugeordnet werden

Der folgende Fehler tritt auf, wenn das Verzeichnis des freigegebenen Objekts nicht ausführbar ist.

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

Führen Sie die folgenden Befehle aus, um das Problem zu beheben. In diesen Beispielen wird davon ausgegangen, dass die gIB-Binärdateien auf den VMs in /var/lib/gib installiert sind:

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

Die Gastkonfigurationsprüfung findet keine Konfigurationsdatei

Diese Art von Logeinträgen wird angezeigt, wenn der Gast-Konfigurationsprüfer keine Konfigurationsdatei findet, die er verwenden kann.

... 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

Um das Problem zu beheben, können Sie die Umgebungsvariable NCCL_SHIMNET_GUEST_CONFIG_CHECKER_CONFIG_FILE so festlegen, dass sie auf den Speicherort von guest_config.txtpb verweist. Der Standardspeicherort für die Konfigurationsdatei des NCCL/gIB-Installationsprogramms ist /usr/local/gib/configs/guest_config.txtpb.

Wir raten davon ab, den Gast-Konfigurationsprüfer zu deaktivieren, da er dazu beiträgt, Best Practices und eine korrekte Konfiguration zu gewährleisten. Bei Bedarf können Sie den Gastkonfigurationsprüfer jedoch deaktivieren, indem Sie die Umgebungsvariable NCCL_SHIMNET_SHIM_LAYERS auf UNUSED setzen.

Die Gastkonfigurationsprüfung hat eine Einstellung erzwungen oder empfohlen.

Die folgenden Fehler treten auf, wenn die NCCL-/gIB-Umgebungsvariablen nicht wie empfohlen festgelegt sind.

# 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)

So beheben Sie das Problem:

Folgen Sie der Anleitung in den Logs des Gastkonfigurationsprüfers.
Überprüfen Sie die Umgebungsvariablen für NCCL/gIB.

Der Tuner kann keine Konfigurationsdatei finden

Der folgende Fehler tritt auf, wenn das Tuner-Plug-in keine zu verwendende Konfigurationsdatei finden kann.

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

So beheben Sie das Problem:

Legen Sie die Umgebungsvariable NCCL_TUNER_CONFIG_PATH so fest, dass sie auf den Speicherort von tuner_config.txtpb verweist. Der Standardspeicherort für die Konfigurationsdatei des NCCL/gIB-Installationsprogramms ist /usr/local/gib/configs/guest_config.txtpb.
Überprüfen Sie die Umgebungsvariablen für NCCL/gIB.

Unzureichende glibc-Version

Der folgende Fehler tritt auf, wenn die lokale glibc-Version Ihrer Distribution zu alt ist. Das liegt höchstwahrscheinlich daran, dass die Linux-Distribution in Ihrer lokalen Umgebung zu alt ist. Für die NCCL-/gIB-Binärdateien ist glibc-Version 2.29 erforderlich.

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

Aktualisieren Sie zur Problembehebung Ihre Bilddistribution (z. B. Ubuntu 20.04 oder höher, RockyLinux 9 oder höher).

Nachricht gekürzt

Der folgende Fehler tritt auf, wenn Sie für verschiedene Ränge unterschiedliche NCCL-Versionen verwenden.

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

Prüfen Sie Ihre NCCL- und gIB-Version, um das Problem zu beheben. Wenn Sie GKE verwenden, prüfen oder installieren Sie das NCCL-/gIB-Installer-DaemonSet neu (Anleitung für A3U und A4 oder Anleitung für A4X).

libibverbs kann die Anbieterkonfiguration nicht laden

Der folgende Fehler tritt auf, wenn Sie das Verzeichnis mit den gIB-Binärdateien nicht in /usr/local/gib eingebunden haben. Dies führt nicht zu einem Fehler bei der Arbeitslast. NCCL greift jedoch auf TCP zurück, was zu einer schlechten Leistung führen kann.

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

Wenn Sie GKE verwenden, prüfen Sie das Arbeitslastmanifest, um das Problem zu beheben.

ibv_modify_qp-Fehler

Beim Vorbereiten von QPs für tatsächliche Netzwerktransaktionen durch das gIB-Netzwerk-Plug-in können verschiedene Fehler auftreten.

Ungültiges Argument (Fehlernummer 22)

Dieser Fehler tritt aus einem der folgenden Gründe auf:

Am anderen Ende des QP befindet sich eine beschädigte GID-Tabelle.
Die NCCL-/gIB-Umgebungsvariablen sind falsch konfiguriert, insbesondere NCCL_IB_GID_INDEX, NCCL_IB_TC und NCCL_IB_FIFO_TC.

... NCCL WARN Call to ibv_modify_qp failed with error Invalid argument errno 22

So beheben Sie das Problem:

Suchen Sie nach anderen ibv_modify_qp-Fehlern mit der Signatur No data available error 61 und folgen Sie der Anleitung zur Fehlerbehebung für Fehler 61.
Überprüfen Sie die Umgebungsvariablen für NCCL/gIB.

Keine Daten verfügbar (errno 61)

Dieser Fehler tritt aus einem der folgenden Gründe auf:

Diese VM hat eine beschädigte GID-Tabelle.
Die NCCL-/gIB-Umgebungsvariablen sind falsch konfiguriert, insbesondere NCCL_IB_GID_INDEX, NCCL_IB_TC und NCCL_IB_FIFO_TC.

... NCCL WARN Call to ibv_modify_qp failed with error No data available errno 61

So beheben Sie das Problem:

GID-Tabelle prüfen
NCCL-/gIB-Umgebungsvariablen prüfen

Wenn die GID-Tabelle beschädigt ist, versuchen Sie Folgendes:

(Kurzfristig) Starten Sie den Netzwerkmanager (z. B. networkd) auf der VM neu, bis die IP-Adresse der problematischen Schnittstelle aktualisiert wird.
1. Sie können networkd auf der VM mit sudo systemctl restart systemd-networkd neu starten.
2. Mit ip a können Sie die IP-Adresse aller Schnittstellen aufrufen.
3. Prüfen Sie, ob die GID-Tabelle wiederhergestellt wurde.
Wenden Sie sich an den Google-Support, um Unterstützung bei einer langfristigen Lösung zu erhalten.

Zeitüberschreitung der Verbindung (Fehlernummer 110)

Der folgende Fehler tritt auf, wenn es ein grundlegendes Verbindungsproblem zwischen den VMs gibt.

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

Wenden Sie sich an den Google-Support, um das Problem zu beheben.

QP Got Completion with Error

Dieser Fehler tritt aus einem der folgenden Gründe auf:

Zugrunde liegende Probleme mit der RDMA-Verbindung (Link-Flaps usw.).
Die NCCL-/gIB-Umgebungsvariablen sind falsch konfiguriert, insbesondere NCCL_IB_TIMEOUT und 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

Wenden Sie sich an den Google-Support, um das Problem zu beheben.

NCCL-/gIB-Logs zur Fehlerbehebung erfassen und verstehen Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.

NCCL-Logs erfassen

NCCL-Logformat

Prüfen, ob die NCCL-/gIB-Plug-ins korrekt geladen werden

Netzwerk-Plug-in (libnccl-net.so)

Tuner-Plug‑in (libnccl-tuner.so)

CollNet-Plug-in

NCCL- und gIB-Version prüfen

NCCL-/gIB-Umgebungsvariablen prüfen

GKE-Arbeitslastmanifest prüfen

GID-Tabelle prüfen

NCCL-Warnungen

Ein freigegebenes Objekt kann nicht geladen werden

Segment konnte nicht aus freigegebenem Objekt zugeordnet werden

Die Gastkonfigurationsprüfung findet keine Konfigurationsdatei

Die Gastkonfigurationsprüfung hat eine Einstellung erzwungen oder empfohlen.

Der Tuner kann keine Konfigurationsdatei finden

Unzureichende glibc-Version

Nachricht gekürzt

libibverbs kann die Anbieterkonfiguration nicht laden

ibv_modify_qp-Fehler

Ungültiges Argument (Fehlernummer 22)

Keine Daten verfügbar (errno 61)

Zeitüberschreitung der Verbindung (Fehlernummer 110)

QP Got Completion with Error

NCCL-/gIB-Logs zur Fehlerbehebung erfassen und verstehen