收集及解讀 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 開發的外掛程式組成。如果無法載入任何外掛程式，可能會導致效能不佳，有時甚至會發生嚴重錯誤。

網路外掛程式 (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 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：

資訊清單必須將 VM 中的 NCCL/gIB 二進位檔掛接到工作負載容器的 /usr/local/gib 中。/home/kubernetes/bin/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 中，全域 ID (GID) 表格用於唯一位址 RDMA 流量。如果 GID 表格損毀，就無法傳輸任何 RDMA 流量。

我們提供指令碼 show_gids.sh，用於顯示 GID 表格。在安裝程式中，這個檔案位於 /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

如何解決這個問題：

確認環境中已安裝共用物件。
確認共用物件的目錄位於 $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

訪客設定檢查工具找不到設定檔

如果客體設定檢查工具找不到可用的設定檔，就會顯示這類記錄項目。

... 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 環境變數。

Tuner 找不到設定檔

如果調諧器外掛程式找不到要使用的設定檔，就會發生下列錯誤。

... 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 安裝程式 DaemonSet (請參閱 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

如何解決這個問題：

尋找其他含有簽章 No data available error 61 的 ibv_modify_qp 錯誤，並按照錯誤 61 的緩解措施操作。
驗證 NCCL/gIB 環境變數。

沒有可用的資料 (errno 61)

發生這項錯誤的原因如下：

這個 VM 的 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 表格。
驗證 NCCL/gIB 環境變數。

如果 GID 表格損毀，請嘗試下列緩解措施：

(短期) 在 VM 上重新啟動網路管理員 (例如 networkd)，直到問題介面的 IP 位址重新整理為止。
1. 您可以使用 sudo systemctl restart systemd-networkd 重新啟動 VM 上的 networkd。
2. 您可以使用 ip a 查看所有介面的 IP 位址。
3. 檢查 GID 資料表是否已復原。
如需長期解決方案的相關協助，請與 Google 支援團隊聯絡。

連線逾時 (errno 110)

如果 VM 之間發生基本連線問題，就會出現下列錯誤。

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

如要解決這個問題，請與 Google 支援團隊聯絡。

QP Got Completion with Error

發生這項錯誤的原因如下：

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 支援團隊聯絡。

收集及解讀 NCCL/gIB 記錄，以利排解問題 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

收集 NCCL 記錄

NCCL 記錄格式

確認 NCCL/gIB 外掛程式已正確載入

網路外掛程式 (libnccl-net.so)

調諧器外掛程式 (libnccl-tuner.so)

CollNet 外掛程式

檢查 NCCL 和 gIB 版本

驗證 NCCL/gIB 環境變數

檢查 GKE 工作負載資訊清單

檢查 GID 表格

NCCL 警告

無法載入共用物件

無法對應共用物件中的區隔

訪客設定檢查工具找不到設定檔

訪客設定檢查工具強制或建議採用某項設定

Tuner 找不到設定檔

glibc 版本不足

訊息遭截斷

libibverbs 無法載入供應商設定

ibv_modify_qp 錯誤

引數無效 (errno 22)

沒有可用的資料 (errno 61)

連線逾時 (errno 110)

QP Got Completion with Error

收集及解讀 NCCL/gIB 記錄，以利排解問題