ML ワークロードのデバッグ Wiki を使用してトラブルシューティングする

ML ワークロード デバッグ Wiki は、AI コーディング エージェントが JAX、XLA、Pathways を使用して Google Kubernetes Engine（GKE）で実行されている TPU ワークロードのトラブルシューティングに使用する GitHub リポジトリです。この Wiki により、AI エージェントはワークロード ログを収集し、エラー シグネチャを既知の障害モードと照合して、診断ワークフローを実行し、ログに基づいて根本原因を報告できます。これにより、エージェントはワークロードのクラッシュ、ハング、再起動、プリエンプションの診断に必要な情報を取得できます。

Wiki には、次の 2 種類の参考資料があります。

  • ナレッジページ: コンセプト、障害の症状とそのログ シグネチャ、トラブルシューティングのハンドブック、診断ツールを説明する Markdown ページ。
  • 実行可能な手順: JSON アクションとワークフロー。アクションは、ログクエリや kubectl コマンドなどの単一の診断ステップです。ワークフローは、特定の障害モードを診断するための一連のアクションを実行します。

/troubleshoot コマンドを実行すると、専門のサブエージェント チームがワークロード ログをトリアージし、障害に一致するワークフローを選択して実行し、各結論をプライマリ ログと照合します。次に、エージェントは根本原因、ログから引用された原因となったホスト、各中断をまとめた障害テーブルを報告します。

キーファイル

次の表に、Debug ML Workloads Wiki 内の主なファイルとディレクトリを示します。

パス 説明
_wiki/TUTORIAL.md 診断中に何が起こるか、結果をどのように評価するかを、具体例を交えて説明します。
_wiki/INDEX.md Wiki のすべてのページ、アクション、ワークフローのカタログ。それぞれに 1 行の概要が記載されています。
_wiki/concepts/ システム アーキテクチャとコンポーネントのライフサイクルのコンセプト（libtpu プログラムのライフサイクル、グッドプット、ワークロードの進行状況のモニタリングなど）。
_wiki/entities/ TPU、GPU、JAX、XLA、Pathways などのハードウェア、ソフトウェア、プラットフォーム エンティティ。
_wiki/symptoms/ 障害モード、そのログ署名、各障害モードの検証方法。
_wiki/playbooks/ トラブルシューティング戦略、ディシジョン ツリーのフローチャート、一般的な落とし穴。
_wiki/tools/ 診断ツール、スクリプト、コマンドライン リファレンス ガイド。
_wiki/workflows/ JSON 形式の診断手順。各ワークフローは、特定の障害モードを診断するための一連のアクションを実行します。
_wiki/actions/ JSON 形式の個々の診断ステップ（ログクエリや kubectl コマンドなど）。
_wiki/SCHEMA.md Wiki ページが従う必要があるページタイプ、フロントマターの要件、分類タグ。
_agents/QUICKSTART.md Antigravity ユーザーのセットアップと発送の詳細。
CLAUDE.md Claude Code ユーザー向けのワークスペース レイアウト、コマンドライン ツール、サブエージェントのロール。

キーコマンド

次の表に、wiki で実行できるコマンドを示します。

コマンド 用途 説明
/troubleshoot /troubleshoot WORKLOAD_ID。ここで、WORKLOAD_ID はワークロードまたは JobSet の名前です。 Cloud Logging、GKE クラスタ イベント、kubelet ログ、ノードログを使用してワークロードを診断します。ルーター、プラクティショナー、レビュー担当者、アドバイザーのサブエージェントが診断を実行し、根本原因、ログから引用された原因ホスト、障害テーブルを報告します。
/dashboard /dashboard [TARGET]。ここで、TARGET はオプションのプロジェクト ID、クラスタ名、またはワークロード ID です。TARGET を省略すると、Google Cloud CLI 構成で設定されているプロジェクト内のすべての GKE クラスタがダッシュボードに表示されます。 GKE Capacity & Triage Dashboard（http://localhost:8080 のローカル ウェブアプリ）を起動します。このコマンドは、ターゲットのクラスタをスキャンし、ターゲットにフィルタされたダッシュボード ビューへのリンクを返します。
/handoff

/handoff WORKLOAD_ID [CASE_ID] [--bucket=BUCKET] [--findings=PATH] [--no-watch]

WORKLOAD_ID 以外の引数はすべて省略可能です。

  • CASE_ID: サポートケース番号。
  • --bucket=BUCKET: バケットの名前。このフラグを省略すると、エージェントはバケットを要求します。
  • --findings=PATH: 既存の検出結果ファイルへのパス。このフラグを設定すると、コマンドは /troubleshoot を実行しません。
  • --no-watch: バケット モニタリングをオフにします。
 /troubleshoot の検出結果を Cloud Storage バケットにパッケージ化して Cloud カスタマーケアと共有し、バケットの更新をモニタリングします。後で更新を確認するには、/handoff --watch STORAGE_KEY を実行します。ここで、STORAGE_KEY はバケット内のハンドオフ フォルダの名前です。

