Executar verificações de integridade em GPUs e TPUs

O verificador de integridade do cluster é uma ferramenta de diagnóstico de autoatendimento que valida a prontidão da capacidade da GPU e do Cloud TPU antes de programar uma carga de trabalho. O verificador de integridade do cluster executa comparativos de mercado que simulam o tráfego real de carga de trabalho nos nós do acelerador para medir o desempenho dos aceleradores, da memória e das interconexões entre eles. Use os resultados para identificar e remover nós com falha antes que eles façam com que os jobs de treinamento ou inferência parem de responder, sejam executados lentamente ou falhem.

Para TPUs, o verificador de integridade do cluster complementa o monitoramento de integridade da TPU, que informa continuamente os sinais de integridade do hardware. O verificador de integridade do cluster executa ativamente cargas de trabalho na capacidade ociosa para medir o desempenho e expor falhas que só aparecem sob carga.

O verificador de integridade do cluster é totalmente de código aberto. Para ver o código-fonte, contribuir ou registrar problemas, consulte o repositório do GitHub do verificador de integridade do cluster.

Neste documento, descrevemos como instalar o verificador de integridade do cluster, executar uma verificação de integridade em reservas de GPU e TPU, interpretar os resultados e corrigir nós não íntegros.

Ambientes compatíveis

O verificador de integridade do cluster é compatível com os seguintes ambientes de implantação:

Ambiente Aceleradores compatíveis Ambiente do cliente Opções de instalação
Clusters do Google Kubernetes Engine (GKE) GPUs e TPUs (pools de nós que usam fatiamento estático ou dinâmico) Uma máquina Linux que tenha acesso kubectl ao cluster de destino. Pacote do Python ou imagem de contêiner
Clusters do Slurm Somente GPUs O controlador do Slurm ou o nó de login, em que os comandos sinfo e sbatch estão disponíveis. Somente pacote Python
Instâncias de TPU independentes Somente TPUs A própria instância de TPU Pacote Python ou imagem do contêiner (Container-Optimized OS)

O verificador de integridade do cluster é compatível com os seguintes tipos de máquina de GPU e TPU:

  • Tipos de máquina de GPU:
    • A5X: a5x-highgpu-4g-metal (somente GKE)
    • A4X Max: a4x-maxgpu-4g-metal
    • A4X: a4x-highgpu-4g
    • A4: a4-highgpu-8g
    • A3 Ultra: a3-ultragpu-8g
    • A3 Mega: a3-megagpu-8g
  • Tipos de máquina de TPU:

Pacotes de diagnóstico

É possível instalar o verificador de integridade do cluster como um pacote Python ou como uma imagem de contêiner. As duas opções oferecem a interface de linha de comando (CLI) chs e os comparativos de mercado de diagnóstico. Execute a CLI em uma máquina com acesso ao cluster do GKE, em um controlador do Slurm ou nó de login ou diretamente em uma instância de TPU independente. Em seguida, a CLI executa os testes de diagnóstico nos nós de GPU ou TPU de destino.

O verificador de integridade do cluster oferece dois pacotes de diagnóstico para cada tipo de acelerador:

  • Lite: executa uma verificação rápida. Em GPUs e instâncias de TPU independentes, o pacote Lite verifica hosts individuais. Nos pools de nós de TPU do GKE, ele também executa uma verificação coletiva rápida (tpu-collectives) na fração de TPU. Uma operação coletiva é um padrão de comunicação em que todos os aceleradores trocam dados, como AllReduce, que combina valores de cada acelerador e compartilha o resultado com todos os aceleradores. Use o pacote Lite para verificações de integridade rápidas ou antes de executar cargas de trabalho de host único.
  • Padrão: executa uma validação abrangente em toda a capacidade de destino. Em GPUs, o pacote Standard executa operações coletivas em vários nós e mede a largura de banda da memória da GPU. Nas TPUs, ele executa todos os testes Lite, além de testes de estresse de computação, memória e rede. Use o pacote Standard antes de executar cargas de trabalho de treinamento ou inferência de vários hosts, em que o desempenho e a estabilidade da rede sob carga sustentada afetam diretamente o desempenho do job.
