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

Для AMD версії GPU, системи, драйвера та бібліотек мають утворювати підтримувану комбінацію. Цей скрипт не замінює [офіційну матрицю сумісності ROCm](https://rocm.docs.amd.com/en/latest/compatibility/compatibility-matrix.html).

## Читання JSON

Структура стабільна для версії 1:

| Поле | Значення |
| --- | --- |
| `schema`, `script_version` | Формат і версія скрипту. |
| `requested_device` | `gpu` або `cpu`; `unspecified`, якщо аргументи недійсні або виконання перервано. |
| `status`, `code`, `exit_code`, `message` | Загальний результат, стабільний код, код процесу та фіксоване пояснення. |
| `stage` | Останній досягнутий етап: імпорт, виявлення, видимість, виділення, обчислення, градієнт, синхронізація, перевірка тощо. |
| `runtime` | Числова версія використаного Python і сімейство системи; жодного ідентифікатора машини. |
| `pytorch` | Відфільтрована версія пакета, версії збірки CUDA/HIP, заявлений бекенд і видимість GPU, коли вона запитувалася. `null`, якщо PyTorch не вдалося імпортувати. |
| `execution` | Фактично вибраний пристрій, відфільтрована модель GPU, загальна пам'ять, повідомлена PyTorch, тип, форма матриць і результат перевірок. `null`, якщо обчислення не було підготовлено. |
| `host_check` | Присутнє лише на запит: стан читання NVIDIA і два числові поля на кожну карту. |

У режимі CPU `pytorch.backend` може бути `cuda`, оскільки він описує встановлений пакет. `execution.backend` залишається `cpu` і описує виконане обчислення. Доступність GPU, кількість GPU, модель і пам'ять GPU тоді `null`: вони не вимірювалися.

Перевірка множить дві матриці 2×2 у `float32`, перевіряє добуток `[[4, 4], [10, 8]]`, а потім градієнт `[[16, 24], [40, 52]]`. Очікувана сума квадратів дорівнює `196.0`. Ці малі цілі числа дають тут змогу для точного порівняння; ця властивість не обіцяє порозрядну відтворюваність будь-якої моделі. Перевірка використовує [`torch.equal`](https://docs.pytorch.org/docs/2.14/generated/torch.equal.html). Створення контексту GPU може споживати більше пам'яті, ніж самі матриці.

`total_memory_bytes` — це заявлена ємність, а не вільна чи доступна пам'ять для вашої майбутньої моделі. Скрипт не вимірює ні максимальну пам'ять тренування, ні з'єднання, ні швидкість, ні мульти-GPU.

## Розуміння збою

| Вивід | Код JSON | Читання та наступна перевірка |
| --- | --- | --- |
| 0 | `CPU_CHECK_PASSED` / `GPU_CHECK_PASSED` | Мале обчислення та його градієнт правильні на зазначеному пристрої. |
| 2 | `CLI_ARGUMENTS_INVALID` | Перечитайте `--help`; недійсне значення не відтворюється. |
| 3 | `TORCH_MISSING` | PyTorch відсутній у цьому Python. Перевірте, чи ви вибрали правильне середовище. |
| 4 | `TORCH_IMPORT_FAILED` | PyTorch існує, але його імпорт не вдається; перевірте пакет і його залежності. |
| 5 | `GPU_BACKEND_ABSENT` | Пакет не заявляє ні CUDA, ні HIP. Виберіть відповідний дистрибутив або явно вкажіть CPU. |
| 6 | `GPU_UNAVAILABLE` | Пакет заявляє бекенд GPU, але жоден придатний GPU не видимий у цьому процесі. Перевірте доступ до пристрою та сумісність середовища. |
| 7 | `DEVICE_INDEX_INVALID` | Запитаний індекс відсутній у списку, видимому для PyTorch. |
| 8 | `CHECK_FAILED` | Обчислення або градієнт відрізняється від очікуваного фіксованого результату. |
| 9 | `OUT_OF_MEMORY` / `RUNTIME_ERROR` | Неможливо виділити пам'ять або помилка бекенду; `stage` уточнює етап, не експортуючи сирий виняток. |
| 10 | `TIMEOUT` | Підпроцес перевищив час очікування і був зупинений. |
| 11 | `WORKER_FAILED` | Підпроцес не надав дійсного звіту. |
| 12 | `OUTPUT_WRITE_FAILED` | Файл уже існує або недоступний; виберіть нове ім'я. Загальний статус зазнає невдачі, навіть якщо попереднє обчислення було успішним. |
| 130 | `INTERRUPTED` | Перевірку було перервано. |

Не передавайте повний дамп вашого середовища, щоб пояснити збій. Код і етап звіту становлять перше спостереження; якщо потрібне точніше дослідження, проведіть його у своєму середовищі, перш ніж ділитися даними.

## Дані та обмеження

Скрипт не виконує жодних мережевих запитів і нічого не передає до Kernodeck. Він не читає ваші ноутбуки, набори даних, облікові записи, платежі або чекпойнти. Він не збирає змінні середовища, список пакетів, ім'я хоста, ім'я користувача, особистий шлях, серійний номер, UUID, процеси GPU або токен.

Версія Python, сімейство системи, технічні версії, відфільтрована модель GPU та обсяг пам'яті можуть розкрити частину вашого апаратного середовища. Перегляньте звіт, перш ніж ділитися ним. Сирі повідомлення PyTorch і драйвера не копіюються; нерозпізнана версія чи модель стає нейтральним значенням. Тому звіт може пропустити легітимну позначку.

Тайм-аут обмежує підпроцес перевірки, а не роботу системи чи драйвера. Скрипт не виправляє середовище, не перевіряє спеціалізоване ядро і не замінює випробування вашого робочого навантаження. Жодне стороннє шкідливе чи змінене програмне забезпечення не оцінювалося.

## Перевірки, фактично виконані 24 вересня 2026 року

Наведені нижче приклади — це мінімізовані звіти, фактично створені скриптом, без сирих винятків чи ідентифікаторів машини. Вони стосуються контрольного середовища і не описують жодної пропозиції з каталогу Kernodeck.

| Виконаний випадок | Середовище | Результат |
| --- | --- | --- |
| Явний CPU | Windows, Python 3.14.6, PyTorch 2.11.0+cu128 | Добуток і градієнт перевірено; втрата `196.0`. [JSON CPU](kernodeck-diagnostic-v1-cpu-example.json) |
| GPU за замовчуванням | Те саме середовище, компіляція CUDA 12.8, NVIDIA GeForce RTX 5070 | Добуток і градієнт перевірено на `cuda:0`; втрата `196.0`. [JSON CUDA](kernodeck-diagnostic-v1-cuda-example.json) |
| PyTorch відсутній | Windows, Python 3.12.14, без PyTorch | `TORCH_MISSING`, вихід 3. [JSON збою](kernodeck-diagnostic-v1-torch-absent-example.json) |
| GPU зроблено невидимим лише для тестового процесу | Python 3.14.6 і пакет CUDA вище | `GPU_UNAVAILABLE`, вихід 6. |
| Індекс відсутній, недійсні аргументи, наявний файл | Окремі процеси перевірки | Виходи 7, 2 і 12; наявний файл збережено. |

Набір тестів містить 44 перевірки, що поєднують ці реальні запуски та ізольовані модульні тести. Модульні тести охоплюють, зокрема, пакет без бекенду GPU, виявлення HIP, помилку бекенду, перевищений тайм-аут і фільтрування полів. Вони не є апаратними запусками ROCm. **Жоден GPU AMD/ROCm не запускався в цьому наборі тестів.** NumPy 2.4.4 можна було імпортувати в контрольному середовищі, але скрипт не імпортує його безпосередньо.

[Використані джерела та їхня роль](kernodeck-diagnostic-v1-SOURCES.md) розрізняють версії документації та версії, фактично використані. [Маніфест SHA-256](kernodeck-diagnostic-v1-manifest.json) описує файли цієї поставки. Відбитки виявляють різницю у файлі; вони не є підписом автора.


## Презентація Kernodeck і сумісність звітів

Презентація, ім'я файлу та довідка команди носять бренд Kernodeck з 25 вересня 2026 року. Технічні ідентифікатори схеми JSON залишаються стабільними для наявних читачів. Три наведені вище приклади звітів збережено побайтово як результати виконання 24 вересня 2026 року. Їхня наявність не є новим запуском цієї презентації. Маніфест розрізняє це перевидання та історичні перевірки.