MTDCGM 常见问题（FAQ）
本页解答 MTDCGM 安装、连接、监控、诊断和集成过程中的常见问题。有关主要功能、常见操作和命令示例，参见 MTDCGM 功能概述。
安装和连接
如何确认当前环境是否支持 MTDCGM？
先在 MTDCGM 快速入门 中核对处理器架构、操作系统、GPU、驱动、MUSA Toolkit、MTML 和 MTBIOS 版本。不同 MTDCGM 版本的支持范围可能变化，安装指定版本前还应查看对应发布说明。
不要只核对操作系统。GPU、驱动、MUSA Toolkit、MTML 和 MTBIOS 中任一组件不兼容，都可能导致安装后无法发现 GPU 或诊断失败。
应该选择在线安装还是离线安装？
- 全新 Ubuntu 22.04 x86_64 Server 环境优先使用 APT 在线安装；
- 受控或无网络环境，以及需要安装指定版本时，使用 DEB 或 RPM 离线安装包；
- 系统中存在旧版本时，先按照原安装方式卸载，再安装新版本。
详细步骤请参见 MTDCGM 快速入门。
为什么终端提示找不到 dcgmi 或 MTDCGM 动态库？
确认已配置 MTDCGM 和 MUSA Toolkit 的命令及动态库路径：
export PATH=/usr/local/musa/bin:/usr/local/mtdcgm/bin:${PATH}
export LD_LIBRARY_PATH=/usr/local/musa/lib:/usr/local/mtdcgm/lib/x86_64-linux-gnu:${LD_LIBRARY_PATH}
诊断功能需要在启动 Host Engine 前读取这些环境变量。如果先启动了 Host Engine，配置环境变量后应按照部署方式重新启动服务。完整首次使用流程请参见 MTDCGM 快速入门。
dcgmi 为什么无法连接 Host Engine？
先确认 Host Engine 进程是否存在：
pgrep -a mt-hostengine
如果进程不存在，按照当前部署方式启动 mt-hostengine。如果进程存在，继续检查：
- Host Engine 启动前是否已配置动态库路径；
dcgmi使用的主机名、IP 地址、端口或 Unix Domain Socket 是否正确；- 当前用户是否具有设备和服务端点访问权限；
/var/log/mt-hostengine.log是否包含库加载、权限或监听错误。
需要收集 DEBUG 日志时，请参见 诊断工具故障排查。
dcgmi discovery -l 未显示预期的 GPU，怎么办？
先分别检查本机 GPU 可见性和 MTDCGM 设备发现：
mthreads-gmi
dcgmi discovery -l
mthreads-gmi未发现预期的 GPU，或只发现部分 GPU：优先检查驱动、设备状态和内核日志，记录缺失设备的 PCIe 信息、GPU ID 和 XID；mthreads-gmi可以发现预期 GPU，但dcgmi不能：GPU 对本机可见，不属于掉卡；继续检查 Host Engine、动态库路径、权限和版本兼容性。
需要按故障范围继续排查时，请参见 GPU 故障排查。
GPU 管理和监控
mthreads-gmi 和 dcgmi 应该分别在什么场景使用？
mthreads-gmi：适合查询本机 GPU、驱动、进程、拓扑和设备状态，并执行设备管理操作；dcgmi：通过 Host Engine 提供 GPU 分组、字段监控、健康检查和诊断等数据中心管理能力。
排查 GPU 是否对本机可见时，以 mthreads-gmi 的结果为准。mthreads-gmi 正常而 dcgmi discovery -l 异常时，应按 MTDCGM/Host Engine 问题排查，不要判定为掉卡。dcgmi 的常用命令请参见 MTDCGM 功能概述。
GPU Group 和 Field Group 有什么区别？
- GPU Group：一组需要统一管理、监控或诊断的 GPU；
- Field Group：一组需要重复采集的监控字段。
例如，可以先创建包含 GPU 0 和 GPU 1 的 GPU Group，再创建包含温度、功耗等字段的 Field Group，最后使用 dcgmi dmon 对该 GPU Group 采集 Field Group 中的数据。示例请参见 MTDCGM 功能概述。
删除 GPU Group 会删除或重置 GPU 吗？
不会。GPU Group 是 MTDCGM 中的逻辑分组。删除组只会删除组定义，不会删除、重置或更改组内 GPU。
删除前，请确认其他监控或诊断任务没有继续引用该组 ID。
如何选择 dcgmi dmon 使用的字段 ID？
先查询当前安装版本支持的字段：
dcgmi dmon -l
字段 ID 及含义可能随版本变化。请根据实际输出选择字段，并记录 MTDCGM 版本；不要直接复制其他环境中的字段 ID 用于生产监控。
为什么健康检查刚启用时没有有效结果？
健康监控需要先设置监控项并等待数据采集。例如：
dcgmi health -g 0 -s p
dcgmi health -g 0 -f
dcgmi health -g 0 -c
根据 dcgmi health --help 的说明，PCIe 和 MTLink 监控在首次查询前至少需要 60 秒采集时间。检查结果前，请确认组 ID 正确、监控项已启用并完成一个监 控窗口。
健康监控和诊断有什么区别？
- 健康监控：在监控窗口内持续观察 GPU 或 GPU 组的受支持组件，适合日常状态检查；
- 诊断：主动执行部署验证或 GPU 测试，适合节点上线检查和故障定位。
健康监控通常不会替代诊断，诊断通过也不能替代持续监控。二级及以上诊断可能占用较多系统资源，只能在排空并隔离节点后执行。
诊断和故障处理
应该选择哪个诊断级别？
| 级别 | 适用场景 | 运行要求 |
|---|---|---|
1 | 首次部署检查和快速系统验证 | 作为首个主动检查。 |
2 | 扩展系统验证 | 排空作业，确认 GPU 无业务负载。 |
3 | 系统硬件诊断 | 排空并隔离节点，在维护窗口运行。 |
4 | 更长时间的系统硬件诊断 | 仅在受控维护窗口运行。 |
从一级开始。不要因为一级失败而直接提高诊断级别，应先修复安装、权限、驱动或动态库问题。具体测试范围请以当前版本的 dcgmi diag -h 和实际输出为准。
可以在运行生产作业时执行诊断吗？
不要在运行生产作业的节点上执行二级及以上诊断。高级别诊断可能占用 GPU、CPU、内存、PCIe、MTLink 和网络资源，运行前必须排空并隔离节点。
一级诊断适合首次部署检查，但在故障现场运行任何诊断前仍应先保存日志、GPU 状态和作业信息。安全操作流程请参见 MTDCGM 诊断指南。
如何区分诊断命令失败和 GPU 测试失败？
- 命令无法启动：通常是 Host Engine、环境变量、权限、参数或依赖问题；
- 部署检查失败：通常是 MTML、MUSA 动态库、权限或操作系统检查未通过；
- GPU 测试失败：测试已经运行，但指定 GPU 或测试插件返回失败。
命令无法启动时，不要把结果当成 GPU 故障。先保存终端输出和 Host Engine 日志，再修复运行环境。详细判断方法请参见 判定诊断结果。
诊断结果中的 Skip 是否等于 Pass？
不等于。Skip 表示测试未执行或前置条件不满足，不能证明对应项目正常。
记录测试名称和跳过原因，确认当前 GPU、构建配置和运行环境是否支持该测试，以及是否缺少依赖、权限或必要的节点状态。
一级诊断通过后，为什么应用仍然失败？
一级诊断主要检查部署和运行环境，单次通过不能排除间歇性故障、通信问题或应用自身问题。
- 多卡或多节点通信异常：检查 MCCL、网络和拓扑；
- 只有一个应用失败：保留启动命令、环境变量和调用栈，使用最小用例复现；
- GPU 或节点状态异常：结合健康监控、XID、内核日志和更完整的诊断结果判断。
请按照 GPU 故障排查 选择后续路径。
诊断长时间无响应时如何停止？
先保存时间、进程、GPU 和节点状态，再向目标 Host Engine 发送停止请求：
DCGMI_STOP_DIAG_HOSTNAME=localhost dcgmi diag
将 localhost 替换为实际 Host Engine 的主机名或地址。如果停止请求无响应，先保存 Host Engine、诊断和内核日志，再按照维护流程处理服务或节点。不要在保留证据前直接终止进程或重启主机。
如果此时还无法停止，则可以通过执行 mthreads-gmi 查看当前的 MTVS 进程 PID，在终端执行 kill -9 <pid> 快速停止诊断进程。
提交诊断问题时需要收集哪些信息？
至少提供：
- 运行时间、主机名、GPU ID 和 GPU 数量；
dcgmi diag的完整命令、终端输出和退出码；- JSON、
--debugLogFile日志和插件统计文件； mthreads-gmi、dcgmi discovery -l和健康监控结果；- Host Engine、 内核、XID 和应用日志；
- 驱动、MUSA Toolkit、MTDCGM、固件和应用版本；
- 节点是否排空、隔离，以及已经执行的恢复操作。
还应运行：
sudo mthreads-bug-report.sh
dcgmi -v
完整清单请参见 收集诊断证据。
出现 XID 是否说明 GPU 硬件已经损坏？
不一定。XID 可能与 GPU 硬件、驱动、用户程序、系统内存、PCIe、MTLink 或热管理有关。
保存完整 XID、发生时间、GPU 标识和相关日志，再根据 XID 参考手册 中的严重性、影响范围、可能原因和处置措施继续判断。不要仅凭一个 XID 决定返修或更换 GPU。
API 集成
应该选择独立模式还是嵌入模式？
- 独立模式：适合多个客户端共享 Host Engine，或者管理员需要使用
dcgmi的环境； - 嵌入模式：适合由单个管理代理加载 MTDCGM 动态库，并控制数据采集和后台任务的集成场景。
嵌入模式下，应用需要按照 API 要求定期调用字段更新接口。开始集成前，请参见 MTDCGM API 参考手册，确认初始化、连接、更新、健康检查和关闭流程。
