# 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)

Dla AMD wersja GPU, systemu, sterownika i bibliotek muszą tworzyć obsługiwaną kombinację. Ten skrypt nie zastępuje [oficjalnej matrycy kompatybilności ROCm](https://rocm.docs.amd.com/en/latest/compatibility/compatibility-matrix.html).

## Odczyt JSON

Struktura jest stabilna dla wersji 1:

| Pole | Znaczenie |
| --- | --- |
| `schema`, `script_version` | Format i wersja skryptu. |
| `requested_device` | `gpu` lub `cpu`; `unspecified`, jeśli argumenty są nieprawidłowe lub wykonanie zostało przerwane. |
| `status`, `code`, `exit_code`, `message` | Wynik globalny, stabilny kod, kod procesu i stałe wyjaśnienie. |
| `stage` | Ostatni osiągnięty etap: import, detekcja, widoczność, alokacja, obliczenia, gradient, synchronizacja, walidacja itd. |
| `runtime` | Numeryczna wersja używanego Pythona i rodzina systemu; żaden identyfikator maszyny. |
| `pytorch` | Przefiltrowana wersja pakietu, wersje kompilacji CUDA/HIP, zadeklarowany backend i widoczność GPU, gdy została sprawdzona. `null`, jeśli nie udało się zaimportować PyTorch. |
| `execution` | Faktycznie wybrane urządzenie, przefiltrowany model GPU, całkowita pamięć raportowana przez PyTorch, typ, kształt macierzy i wynik weryfikacji. `null`, jeśli obliczenia nie zostały przygotowane. |
| `host_check` | Obecne tylko na żądanie: stan odczytu NVIDIA i dwa pola numeryczne na kartę. |

W trybie CPU `pytorch.backend` może mieć wartość `cuda`, ponieważ opisuje zainstalowany pakiet. `execution.backend` pozostaje `cpu` i opisuje wykonane obliczenia. Dostępność GPU, liczba GPU, model i pamięć GPU są wtedy `null`: nie zostały zmierzone.

Kontrola mnoży dwie macierze 2×2 w `float32`, sprawdza iloczyn `[[4, 4], [10, 8]]`, a następnie gradient `[[16, 24], [40, 52]]`. Oczekiwana suma kwadratów wynosi `196.0`. Te małe liczby całkowite pozwalają tutaj na dokładne porównanie; ta właściwość nie gwarantuje reprodukowalności bit w bit dowolnego modelu. Weryfikacja używa [`torch.equal`](https://docs.pytorch.org/docs/2.14/generated/torch.equal.html). Utworzenie kontekstu GPU może zużyć więcej pamięci niż same macierze.

`total_memory_bytes` to raportowana pojemność, a nie pamięć wolna lub dostępna dla Twojego przyszłego modelu. Skrypt nie mierzy ani maksymalnej pamięci treningu, ani połączeń międzykartowych, ani szybkości, ani wielu GPU.

## Zrozumienie niepowodzenia

| Wyjście | Kod JSON | Odczyt i następne sprawdzenie |
| --- | --- | --- |
| 0 | `CPU_CHECK_PASSED` / `GPU_CHECK_PASSED` | Małe obliczenie i jego gradient są poprawne na wskazanym urządzeniu. |
| 2 | `CLI_ARGUMENTS_INVALID` | Przeczytaj ponownie `--help`; nieprawidłowa wartość nie jest kopiowana. |
| 3 | `TORCH_MISSING` | Brak PyTorch w tym Pythonie. Sprawdź, czy wybrałeś właściwe środowisko. |
| 4 | `TORCH_IMPORT_FAILED` | PyTorch istnieje, ale jego import kończy się niepowodzeniem; sprawdź pakiet i jego zależności. |
| 5 | `GPU_BACKEND_ABSENT` | Pakiet nie deklaruje ani CUDA, ani HIP. Wybierz odpowiednią dystrybucję lub zażądaj jawnie CPU. |
| 6 | `GPU_UNAVAILABLE` | Pakiet deklaruje backend GPU, ale w tym procesie nie jest widoczny żaden użyteczny GPU. Sprawdź dostęp do urządzenia i zgodność środowiska. |
| 7 | `DEVICE_INDEX_INVALID` | Żądany indeks nie występuje na liście widocznej dla PyTorch. |
| 8 | `CHECK_FAILED` | Obliczenie lub gradient różni się od stałego oczekiwanego wyniku. |
| 9 | `OUT_OF_MEMORY` / `RUNTIME_ERROR` | Alokacja niemożliwa lub błąd backendu; `stage` wskazuje etap, bez eksportowania surowego wyjątku. |
| 10 | `TIMEOUT` | Podproces przekroczył limit czasu i został zatrzymany. |
| 11 | `WORKER_FAILED` | Podproces nie dostarczył prawidłowego raportu. |
| 12 | `OUTPUT_WRITE_FAILED` | Plik już istnieje lub nie jest dostępny; wybierz nową nazwę. Status globalny kończy się niepowodzeniem, nawet jeśli poprzednie obliczenie się powiodło. |
| 130 | `INTERRUPTED` | Kontrola została przerwana. |

Nie przekazuj pełnego zrzutu swojego środowiska, aby wyjaśnić niepowodzenie. Kod i etap raportu stanowią wstępne rozpoznanie; jeśli konieczne jest dokładniejsze zbadanie, przeanalizuj je we własnym środowisku, zanim udostępnisz dane.

## Dane i ograniczenia

Skrypt nie wykonuje żadnych żądań sieciowych i nie przekazuje niczego do Kernodeck. Nie czyta Twoich notebooków, zbiorów danych, kont, płatności ani checkpointów. Nie zbiera zmiennych środowiskowych, listy pakietów, nazwy hosta, nazwy użytkownika, ścieżki osobistej, numeru seryjnego, UUID, procesów GPU ani tokenu.

Wersja Pythona, rodzina systemu, wersje techniczne, filtrowany model GPU i pojemność pamięci mogą ujawnić część Twojego środowiska sprzętowego. Przejrzyj raport przed jego udostępnieniem. Surowe komunikaty PyTorch i sterownika nie są kopiowane; nierozpoznana wersja lub model staje się wartością neutralną. Raport może zatem pominąć prawidłową etykietę.

Limit czasu ogranicza podproces kontrolny, a nie działanie systemu lub sterownika. Skrypt nie naprawia środowiska, nie waliduje wyspecjalizowanego jądra i nie zastępuje próby Twojego obciążenia. Nie oceniano żadnego złośliwego ani zmodyfikowanego oprogramowania firm trzecich.

## Kontrole faktycznie przeprowadzone 24 września 2026

Poniższe przykłady to zminimalizowane raporty faktycznie wygenerowane przez skrypt, bez surowego wyjątku ani identyfikatora maszyny. Dotyczą środowiska kontrolnego i nie opisują żadnej oferty z katalogu Kernodeck.

| Wykonany przypadek | Środowisko | Wynik |
| --- | --- | --- |
| CPU jawnie | Windows, Python 3.14.6, PyTorch 2.11.0+cu128 | Iloczyn i gradient zweryfikowane; strata `196.0`. [JSON CPU](kernodeck-diagnostic-v1-cpu-example.json) |
| GPU domyślnie | To samo środowisko, kompilacja CUDA 12.8, NVIDIA GeForce RTX 5070 | Iloczyn i gradient zweryfikowane na `cuda:0`; strata `196.0`. [JSON CUDA](kernodeck-diagnostic-v1-cuda-example.json) |
| Brak PyTorch | Windows, Python 3.12.14, bez PyTorch | `TORCH_MISSING`, kod wyjścia 3. [JSON błędu](kernodeck-diagnostic-v1-torch-absent-example.json) |
| GPU niewidoczny tylko dla procesu testowego | Python 3.14.6 i powyższy pakiet CUDA | `GPU_UNAVAILABLE`, kod wyjścia 6. |
| Brak indeksu, nieprawidłowe argumenty, istniejący plik | Oddzielne procesy kontrolne | Kody wyjścia 7, 2 i 12; istniejący plik zachowany. |

Zestaw testów obejmuje 44 kontrole, łączące te rzeczywiste wykonania i izolowane testy jednostkowe. Testy jednostkowe obejmują między innymi pakiet bez backendu GPU, wykrywanie HIP, błąd backendu, przekroczony limit czasu i filtrowanie pól. Nie stanowią one wykonania na sprzęcie ROCm. **W tym zestawie testów nie uruchomiono żadnego GPU AMD/ROCm.** NumPy 2.4.4 było importowalne w środowisku kontrolnym, ale skrypt nie importuje go bezpośrednio.

[Wykorzystane źródła i ich rola](kernodeck-diagnostic-v1-SOURCES.md) rozróżniają wersje dokumentacji od wersji faktycznie użytych. [Manifest SHA-256](kernodeck-diagnostic-v1-manifest.json) opisuje pliki tego wydania. Skróty wykrywają różnicę plików; nie są podpisem autora.


## Prezentacja Kernodeck i zgodność raportów

Prezentacja, nazwa pliku i pomoc wiersza poleceń noszą markę Kernodeck od 25 września 2026. Techniczne identyfikatory schematu JSON pozostają stabilne dla istniejących odbiorców. Trzy powyższe raporty przykładowe są zachowane bajt w bajt jako wyniki wykonania z 24 września 2026. Ich obecność nie stanowi nowego wykonania tej prezentacji. Manifest rozróżnia tę reedycję od historycznych kontroli.