Pacote Accelerator Testes Foco
lite GPU nvidia-smi, dcgm, gemm, nccl-single-node Validação rápida da integridade da GPU e do driver, da capacidade de computação e da comunicação entre GPUs no nó.
TPU tpu-info, tpu-gemm, tpu-hbm, tpu-host-device, tpu-collectives Validação rápida da integridade do dispositivo, da capacidade de computação, da largura de banda da memória de alta largura de banda (HBM), da largura de banda do host para o dispositivo e da largura de banda coletiva da interconexão entre chips (ICI).
standard GPU nvidia-smi, dcgm, gemm, nccl-cluster, nccl-pairwise, stream Validação de rede de vários nós nos nós de destino, além da largura de banda da memória.
TPU Todos os testes de TPU lite, além de tpu-compute-stress, tpu-hbm-stress e tpu-network-stress Testes de estresse prolongados que expõem instabilidade, corrupção silenciosa de dados e erros de bit de ICI.

O teste de GPU nccl-domain não faz parte de um pacote. Para executar nccl-domain, use a flag --tests.

Pacotes e testes de GPU

O verificador de integridade do cluster oferece os seguintes pacotes para nós de GPU:

  • Lite: valida o driver e o hardware da GPU, mede a capacidade de computação e executa um teste da NVIDIA Collective Communications Library (NCCL) em cada nó.
  • Padrão: executa coletivos NCCL em todos os nós de destino e entre pares de nós para medir o desempenho da rede entre nós e a largura de banda da memória.

A tabela a seguir descreve cada teste de GPU:

Teste Descrição Pacotes
nccl-single-node Executa testes coletivos da NCCL entre as GPUs em um único nó. lite
nvidia-smi Verifica a integridade básica da GPU e o driver dela usando a interface de gerenciamento do sistema NVIDIA. lite, standard
dcgm Executa diagnósticos do NVIDIA Data Center GPU Manager (DCGM) para realizar verificações profundas de hardware em cada GPU. lite, standard
gemm Executa multiplicações de matriz geral (GEMM, na sigla em inglês) para medir a capacidade de computação da GPU. lite, standard
nccl-cluster Executa testes coletivos do NCCL em todos os nós de destino para medir a largura de banda da rede em todo o cluster. standard
nccl-pairwise Executa testes da NCCL entre pares de nós para medir a latência entre nós e isolar nós ou links com falha. standard
stream Executa o comparativo de mercado STREAM para medir a largura de banda da memória da GPU. standard
nccl-domain Executa testes coletivos da NCCL em cada domínio NVLink de vários nós. Compatível apenas com tipos de máquina com domínios NVLink de vários nós. Nenhum (executar com --tests)

Pacotes e testes de TPU

O verificador de integridade do cluster oferece os seguintes pacotes para nós de TPU:

  • Lite: valida o desempenho dos chips de TPU e da HBM em cada host, mede a largura de banda de host para dispositivo e executa um teste de operações coletivas para medir a largura de banda da ICI.
  • Padrão: executa operações coletivas nos chips de TPU em uma fração, além de testes de estresse sustentados nos chips de TPU, HBM e links de ICI.

A tabela a seguir descreve cada teste de TPU:

Teste Descrição Pacotes
tpu-info Verifica a integridade básica da TPU, incluindo a contagem de dispositivos, a versão da LibTPU e o tipo de dispositivo TPU. lite, standard
tpu-gemm Executa multiplicações de matrizes gerais (GEMM, na sigla em inglês) para medir o pico sustentado de TFLOPS. lite, standard
tpu-hbm Mede a largura de banda de leitura e gravação da HBM. lite, standard
tpu-collectives Cronometra operações coletivas, como AllReduce e AllGather, para medir a largura de banda da ICI (somente clusters do GKE). lite, standard
tpu-host-device Mede a largura de banda de host para dispositivo. lite, standard
tpu-compute-stress Executa multiplicações de matrizes sustentadas para verificar a estabilidade computacional e expor a corrupção silenciosa de dados. standard
tpu-hbm-stress Estressa a HBM para medir a largura de banda máxima e validar a integridade de dados. standard
tpu-network-stress Envia payloads aleatórios grandes por links ICI para medir a largura de banda sustentada e detectar erros de bit (somente clusters do GKE). standard

