Sélectionner un Transport Distant NVSHMEM

Objectif

Recommander une configuration de transport NVSHMEM à partir de preuves statiques. Distinguer l'admissibilité absolue de l'adéquation kernel attendue, séparer les faits documentés de l'inférence.

Concentrer l'attention sur les sondes système en lecture seule et l'inspection de source. Ne pas exécuter d'applications NVSHMEM, de tests de correction ou de benchmarks de performance.

Prérequis

• Exiger un inventaire des plugins de transport installés avant de recommander un transport qui doit être disponible dans l'installation sélectionnée.
• Enregistrer la version NVSHMEM installée quand elle est facilement disponible, mais ne pas exiger de vérification de version au niveau du correctif pour une sélection de transport ordinaire ou des réglages stables comme NVSHMEM_REMOTE_TRANSPORT.
• Exiger des preuves de version exacte uniquement quand la décision dépend d'une barrière de version, d'un problème connu, d'un réglage modifié, ou d'une limitation de mode opératoire ou mémoire spécifique à la version.
• Utiliser le workflow sibling $nvshmem-docs, ou son fichier ../nvshmem-docs/SKILL.md lisible, quand l'utilisateur demande une vérification officielle actuelle/exacte ou qu'une décision sensible à la version exacte ne peut pas être résolue à partir de la matrice intégrée. Ne pas l'invoquer simplement parce que le correctif cible diffère d'une version source examinée par la matrice.
• Ne pas exiger de clé API, de commande privilégiée, d'accès réseau pour l'inspection, ou d'exécution de benchmark.

Entrées

Entrées de Recommandation Centrales

• Inventaire des plugins de transport installés, ou confirmation explicite de l'utilisateur quant au transport disponible.
• Fabric/fournisseur cible : InfiniBand, RoCE, EFA, Slingshot/CXI, UCX-géré, ou NVLink uniquement.
• Pour l'analyse kernel/charge de travail uniquement, source CUDA kernel/application sélectionnée, ou un profil couvrant :
  • utilisation des API host, on-stream ou device ;
  • opérations RMA, AMO, signalisation, synchronisation ou collectives ;
  • tailles de message typiques et gamme ;
  • threads, warps et CTAs émetteurs ;
  • fan-out pair et débit de message simultané attendu.
• Échelle de job : nombre total de PEs et PEs locaux par nœud.
• Résultat souhaité : défaut général, sensible à la latence, orienté débit, ou priorité à la compatibilité.

Optionnel

• Version NVSHMEM exacte au niveau correctif quand la décision n'est pas sensible à la version.
• NVSHMEM_PREFIX, cache CMake, module/détails de conteneur, commande lanceur, environnement et fichiers de configuration NVSHMEM.
• Détails GPU, NIC, driver, kernel, OFED/rdma-core, UCX, libfabric, GPUNetIO ou DOCA non disponibles par inspection.
• Topologie GPU-vers-NIC et liaison PE locale.
• Mix de trafic host/device, disponibilité CPU, comportement kernel persistant, opportunités de batching et fréquence de complétion.
• Atomiques requis, buffers utilisateur enregistrés, VMM, DCI/DCT, multi-NIC, Spectrum-X ou fonctionnalités custom-QP.
• Transports préférés ou interdits.

Ne pas redemander des faits que l'utilisateur a déjà fournis. Préférer une recommandation unique basée sur la meilleure preuve à une liste de branches conditionnelles. Énoncer les hypothèses matérielles et les inconnues, mais retenir la sélection de configuration uniquement quand aucun candidat ne passe une barrière absolue ou que le réglage lui-même ne peut pas être résolu en toute sécurité.

Instructions

1. Établir la Source de Preuve

D'abord établir si l'agent s'exécute sur le système cible ; demander à moins que l'utilisateur ait déjà répondu ou fourni une sonde complète du système cible. Ne jamais inférer cela à partir du shell, du planificateur, du nom d'hôte, du matériel ou du repository.

Si oui, inspecter le script collecteur intégré complet avant sa première invocation dans le checkout actuel. Exécuter uniquement ce fichier inspecté ; s'il est indisponible ou incomplet, ne pas l'exécuter. Ensuite annoncer la sonde en lecture seule et invoquer le collecteur sans préfixe :

run_script("scripts/collect-transport-facts.sh")

S'il résout un préfixe NVSHMEM, dire à l'utilisateur quelle installation sera analysée. Sinon demander un préfixe absolu et réexécuter :

