PyTorchがGPUを認識しない:正しい順序で診断する

4つの判断による診断の流れ

目的は失敗する最初の層を見つけることであり、複数のインストールを続けて試すことではない。実行したコマンド、最初のエラーメッセージ、各チェックの結果を保存せよ。Python、PyTorchパッケージ、バッチサイズを同時に変更すると、どの変更で問題が解決したのか分からなくなる。

ダウンロード可能なスクリプトはこの順序を適用し、限定的な技術レポートを生成する。モデルを起動せず、インストールを変更しない。プロジェクトと同じ環境で使用せよ。そうしないと、故障しているプログラムとは別のインタプリタを確認することになる。

表をスクロールしてすべての列を表示してください。

最初に失敗したステップで停止せよ。
チェック	チェックが失敗した場合	成功すると実現できること
1. インタプリタとインポート	使用しているPythonまたはそのPyTorchインストールを修正する。	実際にインポートされたパッケージのバージョンとバックエンドを確認する。
2. バックエンドとデバイス	パッケージ、ドライバ、GPUの公開、権限を調べる。	対象のGPUでの割り当てを要求する。
3. 小さなGPU計算	割り当て、計算、または同期のエラーを保存する。	アプリケーションの縮小された入力に移行する。
4. 代表的なアプリケーション	重み、拡張、フォーマット、メモリ、または不正な出力を切り分ける。	実際の作業負荷を徐々に増やす。

1. 実際に実行されているPythonを特定する

ターミナル、ノートブック、サービスは異なるインタプリタを使用することがある。プロジェクトを起動するコンテキストでsys.executableを表示し、バージョンを確認せよ。パスにより、忘れられた仮想環境や別のカーネルに留まっているノートブックを特定できる。自分のマシンで確認せよ。個人のディレクトリ構造をレポートに公開する必要はない。

次に同じインタプリタを使ってパッケージを照会する。コマンドpython -m pip show torchは、そのPythonに関連付けられたPyTorchの情報を表示する。import torchが失敗する場合、次のステップはそのインストールを修正することである。バッチを減らしたりモデルの重みを変更しても、存在しないモジュールは解決しない。

プロジェクトと同じ環境で実行する

python -c "import sys; print(sys.executable); print(sys.version)"
python -m pip show torch

2. CUDA、ROCm、GPUアクセラレーションなしのパッケージを区別する

torch.__version__、torch.version.cuda、torch.version.hipを個別に記録せよ。torch.version.cudaの値がNoneであることだけから「CPUパッケージ」と結論付けないこと。ROCm用のPyTorchはHIPを使用し、torch.cudaを再利用し、同様にcudaという名前のデバイスを期待する。この名前をrocmやhipに置き換えることは適用すべき修正ではない。

次にtorch.cuda.is_available()とtorch.cuda.device_count()を確認します。これらの結果は、このPython環境がその時点で利用できるものを示しています。最小限の計算の代わりにはなりません。システムツールがカードを認識していても、パッケージ、プロセスからアクセス可能なドライバー、またはその環境が原因でPyTorchが使用できない場合があります。

モデルをロードせずに指標を読み取る

python -c "import torch; print(torch.__version__); print(torch.version.cuda); print(torch.version.hip); print(torch.cuda.is_available()); print(torch.cuda.device_count())"

3. Kernodeckスクリプトでレポートを生成する

ファイルをダウンロードしたら、作業フォルダに置き、プロジェクトのPythonで実行します。デフォルトではGPUが必要です。CPUモードは明示的に指定する必要があります。その成功は診断のCPU分岐を検証するものであり、利用できないGPUが検証済みのGPUになることは決してありません。レポートはターミナルに出力され、--outputを指定すると新しいJSONファイルに書き込まれます。既存のファイルが上書きされることはありません。次の試行には別の名前を選んでください。

このスクリプトは float32 の2×2行列を2つ割り当て、その積と勾配を検証してからGPUデバイスを同期します。この固定計算における期待損失値は196です。この非常に短いチェックはモデルの重みを一切読み込まず、スループットも測定しません。単なるデバイス検出にとどまらず、バックエンドに小さな実計算を要求します。

オプションのシステムチェックは、存在する場合にnvidia-smiを使用します。報告するのはNVIDIAドライバーのバージョンと、このツールから見える総メモリのみです。ROCmに対する同等のシステムチェックではありません。計算のタイムアウトはデフォルトで30秒で、5〜120秒の範囲で指定できます。システムチェックには独自の最大タイムアウト3秒があります。

GPUチェックとレポートの保存

python kernodeck-diagnostic-v1.py --device-index 0 --timeout 30 --output diagnostic-gpu.json

意図的に分離されたCPUチェック

python kernodeck-diagnostic-v1.py --device cpu --output diagnostic-cpu.json

オプションのNVIDIAシステムチェックを追加する

python kernodeck-diagnostic-v1.py --host-check --output diagnostic-gpu-systeme.json

4. レポートを読み、次のアクションを選ぶ

