Coletar e entender registros do NCCL/gIB para solução de problemas

Neste documento, descrevemos como coletar e interpretar registros do NCCL/gIB para resolver problemas de estabilidade e desempenho na AI Hypercomputer, incluindo orientações sobre como fazer o seguinte:

• Colete registros do NCCL.
• Entenda a estrutura das entradas de registro do NCCL.
• Verifique se os plug-ins NCCL/gIB foram carregados corretamente.
• Verifique se as versões do NCCL e do gIB estão corretas.
• Resolver problemas de avisos e erros comuns do NCCL.

Coletar registros do NCCL

É possível usar os registros da NVIDIA Collective Communications Library (NCCL) para depurar falhas da NCCL. Para qualquer depuração de estabilidade ou performance, colete registros do NCCL de todos os níveis de registro enquanto executa a carga de trabalho problemática. Evite despejar entradas de registro no console, porque o grande volume de registros pode impedir a continuidade do job.

Para coletar registros do NCCL, defina as seguintes variáveis de ambiente:

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

Substitua:

DESIRED_PATH: o caminho em que você quer armazenar os arquivos de registro

VM_NAME: o nome da VM.

RANK_PROCESS_ID: o ID do processo do ranking

Formato do registro do NCCL

Os registros do NCCL são semelhantes a estes:

# 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

Independente da origem, os registros do NCCL têm um prefixo semelhante a este:

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

Verificar se os plug-ins NCCL/gIB foram carregados corretamente

O NCCL/gIB é composto por vários plug-ins desenvolvidos pelo Google. A falha ao carregar qualquer um dos plug-ins pode resultar em desempenho ruim e, em alguns casos, erros fatais.

Plug-in de rede (libnccl-net.so)

Se o plug-in de rede gIB for carregado corretamente, você verá entradas de registro do NCCL semelhantes a estas:

... NCCL INFO Using network gIB

Se você encontrar entradas de registro semelhantes a qualquer uma das seguintes, use as etapas na seção Não é possível carregar um objeto compartilhado para corrigir o problema.

# 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

Plug-in do sintonizador (libnccl-tuner.so)

Se o plug-in do sintonizador gIB for carregado corretamente, você verá entradas de registro do NCCL semelhantes a estas:

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

Se você encontrar uma entrada de registro semelhante à seguinte, use as etapas na seção Não é possível carregar um objeto compartilhado para corrigir o problema.

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

Plug-in CollNet

Embora essas entradas de registro indiquem uma falha, elas são esperadas e não são motivo de preocupação:

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.

Verificar a versão do NCCL e do gIB

Recomendamos que você use o NCCL incluído no instalador do gIB para garantir os recursos mais recentes, o melhor desempenho e a maior estabilidade. No entanto, é possível usar uma versão personalizada do NCCL para testes, como uma versão do NCCL agrupada com a estrutura de machine learning escolhida.

Para verificar a versão do NCCL e do gIB usada, procure as seguintes entradas de registro do NCCL:

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

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

Verificar variáveis de ambiente do NCCL/gIB

Para alcançar um bom desempenho do NCCL, fornecemos um script que pode ser usado para definir as variáveis de ambiente recomendadas do NCCL. Antes de executar a carga de trabalho, crie o script no mesmo ambiente da carga de trabalho. No instalador do NCCL/gIB, o script está em /usr/local/gib/set_nccl_env.sh. Se você não usar esse script e, como resultado, as variáveis de ambiente do NCCL forem definidas incorretamente, é possível que o verificador de configuração do gIB NCCL encerre a carga de trabalho, o NCCL falhe ou o desempenho do NCCL seja ruim.

Para verificar se as variáveis de ambiente do NCCL/gIB foram aplicadas corretamente, procure entradas de registro do NCCL semelhantes a estas:

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

Compare os valores a seguir com as variáveis de ambiente recomendadas do NCCL.

Verificar o manifesto da carga de trabalho do GKE

No GKE, o manifesto da carga de trabalho do Kubernetes tem várias configurações necessárias para consumir o NCCL/gIB sem problemas:

