# Kernodeck PyTorch 诊断 — 版本 1.0.0

该脚本用于验证一个小型 PyTorch 计算及其梯度能否在指定设备上执行。它会生成一份仅包含有用技术字段的 JSON 报告。默认情况下，它要求使用 GPU；CPU 检查必须显式请求。

它不会启动任何训练，不会测量任何吞吐量，也不会对商业方案、训练能力或机器的长期稳定性作出任何认证。其原始代码以 [MIT 许可证](kernodeck-diagnostic-v1-LICENSE.md) 提供。

## 准备与运行

下载[脚本](kernodeck-diagnostic-v1.py)，然后在其所在文件夹中打开终端。使用你工作环境中的 Python，并确保已安装 PyTorch。该脚本使用 Python 3.10 或更高版本的标准库；实际受控的环境详见下文。不会安装或修改任何驱动程序。

```sh
python kernodeck-diagnostic-v1.py
```

该命令会选择 PyTorch 可见的第一个 GPU。如果缺少 PyTorch、GPU 后端或可用设备，它会以非零退出码失败。它不会回退到 CPU。

若仅验证 CPU 上的计算：

```sh
python kernodeck-diagnostic-v1.py --device cpu
```

若要选择一个可见的 GPU 并将报告保存到新文件：

```sh
python kernodeck-diagnostic-v1.py --device-index 0 --output diagnostic.json
```

输出路径由你选择，不会出现在报告中。已存在的文件绝不会被覆盖。若不使用 `--output`，脚本不会创建任何文件。你可以在 PowerShell 中用 `$LASTEXITCODE` 读取退出码，或在 POSIX shell 中用 `echo $?` 读取。

如果导入 PyTorch 需要更长时间，请在规定上限内增加超时时间：

```sh
python kernodeck-diagnostic-v1.py --timeout 60
```

| 公开选项 | 取值与效果 |
| --- | --- |
| `--device gpu` | 默认值；要求有可用的 CUDA 或 ROCm GPU。 |
| `--device cpu` | 显式进行 CPU 计算；不验证 GPU 驱动的可见性。 |
| `--device-index N` | PyTorch 可见的索引，介于 0 与 63 之间；默认为 0。对 CPU 计算无效。 |
| `--timeout N` | 计算子进程的超时时间，介于 5 与 120 秒之间；默认为 30。 |
| `--host-check` | 可选的 NVIDIA 读取，额外限制为 3 秒。 |
| `--output FICHIER` | 同时将 JSON 写入一个新的 UTF-8 文件。 |
| `--help` | 显示帮助，不导入 PyTorch。 |

