Analyse Nsight Compute

NVIDIA Nsight Compute (ncu) profile les kernels CUDA individuels pour déterminer pourquoi ils sont lents et quoi optimiser. Il mesure le débit GPU en pourcentage du pic théorique (Speed of Light / SOL%), permettant une classification systématique des goulots d'étranglement et une optimisation ciblée.

Quand utiliser

Utilisez cette compétence quand vous rencontrez :

• Déclencheurs : L'utilisateur veut profiler un kernel CUDA, analyser une sortie ncu, interpréter des rapports .ncu-rep, ou optimiser les performances des kernels GPU
• Symptômes : Kernel s'exécutant plus lentement que prévu, faible utilisation GPU, besoin de classer calcul-limité vs mémoire-limité, problèmes d'occupancy
• Mots-clés : "ncu", "nsight compute", "SOL%", "speed of light", "kernel profiling", "compute-bound", "memory-bound", "latency-bound", "occupancy", "roofline", "warp stalls", "cache hit rate", "ncu-rep"

N'utilisez PAS cette compétence pour :

• Profiling au niveau système (utilisez Nsight Systems / nsys à la place)
• Traçage API CUDA ou analyse chronologique CPU-GPU (utilisez nsys)
• Monitoring GPU sans profiling (utilisez nvidia-smi)

Prérequis

Permissions : ncu peut nécessiter sudo, CAP_SYS_ADMIN, ou --privileged dans les conteneurs. Vérifiez avec ncu -v d'abord.

Principes

Intégrité des données

C'est un système d'analyse basé sur les données. Chaque nombre que vous présentez doit avoir une source faisant autorité. Suivez ces règles sans exception :

1. Citez avant d'interpréter. Quand vous présentez des métriques de la sortie ncu, montrez toujours la commande ncu réelle que vous avez exécutée ET la sortie brute pertinente (lignes CSV, valeurs de métriques) avant de formuler une conclusion numérique.
2. Ne jamais inventer de métriques. Si ncu échoue, retourne une sortie inattendue, ou vous ne pouvez pas l'exécuter, dites-le explicitement. N'inventez pas de nombres plausibles. Un honnête "le profiling a échoué" vaut mieux que des données inventées.
3. Attribuez chaque valeur. Pour chaque métrique que vous citez (SOL%, durée, occupancy, débit), le lecteur doit pouvoir la retracer jusqu'à une ligne spécifique dans la sortie brute ncu que vous avez montré.

Modèle mental SOL%

Speed of Light (SOL%) mesure à quel point un kernel s'exécute près du pic théorique du GPU :

• Compute SOL% = débit de calcul réel / débit de calcul pic
• Memory SOL% = débit mémoire réel / débit mémoire pic

Un kernel ne peut pas saturer les deux simultanément. La métrique plus élevée révèle le type de goulot d'étranglement. Utilisez ceci comme signal de classification principal.

Seuils de classification

Signaux supplémentaires :

