Exécuter des analyses d'état sur les GPU et les TPU

L'outil d'analyse de l'état du cluster est un outil de diagnostic en libre-service qui valide l'aptitude de votre capacité de GPU et de Cloud TPU avant de planifier une charge de travail. L'outil d'analyse de l'état du cluster exécute des benchmarks qui simulent le trafic réel de la charge de travail sur vos nœuds d'accélérateur afin de mesurer les performances des accélérateurs, de leur mémoire et des interconnexions entre eux. Vous pouvez utiliser les résultats pour identifier et supprimer les nœuds défectueux avant qu'ils n'entraînent l'arrêt, le ralentissement ou l'échec de vos jobs d'entraînement ou d'inférence.

Pour les TPU, l'outil d'analyse de l'état du cluster complète la surveillance de l'état des TPU, qui signale en continu l'état du matériel. L'outil d'analyse de l'état du cluster exécute activement des charges de travail sur la capacité inactive pour mesurer les performances et exposer les défaillances qui n'apparaissent que sous charge.

Le scanner d'état du cluster est entièrement Open Source. Pour afficher le code source, contribuer ou signaler des problèmes, consultez le dépôt GitHub de l'outil d'analyse de l'état du cluster.

Ce document explique comment installer l'outil d'analyse de l'état des clusters, exécuter une analyse de l'état sur les réservations de GPU et de TPU, interpréter les résultats et corriger les nœuds non opérationnels.

Environnements compatibles

L'outil d'analyse de l'état du cluster est compatible avec les environnements de déploiement suivants :

Environnement Accélérateurs compatibles Environnement client Options d'installation
Clusters Google Kubernetes Engine (GKE) GPU et TPU (pools de nœuds utilisant le slicing statique ou dynamique) Une machine Linux disposant d'un accès kubectl au cluster cible Package Python ou image de conteneur
Clusters Slurm GPU uniquement Le contrôleur Slurm ou le nœud de connexion, où les commandes sinfo et sbatch sont disponibles Package Python uniquement
Instances TPU autonomes TPU uniquement L'instance TPU elle-même Package Python ou image de conteneur (Container-Optimized OS)

L'outil d'analyse de l'état du cluster est compatible avec les types de machines GPU et TPU suivants :

  • Types de machines avec GPU :
    • A5X : a5x-highgpu-4g-metal (GKE uniquement)
    • A4X Max : a4x-maxgpu-4g-metal
    • A4X : a4x-highgpu-4g
    • A4 : a4-highgpu-8g
    • A3 Ultra : a3-ultragpu-8g
    • A3 Mega : a3-megagpu-8g
  • Types de machines TPU :

Suites de diagnostics

Vous pouvez installer l'outil d'analyse de l'état du cluster en tant que package Python ou image de conteneur. Les deux options fournissent l'interface de ligne de commande (CLI) chs et les benchmarks de diagnostic. Vous exécutez la CLI à partir d'une machine ayant accès à votre cluster GKE, sur un contrôleur Slurm ou un nœud de connexion, ou directement sur une instance TPU autonome. La CLI exécute ensuite les tests de diagnostic sur les nœuds GPU ou TPU cibles.

L'outil d'analyse de l'état du cluster fournit deux suites de diagnostic pour chaque type d'accélérateur :

  • Lite : exécute une vérification rapide. Sur les GPU et les instances de TPU autonomes, la suite Lite vérifie les hôtes individuels. Sur les pools de nœuds TPU GKE, il exécute également une vérification collective rapide (tpu-collectives) sur la tranche TPU. Une opération collective est un modèle de communication dans lequel tous les accélérateurs échangent des données, comme AllReduce, qui combine les valeurs de chaque accélérateur et partage le résultat avec tous les accélérateurs. Utilisez la suite Lite pour effectuer des vérifications d'état rapides ou avant d'exécuter des charges de travail sur un seul hôte.
  • Standard : exécute une validation complète sur votre capacité cible. Sur les GPU, la suite Standard exécute des opérations collectives sur plusieurs nœuds et mesure la bande passante de la mémoire GPU. Sur les TPU, il exécute tous les tests Lite, ainsi que des tests de contrainte prolongés sur le calcul, la mémoire et le réseau. Utilisez la suite Standard avant d'exécuter des charges de travail d'entraînement ou d'inférence multihôtes, où les performances et la stabilité du réseau sous une charge soutenue affectent directement les performances des jobs.