前提条件

Wiki を設定する前に、診断するワークロードを特定し、次の詳細をメモします。

  • ワークロードまたは JobSet の名前。
  • ワークロードを実行する Google Cloud プロジェクトの ID。
  • 診断する実行のおおよその期間。

インストール

この wiki では、次のインストールが必要です。

  1. venv モジュールを含む Python 3 をインストールします。この wiki には Python 3.9 以降が必要です。Debian と Ubuntu では、venv モジュールは python3-venv パッケージにあります。
  2. Google Cloud CLI をインストールして初期化します。
  3. kubectl と gke-gcloud-auth-plugin をインストールします。
  4. 次のいずれかの AI コーディング エージェントをインストールします。この Wiki には、次の両方の構成ファイルが含まれています。

必要なロール

エージェントは、 Google Cloud 認証情報を使用して診断コマンドを実行します。ワークロードを診断するには、ワークロードを実行するプロジェクトに次の IAM ロールを付与します。

  • ログビューア（roles/logging.viewer）: エージェントがワークロード コンテナ、ノード、監査ログを読み取れるようにします。
  • Kubernetes Engine 閲覧者（roles/container.viewer）: エージェントがワークロードを実行したクラスタ、ノード、Pod を検査できるようにします。
  • Compute 閲覧者（roles/compute.viewer）: エージェントが、クラスタノードをバックアップする Compute Engine VM（VM のメンテナンス イベントや終了イベントなど）を検査できるようにします。
  • モニタリング閲覧者（roles/monitoring.viewer）: エージェントが、ワークロードとノードの指標を検査するワークフローの Cloud Monitoring 指標を読み取れるようにします。

/handoff コマンドを実行するには、Cloud カスタマーケアと共有する Cloud Storage バケットに対するストレージ オブジェクト管理者（roles/storage.objectAdmin）ロールも必要です。このロールにより、エージェントは検出結果をバケットにアップロードし、更新をモニタリングできます。

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

Wiki を設定する

  1. リポジトリのクローンを作成し、そのルート ディレクトリに移動します。

    git clone https://github.com/google/ml-workload-debugging-wiki.git
cd ./ml-workload-debugging-wiki

    Wiki では、リポジトリのルートからの相対パスが使用されます。そのため、このディレクトリからコマンドを実行してエージェントを起動します。

  2. Python 仮想環境を作成して有効にし、Wiki の依存関係をインストールします。

    python3 -m venv _wiki/.venv
source _wiki/.venv/bin/activate
pip install -r _wiki/requirements.txt

  3. ユーザー アカウントのローカルアプリケーションのデフォルト認証情報（ADC）を作成します。Wiki の Python ツールは、ADC を使用して Cloud Logging にクエリを実行します。

    gcloud auth application-default login

  4. wiki linter を実行して設定を確認します。

    python3 _wiki/wiki_linter.py

    linter は、Wiki の構造、スキーマ、リンクをチェックし、JSON レポートを出力します。レポートに "status": "PASS" が含まれている場合、チェックは成功しています。レポートの警告はステータスに影響しません。

ワークロードのトラブルシューティング

ML ワークロード デバッグ Wiki を使用してワークロードのトラブルシューティングを行うには、次の手順を行います。

  1. ML ワークロード デバッグ Wiki リポジトリのルートからエージェントを起動します。

    • Claude Code: 仮想環境を有効にしたシェルで、claude を実行します。Claude Code は、CLAUDE.md から Wiki の指示を読み込み、.claude/ ディレクトリからコマンドとサブエージェントの定義を読み込みます。
    • Antigravity: リポジトリのルートをワークスペースとして開きます。Wiki の Antigravity スキルとサブエージェントの定義は、_agents/ ディレクトリにあります。設定の詳細については、_agents/QUICKSTART.md をご覧ください。

  2. 診断するワークロードまたは JobSet の名前を指定して、/troubleshoot コマンドを実行します。

    /troubleshoot WORKLOAD_ID

  3. エージェントにプロジェクト ID と実行の期間を指定します。UTC タイムスタンプ形式（YYYY-MM-DDTHH:MM:SSZ）で正確な期間を指定することも、自然言語で「1 時間前」や「過去 24 時間」などの相対的な期間を指定することもできます。エージェントは期間を使用してログクエリのスコープを設定するため、実行全体がカバーされるようにしてください。

診断ワークフローは、デフォルトで読み取り専用チェックを実行します。エージェントは、ノードの電源の再投入や taint など、クラスタの状態を変更するアクションを実行する前に、明示的な確認をリクエストします。各コマンドは審査と承認を受ける必要があります。これらのアクションは、_wiki/actions/ の定義で requires_approval: true とマークされています。診断が完了すると、エージェントは調査結果を報告します。

不確定な結果を認識する方法など、検出結果を評価する方法については、_wiki/TUTORIAL.md をご覧ください。