GPU と TPU でヘルススキャンを実行する

クラスタ ヘルス スキャナは、ワークロードをスケジュールする前に GPU と Cloud TPU の容量の準備状況を検証するセルフサービス診断ツールです。クラスタ ヘルス スキャナは、アクセラレータ ノードで実際のワークロード トラフィックをシミュレートするベンチマークを実行して、アクセラレータ、そのメモリ、それらの間の相互接続のパフォーマンスを測定します。この結果を使用して、トレーニング ジョブや推論ジョブが応答を停止したり、実行速度が低下したり、失敗したりする前に、障害のあるノードを特定して削除できます。

TPU の場合、クラスタ ヘルス スキャナは、ハードウェアの健全性シグナルを継続的に報告する TPU 健全性モニタリングを補完します。クラスタ ヘルス スキャナは、アイドル容量でワークロードをアクティブに実行してパフォーマンスを測定し、負荷がかかった場合にのみ発生する障害を検出します。

クラスタ ヘルス スキャナは完全にオープンソースです。ソースコードの表示、投稿、問題の報告については、クラスタ ヘルス スキャナの GitHub リポジトリをご覧ください。

このドキュメントでは、クラスタ ヘルス スキャナをインストールし、GPU と TPU の予約でヘルススキャンを実行して、結果を解釈し、異常なノードを修復する方法について説明します。

サポートされる環境

クラスタ ヘルス スキャナは、次のデプロイ環境をサポートしています。

環境 サポートされているアクセラレータ クライアント環境 インストール オプション
Google Kubernetes Engine(GKE)クラスタ GPU と TPU(静的スライスまたは動的スライスを使用するノードプール) ターゲット クラスタへの kubectl アクセス権を持つ Linux マシン Python パッケージまたはコンテナ イメージ
Slurm クラスタ GPU のみ sinfo コマンドと sbatch コマンドを使用できる Slurm コントローラまたはログインノード Python パッケージのみ
スタンドアロン TPU インスタンス TPU のみ TPU インスタンス自体 Python パッケージまたはコンテナ イメージ(Container-Optimized OS)