まずstatus、code、exit_code、stageを確認します。runtimeブロックはPythonのバージョンとシステムファミリーを示します。pytorchブロックはインポートされたパッケージ、そのCUDA/HIPビルドバージョン、宣言されたバックエンド、および可視デバイスを区別します。executionブロックは、計算が実際にどこで行われたか、積と勾配が確認されたかどうかを示します。

CPUモードでは、gpu_availableとvisible_device_countはnullのままです。スクリプトはGPUドライバーの状態を問い合わせません。これはゼロでも障害でもありません。execution.deviceも確認してください。CUDA向けにコンパイルされたパッケージでも、明示的に指定すればこのチェックをCPUで実行できます。

レポートには厳選された技術データが含まれます。環境変数、マシンのパス、セッション識別子、完全なパッケージリスト、例外の生トレースは含まれません。スクリプトはKernodeckにレポートを送信しません。アプリケーションの詳細なエラーについては、そのトレースを作業スペースに保存し、共有する前にシークレットを削除してください。

表をスクロールしてすべての列を表示してください。

次の判断に役立つコード。完全なリストはスクリプトに付属しています。
結果	意味	次のアクション
GPU_CHECK_PASSED · 0	選択したGPUで積と勾配を確認済み。	アプリケーションの小さな入力に進みます。
CPU_CHECK_PASSED · 0	CPUのみで積と勾配を確認済み。	CUDAまたはROCmについて結論を出さないこと。
TORCH_MISSING · 3 / TORCH_IMPORT_FAILED · 4	このPythonにPyTorchがない、またはインポートに失敗。	インタープリター、パッケージとその依存関係を確認します。
GPU_BACKEND_ABSENT · 5	パッケージがCUDAもHIPも宣言していない。	環境に合ったパッケージをインストールします。
GPU_UNAVAILABLE · 6 / DEVICE_INDEX_INVALID · 7	このプロセスでGPUが使用できない、または可視デバイスの範囲外のインデックス。	カードの公開状況、ドライバー、指定したインデックスを確認します。
CHECK_FAILED · 8 / OUT_OF_MEMORYまたはRUNTIME_ERROR · 9	固定計算、割り当て、またはバックエンドの操作に失敗。	完全なモデルを実行する前に、示されたステージを確認します。
TIMEOUT · 10 / WORKER_FAILED · 11	タイムアウトでチェックが停止、または活用できるレポートがない。	コントロールを失敗として扱う。環境を調べる。
OUTPUT_WRITE_FAILED · 12	レポートは指定された出力先に保存されませんでした。	アクセス可能な新しいファイル名を使用してください。

5. 小さな計算から自分のアプリケーションへ進む

起動前に、再現可能なコマンド、特定済みのモデル、小さなデータセット、アクセス可能な出力ディレクトリを用意します。最終的な作業の重要な特徴を保つ入力を選んでください。テキストの長さ、画像の寸法、音声の形式、必須フィールドなどです。不自然に短い入力は、観察したい問題を覆い隠す可能性があります。

具体的な成功基準を書いてください。埋め込みの計算では、各入力識別子が期待される次元のベクトルを、有限の値で取得できる必要があります。トレーニングでは、1つのステップが使用可能な損失を生成し、想定されたパラメータを更新し、保存を可能にする必要があります。プロセスの終了コードはこれらのチェックを補完するものであり、置き換えるものではありません。

パラメータの読み取り、ライブラリのインポート、重みの読み込み、データの準備、その転送、計算、書き込みの前後にマーカーを追加します。各試行に識別子を付け、関連するパラメータを保持してください。「モデル読み込み完了」というメッセージは、読み込みの意図ではなく、完了したイベントに対応する必要があります。

データセット全体をコピーせずに、有用なテンソルの形状、型、デバイスをログに記録します。「入力: 8シーケンス、最大長512、デバイスcuda:0」のような要約は、2つの試行を比較するのに役立ちます。ここでのこれらの数値はログの一例を説明するものであり、普遍的な設定ではありません。これらのメッセージにアクセストークンや入力の機密内容を含めないでください。

6. 正しい層でエラーを修正する

小さな計算は通るのに重みが見つからない場合は、パス、形式、アクセス権を確認します。拡張機能のインポートに失敗する場合は、PyTorchパッケージおよびプロジェクトのバックエンドとの互換性を確認します。診断が成功しても、アプリケーションのすべての拡張機能を保証するものではありません。複数の依存関係を一度に変えるのではなく、最初に失敗したステップに戻ってください。

デバイスのエラーは、モデルがGPUにあるのにCPUに残った入力が原因のことがあります。型のエラーは、部分的な変換や、選択した精度と互換性のない演算子が原因のことがあります。最初の完全なメッセージとそのトレースを保持します。一度に1つの仮説だけを変更し、最終的なボリュームを再度導入する前に最小入力を再実行してください。

7. モデルが起動した後にメモリを超えた場合

メモリ超過が重みの読み込み時、最初の計算時、それとも複数回のイテレーション後に発生するかを特定します。これらのタイミングは、異なる原因を示します。モデルが大きすぎる、アクティベーションや生成キャッシュが大きい、保持されたテンソルが蓄積しているなどです。同じステップでtorch.cuda.memory_allocated()とtorch.cuda.memory_reserved()を記録します。前者はテンソルの割り当てを追跡し、後者はアロケータが管理するメモリを対象とします。

