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

Untuk AMD, versi GPU, sistem, driver, dan pustaka harus membentuk kombinasi yang didukung. Skrip ini tidak menggantikan [matriks kompatibilitas resmi ROCm](https://rocm.docs.amd.com/en/latest/compatibility/compatibility-matrix.html).

## Membaca JSON

Strukturnya stabil untuk versi 1:

| Bidang | Arti |
| --- | --- |
| `schema`, `script_version` | Format dan versi skrip. |
| `requested_device` | `gpu` atau `cpu`; `unspecified` jika argumen tidak valid atau eksekusi terhenti. |
| `status`, `code`, `exit_code`, `message` | Hasil keseluruhan, kode stabil, kode proses, dan penjelasan tetap. |
| `stage` | Tahap terakhir yang tercapai: impor, deteksi, visibilitas, alokasi, komputasi, gradien, sinkronisasi, validasi, dll. |
| `runtime` | Versi numerik Python yang digunakan dan keluarga sistem; tanpa pengenal mesin. |
| `pytorch` | Versi paket yang telah difilter, versi kompilasi CUDA/HIP, backend yang dideklarasikan, dan visibilitas GPU saat ditanyakan. `null` jika PyTorch tidak dapat diimpor. |
| `execution` | Perangkat yang benar-benar dipilih, model GPU yang telah difilter, memori total yang dilaporkan oleh PyTorch, tipe, bentuk matriks, dan hasil pemeriksaan. `null` jika komputasi belum disiapkan. |
| `host_check` | Hanya ada jika diminta: status pembacaan NVIDIA dan dua bidang numerik per kartu. |

Dalam mode CPU, `pytorch.backend` dapat bernilai `cuda` karena mendeskripsikan paket yang terpasang. `execution.backend` tetap `cpu` dan mendeskripsikan komputasi yang dijalankan. Ketersediaan GPU, jumlah GPU, model, dan memori GPU saat itu bernilai `null`: semuanya tidak diukur.

Pemeriksaan ini mengalikan dua matriks 2×2 dalam `float32`, memverifikasi hasil kali `[[4, 4], [10, 8]]`, lalu gradiennya `[[16, 24], [40, 52]]`. Jumlah kuadrat yang diharapkan bernilai `196.0`. Bilangan bulat kecil ini memungkinkan perbandingan yang tepat di sini; sifat ini tidak menjanjikan reproduksibilitas bit demi bit untuk model apa pun. Verifikasi ini menggunakan [`torch.equal`](https://docs.pytorch.org/docs/2.14/generated/torch.equal.html). Pembuatan konteks GPU dapat mengonsumsi lebih banyak memori daripada sekadar matriksnya.

`total_memory_bytes` adalah kapasitas yang dilaporkan, bukan memori bebas atau yang dapat digunakan oleh model Anda nanti. Skrip ini tidak mengukur memori maksimum suatu pelatihan, tidak pula interkoneksi, kecepatan, maupun multi-GPU.

## Memahami kegagalan

| Keluaran | Kode JSON | Pembacaan dan pemeriksaan berikutnya |
| --- | --- | --- |
| 0 | `CPU_CHECK_PASSED` / `GPU_CHECK_PASSED` | Komputasi kecil dan gradiennya benar pada perangkat yang ditunjukkan. |
| 2 | `CLI_ARGUMENTS_INVALID` | Baca ulang `--help`; nilai yang tidak valid tidak disalin ulang. |
| 3 | `TORCH_MISSING` | PyTorch tidak ada di Python ini. Periksa apakah Anda sudah memilih lingkungan yang benar. |
| 4 | `TORCH_IMPORT_FAILED` | PyTorch ada tetapi impornya gagal; periksa paket dan dependensinya. |
| 5 | `GPU_BACKEND_ABSENT` | Paket tidak mendeklarasikan CUDA maupun HIP. Pilih distribusi yang sesuai, atau minta CPU secara eksplisit. |
| 6 | `GPU_UNAVAILABLE` | Paket mendeklarasikan backend GPU, tetapi tidak ada GPU yang dapat digunakan yang terlihat dalam proses ini. Periksa akses perangkat dan kompatibilitas lingkungan. |
| 7 | `DEVICE_INDEX_INVALID` | Indeks yang diminta tidak ada dalam daftar yang terlihat oleh PyTorch. |
| 8 | `CHECK_FAILED` | Komputasi atau gradien berbeda dari hasil tetap yang diharapkan. |
| 9 | `OUT_OF_MEMORY` / `RUNTIME_ERROR` | Alokasi tidak mungkin atau terjadi kesalahan backend; `stage` menunjukkan tahapnya, tanpa mengekspor pengecualian mentah. |
| 10 | `TIMEOUT` | Subproses melewati batas waktu dan dihentikan. |
| 11 | `WORKER_FAILED` | Subproses tidak memberikan laporan yang valid. |
| 12 | `OUTPUT_WRITE_FAILED` | File sudah ada atau tidak dapat diakses; pilih nama baru. Status keseluruhan gagal meskipun komputasi sebelumnya berhasil. |
| 130 | `INTERRUPTED` | Pemeriksaan dihentikan. |

Jangan kirimkan dump lengkap lingkungan Anda untuk menjelaskan kegagalan. Kode dan tahap pada laporan merupakan temuan awal; jika diperlukan investigasi yang lebih rinci, periksa di lingkungan Anda sendiri sebelum membagikan data.

## Data dan batasan

Skrip ini tidak melakukan permintaan jaringan apa pun dan tidak mengirimkan apa pun ke Kernodeck. Skrip ini tidak membaca notebook, set data, akun, pembayaran, atau checkpoint Anda. Skrip ini tidak mengumpulkan variabel lingkungan, daftar paket, nama host, nama pengguna, jalur pribadi, nomor seri, UUID, proses GPU, atau token.

Versi Python, keluarga sistem, versi teknis, model GPU yang telah difilter, dan kapasitas memori dapat mengungkap sebagian lingkungan perangkat keras Anda. Periksa laporan sebelum membagikannya. Pesan mentah dari PyTorch dan driver tidak disalin ulang; versi atau model yang tidak dikenali menjadi nilai netral. Oleh karena itu, laporan dapat menghilangkan label yang sah.

Batas waktu membatasi subproses pemeriksaan, bukan cara kerja sistem atau driver. Skrip ini tidak memperbaiki lingkungan, tidak memvalidasi kernel khusus, dan tidak menggantikan uji coba beban kerja Anda. Tidak ada perangkat lunak pihak ketiga yang berbahaya atau dimodifikasi yang dievaluasi.

## Pemeriksaan yang benar-benar dilakukan pada 24 September 2026

Contoh berikut adalah laporan minimal yang benar-benar dihasilkan oleh skrip, tanpa pengecualian mentah atau pengenal mesin. Laporan ini berkaitan dengan lingkungan pemeriksaan dan tidak menggambarkan penawaran apa pun dari katalog Kernodeck.

| Kasus yang dijalankan | Lingkungan | Hasil |
| --- | --- | --- |
| CPU eksplisit | Windows, Python 3.14.6, PyTorch 2.11.0+cu128 | Perkalian dan gradien terverifikasi; loss `196.0`. [JSON CPU](kernodeck-diagnostic-v1-cpu-example.json) |
| GPU default | Lingkungan yang sama, kompilasi CUDA 12.8, NVIDIA GeForce RTX 5070 | Perkalian dan gradien terverifikasi pada `cuda:0`; loss `196.0`. [JSON CUDA](kernodeck-diagnostic-v1-cuda-example.json) |
| PyTorch tidak ada | Windows, Python 3.12.14, tanpa PyTorch | `TORCH_MISSING`, keluaran 3. [JSON kegagalan](kernodeck-diagnostic-v1-torch-absent-example.json) |
| GPU dibuat tidak terlihat hanya untuk proses pengujian | Python 3.14.6 dan paket CUDA di atas | `GPU_UNAVAILABLE`, keluaran 6. |
| Indeks tidak ada, argumen tidak valid, file sudah ada | Proses pemeriksaan terpisah | Keluaran 7, 2, dan 12; file yang sudah ada dipertahankan. |

Resep ini mencakup 44 pemeriksaan, yang menggabungkan eksekusi nyata tersebut dan pengujian unit yang terisolasi. Pengujian unit mencakup antara lain paket tanpa backend GPU, deteksi HIP, kesalahan backend, batas waktu yang terlampaui, dan pemfilteran bidang. Pengujian tersebut bukan merupakan eksekusi perangkat keras ROCm. **Tidak ada GPU AMD/ROCm yang dijalankan dalam resep ini.** NumPy 2.4.4 dapat diimpor di lingkungan pemeriksaan, tetapi skrip tidak mengimpornya secara langsung.

[Sumber yang dikonsultasikan dan perannya](kernodeck-diagnostic-v1-SOURCES.md) membedakan versi dokumentasi dari versi yang benar-benar digunakan. [Manifes SHA-256](kernodeck-diagnostic-v1-manifest.json) menjelaskan file-file dalam pengiriman ini. Sidik jari mendeteksi perbedaan file; sidik jari bukanlah tanda tangan penulis.


## Tampilan Kernodeck dan kompatibilitas laporan

Tampilan, nama file, dan bantuan perintah menyandang merek Kernodeck sejak 25 September 2026. Pengenal teknis skema JSON tetap stabil untuk pembaca yang sudah ada. Ketiga laporan contoh di atas disimpan persis seperti aslinya sebagai hasil eksekusi 24 September 2026. Keberadaannya bukan merupakan eksekusi baru dari tampilan ini. Manifes membedakan penerbitan ulang ini dari pemeriksaan historis.