Antes de começar

Antes de usar o verificador de integridade do cluster, instale as ferramentas necessárias, configure as permissões e conecte-se ao cluster ou à instância.

Instalações

Antes de executar uma verificação de integridade, conclua as instalações do ambiente de implantação.

Clusters do GKE

Para executar verificações de integridade em um cluster do GKE, verifique se você tem um cluster de destino e instale as ferramentas necessárias na máquina em que planeja executar as verificações:

Clusters do Slurm

Para executar verificações de integridade em um cluster do Slurm, verifique se você tem um cluster de GPU de destino e instale as ferramentas necessárias no controlador do Slurm ou no nó de login, em que os comandos sinfo e sbatch estão disponíveis:

Para clusters do Slurm, use a opção de instalação do pacote Python. O Slurm não é compatível com a opção de imagem de contêiner.

Instâncias de TPU independentes

Para executar verificações de integridade em uma instância de TPU independente, verifique se você tem uma instância de TPU de destino e instale as ferramentas necessárias diretamente nela:

Funções exigidas

Para receber as permissões necessárias para executar uma verificação de integridade, peça ao administrador para conceder a você o papel roles/compute.viewer no projeto. Esse papel permite que o verificador de integridade do cluster leia os metadados do Compute Engine e as informações de topologia dos nós.

Você também precisa dos seguintes papéis do Identity and Access Management (IAM), dependendo do seu ambiente de implantação:

Ambiente Funções exigidas
Clusters do GKE Desenvolvedor do Kubernetes Engine (roles/container.developer)
Clusters do Slurm
  • Login do SO do Compute (roles/compute.osLogin) ou Login de administrador no SO do Compute (roles/compute.osAdminLogin)
  • Usuário do túnel protegido pelo IAP (roles/iap.tunnelResourceAccessor), se a conexão for feita pelo Identity-Aware Proxy (IAP)
Instâncias de TPU independentes
  • Administrador da TPU (roles/tpu.admin)
  • Usuário do túnel protegido pelo IAP (roles/iap.tunnelResourceAccessor), se a conexão for feita pelo IAP

Se você configurar um bucket do Cloud Storage para relatórios, também precisará do papel de Administrador de objetos do Storage (roles/storage.objectAdmin) no bucket. Esse papel permite que o verificador de integridade do cluster faça upload de artefatos de resultado, como o relatório de integridade, para o bucket.

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Conectar-se ao cluster ou à instância

Conecte-se ao ambiente em que você planeja executar as verificações de integridade.

Clusters do GKE

Configure o Application Default Credentials (ADC) e o kubectl para se comunicar com o cluster do GKE:

gcloud auth application-default login
gcloud container clusters get-credentials CLUSTER_NAME \
    --location=LOCATION \
    --project=PROJECT_ID

Clusters do Slurm

Conecte-se ao controlador do Slurm ou ao nó de login usando SSH:

gcloud compute ssh SLURM_NODE_NAME \
    --zone=ZONE \
    --project=PROJECT_ID

Instâncias de TPU independentes

Conecte-se à instância de TPU independente usando SSH:

gcloud compute tpus tpu-vm ssh TPU_NAME \
    --zone=ZONE \
    --project=PROJECT_ID

Instalar o verificador de integridade do cluster

Instale o verificador de integridade do cluster na máquina em que você executa as verificações, o que depende do seu ambiente:

  • Clusters do GKE: qualquer máquina que tenha acesso kubectl ao cluster.
  • Clusters do Slurm: o controlador ou nó de login do Slurm.
  • Instâncias de TPU independentes: a própria instância de TPU.

Nos clusters do GKE e do Slurm, o verificador de integridade do cluster extrai automaticamente as imagens de contêiner de diagnóstico que correspondem aos nós de GPU ou TPU e as programa no cluster. Assim, não é necessário instalar nenhum software nos nós de computação individuais. Em uma instância de TPU independente, você instala e executa o verificador de integridade do cluster diretamente na instância.