run_script("scripts/collect-transport-facts.sh", "--prefix", "/opt/nvshmem")

Remplacer le préfixe d'exemple par le préfixe absolu résolu. Préserver la sortie partielle quand elle se termine avec le statut 2.

Si le collecteur émet des entrées manual_follow_up_command, arrêter le sondage automatique et demander à l'utilisateur d'exécuter ces commandes manuellement sur l'hôte cible ou l'allocation/conteneur exact utilisé pour lancer NVSHMEM. Reprendre après que l'utilisateur retourne sa sortie complète. Ne pas répéter une commande quand une sortie réussie équivalente était déjà fournie.

Si non, demander la sortie complète de bash scripts/collect-transport-facts.sh sur la cible, ou ses faits GPU/driver, NIC/fabric/provider, RDMA/provider-stack et job-scale. Ne pas demander un préfixe NVSHMEM dans cette branche. Utiliser les preuves d'installation déjà fournies ; sinon l'admissibilité reste conditionnelle.

2. Choisir l'Étendue de l'Analyse

Poser une seule question avec exactement deux choix : analyse kernel/charge de travail ou admissibilité système uniquement. Ignorer quand déjà répondu.

• Pour l'analyse kernel/charge de travail, inspecter uniquement le kernel sélectionné, son graphe d'appels device accessible et les appels host/on-stream directement correspondants quand la source est fournie. Sinon utiliser les champs du profil de communication dans kernel-fit.md. Ne pas chercher d'autres kernels.
• Pour l'admissibilité système uniquement, ne demander aucun détail source/profil. Sélectionner le défaut priorité-compatibilité parmi les candidats qui passent les barrières statiques du système, émettre sa configuration de sélection minimale et énoncer que l'adéquation aux charge de travail spécifique n'a pas été évaluée.

Traiter l'évaluation comme en lecture seule. Identifier l'échelle du job et l'objectif d'optimisation, et déterminer si le trafic de communication pertinent peut franchir les nœuds ; le trafic P2P/NVLink local n'utilise pas le transport distant.

3. Classifier la Communication

Quand l'analyse kernel/charge de travail a été sélectionnée, lire kernel-fit.md et enregistrer :

• surface API et opérations exactes ;
• chemins distant par rapport à local ;
• distribution de tailles de message et si les opérations sont empaquetées ;
• émetteurs, pairs et débit de message physique attendu concurrents ;
• fréquence d'ordonnancement/complétion et pression QP ;
• mix host/device, disponibilité CPU et comportement kernel persistant ;
• besoins en ressources sensibles à l'échelle comme RC versus DCI/DCT.

Ne pas inférer un débit de message élevé simplement à partir de nombreux éléments logiques. Tenir compte de l'agrégation d'application, d'une émission monothread, de la coalescence de warp et du batching.

4. Appliquer les Barrières d'Admissibilité Absolue

Lire transport-matrix.md complètement. Exclure un candidat quand l'une quelconque des conditions requises est contredite :

• plugin indisponible dans l'installation NVSHMEM sélectionnée ;
• version cible ou opération requise reconnue comme non prise en charge ;
• incompatibilité fabric/provider ;
• prérequis driver, peer-memory/DMA-BUF, GDRCopy, DevX, UCX, libfabric, GPUNetIO ou DOCA manquant ;
• mode mémoire, utilisation de buffer enregistré, échelle ou fonctionnalité requise incompatible.

Traiter un fait manquant comme conditionnel uniquement quand il peut invalider la configuration proposée. Sinon recommander le défaut documenté ou priorité-compatibilité et lister le fait manquant sous confiance et inconnues. Garder le support de build, la chargeabilité runtime et l'adéquation matérielle séparées.

Pour cette skill, un module kernel gdrdrv chargé ou un appareil /dev/gdrdrv visible est une preuve positive suffisante que le prérequis GDRCopy est présent. Ne pas exiger pkg-config, ldconfig ou un chemin libgdrapi découvert en addition, et ne pas traiter les indices manquants de bibliothèque userspace comme preuve que GDRCopy est absent.

Pour IBGDA, évaluer à la fois le chemin de données GPU et un transport distant separate host. Pour GPUNetIO GDAKI, exiger gpunetio comme transport distant. Ne jamais activer IBGDA et GPUNetIO GDAKI ensemble.

5. Classer les Candidats Admissibles

