PyTorch 看不到 GPU：按正确顺序进行诊断

四个决策点的诊断流程

目标是找到第一个失败的环节，而不是接连尝试多次安装。请保留执行过的命令、第一条报错信息以及每次检查的结果。如果你同时改动 Python、PyTorch 软件包和 batch 大小，就无法判断到底是哪项改动解决了问题。

可下载的脚本会按这一顺序执行，并生成一份范围有限的技术报告。它不会启动你的模型，也不会修改你的安装。请在与项目相同的环境中使用它，否则你检查的将是与出故障程序不同的解释器。

左右滚动表格即可查看所有列。

在第一个失败的步骤处停下。
检查项	如果检查失败	通过后能做什么
1. 解释器与导入	修正所使用的 Python 或其 PyTorch 安装。	读取实际导入的软件包版本和后端。
2. 后端与设备	检查软件包、驱动、GPU 是否暴露以及权限。	在目标 GPU 上申请分配。
3. 小规模 GPU 计算	保留分配、计算或同步时的报错。	改用应用的缩减输入。
4. 代表性应用	排查权重、扩展、格式、内存或输出不正确的问题。	逐步增加实际工作量。

1. 确认实际运行的 Python

终端、notebook 和服务可能使用不同的解释器。在启动项目的上下文中显示 sys.executable，然后检查版本。通过路径可以发现被遗忘的虚拟环境，或仍停留在另一个内核上的 notebook。请在本机查看即可；没有必要把个人目录结构发布到报告中。

接下来用同一个解释器查询软件包。命令 python -m pip show torch 会给出与该 Python 关联的 PyTorch 信息。如果 import torch 失败，下一步就是修正这个安装：减小 batch 或更换模型权重都无法解决模块缺失的问题。

请在与项目相同的环境中运行

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 矩阵，验证它们的乘积，然后验证一个梯度并同步 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. 从小规模计算过渡到你的应用

在启动之前，请准备好一条可复现的命令、一个已确定身份的模型、一个小型数据集以及一个可访问的输出目录。请选择能够保留最终工作关键特征的输入：文本长度、图像尺寸、音频格式或必填字段。人为缩短的输入可能会掩盖你希望观察的问题。

编写一个具体的成功标准。对于嵌入计算，每个输入标识符都必须返回一个维度符合预期、且取值有限的向量。对于训练，一个步骤必须产生可用的损失、更新预期参数并支持保存。进程的退出码是对这些检查的补充，而不能替代它们。

在读取参数、导入库、加载权重、准备数据、传输数据、计算和写入的前后都添加标记。为每次试验分配一个标识符，并保留相关参数。一条“模型已加载”的消息应对应于一个已完成的事件，而不只是加载的意图。

记录有用张量的形状、类型和设备，无需复制整个数据集。像「输入：8 个序列，最大长度 512，设备 cuda:0」这样的摘要有助于比较两次试验。这里的数字描述的只是日志示例，并非通用配置。避免在这些消息中放置访问令牌或输入的敏感内容。

6. 在正确的层面修复错误

如果小规模计算通过但找不到权重，请检查其路径、格式和访问权限。如果某个扩展导入失败，请检查它与 PyTorch 包及项目后端的兼容性。一次成功的诊断并不能说明应用的所有扩展都没问题。从第一个失败的步骤重新开始，而不是同时更改多个依赖项。

设备错误可能源于输入仍留在 CPU 上，而模型已在 GPU 上。类型错误可能源于部分转换，或运算符与所选精度不兼容。保留第一条完整的消息及其堆栈跟踪。每次只修改一个假设，然后重新运行最小输入，再重新引入最终数据量。

7. 如果模型启动后耗尽内存

判断超限发生在加载权重时、首次计算时还是多次迭代之后。这些时点指向不同的原因：模型过大、激活或生成缓存过大、保留的张量不断累积。在相同的步骤记录 torch.cuda.memory_allocated() 和 torch.cuda.memory_reserved()。前者跟踪张量的分配；后者涵盖由分配器管理的内存。

torch.cuda.empty_cache() 可以释放未使用的缓存，但不会删除仍被引用的张量。因此要检查输出列表、损失历史以及保留计算图的对象。然后减小批次或输入长度，以找出决定性因素。当你了解哪个阶段超限以及实际需要的余量时，更换显卡就成了有依据的决定。

8. 测量计算时不要忽略异步性

GPU 操作可能相对于 Python 程序是异步的。因此，围绕某个调用放置的计时器可能主要测量的是工作的发送。用于诊断测量时，请在所观察片段的边界同步 GPU，或使用合适的事件。这种同步会改变执行流程：请将此插桩与应用的正常运行保持分离。

构建一个简单的示例，包含三个片段：输入准备、计算、输出写入。对于 GPU 片段，调用 torch.cuda.synchronize()，读取 time.perf_counter()，执行计算，再次同步，然后计算差值。将首次运行和后续运行分开保存。加载或初始化不应被淹没在被称为完整响应时间的平均值中。

PyTorch：同步与 GPU 计算计时

9. 检查输出并保留可复用的诊断

对于常规推理，model.eval() 设置相关模块的行为，而 torch.inference_mode() 则禁用梯度所需的跟踪。这两种设置的功能不同。当生成的张量后续不应参与带梯度的计算时，请使用后者。训练过程中的模型评估需要在恢复训练前显式地重新设置正确的模式。

现在将输出与准备好的约定进行比较：结果数量、标识符对应关系、维度、有限值以及相应的业务指标。如果增大 batch，请再次检查这种对应关系。如果添加 GPU，请检查输入的分配和输出的收集。租赁批次指的是订购的显卡；batch 指的是程序一起处理的样本。

此方法的结果是一个小文件夹：命令、版本、参数、最小输入、最后一个成功步骤、第一个错误、内存观察结果和获得的输出。如果启动成功，请保留此文件夹作为增加负载前的比较基准。如果启动失败，它可以复现问题，而无需重新开始整个排查。

在进行长时间处理之前，还要在这个小输入集上执行一次正常停止和恢复。检查已写入的输出既未丢失也未重复计算。通过这些检查后，逐步增加单一维度——batch、长度、并发数或进程数——并记录观察到的上限。这样你得到的是针对自己应用的实测运行范围，而不是基于 GPU 名称的猜测。

所提供的证据及其局限性

可下载的示例来自 2026 年 9 月 24 日进行的真实测试。两次 PyTorch 运行使用 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。