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: VM 名

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 バージョン(選択した機械学習(# Cloud では「ML」とする)フレームワークにバンドルされている 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 チューナー プラグインが正しく読み込まれている場合は、次のような 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 を使用することをおすすめします。ただし、選択した ML フレームワークにバンドルされている 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 では、NCCL/gIB をスムーズに使用するために、Kubernetes ワークロード マニフェストにいくつかの必須の設定があります。

  • マニフェストでは、VM の /home/kubernetes/bin/gib からワークロード コンテナの /usr/local/gib に NCCL/gIB バイナリをマウントする必要があります。VM の /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 トラフィックは通過できません。

GID テーブルを表示するスクリプト show_gids.sh が用意されています。インストーラでは、/usr/local/gib/scripts にあります。変更を加えずにインストーラを使用した場合は、VM の /var/lib/gib/scripts にインストールされます。

VM でスクリプトを実行すると、次のような出力が表示されます。

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 テーブルは破損しています。VM を再起動するか、ゲスト OS のネットワーク マネージャーを再起動することを検討してください。

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 バイナリが VM の /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. ゲスト Config Checker のログのガイダンスに沿って対応します。
  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 以降)。

メッセージが切り捨てられました

ランク間で NCCL バージョンを混在させると、次のエラーが発生します。たとえば、このエラーは、クラスタ内のノードのサブセットでのみ NCCL Core をアップグレードした場合に発生します。これにより、アップグレードされたランクとアップグレードされていないランクの間で通信の不一致が発生します。

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

この問題を解決するには、NCCL と gIB のバージョンを確認し、すべてのクラスタノードでまったく同じ NCCL バージョンが実行されていることを確認します。

  • Compute Engine VM で 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)

次のエラーは、次のいずれかの理由で発生します。

  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. この VM には、破損した 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. (短期)問題のあるインターフェースの IP アドレスが更新されるまで、VM でネットワーク マネージャー(networkd など)を再起動します。
    1. sudo systemctl restart systemd-networkd を使用して、VM で networkd を再起動できます。
    2. ip a を使用して、すべてのインターフェースの IP アドレスを確認できます。
    3. GID テーブルが復元されたことを確認します。
  2. 長期的な解決策については、Google サポートにお問い合わせください。

接続がタイムアウトしました(errno 110)

VM 間に基本的な接続の問題があると、次のエラーが発生します。

... 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 サポートにお問い合わせください。