Suite Accélérateur Tests Objectif
lite GPU nvidia-smi, dcgm, gemm, nccl-single-node Validation rapide de l'état du GPU et du pilote, du débit de calcul et de la communication GPU intra-nœud.
TPU tpu-info, tpu-gemm, tpu-hbm, tpu-host-device et tpu-collectives Validation rapide de l'état de l'appareil, du débit de calcul, de la bande passante de la mémoire à haut débit (HBM), de la bande passante hôte-appareil et de la bande passante collective de l'interconnexion entre puces (ICI).
standard GPU nvidia-smi, dcgm, gemm, nccl-cluster, nccl-pairwise, stream Validation du réseau multinœud sur les nœuds cibles, plus bande passante de la mémoire.
TPU Tous les tests TPU lite, plus tpu-compute-stress, tpu-hbm-stress et tpu-network-stress Tests de contrainte prolongés qui révèlent l'instabilité, la corruption silencieuse des données et les erreurs de bits ICI.

Le test GPU nccl-domain ne fait pas partie d'une suite. Pour exécuter nccl-domain, utilisez l'option --tests.

Suites et tests de GPU

L'outil d'analyse de l'état du cluster fournit les suites suivantes pour les nœuds GPU :

  • Lite : valide le pilote et le matériel du GPU, mesure le débit de calcul et exécute un test de la bibliothèque NVIDIA Collective Communications Library (NCCL) dans chaque nœud.
  • Standard : exécute les collectifs NCCL sur tous les nœuds cibles et entre des paires de nœuds pour mesurer les performances du réseau inter-nœuds, et mesure la bande passante de la mémoire.

Le tableau suivant décrit chaque test de GPU :

Test Description Suites
nccl-single-node Exécute des tests collectifs NCCL entre les GPU d'un même nœud. lite
nvidia-smi Vérifie l'état de base du GPU et du pilote GPU à l'aide de l'interface de gestion du système NVIDIA. lite, standard
dcgm Exécute les diagnostics du gestionnaire de GPU du centre de données (DCGM) NVIDIA pour effectuer des vérifications matérielles approfondies sur chaque GPU. lite, standard
gemm Exécute des multiplications matricielles générales (GEMM) pour mesurer le débit de calcul du GPU. lite, standard
nccl-cluster Exécute des tests collectifs NCCL sur tous les nœuds cibles pour mesurer la bande passante réseau à l'échelle du cluster. standard
nccl-pairwise Exécute de tests NCCL entre des paires de nœuds pour mesurer la latence de nœud à nœud et isoler les nœuds ou les liens défectueux. standard
stream Exécute le benchmark STREAM pour mesurer la bande passante de la mémoire GPU. standard
nccl-domain Exécute des tests collectifs NCCL dans chaque domaine NVLink multinœud. Compatible uniquement avec les types de machines dotés de domaines NVLink multinœuds. Aucune (exécuter avec --tests)

Suites et tests TPU

L'outil d'analyse de l'état du cluster fournit les suites suivantes pour les nœuds TPU :

  • Lite : valide les performances des puces TPU et de la mémoire HBM sur chaque hôte, mesure la bande passante hôte-appareil et exécute un test d'opérations collectives pour mesurer la bande passante ICI.
  • Standard : exécute des opérations collectives sur les puces TPU d'une tranche, ainsi que des tests de résistance prolongés sur les puces TPU, la HBM et les liaisons ICI.

Le tableau suivant décrit chaque test TPU :

