gpu-xid

GPU Xid 错误：从内核日志定位到硬件复检的排障路径。

现象

训练或推理进程突然退出、卡住，容器反复重启；dmesg 或 journalctl -k 出现 NVRM: Xid 日志；严重时 nvidia-smi 里少了某张卡，或者整机 GPU 查询直接失败。典型日志形态如下：

NVRM: Xid (PCI:0000:3b:00): <编号>, pid=<PID>, name=<进程名>

Xid 是 NVIDIA 驱动检测到 GPU 异常时打印的错误码，它表示“症状”，而不是根因。同一个 Xid 可能来自应用非法访存、驱动与内核不匹配、显存或 NVLink 硬件故障，也可能只是散热和供电问题。不同编号的含义与处置建议会随 GPU 架构和驱动版本变化，必须查 NVIDIA 官方 Xid 文档与 Catalog，本文不逐号解释。

监控侧通常先在 DCGM_FI_DEV_XID_ERRORS 指标、系统日志或 nvidia-smi -q 的健康字段里发现异常。单次 Xid 不一定致命，但同一张卡重复出现、伴随 ECC 计数增长或掉卡时，应按硬件故障处理。

快速判断

先取现场，不要急着重启：

# 最近的内核日志，定位 PCI 地址、PID 和编号
dmesg -T | grep -i -E 'NVRM|Xid'
journalctl -k --since '24 hours ago' | grep -i -E 'NVRM|Xid'

# GPU 是否还在、ECC 与 Xid 线索
nvidia-smi -L
nvidia-smi -q -d ECC,PAGE_RETIREMENT,ROW_REMAPPER
nvidia-smi -q | grep -i -E 'xid|ecc|remapped|retired|pending'

第一条命令先看三件事：出错的 PCI 地址对应哪张卡、进程 PID 是谁、错误是否在重复。然后回答四个问题：

1. 是单卡还是多卡同时报错？单卡更像该卡或该进程的问题；多卡同时报错要怀疑驱动、固件、供电或 NVSwitch/Fabric Manager。
2. 错误能否复现？固定输入、固定进程能复现，优先查应用和 CUDA 代码；随机出现、负载越高越频繁，优先查硬件和散热。
3. GPU 还在不在？nvidia-smi -L 少卡、lspci 看不到设备，属于掉卡级别，直接按硬件故障走。
4. ECC、Retired Pages、Row Remapper 是否在增长？增长说明显存可能已经出现可纠正或不可纠正错误，不能只重启了事。

按下表先做粗分类，再进入排查步骤：

常见原因

按概率从高到低，常见有五类。

应用与框架

越界访存、非法指针、kernel 启动参数错误、使用了与当前 GPU 架构不匹配的编译产物，都会触发驱动侧异常。自定义 CUDA/Triton 算子、量化 kernel、第三方加速库是重灾区。此类问题通常与特定输入强相关，换一张卡、换一个进程仍能复现。

驱动、内核与容器

内核升级后 NVIDIA 内核模块没有同步重建、驱动安装不完整、容器内用户态库与宿主机驱动版本不一致、nvidia-container-toolkit 配置错误，都可能让 GPU 在初始化或运行中报错。多卡机型还要检查 Fabric Manager 是否在驱动加载后正常启动，版本是否与驱动匹配。

硬件：显存、供电、PCIe

显存颗粒故障、GPU 掉卡、PCIe 链路错误或降速、供电不足、散热不良都会以 Xid 形式暴露。ECC 可纠正错误持续增长、Row Remapper 触发、Retired Pages 增加，都是需要下线复检的信号。

NVLink、NVSwitch 与拓扑

多卡训练中 NVLink 链路错误、NVSwitch 或 Fabric Manager 异常，可能表现为通信报错后伴随 Xid。此时只看单卡状态不够，要同时查 nvidia-smi nvlink -e、Fabric 状态和相关服务日志。

配置与环境

超频、功耗墙设置、风扇策略、MIG 切分、IOMMU 与 P2P 配置、共享 GPU 的显存争抢，都可能让原本正常的卡进入异常状态。这类问题往往在变更后出现，回滚变更即可验证。

排查步骤

第一步：固定现场

在重启前收集：

sudo nvidia-bug-report.sh
nvidia-smi -q > /tmp/nvidia-smi-q.txt
dmesg -T > /tmp/dmesg.txt
journalctl -k --since '24 hours ago' > /tmp/kernel-xid.txt
nvidia-smi --query-gpu=index,pci.bus_id,name,memory.used,temperature.gpu,power.draw \
  --format=csv > /tmp/gpu-snapshot.csv

nvidia-bug-report.sh 会打包驱动、拓扑、日志和配置，是提交 NVIDIA 支持或内部复检的标准材料。若机器还能登录，先保留现场再决定是否重启。

第二步：确认是否掉卡

nvidia-smi -L
lspci -nn | grep -i nvidia

nvidia-smi 少卡但 lspci 仍在，可能是驱动状态异常；两者都看不到，优先怀疑 PCIe 链路、供电或硬件。掉卡场景不要反复热重启，按厂商流程冷启动并复检。

第三步：分清应用问题和硬件问题

• 用同一份代码在另一张卡或另一个节点复现。换卡仍复现，问题更可能在应用；只在原卡复现，问题更可能在硬件。
• 对可疑 kernel 运行 compute-sanitizer，定位越界访存和非法访问：

compute-sanitizer --tool memcheck python train_step.py

• 临时设置 CUDA_LAUNCH_BLOCKING=1 让报错定位到具体 kernel，但它会显著拖慢训练，只用于定位。
• 查看进程退出码、Python traceback 和框架日志，确认是 CUDA 报错、NCCL 报错还是直接被信号杀死。