• O manifesto precisa montar os binários NCCL/gIB de /home/kubernetes/bin/gib na VM para /usr/local/gib no contêiner de carga de trabalho. Observe que /home/kubernetes/bin/nvidia na VM é ativado automaticamente em /usr/local/nvidia no contêiner de carga de trabalho.
• O contêiner da carga de trabalho precisa definir LD_LIBRARY_PATH como /usr/local/gib/lib64:/usr/local/nvidia/lib64.
• O cluster e os pools de nós precisam ter a multirrede do GKE configurada, e o manifesto da carga de trabalho precisa incluir as anotações de multirrede para evitar a necessidade de definir hostNetwork: true.

Um manifesto de carga de trabalho do Kubernetes real no GKE é semelhante a este:

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

Verificar a tabela de GIDs

No RoCE, a tabela de identificador global (GID) é usada para endereçar o tráfego RDMA de maneira exclusiva. Se a tabela GID estiver corrompida, nenhum tráfego RDMA poderá passar.

Oferecemos um script show_gids.sh para mostrar a tabela de GIDs. No instalador, ele está localizado em /usr/local/gib/scripts. Se você usou nosso instalador sem modificações, ele será instalado em /var/lib/gib/scripts na VM.

Ao executar o script na VM, você vai ver uma saída semelhante a esta:

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

Analise a saída e confirme o seguinte:

• A tabela de GIDs tem o número correto de entradas:
  • Para A3 Ultra ou A4, 32 entradas com 4 entradas por CX-7.
  • Para o A3 Mega, 32 entradas com 4 entradas por CX-7.
  • Para A3 High (8 GPUs), 16 entradas com 4 entradas por CX-7.
  • Para A4X, 16 entradas com 4 entradas por CX-7.
• As entradas de GID de cada CX-7 têm índices 0, 1, 2 e 3.
• Para cada CX-7, os índices 2 e 3 têm um endereço IPv4, e esse endereço IP corresponde ao IPv4 do dispositivo (por exemplo, de ip a).

Se algum desses itens for falso, a tabela de GIDs estará corrompida. Reinicie a VM ou o gerenciador de rede no SO convidado.

Avisos da NCCL

Os registros da NCCL têm vários níveis, sendo os avisos da NCCL (NCCL WARN) os mais graves. Os avisos do NCCL geralmente indicam falhas, que podem ou não ser fatais. O NCCL não tem um nível de registro em que a carga de trabalho é interrompida automaticamente.

Não é possível carregar um objeto compartilhado

O seguinte erro ocorre quando um objeto compartilhado não pode ser carregado devido à sua configuração.

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

Para resolver o problema:

1. Verifique se o objeto compartilhado está instalado no seu ambiente.
2. Verifique se o diretório do objeto compartilhado está na variável de ambiente $LD_LIBRARY_PATH.

Não foi possível mapear o segmento do objeto compartilhado

O seguinte erro ocorre quando o diretório do objeto compartilhado não é executável.

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

Para resolver o problema, execute os comandos a seguir. Estes exemplos pressupõem que os binários do gIB estão instalados em /var/lib/gib nas VMs:

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

O Guest Config Checker não consegue encontrar um arquivo de configuração

Entradas de registro como essas aparecem quando o verificador de configuração convidado não consegue encontrar um arquivo de configuração para usar.

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

Para resolver o problema, defina a variável de ambiente NCCL_SHIMNET_GUEST_CONFIG_CHECKER_CONFIG_FILE para apontar para o local de guest_config.txtpb. O local padrão do arquivo de configuração do instalador do NCCL/gIB é /usr/local/gib/configs/guest_config.txtpb.

Não recomendamos desativar o verificador de configuração do convidado, porque ele ajuda a garantir as práticas recomendadas e a configuração adequada. No entanto, se necessário, é possível desativar o verificador de configuração do convidado definindo a variável de ambiente NCCL_SHIMNET_SHIM_LAYERS como UNUSED.

O verificador de configuração de convidado aplicou ou recomendou uma configuração

Os erros a seguir ocorrem quando as variáveis de ambiente NCCL/gIB não são definidas conforme recomendado.

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

Para resolver o problema:

