# 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ビルドバージョン、宣言されたバックエンド、照会された場合のGPU可視性。PyTorchをインポートできなかった場合は`null`。 |
| `execution` | 実際に選択されたデバイス、フィルタリングされたGPUモデル、PyTorchが報告した総メモリ、型、行列の形状、検証結果。計算が準備されなかった場合は`null`。 |
| `host_check` | 要求時のみ存在：NVIDIA読み取りの状態と、カードごとの2つの数値フィールド。 |

CPUモードでは、`pytorch.backend`はインストールされたパッケージを記述するため`cuda`になることがあります。`execution.backend`は`cpu`のままで、実行された計算を記述します。その場合、GPUの可用性、GPU数、GPUモデル、GPUメモリは`null`です：測定されていないためです。

このチェックは2つの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` | このPythonにPyTorchがありません。正しい環境を選択したか確認してください。 |
| 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 のバージョン、OS ファミリー、技術バージョン、フィルタリングされた GPU モデル、メモリ容量は、ハードウェア環境の一部を明らかにする可能性があります。共有する前にレポートを確認してください。PyTorch とドライバーの生のメッセージは転記されません。認識されないバージョンやモデルはニュートラルな値になります。そのため、レポートが正当なラベルを省略する場合があります。

タイムアウトはチェック用サブプロセスを制限するものであり、システムやドライバーの動作を制限するものではありません。このスクリプトは環境を修復せず、専用カーネルを検証せず、ワークロードのテストの代わりにもなりません。悪意のあるまたは改変されたサードパーティ製ソフトウェアは評価されていません。

## 2026年9月24日に実際に実施されたチェック

以下の例は、スクリプトが実際に生成した最小化されたレポートです。生の例外やマシン識別子は含まれていません。これらはチェック環境に関するものであり、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 ハードウェアでの実行ではありません。**このテストスイートでは AMD/ROCm GPU は一切実行されていません。** NumPy 2.4.4 はチェック環境でインポート可能でしたが、スクリプトはそれを直接インポートしません。

[参照した情報源とその役割](kernodeck-diagnostic-v1-SOURCES.md)では、ドキュメントのバージョンと実際に使用されたバージョンが区別されています。[SHA-256 マニフェスト](kernodeck-diagnostic-v1-manifest.json)は、このリリースのファイルを記述しています。ハッシュはファイルの差異を検出しますが、作成者の署名ではありません。


## Kernodeck の表示とレポートの互換性

表示、ファイル名、コマンドヘルプは 2026年9月25日以降 Kernodeck ブランドを冠しています。JSON スキーマの技術識別子は既存のリーダー向けに安定したままです。上記の 3 つのサンプルレポートは、2026年9月24日の実行結果としてバイト単位で保持されています。それらの存在は、この表示による新たな実行を意味するものではありません。マニフェストは、この再版と過去のチェックを区別しています。