pymtml：摩尔线程 GPU 管理库的 Python 绑定

许多 AI 推理与训练项目使用 NVIDIA 的 pynvml 来查询 GPU 设备数量、显存占用、温度、功耗等信息，或用于多卡拓扑与 P2P 检测。在摩尔线程 GPU 上，底层管理库是 MTML（Moore Threads Management Library），对应 C 库为 libmtml.so。pymtml 是 MTML 的 Python 绑定，不仅封装了全部原生 MTML API，还提供 pynvml 兼容层：只需将 import pynvml 改为 import pymtml as pynvml，现有监控与拓扑代码即可在摩尔线程 GPU 上运行，无需修改其余逻辑。

本文基于 pymtml 的安装与使用手册，介绍其项目简介、环境与安装、快速上手、原生 API 与 NVML 兼容层、上下文管理器与错误处理，以及常见问题。

什么是 pymtml？

pymtml 是摩尔线程 GPU 管理库 (MTML) 的 Python 绑定，通过 ctypes 动态加载 libmtml.so 共享库，提供对摩尔线程 GPU 设备的监控与管理能力。项目开源在 GitHub：MooreThreads/mthreads-ml-py。

为什么需要 pymtml？

在摩尔线程 GPU 上做显存/温度/功耗监控、多卡拓扑与 P2P 检测时，若直接使用 pynvml，会依赖 NVIDIA 驱动与 NVML，无法在摩尔线程环境中工作。pymtml 一方面提供完整的 原生 MTML API，可访问设备信息、GPU/Memory/VPU 子组件、MtLink 互连、ECC、风扇、MPC、虚拟化等；另一方面提供 NVML 兼容层，使依赖 pynvml 的既有代码（如 sglang 等 AI 推理框架）只需改一行 import 即可在摩尔线程平台上运行。

核心特性

特性	说明
原生 MTML API	直接封装 libmtml.so C 库函数
NVML 兼容层	提供 pynvml 的替代接口，支持一行替换
上下文管理器	提供 with 语句管理 GPU/Memory/VPU 子组件生命周期
多 GPU 支持	支持多卡拓扑查询、P2P 状态检测、MtLink 互连检测
框架兼容	兼容 sglang 等 AI 推理框架的 NVML 调用

能力一览

能力	说明
库与设备	mtmlLibraryInit / ShutDown，按索引/UUID/PCI 获取设备
设备信息	名称、UUID、PCI、功耗、VBIOS/MtBIOS、核心数、路径、属性
GPU 监控	利用率、温度、时钟、各引擎（几何/2D/3D/计算）利用率
显存监控	总量/已用/空闲、利用率、时钟、带宽、总线宽度、类型、供应商
VPU	时钟、编解码利用率与容量
多卡	MtLink 规格与状态、拓扑层级、P2P 读写状态
其他	ECC、风扇、MPC、虚拟化、CPU 亲和性、日志配置

环境要求与安装

环境要求

• Python 3.7+
• MTML 2.2.0+
• 硬件 摩尔线程 GPU
• 驱动 已安装摩尔线程 GPU 驱动程序

验证驱动是否可用：

# 检查 libmtml.so 是否可用
ldconfig -p | grep libmtml

# 检查 GPU 设备
ls /dev/dri/render*

安装方式

方式一：通过 pip 安装（推荐）

pip install mthreads-ml-py

方式二：从源码安装

git clone https://github.com/MooreThreads/mthreads-ml-py.git
cd mthreads-ml-py
pip install -e .

方式三：构建 wheel 后安装

