MTGMI 常见问题（FAQ）

本页面向首次使用和日常运维 mthreads-gmi 的用户，集中回答安装验证、GPU 查询、输出处理、容器和 vGPU 使用中的常见问题。命令选项和版本差异请以 MTGMI 使用手册以及对应版本的发布说明为准。

安装与环境

如何确认 mthreads-gmi 已安装？

mthreads-gmi 通常随 GPU 驱动程序安装。先确认命令是否在 PATH 中：

command -v mthreads-gmi
mthreads-gmi --help

直接运行 mthreads-gmi，输出顶部应包含 mthreads-gmi 版本和 Driver Version；同时应列出系统中的摩尔线程 GPU。若提示找不到命令，请根据 GPU 型号参见 Linux Server Driver 文档或 Linux PC Driver 文档。

当前版本支持哪些平台？

不同 mthreads-gmi 版本支持的处理器架构、操作系统、GPU 和 MTBIOS 版本可能不同。请先查看使用手册中的支持平台，再核对输出顶部显示的 mthreads-gmi 和 Driver Version；不要把其他版本的支持矩阵直接用于当前环境。

如何确认驱动已经识别 GPU？

按以下顺序检查，先确认 PCIe 设备，再确认内核模块，最后确认管理工具输出：

lspci -d 1ed5:
lsmod | grep mtgpu
mthreads-gmi --query

如果 lspci 看不到设备，优先检查硬件连接、供电和 BIOS；如果设备存在但 mtgpu 未加载，请参见 Linux Driver 安装指南中的驱动模块排查。不要在保存日志前直接重启设备或主机。

为什么运行 mthreads-gmi 时提示 failed to load driver？

这通常表示内核驱动模块没有成功加载，或者当前驱动与系统环境不匹配。先保存命令输出，再检查：

uname -r
lsmod | grep mtgpu
dmesg | grep -i mtgpu | tail -50

如果模块加载失败，请按照当前 GPU 型号和操作系统对应的 Linux Driver 安装指南处理，不要直接删除系统配置文件或强制重载模块。

---

查询与输出

mthreads-gmi、--query、--list-gpus 和 -cf 有什么区别？

• mthreads-gmi：显示 GPU 概览和基本状态；
• mthreads-gmi --query（或 -q）：显示更完整的设备属性，可按 GPU、字段和时间间隔筛选；
• mthreads-gmi --list-gpus（或 -L）：列出 GPU 及其 UUID；
• mthreads-gmi -cf：以精简格式显示物理 GPU 概览。

首次排查设备可见性时，建议先运行：

mthreads-gmi --query

为什么部分字段显示为 N/A？

N/A 表示当前设备或运行环境不支持该属性，不一定表示 GPU 故障。请结合设备型号、驱动版本和命令选项判断；需要确认当前版本支持的字段时，参见使用手册中的查询命令。

如何查询单块 GPU、持续监控并保存结果？

使用 -i 指定 GPU，使用 -l 设置查询间隔，使用 -f 将结果保存到文件：

mthreads-gmi --query -i 0
mthreads-gmi --query -l 10
mthreads-gmi --query -l 10 -f mthreads-gmi-query.log

需要脚本处理结果时，可以使用 --json（如果当前版本支持）：

mthreads-gmi --query --json

为什么看不到进程信息？

精简格式和进程监控命令的支持范围取决于设备类型和运行环境。当前用户手册明确说明，虚拟 GPU 环境暂不支持部分进程级信息；遇到此情况，请先确认是在物理 GPU 还是 vGPU 环境中运行，再参见 vGPU 查询说明。

---

容器与 vGPU

容器中无法识别 GPU，应该检查什么？

先在宿主机运行 mthreads-gmi --query，确认宿主机驱动和 GPU 正常；再检查容器是否透传 GPU 设备、是否使用了正确的权限和 MTHREADS_VISIBLE_DEVICES 配置。容器和 Kubernetes 场景请参见 云原生安装指南。

如何查询 vGPU 状态和会话？

常用命令包括：

mthreads-gmi vgpu -q
mthreads-gmi vgpu -u
mthreads-gmi vgpu -es
mthreads-gmi vgpu -ds

这些命令分别用于查询 vGPU 详情和利用率，以及编码、解码会话。不同 vGPU 版本的命令和输出可能不同，请以对应版本的 vGPU 安装指南为准。

---

重置与故障处理

什么时候可以使用 mthreads-gmi -r？

-r 用于在不重启主机的情况下重置 GPU 状态，但手册说明该操作不保证在所有场景有效，且不建议在生产环境中使用。执行前应：

1. 保存 XID、内核日志、应用日志和 mthreads-gmi --query 输出；
2. 确认没有作业或进程正在使用目标 GPU；
3. 由集群管理员确认节点已排空。

现场故障请先阅读 GPU 故障排查，不要把重置当作第一步。

什么时候应该对比 mthreads-gmi 和 dcgmi？

当 mthreads-gmi 能发现 GPU、但 dcgmi discovery -l 不能发现 GPU 时，重点检查 Host Engine、动态库路径、权限和版本兼容性。两者职责不同：mthreads-gmi 侧重本机 GPU 查询和设备管理，dcgmi 侧重数据中心分组、监控和诊断。更多场景请参见 MTDCGM FAQ。

提交问题时需要收集哪些信息？

至少保存以下信息：

mthreads-gmi --query -f mthreads-gmi-query.log
mthreads-gmi --list-gpus

同时记录 GPU ID/UUID、发生时间、驱动和工具版本、完整命令、终端输出、内核/XID/应用日志，以及问题是否可以在其他节点复现。需要完整现场证据时，参见 GPU 故障排查中的证据收集步骤。

---

相关文档

• 使用手册：完整命令、参数、示例和 vGPU/VPU 命令。
• 版本说明：查看当前版本的环境要求和变更。
• MTDCGM FAQ：处理 mthreads-gmi 与 dcgmi 的协同排查问题。
• GPU 故障排查：保存现场、定位故障范围、恢复和提交支持信息。