rocm-doctor

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

ROCm Doctor

ROCm 诊断工具

Given a "ROCm / PyTorch / llama.cpp isn't working on my AMD GPU" complaint, identify which known misconfiguration is the cause and either fix it (with consent) or hand back the exact next step.

This skill does not probe or reason on its own. The

rocm

CLI owns the probe, the closed failure-mode catalog, and the fixes; the skill just drives it and relays the results. The catalog is a closed list — if the symptom doesn't match a known mode, route the user upstream instead of guessing.

当收到“我的AMD GPU上ROCm / PyTorch / llama.cpp无法运行”的问题反馈时，识别导致问题的已知配置错误，经用户同意后执行修复，或给出明确的下一步操作。

本技能不会自行进行探测或推理。探测逻辑、封闭的故障模式目录以及修复方案均由

rocm

CLI提供；本技能仅负责调用该CLI并传递结果。该目录是封闭列表——如果症状与已知模式不匹配，应将用户引导至上游渠道，而非自行猜测。

Scope gate — check before anything else

范围校验 — 首要检查项

Read the user's symptom and answer one question first: is this an AMD GPU?

If it is not — an NVIDIA / Intel / Apple GPU — then stop and decline:

Say plainly that it is out of scope for this skill and why (not an AMD GPU).
Give no troubleshooting for it: no commands to run, no driver or CUDA advice, no diagnostic checklist, no "try this first" — not even generic GPU suggestions. Point at the vendor's own docs and stop there.
Do not run
```
rocm examine
```
/
```
rocm diagnose
```
/
```
rocm fix
```
.

Being helpful here means being honest about the boundary — confidently-wrong advice for a stack this skill does not cover is worse than no advice. Only continue past this gate when the GPU is AMD. See Out of scope.

WSL2 is in scope and does not stop this gate. It is a platform family of its own, with its own catalog entries covering

/dev/dxg

, the DXCore handoff, ROCDXG, the distro floor, the Windows host driver and WSL 1. Do not decline a WSL2 user or route them away untouched — run the workflow as for any other platform. The CLI scopes entries itself, so a bare-metal Linux fix is never offered there.

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

如果不是——是NVIDIA / Intel / Apple GPU——那么直接停止并拒绝处理：

明确说明该问题超出本技能的处理范围及原因（非AMD GPU）。
不要提供任何故障排查建议：不要给出要运行的命令、不要提供驱动或CUDA相关建议、不要给出诊断清单、不要说“先试试这个”——甚至连通用的GPU建议都不要提。只需指向厂商官方文档即可停止处理。
不要运行
```
rocm examine
```
/
```
rocm diagnose
```
/
```
rocm fix
```
。

在这里，有帮助意味着坦诚告知边界——对于本技能不覆盖的技术栈，给出看似笃定的错误建议比不给建议更糟糕。仅当确认是AMD GPU时，才能继续后续流程。参见超出范围。

WSL2在处理范围内，不会被此校验拦截。它属于独立的平台系列，有对应的目录条目，覆盖

/dev/dxg

、DXCore交接、ROCDXG、发行版最低要求、Windows宿主机驱动和WSL 1相关问题。不要拒绝WSL2用户，也不要不加处理就将其引导走——像对待其他平台一样执行工作流即可。CLI会自行匹配条目的适用范围，因此绝不会在WSL2环境下提供裸机Linux的修复方案。

Prerequisites

前提条件

The
rocm
CLI. This skill is only a driver over it; Phase 0 below installs it with the user's consent if
```
rocm --version
```
fails. Nothing else here is assumed — the CLI does the probing.
Platform: native Linux (in-tree
```
amdgpu
```
module +
```
/dev/kfd
```
), Windows (HIP SDK), or WSL2 (
```
/dev/dxg
```
+ the Windows host driver). NVIDIA/Intel/Apple GPUs and clean-machine installs are out of scope (see Out of scope).
No fixed ROCm version, GPU arch (
gfx…
), or container image is assumed —
```
rocm examine
```
/
```
diagnose
```
detect the installed ROCm, the GPU's
```
gfx
```
target, and container context, and match fixes to what they find. Never hand-set
```
HSA_OVERRIDE_GFX_VERSION
```
(or similar footgun env vars) yourself; let the CLI decide.

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来决定。

Workflow

工作流

Only start here once the Scope gate passes — the GPU is AMD. Linux, Windows and WSL2 all run the same workflow.

