rocm-doctor

ROCm Doctor

如果用户反馈“AMD GPU 上的 ROCm / PyTorch / llama.cpp 无法正常工作”，请判断原因是否属于已知配置错误，并在征得同意后修复，或告知用户下一步的确切操作。

此技能不会自行探测或推理。探测、封闭的故障模式目录和修复操作均由 rocm CLI 负责；此技能只负责驱动 CLI 并转达结果。该目录是一个封闭列表——如果症状不符合任何已知模式，请将用户引导至上游，而不是自行猜测。

范围检查——优先检查

阅读用户描述的症状，并先回答一个问题：这是 AMD GPU 吗？

如果不是——而是 NVIDIA / Intel / Apple GPU——则停止并拒绝处理：

• 明确说明这超出此技能的范围，并解释原因（不是 AMD GPU）。
• 不要为此提供任何故障排查建议：不要给出要运行的命令、驱动或 CUDA 建议、诊断清单，也不要说“先试试这个”——甚至不要提供通用 GPU 建议。指向厂商自己的文档，然后停止。
• 不要运行 rocm examine / rocm diagnose / rocm fix。

此时，提供帮助意味着坦诚说明适用范围——对本技能不支持的软件栈给出自信却错误的建议，比不提供建议更糟。只有 GPU 是 AMD 时，才继续执行此检查。参见不在适用范围内。

WSL2 在适用范围内，不会导致此检查停止。它是独立的平台类别，拥有自己的目录条目，涵盖 /dev/dxg、DXCore 交接、ROCDXG、发行版最低要求、Windows 主机驱动和 WSL 1。不要拒绝 WSL2 用户，也不要直接将他们引导至其他地方——应像处理其他平台一样运行工作流。CLI 会自行限定适用条目，因此不会向此类用户提供裸机 Linux 修复方案。

前提条件

• rocm CLI。 此技能只是对它的驱动；如果 rocm --version 失败，下面的第 0 阶段会在征得用户同意后安装它。此处不假设其他条件——探测由 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 GPU——后，才能从此处开始。Linux、Windows 和 WSL2 均运行相同的工作流。

0. 确保已安装 rocm CLI。 以下所有步骤都会调用它，因此请先检查；如果缺失，则安装：

   rocm --version
   

   如果检查成功，则跳到步骤 1。如果找不到该 CLI，请在征得用户同意后安装（此操作会下载并运行安装程序，将 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 中仍会返回非空的低于阈值的条目。以是否为空作为判断依据，会导致你为没有问题的机器提出修复方案。True 也不代表问题已解决：仅凭主机状态，排名第一的 diagnose-only 匹配项就可能达到门槛，而与你粘贴的症状无关——请参阅步骤 2 中的细化说明。
   • 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 = 可能性较高（先向用户确认一条证据）。 提出任何方案前，先查看 fix.class。 diagnose-only 表示原因确实存在且已得到解释，但没有补救措施——目前仅适用于 info-20-gpu-no-rocm-support，因此它使用 info- 开头的 id，而不是 fix-N / fix-wsl-N。rocm fix 仍会接受该 id 并作出回应，说明问题所在但不做任何更改。
   • 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 命令。只有用户同意后，才提出应用修复方案。

   如果排名第一的匹配项的 fix.class 是 diagnose-only，则没有可提出的修复方案：将其 title 和 evidence 转述为对主机状况的说明，然后到此为止——前提是用户没有粘贴症状，或者这些证据有可能解释其症状。像 info-20-gpu-no-rocm-support 这样的 diagnose-only 原因仅根据主机状态（GPU 架构）计分，而不是根据症状，因此即使粘贴的文本描述了证据从未提及的情况，它也可能成为排名第一的匹配项——例如，实际在此主机上运行的引擎发生崩溃，而不是任何与 ROCm/HIP 支持有关的问题。转述与用户粘贴内容无关的主机状态证据后就停止，会悄然忽略用户实际提出的问题。如果用户粘贴了症状，且此原因的证据无法合理解释该症状，则应视为此原因没有回答问题：说明它能确认的主机状况，然后针对用户粘贴的症状，按照 route_when_no_match 转交上游，就像 has_match 为 false 一样。只有当排名较低的原因也达到 min_score_for_match 时，才可以提及它——低于该阈值就表示尚未确定任何问题，这与上文 has_match 段落设定的标准相同，而且排名第一的 diagnose-only 匹配项不会降低此标准。

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 会自行运行的只有四种可自动应用的修复。其他 23 种都是仅打印（引导加载程序、内核、重装、Windows 驱动程序等）：rocm fix <id> 只会打印计划，供用户自行执行——不会提示用户，CLI 也绝不会执行这些修复。

   有一项不属于这两组。info-20-gpu-no-rocm-support 是仅诊断：rocm fix 接受该 ID，说明问题，指出没有可靠的修复方法，并以状态码 0 退出，期间不会更改任何内容。

   四种修复中，有两种不会总是进行修改：

   • fix-2-unset-override 仅在 Windows 上进行修改。 在 Linux 上，它会报告覆盖设置的位置以及包含该设置的 rc 文件，然后停止——不会编辑用户的点文件。因此无需回答提示，也没有可供 --dry-run 预览的内容。告知 Linux 用户需要编辑什么；不要说成是 CLI 所做或预览的更改。
   • 只有在传入 --device-index N 时，fix-9-igpu-dgpu 才会进行修改。 在任一平台上，如果未传入该参数，运行程序只会打印用于识别独立 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；WSL2 在支持范围内，应运行正常工作流。
• 绝不臆造修复方法。如果 rocm diagnose 没有返回匹配项，请将用户引导至上游。
• 未经用户明确同意，绝不运行会进行修改的修复；优先先运行 --dry-run。新的故障模式应加入 CLI 目录，不要在此处临时编造处理方案。

完整的封闭目录以及 CLI 命令和退出码参考，请参见 reference.md。