dynamo-interconnect-check

Dynamo インターコネクトの確認

目的

分散サービングが依存するトランスポートが実際に機能していることを確認します。デプロイはエンドポイントのスモークテストに合格していても、分散構成に問題が潜んでいることがあります。NIXL／UCX が RDMA または NVLink 経由でピアワーカーに到達できない場合、KV 転送は低速または機能しない経路にフォールバックします。分散デプロイやそのベンチマーク値を信頼する前に、読み取り専用のチェックで問題を検出します。

このスキルは読み取り専用です。クラスターを変更することはなく、シークレットを出力することもありません。

前提条件

• オペレーターのマシンに Python 3.10 以降があること。
• 対象の Dynamo デプロイ内のワーカーポッドに対する kubectl exec アクセス権があること。
• レシピディレクトリ（recipes/<model>/<framework>/<mode>）への読み取りアクセス権があること。
• ノードの機能を確認する場合：ワーカーポッドのイメージに ibstat、nvidia-smi、lsmod などのツールがあること（ツールがない場合は失敗ではなく skipped として報告されます）。

使用するタイミング

• dynamo-recipe-runner が分散構成またはマルチノードのレシピをデプロイした後。
• 分散構成のスループット／レイテンシを報告する前に、実際のトランスポートが数値に反映されるようにするため。
• 集約構成は動作するのに、分散構成が遅い、停止する、または誤った出力を返し、モデルではなくファブリックに問題があると疑われる場合。

すでにクラッシュしている、またはスケジュールできないポッドの診断には、まず dynamo-troubleshoot を使用してください。

手順

1. レシピ上のトランスポート環境変数を確認する

python3 scripts/check_interconnect.py env recipes/<model>/<framework>/<mode>

設定されている NIXL／UCX／NCCL のトランスポート変数を報告し、未設定の分散構成に不可欠な変数（例：UCX_TLS、UCX_NET_DEVICES、NCCL_IB_HCA）を指摘します。ここで見つからなくても警告にとどまります。イメージに組み込まれている可能性があるため、ノードと NIXL のチェックで確認してください。各変数の役割については references/interconnect-env-vars.md を参照してください。

2. ノードの機能を確認する

GPU ノード上、または実行中のワーカーポッド内で実行します。

python3 scripts/check_interconnect.py node \
  --namespace "${NAMESPACE}" --pod <worker-pod>

次の項目を読み取り専用で調べます：InfiniBand デバイスと Active リンク、GPUDirect RDMA （nvidia_peermem）、GDRCopy、GPU トポロジー内の NVLink。ツールがない場合は失敗ではなく skipped として報告されます。

3. NIXL の到達可能性を検証する

python3 scripts/check_interconnect.py nixl \
  --namespace "${NAMESPACE}" --pod <worker-pod>

ポッド内の NIXL テストツールを探し、プリフィル↔デコード間のペア転送テストを実行するための次の手順を提示します。ポッド間の完全な転送テストには、ファブリック上でスケジュールされた GPU ポッドが 2 つ必要です。

利用可能なスクリプト

スクリプト	目的	引数
scripts/check_interconnect.py env	レシピ上の NIXL／UCX／NCCL 環境変数を調べる	位置引数としてレシピのパス
scripts/check_interconnect.py node	ノードまたはポッド上の InfiniBand、GPUDirect RDMA、GDRCopy、NVLink を調べる	--namespace、--pod
scripts/check_interconnect.py nixl	ポッドの NIXL 転送テストの準備状況を提示する	--namespace、--pod

agentskills.io の run_script() プロトコルを介して実行します。

run_script("scripts/check_interconnect.py", args=["env", "recipes/qwen3-coder-480b/sglang/disagg"])
run_script("scripts/check_interconnect.py", args=["node", "--namespace", "dynamo-demo", "--pod", "qwen-worker-0"])

例

デプロイ前に、分散構成のレシピにおけるトランスポート環境変数の設定状況を確認します。

python3 scripts/check_interconnect.py env recipes/qwen3-coder-480b/sglang/disagg

デプロイ後に、ワーカーポッドのファブリックを検証します。

python3 scripts/check_interconnect.py node \
  --namespace dynamo-demo --pod qwen-worker-0
python3 scripts/check_interconnect.py nixl \
  --namespace dynamo-demo --pod qwen-worker-0

エージェントプロトコルを介した同等の実行方法：

run_script("scripts/check_interconnect.py", args=["nixl", "--namespace", "dynamo-demo", "--pod", "qwen-worker-0"])

出力の仕様

各チェックは、1 行の詳細とともに ok／warn／fail／skipped を返し、分散トランスポートの準備状況を総合的に判定します。次の項目を報告します。

• 設定済みのトランスポート環境変数と、未設定の分散構成に不可欠な環境変数
• RDMA／GPUDirect／NVLink の機能状況
• NIXL の到達可能性が検証済みかどうか、および未検証の場合は次に実行するコマンド
• 分散構成を信頼できるか、または最初に何を修正すべきかを明確に示す説明

制限事項

• 読み取り専用のファブリック検査です。完全な NIXL ペア転送は実行しません（実行にはスケジュール済みの GPU ポッドが 2 つと、ポッド内の NIXL テストツールが必要です）。
• ツール（ibstat、nvidia-smi、lsmod）がない場合の skipped 結果は判定不能であり、合格を意味しません。
• 環境変数のチェックはレシピのテキストを調べます。initContainers 経由で実行時に設定された値や、オペレーターが適用した環境変数は検出されません。
• 単一ノードの集約デプロイではトランスポートを使用しません。このスキルは分散構成／マルチノードの検証向けです。

トラブルシューティング

症状	考えられる原因	次のステップ
env ですべての重要な変数が不足していると報告される	イメージに変数が組み込まれている、またはオペレーターによって注入されている	ワーカーポッド内で node チェックを実行し、実際の環境変数を確認します
node でアクティブな IB リンクがないと報告される	ファブリックの停止、または HCA がノードにプロビジョニングされていない	クラスター管理者に連絡し、kubectl describe node に nvidia.com/gpu と IB ラベルが表示されることを確認します
nvidia_peermem が見つからない	GPUDirect RDMA モジュールが読み込まれていない	クラスター管理者に nvidia-peermem の読み込みを依頼します。読み込まれていない場合、NIXL はステージングコピーにフォールバックします
nixl でテストツールが見つからない	ワーカーイメージに NIXL テストハーネスが含まれていない	NIXL 対応イメージを使用するか、デバッグポッドからスタンドアロン転送テストを実行します

ベンチマーク

NVCARPS-EVAL のパフォーマンスレポート（NVSkills CI パイプラインによって自動生成）については、BENCHMARK.md を参照してください。更新するには、このスキルに関連する上流 PR で /nvskills-ci を再実行します。

参考資料

• references/interconnect-env-vars.md — NIXL/UCX/NCCL 環境変数の一覧と IB 機能チェックリスト。
• 読み取り専用のチェックにはすべて scripts/check_interconnect.py を使用します。