Test Description Suites
tpu-info Vérifie l'état de base du TPU, y compris le nombre d'appareils, la version de LibTPU et le type d'appareil TPU. lite, standard
tpu-gemm Exécute des multiplications matricielles générales (GEMM) pour mesurer le pic de TFLOPS soutenu. lite, standard
tpu-hbm Mesure la bande passante de lecture et d'écriture HBM. lite, standard
tpu-collectives Chronomètre les opérations collectives, telles que AllReduce et AllGather, pour mesurer la bande passante ICI (clusters GKE uniquement). lite, standard
tpu-host-device Mesure la bande passante hôte à appareil. lite, standard
tpu-compute-stress Exécute des multiplications matricielles continues pour vérifier la stabilité des calculs et détecter la corruption silencieuse des données. standard
tpu-hbm-stress Il sollicite la mémoire HBM pour mesurer la bande passante maximale et valider l'intégrité des données. standard
tpu-network-stress Envoie des charges utiles aléatoires volumineuses via des liaisons ICI pour mesurer la bande passante soutenue et détecter les erreurs de bits (clusters GKE uniquement). standard

Avant de commencer

Avant d'utiliser l'outil d'analyse de l'état du cluster, installez les outils requis, configurez les autorisations et connectez-vous à votre cluster ou à votre instance.

Installations

Avant d'exécuter une analyse d'état, effectuez les installations pour votre environnement de déploiement.

Clusters GKE

Pour exécuter des analyses d'état sur un cluster GKE, assurez-vous de disposer d'un cluster cible et d'installer les outils requis sur la machine sur laquelle vous prévoyez d'exécuter les analyses :

Clusters Slurm

Pour exécuter des analyses d'état sur un cluster Slurm, assurez-vous de disposer d'un cluster GPU cible et d'installer les outils requis sur le contrôleur Slurm ou le nœud de connexion, où les commandes sinfo et sbatch sont disponibles :

Pour les clusters Slurm, utilisez l'option d'installation du package Python. Slurm n'est pas compatible avec l'option d'image de conteneur.

Instances TPU autonomes

Pour exécuter des analyses d'état sur une instance TPU autonome, assurez-vous de disposer d'une instance TPU cible et installez les outils requis directement sur l'instance :

Rôles requis

Pour obtenir les autorisations nécessaires pour exécuter une analyse d'état, demandez à votre administrateur de vous accorder le rôle roles/compute.viewer sur votre projet. Ce rôle permet au scanner d'état du cluster de lire les métadonnées Compute Engine et les informations de topologie de vos nœuds.

Vous avez également besoin des rôles IAM (Identity and Access Management) suivants, en fonction de votre environnement de déploiement :

Environnement Rôles requis
Clusters GKE Développeur sur Kubernetes Engine (roles/container.developer)
Clusters Slurm
  • Connexion au système d'exploitation Compute (roles/compute.osLogin) ou Connexion administrateur au système d'exploitation Compute (roles/compute.osAdminLogin)
  • Utilisateur de tunnels sécurisés par IAP (roles/iap.tunnelResourceAccessor), si vous vous connectez via Identity-Aware Proxy (IAP)
Instances TPU autonomes
  • Administrateur TPU (roles/tpu.admin)
  • Utilisateur de tunnels sécurisés par IAP (roles/iap.tunnelResourceAccessor), si la connexion s'effectue via IAP

Si vous configurez un bucket Cloud Storage pour les rapports, vous devez également disposer du rôle "Administrateur des objets de l'espace de stockage" (roles/storage.objectAdmin) sur le bucket. Ce rôle permet au scanner d'état du cluster d'importer des artefacts de résultat, tels que le rapport d'état, dans le bucket.

Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.

Se connecter à votre cluster ou à votre instance

Connectez-vous à l'environnement dans lequel vous prévoyez d'exécuter des analyses d'état.

Clusters GKE

Configurez les Identifiants par défaut de l'application (ADC) et configurez kubectl pour communiquer avec votre cluster GKE :

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

Clusters Slurm

Connectez-vous à votre contrôleur Slurm ou à votre nœud de connexion à l'aide de SSH :

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

Instances TPU autonomes

Connectez-vous à votre instance TPU autonome à l'aide de SSH :

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

Installer l'outil d'analyse de l'état du cluster

Installez l'outil d'analyse de l'état du cluster sur la machine sur laquelle vous exécutez les analyses, qui dépend de votre environnement :

  • Clusters GKE : toute machine disposant d'un accès kubectl à votre cluster.
  • Clusters Slurm : contrôleur ou nœud de connexion Slurm.
  • Instances TPU autonomes : l'instance TPU elle-même.

