Esegui scansioni di integrità su GPU e TPU

Lo scanner di integrità del cluster è uno strumento di diagnostica self-service che convalida l'idoneità della capacità delle GPU e delle Cloud TPU prima di pianificare un workload. Lo scanner di integrità del cluster esegue benchmark che simulano il traffico reale dei workload sui nodi dell'acceleratore per misurare le prestazioni degli acceleratori, della loro memoria e delle interconnessioni tra loro. Puoi utilizzare i risultati per identificare e rimuovere i nodi difettosi prima che causino l'interruzione della risposta, il rallentamento o l'errore dei job di addestramento o inferenza.

Per le TPU, lo scanner di integrità del cluster integra il monitoraggio dell'integrità delle TPU, che segnala continuamente gli indicatori di integrità dell'hardware. Lo scanner di integrità del cluster esegue attivamente i workload sulla capacità inattiva per misurare le prestazioni ed esporre gli errori che si verificano solo sotto carico.

Lo scanner per l'integrità del cluster è completamente open source. Per visualizzare il codice sorgente, contribuire o segnalare problemi, consulta il repository GitHub dello scanner di integrità del cluster.

Questo documento descrive come installare lo scanner di integrità del cluster, eseguire un'analisi di integrità sulle prenotazioni di GPU e TPU, interpretare i risultati e correggere i nodi non integri.

Ambienti supportati

Lo scanner per l'integrità dei cluster supporta i seguenti ambienti di deployment:

Ambiente Acceleratori supportati Ambiente client Opzioni di installazione
Cluster Google Kubernetes Engine (GKE) GPU e TPU (node pool che utilizzano lo slicing statico o dinamico) Un computer Linux con accesso kubectl al cluster di destinazione Pacchetto Python o immagine container
Cluster Slurm Solo GPU Il controller Slurm o il nodo di accesso, dove sono disponibili i comandi sinfo e sbatch Solo pacchetto Python
Istanze TPU autonome Solo TPU L'istanza TPU stessa Pacchetto Python o immagine container (Container-Optimized OS)