torch.cuda.empty_cache()は未使用のキャッシュを解放できますが、まだ参照されているテンソルは削除しません。したがって、出力リスト、損失の履歴、計算グラフを保持しているオブジェクトを調べます。次にバッチや入力長を減らして、決定的な要因を切り分けます。超過するフェーズと実際に必要な余裕がわかれば、カードの変更は情報に基づく判断となります。

8. 非同期性を忘れずに計算を測定する

GPUの操作はPythonプログラムに対して非同期になることがあります。したがって、呼び出しの周りに置いたタイマーは、主に作業の送信を測定している可能性があります。診断用の測定では、観察する区間の境界でGPUを同期するか、適切なイベントを使用します。この同期は実行の流れを変えるため、この計測はアプリケーションの通常動作と分けておいてください。

入力の準備、計算、出力の書き込みという3つのセグメントからなる簡単な例を作成してください。GPU のセグメントでは、torch.cuda.synchronize() を呼び出し、time.perf_counter() を記録し、計算を実行し、再度同期してから差分を計算します。最初のパスとそれ以降を別々に保持してください。読み込みや初期化が、完全な応答時間として提示された平均に紛れ込んではいけません。

PyTorch：同期とGPU計算の測定

9. 出力を検証し、再利用可能な診断を保持する

通常の推論では、model.eval() は対象モジュールの挙動を切り替え、torch.inference_mode() は勾配に必要な追跡を無効化します。この2つの設定は役割が異なります。生成されたテンソルがその後に勾配計算に参加しない場合は、後者を使用してください。学習中のモデル評価では、再開前に正しいモードへ明示的に戻す必要があります。

次に、出力を準備した契約と比較しましょう。結果の数、識別子の一致、次元、有限値、および適切なビジネスメトリクスです。バッチを増やす場合は、この一致を再度確認してください。GPUを追加する場合は、入力の分散と出力の収集を検証してください。レンタルロットは注文されたカードを指し、バッチはプログラムがまとめて処理するサンプルを指します。

この方法の結果は小さなフォルダです。コマンド、バージョン、パラメータ、最小入力、最後に成功したステップ、最初のエラー、メモリの観察結果、得られた出力です。起動が成功した場合は、負荷を増やす前の比較基準としてこのフォルダを保持してください。起動が失敗した場合は、調査を最初からやり直すことなく問題を再現できます。

長時間の処理の前に、この小さな入力セットでクリーンな停止と再開も行ってください。既に書き込まれた出力が失われたり二重にカウントされたりしないことを確認してください。これらの検証を通過したら、バッチ、長さ、並行性、プロセス数のうち1つの軸だけを段階的に増やし、観察された限界を記録してください。こうすることで、GPU名に基づく推測ではなく、アプリケーションの測定された動作範囲が得られます。

提供された証拠とその限界

ダウンロード可能なサンプルは、2026年9月24日に実施された実際の検証に基づいています。PyTorchを用いた2回の実行は、Windows、Python 3.14.6、およびPyTorch 2.11.0+cu128を使用しています。GPU検証はCUDAを使用し、NVIDIA GeForce RTX 5070上で行いました。CPU検証では明示的にCPUを指定しています。この検証用ハードウェアは、Kernodeckの提供内容として提示されるものではありません。この証拠のためにROCmの計算は一切実行されていません。

小規模な計算が成功したことは、選択したデバイス上で割り当てと計算の経路が機能することを示しています。しかし、お使いのモデルの速度、最大入力時に必要なメモリ、特定の拡張機能との互換性を測定するものではありません。また、このレポートはマルチカードトポロジーを保証するものでもありません。負荷やレンタルを増やす判断をする前に、代表的なテストへ進んでください。

CUDAアプリケーションの場合は、NVIDIAのスペック表とご自身のメモリおよびライブラリ要件を比較してください。ROCmチェーンの場合は、MI300Xの条件を確認してください。リンクされたスペック表は、お客様のプロジェクトで検討すべき候補であり、証拠で使用されたハードウェアのリストではありません。初期検証とエクスポートの時間は、3日、7日、または30日の期間に含めて見積もってください。

表をスクロールしてすべての列を表示してください。

スクリプト v1.0.0 で観測された結果。パフォーマンス数値は含まれません。
実際の検証	観測された結果	スコープ
明示的な CPU · Python 3.14.6 / PyTorch 2.11.0+cu128	CPU_CHECK_PASSED ; 積と勾配は正確 ; 損失 196。	固定計算は CPU で動作します。
CUDA · RTX 5070 / CUDA 12.8パッケージ	GPU_CHECK_PASSED ; 出力と勾配は正確 ; 損失196。	この環境では、このカード上で固定計算が動作します。
PyTorchなし · Python 3.12.14	TORCH_MISSING ; 終了コード3。	モジュールが存在しないため、明示的に失敗します。
GPUが検査プロセスから見えない状態	GPU_UNAVAILABLE ; 終了コード6。	スクリプトはGPUを黙ってCPUに置き換えることはありません。