Accorder la cartographie NIC-to-PE NVSHMEM

Objectif

Produire une recommandation reproductible à partir de la topologie réelle GPU/NIC du nœud cible. Ne pas promettre une amélioration de performance ; présenter la cartographie comme un point de départ informé par la topologie qui doit être validé.

Exigences

• Utiliser un nœud de calcul alloué cible avec GPUs et dispositifs RDMA visibles ; ne pas utiliser la topologie du nœud de connexion comme preuve.
• Rendre nvidia-smi et /sys/class/infiniband lisibles sur ce nœud. Si /sys est indisponible, mettre ibv_devinfo à disposition ou fournir une preuve équivalente par port.
• Fournir le préfixe d'installation NVSHMEM, mettre nvshmem-info à disposition sur le nœud cible, ou fournir explicitement la version NVSHMEM installée.
• Utiliser le collecteur en lecture seule fourni si possible. Il ne nécessite aucune clé API, identifiants, installation de paquets ou accès en écriture au système de fichiers.

Entrées

Résoudre chaque entrée requise avant d'émettre les exports exacts. Si les valeurs de différentes sources entrent en conflit, identifier le conflit et demander une clarification plutôt que de sélectionner une valeur silencieusement.

Entrées requises

• Version NVSHMEM : Préférer la version installée confirmée par l'utilisateur ; sinon utiliser la sortie [nvshmem-version] du collecteur, puis nvshmem-info -n sur le nœud cible. Conserver la version complète rapportée après normalisation d'un v initial.
• Transport distant : Préférer le transport explicitement sélectionné pour l'exécution cible ; sinon utiliser le journal d'initialisation NVSHMEM du nœud cible. Ne pas déduire un transport de la topologie ; demander un journal quand la sélection automatique est ambiguë.
• Nombre local de PE : Préférer les journaux observés par rang, puis la configuration du lanceur, puis un nombre fourni explicitement par l'utilisateur. Confirmer que toutes les preuves décrivent la même allocation de nœud.
• Liaison ordonnée locale PE -> index GPU ou BDF PCI : Préférer les journaux de liaison observés par rang, puis la configuration de liaison du lanceur, puis une cartographie explicite de l'utilisateur. Utiliser CUDA_VISIBLE_DEVICES uniquement quand son ordre de rang est explicitement établi.
• Topologie GPU/NIC et port HCA du nœud cible : Préférer la sortie complète la plus récente de scripts/collect-nic-topology.sh sur le nœud cible. Sinon utiliser les commandes nvidia-smi listées plus la preuve par port /sys/class/infiniband ou ibv_devinfo. Inclure les BDF PCI GPU et NIC, l'état du port et la couche de liaison.

Entrées optionnelles

• Couche de liaison demandée : Utiliser la préférence InfiniBand ou Ethernet/RoCE explicite de l'utilisateur. Si absente, choisir parmi les ports actifs observés comme décrit à l'étape 5.
• Politique d'excédent de ports : Utiliser la demande explicite de l'utilisateur pour sélectionner un sous-ensemble rapproché ou utiliser plusieurs NIC par PE. Si absente, présenter les alternatives supportées conditionnellement et ne faire aucune sélection.
• Documentation officielle actuelle ou citations : Obtenir uniquement quand l'utilisateur les demande ou que la matrice version/transport est insuffisante. Utiliser $nvshmem-docs pour cette vérification.

Scripts

Lire les Références Requises

• Lire references/version-transport-matrix.md avant d'interpréter ou d'émettre toute variable de cartographie.
• Lire references/topology-and-output.md avant de classer les NIC ou de formater une recommandation.
• Traiter le contrat BLOCK NVSHMEM 3.8 ou ultérieur fourni comme autoritaire dans sa portée de transport enregistrée. Ne pas invoquer $nvshmem-docs simplement pour revalider un comportement que ce contrat résout, y compris pour les versions ultérieures à 3.8.

Instructions

1. Résoudre la Version et le Transport NVSHMEM

Obtenir la version de l'utilisateur en premier. Sinon utiliser la preuve [nvshmem-version] du collecteur ou exécuter nvshmem-info -n quand elle est déjà disponible sur le nœud cible. Normaliser un v initial et conserver la version complète rapportée.

Classer la version comme :

• 3.7 ou antérieure ;
• 3.8 ou ultérieure.

Ne pas supposer latest ou traiter silencieusement une version inconnue comme 3.8. Si la version reste inconnue, demander la version installée avant de continuer.

Déterminer le transport distant sélectionné : IBRC, IBDevX, IBGDA, GPUNetIO, UCX, ou libfabric. Si la sélection automatique rend le transport ambigu, demander le journal d'initialisation pertinent ou le transport prévu.

2. Résoudre l'Incertitude de Documentation

Utiliser references/version-transport-matrix.md comme autorité par défaut pour le comportement de cartographie. Ne pas invoquer $nvshmem-docs quand la matrice ou le contrat BLOCK NVSHMEM 3.8 ou ultérieur fourni résout la version, le transport, la porte de fonctionnalité et les contrôles de cartographie requis, y compris pour une version ultérieure à 3.8.

