# 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 için GPU, sistem, sürücü ve kitaplık sürümleri desteklenen bir bileşim oluşturmalıdır. Bu betik, [resmi ROCm uyumluluk matrisinin](https://rocm.docs.amd.com/en/latest/compatibility/compatibility-matrix.html) yerini almaz.

## JSON'u okuma

Yapı, 1. sürüm için sabittir:

| Alan | Anlamı |
| --- | --- |
| `schema`, `script_version` | Betiğin biçimi ve sürümü. |
| `requested_device` | `gpu` veya `cpu`; argümanlar geçersizse ya da yürütme kesintiye uğrarsa `unspecified`. |
| `status`, `code`, `exit_code`, `message` | Genel sonuç, sabit kod, süreç kodu ve sabit açıklama. |
| `stage` | Ulaşılan son adım: import, algılama, görünürlük, ayırma, hesaplama, gradyan, eşitleme, doğrulama vb. |
| `runtime` | Kullanılan Python'un sayısal sürümü ve sistem ailesi; hiçbir makine tanımlayıcısı yok. |
| `pytorch` | Paketin filtrelenmiş sürümü, CUDA/HIP derleme sürümleri, bildirilen backend ve sorgulandığında GPU görünürlüğü. PyTorch içe aktarılamadıysa `null`. |
| `execution` | Gerçekte seçilen aygıt, filtrelenmiş GPU modeli, PyTorch tarafından bildirilen toplam bellek, tür, matris biçimi ve doğrulama sonuçları. Hesaplama hazırlanamadıysa `null`. |
| `host_check` | Yalnızca istendiğinde bulunur: NVIDIA okumasının durumu ve kart başına iki sayısal alan. |

CPU modunda `pytorch.backend`, yüklü paketi tanımladığı için `cuda` olabilir. `execution.backend` ise `cpu` olarak kalır ve yürütülen hesaplamayı tanımlar. Bu durumda GPU kullanılabilirliği, GPU sayısı, model ve GPU belleği `null` olur: ölçülmemişlerdir.

