# Diagnostic PyTorch Kernodeck — version 1.0.0

Ce script vérifie qu’un petit calcul PyTorch et son gradient s’exécutent sur le périphérique demandé. Il produit un rapport JSON limité à des champs techniques utiles. Par défaut, il exige un GPU ; un contrôle CPU doit être demandé explicitement.

Il ne lance aucun entraînement, ne mesure aucun débit et ne certifie ni une offre commerciale, ni une capacité d’entraînement, ni la stabilité d’une machine sur la durée. Son code original est fourni sous [licence MIT](kernodeck-diagnostic-v1-LICENSE.md).

## Préparer et lancer

Téléchargez [le script](kernodeck-diagnostic-v1.py), puis ouvrez un terminal dans son dossier. Utilisez le Python de votre environnement de travail, avec PyTorch déjà installé. Le script emploie la bibliothèque standard de Python 3.10 ou ultérieur ; les environnements réellement contrôlés sont détaillés plus bas. Aucune installation ou modification de pilote n’est effectuée.

```sh
python kernodeck-diagnostic-v1.py
```

Cette commande sélectionne le premier GPU visible par PyTorch. Elle échoue avec un code de sortie non nul si PyTorch, le backend GPU ou le périphérique utilisable manque. Elle ne se rabat pas sur CPU.

Pour vérifier uniquement le calcul sur CPU :

```sh
python kernodeck-diagnostic-v1.py --device cpu
```

Pour choisir un GPU visible et conserver un rapport dans un nouveau fichier :

```sh
python kernodeck-diagnostic-v1.py --device-index 0 --output diagnostic.json
```

Le chemin de sortie est choisi par vous et n’apparaît pas dans le rapport. Un fichier existant n’est jamais écrasé. Sans `--output`, le script ne crée aucun fichier. Vous pouvez lire le code de sortie avec `$LASTEXITCODE` dans PowerShell ou `echo $?` dans un shell POSIX.

Si l’import de PyTorch demande plus de temps, augmentez le délai, dans la limite prévue :

```sh
python kernodeck-diagnostic-v1.py --timeout 60
```

| Option publique | Valeur et effet |
| --- | --- |
| `--device gpu` | Valeur par défaut ; exige un GPU CUDA ou ROCm utilisable. |
| `--device cpu` | Calcul CPU explicite ; ne vérifie pas la visibilité du pilote GPU. |
| `--device-index N` | Index PyTorch visible, entre 0 et 63 ; défaut 0. Sans effet sur le calcul CPU. |
| `--timeout N` | Délai du sous-processus de calcul, entre 5 et 120 secondes ; défaut 30. |
| `--host-check` | Lecture NVIDIA facultative, limitée à 3 secondes supplémentaires. |
| `--output FICHIER` | Écrit aussi le JSON dans un nouveau fichier UTF-8. |
| `--help` | Affiche l’aide, sans importer PyTorch. |

