Vérification de l'Interconnexion Dynamo

<!-- SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. SPDX-License-Identifier: CC-BY-4.0 -->

Objectif

Confirmer que le transport du serving désagrégé dépend réellement de ce qui fonctionne. Un déploiement peut passer un test de fumée d'endpoint tandis que la désagrégation est silencieusement défaillante : si NIXL/UCX ne peut pas atteindre le worker pair sur RDMA ou NVLink, le transfert KV bascule vers un chemin lent ou cassé. Détectez cela avec des vérifications en lecture seule avant de faire confiance à un déploiement désagrégé ou à ses chiffres de benchmark.

Cette skill est en lecture seule. Elle ne modifie jamais le cluster et n'affiche jamais de secrets.

Prérequis

• Python 3.10+ sur la machine opérateur.
• Accès kubectl exec à un pod worker dans le déploiement Dynamo cible.
• Accès en lecture au répertoire recipe (recipes/<model>/<framework>/<mode>).
• Pour les vérifications de capacité de nœud : outils comme ibstat, nvidia-smi, lsmod disponibles dans l'image du pod worker (les outils manquants sont signalés comme skipped, non comme des échecs).

Quand l'utiliser

• Après que dynamo-recipe-runner déploie une recette disagg ou multi-nœud.
• Avant de rapporter le débit/la latence désagrégée, afin que les chiffres reflètent le transport réel.
• Quand agg fonctionne mais disagg est lent, se bloque, ou retourne une sortie incorrecte et vous soupçonnez le fabric plutôt que le modèle.

Pour diagnostiquer les pods qui crashent déjà ou ne sont pas planifiables, utilisez d'abord dynamo-troubleshoot.

Instructions

1. Vérifier les variables d'environnement de transport sur la recipe

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

Rapporte quelles variables de transport NIXL/UCX/NCCL sont définies et signale les variables critiques pour disagg (par exemple UCX_TLS, UCX_NET_DEVICES, NCCL_IB_HCA) qui sont absentes. Une absence ici est seulement un avertissement — elles peuvent être cuites dans l'image — donc confirmer avec les vérifications de nœud et NIXL. Voir references/interconnect-env-vars.md pour ce que chaque variable fait.

2. Vérifier les capacités du nœud

Localement sur un nœud GPU, ou à l'intérieur d'un pod worker en cours d'exécution :

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

Teste (en lecture seule) : les appareils InfiniBand et les liens actifs, GPUDirect RDMA (nvidia_peermem), GDRCopy, et NVLink dans la topologie GPU. Les outils manquants sont signalés comme skipped, non comme des échecs.

3. Valider la réachabilité NIXL

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

Recherche les outils de test NIXL dans le pod et affiche l'étape exacte suivante pour exécuter un test de transfert prefill↔decode par paire. Un test de transfert cross-pod complet nécessite deux pods GPU planifiés sur le fabric.

Scripts disponibles

Invoquez via le protocole run_script() d'agentskills.io :

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"])

Exemples

Vérifier la forme du transport env d'une recipe disagg avant le déploiement :

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

Après le déploiement, valider le fabric d'un pod worker :

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

Équivalent via le protocole agent :

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

Contrat de sortie

Chaque vérification retourne ok / warn / fail / skipped avec un détail sur une ligne, plus un verdict consolidé sur la préparation du transport disagg. Rapportez :

• variables d'environnement de transport présentes vs. variables critiques pour disagg manquantes
• statut de capacité RDMA / GPUDirect / NVLink
• si la réachabilité NIXL a été validée, et la commande suivante si ce n'est pas le cas
• une déclaration claire indiquant si disagg peut être fiable, ou ce qu'il faut corriger d'abord

Limitations

• Probe de fabric en lecture seule ; n'exécute pas un transfert NIXL pairwise complet (nécessite deux pods GPU planifiés et les outils de test NIXL in-pod).
• Les résultats skipped pour les outils manquants (ibstat, nvidia-smi, lsmod) ne sont pas concluants, pas une réussite.
• La vérification des variables d'environnement inspecte le texte de la recipe ; les valeurs injectées à runtime via initContainers ou les envs appliquées par l'opérateur ne sont pas détectées.
• Les déploiements d'agrégation single-nœud n'exercent pas le transport — cette skill est pour la validation disagg / multi-nœud.

Dépannage

Benchmark

Voir BENCHMARK.md pour le rapport de performance NVCARPS-EVAL (généré automatiquement par le pipeline CI NVSkills). Pour rafraîchir, réexécutez /nvskills-ci sur une PR amont modifiant cette skill.

Références

• references/interconnect-env-vars.md — Catalogue des variables d'environnement NIXL/UCX/NCCL et liste de contrôle de capacité IB.
• Utilisez scripts/check_interconnect.py pour toutes les vérifications en lecture seule.