Kontrol, `float32` türünde iki 2×2 matrisi çarpar, `[[4, 4], [10, 8]]` çarpımını ve ardından `[[16, 24], [40, 52]]` gradyanını doğrular. Beklenen kareler toplamı `196.0` değerindedir. Bu küçük tam sayılar burada tam bir karşılaştırmaya olanak tanır; bu özellik herhangi bir modelin bit düzeyinde yeniden üretilebilirliğini garanti etmez. Doğrulama [`torch.equal`](https://docs.pytorch.org/docs/2.14/generated/torch.equal.html) kullanır. Bir GPU bağlamının oluşturulması, yalnızca matrislerden daha fazla bellek tüketebilir.

`total_memory_bytes` bildirilen bir kapasitedir; boş bellek ya da gelecekteki modelinizin kullanabileceği bellek değildir. Betik ne bir eğitimin azami belleğini ne ara bağlantıyı ne hızı ne de çoklu GPU'yu ölçer.

## Bir başarısızlığı anlama

| Çıktı | JSON kodu | Okuma ve sonraki kontrol |
| --- | --- | --- |
| 0 | `CPU_CHECK_PASSED` / `GPU_CHECK_PASSED` | Küçük hesaplama ve gradyanı belirtilen aygıtta doğrudur. |
| 2 | `CLI_ARGUMENTS_INVALID` | `--help` çıktısını yeniden okuyun; geçersiz değer kopyalanmaz. |
| 3 | `TORCH_MISSING` | Bu Python'da PyTorch eksik. Doğru ortamı seçtiğinizden emin olun. |
| 4 | `TORCH_IMPORT_FAILED` | PyTorch var ama içe aktarımı başarısız oluyor; paketi ve bağımlılıklarını kontrol edin. |
| 5 | `GPU_BACKEND_ABSENT` | Paket ne CUDA ne de HIP bildiriyor. Uygun bir dağıtım seçin ya da açıkça CPU isteyin. |
| 6 | `GPU_UNAVAILABLE` | Paket bir GPU backend'i bildiriyor, ancak bu süreçte kullanılabilir hiçbir GPU görünmüyor. Aygıt erişimini ve ortam uyumluluğunu kontrol edin. |
| 7 | `DEVICE_INDEX_INVALID` | İstenen dizin, PyTorch tarafından görülen listede yok. |
| 8 | `CHECK_FAILED` | Hesaplama ya da gradyan, beklenen sabit sonuçtan farklı. |
| 9 | `OUT_OF_MEMORY` / `RUNTIME_ERROR` | Ayırma mümkün değil ya da backend hatası; `stage` adımı belirtir, ham istisnayı dışa aktarmaz. |
| 10 | `TIMEOUT` | Alt süreç zaman aşımını aştı ve durduruldu. |
| 11 | `WORKER_FAILED` | Alt süreç geçerli bir rapor sunmadı. |
| 12 | `OUTPUT_WRITE_FAILED` | Dosya zaten var ya da erişilebilir değil; yeni bir ad seçin. Önceki hesaplama başarılı olsa bile genel durum başarısız olur. |
| 130 | `INTERRUPTED` | Kontrol kesintiye uğradı. |

Bir başarısızlığı açıklamak için ortamınızın tam dökümünü paylaşmayın. Raporun kodu ve adımı ilk tespiti oluşturur; daha ayrıntılı bir inceleme gerekliyse, veri paylaşmadan önce bunu kendi ortamınızda inceleyin.

## Veriler ve sınırlar

Script hiçbir ağ isteği yapmaz ve Kernodeck'e hiçbir şey iletmez. Not defterlerinizi, veri kümelerinizi, hesaplarınızı, ödemelerinizi veya kontrol noktalarınızı okumaz. Ortam değişkenlerini, paket listesini, ana makine adını, kullanıcı adını, kişisel yolu, seri numarasını, UUID'yi, GPU sürecini veya jetonu toplamaz.

Python sürümü, sistem ailesi, teknik sürümler, filtrelenmiş GPU modeli ve bellek kapasitesi donanım ortamınızın bir kısmını açığa çıkarabilir. Paylaşmadan önce raporu inceleyin. PyTorch ve sürücünün ham mesajları kopyalanmaz; tanınmayan bir sürüm veya model nötr bir değere dönüşür. Bu nedenle rapor geçerli bir etiketi atlayabilir.

Zaman aşımı, kontrol alt sürecini sınırlar; sistemin veya sürücünün çalışmasını değil. Script bir ortamı onarmaz, özelleşmiş bir çekirdeği doğrulamaz ve iş yükünüzün denemesinin yerini almaz. Hiçbir kötü niyetli veya değiştirilmiş üçüncü taraf yazılımı değerlendirilmemiştir.

## 24 Eylül 2026 tarihinde gerçekten gerçekleştirilen kontroller

Aşağıdaki örnekler, script tarafından gerçekten üretilen, ham istisna veya makine tanımlayıcısı içermeyen asgari raporlardır. Bunlar kontrol ortamıyla ilgilidir ve Kernodeck kataloğundaki hiçbir teklifi tanımlamaz.

| Çalıştırılan durum | Ortam | Sonuç |
| --- | --- | --- |
| Açık CPU | Windows, Python 3.14.6, PyTorch 2.11.0+cu128 | Çarpım ve gradyan doğrulandı; kayıp `196.0`. [CPU JSON](kernodeck-diagnostic-v1-cpu-example.json) |
| Varsayılan GPU | Aynı ortam, CUDA 12.8 derlemesi, NVIDIA GeForce RTX 5070 | Çarpım ve gradyan `cuda:0` üzerinde doğrulandı; kayıp `196.0`. [CUDA JSON](kernodeck-diagnostic-v1-cuda-example.json) |
| PyTorch yok | Windows, Python 3.12.14, PyTorch olmadan | `TORCH_MISSING`, çıkış 3. [Hata JSON'u](kernodeck-diagnostic-v1-torch-absent-example.json) |
| GPU yalnızca test sürecine görünmez kılındı | Python 3.14.6 ve yukarıdaki CUDA paketi | `GPU_UNAVAILABLE`, çıkış 6. |
| Dizin yok, geçersiz bağımsız değişkenler, mevcut dosya | Ayrı kontrol süreçleri | Çıkışlar 7, 2 ve 12; mevcut dosya korundu. |

Kabul testi, bu gerçek çalıştırmaları ve yalıtılmış birim testlerini bir araya getiren 44 kontrol içerir. Birim testleri özellikle GPU arka ucu olmayan bir paketi, HIP algılamayı, bir arka uç hatasını, aşılan bir zaman aşımını ve alanların filtrelenmesini kapsar. Bunlar ROCm donanım çalıştırmaları değildir. **Bu kabul testinde hiçbir AMD/ROCm GPU'su çalıştırılmamıştır.** NumPy 2.4.4 kontrol ortamında içe aktarılabilirdi, ancak script onu doğrudan içe aktarmaz.

[Başvurulan kaynaklar ve rolleri](kernodeck-diagnostic-v1-SOURCES.md), belge sürümlerini gerçekten kullanılan sürümlerden ayırt eder. [SHA-256 manifestosu](kernodeck-diagnostic-v1-manifest.json) bu teslimatın dosyalarını tanımlar. Parmak izleri bir dosya farkını tespit eder; bunlar bir yazar imzası değildir.


## Kernodeck sunumu ve rapor uyumluluğu

Sunum, dosya adı ve komut yardımı 25 Eylül 2026 tarihinden itibaren Kernodeck markasını taşır. JSON şemasının teknik tanımlayıcıları mevcut okuyucular için sabit kalır. Yukarıdaki üç örnek rapor, 24 Eylül 2026 tarihli çalıştırmanın sonuçları olarak bayt düzeyinde korunmuştur. Bunların varlığı bu sunumun yeni bir çalıştırması anlamına gelmez. Manifesto bu yeniden basımı geçmiş kontrollerden ayırt eder.