Invoquer la compétence sœur $nvshmem-docs à ../nvshmem-docs/SKILL.md uniquement quand la matrice et le contrat fourni sont insuffisants ou en conflit, l'applicabilité exacte de la version de fonctionnalité reste floue, ou l'utilisateur demande explicitement la documentation officielle en direct ou des citations. Suivre le workflow de version et de citation de cette compétence.

Si une vérification de documentation est nécessaire mais la compétence sœur, un outil de récupération HTTPS, ou les pages officielles en direct sont indisponibles :

• continuer à partir de la matrice uniquement quand elle résout le comportement requis ;
• sinon retenir les exports finaux et identifier le comportement non résolu ;
• étiqueter Documentation freshness: unverified uniquement quand une vérification de documentation a été tentée ;
• déclarer quelles routes officielles n'ont pas pu être vérifiées ; et
• jamais inventer un comportement que la matrice n'établit pas.

Quand une vérification de documentation est effectuée, rapporter l'édition de documentation exacte consultée et toute incertitude restante. Sinon identifier la section de matrice applicable comme base de la recommandation.

3. Collecter les Preuves de Topologie

Quand le script s'exécute déjà sur le nœud de calcul cible, dire à l'utilisateur que la compétence exécute un collecteur en lecture seule. Avant sa première invocation dans le checkout actuel, inspecter complètement le script collecteur fourni. Exécuter uniquement ce fichier inspecté ; s'il est indisponible ou incomplet, ne pas l'exécuter. Puis exécuter :

run_script("scripts/collect-nic-topology.sh")

Quand le préfixe d'installation NVSHMEM est connu, passer son chemin absolu explicitement :

run_script("scripts/collect-nic-topology.sh", "--prefix", "/opt/nvshmem")

Remplacer le chemin d'exemple par le préfixe absolu. Sans --prefix, la découverte utilise NVSHMEM_PREFIX, puis nvshmem-info sur PATH. Les bibliothèques de préfixe sont limitées à cette requête. Le code de sortie 2 indique une preuve incomplète.

Quand ne pas sur le nœud cible, demander à l'utilisateur la sortie complète du collecteur du nœud cible. Si le script est indisponible à distance, demander tout :

nvshmem-info -n
nvidia-smi --query-gpu=index,pci.bus_id,name --format=csv,noheader
nvidia-smi topo -m

Demander aussi, pour chaque port HCA candidat, son nom HCA, numéro de port, BDF PCI, état et couche de liaison depuis /sys/class/infiniband ou ibv_devinfo.

Ne pas exécuter un collecteur à partir d'un nœud de connexion et traiter cette topologie comme preuve de nœud de calcul.

4. Établir le Placement des PE

Obtenir le nombre de PE locaux par nœud. Supposer que les nœuds sont homogènes uniquement après avoir énoncé cette supposition.

Obtenir la liaison locale ordonnée PE -> index GPU ou BDF PCI depuis l'entrée explicite de l'utilisateur, la configuration du lanceur, CUDA_VISIBLE_DEVICES, ou les journaux par rang. Ne pas déduire le GPU d'un PE local uniquement du nombre de PE ou de l'ordre affiché par nvidia-smi topo -m.

Si la liaison est ambiguë, la demander avant de produire une cartographie de NIC rapproché exact. Un tableau conditionnel est acceptable, mais les exports finaux ne le sont pas. Ne pas contourner la liaison manquante en dupliquant chaque NIC utilisable pour chaque PE ; cela ajoute des chemins non rapprochés et est une politique multi-ports différente. Considérer une telle affectation tous-les-ports uniquement après que l'utilisateur l'ait explicitement demandée et accepté le compromis de distance.

5. Filtrer et Classer les Ports Candidats

Traiter un port HCA, pas simplement un dispositif HCA, comme l'unité NIC sélectionnable.

• Exclure les ports inactifs ou physiquement arrêtés et enregistrer pourquoi chacun a été exclu.
• Partitionner les ports actifs par couche de liaison. Ne pas mélanger InfiniBand avec Ethernet/RoCE par défaut.
• Honorer une couche de liaison explicitement demandée. Sinon choisir la partition active la plus grande ; préférer InfiniBand en cas d'égalité exacte. Demander à l'utilisateur si ce défaut entre en conflit avec leur intention de tissu ou de fournisseur.
• Classer chaque paire GPU-lié-à-port par PIX < PXB < PHB < NODE < SYS depuis nvidia-smi topo -m.
• Rompre les choix à distance égale par charge de port assignée inférieure, puis ordre canonique hca:port.
• Partager un port quand moins de ports NIC utilisables que de PE rend le partage nécessaire, en préservant d'abord la distance puis l'équilibre.

6. Résoudre l'Excédent de NIC Explicitement

Quand les ports NIC utilisables dépassent les PE locaux, s'arrêter avant les exports finaux et demander si :

1. sélectionner le sous-ensemble rapproché équilibré ; ou
2. utiliser plusieurs NIC par PE.

