CLI指标监控监控大盘【免费下载链接】nvitopAn interactive NVIDIA-GPU process viewer and beyond, the one-stop solution for GPU process management.项目地址https://gitcode.com/gh_mirrors/nv/nvitop点击查看免费下载nvitop 是一个交互式 NVIDIA-GPU 进程查看器其底层设备与进程数据全部来自 NVIDIA Management LibraryNVML。nvitop.libnvml模块源码见 nvitop/api/libnvml.py正是在 NVML 官方 Python 绑定nvidia-ml-pypynvml之上构建的一层安全胶水层负责解决裸绑定在真实 GPU 环境中常见的三大痛点上下文初始化繁琐、查询失败即抛异常、驱动与绑定版本不匹配导致函数缺失。阅读本文后你将掌握 nvitop 如何用nvmlQuery统一封装 NVML 调用、如何通过版本探测自动兼容新旧驱动 API、以及如何用线程安全的引用计数与 atexit 排空机制避免解释器退出时的崩溃。模块定位为什么需要 libnvml 这一层NVML 官方绑定pynvml的函数要求使用者先调用nvmlInit()完成库加载且每次查询失败都会抛出对应的NVMLError子类。在多 GPU、驱动版本繁杂的生产环境中这会导致业务代码里到处是try/except和初始化样板。libnvml 模块的职责是把这些噪音收敛起来自动初始化所有查询通过nvmlQuery进入内部先执行_lazy_init()惰性初始化 NVML 上下文调用方无需关心初始化时机统一错误策略查询失败默认返回NA占位值而不是抛异常只有显式要求时才抛出向后兼容对pynvml中驱动版本相关的高版本 API 做符号探测与回退保证在新旧驱动上都可用进程级生命周期管理维护全局初始化锁、活动查询计数并在atexit阶段排空在途查询后再关闭 NVML避免解释器退出时的 use-after-free 段错误。在 nvitop 内部nvitop.api包只从该模块导出NVMLError与nvmlCheckReturn见 nvitop/api/init.py而nvitop.api.device中的Device类则大量通过libnvml.nvmlQuery(...)获取驱动版本、设备句柄、名称、UUID、内存、利用率、时钟、功耗等指标。初始化与生命周期管理惰性初始化_lazy_init_lazy_init()是模块内部的核心入口nvitop/api/libnvml.pydef _lazy_init() - None: global __atexit_registered if __initialized or __shutting_down: return with __lock: if __initialized or __shutting_down: return nvmlInit() with __lock: if not __atexit_registered: _atexit.register(_atexit_shutdown, timeout120.0) __atexit_registered True它使用双重检查锁double-checked locking保证并发安全先读全局__initialized快速返回再在__lock内复查随后才真正调用nvmlInit()。首次初始化时会恰好一次注册atexit关闭钩子避免并发首次初始化或重复初始化/关闭循环时排队多个钩子。可重复的nvmlInit/nvmlInitWithFlags/nvmlShutdownlibnvml 重新定义了三个上下文函数覆盖同名pynvml成员使初始化具备引用计数语义nvmlInit()等价于nvmlInitWithFlags(0)用默认标志初始化nvmlInitWithFlags(flags)维护一个全局标志栈__flags。若栈顶标志与本次相同则直接置__initialized True返回否则调用_pynvml.nvmlInitWithFlags(flags)并把标志压栈nvitop/api/libnvml.pynvmlShutdown()调用底层_pynvml.nvmlShutdown()后弹出栈顶标志并按栈是否为空更新__initializednvitop/api/libnvml.py。这意味着同一进程中可以安全地多轮初始化/关闭且只有最后一次关闭才真正让 NVML 失效。nvmlInitWithFlags还对两类常见故障输出了带颜色的诊断信息NVMLError_LibraryNotFound提示 NVML 随 NVIDIA 显示驱动或 CUDA Toolkit 分发并列出 NVML API Reference 位置AttributeError提示nvidia-ml-py依赖包损坏可能有其它包覆盖了pynvml模块并给出python3 -m pip install --force-reinstall nvitop的修复命令。上下文管理器支持libnvml 将模块自身替换为_CustomModule类型继承ModuleType见 nvitop/api/libnvml.py因此模块同时支持with语句与属性查找回退import nvitop.api.libnvml as libnvml with libnvml: # 进入时 _lazy_init() handle libnvml.nvmlDeviceGetHandleByIndex(0) # 退出时自动 nvmlShutdown()异常被静默吞掉__getattribute__在自身找不到成员时会回退到pynvml查找因此libnvml.c_nvmlGpuInstance_t等新版本类型即使未显式定义也能访问——这是向后兼容机制的一部分。统一查询入口nvmlQuerynvmlQuery是 libnvml 使用频率最高的 APInvitop/api/libnvml.pynvitop 的所有 NVML 数据读取几乎都经由它完成例如 nvitop/api/device.py 中读取驱动版本libnvml.nvmlQuery(nvmlSystemGetDriverVersion)、nvitop/api/device.py 中获取设备句柄以及 nvitop/api/device.py 中枚举 GPU 运行进程。函数签名与参数def nvmlQuery( func, # 可调用对象或 pynvml 中的函数名字符串 /, *args, # 传给 NVML 函数的位置参数 defaultNA, # 查询失败时返回的默认值 ignore_errorsTrue, # 是否吞掉错误并返回 default ignore_function_not_foundFalse, # 是否忽略函数不存在错误 **kwargs, # 传给 NVML 函数的关键字参数 ) - Any行为要点函数名传字符串若func是字符串先从pynvml模块属性中解析出真实函数解析失败抛出NVMLError_FunctionNotFound错误策略NVMLError及子类含FunctionNotFound在ignore_errorsTrue时一律返回default默认NA只有显式设置ignore_errorsFalse才向上抛出FunctionNotFound 单独开关ignore_function_not_foundFalse时遇到函数缺失会通过LOGGER.exception记录完整调用现场与请核对nvidia-ml-py与驱动版本兼容性的提示并把(函数, 异常)记入UNKNOWN_FUNCTIONS缓存上限 1024 条去重方便后续排查字节解码返回值为bytes时自动按 UTF-8errorsreplace解码避免中文/特殊字符字段如设备名解码失败UnicodeDecodeError 兜底底层调用若抛UnicodeDecodeError统一转成NVMLError_Unknown抛出。与 atexit 排空的协作nvmlQuery在执行任何 NVML 调用包括_lazy_init内部的nvmlInit之前先在__shutdown_condition上把在途查询计数__active_queries加一函数结束在finally中减一并notify_all()。这样在解释器退出阶段_atexit_shutdown能精确等待在途查询归零后再调用nvmlShutdown避免后台线程仍停留在libnvidia-ml内部时 NVML 状态被释放。若已进入关闭状态__shutting_down为真新查询直接返回default或抛NVMLError_Uninitialized从根上杜绝与关闭过程竞态对应 issue #222 的修复。批量字段查询nvmlQueryFieldValues现代 NVML 提供了nvmlDeviceGetFieldValues批量查询接口一次驱动调用即可取回多个字段值且同一驱动调用填充的字段不会重复发起调用。nvmlQueryFieldValuesnvitop/api/libnvml.py将其封装为易用形式def nvmlQueryFieldValues(handle, field_ids): # field_ids: list[int | tuple[int, int]]如 NVML_FI_DEV_NVLINK_LINK_COUNT # 返回: list[tuple[value, timestamp_us]]实现细节底层通过nvmlQuery(nvmlDeviceGetFieldValues, handle, field_ids)发起查询若整体失败或nvmlCheckReturn不通过为每个字段返回(NA, 当前微秒时间戳)逐字段判断nvmlReturn是否为NVML_SUCCESS与valueType按NVML_VALUE_TYPE_DOUBLE / UNSIGNED_INT / UNSIGNED_LONG / UNSIGNED_LONG_LONG / SIGNED_LONG_LONG / SIGNED_INT从union中取出对应类型的值未知类型或字段失败同样回落为NA。nvitop 用它查询 NVLink 链路数量与吞吐等聚合字段见 nvitop/api/device.py 的nvmlQueryFieldValues调用。模块同时显式导出了NVML_FI_DEV_NVLINK_*系列字段常量与NVML_VALUE_TYPE_*类型常量。返回值校验nvmlCheckReturnnvmlQuery失败时默认返回NANaType哨兵对象同时从 nvitop/api/utils.py 导入NA、UINT_MAX、ULONGLONG_MAX。调用方需要一种轻量方式来区分真实值与占位值def nvmlCheckReturn(retval, typesNone, /) - bool: if types is None: return retval ! NA return retval ! NA and isinstance(retval, types)典型用法如 nvitop/api/device.py先查 CUDA 驱动版本再libnvml.nvmlCheckReturn(cuda_driver_version, int)确认拿到的是整数而非NA才进入后续换算逻辑内存、利用率、功率、PCIe 吞吐等属性如 nvitop/api/device.py、nvitop/api/device.py同样以此模式做防护。异常体系与常量注册NVMLError 异常模块以类型别名方式从pynvml引入NVMLError基类并为其补写 docstringBase exception class for NVML query errors.nvmlExceptionClass负责把错误码映射到具体子类。加载阶段nvitop/api/libnvml.py会遍历pynvml的成员表先把所有NVML_ERROR_*常量与NVMLError_*异常类放入__all__并建立错误码 → 常量名映射_errcode_to_name再把其余NVML_*常量与nvml*函数成员排除nvmlInit、nvmlInitWithFlags、nvmlShutdown三个被重定义的入口全部注册进__all__从而让from nvitop.api.libnvml import *能拿到完整 NVML 表面为每个错误码对应的异常子类动态写入 docstring格式为原因描述。Code:NVML_ERROR_XXX(错误码)为无文档的常量生成 Sphinx.. data::指令追加到模块 docstring形成 Constants 与 Functions and Exceptions 两节——这也是 docs/source/api/libnvml.rst 中.. automodule:: nvitop.libnvml :members:能自动展开出丰富 API 文档的原因。常用异常子类均为类型别名NVMLError_Uninitialized、NVMLError_FunctionNotFound、NVMLError_GpuIsLost、NVMLError_InvalidArgument、NVMLError_LibraryNotFound、NVMLError_NoPermission、NVMLError_NotFound、NVMLError_NotSupported、NVMLError_Unknown。常用常量模块显式导出并被上层广泛使用的常量包括NVML_SUCCESS、NVML_ERROR_INSUFFICIENT_SIZE、时钟类型NVML_CLOCK_GRAPHICS/SM/MEM/VIDEO、温度传感器NVML_TEMPERATURE_GPU、驱动模型NVML_DRIVER_WDDM/WDM/MCDM、计算模式NVML_COMPUTEMODE_DEFAULT/EXCLUSIVE_THREAD/PROHIBITED/EXCLUSIVE_PROCESS、PCIe 利用率NVML_PCIE_UTIL_TX_BYTES/RX_BYTES、NVML_NVLINK_MAX_LINKS等。其中NVML_DRIVER_MCDM与NVML_VALUE_TYPE_*等在新旧pynvml中定义不一致的常量均用getattr(_pynvml, name, default)提供默认值保证不同绑定版本下模块可导入。驱动 API 版本兼容补丁层NVML C 库的 API 带有版本后缀如_v1、_v2、_v3旧驱动可能缺少新符号。libnvml 采用探测函数指针 → 决定后缀 → 回退旧结构体的统一模式修补了五组高版本 API全部通过_nvmlGetFunctionPointer探查符号是否存在缺失时以 debug 日志记录并返回None。若检测到pynvml安装损坏缺少_nvmlGetFunctionPointer而只有_PrintableStructure则跳过所有补丁并输出警告。运行进程枚举v1 / v2 / v3 自适应针对nvmlDeviceGet{Compute,Graphics,MPSCompute}RunningProcesses模块定义了三个版本的进程信息结构体nvitop/api/libnvml.pyc_nvmlProcessInfo_v1_tpidusedGpuMemoryWDDM 下恒为不可用值c_nvmlProcessInfo_v2_t在 v1 基础上增加gpuInstanceId/computeInstanceIdMIG 场景c_nvmlProcessInfo_v3_t再增加usedGpuCcProtectedMemory受保护计算内存。__determine_get_running_processes_version_suffix()nvitop/api/libnvml.py按优先级探测优先_v3但若驱动不支持 v3 结构体则退回 v2 结构体配_v3函数其次_v2最后无后缀 v1。查询流程沿用了pynvml的两步法先以NULL缓冲区调用取得进程数NVML_ERROR_INSUFFICIENT_SIZE为典型情况按count * 2 5扩容数组后二次调用并把ULONGLONG_MAX的usedGpuMemory归一化为NoneWindows WDDM 特例。上层Device.processes()nvitop/api/device.py依次调用 Compute 与 Graphics 两个枚举函数合并同 PID 的进程类型标记再用nvmlDeviceGetProcessUtilization的采样数据回填 SM/内存/编码/解码利用率最终构造成GpuProcess实例字典。内存信息v1 / v2nvmlDeviceGetMemoryInfo的 v2 API 增加了reserved字段驱动/固件保留内存libnvml 定义c_nvmlMemory_v1_t与c_nvmlMemory_v2_t两个结构体nvitop/api/libnvml.py探测到nvmlDeviceGetMemoryInfo_v2符号则填入version nvmlMemory_v2结构体大小 |2 24走 v2否则退回 v1。温度nvmlDeviceGetTemperatureV新版 NVML 将温度读取改为带版本的nvmlDeviceGetTemperatureV结构体含version、sensorType、temperature。探测失败时回退到无版本的旧函数用ctypes.c_uint直接传传感器类型。驱动模型_v2自nvidia-ml-py13.595.45 起nvmlDeviceGetDriverModel会派发到 C 符号nvmlDeviceGetDriverModel_v2旧驱动可能缺失。libnvml 探测失败则回退 v1并在此基础上提供nvmlDeviceGetCurrentDriverModel取当前模型与nvmlDeviceGetPendingDriverModel取待生效模型两个便捷函数返回 WDDM / WDM(TCC) / MCDM 常量。进程安全fork 与退出排空_atexit_shutdownnvitop/api/libnvml.py在退出时先将__shutting_down置位此后nvmlQuery不再发起新调用再用Condition.wait_for(lambda: __active_queries 0, timeout)阻塞等待在途查询排空排空成功调用nvmlShutdown()并容忍 NVML 已被显式关闭的情况静默吞掉NVMLError超时仍有在途查询跳过nvmlShutdown()并记录警告避免 use-after-free资源交由操作系统在进程退出时回收。默认超时 120 秒。_reset_after_forknvitop/api/libnvml.py处理os.fork()场景子进程只继承调用线程锁可能处于被已消失线程持有的已锁状态在途计数也可能虚高。因此子进程侧重建__lock、__shutdown_condition并把__active_queries、__shutting_down归零避免继承的 atexit 钩子在子进程里因幽灵查询阻塞满超时或死锁。该钩子通过os.register_at_fork(after_in_child...)注册Windows 无 fork自动跳过。实践要点与常见问题排查查询失败不抛异常是默认行为需要强一致性的读取如构建设备句柄请显式传ignore_errorsFalse如 nvitop/api/device.py 的nvmlQuery(nvmlDeviceGetHandleByUUID, uuid, ignore_errorsFalse)函数不存在 ≠ 设备不支持日志出现FunctionNotFound提示时优先核对nvidia-ml-py版本与驱动版本是否匹配可执行pip3 install --force-reinstall nvidia-ml-py nvitop修复损坏的绑定内存字段为N/AWindows WDDM 或 MIG 场景下usedGpuMemory可能不可用上层通过ULONGLONG_MAX归一化为None处理时按NA对待日志开关模块 logger 级别由环境变量LOGLEVEL控制默认WARNING在 DEBUG 级别下会把日志同时输出到控制台与nvitop.log可用来观察版本探测与符号回退的完整决策过程nvitop/api/libnvml.py。小结nvitop.libnvml是一层小而关键的安全 NVML 门面nvmlQuery统一了惰性初始化、错误吞并、函数缺失诊断与字节解码nvmlQueryFieldValues提供了批量字段查询nvmlCheckReturn让NA占位值可以像普通值一样被安全消费版本补丁层让同一份代码跨新旧驱动稳定运行而线程安全的初始化计数、atexit 排空与 fork 重置保证了在多线程监控、后台采集与守护进程场景下的进程级健壮性。若要在自己的项目里复用这套模式直接from nvitop.api.libnvml import nvmlQuery, nvmlCheckReturn, NA即可获得与 nvitop 完全一致的 NVML 访问体验完整的自动生成 API 文档入口位于 docs/source/api/libnvml.rst。赞分享CLI指标监控监控大盘【免费下载链接】nvitopAn interactive NVIDIA-GPU process viewer and beyond, the one-stop solution for GPU process management.项目地址https://gitcode.com/gh_mirrors/nv/nvitop点击查看免费下载相关推荐PaddleSpeech CTC 解码器 SWIG 封装模块深度解析从 Python 接口到 C 底层实现PaddleSpeech CTC 解码器 SWIG 封装模块深度解析从 Python 接口到 C 底层实现 本篇文章以 PaddleSpeech 仓库中的人工智能语音音频如何快速掌握Stanford CME 106概率统计完整指南与VIP速查表解析如何快速掌握Stanford CME 106概率统计完整指南与VIP速查表解析 想要在短时间内掌握斯坦福大学CME 106概率统计课程的精髓吗这份 VIP速llama-cpp-python API 参考详解High Level 封装、ctypes 底层绑定与类型体系全解析llama cpp python API 参考详解High Level 封装、ctypes 底层绑定与类型体系全解析 llama cpp python 是 l人工智能大模型本地部署模型推理服务上一篇如何用 TVBoxOSC 在电视上查看文档从安装到遥控器操作的完整指南下一篇重置失败、试用期没恢复ide-eval-resetter常见问题6项排查清单创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/29 7:43:54 · 阅读 1.2k nvitop libnvml 模块解析：NVML Python 绑定的封装、查询与兼容层实现
CLI指标监控监控大盘【免费下载链接】nvitopAn interactive NVIDIA-GPU process viewer and beyond, the one-stop solution for GPU process management.项目地址https://gitcode.com/gh_mirrors/nv/nvitop点击查看免费下载nvitop 是一个交互式 NVIDIA-GPU 进程查看器其底层设备与进程数据全部来自 NVIDIA Management LibraryNVML。nvitop.libnvml模块源码见 nvitop/api/libnvml.py正是在 NVML 官方 Python 绑定nvidia-ml-pypynvml之上构建的一层安全胶水层负责解决裸绑定在真实 GPU 环境中常见的三大痛点上下文初始化繁琐、查询失败即抛异常、驱动与绑定版本不匹配导致函数缺失。阅读本文后你将掌握 nvitop 如何用nvmlQuery统一封装 NVML 调用、如何通过版本探测自动兼容新旧驱动 API、以及如何用线程安全的引用计数与 atexit 排空机制避免解释器退出时的崩溃。模块定位为什么需要 libnvml 这一层NVML 官方绑定pynvml的函数要求使用者先调用nvmlInit()完成库加载且每次查询失败都会抛出对应的NVMLError子类。在多 GPU、驱动版本繁杂的生产环境中这会导致业务代码里到处是try/except和初始化样板。libnvml 模块的职责是把这些噪音收敛起来自动初始化所有查询通过nvmlQuery进入内部先执行_lazy_init()惰性初始化 NVML 上下文调用方无需关心初始化时机统一错误策略查询失败默认返回NA占位值而不是抛异常只有显式要求时才抛出向后兼容对pynvml中驱动版本相关的高版本 API 做符号探测与回退保证在新旧驱动上都可用进程级生命周期管理维护全局初始化锁、活动查询计数并在atexit阶段排空在途查询后再关闭 NVML避免解释器退出时的 use-after-free 段错误。在 nvitop 内部nvitop.api包只从该模块导出NVMLError与nvmlCheckReturn见 nvitop/api/init.py而nvitop.api.device中的Device类则大量通过libnvml.nvmlQuery(...)获取驱动版本、设备句柄、名称、UUID、内存、利用率、时钟、功耗等指标。初始化与生命周期管理惰性初始化_lazy_init_lazy_init()是模块内部的核心入口nvitop/api/libnvml.pydef _lazy_init() - None: global __atexit_registered if __initialized or __shutting_down: return with __lock: if __initialized or __shutting_down: return nvmlInit() with __lock: if not __atexit_registered: _atexit.register(_atexit_shutdown, timeout120.0) __atexit_registered True它使用双重检查锁double-checked locking保证并发安全先读全局__initialized快速返回再在__lock内复查随后才真正调用nvmlInit()。首次初始化时会恰好一次注册atexit关闭钩子避免并发首次初始化或重复初始化/关闭循环时排队多个钩子。可重复的nvmlInit/nvmlInitWithFlags/nvmlShutdownlibnvml 重新定义了三个上下文函数覆盖同名pynvml成员使初始化具备引用计数语义nvmlInit()等价于nvmlInitWithFlags(0)用默认标志初始化nvmlInitWithFlags(flags)维护一个全局标志栈__flags。若栈顶标志与本次相同则直接置__initialized True返回否则调用_pynvml.nvmlInitWithFlags(flags)并把标志压栈nvitop/api/libnvml.pynvmlShutdown()调用底层_pynvml.nvmlShutdown()后弹出栈顶标志并按栈是否为空更新__initializednvitop/api/libnvml.py。这意味着同一进程中可以安全地多轮初始化/关闭且只有最后一次关闭才真正让 NVML 失效。nvmlInitWithFlags还对两类常见故障输出了带颜色的诊断信息NVMLError_LibraryNotFound提示 NVML 随 NVIDIA 显示驱动或 CUDA Toolkit 分发并列出 NVML API Reference 位置AttributeError提示nvidia-ml-py依赖包损坏可能有其它包覆盖了pynvml模块并给出python3 -m pip install --force-reinstall nvitop的修复命令。上下文管理器支持libnvml 将模块自身替换为_CustomModule类型继承ModuleType见 nvitop/api/libnvml.py因此模块同时支持with语句与属性查找回退import nvitop.api.libnvml as libnvml with libnvml: # 进入时 _lazy_init() handle libnvml.nvmlDeviceGetHandleByIndex(0) # 退出时自动 nvmlShutdown()异常被静默吞掉__getattribute__在自身找不到成员时会回退到pynvml查找因此libnvml.c_nvmlGpuInstance_t等新版本类型即使未显式定义也能访问——这是向后兼容机制的一部分。统一查询入口nvmlQuerynvmlQuery是 libnvml 使用频率最高的 APInvitop/api/libnvml.pynvitop 的所有 NVML 数据读取几乎都经由它完成例如 nvitop/api/device.py 中读取驱动版本libnvml.nvmlQuery(nvmlSystemGetDriverVersion)、nvitop/api/device.py 中获取设备句柄以及 nvitop/api/device.py 中枚举 GPU 运行进程。函数签名与参数def nvmlQuery( func, # 可调用对象或 pynvml 中的函数名字符串 /, *args, # 传给 NVML 函数的位置参数 defaultNA, # 查询失败时返回的默认值 ignore_errorsTrue, # 是否吞掉错误并返回 default ignore_function_not_foundFalse, # 是否忽略函数不存在错误 **kwargs, # 传给 NVML 函数的关键字参数 ) - Any行为要点函数名传字符串若func是字符串先从pynvml模块属性中解析出真实函数解析失败抛出NVMLError_FunctionNotFound错误策略NVMLError及子类含FunctionNotFound在ignore_errorsTrue时一律返回default默认NA只有显式设置ignore_errorsFalse才向上抛出FunctionNotFound 单独开关ignore_function_not_foundFalse时遇到函数缺失会通过LOGGER.exception记录完整调用现场与请核对nvidia-ml-py与驱动版本兼容性的提示并把(函数, 异常)记入UNKNOWN_FUNCTIONS缓存上限 1024 条去重方便后续排查字节解码返回值为bytes时自动按 UTF-8errorsreplace解码避免中文/特殊字符字段如设备名解码失败UnicodeDecodeError 兜底底层调用若抛UnicodeDecodeError统一转成NVMLError_Unknown抛出。与 atexit 排空的协作nvmlQuery在执行任何 NVML 调用包括_lazy_init内部的nvmlInit之前先在__shutdown_condition上把在途查询计数__active_queries加一函数结束在finally中减一并notify_all()。这样在解释器退出阶段_atexit_shutdown能精确等待在途查询归零后再调用nvmlShutdown避免后台线程仍停留在libnvidia-ml内部时 NVML 状态被释放。若已进入关闭状态__shutting_down为真新查询直接返回default或抛NVMLError_Uninitialized从根上杜绝与关闭过程竞态对应 issue #222 的修复。批量字段查询nvmlQueryFieldValues现代 NVML 提供了nvmlDeviceGetFieldValues批量查询接口一次驱动调用即可取回多个字段值且同一驱动调用填充的字段不会重复发起调用。nvmlQueryFieldValuesnvitop/api/libnvml.py将其封装为易用形式def nvmlQueryFieldValues(handle, field_ids): # field_ids: list[int | tuple[int, int]]如 NVML_FI_DEV_NVLINK_LINK_COUNT # 返回: list[tuple[value, timestamp_us]]实现细节底层通过nvmlQuery(nvmlDeviceGetFieldValues, handle, field_ids)发起查询若整体失败或nvmlCheckReturn不通过为每个字段返回(NA, 当前微秒时间戳)逐字段判断nvmlReturn是否为NVML_SUCCESS与valueType按NVML_VALUE_TYPE_DOUBLE / UNSIGNED_INT / UNSIGNED_LONG / UNSIGNED_LONG_LONG / SIGNED_LONG_LONG / SIGNED_INT从union中取出对应类型的值未知类型或字段失败同样回落为NA。nvitop 用它查询 NVLink 链路数量与吞吐等聚合字段见 nvitop/api/device.py 的nvmlQueryFieldValues调用。模块同时显式导出了NVML_FI_DEV_NVLINK_*系列字段常量与NVML_VALUE_TYPE_*类型常量。返回值校验nvmlCheckReturnnvmlQuery失败时默认返回NANaType哨兵对象同时从 nvitop/api/utils.py 导入NA、UINT_MAX、ULONGLONG_MAX。调用方需要一种轻量方式来区分真实值与占位值def nvmlCheckReturn(retval, typesNone, /) - bool: if types is None: return retval ! NA return retval ! NA and isinstance(retval, types)典型用法如 nvitop/api/device.py先查 CUDA 驱动版本再libnvml.nvmlCheckReturn(cuda_driver_version, int)确认拿到的是整数而非NA才进入后续换算逻辑内存、利用率、功率、PCIe 吞吐等属性如 nvitop/api/device.py、nvitop/api/device.py同样以此模式做防护。异常体系与常量注册NVMLError 异常模块以类型别名方式从pynvml引入NVMLError基类并为其补写 docstringBase exception class for NVML query errors.nvmlExceptionClass负责把错误码映射到具体子类。加载阶段nvitop/api/libnvml.py会遍历pynvml的成员表先把所有NVML_ERROR_*常量与NVMLError_*异常类放入__all__并建立错误码 → 常量名映射_errcode_to_name再把其余NVML_*常量与nvml*函数成员排除nvmlInit、nvmlInitWithFlags、nvmlShutdown三个被重定义的入口全部注册进__all__从而让from nvitop.api.libnvml import *能拿到完整 NVML 表面为每个错误码对应的异常子类动态写入 docstring格式为原因描述。Code:NVML_ERROR_XXX(错误码)为无文档的常量生成 Sphinx.. data::指令追加到模块 docstring形成 Constants 与 Functions and Exceptions 两节——这也是 docs/source/api/libnvml.rst 中.. automodule:: nvitop.libnvml :members:能自动展开出丰富 API 文档的原因。常用异常子类均为类型别名NVMLError_Uninitialized、NVMLError_FunctionNotFound、NVMLError_GpuIsLost、NVMLError_InvalidArgument、NVMLError_LibraryNotFound、NVMLError_NoPermission、NVMLError_NotFound、NVMLError_NotSupported、NVMLError_Unknown。常用常量模块显式导出并被上层广泛使用的常量包括NVML_SUCCESS、NVML_ERROR_INSUFFICIENT_SIZE、时钟类型NVML_CLOCK_GRAPHICS/SM/MEM/VIDEO、温度传感器NVML_TEMPERATURE_GPU、驱动模型NVML_DRIVER_WDDM/WDM/MCDM、计算模式NVML_COMPUTEMODE_DEFAULT/EXCLUSIVE_THREAD/PROHIBITED/EXCLUSIVE_PROCESS、PCIe 利用率NVML_PCIE_UTIL_TX_BYTES/RX_BYTES、NVML_NVLINK_MAX_LINKS等。其中NVML_DRIVER_MCDM与NVML_VALUE_TYPE_*等在新旧pynvml中定义不一致的常量均用getattr(_pynvml, name, default)提供默认值保证不同绑定版本下模块可导入。驱动 API 版本兼容补丁层NVML C 库的 API 带有版本后缀如_v1、_v2、_v3旧驱动可能缺少新符号。libnvml 采用探测函数指针 → 决定后缀 → 回退旧结构体的统一模式修补了五组高版本 API全部通过_nvmlGetFunctionPointer探查符号是否存在缺失时以 debug 日志记录并返回None。若检测到pynvml安装损坏缺少_nvmlGetFunctionPointer而只有_PrintableStructure则跳过所有补丁并输出警告。运行进程枚举v1 / v2 / v3 自适应针对nvmlDeviceGet{Compute,Graphics,MPSCompute}RunningProcesses模块定义了三个版本的进程信息结构体nvitop/api/libnvml.pyc_nvmlProcessInfo_v1_tpidusedGpuMemoryWDDM 下恒为不可用值c_nvmlProcessInfo_v2_t在 v1 基础上增加gpuInstanceId/computeInstanceIdMIG 场景c_nvmlProcessInfo_v3_t再增加usedGpuCcProtectedMemory受保护计算内存。__determine_get_running_processes_version_suffix()nvitop/api/libnvml.py按优先级探测优先_v3但若驱动不支持 v3 结构体则退回 v2 结构体配_v3函数其次_v2最后无后缀 v1。查询流程沿用了pynvml的两步法先以NULL缓冲区调用取得进程数NVML_ERROR_INSUFFICIENT_SIZE为典型情况按count * 2 5扩容数组后二次调用并把ULONGLONG_MAX的usedGpuMemory归一化为NoneWindows WDDM 特例。上层Device.processes()nvitop/api/device.py依次调用 Compute 与 Graphics 两个枚举函数合并同 PID 的进程类型标记再用nvmlDeviceGetProcessUtilization的采样数据回填 SM/内存/编码/解码利用率最终构造成GpuProcess实例字典。内存信息v1 / v2nvmlDeviceGetMemoryInfo的 v2 API 增加了reserved字段驱动/固件保留内存libnvml 定义c_nvmlMemory_v1_t与c_nvmlMemory_v2_t两个结构体nvitop/api/libnvml.py探测到nvmlDeviceGetMemoryInfo_v2符号则填入version nvmlMemory_v2结构体大小 |2 24走 v2否则退回 v1。温度nvmlDeviceGetTemperatureV新版 NVML 将温度读取改为带版本的nvmlDeviceGetTemperatureV结构体含version、sensorType、temperature。探测失败时回退到无版本的旧函数用ctypes.c_uint直接传传感器类型。驱动模型_v2自nvidia-ml-py13.595.45 起nvmlDeviceGetDriverModel会派发到 C 符号nvmlDeviceGetDriverModel_v2旧驱动可能缺失。libnvml 探测失败则回退 v1并在此基础上提供nvmlDeviceGetCurrentDriverModel取当前模型与nvmlDeviceGetPendingDriverModel取待生效模型两个便捷函数返回 WDDM / WDM(TCC) / MCDM 常量。进程安全fork 与退出排空_atexit_shutdownnvitop/api/libnvml.py在退出时先将__shutting_down置位此后nvmlQuery不再发起新调用再用Condition.wait_for(lambda: __active_queries 0, timeout)阻塞等待在途查询排空排空成功调用nvmlShutdown()并容忍 NVML 已被显式关闭的情况静默吞掉NVMLError超时仍有在途查询跳过nvmlShutdown()并记录警告避免 use-after-free资源交由操作系统在进程退出时回收。默认超时 120 秒。_reset_after_forknvitop/api/libnvml.py处理os.fork()场景子进程只继承调用线程锁可能处于被已消失线程持有的已锁状态在途计数也可能虚高。因此子进程侧重建__lock、__shutdown_condition并把__active_queries、__shutting_down归零避免继承的 atexit 钩子在子进程里因幽灵查询阻塞满超时或死锁。该钩子通过os.register_at_fork(after_in_child...)注册Windows 无 fork自动跳过。实践要点与常见问题排查查询失败不抛异常是默认行为需要强一致性的读取如构建设备句柄请显式传ignore_errorsFalse如 nvitop/api/device.py 的nvmlQuery(nvmlDeviceGetHandleByUUID, uuid, ignore_errorsFalse)函数不存在 ≠ 设备不支持日志出现FunctionNotFound提示时优先核对nvidia-ml-py版本与驱动版本是否匹配可执行pip3 install --force-reinstall nvidia-ml-py nvitop修复损坏的绑定内存字段为N/AWindows WDDM 或 MIG 场景下usedGpuMemory可能不可用上层通过ULONGLONG_MAX归一化为None处理时按NA对待日志开关模块 logger 级别由环境变量LOGLEVEL控制默认WARNING在 DEBUG 级别下会把日志同时输出到控制台与nvitop.log可用来观察版本探测与符号回退的完整决策过程nvitop/api/libnvml.py。小结nvitop.libnvml是一层小而关键的安全 NVML 门面nvmlQuery统一了惰性初始化、错误吞并、函数缺失诊断与字节解码nvmlQueryFieldValues提供了批量字段查询nvmlCheckReturn让NA占位值可以像普通值一样被安全消费版本补丁层让同一份代码跨新旧驱动稳定运行而线程安全的初始化计数、atexit 排空与 fork 重置保证了在多线程监控、后台采集与守护进程场景下的进程级健壮性。若要在自己的项目里复用这套模式直接from nvitop.api.libnvml import nvmlQuery, nvmlCheckReturn, NA即可获得与 nvitop 完全一致的 NVML 访问体验完整的自动生成 API 文档入口位于 docs/source/api/libnvml.rst。赞分享CLI指标监控监控大盘【免费下载链接】nvitopAn interactive NVIDIA-GPU process viewer and beyond, the one-stop solution for GPU process management.项目地址https://gitcode.com/gh_mirrors/nv/nvitop点击查看免费下载相关推荐PaddleSpeech CTC 解码器 SWIG 封装模块深度解析从 Python 接口到 C 底层实现PaddleSpeech CTC 解码器 SWIG 封装模块深度解析从 Python 接口到 C 底层实现 本篇文章以 PaddleSpeech 仓库中的人工智能语音音频如何快速掌握Stanford CME 106概率统计完整指南与VIP速查表解析如何快速掌握Stanford CME 106概率统计完整指南与VIP速查表解析 想要在短时间内掌握斯坦福大学CME 106概率统计课程的精髓吗这份 VIP速llama-cpp-python API 参考详解High Level 封装、ctypes 底层绑定与类型体系全解析llama cpp python API 参考详解High Level 封装、ctypes 底层绑定与类型体系全解析 llama cpp python 是 l人工智能大模型本地部署模型推理服务上一篇如何用 TVBoxOSC 在电视上查看文档从安装到遥控器操作的完整指南下一篇重置失败、试用期没恢复ide-eval-resetter常见问题6项排查清单创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考