Le parcours de diagnostic en quatre décisions
Le but est de trouver la première couche qui échoue, pas d’essayer plusieurs installations à la suite. Conservez la commande lancée, le premier message d’erreur et le résultat de chaque contrôle. Si vous changez à la fois Python, le paquet PyTorch et la taille du batch, vous ne saurez plus quelle modification a résolu le problème.
Le script téléchargeable applique cette progression et produit un rapport technique limité. Il ne lance pas votre modèle et ne modifie pas votre installation. Utilisez-le dans le même environnement que votre projet, sinon vous contrôlerez un autre interpréteur que celui du programme en panne.
Faites défiler le tableau pour lire toutes les colonnes.| Contrôle | Si le contrôle échoue | Ce que sa réussite permet de faire |
|---|---|---|
| 1. Interpréteur et import | Corriger le Python utilisé ou son installation de PyTorch. | Lire la version et le backend du paquet réellement importé. |
| 2. Backend et périphérique | Examiner le paquet, le pilote, l’exposition du GPU et les droits. | Demander une allocation sur le GPU visé. |
| 3. Petit calcul GPU | Conserver l’erreur d’allocation, de calcul ou de synchronisation. | Passer à une entrée réduite de l’application. |
| 4. Application représentative | Isoler poids, extension, format, mémoire ou sortie incorrecte. | Augmenter progressivement le travail réel. |
1. Identifier le Python réellement exécuté
Un terminal, un notebook et un service peuvent utiliser des interpréteurs différents. Affichez sys.executable dans le contexte qui lance le projet, puis contrôlez la version. Le chemin permet de repérer un environnement virtuel oublié ou un notebook resté sur un autre noyau. Examinez-le sur votre machine ; il n’est pas nécessaire de publier votre arborescence personnelle dans un rapport.
Utilisez ensuite ce même interpréteur pour interroger les paquets. La commande python -m pip show torch donne les informations de PyTorch associé à ce Python. Si import torch échoue, l’étape suivante consiste à corriger cette installation : réduire le batch ou changer les poids du modèle ne résoudra pas un module absent.
python -c "import sys; print(sys.executable); print(sys.version)"
python -m pip show torch2. Distinguer CUDA, ROCm et un paquet sans accélération GPU
Relevez séparément torch.__version__, torch.version.cuda et torch.version.hip. Ne concluez pas « paquet CPU » à partir de la seule valeur None de torch.version.cuda : PyTorch pour ROCm utilise HIP, réemploie torch.cuda et attend également un périphérique nommé cuda. Remplacer ce nom par rocm ou hip n’est pas la correction à appliquer.
Vérifiez ensuite torch.cuda.is_available() et torch.cuda.device_count(). Ces résultats décrivent ce que cet environnement Python peut utiliser à ce moment. Ils ne remplacent pas le calcul minimal. Un outil système peut voir une carte alors que le paquet, le pilote accessible au processus ou son environnement empêchent PyTorch de l’utiliser.
python -c "import torch; print(torch.__version__); print(torch.version.cuda); print(torch.version.hip); print(torch.cuda.is_available()); print(torch.cuda.device_count())"3. Produire le rapport avec le script Kernodeck
Après avoir téléchargé le fichier, placez-le dans un dossier de travail et lancez-le avec le Python du projet. Par défaut, il exige un GPU. Le mode CPU doit être demandé explicitement : son succès vérifie la branche CPU du diagnostic et ne transforme jamais un GPU indisponible en GPU validé. Le rapport est écrit dans le terminal et, avec --output, dans un nouveau fichier JSON. Un fichier existant n’est jamais écrasé : choisissez un autre nom pour votre prochain essai.
Le script alloue deux matrices 2 × 2 en float32, vérifie leur produit puis un gradient et synchronise le périphérique GPU. La perte attendue vaut 196 pour ce calcul fixe. Ce contrôle très court ne charge aucun poids de modèle et ne mesure aucun débit. Il demande un petit calcul réel au backend, au-delà d’une simple détection de périphérique.
Le contrôle système facultatif utilise nvidia-smi lorsqu’il est présent. Il rapporte uniquement la version du pilote NVIDIA et la mémoire totale visible par cet outil ; il ne constitue pas un contrôle système équivalent pour ROCm. Le délai du calcul vaut 30 secondes par défaut et peut aller de 5 à 120 secondes. Le contrôle système a son propre délai maximal de 3 secondes.
python kernodeck-diagnostic-v1.py --device-index 0 --timeout 30 --output diagnostic-gpu.jsonpython kernodeck-diagnostic-v1.py --device cpu --output diagnostic-cpu.jsonpython kernodeck-diagnostic-v1.py --host-check --output diagnostic-gpu-systeme.json4. Lire le rapport et choisir la prochaine action
Commencez par status, code, exit_code et stage. Le bloc runtime identifie la version Python et la famille du système. Le bloc pytorch distingue le paquet importé, ses versions de compilation CUDA/HIP, le backend déclaré et les périphériques visibles. Le bloc execution indique où le calcul a réellement eu lieu et si le produit ainsi que le gradient ont été vérifiés.
En mode CPU, gpu_available et visible_device_count restent à null : le script ne demande pas l’état du pilote GPU. Ce n’est ni un zéro ni une panne. Lisez aussi execution.device : un paquet compilé pour CUDA peut très bien exécuter ce contrôle sur CPU lorsqu’on le demande explicitement.
Le rapport contient une sélection de données techniques. Il n’inclut pas les variables d’environnement, les chemins du poste, les identifiants de session, une liste complète des paquets ou la trace brute d’une exception. Le script n’envoie aucun rapport à Kernodeck. Pour une erreur détaillée de votre application, conservez sa trace dans votre espace de travail et retirez les secrets avant de la partager.
Faites défiler le tableau pour lire toutes les colonnes.| Résultat | Sens | Action suivante |
|---|---|---|
| GPU_CHECK_PASSED · 0 | Produit et gradient vérifiés sur le GPU choisi. | Passer à une petite entrée de votre application. |
| CPU_CHECK_PASSED · 0 | Produit et gradient vérifiés sur CPU seulement. | Ne pas conclure sur CUDA ou ROCm. |
| TORCH_MISSING · 3 / TORCH_IMPORT_FAILED · 4 | PyTorch absent de ce Python, ou import en échec. | Vérifier l’interpréteur, le paquet et ses dépendances. |
| GPU_BACKEND_ABSENT · 5 | Le paquet ne déclare ni CUDA ni HIP. | Installer le paquet adapté à votre environnement. |
| GPU_UNAVAILABLE · 6 / DEVICE_INDEX_INVALID · 7 | GPU inutilisable dans ce processus, ou index hors des périphériques visibles. | Vérifier l’exposition des cartes, le pilote et l’index demandé. |
| CHECK_FAILED · 8 / OUT_OF_MEMORY ou RUNTIME_ERROR · 9 | Échec du calcul fixe, de l’allocation ou d’une opération du backend. | Lire l’étape signalée avant de lancer le modèle complet. |
| TIMEOUT · 10 / WORKER_FAILED · 11 | Contrôle arrêté par le délai, ou sans rapport exploitable. | Traiter le contrôle comme un échec ; examiner l’environnement. |
| OUTPUT_WRITE_FAILED · 12 | Le rapport n’a pas été enregistré à la destination demandée. | Utiliser un nouveau nom de fichier accessible. |
5. Passer du petit calcul à votre application
Avant le lancement, disposez d’une commande reproductible, d’un modèle identifié, d’un petit jeu de données et d’un répertoire de sortie accessible. Choisissez une entrée qui conserve les caractéristiques importantes du travail final : longueur de texte, dimensions d’image, format audio ou champs obligatoires. Une entrée artificiellement courte peut masquer le problème que vous cherchez à observer.
Écrivez un critère de réussite concret. Pour un calcul d’embeddings, chaque identifiant d’entrée doit retrouver un vecteur de la dimension attendue, avec des valeurs finies. Pour un entraînement, une étape doit produire une perte exploitable, mettre à jour les paramètres prévus et permettre une sauvegarde. Le code de sortie du processus complète ces contrôles ; il ne les remplace pas.
Ajoutez des marqueurs avant et après la lecture des paramètres, l’import des bibliothèques, le chargement des poids, la préparation des données, leur transfert, le calcul et l’écriture. Donnez à chaque essai un identifiant et conservez les paramètres associés. Un message « modèle chargé » doit correspondre à un événement terminé, pas simplement à une intention de chargement.
Journalisez les formes, types et périphériques des tenseurs utiles sans recopier tout le jeu de données. Un résumé comme « entrée : 8 séquences, longueur maximale 512, périphérique cuda:0 » aide à comparer deux essais. Ces nombres décrivent ici un exemple de journal, pas une configuration universelle. Évitez de placer des jetons d’accès ou le contenu sensible des entrées dans ces messages.
6. Corriger l’erreur de la bonne couche
Si le petit calcul passe mais que les poids sont introuvables, contrôlez leur chemin, leur format et les droits d’accès. Si une extension échoue à l’import, vérifiez sa compatibilité avec le paquet PyTorch et le backend du projet. Un diagnostic réussi ne qualifie pas toutes les extensions de l’application. Reprenez la première étape qui échoue au lieu de changer plusieurs dépendances à la fois.
Une erreur de périphérique peut venir d’une entrée restée sur le CPU alors que le modèle est sur le GPU. Une erreur de type peut venir d’une conversion partielle ou d’un opérateur incompatible avec la précision choisie. Conservez le premier message complet et sa trace. Modifiez une seule hypothèse à la fois, puis relancez l’entrée minimale avant de réintroduire le volume final.
7. Si le modèle démarre puis dépasse la mémoire
Repérez si le dépassement survient au chargement des poids, au premier calcul ou après plusieurs itérations. Ces moments orientent vers des causes différentes : modèle trop volumineux, activations ou cache de génération importants, accumulation de tenseurs conservés. Relevez torch.cuda.memory_allocated() et torch.cuda.memory_reserved() aux mêmes étapes. Le premier suit les allocations des tenseurs ; le second couvre la mémoire gérée par l’allocateur.
torch.cuda.empty_cache() peut rendre du cache inutilisé, mais ne supprime pas les tenseurs encore référencés. Inspectez donc les listes de sorties, les historiques de pertes et les objets gardant un graphe de calcul. Diminuez ensuite le batch ou la longueur d’entrée pour isoler le facteur déterminant. Changer de carte devient une décision informée lorsque vous connaissez la phase qui dépasse et la marge réellement nécessaire.
8. Mesurer le calcul sans oublier l’asynchronisme
Les opérations GPU peuvent être asynchrones par rapport au programme Python. Un chronomètre placé autour d’un appel peut donc mesurer surtout l’envoi du travail. Pour une mesure de diagnostic, synchronisez le GPU aux limites du segment observé, ou utilisez des événements adaptés. Cette synchronisation modifie le déroulement : gardez cette instrumentation distincte du fonctionnement normal de votre application.
Construisez un exemple simple avec trois segments : préparation de l’entrée, calcul, écriture de la sortie. Pour le segment GPU, appelez torch.cuda.synchronize(), relevez time.perf_counter(), exécutez le calcul, synchronisez de nouveau, puis calculez la différence. Conservez séparément le premier passage et les suivants. Un chargement ou une initialisation ne doit pas disparaître dans une moyenne présentée comme le temps de réponse complet.
9. Contrôler les sorties et conserver un diagnostic réutilisable
Pour une inférence classique, model.eval() règle le comportement des modules concernés, tandis que torch.inference_mode() désactive le suivi nécessaire aux gradients. Ces deux réglages ont des fonctions différentes. Utilisez le second lorsque les tenseurs produits ne doivent pas participer ensuite à un calcul avec gradients. Une évaluation de modèle pendant l’entraînement demande de remettre explicitement le bon mode avant la reprise.
Comparez maintenant les sorties au contrat préparé : nombre de résultats, correspondance des identifiants, dimensions, valeurs finies et métrique métier appropriée. Si vous augmentez le batch, vérifiez encore cette correspondance. Si vous ajoutez des GPU, contrôlez la répartition des entrées et la collecte des sorties. Les lots de location désignent des cartes commandées ; le batch désigne des exemples traités ensemble par votre programme.
Le résultat de cette méthode est un petit dossier : commande, versions, paramètres, entrée minimale, dernière étape réussie, première erreur, observations de mémoire et sortie obtenue. Si le lancement fonctionne, conservez ce dossier comme point de comparaison avant d’augmenter la charge. Si le lancement échoue, il permet de reproduire le problème sans recommencer toute l’enquête.
Avant un traitement long, effectuez aussi un arrêt propre et une reprise sur ce petit jeu d’entrées. Vérifiez que les sorties déjà écrites ne sont ni perdues ni comptées deux fois. Une fois ces contrôles passés, augmentez progressivement un seul axe — batch, longueur, concurrence ou nombre de processus — et consignez la limite observée. Vous obtenez une plage de fonctionnement mesurée pour votre application, plutôt qu’une supposition liée au nom du GPU.
La preuve fournie et ses limites
Les exemples téléchargeables proviennent de contrôles réels effectués le 24 septembre 2026. Les deux exécutions avec PyTorch utilisent Windows, Python 3.14.6 et PyTorch 2.11.0+cu128. Le contrôle GPU emploie CUDA, sur une NVIDIA GeForce RTX 5070 ; le contrôle CPU demande explicitement le CPU. Ce matériel de contrôle n’est pas présenté comme une offre Kernodeck. Aucun calcul ROCm n’a été exécuté pour cette preuve.
Un petit calcul réussi montre qu’un chemin d’allocation et de calcul fonctionne sur le périphérique choisi. Il ne mesure ni la vitesse de votre modèle, ni la mémoire nécessaire à ses plus grandes entrées, ni sa compatibilité avec une extension particulière. Le rapport ne certifie pas non plus une topologie multicarte. Passez à l’essai représentatif avant de décider d’augmenter la charge ou la location.
Pour une application CUDA, comparez une fiche NVIDIA à vos besoins de mémoire et de bibliothèque ; pour une chaîne ROCm, examinez les conditions du MI300X. Les fiches liées sont des options à qualifier pour votre projet, pas la liste du matériel utilisé dans la preuve. Gardez le temps de contrôle initial et d’export dans votre période de 3, 7 ou 30 jours.
Faites défiler le tableau pour lire toutes les colonnes.| Contrôle réel | Résultat observé | Portée |
|---|---|---|
| CPU explicite · Python 3.14.6 / PyTorch 2.11.0+cu128 | CPU_CHECK_PASSED ; produit et gradient exacts ; perte 196. | Le calcul fixe fonctionne sur CPU. |
| CUDA · RTX 5070 / paquet CUDA 12.8 | GPU_CHECK_PASSED ; produit et gradient exacts ; perte 196. | Le calcul fixe fonctionne sur cette carte dans cet environnement. |
| PyTorch absent · Python 3.12.14 | TORCH_MISSING ; code de sortie 3. | L’absence du module produit un échec explicite. |
| GPU rendu invisible au processus de contrôle | GPU_UNAVAILABLE ; code de sortie 6. | Le script ne remplace pas silencieusement le GPU par le CPU. |