Offrir l'option 2 uniquement quand la version résolue et le transport la supportent selon la matrice. Expliquer si multi-NIC nécessite l'affectation de distance automatique ou supporte une cartographie BLOCK explicite. Si l'utilisateur ne répond pas, montrer les deux alternatives supportées comme recommandations conditionnelles et ne pas choisir silencieusement.

Si l'utilisateur a demandé d'utiliser tous les NIC mais la version/transport résolue ne supporte pas multi-NIC, expliquer la restriction et demander approbation pour utiliser le sous-ensemble rapproché. Ne pas traiter la demande non supportée comme approbation implicite pour un sous-ensemble, et ne pas émettre les exports finaux jusqu'à confirmation de l'utilisateur. Quand seul le sous-ensemble est supporté, présenter ce choix unique supporté pour confirmation au lieu d'offrir une option multi-NIC désactivée.

7. Synthétiser Exactement Un Mécanisme de Sélection

Préférer NVSHMEM_HCA_PE_MAPPING pour les affectations exactes. Utiliser NVSHMEM_HCA_LIST uniquement quand sélectionner un ensemble éligible et accepter l'ordre canonique du transport. Ne jamais définir les deux variables.

Appliquer exactement les règles version/transport de la matrice :

• Pour 3.7 et antérieur, préserver un slot de cartographie étendu par PE pour les cartographies IB explicites. Utiliser l'affectation de distance automatique pour les chemins multi-NIC supportés.
• Pour 3.8 ou ultérieur, appliquer le contrat BLOCK fourni : définir NVSHMEM_ENABLE_NIC_PE_MAPPING=1 pour les affectations explicites et NVSHMEM_ENABLE_MULTI_PORT=1 chaque fois que recommander plus d'un NIC par PE.
• Pour UCX et libfabric, expliquer la limite contrôlée par le fournisseur et ne pas fabriquer les cartographies HCA communes exacts.

Construire NVSHMEM_HCA_PE_MAPPING avec des entrées hca:port:count explicites. Développer chaque nombre avant d'expliquer quels slots chaque PE reçoit. Préserver les doublons quand le partage intentionnel est requis.

Garder un bloc d'export de cartographie uniquement limité aux contrôles d'affectation NIC. Ne pas ajouter NVSHMEM_REMOTE_TRANSPORT ou les paramètres de fournisseur/lanceur simplement parce que le transport est connu ; les inclure uniquement quand l'utilisateur demande séparément de sélectionner le transport et la matrice, ou documentation quand requise, vérifie la valeur.

8. Retourner la Recommandation

Exécuter le Contrat de Sortie dans l'ordre ; cette référence est l'autorité unique pour les champs de sortie, le formatage, les messages retenus et les conseils de validation.

Traiter ses sections Mapping et Exact Exports comme des portes obligatoires. Ne pas retourner jusqu'à ce que chaque porte soit soit complétée soit explicitement retenue pour la raison autorisée par le contrat. Ne pas dupliquer ou paraphraser le contrat dans ce fichier.

Exemples

• « Mes 4 PE locaux sont liés aux GPUs 0–3. Étant donné cette sortie de collecteur de nœud cible et NVSHMEM 3.8.0 IBRC, recommander la cartographie de port InfiniBand rapproché équilibré exact et les exports exacts. »
• « Interpréter ce nvidia-smi topo -m et la sortie d'état/couche de liaison par port. NVSHMEM est 3.7 avec IBGDA ; identifier si plusieurs NIC par PE sont supportés et quelle preuve supplémentaire est requise avant d'émettre les exports. »
• « Nous avons 2 PE et 5 ports Ethernet/RoCE actifs. Utiliser cette liaison PE-to-GPU et le journal d'initialisation pour montrer le sous-ensemble supporté et les alternatives multi-NIC sans en sélectionner une silencieusement. »

Dépannage

Limitations

• Limiter les recommandations à la topologie de nœud cible observée et l'état du port ; répéter la collecte de preuves après des changements de matériel, tissu, lanceur ou liaison.
• Traiter la proximité de topologie comme une heuristique de sélection, pas une garantie de performance ; valider avec une charge de travail représentative.
• Ne pas produire une cartographie exacte jusqu'à ce que la version NVSHMEM, le transport, la liaison PE-to-GPU locale et la preuve de port utilisable soient résolus.
• Pour UCX et libfabric, rester dans la limite contrôlée par le fournisseur et ne pas fabriquer les paramètres de cartographie HCA communes.

Garde-fous

• Ne pas sélectionner les ports inactifs ou mélanger silencieusement les couches de liaison.
• Ne pas supposer qu'un index GPU et NIC numériquement correspondant implique la proximité.
• Ne pas transformer une liaison PE-to-GPU inconnue en une cartographie tous-les-ports-par-PE.
• Ne pas émettre le comportement BLOCK 3.8 ou ultérieur pour 3.7 ou antérieur.
• Ne pas émettre les contrôles multi-port IBGDA hérités comme le contrôle principal 3.8 ou ultérieur.
• Ne pas générer les paramètres natifs du fournisseur UCX ou libfabric ; les expliquer sans inventer de valeurs.
• Ne pas écraser les fichiers utilisateur ou modifier le système lors de la collecte de preuves.

<!-- ci trigger -->