# 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, 감지, 가시성, 할당, 계산, gradient, 동기화, 검증 등. |
| `runtime` | 사용된 Python의 숫자 버전과 시스템 계열; 머신 식별자는 없습니다. |
| `pytorch` | 필터링된 패키지 버전, CUDA/HIP 컴파일 버전, 선언된 backend 및 조회된 경우의 GPU 가시성. PyTorch를 import할 수 없었던 경우 `null`. |
| `execution` | 실제로 선택된 장치, 필터링된 GPU 모델, PyTorch가 보고한 총 메모리, 유형, 행렬 형태 및 검증 결과. 계산이 준비되지 않은 경우 `null`. |
| `host_check` | 요청 시에만 표시: NVIDIA 읽기 상태와 카드당 두 개의 숫자 필드. |

CPU 모드에서 `pytorch.backend`는 설치된 패키지를 설명하므로 `cuda`일 수 있습니다. `execution.backend`는 `cpu`로 유지되며 실행된 계산을 설명합니다. 이때 GPU 가용성, GPU 수, 모델 및 GPU 메모리는 `null`입니다: 측정되지 않았기 때문입니다.

이 검사는 `float32`로 2×2 행렬 두 개를 곱하고, 곱 `[[4, 4], [10, 8]]`을 검증한 다음, gradient `[[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` | 표시된 장치에서 작은 계산과 그 gradient가 올바릅니다. |
| 2 | `CLI_ARGUMENTS_INVALID` | `--help`를 다시 읽어보세요; 유효하지 않은 값은 복사되지 않습니다. |
| 3 | `TORCH_MISSING` | 이 Python에 PyTorch가 없습니다. 올바른 환경을 선택했는지 확인하세요. |
| 4 | `TORCH_IMPORT_FAILED` | PyTorch는 존재하지만 import가 실패합니다; 패키지와 그 종속성을 확인하세요. |
| 5 | `GPU_BACKEND_ABSENT` | 패키지가 CUDA나 HIP를 선언하지 않습니다. 적합한 배포판을 선택하거나 CPU를 명시적으로 요청하세요. |
| 6 | `GPU_UNAVAILABLE` | 패키지가 GPU backend를 선언하지만, 이 프로세스에서 사용 가능한 GPU가 보이지 않습니다. 장치 접근 및 환경 호환성을 확인하세요. |
| 7 | `DEVICE_INDEX_INVALID` | 요청한 인덱스가 PyTorch가 볼 수 있는 목록에 없습니다. |
| 8 | `CHECK_FAILED` | 계산 또는 gradient가 예상되는 고정 결과와 다릅니다. |
| 9 | `OUT_OF_MEMORY` / `RUNTIME_ERROR` | 할당 불가 또는 backend 오류; `stage`가 단계를 명시하며, 원시 예외를 내보내지 않습니다. |
| 10 | `TIMEOUT` | 하위 프로세스가 제한 시간을 초과하여 중지되었습니다. |
| 11 | `WORKER_FAILED` | 하위 프로세스가 유효한 보고서를 제공하지 않았습니다. |
| 12 | `OUTPUT_WRITE_FAILED` | 파일이 이미 존재하거나 접근할 수 없습니다; 새 이름을 선택하세요. 이전 계산이 성공했더라도 전체 상태는 실패합니다. |
| 130 | `INTERRUPTED` | 검사가 중단되었습니다. |

실패를 설명하기 위해 전체 환경 덤프를 전송하지 마세요. 보고서의 코드와 단계가 첫 번째 진단을 구성합니다; 더 정밀한 조사가 필요하면 데이터를 공유하기 전에 자신의 환경에서 검토하세요.

## 데이터 및 한계

Le script n’effectue aucune requête réseau et ne transmet rien à Kernodeck. Il ne lit pas vos notebooks, jeux de données, comptes, paiements ou checkpoints. Il ne collecte pas de variables d’environnement, de liste de paquets, de nom d’hôte, de nom d’utilisateur, de chemin personnel, de numéro de série, de UUID, de processus GPU ou de jeton.

La version Python, la famille du système, les versions techniques, le modèle GPU filtré et la capacité mémoire peuvent révéler une partie de votre environnement matériel. Examinez le rapport avant de le partager. Les messages bruts de PyTorch et du pilote ne sont pas recopiés ; une version ou un modèle non reconnu devient une valeur neutre. Le rapport peut donc omettre un libellé légitime.

Le délai borne le sous-processus de contrôle, pas le fonctionnement du système ou du pilote. Le script ne répare pas un environnement, ne valide pas un noyau spécialisé et ne remplace pas un essai de votre charge de travail. Aucun logiciel tiers malveillant ou modifié n’a été évalué.

## Contrôles réellement effectués le 24 septembre 2026

Les exemples suivants sont les rapports minimisés réellement produits par le script, sans exception brute ni identifiant de machine. Ils concernent l’environnement de contrôle et ne décrivent aucune offre du catalogue Kernodeck.

| Cas exécuté | Environnement | Résultat |
| --- | --- | --- |
| CPU explicite | Windows, Python 3.14.6, PyTorch 2.11.0+cu128 | Produit et gradient vérifiés ; perte `196.0`. [JSON CPU](kernodeck-diagnostic-v1-cpu-example.json) |
| GPU par défaut | Même environnement, compilation CUDA 12.8, NVIDIA GeForce RTX 5070 | Produit et gradient vérifiés sur `cuda:0` ; perte `196.0`. [JSON CUDA](kernodeck-diagnostic-v1-cuda-example.json) |
| PyTorch absent | Windows, Python 3.12.14, sans PyTorch | `TORCH_MISSING`, sortie 3. [JSON d’échec](kernodeck-diagnostic-v1-torch-absent-example.json) |
| GPU rendu invisible au seul processus de test | Python 3.14.6 et paquet CUDA ci-dessus | `GPU_UNAVAILABLE`, sortie 6. |
| Index absent, arguments invalides, fichier existant | Processus de contrôle séparés | Sorties 7, 2 et 12 ; fichier existant conservé. |

La recette compte 44 contrôles, mêlant ces exécutions réelles et des tests unitaires isolés. Les tests unitaires couvrent notamment un paquet sans backend GPU, la détection HIP, une erreur du backend, un délai dépassé et le filtrage des champs. Ils ne constituent pas des exécutions matérielles ROCm. **Aucun GPU AMD/ROCm n’a été exécuté dans cette recette.** NumPy 2.4.4 était importable dans l’environnement de contrôle, mais le script ne l’importe pas directement.

Les [sources consultées et leur rôle](kernodeck-diagnostic-v1-SOURCES.md) distinguent les versions de documentation des versions réellement utilisées. Le [manifeste SHA-256](kernodeck-diagnostic-v1-manifest.json) décrit les fichiers de cette livraison. Les empreintes détectent une différence de fichier ; elles ne sont pas une signature d’auteur.


## Présentation Kernodeck et compatibilité des rapports

La présentation, le nom du fichier et l’aide de commande portent la marque Kernodeck depuis le 25 septembre 2026. Les identifiants techniques du schéma JSON restent stables pour les lecteurs existants. Les trois rapports d’exemple ci-dessus sont conservés à l’octet comme résultats de l’exécution du 24 septembre 2026. Leur présence ne constitue pas une nouvelle exécution de cette présentation. Le manifeste distingue cette réédition des contrôles historiques.