É possível instalar o verificador de integridade do cluster como um pacote Python ou como uma imagem de contêiner. Os comandos chs no restante deste documento funcionam com qualquer uma das opções de instalação. Para ver informações detalhadas de uso de qualquer comando, anexe a flag --help.

Pacote Python

Crie um ambiente virtual do Python e instale o pacote do verificador de integridade do cluster do GitHub. Nos clusters do GKE e do Slurm, use o Python 3.12 ou mais recente. Em instâncias de TPU independentes (x86_64), use o Python 3.12 (com o Python 3.13 ou mais recente, o pip install não instala as dependências de comparativo de mercado da TPU e o chs run ignora a instância):

python3 -m venv chs-venv
source chs-venv/bin/activate
pip install git+https://github.com/GoogleCloudPlatform/cluster-health-scanner.git

Para instalar uma versão específica, anexe @VERSION ao URL do repositório:

pip install git+https://github.com/GoogleCloudPlatform/cluster-health-scanner.git@VERSION

Para ver uma lista de versões, consulte as versões do verificador de integridade do cluster no GitHub.

Imagem do contêiner

O verificador de integridade do cluster é distribuído como uma imagem de contêiner no Artifact Registry. A imagem é compatível com GPUs e TPUs. É possível usar a imagem de contêiner para clusters do GKE e instâncias de TPU independentes, mas não para clusters do Slurm.

  1. Configure o Docker para autenticação com o Artifact Registry e extraia a imagem do contêiner do verificador de integridade do cluster:

    gcloud auth configure-docker us-docker.pkg.dev
    docker pull us-docker.pkg.dev/gce-ai-infra/chs/chs:latest
    

    Para extrair uma versão específica em vez de latest, substitua latest pelo número da versão. Por exemplo, 0.3.0 para a versão v0.3.0 do GitHub. Para ver uma lista de versões, consulte as versões do verificador de integridade do cluster no GitHub.

  2. Crie um alias de shell para executar comandos chs diretamente. O alias que você cria depende do seu ambiente:

    • Clusters do GKE: o alias monta o arquivo kubeconfig e as credenciais do Google Cloud no modo somente leitura. O alias também armazena o estado das execuções no volume do Docker chs-local-state e grava arquivos de saída no diretório chs-output no diretório atual:

      alias chs='docker run --rm -it --network host \
          -v ~/.kube:/workspace/.kube:ro \
          -v ~/.config/gcloud:/workspace/.config/gcloud:ro \
          -v chs-local-state:/workspace/.local/share \
          -v "$(pwd)/chs-output":/workspace/chs-output \
          us-docker.pkg.dev/gce-ai-infra/chs/chs:latest'
      
    • Instâncias de TPU independentes: em uma instância de TPU que executa o Container-Optimized OS, a imagem de contêiner é a única opção de instalação compatível. O alias concede ao contêiner acesso aos dispositivos de TPU e ao namespace do PID do host da instância, ativa o sistema de arquivos raiz do host em /host e ativa as credenciais do Google Cloud no modo somente leitura. O alias também armazena o estado das execuções no volume do Docker chs-local-state e grava arquivos de saída no diretório chs-output no diretório atual:

      alias chs='docker run --rm -it --privileged --pid=host \
          -v /:/host \
          -v ~/.config/gcloud:/workspace/.config/gcloud:ro \
          -v chs-local-state:/workspace/.local/share \
          -v "$(pwd)/chs-output":/workspace/chs-output \
          us-docker.pkg.dev/gce-ai-infra/chs/chs:latest'
      

Opcional: configurar um bucket do Cloud Storage para relatórios