1. Siga as orientações dos registros do verificador de configuração do convidado.
2. Verifique as variáveis de ambiente NCCL/gIB.

O Tuner não consegue encontrar um arquivo de configuração

O seguinte erro ocorre quando o plug-in de ajuste não consegue encontrar um arquivo de configuração para usar.

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

Para resolver o problema:

1. Defina a variável de ambiente NCCL_TUNER_CONFIG_PATH para apontar para o local de tuner_config.txtpb. O local padrão do arquivo de configuração do instalador do NCCL/gIB é /usr/local/gib/configs/guest_config.txtpb.
2. Verifique as variáveis de ambiente NCCL/gIB.

Versão do glibc insuficiente

O seguinte erro ocorre quando a versão glibc local da sua distribuição é muito antiga, provavelmente porque a distribuição Linux no seu ambiente local é muito antiga. Os binários NCCL/gIB exigem a versão 2.29 da glibc.

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

Para resolver o problema, faça upgrade da distribuição de imagens (por exemplo, Ubuntu 20.04 ou mais recente, RockyLinux 9 ou mais recente).

Mensagem truncada

O seguinte erro ocorre quando você usa versões mistas do NCCL em diferentes classificações.

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

Para resolver o problema, verifique as versões do NCCL e do gIB. Se você estiver usando o GKE, verifique ou reinstale o daemonset do instalador do NCCL/gIB. Consulte as instruções para A3U e A4 ou instruções para A4X.

libibverbs não pode carregar a configuração do provedor

O erro a seguir ocorre quando você não monta o diretório que contém os binários do gIB em /usr/local/gib. Isso não vai causar uma falha na carga de trabalho. No entanto, a NCCL volta a usar o TCP e pode causar um desempenho ruim.

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

Para resolver o problema, se você estiver usando o GKE, verifique o manifesto da carga de trabalho.

Erros de ibv_modify_qp

Você pode encontrar vários erros enquanto o plug-in de rede gIB prepara QPs para transações de rede reais.

Argumento inválido (errno 22)

O seguinte erro ocorre por um dos seguintes motivos:

1. A outra extremidade do QP tem uma tabela GID corrompida.
2. As variáveis de ambiente NCCL/gIB estão mal configuradas, especialmente NCCL_IB_GID_INDEX, NCCL_IB_TC e NCCL_IB_FIFO_TC.

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

Para resolver o problema:

1. Procure outros erros ibv_modify_qp com a assinatura No data available error 61 e siga as instruções de mitigação para o erro 61.
2. Verifique as variáveis de ambiente NCCL/gIB.

Nenhum dado disponível (errno 61)

O seguinte erro ocorre por um dos seguintes motivos:

1. Esta VM tem uma tabela GID corrompida.
2. As variáveis de ambiente NCCL/gIB estão mal configuradas, especialmente NCCL_IB_GID_INDEX, NCCL_IB_TC e NCCL_IB_FIFO_TC.

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

Para resolver o problema, primeiro verifique a causa:

1. Verifique a tabela de GIDs.
2. Verifique as variáveis de ambiente do NCCL/gIB.

Se a tabela de GIDs estiver corrompida, tente as seguintes mitigações:

1. (Curto prazo) Reinicie o gerenciador de rede (por exemplo, networkd) na VM até que o endereço IP da interface problemática seja atualizado.
   1. É possível reiniciar networkd na VM usando sudo systemctl restart systemd-networkd.
   2. É possível conferir o endereço IP de todas as interfaces usando ip a.
   3. Verifique se a tabela de GIDs foi recuperada.
2. Entre em contato com o Suporte do Google para receber ajuda com uma solução de longo prazo.

Tempo limite de conexão expirado (errno 110)

O seguinte erro ocorre quando há um problema básico de conectividade entre as VMs.

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

Para resolver o problema, entre em contato com o Suporte do Google.

QP Got Completion with Error

O seguinte erro ocorre por um dos seguintes motivos:

1. Problemas subjacentes de conexão RDMA (flaps de link etc.).
2. As variáveis de ambiente do NCCL/gIB estão mal configuradas, especialmente NCCL_IB_TIMEOUT e 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

Para resolver o problema, entre em contato com o Suporte do Google.