make build
pip install dist/*.whl

快速开始

最简示例

from pymtml import *

mtmlLibraryInit()

device_count = mtmlLibraryCountDevice()
print(f"Found {device_count} GPU(s)")

for i in range(device_count):
    device = mtmlLibraryInitDeviceByIndex(i)
    name = mtmlDeviceGetName(device)
    uuid = mtmlDeviceGetUUID(device)
    print(f"Device {i}: {name} ({uuid})")

mtmlLibraryShutDown()

查询设备详细信息（含显存与 GPU 利用率）

推荐使用上下文管理器自动管理 GPU/Memory 子组件的初始化和释放：

from pymtml import *

mtmlLibraryInit()

for i in range(mtmlLibraryCountDevice()):
    device = mtmlLibraryInitDeviceByIndex(i)

    name = mtmlDeviceGetName(device)
    uuid = mtmlDeviceGetUUID(device)
    print(f"Device {i}: {name} ({uuid})")

    with mtmlMemoryContext(device) as memory:
        total = mtmlMemoryGetTotal(memory)
        used = mtmlMemoryGetUsed(memory)
        print(f"  Memory: {used / 1024**3:.2f} / {total / 1024**3:.2f} GB")

    with mtmlGpuContext(device) as gpu:
        util = mtmlGpuGetUtilization(gpu)
        temp = mtmlGpuGetTemperature(gpu)
        print(f"  GPU Util: {util}%, Temp: {temp}°C")

mtmlLibraryShutDown()

作为 pynvml 替代使用

只需修改一行 import，即可将已有 pynvml 代码迁移到摩尔线程平台：

# 替换前：
# import pynvml

# 替换后：
import pymtml as pynvml

# 之后的代码完全不用改动
pynvml.nvmlInit()
device_count = pynvml.nvmlDeviceGetCount()
for i in range(device_count):
    handle = pynvml.nvmlDeviceGetHandleByIndex(i)
    name = pynvml.nvmlDeviceGetName(handle)
    mem_info = pynvml.nvmlDeviceGetMemoryInfo(handle)
    print(f"Device {i}: {name}")
    print(f"  Memory: {mem_info.used / 1024**3:.2f} / {mem_info.total / 1024**3:.2f} GB")
    print(f"  Free:   {mem_info.free / 1024**3:.2f} GB")
pynvml.nvmlShutdown()

原生 MTML API 概览

库生命周期与设备

函数	说明
mtmlLibraryInit()	初始化 MTML 库，加载 libmtml.so
mtmlLibraryShutDown()	关闭库接口
mtmlLibraryGetVersion()	获取 MTML 库版本号
mtmlLibraryCountDevice()	获取 GPU 设备数量
mtmlLibraryInitDeviceByIndex(index)	按索引获取设备句柄
mtmlLibraryInitDeviceByUuid(uuid)	按 UUID 获取设备句柄
mtmlLibraryInitDeviceByPciSbdf(sbdf)	按 PCI SBDF 获取设备句柄
mtmlLibraryInitSystem()	初始化系统句柄（如查驱动版本）

GPU / Memory / VPU 子组件

GPU、Memory、VPU 是设备的子组件，需先初始化、用完后释放。推荐使用上下文管理器，避免资源泄漏：

# GPU
with mtmlGpuContext(device) as gpu:
    util = mtmlGpuGetUtilization(gpu)
    temp = mtmlGpuGetTemperature(gpu)
    clock = mtmlGpuGetClock(gpu)

# Memory
with mtmlMemoryContext(device) as memory:
    total = mtmlMemoryGetTotal(memory)
    used = mtmlMemoryGetUsed(memory)
    util = mtmlMemoryGetUtilization(memory)
    bandwidth = mtmlMemoryGetBandwidth(memory)

# VPU（视频处理单元）
with mtmlVpuContext(device) as vpu:
    clock = mtmlVpuGetClock(vpu)
    enc_cap, dec_cap = mtmlVpuGetCodecCapacity(vpu)

多卡：MtLink 与拓扑、P2P

类别	示例函数
MtLink	mtmlDeviceGetMtLinkSpec, mtmlDeviceGetMtLinkState, mtmlDeviceGetMtLinkRemoteDevice
拓扑	mtmlDeviceGetTopologyLevel(dev1, dev2), mtmlDeviceCountDeviceByTopologyLevel
P2P	mtmlDeviceGetP2PStatus(dev1, dev2, cap)

拓扑层级包括：同一 GPU、单 PCIe 交换机、多 PCIe 交换机、主桥、同一 NUMA 节点、跨 NUMA 节点等。

NVML 兼容层

pymtml 提供完整的 pynvml 兼容接口，支持以 import pymtml as pynvml 零改动迁移。

主要映射关系

NVML 函数	MTML 对应
nvmlInit() / nvmlShutdown()	mtmlLibraryInit() / mtmlLibraryShutDown()
nvmlDeviceGetCount()	mtmlLibraryCountDevice()
nvmlDeviceGetHandleByIndex(i)	mtmlLibraryInitDeviceByIndex(i)
nvmlDeviceGetName / nvmlDeviceGetUUID	mtmlDeviceGetName / mtmlDeviceGetUUID
nvmlDeviceGetMemoryInfo(dev)	内部组合调用，返回 NVMLMemoryInfo(total, free, used)
nvmlDeviceGetUtilizationRates(dev)	内部组合调用，返回 NVMLUtilization(gpu, memory)
nvmlDeviceGetTemperature / nvmlDeviceGetPowerUsage	mtmlGpuGetTemperature / mtmlDeviceGetPowerUsage
nvmlDeviceGetP2PStatus / nvmlDeviceGetTopologyCommonAncestor	多种 MTML 调用组合
nvmlSystemGetDriverVersion()	mtmlSystemGetDriverVersion()

不支持的 NVML 函数

因硬件/驱动差异，以下函数返回固定值或空值，例如：

• nvmlSystemGetCudaDriverVersion() → 0（摩尔线程使用 MUSA 而非 CUDA）
• nvmlDeviceGetBAR1MemoryInfo() → "N/A"
• nvmlDeviceGetCudaComputeCapability() → (0, 0)，需要安装 torch_musa 才能获取 MUSA 计算能力
• 以及部分显示、持久化、MIG、进程列表等接口，详见文档。

上下文管理器与错误处理

上下文管理器

三个上下文管理器分别管理 GPU、Memory、VPU 子组件的创建与释放，异常时也会正确释放资源：

with mtmlGpuContext(device) as gpu:
    ...

with mtmlMemoryContext(device) as memory:
    ...

with mtmlVpuContext(device) as vpu:
    ...

错误处理

MTML 调用失败时抛出 MTMLError（别名 NVMLError）。可为不同错误码使用子类做精确捕获，例如 MTMLError_NotSupported、MTMLError_NotFound 等。常见错误码包括：驱动未加载、无效参数、不支持、权限不足、未找到、超时、资源繁忙等。

try:
    device = mtmlLibraryInitDeviceByIndex(99)  # 不存在的设备
except MTMLError as e:
    print(f"Error code: {e.value}, message: {e}")

常见问题

Q: 运行时报 "Driver Not Loaded"

原因：摩尔线程 GPU 驱动未加载或当前环境无法使用（如容器中）。解决：确认驱动已安装，且 libmtml.so 在 LD_LIBRARY_PATH 中。

Q: nvmlDeviceGetCudaComputeCapability() 返回 (0, 0)

原因：该函数需要 torch 和 torch_musa 才能返回 MUSA 计算能力。解决：安装 torch_musa 后即可正常返回。

Q: 如何在 sglang 中使用？

在 sglang 代码中将 import pynvml 改为 import pymtml as pynvml，其余代码无需修改。pymtml 已实现 sglang 依赖的 NVML API，包括 P2P 检测和拓扑查询。

Q: MtLink 查询返回 N/A

原因：当前设备不支持 MtLink（单卡或无 MtLink 硬件）。MtLink 是摩尔线程的多卡互连技术，类似 NVIDIA 的 NVLink。

Q: 库的 init/shutdown 可以多次调用吗？

可以。pymtml 支持多次 init/shutdown 循环，内部通过引用计数管理库生命周期。

测试与示例

如何运行 examples

项目在 examples/ 目录下提供了 13 个独立示例，覆盖库基础、设备信息、GPU/显存/VPU 监控、风扇与功耗、ECC、拓扑与 MtLink、NVML 兼容、设备路径、MPC 与虚拟化、亲和性与日志、综合报告等所有支持的 API 类别。在仓库根目录下可这样运行：

# 运行单个示例
python examples/01_library_basics.py

# 运行所有示例（按编号顺序）
for f in examples/[0-9]*.py; do python "$f"; echo; done

Windows 下若没有 bash，可逐个执行，例如：

python examples/01_library_basics.py
python examples/02_device_info.py
# ... 依此类推

如何运行测试

make test             # 使用 pytest 运行全部测试
# 或逐个运行
python test_pymtml.py        # 原生 MTML API 测试
python test_pynvml.py        # NVML 兼容层测试
python test_sglang_compat.py # sglang 框架兼容性测试

所有测试与示例均需在具备摩尔线程 GPU 及驱动的环境中运行。

总结

pymtml 是摩尔线程 MTML 的 Python 绑定，通过 ctypes 加载 libmtml.so，提供完整的设备与子组件（GPU/Memory/VPU）监控、多卡拓扑与 P2P、MtLink、ECC 等能力，并配有上下文管理器与统一错误类型。其 NVML 兼容层 支持 import pymtml as pynvml 一行替换，使依赖 pynvml 的既有代码（如 sglang）无需修改即可在摩尔线程 GPU 上运行，是摩尔线程平台上进行 GPU 监控与管理的首选 Python 库。

更多 API 细节、常量与枚举、示例输出格式请参见 mthreads-ml-py 仓库 及仓库内文档。