Por padrão, o verificador de integridade do cluster salva relatórios e registros de diagnóstico em um diretório de saída local. É possível configurar um bucket do Cloud Storage para também armazená-los remotamente.

  1. Se você ainda não tiver um bucket para relatórios de verificação de integridade, crie um:

    gcloud storage buckets create gs://BUCKET_NAME \
        --location=BUCKET_LOCATION \
        --project=PROJECT_ID
    
  2. Conceda o papel de Administrador de objetos do Storage (roles/storage.objectAdmin) à sua conta de usuário principal ou de serviço:

    gcloud storage buckets add-iam-policy-binding gs://BUCKET_NAME \
        --member=PRINCIPAL \
        --role=roles/storage.objectAdmin
    

    O membro PRINCIPAL é o principal que grava o relatório. Por exemplo, user:EMAIL ou serviceAccount:SERVICE_ACCOUNT_EMAIL.

  3. Defina o bucket em que o verificador de integridade do cluster armazena os relatórios. O bucket já precisa existir, porque o verificador de integridade do cluster não o cria automaticamente. Você só precisa executar esse comando uma vez para cada ambiente:

    chs configure storage gcs BUCKET_NAME
    

    Para armazenar relatórios em um prefixo de pasta no bucket, anexe o prefixo ao nome do bucket:

    chs configure storage gcs BUCKET_NAME/PREFIX
    

Fazer uma verificação de integridade

Nesta seção, descrevemos como verificar se os nós estão inativos, iniciar uma verificação e monitorar o progresso dela.

Verificar se os nós de destino estão inativos

O verificador de integridade do cluster só é executado na capacidade inativa e não interrompe nem remove automaticamente suas cargas de trabalho. Antes de iniciar uma verificação, drene ou interrompa as cargas de trabalho executadas nos nós ou na instância de destino.

Se o verificador de integridade do cluster detectar cargas de trabalho ativas em um nó ou uma instância de destino, ele vai processar a capacidade da seguinte maneira:

  • GPU: o verificador de integridade do cluster ignora os nós ocupados e executa a verificação nos nós inativos restantes.
  • TPU: a forma como o verificador de integridade do cluster lida com a capacidade ocupada depende do ambiente:
    • Clusters do GKE: os testes de TPU de vários hosts (tpu-collectives e tpu-network-stress) exigem uma fração inativa completa, enquanto os testes de TPU de host único podem ser executados em nós inativos individuais:
      • Pools de nós de fatiamento estático (--nodepools ou --nodes): se alguns nós em um pool estiverem ocupados quando você executar o pacote lite ou standard, o verificador de integridade do cluster vai registrar um aviso, omitir os testes de vários hosts e executar os testes de TPU de host único nos nós inativos restantes.
      • Pools de nós de fatiamento dinâmico (--nodepools ou --nodes): para segmentar um pool com --nodepools, todo o pool de nós precisa estar ocioso para que o verificador de integridade do cluster possa provisionar um recurso Slice de pool completo. Se você segmentar nós específicos com --nodes (no GKE versão 1.36.0-gke.3712000 ou posterior), o verificador de integridade do cluster provisionará uma subfração 2x2x1 individual para cada nó inativo, ignorará os nós ocupados e executará testes de TPU de host único nos nós inativos.
    • Instâncias de TPU independentes: o verificador de integridade do cluster não poderá ser executado se outro processo estiver usando os dispositivos de TPU em /dev/vfio.

Para garantir que a capacidade de destino esteja inativa, siga as etapas do seu ambiente.

Clusters do GKE

  1. Interrompa ou exclua todos os jobs ou pods de carga de trabalho ativos no pool de nós de destino ou aguarde a conclusão das cargas de trabalho em execução.

    Se você usar kubectl drain para remover cargas de trabalho do pool de nós, remova o isolamento dos nós antes de iniciar a verificação para que o verificador de integridade do cluster possa programar pods de diagnóstico neles (o verificador de integridade do cluster ignora nós isolados):

    kubectl drain -l cloud.google.com/gke-nodepool=NODE_POOL_NAME \
        --ignore-daemonsets --delete-emptydir-data
    kubectl uncordon -l cloud.google.com/gke-nodepool=NODE_POOL_NAME
    

    Verifique se nenhuma carga de trabalho nova está programada no pool de nós enquanto a verificação é executada.

  2. Verifique se não há pods de carga de trabalho no pool de nós:

    kubectl get pods --all-namespaces -o wide \
        --field-selector=status.phase=Running | grep NODE_POOL_NAME
    

    Os pods do sistema, como os gerenciados por DaemonSets no namespace kube-system, podem continuar em execução.