第四步：检查显存与硬件健康

nvidia-smi -q -d ECC
nvidia-smi -q -d PAGE_RETIREMENT
nvidia-smi -q -d ROW_REMAPPER
nvidia-smi nvlink -s
nvidia-smi nvlink -e
nvidia-smi -q -d TEMPERATURE,POWER,PERFORMANCE

关注三点：ECC 计数是易失计数还是累计计数、复检前后是否继续增长；是否有 retired page 或 row remap；NVLink 错误计数在空闲时是否仍增长。温度长期贴近上限、功耗频繁触顶，也要纳入硬件排查。

第五步：检查驱动、固件与 Fabric

nvidia-smi --query-gpu=driver_version --format=csv,noheader
cat /proc/driver/nvidia/version
systemctl status nvidia-fabricmanager
journalctl -u nvidia-fabricmanager --since '24 hours ago'
nvidia-smi -q | grep -i -A5 fabric

在带 NVSwitch 的机器上，Fabric Manager 未运行或版本不匹配会导致 NVLink 初始化异常，进而出现训练报错和 Xid。驱动、CUDA、Fabric Manager、容器工具链要按兼容矩阵成套升级，不要只动其中一个。

第六步：隔离与压测

把可疑卡从调度中摘除，单独做健康检查：

CUDA_VISIBLE_DEVICES=<index> gpu_burn 1800
dcgmi diag -r 3

gpu_burn 用来观察高负载下的温度和降频，dcgmi diag 覆盖更完整的硬件自检。压测通过不代表问题一定在应用：还要用原业务负载复跑，因为只有真实显存访问模式才能复现某些错误。

第七步：对照官方编号说明

拿到 Xid 编号后，查 NVIDIA Xid Errors 文档和 Xid Catalog，确认该编号对应的建议动作。不同架构、不同驱动版本对同一编号的解释可能不同，不要在团队内凭记忆口口相传。文档建议送修的，不要靠重启和降频硬撑。

修复与验证

按定位结果分别处理。

• 应用问题：修复越界访问和错误的 kernel 参数，把 compute-sanitizer 加入 CI 的 GPU 冒烟测试；升级已知有问题的框架或算子库，并在相同输入上回归。
• 驱动与容器问题：重装与内核匹配的驱动，重建内核模块后重启；统一宿主机驱动、容器镜像和 toolkit 版本；确认 Fabric Manager 在驱动之后启动且版本匹配。
• 硬件问题：按厂商流程下线、报修或更换 GPU、转接卡、线缆和电源；修复后重新跑 dcgmi diag、gpu_burn 和业务回归。
• NVLink/Fabric 问题：在无训练任务时重启 Fabric Manager，复检 nvidia-smi nvlink -e；链路错误仍增长则检查线缆、背板和 NVSwitch。
• 散热与供电问题：清理风道、修复风扇、调整机房温度，确认功耗和温度在高负载下不触顶。

验证至少覆盖四层：

1. 系统层：重启后 nvidia-smi -L 能识别全部 GPU，空载和压测后 dmesg 都没有新的 Xid。
2. 硬件层：ECC、Retired Pages、Row Remapper 和 NVLink 错误计数在压测前后保持稳定。
3. 通信层：多机多卡跑 nccl-tests，busbw 与故障前基线一致。
4. 业务层：用原训练或推理任务复跑，完成至少一个完整周期，原来出错的 step 不再复现。

只有四层都通过，才把节点重新加入调度。仅“重启后能起来”不构成修复验证。

预防

• 建立 Xid 监控：用 DCGM Exporter 采集 DCGM_FI_DEV_XID_ERRORS，同时监控 ECC、温度、功耗和 NVLink 错误，按卡设置告警而不是只看集群总量。
• 固化版本矩阵：驱动、CUDA、NCCL、Fabric Manager、容器 toolkit 和框架版本成套管理，升级前查兼容矩阵并在灰度节点验证。
• 管住内核升级：GPU 节点关闭无人值守的内核升级，或把驱动重建纳入升级流程，避免重启后模块不匹配。
• 上线前做健康检查：新节点先跑 dcgmi diag、gpu_burn 和 nccl-tests，通过后再打上可调度标签。
• 保留故障现场：把 nvidia-bug-report.sh、内核日志和 DCGM 指标纳入自动化采集，避免重启后证据丢失。
• 建立下线阈值：同一张卡在时间窗口内重复出现 Xid、ECC 持续增长或压测不通过时，自动 cordon 并通知硬件团队。
• 应用侧设防：对自定义 kernel 做 sanitizer 测试，对长任务加检查点和自动重试，降低单卡故障对整体作业的影响。

相关命令

• nvidia-smi — 查看 GPU、ECC、Xid、拓扑与进程。
• dcgm-exporter — 采集 Xid、ECC 与温度指标。
• dcgm — 运行诊断和健康检查。
• gpu-burn — 高负载压测与散热验证。
• nvidia-fabricmanager — NVSwitch 路由服务与 NVLink 状态。
• gpu-topology — 判断 GPU、网卡与 NUMA 连接关系。
• GPU Operator — Kubernetes 节点上的 GPU 驱动与监控栈。

参考链接

• NVIDIA Xid Errors
• NVIDIA GPU Debug Guidelines
• NVIDIA DCGM 文档

读完自测

合上页面，先回答，再展开对照。

1. 看到 Xid 后，重启前应先记录哪些信息？为什么不能直接重启？
2. 同一份代码换卡仍复现，与只在原卡复现，分别说明什么？
3. 修复后至少要验证哪几层，才算通过？