Sur les clusters GKE et Slurm, l'outil d'analyse de l'état du cluster extrait automatiquement les images de conteneur de diagnostic qui correspondent à vos nœuds GPU ou TPU, et les planifie sur le cluster. Vous n'avez donc pas besoin d'installer de logiciel sur les nœuds de calcul individuels. Sur une instance TPU autonome, vous installez et exécutez l'outil d'analyse de l'état du cluster directement sur l'instance.

Vous pouvez installer l'outil d'analyse de l'état du cluster en tant que package Python ou image de conteneur. Les commandes chs du reste de ce document fonctionnent avec l'une ou l'autre des options d'installation. Pour afficher des informations détaillées sur l'utilisation d'une commande, ajoutez l'option --help.

Package Python

Créez un environnement virtuel Python et installez le package de l'outil d'analyse de l'état du cluster à partir de GitHub. Sur les clusters GKE et Slurm, utilisez Python 3.12 ou une version ultérieure. Sur les instances TPU autonomes (x86_64), vous devez utiliser Python 3.12 (avec Python 3.13 ou version ultérieure, pip install n'installe pas les dépendances de benchmark TPU et chs run ignore l'instance) :

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

Pour installer une version spécifique, ajoutez @VERSION à l'URL du dépôt :

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

Pour obtenir la liste des versions, consultez Versions de l'outil d'analyse de l'état des clusters sur GitHub.

Image de conteneur

L'outil d'analyse de l'état du cluster est distribué sous forme d'image de conteneur dans Artifact Registry. L'image est compatible avec les GPU et les TPU. Vous pouvez utiliser l'image de conteneur pour les clusters GKE et les instances TPU autonomes, mais pas pour les clusters Slurm.

  1. Configurez Docker pour qu'il s'authentifie auprès d'Artifact Registry et extrayez l'image de conteneur de l'outil d'analyse de l'état du cluster :

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

    Pour extraire une version spécifique au lieu de latest, remplacez latest par le numéro de version. Par exemple, 0.3.0 pour la version GitHub v0.3.0. Pour obtenir la liste des versions, consultez Versions de l'outil d'analyse de l'état du cluster sur GitHub.

  2. Créez un alias de shell pour exécuter directement les commandes chs. L'alias que vous créez dépend de votre environnement :

    • Clusters GKE : l'alias installe votre fichier kubeconfig et vos identifiants Google Cloud en mode lecture seule. L'alias stocke également l'état de vos exécutions dans le volume Docker chs-local-state et écrit les fichiers de sortie dans le répertoire chs-output de votre répertoire actuel :

      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'
      
    • Instances TPU autonomes : sur une instance TPU qui exécute Container-Optimized OS, l'image de conteneur est la seule option d'installation compatible. L'alias accorde au conteneur l'accès aux appareils TPU et à l'espace de noms PID de l'hôte de l'instance, installe le système de fichiers racine de l'hôte sur /host et installe vos identifiants Google Clouden mode lecture seule. L'alias stocke également l'état de vos exécutions dans le volume Docker chs-local-state et écrit les fichiers de sortie dans le répertoire chs-output de votre répertoire actuel :

      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'
      

Facultatif : Configurer un bucket Cloud Storage pour les rapports

Par défaut, l'outil d'analyse de l'état du cluster enregistre les rapports et les journaux de diagnostic dans un répertoire de sortie local. Vous pouvez configurer un bucket Cloud Storage pour les stocker également à distance.

  1. Si vous ne disposez pas encore d'un bucket pour les rapports d'analyse d'état, créez-en un :

    gcloud storage buckets create gs://BUCKET_NAME \
        --location=BUCKET_LOCATION \
        --project=PROJECT_ID
    
  2. Attribuez le rôle Administrateur des objets de l'espace de stockage (roles/storage.objectAdmin) à votre compte utilisateur ou de service principal :

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

    Le membre PRINCIPAL est le compte principal qui écrit le rapport. Par exemple, user:EMAIL ou serviceAccount:SERVICE_ACCOUNT_EMAIL.

  3. Définissez le bucket dans lequel l'analyseur d'état du cluster stocke les rapports. Le bucket doit déjà exister, car l'outil d'analyse de l'état du cluster ne le crée pas automatiquement. Vous n'avez besoin d'exécuter cette commande qu'une seule fois pour chaque environnement :

    chs configure storage gcs BUCKET_NAME
    

    Pour stocker les rapports sous un préfixe de dossier dans le bucket, ajoutez le préfixe au nom du bucket :

    chs configure storage gcs BUCKET_NAME/PREFIX
    