Clusters do Slurm

  1. Verifique se há jobs em execução na partição de destino:

    squeue --partition=PARTITION_NAME
    

    Se houver jobs em execução na partição, aguarde a conclusão deles ou cancele-os com scancel JOB_ID.

  2. Verifique se os nós na partição de destino estão no estado idle:

    sinfo --partition=PARTITION_NAME
    

Instâncias de TPU independentes

Verifique se nenhum outro processo está usando os dispositivos de TPU na instância:

sudo fuser -v /dev/vfio/*

Se algum processo estiver listado, aguarde a conclusão das cargas de trabalho ou interrompa os processos antes de iniciar uma verificação.

Iniciar uma verificação

As flags transmitidas ao comando chs run dependem do ambiente em que você executa o verificador de integridade do cluster. O verificador de integridade do cluster detecta automaticamente o programador e o tipo de acelerador, então não é necessário especificá-los.

Para listar os pacotes de diagnóstico e testes disponíveis para um tipo de acelerador, execute os seguintes comandos:

  • Para GPUs:

    chs list suites --gpu
    chs list tests --gpu
    
  • Para TPUs:

    chs list suites --tpu
    chs list tests --tpu
    

Pools de nós do GKE

Execute o verificador de integridade do cluster em qualquer máquina que tenha acesso kubectl ao cluster, como sua máquina local ou o Cloud Shell.

Para iniciar uma verificação em um ou mais pools de nós, execute o seguinte comando:

chs run \
    --nodepools=NODE_POOL_NAMES \
    --suite=SUITE

Substitua:

  • NODE_POOL_NAMES: uma lista separada por vírgulas dos pools de nós de GPU ou TPU a serem verificados. Por exemplo, a4-pool-1,a4-pool-2 ou tpu7x-pool-1,tpu7x-pool-2. Todos os pools de nós de destino precisam usar o mesmo tipo de máquina.
  • SUITE: o pacote de diagnóstico a ser executado, lite ou standard. Para mais informações sobre cada pacote, consulte Pacotes de diagnóstico.

Para executar testes específicos em vez de um pacote completo, substitua a flag --suite pela flag --tests e especifique uma lista separada por vírgulas de nomes de teste:

chs run \
    --nodepools=NODE_POOL_NAMES \
    --tests=TEST_NAMES

Para verificar nós específicos em vez de um pool de nós inteiro, substitua a flag --nodepools pela flag --nodes e especifique uma lista separada por vírgulas de nomes de nós.

Quando você especifica vários pools de nós na flag --nodepools, o verificador de integridade do cluster os processa com base no tipo de acelerador:

  • Pools de nós de GPU: combina todos os nós de GPU inativos nos pools de nós especificados em um único conjunto de destino e executa testes de vários nós (nccl-cluster e nccl-pairwise) em todos eles juntos.
  • Pools de nós de TPU: avalia cada pool de nós (fração de TPU) de forma independente e em paralelo em uma única execução, sem testes entre frações (várias frações).

Partições do Slurm

Execute o verificador de integridade do cluster no controlador do Slurm ou no nó de login, em que os comandos sinfo e sbatch estão disponíveis. O Slurm requer a opção de instalação do pacote Python. Para instruções de instalação, consulte Pacote Python.

Antes de iniciar uma verificação, configure as credenciais do Enroot no cluster para que os nós possam extrair imagens de comparativo de mercado de us-docker.pkg.dev:

gcloud auth configure-docker us-docker.pkg.dev
mkdir -p ~/.enroot
cat <<EOF > "${HOME}/.enroot/.credentials"
machine us-docker.pkg.dev login oauth2accesstoken password $(gcloud auth application-default print-access-token)
EOF

Inicie uma verificação em uma ou mais partições:

chs run \
    --partitions=PARTITION_NAMES \
    --suite=SUITE

Substitua:

  • PARTITION_NAMES: uma lista separada por vírgulas das partições do Slurm a serem verificadas.
  • SUITE: o pacote de diagnóstico a ser executado, lite ou standard. Para mais informações sobre cada pacote, consulte Pacotes de diagnóstico.

Para executar testes de GPU específicos em vez de um pacote completo, substitua a flag --suite pela flag --tests e especifique uma lista separada por vírgulas de nomes de teste (por exemplo, nccl-pairwise,gemm ou nccl-domain):

chs run \
    --partitions=PARTITION_NAMES \
    --tests=TEST_NAMES

Instâncias de TPU independentes

Execute o verificador de integridade do cluster diretamente na instância de TPU. A instância de TPU precisa expor os dispositivos de TPU em /dev/vfio. Para verificar isso na instância, execute ls /dev/vfio.

Se você não executar o verificador de integridade do cluster como o usuário root, aumente o limite de memlock antes de executar os testes de TPU:

ulimit -l unlimited

Para iniciar uma verificação na instância de TPU, execute o seguinte comando:

chs run --suite=SUITE

Substitua SUITE pelo pacote de diagnóstico a ser executado, lite ou standard. Para mais informações sobre cada pacote, consulte Pacotes de diagnóstico.

Para executar testes de TPU específicos em vez de um pacote completo, substitua a flag --suite pela flag --tests e especifique uma lista separada por vírgulas de nomes de teste (por exemplo, tpu-host-device,tpu-hbm-stress):

chs run --tests=TEST_NAMES

Ver execuções e resultados

O verificador de integridade do cluster armazena o histórico de execução e as definições de configuração localmente na máquina cliente em que você executa os comandos chs (em ~/.local/share/chs/ ou no volume do Docker chs-local-state ao usar a imagem do contêiner). Como resultado, os comandos chs history e chs results listam apenas as execuções iniciadas nesse ambiente.

Para listar as execuções anteriores e os IDs delas, execute o seguinte comando:

chs history

Para exibir os resultados de uma execução e os locais do relatório HTML interativo (bill_of_health.html) e do relatório JSON (bill_of_health.json), execute o seguinte comando:

chs results RUN_ID

Se você omitir RUN_ID, o verificador de integridade do cluster vai solicitar que você selecione uma execução. O comando mostra caminhos locais ou URIs do Cloud Storage se você tiver configurado um bucket. Ele lê os resultados armazenados de uma execução anterior e não inicia novos jobs no cluster ou na instância.

Cancelar uma verificação

Para cancelar uma verificação, interromper os jobs dela e remover os recursos que ela criou no cluster ou na instância, execute um dos seguintes comandos:

  • Cancele a execução mais recente:

    chs cancel
    
  • Cancelar uma execução específica:

    chs cancel RUN_ID
    
  • Cancele todas as execuções do verificador de integridade do cluster ou da instância, incluindo as iniciadas por outros usuários:

    chs cancel --all
    

Interprete os resultados

Quando uma verificação é concluída, o verificador de integridade do cluster salva os seguintes artefatos no diretório de saída local e faz o upload deles para o bucket do Cloud Storage, se você tiver configurado o armazenamento:

  • Relatório HTML interativo (bill_of_health.html): mostra cada teste, as métricas medidas e o status.
  • Relatório JSON (bill_of_health.json): contém as varreduras de parâmetros e as métricas medidas para cada teste.
  • Diretório do Workspace: contém os registros de diagnóstico.

Ver o relatório de integridade

Para encontrar os caminhos locais exatos ou os URIs do Cloud Storage (gs://BUCKET/PREFIX/bills_of_health/RUN_ID.html e gs://BUCKET/PREFIX/bills_of_health/RUN_ID.json) para os relatórios de uma verificação, execute o seguinte comando:

chs results RUN_ID

Se você configurou um bucket do Cloud Storage, é possível visualizar o relatório JSON diretamente do URI retornado por chs results:

gcloud storage cat gs://BUCKET_NAME/PREFIX/bills_of_health/RUN_ID.json

Conteúdo do relatório

O relatório de integridade lista todos os nós testados pelo verificador de integridade do cluster, além dos resultados de comparativo de mercado de cada nó. As verificações de GPU e TPU usam o mesmo formato de relatório. Cada nó recebe um dos seguintes status:

Status Descrição
HEALTHY Todos os testes atenderam ao desempenho esperado para o tipo de máquina.
DEGRADED O nó concluiu os testes, mas um ou mais resultados ficaram abaixo do desempenho esperado.
POTENTIALLY DEGRADED Um teste de triagem ficou abaixo do desempenho esperado, e o teste de estresse correspondente não foi executado para confirmar o resultado.
INCOMPLETE Um ou mais testes não foram executados, expiraram, foram cancelados ou não informaram métricas no nó.

O arquivo bill_of_health.json contém os seguintes campos de nível superior:

  • report_id: o identificador exclusivo da execução da verificação.
  • chs_version: a versão do verificador de integridade do cluster que gerou o relatório.
  • created_at: o carimbo de data/hora de quando o relatório foi gerado.
  • system_info: metadados sobre o sistema em teste, como o tipo de cluster e o tipo de máquina.
  • test_results: uma lista de objetos de resultado do teste. Cada entrada inclui os seguintes campos:
    • test_name: o nome do teste de diagnóstico.
    • result_status: o resultado do teste, como RESULT_STATUS_SUCCESS ou RESULT_STATUS_FAILED.
    • target_resources: os nós (node_name e instance_id) em que o teste foi executado.
    • metrics: as métricas medidas e os critérios de validação do teste.

O relatório de integridade usa um formato JSON consistente e estruturado. É possível carregar relatórios no BigQuery ou em outras ferramentas de análise e comparar relatórios de verificações sucessivas da mesma capacidade para detectar desvios graduais de desempenho.

Corrigir nós não íntegros

Se o relatório de integridade identificar um nó ou uma instância com o status DEGRADED, POTENTIALLY DEGRADED ou INCOMPLETE, siga estas etapas:

  1. Para descartar um problema temporário, execute novamente a verificação no pool de nós ou nó do GKE, na partição do Slurm ou na instância independente de TPU antes de isolar ou drenar o nó (o verificador de integridade do cluster ignora nós do GKE isolados e nós do Slurm drenados). Para ver instruções, consulte Iniciar uma verificação.

  2. Se o problema persistir, impeça que novas cargas de trabalho sejam programadas no nó ou na instância afetada:

    • Clusters do GKE: isole o nó não íntegro:

      kubectl cordon NODE_NAME
      
    • Clusters do Slurm: drene o nó não íntegro:

      sudo scontrol update NodeName=NODE_NAME State=DRAIN Reason="CHS unhealthy"
      
    • Instâncias de TPU independentes: não inicie novas cargas de trabalho na instância de TPU até terminar de corrigir o problema.

  3. Repare ou substitua o nó ou a instância usando uma das seguintes opções, dependendo do tipo de acelerador e do ambiente:

    Ao entrar em contato com o suporte, anexe o diretório do espaço de trabalho do diretório de saída local ou do bucket do Cloud Storage, que contém os registros de diagnóstico, e inclua o ID da execução.

  4. Depois que o nó ou a instância for reparado ou substituído, torne-o programável novamente para que o verificador de integridade do cluster não o ignore e, em seguida, execute uma nova verificação para confirmar se a capacidade está íntegra:

    • Clusters do GKE: remova a restrição do nó e execute novamente a verificação antes de programar novas cargas de trabalho:

      kubectl uncordon NODE_NAME
      
    • Clusters do Slurm: retome o nó para que ele retorne ao estado idle e execute novamente a verificação antes de programar novos jobs:

      sudo scontrol update NodeName=NODE_NAME State=RESUME
      
    • Instâncias de TPU independentes: execute novamente a verificação na instância e, em seguida, retome a execução das cargas de trabalho quando a verificação confirmar que a instância está íntegra.

Telemetria

O verificador de integridade do cluster envia métricas de uso anônimas ao Google para ajudar a melhorar a ferramenta e não coleta informações de identificação pessoal (PII). A telemetria é ativada por padrão. Para desativar, execute chs configure telemetry disable ou defina a variável de ambiente CHS_TELEMETRY=0.

A seguir

Para resolver problemas comuns com o verificador de integridade do cluster, consulte Resolver problemas do verificador de integridade do cluster.