Ensure the
rocm
CLI is present. Everything below shells out to it, so check first and install it if missing:
```
rocm --version
```
If that succeeds, skip to step 1. If it's not found, install it with the user's consent (this fetches and runs an installer that drops the
```
rocm
```
and
```
rocmd
```
binaries into
```
~/.local/bin
```
). Both installers default to the
```
release
```
channel, so no channel argument is needed:
- Linux (x86_64 only):
```
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
```
There is no macOS build.
```
install.sh
```
refuses anything but Linux x86_64, so on any other host hand the user the install page and stop rather than suggesting the command anyway. To pin an unreleased build instead, pass
```
nightly
```
(
```
sh -s -- nightly
```
, or
```
$env:ROCM_CLI_CHANNEL = "nightly"
```
).
After install, confirm
```
~/.local/bin
```
is on
```
PATH
```
and re-run
```
rocm --version
```
. If it still isn't available, hand the user the install page (https://github.com/ROCm/rocm-cli) and stop.
Diagnose. Pass the user's error text as the symptom:
```
rocm diagnose --symptom "<paste the exact error>" --json
```
Read the JSON:
- ```
has_match
```
  — the gate. True means a cause cleared the threshold and you may propose a fix; false means nothing was established, so route upstream. Do not substitute "is
```
matched
```
  empty?": several checkers open with a nonzero base score for a merely potentially relevant situation (a container, an APU beside a discrete GPU), so a healthy host still returns a non-empty
```
matched
```
  of sub-threshold entries. Gating on emptiness proposes a fix for a machine with nothing wrong.
- ```
matched[]
```
  — ranked causes, each with
```
id
```
  ,
```
title
```
  ,
```
score
```
  (0–100),
```
evidence[]
```
  , and a
```
fix
```
  (with
```
fix_id
```
  ,
```
summary
```
  ,
```
commands
```
  ,
```
verify
```
  ,
```
notes
```
  , and the
```
needs_sudo
```
  /
```
needs_reboot
```
  /
```
needs_relogin
```
  /
```
auto_applicable
```
  flags).
```
score >= 75
```
  = high confidence;
```
50–74
```
  = likely (confirm one more piece of evidence with the user first).
- ```
out_of_scope
```
  — set only when the host's platform family has no catalog entries at all. Linux, Windows and WSL2 are all covered, so this does not fire for WSL2. When it is set, nothing was checked — say so rather than implying the machine looks fine. First, if the user's symptom clearly names an app that ships its own runtime (Lemonade, Ollama, LM Studio), route them to that app's tracker (see Framework routing) — those trackers apply regardless of platform. Otherwise relay the
```
out_of_scope
```
  message and stop.
- ```
route_when_no_match
```
  — when
```
has_match
```
  is false, hand the user this upstream tracker; do not speculate. Note the CLI picks this target from the host-detected framework, not from the symptom text — so for an app named only in the symptom, route it yourself per Framework routing.
Propose the fix. Show the top match's
```
title
```
,
```
evidence
```
, plan, and
```
verify
```
command. Only propose applying it when the user is on board.
Apply with consent. For an auto-applicable fix:
```
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
```
Only the four auto-applicable fixes are ones the CLI runs itself. The other 22 are print-only (bootloader, kernel, reinstall, Windows driver, …):
```
rocm fix <id>
```
just prints the plan for the user to run themselves — no prompt, and the CLI never performs those.
Of the four, two do not always mutate:
- fix-2-unset-override
  mutates on Windows only. On Linux it reports where the override is set and which rc files carry it, then stops — it will not edit the user's dotfiles. So there is no prompt to answer and nothing for
```
--dry-run
```
  to preview. Tell the Linux user what to edit; do not describe it as a change the CLI made or previewed.
- fix-9-igpu-dgpu
  mutates only when
  --device-index N
  is passed. Without it — on either platform — the runner just prints the
```
rocminfo
```
  /
```
hipInfo
```
  query that identifies the discrete GPU's index and returns 0; there is no prompt, no
```
--dry-run
```
  preview, and nothing is pinned. Once the user knows N, re-run with
```
rocm fix fix-9-igpu-dgpu --device-index N
```
  .
Verify. Have the user run the
```
verify
```
command from the diagnosis.

Use

rocm examine

(or

rocm examine --json

) when you only need the host state (GPU, driver, ROCm install, groups, framework) without a diagnosis.

仅当通过范围校验（即确认是AMD GPU）后，才从这里开始。Linux、Windows和WSL2均执行相同的工作流。

确保已安装
rocm
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）提供给用户后停止处理。
诊断。 将用户的错误文本作为症状传入：
```
rocm diagnose --symptom "<paste the exact error>" --json
```
读取返回的JSON：
- ```
has_match
```
  — 核心校验项。为True表示已找到符合阈值的原因，可以提出修复方案；为False表示未确认任何原因，应引导至上游渠道。不要用“
```
matched
```
  是否为空？”来替代判断：多个检查器对于仅可能相关的场景（如容器环境、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