Lo scanner per l'integrità del cluster supporta i seguenti tipi di macchine GPU e TPU:

  • Tipi di macchine GPU:
    • A5X: a5x-highgpu-4g-metal (solo 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
  • Tipi di macchine TPU:

Suite di diagnostica

Puoi installare lo scanner di integrità del cluster come pacchetto Python o come immagine container. Entrambe le opzioni forniscono l'interfaccia a riga di comando (CLI) chs e i benchmark di diagnostica. Esegui l'interfaccia a riga di comando da una macchina con accesso al tuo cluster GKE, su un controller Slurm o un nodo di accesso o direttamente su un'istanza TPU autonoma. La CLI esegue quindi i test diagnostici sui nodi GPU o TPU di destinazione.

Lo scanner di integrità del cluster fornisce due suite di diagnostica per ogni tipo di acceleratore:

  • Lite: esegue un controllo di screening rapido. Sulle GPU e sulle istanze TPU autonome, la suite Lite controlla i singoli host. Sui pool di nodi TPU GKE, esegue anche un rapido controllo collettivo (tpu-collectives) sulla sezione TPU. Un'operazione collettiva è un pattern di comunicazione in cui tutti gli acceleratori si scambiano dati, ad esempio AllReduce, che combina i valori di ogni acceleratore e condivide il risultato con tutti gli acceleratori. Utilizza la suite Lite per controlli di integrità rapidi o prima di eseguire workload su un singolo host.
  • Standard: esegue una convalida completa della capacità target. Sulle GPU, la suite Standard esegue operazioni collettive su più nodi e misura la larghezza di banda della memoria GPU. Sulle TPU, esegue tutti i test Lite, oltre a test di stress prolungato di calcolo, memoria e rete. Utilizza la suite Standard prima di eseguire workload di addestramento o inferenza multi-host, in cui le prestazioni e la stabilità della rete con un carico sostenuto influiscono direttamente sulle prestazioni dei job.
Suite Acceleratore Test Evidenzia
lite GPU nvidia-smi, dcgm, gemm, nccl-single-node Convalida rapida dell'integrità di GPU e driver, del throughput di calcolo e della comunicazione tra GPU all'interno del nodo.
TPU tpu-info, tpu-gemm, tpu-hbm, tpu-host-device, tpu-collectives Convalida rapida dello stato del dispositivo, del throughput di calcolo, della larghezza di banda della memoria a larghezza di banda elevata (HBM), della larghezza di banda da host a dispositivo e della larghezza di banda collettiva dell'Inter-Chip Interconnect (ICI).
standard GPU nvidia-smi, dcgm, gemm, nccl-cluster, nccl-pairwise, stream Convalida della rete multi-nodo tra i nodi di destinazione, oltre alla larghezza di banda della memoria.
TPU Tutti i test TPU lite, più tpu-compute-stress, tpu-hbm-stress e tpu-network-stress Stress test prolungati che rivelano instabilità, danneggiamento silenzioso dei dati ed errori di bit ICI.

Il test della GPU nccl-domain non fa parte di una suite. Per eseguire nccl-domain, utilizza il flag --tests.

Suite e test GPU

Lo scanner per l'integrità del cluster fornisce le seguenti suite per i nodi GPU:

  • Lite: convalida il driver e l'hardware della GPU, misura il throughput di calcolo ed esegue un test della NVIDIA Collective Communications Library (NCCL) all'interno di ogni nodo.
  • Standard: esegue i collettivi NCCL su tutti i nodi di destinazione e tra coppie di nodi per misurare le prestazioni della rete tra nodi e misura la larghezza di banda della memoria.

La tabella seguente descrive ogni test della GPU:

Test Descrizione Suite
nccl-single-node Esegue test collettivi NCCL tra le GPU all'interno di un singolo nodo. lite
nvidia-smi Controlla lo stato di base della GPU e il driver della GPU utilizzando l'interfaccia di gestione del sistema NVIDIA. lite, standard
dcgm Esegue la diagnostica di NVIDIA Data Center GPU Manager (DCGM) per eseguire controlli hardware approfonditi su ogni GPU. lite, standard
gemm Esegue moltiplicazioni di matrici generali (GEMM) per misurare il throughput di calcolo della GPU. lite, standard
nccl-cluster Esegue test collettivi NCCL su tutti i nodi di destinazione per misurare la larghezza di banda della rete a livello di cluster. standard
nccl-pairwise Esegue test NCCL tra coppie di nodi per misurare la latenza tra i nodi e isolare i nodi o i link difettosi. standard
stream Esegue il benchmark STREAM per misurare la larghezza di banda della memoria GPU. standard
nccl-domain Esegue test collettivi NCCL all'interno di ogni dominio NVLink multi-nodo. Supportato solo su tipi di macchine con domini NVLink multinodo. Nessuno (esegui con --tests)

Suite e test TPU

Lo scanner per l'integrità del cluster fornisce le seguenti suite per i nodi TPU:

  • Lite: convalida le prestazioni dei chip TPU e dell'HBM su ogni host, misura la larghezza di banda da host a dispositivo ed esegue un test delle operazioni collettive per misurare la larghezza di banda ICI.
  • Standard: esegue operazioni collettive sui chip TPU in una sezione, oltre a stress test prolungati sui chip TPU, sull'HBM e sui link ICI.

La tabella seguente descrive ogni test della TPU:

Test Descrizione Suite
tpu-info Controlla lo stato di integrità di base della TPU, inclusi il numero di dispositivi, la versione di LibTPU e il tipo di dispositivo TPU. lite, standard
tpu-gemm Esegue moltiplicazioni di matrici generali (GEMM) per misurare i TFLOPS di picco sostenuti. lite, standard
tpu-hbm Misura la larghezza di banda di lettura e scrittura della memoria HBM. lite, standard
tpu-collectives Misura il tempo delle operazioni collettive, come AllReduce e AllGather, per misurare la larghezza di banda ICI (solo cluster GKE). lite, standard
tpu-host-device Misura la larghezza di banda da host a dispositivo. lite, standard
tpu-compute-stress Esegue moltiplicazioni di matrici prolungate per verificare la stabilità computazionale ed esporre danni silenziosi dei dati. standard
tpu-hbm-stress Sottopone a stress test l'HBM per misurare la larghezza di banda massima e convalidare l'integrità dei dati. standard
tpu-network-stress Invia payload casuali di grandi dimensioni tramite link ICI per misurare la larghezza di banda sostenuta e rilevare errori di bit (solo cluster GKE). standard

Prima di iniziare

Prima di utilizzare lo scanner per l'integrità del cluster, installa gli strumenti richiesti, configura le autorizzazioni e connettiti al cluster o all'istanza.

Installazioni

Prima di eseguire un'analisi di integrità, completa le installazioni per l'ambiente di deployment.

Cluster GKE

Per eseguire analisi di integrità su un cluster GKE, assicurati di avere un cluster di destinazione e installa gli strumenti richiesti sulla macchina su cui prevedi di eseguire le analisi:

Cluster Slurm

Per eseguire i controlli di integrità su un cluster Slurm, assicurati di avere un cluster GPU di destinazione e installa gli strumenti richiesti sul controller Slurm o sul nodo di accesso, dove sono disponibili i comandi sinfo e sbatch:

Per i cluster Slurm, utilizza l'opzione di installazione del pacchetto Python. Slurm non supporta l'opzione dell'immagine container.

Istanze TPU autonome

Per eseguire scansioni di integrità su un'istanza TPU autonoma, assicurati di avere un'istanza TPU di destinazione e installa gli strumenti richiesti direttamente sull'istanza:

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per eseguire un controllo di integrità, chiedi all'amministratore di concederti il ruolo roles/compute.viewer nel progetto. Questo ruolo consente allo scanner di integrità del cluster di leggere i metadati di Compute Engine e le informazioni sulla topologia dei nodi.

A seconda dell'ambiente di deployment, devi disporre anche dei seguenti ruoli IAM (Identity and Access Management):

Ambiente Ruoli obbligatori
Cluster GKE Kubernetes Engine Developer (roles/container.developer)
Cluster Slurm
  • Compute OS Login (roles/compute.osLogin) o Compute OS Admin Login (roles/compute.osAdminLogin)
  • Utente tunnel protetto da IAP (roles/iap.tunnelResourceAccessor), se la connessione avviene tramite Identity-Aware Proxy (IAP)
Istanze TPU autonome
  • Amministratore TPU (roles/tpu.admin)
  • Utente del tunnel con protezione IAP (roles/iap.tunnelResourceAccessor), se la connessione avviene tramite IAP

Se configuri un bucket Cloud Storage per i report, devi anche disporre del ruolo Storage Object Admin (roles/storage.objectAdmin) sul bucket. Questo ruolo consente allo scanner di integrità del cluster di caricare nel bucket gli artefatti dei risultati, come il report sull'integrità.

Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Connettiti al cluster o all'istanza

Connettiti all'ambiente in cui prevedi di eseguire le scansioni di integrità.

Cluster GKE

Configura le Credenziali predefinite dell'applicazione (ADC) e kubectl per comunicare con il tuo cluster GKE:

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

Cluster Slurm

Connettiti al controller Slurm o al nodo di accesso utilizzando SSH:

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

Istanze TPU autonome

Connettiti alla tua istanza TPU autonoma utilizzando SSH:

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

Installa lo scanner per l'integrità del cluster

Installa lo scanner per l'integrità del cluster sulla macchina in cui esegui le scansioni, che dipende dal tuo ambiente:

  • Cluster GKE: qualsiasi macchina che abbia accesso kubectl al tuo cluster.
  • Cluster Slurm: il controller Slurm o il nodo di accesso.
  • Istanze TPU autonome: l'istanza TPU stessa.

Sui cluster GKE e Slurm, lo scanner di integrità del cluster estrae automaticamente le immagini container di diagnostica che corrispondono ai nodi GPU o TPU e le pianifica sul cluster, in modo che non sia necessario installare alcun software sui singoli nodi di computing. Su un'istanza TPU autonoma, installi ed esegui lo scanner di integrità del cluster direttamente sull'istanza.

Puoi installare lo scanner di integrità del cluster come pacchetto Python o come immagine container. I comandi chs nel resto di questo documento funzionano con entrambe le opzioni di installazione. Per visualizzare informazioni dettagliate sull'utilizzo di un comando, aggiungi il flag --help.

Pacchetto Python

Crea un ambiente virtuale Python e installa il pacchetto Cluster Health Scanner da GitHub. Sui cluster GKE e Slurm, utilizza Python 3.12 o versioni successive. Sulle istanze TPU autonome (x86_64), devi utilizzare Python 3.12 (con Python 3.13 o versioni successive, pip install non installa le dipendenze del benchmark TPU e chs run salta l'istanza):

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

Per installare una release specifica, aggiungi @VERSION all'URL del repository:

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

Per un elenco delle release, consulta le release dello scanner di integrità del cluster su GitHub.

Immagine container

Lo scanner per l'integrità del cluster viene distribuito come immagine container in Artifact Registry. L'immagine supporta sia GPU che TPU. Puoi utilizzare l'immagine container per i cluster GKE e le istanze TPU autonome, ma non per i cluster Slurm.

  1. Configura Docker per l'autenticazione con Artifact Registry ed esegui il pull dell'immagine container dello scanner di integrità del cluster:

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

    Per eseguire il pull di una release specifica anziché di latest, sostituisci latest con il numero di versione. Ad esempio, 0.3.0 per la release GitHub v0.3.0. Per un elenco delle release, consulta Release di Cluster Health Scanner su GitHub.

  2. Crea un alias della shell per eseguire direttamente i comandi chs. L'alias che crei dipende dall'ambiente:

    • Cluster GKE: l'alias monta il file kubeconfig e le credenziali Google Cloud in modalità di sola lettura. L'alias memorizza anche lo stato delle esecuzioni nel volume Docker chs-local-state e scrive i file di output nella directory chs-output della directory corrente:

      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'
      
    • Istanze TPU autonome: su un'istanza TPU che esegue Container-Optimized OS, l'immagine container è l'unica opzione di installazione supportata. L'alias concede al container l'accesso ai dispositivi TPU e allo spazio dei nomi PID host dell'istanza, monta il file system root dell'host in /host e monta le tue credenziali Google Cloud in modalità di sola lettura. L'alias memorizza anche lo stato delle tue esecuzioni nel volume Docker chs-local-state e scrive i file di output nella directory chs-output della directory corrente:

      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'
      

(Facoltativo) Configura un bucket Cloud Storage per i report

Per impostazione predefinita, lo scanner di integrità del cluster salva i report e i log di diagnostica in una directory di output locale. Puoi configurare un bucket Cloud Storage per archiviarli anche da remoto.

  1. Se non hai ancora un bucket per i report di controllo di integrità, creane uno:

    gcloud storage buckets create gs://BUCKET_NAME \
        --location=BUCKET_LOCATION \
        --project=PROJECT_ID
    
  2. Concedi il ruolo Storage Object Admin (roles/storage.objectAdmin) al tuo account utente o account di servizio principale:

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

    Il membro PRINCIPAL è l'entità che scrive il report. Ad esempio, user:EMAIL o serviceAccount:SERVICE_ACCOUNT_EMAIL.

  3. Imposta il bucket in cui lo scanner di integrità del cluster archivia i report. Il bucket deve già esistere perché lo scanner di integrità del cluster non lo crea automaticamente. Devi eseguire questo comando una sola volta per ogni ambiente:

    chs configure storage gcs BUCKET_NAME
    

    Per archiviare i report con un prefisso di cartella nel bucket, aggiungi il prefisso al nome del bucket:

    chs configure storage gcs BUCKET_NAME/PREFIX
    

Esegui un'analisi dello stato

Questa sezione descrive come verificare che i nodi siano inattivi, avviare una scansione e monitorarne l'avanzamento.

Verifica che i nodi di destinazione siano inattivi

Lo scanner di integrità del cluster viene eseguito solo sulla capacità inattiva e non arresta o rimuove automaticamente i workload. Prima di avviare una scansione, svuota o arresta tutti i workload in esecuzione sui nodi o sull'istanza di destinazione.

Se lo scanner di integrità del cluster rileva workload attivi su un nodo o un'istanza di destinazione, gestisce la capacità come segue:

  • GPU: lo scanner di integrità del cluster salta i nodi occupati ed esegue l'analisi sui nodi inattivi rimanenti.
  • TPU: il modo in cui lo scanner di integrità del cluster gestisce la capacità occupata dipende dall'ambiente:
    • Cluster GKE: i test TPU multi-host (tpu-collectives e tpu-network-stress) richiedono una sezione inattiva completa, mentre i test TPU single-host possono essere eseguiti su singoli nodi inattivi:
      • Pool di nodi di suddivisione statica (--nodepools o --nodes): se alcuni nodi di un pool sono occupati quando esegui la suite lite o standard, lo scanner di integrità del cluster registra un avviso, omette i test multi-host ed esegue i test TPU su host singolo sui nodi inattivi rimanenti.
      • Node pool di slicing dinamico (--nodepools o --nodes): il targeting di un pool con --nodepools richiede che l'intero pool di nodi sia inattivo, in modo che lo scanner di integrità del cluster possa eseguire il provisioning di una risorsa Slice per l'intero pool. Se scegli come target nodi specifici con --nodes (su GKE versione 1.36.0-gke.3712000 o successive), lo scanner di integrità del cluster esegue il provisioning di una singola sezione secondaria 2x2x1 per ogni nodo inattivo, salta i nodi occupati ed esegue test TPU su host singolo sui nodi inattivi.
    • Istanze TPU autonome: lo scanner di integrità del cluster non può essere eseguito se un altro processo utilizza i dispositivi TPU in /dev/vfio.

Per assicurarti che la capacità target sia inattiva, segui i passaggi per il tuo ambiente.

Cluster GKE

  1. Interrompi o elimina eventuali job o pod dei workload attivi nel pool di nodi di destinazione oppure attendi il completamento dei workload in esecuzione.

    Se utilizzi kubectl drain per rimuovere i workload dal pool di nodi, annulla il blocco dei nodi prima di avviare l'analisi, in modo che lo scanner di integrità del cluster possa pianificare i pod di diagnostica sui nodi (lo scanner di integrità del cluster ignora i nodi bloccati):

    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
    

    Assicurati che non vengano pianificati nuovi workload nel pool di nodi durante l'esecuzione della scansione.

  2. Verifica che non rimangano pod di workload nel pool di nodi:

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

    I pod di sistema, come quelli gestiti dai DaemonSet nello spazio dei nomi kube-system, possono continuare a essere eseguiti.

Cluster Slurm

  1. Controlla se sono presenti job in esecuzione nella partizione di destinazione:

    squeue --partition=PARTITION_NAME
    

    Se sono in esecuzione job nella partizione, attendi che vengano completati o annullali con scancel JOB_ID.

  2. Verifica che i nodi nella partizione di destinazione siano nello stato idle:

    sinfo --partition=PARTITION_NAME
    

Istanze TPU autonome

Verifica che nessun altro processo stia utilizzando i dispositivi TPU nell'istanza:

sudo fuser -v /dev/vfio/*

Se sono elencati dei processi, attendi il completamento dei workload o interrompi i processi prima di avviare una scansione.

Avvia una scansione

I flag che passi al comando chs run dipendono dall'ambiente in cui esegui lo scanner di integrità del cluster. Lo scanner di integrità del cluster rileva automaticamente lo scheduler e il tipo di acceleratore, quindi non è necessario specificarli.

Per elencare le suite e i test di diagnostica disponibili per un tipo di acceleratore, esegui i seguenti comandi:

  • Per le GPU:

    chs list suites --gpu
    chs list tests --gpu
    
  • Per le TPU:

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

Node pool GKE

Esegui lo scanner di integrità del cluster da qualsiasi macchina che abbia accesso kubectl al tuo cluster, ad esempio la tua macchina locale o Cloud Shell.

Per avviare un'analisi su uno o più node pool, esegui questo comando:

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

Sostituisci quanto segue:

  • NODE_POOL_NAMES: un elenco separato da virgole dei node pool GPU o TPU da analizzare. Ad esempio: a4-pool-1,a4-pool-2 o tpu7x-pool-1,tpu7x-pool-2. Tutti i node pool di destinazione devono utilizzare lo stesso tipo di macchina.
  • SUITE: la suite di diagnostica da eseguire, lite o standard. Per saperne di più su ogni suite, consulta Suite di diagnostica.

Per eseguire test specifici anziché una suite completa, sostituisci il flag --suite con il flag --tests e specifica un elenco separato da virgole di nomi di test:

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

Per analizzare nodi specifici anziché un intero pool di nodi, sostituisci il flag --nodepools con il flag --nodes e specifica un elenco separato da virgole di nomi di nodi.

Quando specifichi più pool di nodi nel flag --nodepools, lo scanner di integrità del cluster li gestisce in base al tipo di acceleratore:

  • Node pool GPU: combina tutti i nodi GPU inattivi nei node pool specificati in un unico set di destinazione ed esegue test multi-nodo (nccl-cluster e nccl-pairwise) su tutti i nodi contemporaneamente.
  • Pool di nodi TPU: valuta ogni pool di nodi (sezione TPU) in modo indipendente e in parallelo all'interno di una singola esecuzione, senza test tra sezioni (multisezione).

Partizioni Slurm

Esegui lo scanner di integrità del cluster sul controller Slurm o sul nodo di accesso, dove sono disponibili i comandi sinfo e sbatch. Slurm richiede l'opzione di installazione del pacchetto Python. Per le istruzioni di installazione, consulta Pacchetto Python.

Prima di avviare una scansione, configura le credenziali Enroot sul cluster in modo che i nodi possano eseguire il pull delle immagini di benchmark da 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

Avvia una scansione su una o più partizioni:

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

Sostituisci quanto segue:

  • PARTITION_NAMES: un elenco separato da virgole delle partizioni Slurm da analizzare.
  • SUITE: la suite di diagnostica da eseguire, lite o standard. Per saperne di più su ogni suite, consulta Suite di diagnostica.

Per eseguire test GPU specifici anziché una suite completa, sostituisci il flag --suite con il flag --tests e specifica un elenco di nomi di test separati da virgole (ad esempio, nccl-pairwise,gemm o nccl-domain):

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

Istanze TPU autonome

Esegui lo scanner di integrità del cluster direttamente sull'istanza TPU. L'istanza TPU deve esporre i propri dispositivi TPU in /dev/vfio (puoi verificarlo sull'istanza eseguendo ls /dev/vfio).

Se non esegui lo scanner di integrità del cluster come utente root, aumenta il limite di memlock prima di eseguire i test TPU:

ulimit -l unlimited

Per avviare una scansione sull'istanza TPU, esegui questo comando:

chs run --suite=SUITE

Sostituisci SUITE con la suite di diagnostica da eseguire, lite o standard. Per saperne di più su ciascuna suite, consulta Suite di diagnostica.

Per eseguire test TPU specifici anziché una suite completa, sostituisci il flag --suite con il flag --tests e specifica un elenco separato da virgole di nomi di test (ad esempio, tpu-host-device,tpu-hbm-stress):

chs run --tests=TEST_NAMES

Visualizza esecuzioni e risultati

Lo scanner di integrità del cluster archivia la cronologia delle esecuzioni e le impostazioni di configurazione localmente sulla macchina client su cui esegui i comandi chs (in ~/.local/share/chs/ o nel volume Docker chs-local-state quando utilizzi l'immagine container). Di conseguenza, i comandi chs history e chs results elencano solo le esecuzioni avviate da quell'ambiente.

Per elencare le esecuzioni precedenti e i relativi ID, esegui questo comando:

chs history

Per visualizzare i risultati di un'esecuzione e le posizioni del report HTML interattivo (bill_of_health.html) e del report JSON (bill_of_health.json), esegui questo comando:

chs results RUN_ID

Se ometti RUN_ID, lo scanner di integrità del cluster ti chiede di selezionare un'esecuzione. Il comando stampa i percorsi locali o gli URI Cloud Storage se hai configurato un bucket. Legge i risultati archiviati di un'esecuzione precedente e non avvia nuovi job sul cluster o sull'istanza.

Annulla una scansione

Per annullare un'analisi, interrompere i relativi job e rimuovere le risorse create sul cluster o sull'istanza, esegui uno dei seguenti comandi:

  • Annulla l'esecuzione più recente:

    chs cancel
    
  • Annulla un'esecuzione specifica:

    chs cancel RUN_ID
    
  • Annulla ogni esecuzione dello scanner di integrità del cluster sul cluster o sull'istanza, incluse le esecuzioni avviate da altri utenti:

    chs cancel --all
    

Interpretazione dei risultati

Al termine di una scansione, lo scanner di integrità del cluster salva i seguenti artefatti nella directory di output locale e li carica nel bucket Cloud Storage se hai configurato lo spazio di archiviazione:

  • Report HTML interattivo (bill_of_health.html): mostra ogni test, le relative metriche misurate e lo stato.
  • Report JSON (bill_of_health.json): contiene gli sweep dei parametri e le metriche misurate per ogni test.
  • Directory di Workspace: contiene i log diagnostici.

Visualizza il report sull'integrità

Per trovare i percorsi locali o gli URI Cloud Storage esatti (gs://BUCKET/PREFIX/bills_of_health/RUN_ID.html e gs://BUCKET/PREFIX/bills_of_health/RUN_ID.json) per i report di un'analisi, esegui questo comando:

chs results RUN_ID

Se hai configurato un bucket Cloud Storage, puoi visualizzare il report JSON direttamente dall'URI restituito da chs results:

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

Contenuti del report

Il report sull'integrità elenca tutti i nodi testati dallo scanner di integrità del cluster, insieme ai risultati del benchmark per ciascun nodo. Le scansioni di GPU e TPU utilizzano lo stesso formato di report. Ogni nodo riceve uno dei seguenti stati:

Stato Descrizione
HEALTHY Tutti i test hanno soddisfatto le prestazioni previste per il tipo di macchina.
DEGRADED Il nodo ha completato i test, ma uno o più risultati erano inferiori alle prestazioni previste.
POTENTIALLY DEGRADED Un test di screening ha mostrato un rendimento inferiore al previsto e il relativo stress test non è stato eseguito per confermare il risultato.
INCOMPLETE Uno o più test non sono stati eseguiti, sono scaduti, sono stati annullati o non hanno generato metriche del report sul nodo.

Il file bill_of_health.json contiene i seguenti campi di primo livello:

  • report_id: l'identificatore univoco dell'esecuzione della scansione.
  • chs_version: la versione dello scanner di integrità del cluster che ha generato il report.
  • created_at: il timestamp relativo alla data e all'ora di generazione del report.
  • system_info: metadati relativi al sistema in fase di test, ad esempio il tipo di cluster e il tipo di macchina.
  • test_results: un elenco di oggetti dei risultati del test. Ogni voce include i seguenti campi:
    • test_name: il nome del test diagnostico.
    • result_status: il risultato del test, ad esempio RESULT_STATUS_SUCCESS o RESULT_STATUS_FAILED.
    • target_resources: i nodi (node_name e instance_id) su cui è stato eseguito il test.
    • metrics: le metriche misurate e i criteri di convalida per il test.

Il report sull'integrità utilizza un formato JSON strutturato e coerente. Puoi caricare i report in BigQuery o in altri strumenti di analisi e confrontare i report di scansioni successive della stessa capacità per rilevare una graduale deviazione delle prestazioni.

Correggi i nodi non integri

Se il report sull'integrità identifica un nodo o un'istanza con uno stato DEGRADED, POTENTIALLY DEGRADED o INCOMPLETE, segui questi passaggi:

  1. Per escludere un problema temporaneo, esegui nuovamente l'analisi sul pool di nodi o sul nodo GKE, sulla partizione Slurm o sull'istanza TPU autonoma prima di isolare o svuotare il nodo (lo scanner di integrità del cluster ignora i nodi GKE isolati e i nodi Slurm svuotati). Per istruzioni, vedi Avvia una scansione.

  2. Se il problema persiste, impedisci la pianificazione di nuovi workload sul nodo o sull'istanza interessati:

    • Cluster GKE: contrassegna il nodo non integro come non pianificabile:

      kubectl cordon NODE_NAME
      
    • Cluster Slurm: svuota il nodo non integro:

      sudo scontrol update NodeName=NODE_NAME State=DRAIN Reason="CHS unhealthy"
      
    • Istanze TPU autonome: non avviare nuovi workload sull'istanza TPU finché non hai terminato di risolvere il problema.

  3. Ripara o sostituisci il nodo o l'istanza utilizzando una delle seguenti opzioni, a seconda del tipo di acceleratore e dell'ambiente:

    Quando contatti l'assistenza, allega la directory dell'area di lavoro dalla directory di output locale o dal bucket Cloud Storage, che contiene i log di diagnostica, e includi l'ID esecuzione.

  4. Dopo aver riparato o sostituito il nodo o l'istanza, rendilo nuovamente pianificabile in modo che lo scanner di integrità del cluster non lo ignori, quindi esegui una nuova scansione per verificare che la capacità sia integra:

    • Cluster GKE: annulla il cordon del nodo, quindi esegui nuovamente la scansione prima di pianificare nuovi workload:

      kubectl uncordon NODE_NAME
      
    • Cluster Slurm: riprendi il nodo in modo che torni allo stato idle, quindi esegui nuovamente la scansione prima di pianificare nuovi job:

      sudo scontrol update NodeName=NODE_NAME State=RESUME
      
    • Istanze TPU autonome: esegui nuovamente l'analisi sull'istanza, quindi riprendi l'esecuzione dei workload una volta che l'analisi conferma che l'istanza è integra.

Telemetria

Lo scanner di integrità del cluster invia metriche di utilizzo anonime a Google per contribuire a migliorare lo strumento e non raccoglie informazioni che consentono l'identificazione personale (PII). La telemetria è abilitata per impostazione predefinita. Per disattivare questa funzionalità, esegui chs configure telemetry disable o imposta la variabile di ambiente CHS_TELEMETRY=0.

Passaggi successivi

Per risolvere i problemi comuni relativi allo scanner di integrità del cluster, consulta Risolvi i problemi relativi allo scanner di integrità del cluster.