クラスタ ヘルス スキャナは、次の GPU および TPU マシンタイプをサポートしています。

  • GPU マシンタイプ:
    • A5X: a5x-highgpu-4g-metal(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
  • TPU マシンタイプ:

診断スイート

クラスタ ヘルススキャナは、Python パッケージまたはコンテナ イメージとしてインストールできます。どちらのオプションでも、chs コマンドライン インターフェース(CLI)と診断ベンチマークが提供されます。CLI は、GKE クラスタにアクセスできるマシン、Slurm コントローラまたはログインノード、またはスタンドアロン TPU インスタンスで直接実行します。CLI は、ターゲットの GPU ノードまたは TPU ノードで診断テストを実行します。

クラスタ ヘルス スキャナは、アクセラレータ タイプごとに 2 つの診断スイートを提供します。

  • I: Lite: 高速なスクリーニング チェックを実行します。GPU とスタンドアロン TPU インスタンスでは、Lite スイートは個々のホストをチェックします。GKE TPU ノードプールでは、TPU スライス全体でクイック集団チェック(tpu-collectives)も実行されます。集合演算は、すべてのアクセラレータがデータを交換する通信パターンです。たとえば、AllReduce は、すべてのアクセラレータの値を結合し、その結果をすべてのアクセラレータと共有します。Lite スイートは、簡単なヘルスチェックを行う場合や、単一ホストのワークロードを実行する前に使用します。
  • 標準: ターゲット容量全体で包括的な検証を実行します。GPU では、Standard スイートは複数のノードで集団オペレーションを実行し、GPU メモリ帯域幅を測定します。TPU では、すべての Lite テストに加えて、持続的なコンピューティング、メモリ、ネットワークのストレステストが実行されます。マルチホストのトレーニング ワークロードまたは推論ワークロードを実行する前に、Standard スイートを使用します。これらのワークロードでは、持続的な負荷の下でのネットワーク パフォーマンスと安定性がジョブのパフォーマンスに直接影響します。
スイート アクセラレータ テスト フォーカス
lite GPU nvidia-smi、dcgm、gemm、nccl-single-node GPU とドライバの健全性、コンピューティング スループット、ノード内 GPU 通信を迅速に検証します。
TPU tpu-info、tpu-gemm、tpu-hbm、tpu-host-device、tpu-collectives デバイスの状態、コンピューティング スループット、高帯域幅メモリ(HBM)帯域幅、ホストからデバイスへの帯域幅、チップ間相互接続(ICI)の集合帯域幅を迅速に検証します。
standard GPU nvidia-smi、dcgm、gemm、nccl-cluster、nccl-pairwise、stream ターゲット ノード間のマルチノード ネットワーク検証とメモリ帯域幅。
TPU すべての TPU lite テスト、tpu-compute-stress、tpu-hbm-stress、tpu-network-stress 不安定性、サイレント データ破損、ICI ビットエラーを検出する持続的なストレステスト。

nccl-domain GPU テストはスイートの一部ではありません。nccl-domain を実行するには、--tests フラグを使用します。

GPU スイートとテスト

クラスタ ヘルス スキャナは、GPU ノードに次のスイートを提供します。

  • Lite: GPU ドライバとハードウェアを検証し、コンピューティング スループットを測定して、各ノード内で NVIDIA Collective Communications Library(NCCL)テストを実行します。
  • 標準: すべてのターゲット ノードとノードペア間で NCCL 集団を実行して、ノード間ネットワークのパフォーマンスを測定し、メモリ帯域幅を測定します。

次の表に、各 GPU テストの説明を示します。

テスト 説明 スイート
nccl-single-node 単一ノード内の GPU 間で NCCL 集団テストを実行します。 lite
nvidia-smi NVIDIA System Management Interface を使用して、GPU の基本的な健全性と GPU ドライバを確認します。 lite、standard
dcgm NVIDIA Data Center GPU Manager(DCGM)診断を実行して、各 GPU で詳細なハードウェア チェックを行います。 lite、standard
gemm 一般的な行列乗算(GEMM)を実行して、GPU のコンピューティング スループットを測定します。 lite、standard
nccl-cluster すべてのターゲット ノードで NCCL 集団テストを実行して、クラスタ全体のネットワーク帯域幅を測定します。 standard
nccl-pairwise ノードのペア間で NCCL テストを実行して、ノード間のレイテンシを測定し、障害のあるノードまたはリンクを特定します。 standard
stream STREAM ベンチマークを実行して、GPU メモリ帯域幅を測定します。 standard
nccl-domain 各マルチノード NVLink ドメイン内で NCCL 集団テストを実行します。マルチノード NVLink ドメインを持つマシンタイプでのみサポートされます。 なし(--tests で実行)

TPU スイートとテスト

クラスタ ヘルス スキャナは、TPU ノードに次のスイートを提供します。

  • Lite: 各ホストの TPU チップと HBM のパフォーマンスを検証し、ホストからデバイスへの帯域幅を測定します。また、集合オペレーション テストを実行して ICI 帯域幅を測定します。
  • 標準: スライス内の TPU チップ全体で集団オペレーションを実行し、TPU チップ、HBM、ICI リンクで持続的なストレステストを実行します。

次の表に、各 TPU テストの説明を示します。

テスト 説明 スイート
tpu-info デバイス数、LibTPU バージョン、TPU デバイスタイプなど、基本的な TPU の健全性を確認します。 lite、standard
tpu-gemm 一般的な行列乗算(GEMM)を実行して、持続的なピーク TFLOPS を測定します。 lite、standard
tpu-hbm HBM の読み取りと書き込みの帯域幅を測定します。 lite、standard
tpu-collectives AllReduce や AllGather などの集合オペレーションの時間を測定して、ICI 帯域幅を測定します(GKE クラスタのみ)。 lite、standard
tpu-host-device ホストからデバイスへの帯域幅を測定します。 lite、standard
tpu-compute-stress 持続的な行列乗算を実行して、計算の安定性を検証し、サイレント データ破損を検出します。 standard
tpu-hbm-stress HBM に負荷をかけて最大帯域幅を測定し、データの完全性を検証します。 standard
tpu-network-stress ICI リンクを介して大規模なランダム ペイロードを送信し、持続的な帯域幅を測定してビットエラーを検出します(GKE クラスタのみ)。 standard

始める前に

クラスタ ヘルス スキャナを使用する前に、必要なツールをインストールし、権限を構成して、クラスタまたはインスタンスに接続します。

インストール

ヘルススキャンを実行する前に、デプロイ環境のインストールを完了します。

GKE クラスタ

GKE クラスタでヘルススキャンを実行するには、ターゲット クラスタがあることを確認し、スキャンを実行するマシンに必要なツールをインストールします。

Slurm クラスタ

Slurm クラスタでヘルススキャンを実行するには、ターゲット GPU クラスタがあることを確認し、sinfo コマンドと sbatch コマンドが使用可能な Slurm コントローラまたはログインノードに必要なツールをインストールします。

Slurm クラスタの場合は、Python パッケージのインストール オプションを使用します。Slurm はコンテナ イメージ オプションをサポートしていません。

スタンドアロン TPU インスタンス

スタンドアロン TPU インスタンスでヘルススキャンを実行するには、ターゲット TPU インスタンスがあることを確認し、必要なツールをインスタンスに直接インストールします。

必要なロール

ヘルススキャンを実行するために必要な権限を取得するには、プロジェクトに対する roles/compute.viewer ロールを付与するよう管理者に依頼してください。このロールにより、クラスタ ヘルス スキャナはノードの Compute Engine メタデータとトポロジ情報を読み取ることができます。

デプロイ環境に応じて、次の Identity and Access Management(IAM)ロールも必要です。

環境 必要なロール
GKE クラスタ Kubernetes Engine デベロッパー(roles/container.developer)
Slurm クラスタ
  • Compute OS Login(roles/compute.osLogin)または Compute OS 管理者ログイン(roles/compute.osAdminLogin)
  • Identity-Aware Proxy(IAP)を介して接続する場合は、IAP で保護されたトンネル ユーザー(roles/iap.tunnelResourceAccessor)
スタンドアロン TPU インスタンス
  • TPU 管理者(roles/tpu.admin)
  • IAP で保護されたトンネル ユーザー(roles/iap.tunnelResourceAccessor)(IAP 経由で接続する場合)

レポート用に Cloud Storage バケットを構成する場合は、バケットに対するストレージ オブジェクト管理者ロール(roles/storage.objectAdmin)も必要です。このロールにより、クラスタ ヘルス スキャナは、ヘルスレポートなどの結果アーティファクトをバケットにアップロードできます。

ロールの付与については、プロジェクト、フォルダ、組織へのアクセス権の管理をご覧ください。

クラスタまたはインスタンスに接続する

ヘルススキャンを実行する環境に接続します。

GKE クラスタ

アプリケーションのデフォルト認証情報(ADC)を設定し、GKE クラスタと通信するように kubectl を構成します。

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

Slurm クラスタ

SSH を使用して Slurm コントローラまたはログインノードに接続します。

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

スタンドアロン TPU インスタンス

SSH を使用してスタンドアロン TPU インスタンスに接続します。

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

クラスタ ヘルス スキャナをインストールする

スキャンを実行するマシンにクラスタ ヘルス スキャナをインストールします。これは、環境によって異なります。

  • GKE クラスタ: クラスタへの kubectl アクセス権を持つマシン。
  • Slurm クラスタ: Slurm コントローラまたはログインノード。
  • スタンドアロン TPU インスタンス: TPU インスタンス自体。

GKE クラスタと Slurm クラスタでは、クラスタ ヘルス スキャナが GPU ノードまたは TPU ノードに一致する診断コンテナ イメージを自動的に pull し、クラスタにスケジュールします。そのため、個々のコンピューティング ノードにソフトウェアをインストールする必要はありません。スタンドアロン TPU インスタンスでは、インスタンスにクラスタ ヘルス スキャナを直接インストールして実行します。

クラスタ ヘルス スキャナは、Python パッケージまたはコンテナ イメージとしてインストールできます。このドキュメントの残りの部分にある chs コマンドは、どちらのインストール オプションでも機能します。コマンドの詳細な使用状況情報を表示するには、--help フラグを追加します。

Python パッケージ

Python 仮想環境を作成し、GitHub からクラスタ ヘルス スキャナ パッケージをインストールします。GKE クラスタと Slurm クラスタでは、Python 3.12 以降を使用します。スタンドアロン TPU インスタンス(x86_64)では、Python 3.12 を使用する必要があります(Python 3.13 以降では、pip install は TPU ベンチマークの依存関係をインストールせず、chs run はインスタンスをスキップします)。

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

特定のリリースをインストールするには、リポジトリ URL に @VERSION を追加します。

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

リリースの一覧については、GitHub のクラスタ ヘルス スキャナのリリースをご覧ください。

コンテナ イメージ

クラスタ ヘルス スキャナは、Artifact Registry のコンテナ イメージとして配布されます。このイメージは GPU と TPU の両方をサポートしています。コンテナ イメージは、GKE クラスタとスタンドアロン TPU インスタンスで使用できますが、Slurm クラスタでは使用できません。

  1. Artifact Registry で認証するように Docker を構成し、クラスタ ヘルス スキャナのコンテナ イメージを pull します。

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

    latest ではなく特定のリリースを pull するには、latest をバージョン番号に置き換えます。たとえば、GitHub リリース v0.3.0 の場合は 0.3.0 です。リリースの一覧については、GitHub のクラスタ ヘルス スキャナのリリースをご覧ください。

  2. chs コマンドを直接実行するシェル エイリアスを作成します。作成するエイリアスは、環境によって異なります。

    • GKE クラスタ: エイリアスは、kubeconfig ファイルと Google Cloud 認証情報を読み取り専用モードでマウントします。このエイリアスは、実行の状態を chs-local-state Docker ボリュームに保存し、出力ファイルを現在のディレクトリの chs-output ディレクトリに書き込みます。

      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'
      
    • スタンドアロン TPU インスタンス: Container-Optimized OS を実行する TPU インスタンスでは、コンテナ イメージが唯一のサポートされているインストール オプションです。このエイリアスは、インスタンスの TPU デバイスとホスト PID 名前空間へのアクセス権をコンテナに付与し、ホストのルート ファイル システムを /host にマウントして、 Google Cloud認証情報を読み取り専用モードでマウントします。このエイリアスは、実行の状態を chs-local-state Docker ボリュームに保存し、出力ファイルを現在のディレクトリの chs-output ディレクトリに書き込みます。

      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'
      

省略可: レポート用の Cloud Storage バケットを設定する

デフォルトでは、クラスタ ヘルス スキャナはレポートと診断ログをローカル出力ディレクトリに保存します。Cloud Storage バケットを構成して、リモートに保存することもできます。

  1. ヘルススキャン レポート用のバケットがまだない場合は、作成します。

    gcloud storage buckets create gs://BUCKET_NAME \
        --location=BUCKET_LOCATION \
        --project=PROJECT_ID
    
  2. プリンシパル ユーザー アカウントまたはサービス アカウントに Storage オブジェクト管理者ロール(roles/storage.objectAdmin)を付与します。

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

    PRINCIPAL メンバーは、レポートを書き込むプリンシパルです。たとえば、user:EMAIL や serviceAccount:SERVICE_ACCOUNT_EMAIL です。

  3. クラスタ ヘルス スキャナがレポートを保存するバケットを設定します。クラスタ ヘルス スキャナはバケットを自動的に作成しないため、バケットがすでに存在している必要があります。このコマンドは、環境ごとに 1 回だけ実行する必要があります。

    chs configure storage gcs BUCKET_NAME
    

    バケット内のフォルダ接頭辞の下にレポートを保存するには、バケット名に接頭辞を追加します。

    chs configure storage gcs BUCKET_NAME/PREFIX
    

ヘルススキャンを実行する

このセクションでは、ノードがアイドル状態であることを確認し、スキャンを開始して、その進行状況をモニタリングする方法について説明します。

ターゲット ノードがアイドル状態であることを確認する

クラスタ ヘルス スキャナはアイドル状態の容量でのみ実行され、ワークロードを自動的に停止または強制排除することはありません。スキャンを開始する前に、ターゲット ノードまたはインスタンスで実行されているワークロードをドレインまたは停止します。

クラスタ ヘルス スキャナがターゲット ノードまたはインスタンスでアクティブなワークロードを検出すると、容量は次のように処理されます。

  • GPU: クラスタ ヘルス スキャナは、ビジー状態のノードをスキップし、残りのアイドル状態のノードでスキャンを実行します。
  • TPU: クラスタ ヘルス スキャナがビジー状態の容量を処理する方法は、環境によって異なります。
    • GKE クラスタ: マルチホスト TPU テスト(tpu-collectives と tpu-network-stress)には、完全なアイドル スライスが必要です。一方、単一ホスト TPU テストは、個々のアイドル ノードで実行できます。
      • 静的スライス ノードプール(--nodepools または --nodes): lite スイートまたは standard スイートの実行時にプール内の一部のノードがビジー状態の場合、クラスタ ヘルス スキャナは警告をログに記録し、マルチホストテストを省略して、残りのアイドル状態のノードで単一ホスト TPU テストを実行します。
      • 動的スライス ノードプール(--nodepools または --nodes): --nodepools を使用してプールをターゲットにするには、クラスタ ヘルス スキャナがフルプールの Slice リソースをプロビジョニングできるように、ノードプール全体がアイドル状態である必要があります。--nodes(GKE バージョン 1.36.0-gke.3712000 以降)を使用して特定のノードをターゲットに設定すると、クラスタ ヘルス スキャナは、アイドル状態のノードごとに個別の 2x2x1 サブスライスをプロビジョニングし、ビジー状態のノードをスキップして、アイドル状態のノードで単一ホストの TPU テストを実行します。
    • スタンドアロン TPU インスタンス: 別のプロセスが /dev/vfio の TPU デバイスを使用している場合、クラスタ ヘルス スキャナは実行できません。

ターゲット容量がアイドル状態であることを確認するには、環境に応じた手順を行います。

GKE クラスタ

  1. ターゲット ノードプールでアクティブなワークロードの Job または Pod を停止または削除するか、実行中のワークロードが完了するまで待ちます。

    kubectl drain を使用してノードプールからワークロードを強制排除する場合は、スキャンを開始する前にノードの遮断を解除して、クラスタ ヘルス スキャナが診断 Pod をスケジュールできるようにします(クラスタ ヘルス スキャナは遮断されたノードをスキップします)。

    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
    

    スキャンの実行中に、新しいワークロードがノードプールにスケジュールされないようにします。

  2. ノードプールにワークロード Pod が残っていないことを確認します。

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

    kube-system Namespace の DaemonSet によって管理される Pod などのシステム Pod は、引き続き実行できます。

Slurm クラスタ

  1. ターゲット パーティションで実行中のジョブを確認します。

    squeue --partition=PARTITION_NAME
    

    パーティションでジョブが実行されている場合は、ジョブが完了するまで待つか、scancel JOB_ID でジョブをキャンセルします。

  2. ターゲット パーティション内のノードが idle 状態であることを確認します。

    sinfo --partition=PARTITION_NAME
    

スタンドアロン TPU インスタンス

インスタンス上の TPU デバイスを使用している他のプロセスがないことを確認します。

sudo fuser -v /dev/vfio/*

プロセスが一覧表示されている場合は、ワークロードが完了するまで待つか、プロセスを停止してからスキャンを開始します。

スキャンを開始する

chs run コマンドに渡すフラグは、クラスタ ヘルス スキャナを実行する環境によって異なります。クラスタ ヘルス スキャナは、スケジューラとアクセラレータ タイプを自動的に検出するため、指定する必要はありません。

アクセラレータ タイプで使用可能な診断スイートとテストを一覧表示するには、次のコマンドを実行します。

  • GPU の場合:

    chs list suites --gpu
    chs list tests --gpu
    
  • TPU の場合:

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

GKE ノードプール

クラスタ ヘルス スキャナは、ローカルマシンや Cloud Shell など、クラスタへの kubectl アクセス権を持つマシンから実行します。

1 つ以上のノードプールでスキャンを開始するには、次のコマンドを実行します。

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

次のように置き換えます。

  • NODE_POOL_NAMES: スキャンする GPU または TPU ノードプールのカンマ区切りのリスト。たとえば、a4-pool-1,a4-pool-2 や tpu7x-pool-1,tpu7x-pool-2 です。すべてのターゲット ノードプールで同じマシンタイプを使用する必要があります。
  • SUITE: 実行する診断スイート(lite または standard)。各スイートの詳細については、診断スイートをご覧ください。

スイート全体ではなく特定のテストを実行するには、--suite フラグを --tests フラグに置き換え、テスト名のカンマ区切りのリストを指定します。

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

ノードプール全体ではなく特定のノードをスキャンするには、--nodepools フラグを --nodes フラグに置き換え、ノード名のカンマ区切りのリストを指定します。

--nodepools フラグで複数のノードプールを指定すると、クラスタ ヘルス スキャナはアクセラレータ タイプに基づいてノードプールを処理します。

  • GPU ノードプール: 指定されたノードプール内のすべてのアイドル状態の GPU ノードを 1 つのターゲット セットに結合し、それらすべてに対してマルチノードテスト(nccl-cluster と nccl-pairwise)を実行します。
  • TPU ノードプール: クロススライス(マルチスライス)テストを行わずに、1 回の実行で各ノードプール(TPU スライス)を個別に並列評価します。

Slurm パーティション

sinfo コマンドと sbatch コマンドが使用可能な Slurm コントローラまたはログインノードで、クラスタ ヘルス スキャナを実行します。Slurm には、Python パッケージのインストール オプションが必要です。インストール手順については、Python パッケージをご覧ください。

スキャンを開始する前に、ノードが us-docker.pkg.dev からベンチマーク イメージを pull できるように、クラスタで Enroot 認証情報を構成します。

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

1 つ以上のパーティションでスキャンを開始します。

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

次のように置き換えます。

  • PARTITION_NAMES: スキャンする Slurm パーティションのカンマ区切りのリスト。
  • SUITE: 実行する診断スイート(lite または standard)。各スイートの詳細については、診断スイートをご覧ください。

フルスイートではなく特定の GPU テストを実行するには、--suite フラグを --tests フラグに置き換え、テスト名のカンマ区切りのリスト(nccl-pairwise,gemm や nccl-domain など)を指定します。

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

スタンドアロン TPU インスタンス

TPU インスタンスでクラスタ ヘルス スキャナを直接実行します。TPU インスタンスは、/dev/vfio で TPU デバイスを公開する必要があります(これは、インスタンスで ls /dev/vfio を実行して確認できます)。

root ユーザーとしてクラスタ ヘルス スキャナを実行しない場合は、TPU テストを実行する前に memlock の上限を引き上げます。

ulimit -l unlimited

TPU インスタンスでスキャンを開始するには、次のコマンドを実行します。

chs run --suite=SUITE

SUITE は、実行する診断スイート(lite または standard)に置き換えます。各スイートの詳細については、診断スイートをご覧ください。

完全なスイートではなく特定の TPU テストを実行するには、--suite フラグを --tests フラグに置き換え、テスト名のカンマ区切りのリスト(tpu-host-device,tpu-hbm-stress など)を指定します。

chs run --tests=TEST_NAMES

実行と結果を表示する

クラスタ ヘルス スキャナは、chs コマンドを実行するクライアント マシン(~/.local/share/chs/、またはコンテナ イメージを使用する場合は chs-local-state Docker ボリューム)に、実行履歴と構成設定をローカルに保存します。その結果、chs history コマンドと chs results コマンドは、その環境から開始された実行のみを一覧表示します。

以前の実行とその実行 ID を一覧表示するには、次のコマンドを実行します。

chs history

実行結果と、インタラクティブな HTML レポート(bill_of_health.html)と JSON レポート(bill_of_health.json)の場所を表示するには、次のコマンドを実行します。

chs results RUN_ID

RUN_ID を省略すると、クラスタ ヘルス スキャナは実行を選択するように求めます。このコマンドは、ローカルパスを出力します。バケットを構成した場合は、Cloud Storage URI を出力します。過去の実行の保存された結果を読み取り、クラスタまたはインスタンスで新しいジョブを開始しません。

スキャンをキャンセルする

スキャンをキャンセルし、そのジョブを停止して、クラスタまたはインスタンスに作成されたリソースを削除するには、次のいずれかのコマンドを実行します。

  • 最新の実行をキャンセルします。

    chs cancel
    
  • 特定の実行をキャンセルします。

    chs cancel RUN_ID
    
  • クラスタまたはインスタンスで実行されているすべてのクラスタ ヘルススキャナ(他のユーザーが開始した実行を含む)をキャンセルします。

    chs cancel --all
    

結果を解釈する

スキャンが完了すると、クラスタ ヘルス スキャナは次のアーティファクトをローカル出力ディレクトリに保存し、ストレージを構成している場合は Cloud Storage バケットにアップロードします。

  • インタラクティブ HTML レポート(bill_of_health.html): 各テスト、測定された指標、ステータスが表示されます。
  • JSON レポート(bill_of_health.json): 各テストのパラメータ スイープと測定された指標が含まれます。
  • Workspace ディレクトリ: 診断ログが含まれています。

健全性レポートを表示する

スキャンのレポートの正確なローカルパスまたは Cloud Storage URI(gs://BUCKET/PREFIX/bills_of_health/RUN_ID.html と gs://BUCKET/PREFIX/bills_of_health/RUN_ID.json)を確認するには、次のコマンドを実行します。

chs results RUN_ID

Cloud Storage バケットを構成した場合は、chs results から返された URI から JSON レポートを直接表示できます。

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

レポートの内容

ヘルスレポートには、クラスタ ヘルス スキャナがテストしたすべてのノードと、各ノードのベンチマーク結果が一覧表示されます。GPU スキャンと TPU スキャンでは、同じレポート形式が使用されます。各ノードは、次のいずれかのステータスを受け取ります。

ステータス 説明
HEALTHY すべてのテストで、マシンタイプに期待されるパフォーマンスが達成されました。
DEGRADED ノードはテストを完了しましたが、1 つ以上の結果が期待されるパフォーマンスを下回りました。
POTENTIALLY DEGRADED スクリーニング テストが期待されるパフォーマンスを下回り、対応するストレステストが実行されず、結果が確認されなかった。
INCOMPLETE 1 つ以上のテストが実行に失敗したか、タイムアウトしたか、キャンセルされたか、ノードのレポート指標を報告しませんでした。

bill_of_health.json ファイルには、次の最上位フィールドが含まれています。

  • report_id: スキャン実行の固有識別子。
  • chs_version: レポートを生成したクラスタ ヘルス スキャナのバージョン。
  • created_at: レポートが生成された時点のタイムスタンプ。
  • system_info: テスト対象のシステムに関するメタデータ(クラスタタイプやマシンタイプなど)。
  • test_results: テスト結果オブジェクトのリスト。各エントリには、次のフィールドが含まれます。
    • test_name: 診断テストの名前。
    • result_status: テストの結果(RESULT_STATUS_SUCCESS、RESULT_STATUS_FAILED など)。
    • target_resources: テストが実行されたノード(node_name と instance_id)。
    • metrics: テストの測定指標と検証基準。

ヘルスレポートは、一貫性のある構造化 JSON 形式を使用します。レポートを BigQuery などの分析ツールに読み込み、同じ容量の連続スキャンのレポートを比較して、パフォーマンスの緩やかなドリフトを検出できます。

異常なノードを修正する

ヘルスレポートで DEGRADED、POTENTIALLY DEGRADED、INCOMPLETE のステータスのノードまたはインスタンスが特定された場合は、次の手順を行います。

  1. 一時的な問題を除外するには、ノードを閉鎖またはドレインする前に、GKE ノードプールまたはノード、Slurm パーティション、またはスタンドアロン TPU インスタンスでスキャンを再実行します(クラスタ ヘルス スキャナは、閉鎖された GKE ノードとドレインされた Slurm ノードをスキップします)。手順については、スキャンを開始するをご覧ください。

  2. 問題が解決しない場合は、影響を受けるノードまたはインスタンスに新しいワークロードがスケジュールされないようにします。

    • GKE クラスタ: 異常なノードを閉鎖します。

      kubectl cordon NODE_NAME
      
    • Slurm クラスタ: 異常なノードをドレインします。

      sudo scontrol update NodeName=NODE_NAME State=DRAIN Reason="CHS unhealthy"
      
    • スタンドアロン TPU インスタンス: 問題の修正が完了するまで、TPU インスタンスで新しいワークロードを開始しないでください。

  3. アクセラレータのタイプと環境に応じて、次のいずれかのオプションを使用してノードまたはインスタンスを修復または交換します。

    サポートに問い合わせる際は、診断ログを含むローカル出力ディレクトリまたは Cloud Storage バケットのワークスペース ディレクトリを添付し、実行 ID を含めてください。

  4. ノードまたはインスタンスが修復または交換されたら、クラスタ ヘルス スキャナがスキップしないように、再度スケジュール可能にします。その後、新しいスキャンを実行して、容量が正常であることを確認します。

    • GKE クラスタ: ノードの閉鎖を解除し、新しいワークロードをスケジュールする前にスキャンを再実行します。

      kubectl uncordon NODE_NAME
      
    • Slurm クラスタ: ノードを再開して idle 状態に戻し、新しいジョブをスケジュールする前にスキャンを再実行します。

      sudo scontrol update NodeName=NODE_NAME State=RESUME
      
    • スタンドアロン TPU インスタンス: インスタンスでスキャンを再実行し、スキャンでインスタンスが正常であることが確認されたら、ワークロードの実行を再開します。

テレメトリー

クラスタ ヘルス スキャナは、ツールの改善に役立てるために匿名の使用状況指標を Google に送信します。個人を特定できる情報(PII)は収集しません。テレメトリーはデフォルトで有効になっています。オプトアウトするには、chs configure telemetry disable を実行するか、CHS_TELEMETRY=0 環境変数を設定します。

次のステップ

クラスタ ヘルス スキャナに関する一般的な問題を解決するには、クラスタ ヘルス スキャナのトラブルシューティングをご覧ください。