Exécuter une analyse de l'état

Cette section explique comment vérifier que vos nœuds sont inactifs, lancer une analyse et surveiller sa progression.

Vérifier que les nœuds cibles sont inactifs

L'outil d'analyse de l'état du cluster ne s'exécute que sur la capacité inactive et n'arrête ni n'expulse automatiquement vos charges de travail. Avant de lancer une analyse, drainez ou arrêtez toutes les charges de travail qui s'exécutent sur vos nœuds ou votre instance cibles.

Si l'outil d'analyse de l'état du cluster détecte des charges de travail actives sur un nœud ou une instance cible, il gère la capacité comme suit :

  • GPU : l'outil d'analyse de l'état du cluster ignore les nœuds occupés et exécute l'analyse sur les nœuds inactifs restants.
  • TPU : la façon dont l'outil d'analyse de l'état du cluster gère la capacité occupée dépend de l'environnement :
    • Clusters GKE : les tests TPU multi-hôtes (tpu-collectives et tpu-network-stress) nécessitent une tranche inactive complète, tandis que les tests TPU à hôte unique peuvent s'exécuter sur des nœuds inactifs individuels :
      • Pools de nœuds à découpage statique (--nodepools ou --nodes) : si certains nœuds d'un pool sont occupés lorsque vous exécutez la suite lite ou standard, l'outil d'analyse de l'état du cluster consigne un avertissement, omet les tests multi-hôtes et exécute les tests TPU à hôte unique sur les nœuds inactifs restants.
      • Pools de nœuds de slicing dynamique (--nodepools ou --nodes) : le ciblage d'un pool avec --nodepools nécessite que l'ensemble du pool de nœuds soit inactif afin que l'outil d'analyse de l'état du cluster puisse provisionner une ressource Slice pour l'ensemble du pool. Si vous ciblez des nœuds spécifiques avec --nodes (sur GKE version 1.36.0-gke.3712000 ou ultérieure), l'outil d'analyse de l'état du cluster provisionne une sous-tranche 2x2x1 individuelle pour chaque nœud inactif, ignore les nœuds occupés et exécute des tests TPU à hôte unique sur les nœuds inactifs.
    • Instances TPU autonomes : l'outil d'analyse de l'état du cluster ne peut pas s'exécuter si un autre processus utilise les appareils TPU sous /dev/vfio.

Pour vous assurer que votre capacité cible est inactive, suivez les étapes correspondant à votre environnement.

