rocm-doctor

ROCm Doctor

「AMD GPU で ROCm／PyTorch／llama.cpp が動作しない」という問題について、 原因となっている既知の設定ミスを特定し、ユーザーの同意を得て修正するか、 正確な次の手順を案内します。

このスキルは、自ら調査や推論を行いません。調査、クローズドな障害モードの カタログ、および修正は rocm CLI が担当します。このスキルは CLI を操作し、 結果を伝えるだけです。カタログは限定されたリストです。症状が既知のモードに 当てはまらない場合は、推測せずにユーザーを上流の窓口へ案内してください。

適用範囲の確認 — 何よりも先に確認してください

ユーザーの症状を読み、まず次の質問に答えてください。これは AMD GPU ですか？

AMD GPU ではない場合、つまり NVIDIA／Intel／Apple の GPU の場合は、 そこで中止し、対応を断ってください。

• このスキルの対象外であることと、その理由（AMD GPU ではないこと）を明確に伝えてください。
• トラブルシューティングは一切提供しないでください。実行するコマンド、 ドライバーや CUDA に関する助言、診断チェックリスト、「まずこれを試す」といった 提案はもちろん、一般的な GPU の提案も含めて案内しないでください。ベンダー独自の ドキュメントを案内したら、そこで終了してください。
• rocm examine／rocm diagnose／rocm fix を実行しないでください。

この場合に役立つのは、対応範囲を正直に伝えることです。このスキルが扱わない スタックについて自信満々に誤った助言をするより、何も助言しないほうが適切です。 GPU が AMD の場合に限り、この確認を通過して先へ進んでください。 対象外を参照してください。

WSL2 は対象内であり、この確認で中止する必要はありません。WSL2 は独自の プラットフォーム群であり、/dev/dxg、DXCore の引き渡し、ROCDXG、ディストリビューションの 最低要件、Windows ホストドライバー、WSL 1 を対象とする独自のカタログ項目があります。 WSL2 ユーザーへの対応を断ったり、何もせず別の窓口へ案内したりしないでください。 ほかのプラットフォームと同じようにワークフローを実行してください。CLI が項目の適用範囲を 判定するため、ベアメタル Linux 向けの修正が提示されることはありません。

前提条件

• rocm CLI。 このスキルは CLI を操作するだけです。以下のフェーズ 0 では、 rocm --version が失敗した場合、ユーザーの同意を得て CLI をインストールします。 ここに記載されているそれ以外の準備は不要です。調査は CLI が行います。
• プラットフォーム： ネイティブ Linux（カーネル内の amdgpu モジュールと /dev/kfd）、Windows（HIP SDK）、または WSL2（/dev/dxg と Windows ホストドライバー）。 NVIDIA／Intel／Apple GPU とクリーンマシンへのインストールは対象外です （対象外を参照）。
• ROCm のバージョン、GPU アーキテクチャ（gfx…）、コンテナーイメージは固定で想定しません。 rocm examine／diagnose が、インストールされている ROCm、GPU の gfx ターゲット、 コンテナーのコンテキストを検出し、見つかった内容に応じて修正を選びます。 HSA_OVERRIDE_GFX_VERSION（または同様の危険な環境変数）を自分で設定しないでください。 CLI に判断を任せてください。

ワークフロー

適用範囲の確認を通過し、GPU が AMD であることを 確認してから開始してください。Linux、Windows、WSL2 では同じワークフローを実行します。

0. rocm CLI が使えることを確認します。 以下の手順ではすべて CLI を呼び出すため、 まず確認し、見つからない場合はインストールしてください。

   rocm --version
   

   コマンドが成功した場合は、手順 1 に進みます。見つからない場合は、ユーザーの同意を 得てインストールしてください（インストーラーを取得して実行し、rocm と rocmd バイナリを ~/.local/bin に配置します）。どちらのインストーラーもデフォルトで release チャンネルを使うため、チャンネル引数は不要です。

   • Linux（x86_64 のみ）：

     curl -fsSL https://raw.githubusercontent.com/ROCm/rocm-cli/main/install.sh | sh
     

   • Windows（PowerShell）：

     irm https://raw.githubusercontent.com/ROCm/rocm-cli/main/install.ps1 | iex
     

   macOS 用のビルドはありません。install.sh は Linux x86_64 以外の環境では インストールを拒否するため、それ以外のホストでは、コマンドを提案せずに インストールページを案内して終了してください。未リリースのビルドを指定する場合は、 nightly を渡してください（sh -s -- nightly、または $env:ROCM_CLI_CHANNEL = "nightly"）。

   インストール後、~/.local/bin が PATH に含まれていることを確認し、 rocm --version を再実行してください。それでも利用できない場合は、インストールページ （https://github.com/ROCm/rocm-cli）を案内して終了してください。