```
  = 可能性较高（需先与用户确认更多证据）。
- ```
out_of_scope
```
  — 仅当主机的平台系列完全没有对应目录条目时才会设置。Linux、Windows和WSL2都已覆盖，因此WSL2不会触发此标志。当该标志被设置时，说明没有进行任何检查——请明确告知这一点，不要暗示机器看起来没问题。首先，如果用户的症状明确提到了自带运行时的应用（Lemonade、Ollama、LM Studio），将其引导至对应应用的问题跟踪器（参见框架路由）——这些跟踪器的适用不受平台限制。否则，转达
```
out_of_scope
```
  的提示信息后停止处理。
- ```
route_when_no_match
```
  — 当
```
has_match
```
  为False时，将此上游跟踪器链接提供给用户；不要自行推测。注意，CLI是根据主机检测到的框架来选择目标的，而非根据症状文本——因此对于仅在症状中提到的应用，请按照框架路由自行引导。
提出修复方案。 展示匹配度最高的条目的
```
title
```
、
```
evidence
```
、修复计划和
```
verify
```
命令。仅在用户同意后才执行修复。
经同意后执行修复。 对于可自动应用的修复：
```
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
```
仅有4种可自动应用的修复是由CLI自行执行的。其余22种都是仅打印方案（如引导加载程序、内核、重装、Windows驱动等）：
```
rocm fix <id>
```
只会打印修复计划供用户自行执行——不会有提示，CLI也绝不会执行这些操作。
在这4种自动修复中，有2种并不总是会修改系统：
- fix-2-unset-override
  仅在Windows上会修改系统。在Linux上，它只会报告覆盖配置的设置位置以及哪些rc文件包含该配置，然后就停止——不会编辑用户的点文件（dotfiles）。因此没有需要回答的提示，
```
--dry-run
```
  也没有可预览的内容。请告知Linux用户需要编辑的内容；不要将其描述为CLI已执行或预览的修改。
- fix-9-igpu-dgpu
  仅在传入
  --device-index N
  参数时才会修改系统。不带该参数时——无论哪个平台——运行器只会打印用于识别独显索引的
```
rocminfo
```
  /
```
hipInfo
```
  查询命令，然后返回0；没有提示，没有
```
--dry-run
```
  预览，也不会固定任何配置。当用户知道N的值后，再使用
```
rocm fix fix-9-igpu-dgpu --device-index N
```
  重新运行。
验证。 让用户运行诊断结果中的
```
verify
```
命令。

当你只需要了解主机状态（GPU、驱动、ROCm安装情况、用户组、框架）而不需要诊断时，使用

rocm examine

（或

rocm examine --json

）。

Framework routing

框架路由

rocm diagnose

covers frameworks that build against the system ROCm/HIP:

PyTorch, llama.cpp — in scope; diagnose normally.

Apps that ship their own ROCm runtime aren't diagnosed here — route the user to the right tracker. This routing is yours, not the CLI's: the host probe reports only

pytorch

llama-cpp

unknown

, so

route_when_no_match

can never name one of these apps. Use the list below.

Lemonade → https://github.com/lemonade-sdk/lemonade/issues
Ollama → https://github.com/ollama/ollama/issues
LM Studio → in-app support (no public repo)
Anything else with no catalog match → ROCm core: https://github.com/ROCm/ROCm/issues (this is what
```
route_when_no_match
```
returns by default).

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`的默认返回值）。

Out of scope

超出范围

NVIDIA / Intel / Apple Silicon GPUs, and fresh installs on a clean machine (a setup task, not a diagnosis). Exit cleanly and say so.

WSL2 is not in this list. It is a supported platform family with its own catalog entries — see reference.md.

NVIDIA / Intel / Apple Silicon GPU，以及全新机器的首次安装（属于配置任务，而非诊断）。请明确告知后正常退出。

WSL2不在此列表中。它是受支持的平台系列，有对应的目录条目——参见reference.md。

Rules

规则

Never run the workflow — or offer any troubleshooting, generic GPU fixes included — for a non-AMD GPU. State it is out of scope and stop. This does not apply to WSL2, which is in scope and runs the normal workflow.
Never invent a fix. If
```
rocm diagnose
```
returns no match, route upstream.
Never run a mutating fix without the user's explicit OK; prefer
```
--dry-run
```
first. New failure modes are added to the CLI catalog, not improvised here.

See reference.md for the full closed catalog and the CLI command/exit-code reference.

对于非AMD GPU，永远不要执行工作流——也不要提供任何故障排查建议，包括通用GPU修复方案。只需说明超出范围后停止处理。此规则不适用于WSL2，WSL2在处理范围内，可执行正常工作流。
永远不要自行发明修复方案。如果
```
rocm diagnose
```
没有返回匹配结果，引导至上游渠道。
未经用户明确同意，永远不要执行会修改系统的修复；优先使用
```
--dry-run
```
预览。新的故障模式会被添加到CLI目录中，请勿在此处临时发挥。

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