Coletar e entender registros do NCCL/gIB

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

  • Coletar registros da NCCL.
  • Entender 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 da NCCL.

Coletar registros da NCCL

Use os registros da NVIDIA Collective Communications Library (NCCL) para depurar falhas da NCCL. Para depurar a estabilidade ou o desempenho, colete registros da 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 que o job continue.

Para coletar registros da 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 de processo da classificação

Formato de registro da NCCL

Os registros da NCCL são semelhantes aos seguintes:

# 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

Independentemente da origem, os registros do NCCL têm um prefixo semelhante ao seguinte:

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

Verificar se os plug-ins NCCL/gIB estão carregados corretamente

A NCCL/gIB é composta 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.

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. Se você optar por usar uma versão personalizada da NCCL para testes, como uma versão da NCCL que vem com o framework de machine learning de sua escolha, também será necessário instalar o pacote nccl-gib-plugins.

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

Se o plug-in de rede gIB for carregado corretamente, você vai encontrar 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, siga 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 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, siga 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 da NCCL para testes, como uma versão da NCCL que vem com o framework de machine learning de sua escolha. Nesse caso, instale o pacote nccl-gib-plugins.

Para verificar as versões do NCCL e do gIB que sua carga de trabalho usa, procure as seguintes entradas nos registros do NCCL:

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

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

Para confirmar se você está executando as versões recomendadas, compare as versões registradas do NCCL e do gIB com as versões incluídas no pacote nccl-gib mais recente. Recomendamos manter o nccl-gib atualizado em todos os nós. Para mais informações, consulte Instalar NCCL/gIB.

Se você fez upgrade do NCCL Core manualmente ou instalou o nccl-gib-plugins com uma biblioteca NCCL Core personalizada, verifique se a versão do NCCL registrada corresponde à versão de destino e se o plug-in NET/gIB é inicializado:

# 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

Se o registro exibir a versão anterior do NCCL em pacote em vez da versão atualizada, o vinculador dinâmico ainda estará carregando libnccl.so.2 de /usr/local/gib/lib64 ou /usr/local/gib/lib. Verifique se você removeu os arquivos libnccl.so* incluídos, conforme descrito em Fazer upgrade do NCCL Core em instalações atuais.

Verificar as variáveis de ambiente 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, use o script no mesmo ambiente que ela. 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, que o NCCL falhe ou que o desempenho do NCCL seja ruim.

Para verificar se as variáveis de ambiente NCCL/gIB foram aplicadas corretamente, procure entradas de registro NCCL semelhantes às seguintes:

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

Verificar o manifesto da carga de trabalho do GKE

No GKE, o manifesto de carga de trabalho do Kubernetes tem várias configurações necessárias para consumir 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 é montado automaticamente em /usr/local/nvidia no contêiner de carga de trabalho.
  • O contêiner de 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 rede múltipla do GKE configurada, e o manifesto da carga de trabalho precisa incluir as anotações de rede múltipla para evitar a necessidade de definir hostNetwork: true.

Um manifesto de carga de trabalho real do Kubernetes 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

Verifique a tabela de GID.

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

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

Ao executar o script na VM, você 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 GID tem o número correto de entradas:
    • Para A3 Ultra ou A4, 32 entradas com 4 entradas por CX-7.
    • Para 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 os índices 0, 1, 2 e 3.
  • Para cada CX-7, os índices 2 e 3 têm um endereço IPv4, que corresponde ao IPv4 desse dispositivo (por exemplo, de ip a).

Se algum desses itens for falso, a tabela de GID está 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 da NCCL geralmente indicam falhas, que podem ou não ser fatais. A NCCL não tem um nível de registro que interrompa automaticamente a carga de trabalho.

Não é possível carregar um objeto compartilhado

O erro a seguir 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

Esse erro também ocorre se você remover os arquivos libnccl.so* incluídos durante um upgrade manual do NCCL Core antes de instalar uma biblioteca NCCL Core compatível ou se o diretório de instalação da biblioteca não estiver no caminho de pesquisa do vinculador dinâmico.

Para resolver esse problema, faça o seguinte:

  1. Verifique se o objeto compartilhado está instalado no seu ambiente.
  2. Verifique se o diretório que contém o objeto compartilhado está no caminho de pesquisa do vinculador dinâmico ou na variável de ambiente $LD_LIBRARY_PATH.

Falha ao mapear o segmento do objeto compartilhado

O erro a seguir 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 seguintes comandos (esses 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 encontra 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 NCCL/gIB é /usr/local/gib/configs/guest_config.txtpb.

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

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 erro a seguir ocorre quando o plug-in do sintonizador não encontra 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 NCCL/gIB é /usr/local/gib/configs/guest_config.txtpb.
  2. Verifique as variáveis de ambiente NCCL/gIB.

Versão insuficiente do glibc

O erro a seguir ocorre quando a versão da glibc local da distribuição é muito antiga, provavelmente porque a distribuição do Linux no ambiente local é muito antiga. Os binários NCCL/gIB exigem a versão 2.29 do 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 erro a seguir ocorre quando você usa versões mistas da NCCL em classificações. Por exemplo, esse erro ocorre se você fizer upgrade do NCCL Core em apenas um subconjunto de nós no cluster, o que causa incompatibilidades de comunicação entre classificações atualizadas e não atualizadas:

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

Para resolver esse problema, verifique a versão do NCCL e do gIB e confirme se todos os nós do cluster executam exatamente a mesma versão do NCCL:

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, o 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

Há vários erros que podem ocorrer quando o plug-in de rede gIB prepara QPs para transações de rede reais.

Argumento inválido (errno 22)

O erro a seguir ocorre por um dos seguintes motivos:

  1. A outra extremidade do QP tem uma tabela de GID corrompida.
  2. As variáveis de ambiente NCCL/gIB estão configuradas incorretamente, 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 erro a seguir ocorre por um dos seguintes motivos:

  1. Esta VM tem uma tabela de GID corrompida.
  2. As variáveis de ambiente NCCL/gIB estão configuradas incorretamente, 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 GID.
  2. Verifique as variáveis de ambiente NCCL/gIB.

Se a tabela de GID 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 o networkd na VM usando sudo systemctl restart systemd-networkd.
    2. É possível ver o endereço IP de todas as interfaces usando ip a.
    3. Verifique se a tabela de GID 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 erro a seguir ocorre quando há um problema de conectividade básica 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: conclusão com erro

O erro a seguir ocorre por um dos seguintes motivos:

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