基本简介
DCGM Diagnostics是NVIDIA Data Center GPU Manager中的主动式GPU诊断与验证工具，官方文档注明它源自NVIDIA Validation Suite（即NVVS）。当前推荐入口是dcgmi diag，独立运行的NVVS已不再作为主推方式持续维护。
它不是单纯读取GPU温度、功耗和利用率的监控命令，而是通过DCGM、NVML、CUDA和一组诊断插件，对GPU、驱动、运行时、PCIe、NVLink、显存、计算单元以及功耗与温度的稳定性进行主动测试。测试结果可以输出为终端文本、JSON和日志，便于接入巡检脚本、集群调度器或故障处理流程。
需要先明确它的边界：DCGM Diagnostics不是持续采集型监控系统，也不是完整硬件维修诊断或RMA判定流程。官方文档明确说明，它不负责主动修复问题，也不能替代现场硬件诊断工具。更合理的定位是：在GPU节点投入生产前、作业失败后、硬件更换后或维护窗口中，主动验证节点是否具备稳定运行AI训练、推理和HPC任务的条件。
DCGM Diagnostics的官方介绍地址：https://docs.nvidia.com/datacenter/dcgm/latest/user-guide/dcgm-diagnostics.html
主要解决的问题
在AI算力集群中，很多GPU问题并不会在空闲状态下暴露。例如驱动和CUDA库版本不匹配、PCIe链路降速、NVLink通信异常、显存错误、功耗上不去、温度过高降频、NCCL集合通信异常等，只有在作业开始后才会表现为训练速度下降、任务失败、XID错误或节点重启。
DCGM Diagnostics主要解决以下问题：
- 上线前验证：在新节点、新
GPU或驱动升级后，验证软件栈、设备访问、显存和互联链路是否满足基本运行条件。 - 作业失败后排障：在训练任务或推理服务失败后，快速判断问题更偏向软件部署、硬件链路、显存、功耗、温度还是通信层。
- 性能和稳定性确认：通过矩阵计算、显存带宽、功耗和压力测试，发现单纯读取指标不容易暴露的降频、性能不达标和稳定性问题。
- 集群自动化巡检：通过
JSON输出、退出码、日志和命令行参数，把诊断结果接入节点准入、维护巡检或调度器健康检查流程。
显著优点
| 优点 | 说明 |
|---|---|
| 官方工具链 | 基于NVIDIA官方DCGM能力，能直接访问NVML、CUDA和GPU健康字段。 |
| 主动诊断 | 不只是查看指标，而是运行计算、传输、显存和功耗测试，用结果验证硬件和软件栈。 |
| 测试层级清晰 | -r 1到-r 4覆盖从快速检查到长时间深度测试的不同场景，高层级会包含低层级检查。 |
| 插件化能力 | software、pcie、memory、diagnostic、targeted_power、targeted_stress、memtest、pulse等插件覆盖多个故障域。 |
| 可配置 | 可通过-p覆盖单项参数，也可通过YAML配置文件按GPU SKU设置阈值和是否允许运行某个测试。 |
| 易于自动化 | 支持JSON输出、重复执行、提前失败、超时、日志和错误码处理，适合纳入集群运维流程。 |
常见问题及检测方式
DCGM Diagnostics的核心价值在于主动制造受控负载，再结合硬件计数器和运行时返回值，依据阈值判断问题。下面按常见故障域整理它的检测方式。
| 常见问题 | 相关测试 | 检测方式 |
|---|---|---|
| 软件部署异常 | software / Deployment | 检查NVML、CUDA Runtime、CUDA Main Library是否可加载，检查nouveau、设备节点、权限、cgroups、待退役页和行重映射状态。 |
PCIe链路问题 | pcie | 执行主机到设备、设备到主机、GPU间P2P带宽和时延测试，并结合PCIe重放计数、最小代际、最小链路宽度和阈值判断链路质量。 |
NVLink互联异常 | pcie / nvbandwidth | 在支持的拓扑上运行GPU间通信带宽测试，观察P2P路径、带宽、时延和链路相关错误。 |
| 显存读写错误 | memory / memtest | 分配大比例显存，写入并回读固定数据模式；memtest进一步执行地址线、移动反转、随机数、位衰减等模式测试。 |
| 计算单元异常 | diagnostic | 运行矩阵乘法和显存遍历类负载，检查计算正确性、温度、不可纠正显存错误、XID错误和性能是否达标。 |
| 温度或功耗不稳定 | targeted_power / targeted_stress | 持续施加计算压力，使功耗或吞吐接近目标值，并监控温度、时钟、PCIe重放、单比特错误和XID。 |
| 显存带宽不足 | memory_bandwidth | 使用类似STREAM TRIAD的带宽测试，比较实测带宽和配置阈值。 |
NCCL通信问题 | nccl_tests | 调用NCCL Tests二进制，检查集合通信测试的退出码和输出结果。 |
| 电源瞬态问题 | pulse | 通过短促高强度负载制造电流波动，验证系统电源是否能承受突发功耗变化。 |
测试层级
dcgmi diag -r既可以接收数字层级，也可以接收具体测试名称。数字层级适合标准化巡检，测试名称适合定向排障。
| 层级 | 定位 | 典型用途 |
|---|---|---|
-r 1 | 快速检查 | 节点上线前、作业启动前或故障后的初步筛查。 |
-r 2 | 中等耗时检查 | 作业失败后的更完整检查，适合每天或按需运行。 |
-r 3 | 长时间硬件诊断 | 新节点集成、硬件更换后、难复现故障的维护窗口排查。 |
-r 4 | 扩展深度诊断 | 包含更长时间、更高压力的测试，例如memtest和pulse，应安排在维护窗口。 |
实践中，可以把-r 1作为准入前置检查，把-r 2用于日常巡检或失败后自动排查，把-r 3和-r 4放在维护窗口中运行。原因是高层级测试会主动占用GPU资源，可能影响线上工作负载。
工具安装
参考官网文档：https://docs.nvidia.com/datacenter/dcgm/latest/user-guide/getting-started.html
DCGM Diagnostics随DCGM一起安装。安装前需要先确认主机已安装NVIDIA Datacenter Driver的受支持版本，并按官方文档配置对应发行版的软件源。官方安装说明要求选择与CUDA用户态主版本匹配的datacenter-gpu-manager-4-cudaX包，例如cuda12环境安装datacenter-gpu-manager-4-cuda12。如果节点上已经安装旧版datacenter-gpu-manager或datacenter-gpu-manager-config包，官方步骤会先删除旧包再安装新版datacenter-gpu-manager-4-cudaX包。
官方文档还列出了一些容易被忽略的前置条件：
- 主机建议至少有
16GB内存，CPU核心数不少于节点上的GPU数量。 NVSwitch系统需要额外安装并运行对应组件：Hopper及更早架构通常涉及Fabric Manager和NSCQ，Blackwell及更新架构涉及NVSDM。- 官方安装示例默认安装推荐依赖；这些推荐依赖用于补齐开源
DCGM本体之外的部分功能。 Maxwell、Pascal和Volta架构GPU在使用R580驱动或CUDA 13用户态环境时，官方文档建议安装CUDA 12对应的DCGM包，而不是CUDA 13对应的包。
以Ubuntu或Debian为例：
CUDA_VERSION=$(nvidia-smi -q | sed -E -n 's/CUDA Version[ :]+([0-9]+)[.].*/\1/p')
sudo systemctl list-unit-files nvidia-dcgm.service > /dev/null && \
sudo systemctl stop nvidia-dcgm
sudo dpkg --list datacenter-gpu-manager > /dev/null 2>&1 && \
sudo apt purge --yes datacenter-gpu-manager
sudo dpkg --list datacenter-gpu-manager-config > /dev/null 2>&1 && \
sudo apt purge --yes datacenter-gpu-manager-config
sudo apt-get update
sudo apt-get install --yes --install-recommends datacenter-gpu-manager-4-cuda${CUDA_VERSION}
sudo systemctl --now enable nvidia-dcgm
dcgmi discovery -l
常见发行版的安装命令如下，前提都是软件源已经按官方文档配置完成：
| 发行版 | 安装命令 |
|---|---|
Ubuntu / Debian | sudo apt-get install --yes --install-recommends datacenter-gpu-manager-4-cuda${CUDA_VERSION} |
RHEL / CentOS / Rocky Linux | sudo dnf install --assumeyes --setopt=install_weak_deps=True datacenter-gpu-manager-4-cuda${CUDA_VERSION} |
SLES / OpenSUSE | sudo zypper install --no-confirm --recommends datacenter-gpu-manager-4-cuda${CUDA_VERSION} |
Amazon Linux 2023 | sudo dnf install --assumeyes --setopt=install_weak_deps=True datacenter-gpu-manager-4-cuda${CUDA_VERSION} |
Azure Linux 3.0 | sudo tdnf install --assumeyes --setopt=install_weak_deps=True datacenter-gpu-manager-4-cuda${CUDA_VERSION} |
安装后建议启动nvidia-dcgm服务，它会运行nv-hostengine，dcgmi diag通过该服务访问DCGM能力。dcgmi discovery -l可以用于确认DCGM是否识别到GPU或Switch实体。官方文档建议以root权限运行诊断，尤其是涉及压力、功耗、显存和设备访问的测试。
如果需要使用DCGM的多节点诊断能力，官方文档还提供了可选包datacenter-gpu-manager-4-multinode-cuda${CUDA_VERSION}。该插件仅支持CUDA 12或更高版本，并且要求所有参与多节点诊断的主机安装相同版本的插件包；单节点dcgmi diag日常诊断不需要安装这个可选包。
使用示例
快速检查当前节点
sudo dcgmi diag -r 1
适合在节点上线、驱动升级或作业失败后先跑一遍。如果失败，优先查看失败插件名称、错误码和/var/log/nvidia-dcgm/nvvs.log。
输出JSON便于脚本解析
sudo dcgmi diag -r 2 -j
-j会把结果输出成JSON，适合被调度器、巡检系统或CI脚本解析。脚本中建议同时记录命令退出码和日志路径。
只运行指定测试
sudo dcgmi diag -r pcie,memory
当问题已经聚焦到某个故障域时，直接指定测试名称比跑完整层级更节省时间。多个测试名称可以用逗号分隔。
调整单个测试参数
sudo dcgmi diag -r targeted_power -p "targeted_power.target_power=300.0"
-p用于临时覆盖插件参数，格式通常是测试名.参数名=值。示例中的300.0只是演示值，生产环境应按具体GPU型号、散热条件和机房功耗策略设置。
重复运行并尽早失败
sudo dcgmi diag -r 3 --iterations 3 --fail-early --check-interval 5
--iterations适合排查间歇性问题。--fail-early会在长时间测试过程中周期性检查故障条件，--check-interval用于设置检查间隔。
使用自定义配置文件
sudo dcgmi diag -r 2 -c ./dcgm-diag.yaml
当同一集群中存在不同GPU SKU、不同散热条件或不同功耗策略时，建议使用配置文件统一管理阈值，而不是在命令行中堆叠大量-p参数。
多节点诊断
DCGM还有一个单独的多节点诊断功能，命令入口是dcgmi mndiag，不是dcgmi diag。它的目标是在head node上协调多个节点同步执行压力测试，验证跨节点互联、显存和计算能力。根据官方文档，当前多节点诊断支持的测试只有mnubergemm，支持版本为DCGM 4.3.0及以后，当前支持产品为GB200 NVL和GB300 NVL。
多节点诊断的前置条件更严格，至少要满足以下要求：
- 所有参与节点都安装并配置
OpenMPI。 head node到所有参与节点都要有无密码SSH访问，而且head node上的私钥需要以未加密形式存放在磁盘上。- 所有参与节点必须使用相同的
NVIDIA Driver版本。 - 如果是多节点
NVLink系统，还要先正确配置IMEX Channels，否则mnubergemm可能因为NCCL初始化失败而报错。
官方把多节点诊断的常用参数整理得很清楚：
| 参数 | 作用 |
|---|---|
--hostList | 必填，列出要参与诊断的主机，格式可以是host_name:port或host_name:socket_address。 |
--hostEngineAddress | 指定head node的hostengine地址，默认是localhost。 |
-r / --run | 指定要运行的测试名，当前只有mnubergemm，也是默认值。 |
-p / --parameters | 传入测试参数，例如mnubergemm.time_to_run=600。多个参数用分号分隔。 |
-j / --json | 以JSON格式输出结果。 |
几个简要示例：
dcgmi mndiag --hostList "node1;node2;node3"
dcgmi mndiag --hostEngineAddress 192.168.1.100 --hostList "node1:5000;node2;node3:unix:///tmp/dcgm.sock"
dcgmi mndiag --hostList "node1;node2" -p "mnubergemm.time_to_run=600" -j
这类多节点诊断适合用在大规模GPU集群联调、跨节点互联验证、整体压力测试和上线前验收，不适合和线上业务混跑。
配置方式
常用命令行参数
| 参数 | 作用 |
|---|---|
-r | 指定测试层级或测试名称，例如1、3、pcie,memory。 |
-g | 指定DCGM中的GPU组。 |
-i | 指定实体，例如具体GPU编号。 |
-c | 指定YAML配置文件。 |
-p | 覆盖某个插件参数。 |
-j | 输出JSON结果。 |
--host | 连接远端nv-hostengine。 |
--iterations | 重复执行诊断。 |
--timeout | 设置超时时间。 |
--ignoreErrorCodes | 忽略已知或预期的错误码，适合受控测试环境。 |
配置文件示例
官方配置格式使用spec: dcgm-diag-v1，可以按GPU SKU定义各插件的阈值和开关。下面是结构示例，阈值不能直接照搬到生产环境，必须结合具体GPU型号、驱动版本、机箱散热和历史基线确认。
version: "@CMAKE_PROJECT_VERSION@"
spec: dcgm-diag-v1
skus:
- name: H100 80GB PCIe
id: 2331
memory:
is_allowed: true
l1_is_allowed: true
diagnostic:
is_allowed: true
test_duration: 60.0
temperature_max: 90.0
pcie:
is_allowed: true
h2d_d2h_single_pinned:
min_pci_generation: 3.0
min_pci_width: 16.0
配置文件中常见的思路是：
- 使用
is_allowed控制某个插件是否允许在指定SKU上运行。 - 使用
temperature_max、max_pcie_replays、min_pci_generation、min_pci_width等参数表达机房和硬件基线。 - 对
targeted_power、targeted_stress等压力测试单独设定目标功耗、目标性能和持续时间。 - 对
NCCL相关测试，提前确认NCCL Tests二进制路径和集群通信环境。
环境变量与日志
| 配置项 | 作用 |
|---|---|
NVVS_BIN_PATH | 指定nvvs二进制所在目录。 |
NVVS_PLUGIN_DIR | 指定诊断插件目录。 |
NVVS_HANGDETECT_DISABLE | 禁用挂起检测。 |
NVVS_HANGDETECT_EXPIRY_SEC | 设置挂起检测超时时间。 |
DCGM_NCCL_TESTS_BIN_PATH | 指定NCCL Tests二进制路径。 |
/var/log/nvidia-dcgm/nvvs.log | 默认诊断日志路径。 |
相似工具比较
| 工具 | 定位 | 适合场景 | 短板 |
|---|---|---|---|
nvidia-smi | GPU状态查询和管理命令 | 快速查看驱动、显存、温度、功耗、进程、ECC等信息。 | 主要是点查和管理，不会主动运行完整压力和正确性测试。 |
dcgm-exporter | Prometheus指标导出器 | 持续监控GPU利用率、温度、功耗、显存、错误计数和性能指标。 | 更偏被动采集，不能单独证明节点在压力下稳定可用。 |
DCGM Diagnostics | 主动诊断和节点验证 | 上线前准入、作业失败后排查、维护窗口深度测试。 | 非连续监控，会占用GPU资源，高层级测试不适合和生产负载并行。 |
监控场景下的优点
DCGM Diagnostics在监控体系中的价值不是替代dcgm-exporter，而是补齐“指标异常之后怎么验证”和“上线前怎么证明节点可用”这两个环节。常规监控可以告诉我们温度高、功耗低、XID出现或利用率异常，但不一定能证明根因；诊断工具可以进一步施加受控负载，把软件、链路、显存、计算、功耗和通信问题分域暴露出来。
它特别适合做三类自动化：
- 准入检查：节点加入
Kubernetes、Slurm或其他调度系统前，先运行-r 1或指定测试。 - 告警后动作：当
dcgm-exporter发现XID、ECC、温度或链路异常后，自动触发定向诊断。 - 维护巡检：在维护窗口运行
-r 3或-r 4，验证更深层的稳定性问题。
监控场景下的缺点
它不适合承担持续监控职责，原因包括：
- 诊断测试是主动负载，会占用
GPU、显存、PCIe和功耗预算。 - 长时间压力测试可能干扰线上训练或推理任务。
- 阈值需要结合实际硬件基线调优，不能把官方示例阈值无差别套到所有机型。
- 某些插件和参数与
GPU架构、SKU、驱动和部署方式相关，需要以当前版本官方文档和本机dcgmi diag --help为准。 - 官方明确说明它不是完整硬件诊断、自动修复或
RMA替代流程。
因此，推荐的组合是：dcgm-exporter负责持续采集和告警；nvidia-smi负责临时人工点查；DCGM Diagnostics负责上线前验证、告警后定向排查和维护窗口深度诊断。
常见问题
DCGM Diagnostics是免费工具还是收费工具？
DCGM Diagnostics本身不需要单独购买工具许可证，也不需要额外的商业授权密钥。它随DCGM一起分发，NVIDIA官方页面将DCGM描述为可独立使用、也可集成到集群管理、资源调度和监控产品中的工具套件；NVIDIA/DCGM源码仓库也标明项目源码采用Apache-2.0许可。
需要注意的是，这并不意味着”所有相关能力都不受任何商业条款约束”。实际生产使用仍受NVIDIA Driver、GPU硬件支持范围和NVIDIA软件许可条款约束；企业级支持、DGX服务、云厂商托管服务、硬件维保和商业技术支持属于另外的商业服务范畴。
已有任务占用GPU时，还能同时运行诊断吗？
不建议在同一张正在承载生产任务的GPU上运行完整DCGM Diagnostics。原因是DCGM Diagnostics并不是纯读取指标的轻量探针，它包含会主动占用GPU、显存、PCIe、NVLink和功耗预算的测试，例如targeted_power、targeted_stress、memtest、pulse和nvbandwidth。这些测试可能干扰正在运行的训练或推理任务，也可能因为已有业务负载导致诊断结果失真。
官方文档中也能看到相关约束：DCGM Diagnostics被定位为工作负载部署前的就绪度评估工具；nvbandwidth测试还明确包含运行前检查，如果当前MCUTIL超过10%，测试会失败。因此，生产环境中更稳妥的做法是把完整诊断放到节点准入、维护窗口、作业失败后隔离排查等场景中执行。
如果同一台主机上只有部分GPU被占用，可以使用-i指定空闲GPU，或者使用-g指定DCGM中的GPU组，只对空闲卡运行诊断。例如：
sudo dcgmi diag -r 1 -i 2
如果目标是在线观察运行中任务的健康状态，应优先使用dcgm-exporter、Prometheus、nvidia-smi等被动监控方式，而不是把完整dcgmi diag当作在线健康探针。