# 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` | Последний достигнутый этап: import, обнаружение, видимость, выделение, вычисление, градиент, синхронизация, проверка и т. д. |
| `runtime` | Числовая версия используемого Python и семейство системы; никаких идентификаторов машины. |
| `pytorch` | Отфильтрованная версия пакета, версии сборки CUDA/HIP, заявленный backend и видимость 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` — это сообщаемая ёмкость, а не свободная или доступная вашей будущей модели память. Скрипт не измеряет ни максимальную память обучения, ни межсоединение, ни скорость, ни multi-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` | Пакет заявляет backend GPU, но ни один пригодный GPU не виден в этом процессе. Проверьте доступ к устройству и совместимость окружения. |
| 7 | `DEVICE_INDEX_INVALID` | Запрошенный индекс отсутствует в списке, видимом PyTorch. |
| 8 | `CHECK_FAILED` | Вычисление или градиент отличается от фиксированного ожидаемого результата. |
| 9 | `OUT_OF_MEMORY` / `RUNTIME_ERROR` | Выделение невозможно или ошибка backend; `stage` уточняет этап, не экспортируя исходное исключение. |
| 10 | `TIMEOUT` | Подпроцесс превысил время ожидания и был остановлен. |
| 11 | `WORKER_FAILED` | Подпроцесс не предоставил действительный отчёт. |
| 12 | `OUTPUT_WRITE_FAILED` | Файл уже существует или недоступен; выберите новое имя. Общий статус завершается неудачей, даже если предыдущее вычисление прошло успешно. |
| 130 | `INTERRUPTED` | Проверка была прервана. |

Не передавайте полный дамп вашего окружения для объяснения сбоя. Код и этап отчёта составляют первичную констатацию; если требуется более точное исследование, проведите его в своём окружении, прежде чем делиться данными.

## Данные и ограничения

Скрипт не выполняет никаких сетевых запросов и ничего не передаёт в Kernodeck. Он не читает ваши ноутбуки, наборы данных, аккаунты, платежи или контрольные точки. Он не собирает переменные среды, список пакетов, имя хоста, имя пользователя, личный путь, серийный номер, UUID, процессы GPU или токен.

Версия Python, семейство системы, технические версии, отфильтрованная модель GPU и объём памяти могут раскрыть часть вашего аппаратного окружения. Изучите отчёт перед тем, как им поделиться. Исходные сообщения PyTorch и драйвера не копируются; нераспознанная версия или модель становится нейтральным значением. Поэтому отчёт может опустить legitimate метку.

Тайм-аут ограничивает подпроцесс проверки, а не работу системы или драйвера. Скрипт не исправляет окружение, не подтверждает работоспособность специализированного ядра и не заменяет пробный запуск вашей рабочей нагрузки. Никакое стороннее вредоносное или изменённое программное обеспечение не оценивалось.

## Проверки, фактически выполненные 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 контроля, сочетающих эти реальные запуски и изолированные модульные тесты. Модульные тесты охватывают, в частности, пакет без backend GPU, обнаружение HIP, ошибку backend, превышенный тайм-аут и фильтрацию полей. Они не являются реальными запусками на оборудовании 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 года. Их наличие не является новым выполнением этого представления. Манифест отличает это переиздание от исторических проверок.