• Durée <10us avec plusieurs lancements -> Limité par surcharge de lancement (utilisez nsys d'abord)
• Les deux <40% mais occupancy >50% -> Limité par instruction (vérifiez InstructionStats)

Niveaux de performance SOL%

Profiling d'abord par section

Utilisez toujours les drapeaux --section ciblés plutôt que la collecte en masse --set. Les sections individuelles sont plus rapides et plus précises. Escaladez seulement vers --set basic ou --set detailed quand une exploration large est nécessaire.

ncu vs nsys

Utilisez nsys d'abord pour identifier les top kernels par temps GPU, puis ncu pour une analyse profonde de ces kernels spécifiques.

Flux de travail

Choisissez votre chemin selon la demande :

• Requête de connaissance (quelles métriques utiliser, --section vs --set, comment filtrer les kernels) : Répondez directement à partir des Principes, Référence de commande, et Références ci-dessous. N'exécutez PAS ncu.
• Diagnostic rapide (classer le goulot d'étranglement, vérifier SOL%) : Étape 1 seulement. Escaladez si l'utilisateur veut plus.
• Diagnostic spécifique (conflits de banque, pression de registre, occupancy) : Vérification rapide SOL% (Étape 1), puis aller directement à la section pertinente de l'Étape 2.
• Analyse profonde (rapport détaillé, recommandations d'optimisation) : Étapes complètes 1-5. Présentez le rapport structuré complet avec toutes les métriques clés (SOL%, durée, occupancy) dans votre réponse finale — ne divisez pas le rapport entre les messages ou ne le remplacez pas par un court résumé.

Étape 0 : Vérifier ncu

ncu -v
# Ou : $NCU -v

Si non trouvé, assurez-vous que le toolkit CUDA est installé ou définissez la variable d'environnement NCU au chemin du binaire.

Étape 1 : Diagnostic SOL%

Commencez toujours par SpeedOfLight pour classer le goulot d'étranglement :

ncu --section SpeedOfLight --csv \
    --kernel-name regex:"KERNEL" \
    --launch-skip 5 --launch-count 3 \
    -- COMMAND

Lisez Compute (SM) Throughput et Memory Throughput de la sortie. Classifiez en utilisant les seuils ci-dessus.

Étape 2 : Escalader avec sections ciblées

En fonction de la classification de l'Étape 1, ajoutez des sections :

Incluez toujours LaunchStats et Occupancy quand vous diagnostiquez des kernels latence-limités. Ceux-ci révèlent la pression de registre, les limites de mémoire partagée, et les problèmes de taille de bloc.

Exemple -- plongée profonde mémoire-limité :

ncu --section SpeedOfLight --section MemoryWorkloadAnalysis --csv \
    --kernel-name regex:"embedding_lookup" \
    --launch-count 3 \
    -- python script.py

Exemple -- plongée profonde calcul-limité :

ncu --section SpeedOfLight --section ComputeWorkloadAnalysis --csv \
    --kernel-name regex:"gemm" \
    --launch-count 3 -- python script.py

Exemple -- investigation occupancy :

ncu --section SpeedOfLight --section LaunchStats --section Occupancy --csv \
    --kernel-name regex:"small_kernel" \
    -- python script.py

Étape 3 : Analyse Roofline (Optionnel)

Pour une compréhension visuelle de l'équilibre calcul vs mémoire :

ncu --section SpeedOfLight_RooflineChart \
    --kernel-name regex:"KERNEL" -- COMMAND

Pour le roofline hiérarchique spécifique à la précision :

# Kernels FP16
ncu --section SpeedOfLight_HierarchicalHalfRooflineChart \
    --kernel-name regex:"KERNEL" -- COMMAND

# Kernels tensor core
ncu --section SpeedOfLight_HierarchicalTensorRooflineChart \
    --kernel-name regex:"KERNEL" -- COMMAND

Interprétation : kernel à gauche du point de crête = mémoire-limité ; à droite = calcul-limité ; bien en dessous des deux toits = problème latence/occupancy. Voir references/roofline-analysis.md.

Étape 4 : Interpréter et optimiser

1. Identifiez le goulot d'étranglement dominant à partir de la classification SOL%
2. Consultez l'analyse détaillée et les stratégies d'optimisation dans references/bottleneck-guide.md
3. Appliquez d'abord l'optimisation à plus fort impact
4. Re-profilez pour valider l'amélioration et détecter les changements de goulot d'étranglement

Étape 5 : Valider

Re-profilez le même kernel après optimisation :

ncu --section SpeedOfLight --csv \
    --kernel-name regex:"optimized_kernel" \
    --launch-count 3 \
    -- python optimized_script.py

Comparez : Le pourcentage de débit a-t-il augmenté ? La durée a-t-elle diminué ? Le type de goulot d'étranglement a-t-il changé ?

Profiling des kernels compilés à la volée (Triton/cuTile/CuTeDSL)

Les kernels compilés à la volée déclenchent l'autotuning à la première invocation. Isolez l'exécution réelle :

1. Préchauffez d'abord : Exécutez le kernel 3-5 fois pour terminer la compilation JIT et l'autotuning, puis torch.cuda.synchronize().
2. Utilisez les marqueurs du profileur : Encadrez la région mesurée avec cudaProfilerStart()/cudaProfilerStop().
3. Utilisez --profile-from-start off pour que ncu capture seulement la région marquée :

# Préchauffage (JIT + autotuning)
for _ in range(5):
    result = kernel(inputs)
torch.cuda.synchronize()

# Profiler seulement l'état stable
torch.cuda.cudart().cudaProfilerStart()
for _ in range(3):
    result = kernel(inputs)
    torch.cuda.synchronize()
torch.cuda.cudart().cudaProfilerStop()

ncu --profile-from-start off --section SpeedOfLight --csv \
    --kernel-name regex:"target_kernel" \
    --launch-count 3 -- python script.py

Alternative : utilisez --launch-skip N pour ignorer les lancements d'autotuning. Voir references/advanced-profiling.md pour les alternatives range NVTX et replay mode.

Analyse de rapport programmatique

Extrayez les métriques des fichiers .ncu-rep en utilisant le module Python ncu_report (dans extras/python/ de l'installation Nsight Compute) :

import ncu_report

ctx = ncu_report.load_report("report.ncu-rep")
for rng in ctx:
    for action in rng:
        name = action.name()
        compute = action["sm__throughput.avg.pct_of_peak_sustained_elapsed"].as_double()
        memory = action["dram__throughput.avg.pct_of_peak_sustained_elapsed"].as_double()
        duration = action["gpu__time_duration.sum"].as_uint64()

        if compute > 60:
            classification = "compute-bound"
        elif memory > 60:
            classification = "memory-bound"
        else:
            classification = "latency-bound"

        print(f"{name}: {classification} (compute={compute:.1f}%, mem={memory:.1f}%, {duration}ns)")

Voir references/python-report-api.md pour l'API complète (classes IContext, IRange, IAction, IMetric).

Formats de sortie

Sortie CSV (pour les scripts et l'analyse automatisée) :

ncu --csv --section SpeedOfLight --kernel-name regex:"KERNEL" -- COMMAND
ncu --csv --page raw --section SpeedOfLight -- COMMAND   # Toutes les métriques plates

Fichiers de rapport (pour analyse ultérieure) :

ncu -o report --section SpeedOfLight -- COMMAND
ncu --import report.ncu-rep --csv --page raw            # Exporter en CSV

Colonnes CSV clés :

Indicateurs de succès :

• Les valeurs SOL% présentes dans la sortie -> le profiling a réussi
• Les valeurs Duration raisonnables (pas 0 ou extrêmement grandes)
• Plusieurs lancements capturés quand --launch-count > 1

Exemples

Exemple : Classer un kernel GEMM

ncu --section SpeedOfLight --csv \
    --kernel-name regex:"gemm" \
    --launch-skip 5 --launch-count 3 \
    -- python train.py

Sortie :

"Kernel Name","Duration","Compute (SM) Throughput","Memory Throughput"
"ampere_fp16_gemm",1250000,78.5,35.2

Interprétation : calcul-limité (78.5% calcul, 35.2% mémoire). Étape suivante : vérifiez l'utilisation tensor core avec --section ComputeWorkloadAnalysis.

Exemple : Diagnostiquer un kernel embedding mémoire-limité

ncu --section SpeedOfLight --section MemoryWorkloadAnalysis --csv \
    --kernel-name regex:"embedding" \
    --launch-count 3 -- python train.py

Vérifiez les taux de hit cache L1/L2 et l'efficacité de coalescing dans la sortie. Les taux de hit bas suggèrent une mauvaise localité des données ; une faible efficacité de coalescing suggère un accès dispersé.

Gestion d'erreurs

Trouver plus d'informations

Niveau 1 : Ce fichier (SKILL.md)

Vous le lisez maintenant. Le flux de travail d'abord par section et le tableau d'erreurs ci-dessus couvrent les tâches de profiling les plus courantes. Consultez d'abord ce fichier.

Niveau 2 : Répertoire references/

Grep pour les mots-clés dans references/ -- les en-têtes sont grep-friendly :

• references/cli-reference.md -- Options CLI complètes, filtrage, formats de sortie
• references/metrics-guide.md -- Modèle matériel, nomination de métrique, métriques clés
• references/sections-guide.md -- Tous les noms --section, quand utiliser chacun
• references/bottleneck-guide.md -- Par goulot d'étranglement : causes racines et optimisation
• references/memory-analysis.md -- Hiérarchie mémoire, analyse de cache, coalescing
• references/roofline-analysis.md -- Graphiques roofline et interprétation
• references/advanced-profiling.md -- Replay modes, MPI, CUDA graphs, PM sampling, customisation
• references/python-report-api.md -- API du module Python ncu_report

Comment rechercher :

1. Grep pour votre mot-clé dans references/
2. Lisez seulement le fichier auquel Grep pointe

Niveau 3 : Documentation officielle

Si les niveaux 1-2 ne répondent pas :

• Profiling Guide -- Métriques, modèle matériel, concepts d'analyse
• CLI Reference -- Options CLI complètes
• Python Report Interface -- API ncu_report
• Customization Guide -- Fichiers de section, règles

WebFetch ou WebSearch ces URLs pour le contenu le plus récent. Envisagez de distiller les nouvelles découvertes dans references/.