Clusters GKE

  1. Arrêtez ou supprimez les jobs ou pods de charge de travail actifs sur le pool de nœuds cible, ou attendez que les charges de travail en cours d'exécution se terminent.

    Si vous utilisez kubectl drain pour exclure des charges de travail du pool de nœuds, annulez le cordon des nœuds avant de lancer l'analyse afin que l'outil d'analyse de l'état du cluster puisse planifier des pods de diagnostic sur ces nœuds (l'outil d'analyse de l'état du cluster ignore les nœuds cordonnés) :

    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
    

    Assurez-vous qu'aucune nouvelle charge de travail n'est planifiée sur le pool de nœuds pendant l'exécution de l'analyse.

  2. Vérifiez qu'il ne reste aucun pod de charge de travail dans le pool de nœuds :

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

    Les pods système, tels que ceux gérés par les DaemonSets dans l'espace de noms kube-system, peuvent continuer à s'exécuter.

Clusters Slurm

  1. Vérifiez si des jobs sont en cours d'exécution dans la partition cible :

    squeue --partition=PARTITION_NAME
    

    Si des jobs sont en cours d'exécution dans la partition, attendez qu'ils se terminent ou annulez-les avec scancel JOB_ID.

  2. Vérifiez que les nœuds de la partition cible sont à l'état idle :

    sinfo --partition=PARTITION_NAME
    

Instances TPU autonomes

Vérifiez qu'aucun autre processus n'utilise les appareils TPU sur l'instance :

sudo fuser -v /dev/vfio/*

Si des processus sont listés, attendez que les charges de travail se terminent ou arrêtez les processus avant de lancer une analyse.

Lancer une analyse

Les options que vous transmettez à la commande chs run dépendent de l'environnement dans lequel vous exécutez l'outil d'analyse de l'état du cluster. L'outil d'analyse de l'état du cluster détecte automatiquement le programmeur et le type d'accélérateur. Vous n'avez donc pas besoin de les spécifier.

Pour lister les suites de diagnostic et les tests disponibles pour un type d'accélérateur, exécutez les commandes suivantes :

  • Pour les GPU :

    chs list suites --gpu
    chs list tests --gpu
    
  • Pour les TPU :

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

Pools de nœuds GKE

Exécutez l'outil d'analyse de l'état du cluster à partir de n'importe quelle machine ayant un accès kubectl à votre cluster, par exemple votre machine locale ou Cloud Shell.

Pour lancer une analyse sur un ou plusieurs pools de nœuds, exécutez la commande suivante :

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

Remplacez les éléments suivants :

  • NODE_POOL_NAMES : liste d'éléments séparés par une virgule des pools de nœuds GPU ou TPU à analyser. Par exemple, a4-pool-1,a4-pool-2 ou tpu7x-pool-1,tpu7x-pool-2. Tous les pools de nœuds cibles doivent utiliser le même type de machine.
  • SUITE : suite de diagnostics à exécuter, soit lite, soit standard. Pour en savoir plus sur chaque suite, consultez Suites de diagnostic.

Pour exécuter des tests spécifiques au lieu d'une suite complète, remplacez l'option --suite par l'option --tests et spécifiez une liste de noms de tests séparés par une virgule :

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

Pour analyser des nœuds spécifiques au lieu d'un pool de nœuds entier, remplacez l'option --nodepools par l'option --nodes et spécifiez une liste de noms de nœuds séparés par une virgule.

Lorsque vous spécifiez plusieurs pools de nœuds dans l'option --nodepools, l'outil d'analyse de l'état du cluster les gère en fonction du type d'accélérateur :

  • Pools de nœuds GPU : combine tous les nœuds GPU inactifs des pools de nœuds spécifiés en un seul ensemble cible et exécute des tests multinœuds (nccl-cluster et nccl-pairwise) sur l'ensemble de ces nœuds.
  • Pools de nœuds TPU : évalue chaque pool de nœuds (tranche TPU) indépendamment et en parallèle au cours d'une même exécution, sans test entre les tranches (Multislice).

Partitions Slurm

Exécutez l'outil d'analyse de l'état du cluster sur le contrôleur Slurm ou le nœud de connexion, où les commandes sinfo et sbatch sont disponibles. Slurm nécessite l'option d'installation du package Python. Pour obtenir des instructions d'installation, consultez Package Python.

Avant de lancer une analyse, configurez les identifiants Enroot sur le cluster afin que les nœuds puissent extraire les images de benchmark 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

Lancez une analyse sur une ou plusieurs partitions :

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

Remplacez les éléments suivants :

  • PARTITION_NAMES : liste des partitions Slurm à analyser, séparées par une virgule.
  • SUITE : suite de diagnostics à exécuter, soit lite, soit standard. Pour en savoir plus sur chaque suite, consultez Suites de diagnostic.

Pour exécuter des tests GPU spécifiques au lieu d'une suite complète, remplacez l'option --suite par l'option --tests et spécifiez une liste de noms de tests séparés par une virgule (par exemple, nccl-pairwise,gemm ou nccl-domain) :

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

Instances TPU autonomes

Exécutez l'outil d'analyse de l'état du cluster directement sur l'instance TPU. L'instance TPU doit exposer ses appareils TPU sous /dev/vfio (vous pouvez le vérifier sur l'instance en exécutant ls /dev/vfio).

Si vous n'exécutez pas l'outil d'analyse de l'état du cluster en tant qu'utilisateur root, augmentez la limite de memlock avant d'exécuter les tests TPU :

ulimit -l unlimited

Pour lancer une analyse sur l'instance de TPU, exécutez la commande suivante :

chs run --suite=SUITE

Remplacez SUITE par la suite de diagnostics à exécuter, soit lite, soit standard. Pour en savoir plus sur chaque suite, consultez Suites de diagnostic.

Pour exécuter des tests TPU spécifiques au lieu d'une suite complète, remplacez l'option --suite par l'option --tests et spécifiez une liste de noms de test séparés par une virgule (par exemple, tpu-host-device,tpu-hbm-stress) :

chs run --tests=TEST_NAMES

Afficher les exécutions et les résultats

L'outil d'analyse de l'état du cluster stocke l'historique d'exécution et les paramètres de configuration localement sur la machine cliente sur laquelle vous exécutez les commandes chs (dans ~/.local/share/chs/ ou dans le volume Docker chs-local-state lorsque vous utilisez l'image de conteneur). Par conséquent, les commandes chs history et chs results ne répertorient que les exécutions démarrées à partir de cet environnement.

Pour lister vos exécutions précédentes et leurs ID d'exécution, exécutez la commande suivante :

chs history

Pour afficher les résultats d'une exécution et les emplacements du rapport HTML interactif (bill_of_health.html) et du rapport JSON (bill_of_health.json), exécutez la commande suivante :

chs results RUN_ID

Si vous omettez RUN_ID, l'outil d'analyse de l'état du cluster vous invite à sélectionner une exécution. La commande affiche les chemins d'accès locaux ou les URI Cloud Storage si vous avez configuré un bucket. Il lit les résultats stockés d'une exécution passée et ne démarre pas de nouveaux jobs sur votre cluster ou votre instance.

Annuler une analyse

Pour annuler une analyse, arrêter ses jobs et supprimer les ressources qu'elle a créées sur votre cluster ou votre instance, exécutez l'une des commandes suivantes :

  • Annulez votre dernière exécution :

    chs cancel
    
  • Annulez une exécution spécifique :

    chs cancel RUN_ID
    
  • Annulez toutes les exécutions de l'analyseur d'état du cluster sur le cluster ou l'instance, y compris celles lancées par d'autres utilisateurs :

    chs cancel --all
    

Interprétation des résultats

Une fois l'analyse terminée, l'outil d'analyse de l'état du cluster enregistre les artefacts suivants dans votre répertoire de sortie local et les importe dans votre bucket Cloud Storage si vous avez configuré le stockage :

  • Rapport HTML interactif (bill_of_health.html) : affiche chaque test, ses métriques mesurées et son état.
  • bill_of_health.json (rapport JSON) : contient les balayages de paramètres et les métriques mesurées pour chaque test.
  • Répertoire Workspace : contient les journaux de diagnostic.

Afficher le rapport d'état

Pour trouver les chemins d'accès locaux exacts ou les URI Cloud Storage (gs://BUCKET/PREFIX/bills_of_health/RUN_ID.html et gs://BUCKET/PREFIX/bills_of_health/RUN_ID.json) des rapports d'une analyse, exécutez la commande suivante :

chs results RUN_ID

Si vous avez configuré un bucket Cloud Storage, vous pouvez afficher le rapport JSON directement à partir de l'URI renvoyé par chs results :

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

Contenu du rapport

Le rapport d'état liste tous les nœuds testés par l'outil d'analyse de l'état du cluster, ainsi que les résultats de l'analyse comparative pour chaque nœud. Les analyses de GPU et de TPU utilisent le même format de rapport. Chaque nœud reçoit l'un des états suivants :

État Description
HEALTHY Tous les tests ont atteint les performances attendues pour le type de machine.
DEGRADED Le nœud a terminé les tests, mais un ou plusieurs résultats étaient inférieurs aux performances attendues.
POTENTIALLY DEGRADED Un test de dépistage n'a pas atteint les performances attendues, et le test de contrainte correspondant n'a pas été exécuté pour confirmer le résultat.
INCOMPLETE Un ou plusieurs tests n'ont pas pu être exécutés, ont expiré, ont été annulés ou n'ont pas généré de métriques sur le nœud.

Le fichier bill_of_health.json contient les champs de premier niveau suivants :

  • report_id : identifiant unique de l'exécution de l'analyse.
  • chs_version : version de l'outil d'analyse de l'état du cluster qui a généré le rapport.
  • created_at : code temporel de la génération du rapport.
  • system_info : métadonnées sur le système testé, telles que le type de cluster et le type de machine.
  • test_results : liste d'objets de résultats de test. Chaque entrée inclut les champs suivants :
    • test_name : nom du test de diagnostic.
    • result_status : résultat du test, par exemple RESULT_STATUS_SUCCESS ou RESULT_STATUS_FAILED.
    • target_resources : nœuds (node_name et instance_id) sur lesquels le test a été exécuté.
    • metrics : métriques mesurées et critères de validation du test.

Le rapport d'état utilise un format JSON structuré et cohérent. Vous pouvez charger des rapports dans BigQuery ou d'autres outils d'analyse, et comparer les rapports d'analyses successives d'une même capacité pour détecter une dérive progressive des performances.

Corriger les nœuds non opérationnels

Si le rapport d'état identifie un nœud ou une instance dont l'état est DEGRADED, POTENTIALLY DEGRADED ou INCOMPLETE, procédez comme suit :

  1. Pour exclure un problème temporaire, réexécutez l'analyse sur le pool de nœuds ou le nœud GKE, la partition Slurm ou l'instance TPU autonome avant de mettre le nœud hors service ou de le drainer (l'outil d'analyse de l'état du cluster ignore les nœuds GKE mis hors service et les nœuds Slurm drainés). Pour obtenir des instructions, consultez Lancer une analyse.

  2. Si le problème persiste, empêchez la planification de nouvelles charges de travail sur le nœud ou l'instance concernés :

    • Clusters GKE : marquez le nœud non opérationnel comme étant non programmable :

      kubectl cordon NODE_NAME
      
    • Clusters Slurm : videz le nœud non opérationnel :

      sudo scontrol update NodeName=NODE_NAME State=DRAIN Reason="CHS unhealthy"
      
    • Instances TPU autonomes : ne démarrez pas de nouvelles charges de travail sur l'instance TPU tant que vous n'avez pas résolu le problème.

  3. Réparez ou remplacez le nœud ou l'instance à l'aide de l'une des options suivantes, en fonction du type d'accélérateur et de l'environnement :

    Lorsque vous contactez l'assistance, joignez le répertoire de l'espace de travail de votre répertoire de sortie local ou de votre bucket Cloud Storage, qui contient les journaux de diagnostic, et incluez l'ID d'exécution.

  4. Une fois le nœud ou l'instance réparé ou remplacé, rendez-le à nouveau planifiable afin que l'outil d'analyse de l'état du cluster ne l'ignore pas, puis exécutez une nouvelle analyse pour confirmer que la capacité est opérationnelle :

    • Clusters GKE : marquez le nœud comme non programmable, puis relancez l'analyse avant de planifier de nouvelles charges de travail :

      kubectl uncordon NODE_NAME
      
    • Clusters Slurm : réactivez le nœud pour qu'il revienne à l'état idle, puis réexécutez l'analyse avant de planifier de nouveaux jobs :

      sudo scontrol update NodeName=NODE_NAME State=RESUME
      
    • Instances TPU autonomes : réexécutez l'analyse sur l'instance, puis reprenez l'exécution de vos charges de travail une fois que l'analyse confirme que l'instance est opérationnelle.

Télémétrie

L'outil d'analyse de l'état du cluster envoie des métriques d'utilisation anonymes à Google pour améliorer l'outil et ne collecte pas d'informations permettant d'identifier personnellement l'utilisateur. La télémétrie est activée par défaut. Pour désactiver cette option, exécutez chs configure telemetry disable ou définissez la variable d'environnement CHS_TELEMETRY=0.

Étapes suivantes

Pour résoudre les problèmes courants liés à l'outil d'analyse de l'état du cluster, consultez Résoudre les problèmes liés à l'outil d'analyse de l'état du cluster.