Le téléchargement ne contient pas PyTorch, CUDA, ROCm ou leurs pilotes. Pour choisir une installation adaptée à votre système, partez du [sélecteur officiel PyTorch](https://docs.pytorch.org/get-started/locally/). Une installation valide sur une autre machine ne prouve pas la compatibilité de votre GPU.

## CUDA, ROCm et contrôle hôte

Le script examine `torch.version.hip` avant `torch.version.cuda`. Un paquet ROCm est identifié comme `rocm`, même si sa valeur CUDA est `null`. PyTorch utilise aussi `torch.cuda` et le nom de périphérique `cuda` sur ROCm : un rapport `execution.device: "cuda:0"` n’implique donc pas à lui seul une carte NVIDIA. Consultez aussi `execution.backend`. [Documentation HIP de PyTorch](https://docs.pytorch.org/docs/2.14/notes/hip.html)

`torch.cuda.is_available()` indique si CUDA est actuellement disponible pour PyTorch. Le script complète cette observation par un calcul, son gradient et une synchronisation du périphérique demandé. Il ne déduit pas qu’un modèle réel tiendra en mémoire. [Disponibilité](https://docs.pytorch.org/docs/2.14/generated/torch.cuda.is_available.html) · [Synchronisation](https://docs.pytorch.org/docs/2.14/generated/torch.cuda.synchronize.html)

Avec `--host-check`, une commande NVIDIA distincte demande seulement la version du pilote et la mémoire totale en MiB. Sa sortie doit respecter un format numérique strict. L’absence de `nvidia-smi`, un délai dépassé ou une sortie inconnue n’annule pas un calcul réussi. Cette lecture ne constitue pas un diagnostic hôte AMD et n’est pas nécessaire au contrôle CPU. Elle peut voir des cartes que le processus PyTorch ne voit pas ; la liste hôte n’est pas appariée aux index PyTorch. [Requêtes sélectives NVIDIA](https://docs.nvidia.com/deploy/nvidia-smi/index.html)

Für AMD müssen GPU-, System-, Treiber- und Bibliotheksversionen eine unterstützte Kombination bilden. Dieses Skript ersetzt nicht die [offizielle ROCm-Kompatibilitätsmatrix](https://rocm.docs.amd.com/en/latest/compatibility/compatibility-matrix.html).

## Das JSON lesen

Die Struktur ist für Version 1 stabil:

| Feld | Bedeutung |
| --- | --- |
| `schema`, `script_version` | Format und Version des Skripts. |
| `requested_device` | `gpu` oder `cpu`; `unspecified`, wenn die Argumente ungültig sind oder die Ausführung unterbrochen wurde. |
| `status`, `code`, `exit_code`, `message` | Gesamtergebnis, stabiler Code, Prozesscode und feste Erläuterung. |
| `stage` | Zuletzt erreichte Stufe: Import, Erkennung, Sichtbarkeit, Allokation, Berechnung, Gradient, Synchronisierung, Validierung usw. |
| `runtime` | Numerische Version des verwendeten Python und Systemfamilie; keine Maschinenkennung. |
| `pytorch` | Gefilterte Paketversion, Kompilierungsversionen von CUDA/HIP, deklariertes Backend und GPU-Sichtbarkeit, sofern abgefragt. `null`, wenn PyTorch nicht importiert werden konnte. |
| `execution` | Tatsächlich ausgewähltes Gerät, gefiltertes GPU-Modell, von PyTorch gemeldeter Gesamtspeicher, Typ, Form der Matrizen und Ergebnis der Prüfungen. `null`, wenn die Berechnung nicht vorbereitet wurde. |
| `host_check` | Nur auf Anfrage vorhanden: Status der NVIDIA-Auslesung und zwei numerische Felder pro Karte. |

Im CPU-Modus kann `pytorch.backend` gleich `cuda` sein, weil es das installierte Paket beschreibt. `execution.backend` bleibt `cpu` und beschreibt die ausgeführte Berechnung. Die GPU-Verfügbarkeit, die Anzahl der GPUs, das Modell und der GPU-Speicher sind dann `null`: Sie wurden nicht gemessen.

Die Prüfung multipliziert zwei 2×2-Matrizen in `float32`, prüft das Produkt `[[4, 4], [10, 8]]` und dann den Gradienten `[[16, 24], [40, 52]]`. Die erwartete Summe der Quadrate beträgt `196.0`. Diese kleinen ganzen Zahlen ermöglichen hier einen exakten Vergleich; diese Eigenschaft verspricht jedoch nicht die Bit-für-Bit-Reproduzierbarkeit eines beliebigen Modells. Die Prüfung verwendet [`torch.equal`](https://docs.pytorch.org/docs/2.14/generated/torch.equal.html). Das Erstellen eines GPU-Kontexts kann mehr Speicher verbrauchen als die Matrizen allein.

`total_memory_bytes` ist eine gemeldete Kapazität, nicht der freie oder für Ihr künftiges Modell nutzbare Speicher. Das Skript misst weder den maximalen Speicher eines Trainings noch die Interkonnektivität, die Geschwindigkeit oder Multi-GPU.

## Einen Fehler verstehen

| Ausgabe | JSON-Code | Lesart und nächste Prüfung |
| --- | --- | --- |
| 0 | `CPU_CHECK_PASSED` / `GPU_CHECK_PASSED` | Die kleine Berechnung und ihr Gradient sind auf dem angegebenen Gerät korrekt. |
| 2 | `CLI_ARGUMENTS_INVALID` | Lesen Sie `--help` erneut; der ungültige Wert wird nicht wiedergegeben. |
| 3 | `TORCH_MISSING` | PyTorch fehlt in diesem Python. Prüfen Sie, ob Sie die richtige Umgebung gewählt haben. |
| 4 | `TORCH_IMPORT_FAILED` | PyTorch ist vorhanden, aber der Import schlägt fehl; prüfen Sie das Paket und seine Abhängigkeiten. |
| 5 | `GPU_BACKEND_ABSENT` | Das Paket deklariert weder CUDA noch HIP. Wählen Sie eine passende Distribution oder fordern Sie ausdrücklich CPU an. |
| 6 | `GPU_UNAVAILABLE` | Das Paket deklariert ein GPU-Backend, aber in diesem Prozess ist keine nutzbare GPU sichtbar. Prüfen Sie den Gerätezugriff und die Kompatibilität der Umgebung. |
| 7 | `DEVICE_INDEX_INVALID` | Der angeforderte Index ist nicht in der von PyTorch sichtbaren Liste vorhanden. |
| 8 | `CHECK_FAILED` | Die Berechnung oder der Gradient weicht vom festen erwarteten Ergebnis ab. |
| 9 | `OUT_OF_MEMORY` / `RUNTIME_ERROR` | Allokation nicht möglich oder Backend-Fehler; `stage` gibt die Stufe an, ohne die rohe Ausnahme auszugeben. |
| 10 | `TIMEOUT` | Der Unterprozess hat die Frist überschritten und wurde beendet. |
| 11 | `WORKER_FAILED` | Der Unterprozess hat keinen gültigen Bericht geliefert. |
| 12 | `OUTPUT_WRITE_FAILED` | Die Datei existiert bereits oder ist nicht zugänglich; wählen Sie einen neuen Namen. Der Gesamtstatus schlägt fehl, selbst wenn die vorherige Berechnung erfolgreich war. |
| 130 | `INTERRUPTED` | Die Prüfung wurde unterbrochen. |

Übermitteln Sie keinen vollständigen Dump Ihrer Umgebung, um einen Fehler zu erklären. Der Code und die Stufe des Berichts sind eine erste Feststellung; wenn eine genauere Untersuchung erforderlich ist, prüfen Sie sie in Ihrer Umgebung, bevor Sie Daten teilen.

## Daten und Grenzen

Das Skript führt keine Netzwerkanfragen aus und überträgt nichts an Kernodeck. Es liest weder Ihre Notebooks, Datensätze, Konten, Zahlungen noch Checkpoints. Es erfasst keine Umgebungsvariablen, Paketlisten, Hostnamen, Benutzernamen, persönlichen Pfade, Seriennummern, UUIDs, GPU-Prozesse oder Tokens.

Die Python-Version, die Betriebssystemfamilie, die technischen Versionen, das gefilterte GPU-Modell und die Speicherkapazität können einen Teil Ihrer Hardwareumgebung preisgeben. Prüfen Sie den Bericht, bevor Sie ihn weitergeben. Die Rohmeldungen von PyTorch und dem Treiber werden nicht übernommen; eine nicht erkannte Version oder ein nicht erkanntes Modell wird zu einem neutralen Wert. Der Bericht kann daher eine legitime Bezeichnung auslassen.

Das Timeout begrenzt den Kontroll-Subprozess, nicht den Betrieb des Systems oder des Treibers. Das Skript repariert keine Umgebung, validiert keinen spezialisierten Kernel und ersetzt keinen Test Ihrer Arbeitslast. Es wurde keine bösartige oder veränderte Drittanbieter-Software bewertet.

## Tatsächlich durchgeführte Kontrollen am 24. September 2026

Die folgenden Beispiele sind die minimierten Berichte, die das Skript tatsächlich erzeugt hat, ohne Rohausnahmen oder Maschinenkennung. Sie betreffen die Kontrollumgebung und beschreiben kein Angebot aus dem Katalog von Kernodeck.

| Ausgeführter Fall | Umgebung | Ergebnis |
| --- | --- | --- |
| Explizite CPU | Windows, Python 3.14.6, PyTorch 2.11.0+cu128 | Produkt und Gradient verifiziert; Verlust `196.0`. [JSON CPU](kernodeck-diagnostic-v1-cpu-example.json) |
| Standard-GPU | Dieselbe Umgebung, CUDA-Kompilierung 12.8, NVIDIA GeForce RTX 5070 | Produkt und Gradient auf `cuda:0` verifiziert; Verlust `196.0`. [JSON CUDA](kernodeck-diagnostic-v1-cuda-example.json) |
| PyTorch fehlt | Windows, Python 3.12.14, ohne PyTorch | `TORCH_MISSING`, Exit-Code 3. [JSON des Fehlschlags](kernodeck-diagnostic-v1-torch-absent-example.json) |
| GPU nur für den Testprozess unsichtbar gemacht | Python 3.14.6 und obiges CUDA-Paket | `GPU_UNAVAILABLE`, Exit-Code 6. |
| Index fehlt, ungültige Argumente, vorhandene Datei | Getrennte Kontrollprozesse | Exit-Codes 7, 2 und 12; vorhandene Datei beibehalten. |

Die Testsuite umfasst 44 Kontrollen und kombiniert diese realen Ausführungen mit isolierten Unit-Tests. Die Unit-Tests decken unter anderem ein Paket ohne GPU-Backend, die HIP-Erkennung, einen Backend-Fehler, ein überschrittenes Timeout und die Feldfilterung ab. Sie stellen keine Hardware-Ausführungen mit ROCm dar. **In dieser Testsuite wurde keine AMD/ROCm-GPU ausgeführt.** NumPy 2.4.4 war in der Kontrollumgebung importierbar, aber das Skript importiert es nicht direkt.

Die [konsultierten Quellen und ihre Rolle](kernodeck-diagnostic-v1-SOURCES.md) unterscheiden zwischen Dokumentationsversionen und den tatsächlich verwendeten Versionen. Das [SHA-256-Manifest](kernodeck-diagnostic-v1-manifest.json) beschreibt die Dateien dieser Lieferung. Die Fingerabdrücke erkennen eine Dateiabweichung; sie sind keine Signatur eines Urhebers.


## Kernodeck-Präsentation und Kompatibilität der Berichte

Die Präsentation, der Dateiname und die Befehlszeilenhilfe tragen seit dem 25. September 2026 die Marke Kernodeck. Die technischen Kennungen des JSON-Schemas bleiben für bestehende Leser stabil. Die drei obigen Beispielberichte werden bytegenau als Ergebnisse der Ausführung vom 24. September 2026 beibehalten. Ihr Vorhandensein stellt keine erneute Ausführung dieser Präsentation dar. Das Manifest unterscheidet diese Neuauflage von den historischen Kontrollen.