1. 診断します。 ユーザーのエラーテキストを症状として渡してください。

   rocm diagnose --symptom "<paste the exact error>" --json
   

   JSON を確認します：

   • has_match — ゲートです。 true の場合、原因がしきい値を超えているため、修正を提案できます。false の場合、何も特定されていないため、上流に案内します。「matched が空かどうか」に置き換えてはいけません。一部のチェッカーは、単に関連する可能性のある状況（コンテナー、ディスクリート GPU の隣にある APU）に対して、ゼロではないベーススコアで処理を開始するため、問題のないホストでも、しきい値未満の項目を含む空でない matched が返されます。空かどうかを判定基準にすると、問題のないマシンに修正を提案してしまいます。
   • matched[] — スコア順の原因です。それぞれに id、title、score（0～100）、evidence[]、および fix（fix_id、summary、commands、verify、notes、needs_sudo / needs_reboot / needs_relogin / auto_applicable フラグを含む）があります。score >= 75 = 確信度が高い、50–74 = 可能性が高い（先にユーザーに確認して、もう1つ証拠を確認します）。
   • out_of_scope — ホストのプラットフォームファミリーにカタログ項目が一つもない場合にのみ設定されます。Linux、Windows、WSL2 はすべて対象のため、WSL2 では設定されません。これが設定されている場合、何も確認されていません。マシンに問題がないように見えると示唆するのではなく、その旨を伝えてください。まず、ユーザーの症状に独自のランタイムを提供するアプリ（Lemonade、Ollama、LM Studio）が明確に挙げられている場合は、そのアプリのトラッカーに案内します（フレームワーク別の案内を参照）。これらのトラッカーはプラットフォームに関係なく適用されます。それ以外の場合は、out_of_scope メッセージを伝えて終了します。
   • route_when_no_match — has_match が false の場合に、ユーザーを案内する上流のトラッカーです。推測してはいけません。 CLI は症状のテキストではなく、ホストで検出されたフレームワークに基づいて案内先を選ぶ点に注意してください。症状にのみ記載されたアプリについては、フレームワーク別の案内に従って自分で案内します。

2. 修正を提案します。 最上位の一致項目の title、evidence、手順、verify コマンドを提示します。ユーザーが同意した場合にのみ、適用を提案してください。

3. 同意を得て適用します。 自動適用可能な修正の場合：

   rocm fix <fix-id>            # auto fixes: prompt before changing anything
   rocm fix <fix-id> --dry-run  # show the exact change, touch nothing
   rocm fix <fix-id> --yes      # required to apply in a non-interactive shell
   

   CLI が自動で実行するのは、自動適用可能な4つの修正のみです。残りの22個は表示のみ（ブートローダー、カーネル、再インストール、Windows ドライバーなど）です。rocm fix <id> は、ユーザー自身が実行するための手順を表示するだけです。プロンプトは表示されず、CLI がそれらを実行することもありません。

   4つのうち、常に変更を加えるとは限らないものが2つあります。

   • fix-2-unset-override が変更を加えるのは Windows のみです。 Linux では、オーバーライドが設定されている場所と、それを含む rc ファイルを示して停止します。ユーザーのドットファイルは編集しません。そのため、回答するプロンプトはなく、--dry-run でプレビューするものもありません。Linux ユーザーには、編集すべき内容を伝えてください。CLI が変更またはプレビューしたと説明してはいけません。
   • fix-9-igpu-dgpu が変更を加えるのは --device-index N が渡された場合のみです。 どちらのプラットフォームでも、これを指定しない場合、ランナーはディスクリート GPU のインデックスを特定する rocminfo/hipInfo クエリを表示して 0 を返すだけです。プロンプトも --dry-run によるプレビューもなく、固定も行われません。ユーザーが N を確認したら、rocm fix fix-9-igpu-dgpu --device-index N を再実行します。

4. 検証します。 診断結果にある verify コマンドをユーザーに実行してもらいます。

診断なしでホストの状態（GPU、ドライバー、ROCm のインストール、グループ、フレームワーク）のみを確認する場合は、rocm examine（または rocm examine --json）を使います。

フレームワークの振り分け

rocm diagnose は、システムの ROCm/HIP に対してビルドされるフレームワークを対象とします。

• PyTorch、llama.cpp — 対象です。通常どおり診断します。

独自の ROCm ランタイムを同梱するアプリは、ここでは診断しません。適切なトラッカーにユーザーを案内してください。この振り分けはCLI ではなく、あなたが行います。ホストプローブが報告するのは pytorch、llama-cpp、unknown のみであるため、route_when_no_match がこれらのアプリを指定することはありません。以下のリストを使用してください。

• Lemonade → https://github.com/lemonade-sdk/lemonade/issues
• Ollama → https://github.com/ollama/ollama/issues
• LM Studio → アプリ内サポート（公開リポジトリなし）
• カタログに該当する項目がないその他のアプリ → ROCm コア： https://github.com/ROCm/ROCm/issues（これが route_when_no_match のデフォルトの返却先です）。

対象外

• NVIDIA／Intel／Apple Silicon GPU、およびクリーンなマシンへの新規インストール（診断ではなくセットアップ作業です）。正常に終了し、対象外であることを伝えてください。

WSL2 はこのリストに含まれません。独自のカタログ項目を持つサポート対象のプラットフォームファミリーです。reference.md を参照してください。

ルール

• AMD 以外の GPU では、ワークフローを実行したり、いかなるトラブルシューティング（一般的な GPU の修正方法を含む）を提案したりしないでください。対象外であることを伝えて終了してください。これは対象範囲内であり、通常のワークフローを実行する WSL2 には適用されません。
• 修正方法を決してでっち上げないでください。rocm diagnose が一致する項目を返さない場合は、上流に案内してください。
• ユーザーから明確な OK を得ずに、変更を加える修正を実行しないでください。まず --dry-run を使用してください。新しい障害モードは CLI カタログに追加し、ここで即興の対応をしないでください。

カタログ全体と CLI コマンド／終了コードのリファレンスについては、reference.md を参照してください。