Pour l'admissibilité système uniquement, ne pas appliquer les règles d'adéquation charge de travail. Après l'admissibilité absolue, sélectionner un défaut système priorité-compatibilité : IBRC pour InfiniBand Mellanox ou RoCE vérifié, libfabric natif pour EFA ou Slingshot/CXI, un chemin UCX requis par le site, ou none pour un déploiement prouvé local uniquement. Émettre le bloc de sélection et ne pas prétendre qu'il est le plus rapide. Pour l'analyse kernel/charge de travail, appliquer ces règles dans l'ordre sans assigner de scores artificiels :

1. Barrière famille Mellanox/IB : Sur InfiniBand Mellanox ou RoCE vérifié, évaluer d'abord les chemins IB natifs. Utiliser IBRC comme ligne de base conservatrice, puis considérer IBDevX, IBGDA ou GPUNetIO uniquement quand leurs prérequis et l'adéquation charge de travail les justifient.
2. Barrière fabric native autre : Préférer libfabric avec efa sur EFA et cxi sur Slingshot/CXI quand aucune limitation opératoire spécifique à la version ou mode mémoire connue ne rentre en conflit avec l'application.
3. Pas de réseau distant : Sélectionner none uniquement quand tous les PEs pertinents communiquent dans un domaine NVLink pair-accessible et aucun chemin distant n'est requis.
4. Trafic device parallèle fin : Favoriser un chemin GDAKI admissible quand de nombreux émetteurs GPU soumettent de petites opérations distantes indépendantes et un proxy CPU les sérialiserait.
5. Choix GDAKI :
   • Favoriser IBGDA quand l'échelle de connexion DCI/DCT est requise, GPUNetIO est absent, ou la version exacte a une couverture opératoire requise plus forte.
   • Favoriser GPUNetIO GDAKI quand son échelle de connexion RC est acceptable et un chemin CPU/GPU GPUNetIO unifié ou une fonctionnalité DOCA vérifiée est utile.
   • Ne pas traiter les objectifs de conception GPUNetIO comme preuve qu'il surpasse IBGDA pour cette charge de travail.
6. Trafic proxy-friendly : Favoriser un chemin proxy pour un travail dominant host/on-stream, des transferts plus grands empaquetés, une concurrence de message faible, ou des opérations isolées sensibles à la latence.
7. Choix proxy Mellanox : Utiliser IBRC comme défaut verbs conservateur. Recommander IBDevX uniquement quand DevX mlx5 est disponible, sa couverture opératoire requise est suffisante, et une exigence concrète comme éviter un chemin dépendant de GDRCopy le justifie. Ne pas prétendre à la supériorité générale d'IBDevX.
8. Choix UCX : Favoriser UCX pour un déploiement contrôlé par UCX ou une capacité spécifique à la version vérifiée indisponible à partir des alternatives natives. Préserver les avertissements expérimentaux/statut intégrés ; consulter la documentation exacte uniquement quand la sélection dépend d'un détail spécifique à la version.

Si deux candidats restent proches, choisir l'option priorité-compatibilité comme recommandation, rapporter l'autre comme finaliste, et énoncer que l'analyse statique ne peut pas établir le gagnant en performance.

Ordonner la recommandation et la discussion des candidats par fabric cible. Sur InfiniBand Mellanox ou RoCE vérifié, mener avec IBRC, IBDevX et IBGDA/GPUNetIO le cas échéant ; ne pas mener avec libfabric. Sur EFA ou Slingshot/CXI, mener avec le fournisseur libfabric natif correspondant.

6. Émettre la Configuration de Sélection Minimale

Émettre uniquement les variables requises pour sélectionner la configuration résolue :

Ne pas ajouter de mappage HCA, comptes QP, batching, gestionnaires NIC, changements de mode mémoire ou tuning de provider à ce bloc. Mettre les préconditions de compatibilité obligatoires en dehors du bloc et router le mappage/tuning vers la skill sibling appropriée.

Défaut d'émettre le bloc de sélection minimal pour la configuration recommandée basée sur la meilleure preuve. Le retenir uniquement quand aucun candidat viable ne passe les barrières absolues ou qu'une valeur requise ne peut pas être résolue, comme un plugin manquant, une incompatibilité fabric/provider ou un mode mémoire incompatible obligatoire. Ne pas le retenir simplement parce que la version correctif, le profil charge de travail, la capacité optionnelle ou le gagnant en performance est inconnu.

7. Retourner la Recommandation

Utiliser cet ordre de section exact :