下载内容不包含 PyTorch、CUDA、ROCm 或其驱动程序。若要选择适合你系统的安装方式，请从[PyTorch 官方选择器](https://docs.pytorch.org/get-started/locally/)开始。在另一台机器上有效的安装并不能证明你的 GPU 兼容。

## CUDA、ROCm 与主机检查

脚本会先检查 `torch.version.hip`，再检查 `torch.version.cuda`。ROCm 软件包会被识别为 `rocm`，即使其 CUDA 值为 `null`。PyTorch 在 ROCm 上同样使用 `torch.cuda` 和设备名 `cuda`：因此报告中出现 `execution.device: "cuda:0"` 本身并不代表是 NVIDIA 显卡。还应查看 `execution.backend`。[PyTorch 的 HIP 文档](https://docs.pytorch.org/docs/2.14/notes/hip.html)

`torch.cuda.is_available()` 表示 CUDA 当前是否可供 PyTorch 使用。脚本通过指定设备上的一次计算、其梯度以及一次同步来补充这一观察。它不会推断真实模型是否能装入内存。[可用性](https://docs.pytorch.org/docs/2.14/generated/torch.cuda.is_available.html) · [同步](https://docs.pytorch.org/docs/2.14/generated/torch.cuda.synchronize.html)

使用 `--host-check` 时，会另行调用一条 NVIDIA 命令，仅请求驱动版本和以 MiB 为单位的总内存。其输出必须遵循严格的数字格式。缺少 `nvidia-smi`、超时或输出格式未知，都不会使一次成功的计算失效。此读取不构成 AMD 主机诊断，也不是 CPU 检查所必需的。它可能会看到 PyTorch 进程看不到的显卡；主机列表不会与 PyTorch 索引配对。[NVIDIA 选择性查询](https://docs.nvidia.com/deploy/nvidia-smi/index.html)

对于 AMD，GPU、系统、驱动和库的版本必须构成受支持的组合。本脚本不能替代 [ROCm 官方兼容性矩阵](https://rocm.docs.amd.com/en/latest/compatibility/compatibility-matrix.html)。

## 读取 JSON

该结构在版本 1 中保持稳定：

| 字段 | 含义 |
| --- | --- |
| `schema`、`script_version` | 脚本的格式和版本。 |
| `requested_device` | `gpu` 或 `cpu`；如果参数无效或执行中断，则为 `unspecified`。 |
| `status`、`code`、`exit_code`、`message` | 整体结果、稳定代码、进程代码和固定说明。 |
| `stage` | 最后到达的步骤：导入、检测、可见性、分配、计算、梯度、同步、验证等。 |
| `runtime` | 所用 Python 的数字版本和系统家族；不含任何机器标识符。 |
| `pytorch` | 过滤后的软件包版本、CUDA/HIP 编译版本、声明的后端，以及被查询时的 GPU 可见性。如果 PyTorch 无法导入，则为 `null`。 |
| `execution` | 实际选择的设备、过滤后的 GPU 型号、PyTorch 报告的总内存、类型、矩阵形状以及各项检查的结果。如果计算未准备就绪，则为 `null`。 |
| `host_check` | 仅在请求时出现：NVIDIA 读取状态以及每张显卡的两个数值字段。 |

在 CPU 模式下，`pytorch.backend` 可能是 `cuda`，因为它描述的是已安装的软件包。`execution.backend` 仍为 `cpu`，描述的是实际执行的计算。此时 GPU 可用性、GPU 数量、GPU 型号和 GPU 内存均为 `null`：它们未被测量。

该检查将两个 2×2 矩阵以 `float32` 相乘，验证乘积 `[[4, 4], [10, 8]]`，然后验证梯度 `[[16, 24], [40, 52]]`。预期的平方和为 `196.0`。这里的小整数可实现精确比较；这一特性并不保证任何模型的逐位可复现性。验证使用 [`torch.equal`](https://docs.pytorch.org/docs/2.14/generated/torch.equal.html)。创建 GPU 上下文可能比矩阵本身消耗更多内存。

`total_memory_bytes` 是报告容量，而非您未来模型可用的空闲或可用内存。本脚本既不测量训练的最大内存，也不测量互连、速度或多 GPU。

## 理解失败

| 输出 | JSON 代码 | 解读与下一步检查 |
| --- | --- | --- |
| 0 | `CPU_CHECK_PASSED` / `GPU_CHECK_PASSED` | 在指定设备上，小型计算及其梯度正确。 |
| 2 | `CLI_ARGUMENTS_INVALID` | 请重新阅读 `--help`；无效值不会被复制。 |
| 3 | `TORCH_MISSING` | 此 Python 中缺少 PyTorch。请确认您选择了正确的环境。 |
| 4 | `TORCH_IMPORT_FAILED` | PyTorch 存在但导入失败；请检查软件包及其依赖项。 |
| 5 | `GPU_BACKEND_ABSENT` | 该软件包既未声明 CUDA 也未声明 HIP。请选择适配的发行版，或明确指定 CPU。 |
| 6 | `GPU_UNAVAILABLE` | 该软件包声明了 GPU 后端，但此进程中看不到任何可用的 GPU。请检查设备访问权限和环境兼容性。 |
| 7 | `DEVICE_INDEX_INVALID` | 请求的索引不在 PyTorch 可见的列表中。 |
| 8 | `CHECK_FAILED` | 计算或梯度与预期的固定结果不符。 |
| 9 | `OUT_OF_MEMORY` / `RUNTIME_ERROR` | 无法分配或后端错误；`stage` 指明具体步骤，但不导出原始异常。 |
| 10 | `TIMEOUT` | 子进程已超时并被停止。 |
| 11 | `WORKER_FAILED` | 子进程未提供有效报告。 |
| 12 | `OUTPUT_WRITE_FAILED` | 文件已存在或无法访问；请选择新名称。即使之前的计算成功，整体状态仍为失败。 |
| 130 | `INTERRUPTED` | 检查已被中断。 |

不要为解释失败而传输完整的环境转储。报告中的代码和步骤构成初步判断；如果需要更精确的调查，请在分享数据之前先在您的环境中进行检查。

## 数据与限制

该脚本不执行任何网络请求，也不向Kernodeck传输任何内容。它不会读取您的notebook、数据集、账户、付款或checkpoint。它不会收集环境变量、软件包列表、主机名、用户名、个人路径、序列号、UUID、GPU进程或令牌。

Python版本、系统家族、技术版本、经过筛选的GPU型号和显存容量可能泄露您硬件环境的部分信息。分享前请先检查报告。PyTorch和驱动的原始消息不会被照抄；无法识别的版本或型号会变成中性值。因此报告可能遗漏某个合法标签。

超时限制的是检查子进程，而不是系统或驱动的运行。该脚本不会修复环境，不会验证专用内核，也不能替代您对自身工作负载的试运行。未对任何恶意或被篡改的第三方软件进行评估。

## 2026年9月24日实际执行的检查

以下示例是脚本实际生成的最小化报告，不含原始异常或机器标识符。它们针对的是检查环境，并不描述Kernodeck目录中的任何产品。

| 执行用例 | 环境 | 结果 |
| --- | --- | --- |
| 显式CPU | Windows、Python 3.14.6、PyTorch 2.11.0+cu128 | 乘积与梯度已验证；损失`196.0`。[CPU JSON](kernodeck-diagnostic-v1-cpu-example.json) |
| 默认GPU | 同一环境、CUDA 12.8编译、NVIDIA GeForce RTX 5070 | 在`cuda:0`上验证乘积与梯度；损失`196.0`。[CUDA JSON](kernodeck-diagnostic-v1-cuda-example.json) |
| 缺少PyTorch | Windows、Python 3.12.14、无PyTorch | `TORCH_MISSING`，退出码3。[失败JSON](kernodeck-diagnostic-v1-torch-absent-example.json) |
| GPU仅对测试进程不可见 | Python 3.14.6及上述CUDA包 | `GPU_UNAVAILABLE`，退出码6。 |
| 缺少索引、参数无效、文件已存在 | 独立的检查进程 | 退出码7、2和12；已存在的文件被保留。 |

该测试套件共包含44项检查，混合了上述实际执行与隔离的单元测试。单元测试主要覆盖无GPU后端的软件包、HIP检测、后端错误、超时以及字段筛选。它们不构成ROCm硬件执行。**本次测试未运行任何AMD/ROCm GPU。** 检查环境中可以导入NumPy 2.4.4，但脚本并未直接导入它。

[所查阅的源及其作用](kernodeck-diagnostic-v1-SOURCES.md)区分了文档版本与实际使用的版本。[SHA-256清单](kernodeck-diagnostic-v1-manifest.json)描述了本次交付的文件。指纹可以检测文件差异；它们不是作者签名。


## Kernodeck呈现与报告兼容性

自2026年9月25日起，呈现方式、文件名和命令帮助均带有Kernodeck品牌标识。JSON架构的技术标识符对现有读者保持稳定。上述三份示例报告作为2026年9月24日执行的运行结果按字节保留。它们的存在并不构成对该呈现方式的重新执行。清单将此次再版与历史检查区分开来。