Recommandation : <transport ou configuration host/GPU combinée ; conditionnelle si nécessaire>

Configuration de sélection
<bloc export minimal, ou pourquoi il est retenu>

Preuve d'admissibilité système
<version, plugins, fabric/provider, preuves driver/module/dépendance>

Preuve d'adéquation kernel
<surface API, forme opération, tailles, concurrence, fan-out, complétion, échelle>

Finaliste
<candidat et le fait ou compromis qui l'a gardé deuxième>

Candidats exclus
<candidat : barrière absolue ou prérequis non résolu>

Confiance et inconnues
<haute|moyenne|basse ; faits documentés versus inférence ; preuves manquantes>

Vérifications statiques de suivi
<vérifications en lecture seule ou faits exacts encore nécessaires ; jamais benchmarks>

Énoncer la version de documentation consultée quand la vérification en direct a été utilisée. Décrire la performance comme adéquation attendue, pas un résultat assuré.

Routage

• Router la sélection HCA exacte et le mappage PE-vers-NIC à $nvshmem-configure-nic-pe-mapping quand disponible.
• Router les packages, plugins ou builds manquants à $nvshmem-install quand disponible.
• Router les défaillances d'initialisation runtime à $nvshmem-troubleshoot-and-report-bugs quand disponible.
• Si une skill sibling est indisponible, fournir la limite et les preuves suivantes requises sans inventer son comportement.

Script Disponible

Exemples

• Utiliser $nvshmem-select-remote-transport. Inspecter ce nœud de calcul cible et src/exchange.cu, puis recommander un transport orienté débit pour 256 PEs avec 8 PEs locaux par nœud.
• Utiliser $nvshmem-select-remote-transport avec la sortie du collecteur attachée et le profil de communication. Recommander un transport priorité-compatibilité pour 32 PEs avec 8 PEs locaux par nœud, émettre les exports de sélection minimaux, et énoncer toutes les hypothèses.

Garde-fous

• Ne pas exécuter de binaires NVSHMEM autres que la requête en lecture seule nvshmem-info -n.
• Ne pas lancer de jobs distribués, allouer de nœuds, benchmarker les transports ou muter l'état système/application.
• Ne pas recommander un plugin simplement parce que sa source existe ; exiger une preuve que l'installation sélectionnée le contient.
• Ne pas convertir une preuve absente en compatibilité.
• Ne pas prétendre que la preuve seule de couche liaison Ethernet prouve un RoCE fonctionnant.
• Ne pas laisser les heuristiques kernel surpasser une incompatibilité fabric/provider ou un prérequis manquant.
• Ne pas émettre à la fois les enables IBGDA et GPUNetIO GDAKI.

Dépannage

• Si le collecteur se termine avec le statut 2, préserver sa sortie et résoudre uniquement les faits manquants énumérés sous diagnostics.
• Quand nvidia-smi, ibstatus, ibv_devinfo ou rdma link échoue ou ne peut pas voir les appareils alors que la preuve statique sysfs/module suggère que le matériel existe, traiter l'accès à l'appareil comme non résolu plutôt que de traiter le matériel comme absent. Demander à l'utilisateur d'exécuter les commandes échouées manuellement sur l'hôte cible ou l'environnement de lancement exact ; ne pas réessayer avec les privilèges ou inférer l'admissibilité à partir de sysfs visible host seul.
• Si un plugin est manquant ou échoue à initialiser, vérifier le préfixe sélectionné et les dépendances, puis router les défaillances runtime à $nvshmem-troubleshoot-and-report-bugs.
• Si une capacité spécialisée reste conditionnelle, recommander le meilleur fallback supporté et émettre sa configuration. Demander la version exacte, provider ou preuve opération uniquement quand cela pourrait changer le réglage ou aucun fallback ne passe les barrières absolues.

Limitations

• L'analyse statique estime l'adéquation architecturale ; elle ne valide pas la correction runtime, ne mesure pas la performance, et ne garantit pas le transport le plus rapide.
• Certains détails de compatibilité sont sensibles à la version ; vérifier la version cible exacte uniquement quand la recommandation dépend d'un d'eux.
• Le collecteur décrit un nœud et une installation sélectionnée. Il ne prouve pas l'uniformité au niveau du cluster, un RoCE fonctionnant ou une couverture opération complète.
• La preuve incomplète réduit la confiance et doit être divulguée, mais ne prévient pas par elle-même une recommandation basée sur la meilleure preuve ou les exports minimaux.

<!-- ci trigger -->