[!WARNING] 此软件包包含非官方的NVML绑定和工具。此软件包仅用于演示目的。不提供长期维护或支持的保证。

官方NVML绑定由NVIDIA在名为 nvidia-ml-py 的不同项目中发布（见： https://pypi.ac.cn/project/nvidia-ml-py/）。

此项目的未来版本将不会直接包含NVML绑定，而是将依赖于 nvidia-ml-py。

请迁移到官方软件包以获得长期支持。迁移到官方软件包后，您仍然可以导入和使用熟悉的 pynvml 模块。

用于NVIDIA管理库的Python绑定和工具

[!IMPORTANT] 从版本11.0.0开始，pynvml中使用的NVML包装器直接复制自 nvidia-ml-py。在未来的版本中，本地绑定将被移除，并且 nvidia-ml-py 将成为必需的依赖项。

此项目为NVIDIA管理库（NVML）提供Python工具和绑定。

有关NVML库的信息，请参阅NVML开发者页面 http://developer.nvidia.com/nvidia-management-library-nvml

请注意，尽管结果依赖于系统，但可以使用 'python -m doctest -v README.txt' 运行此文件

要求

Python 3或更早版本，并具有ctypes模块。

安装

pip install .

用法

您可以使用由 nvidia-ml-py 提供的底层 nvml 绑定。

>>> from pynvml import *
>>> nvmlInit()
>>> print("Driver Version:", nvmlSystemGetDriverVersion())
Driver Version: 410.00
>>> deviceCount = nvmlDeviceGetCount()
>>> for i in range(deviceCount):
...     handle = nvmlDeviceGetHandleByIndex(i)
...     print("Device", i, ":", nvmlDeviceGetName(handle))
...
Device 0 : Tesla V100

>>> nvmlShutdown()

或者更高层的 nvidia_smi API。

from pynvml_utils import nvidia_smi
nvsmi = nvidia_smi.getInstance()
nvsmi.DeviceQuery('memory.free, memory.total')

from pynvml_utils import nvidia_smi
nvsmi = nvidia_smi.getInstance()
print(nvsmi.DeviceQuery('--help-query-gpu'), end='\n')

函数

Python 方法封装了在 C 共享库中实现的 NVML 函数。每个函数的使用方法与以下例外相同：

• 失败时，错误代码以 Python 异常的形式抛出。

  >>> try:
  ...     nvmlDeviceGetCount()
  ... except NVMLError as error:
  ...     print(error)
  ...
  Uninitialized
  

• C 函数的输出参数从对应的 Python 函数从左到右返回。

  nvmlReturn_t nvmlDeviceGetEccMode(nvmlDevice_t device,
                                    nvmlEnableState_t *current,
                                    nvmlEnableState_t *pending);
  

  >>> nvmlInit()
  >>> handle = nvmlDeviceGetHandleByIndex(0)
  >>> (current, pending) = nvmlDeviceGetEccMode(handle)
  

• C 结构体被转换为 Python 类。

  nvmlReturn_t DECLDIR nvmlDeviceGetMemoryInfo(nvmlDevice_t device,
                                               nvmlMemory_t *memory);
  typedef struct nvmlMemory_st {
      unsigned long long total;
      unsigned long long free;
      unsigned long long used;
  } nvmlMemory_t;
  

  >>> info = nvmlDeviceGetMemoryInfo(handle)
  >>> print "Total memory:", info.total
  Total memory: 5636292608
  >>> print "Free memory:", info.free
  Free memory: 5578420224
  >>> print "Used memory:", info.used
  Used memory: 57872384
  

• Python 处理字符串缓冲区的创建。

  nvmlReturn_t nvmlSystemGetDriverVersion(char* version,
                                          unsigned int length);
  

  >>> version = nvmlSystemGetDriverVersion();
  >>> nvmlShutdown()
  

有关使用信息，请参阅 NVML 文档。

变量

所有有意义的 NVML 常量和枚举都在 Python 中公开。

NVML_VALUE_NOT_AVAILABLE 常量不使用。相反，None 被映射到字段。

NVML 权限

许多 pynvml 封装假定底层 NVIDIA 管理库 (NVML) API 可以在没有管理员/root 权限的情况下使用。然而，系统权限可能阻止 pynvml 查询 GPU 性能计数器。例如

$ nvidia-smi nvlink -g 0
GPU 0: Tesla V100-SXM2-32GB (UUID: GPU-96ab329d-7a1f-73a8-a9b7-18b4b2855f92)
NVML: Unable to get the NvLink link utilization counter control for link 0: Insufficient Permissions

检查权限状态的一个简单方法是查找驱动程序 params 文件中的 RmProfilingAdminOnly（注意，RmProfilingAdminOnly == 1 表示需要管理员/sudo 访问）

$ cat /proc/driver/nvidia/params | grep RmProfilingAdminOnly
RmProfilingAdminOnly: 1

有关设置/清除相关管理员权限的更多信息，请参阅解决 ERR_NVGPUCTRPERM 错误的这些说明。

发布说明

• 版本 2.285.0
  • 为 NVML 2.285 添加了新函数。有关更多信息，请参阅 NVML 文档。
  • 移植以支持 Python 3.0 和 Python 2.0 语法。
  • 添加了 nvidia_smi.py 工具作为示例应用程序。
• 版本 3.295.0
  • 为 NVML 3.295 添加了新函数。有关更多信息，请参阅 NVML 文档。
  • 更新了 nvidia_smi.py 工具
    • 包括额外的错误处理
• 版本 4.304.0
  • 为 NVML 4.304 添加了新函数。有关更多信息，请参阅 NVML 文档。
  • 更新了 nvidia_smi.py 工具
• 版本 4.304.3
  • 修复 nvmlUnitGetDeviceCount 错误
• 版本 5.319.0
  • 为 NVML 5.319 添加了新函数。有关更多信息，请参阅 NVML 文档。
• 版本 6.340.0
  • 为 NVML 6.340 添加了新函数。有关更多信息，请参阅 NVML 文档。
• 版本 7.346.0
  • 为 NVML 7.346 添加了新函数。有关更多信息，请参阅 NVML 文档。
• 版本 7.352.0
  • 为 NVML 7.352 添加了新函数。有关更多信息，请参阅 NVML 文档。
• 版本 8.0.0
  • 将代码重构为 nvidia_smi 单例类
  • 添加了 DeviceQuery，它返回一个包含 (名称，值) 的字典。
  • 在 DeviceQuery 中添加了过滤器参数，以匹配 nvidia-smi 中的查询 API
  • 在 XmlDeviceQuery 中添加了过滤器参数，以匹配 nvidia-smi 中的查询 API
  • 添加了整数枚举过滤器字符串，以减少性能监控的开销。
  • 添加了具有异步和回调支持的 loop(filter) 方法
• 版本 8.0.1
  • 将目录重构为两个包（pynvml 和 nvidia_smi）
  • 为两个包添加初始测试
  • 在 pynvml 中进行一些命名约定清理
• 版本 8.0.2
  • 为 pynvml 模块添加了 NVLink 函数封装
• 版本 8.0.3
  • 添加了 versioneer
  • 修复 nvmlDeviceGetNvLinkUtilizationCounter 错误
• 版本 8.0.4
  • 添加了 nvmlDeviceGetTotalEnergyConsumption
  • 添加了有关 NVML 权限的说明
  • 修复了版本检查测试
• 版本 11.0.0
  • 更新 nvml.py 以支持 CUDA 11
  • 更新 smi.py DeviceQuery 到 R460
  • 与最新的 nvidia-ml-py 部署对齐 nvml.py
• 版本 11.4.0
  • 更新 nvml.py 以支持 CUDA 11.4
  • 更新 smi.py NVML_BRAND_NAMES
  • 与最新的 nvidia-ml-py 部署（11.495.46）对齐 nvml.py
• 版本 11.4.1
  • 修复 nvml.py 中的逗号错误
• 版本 11.5.0
  • 更新 nvml.py 以支持 CUDA 11.5 和 CUDA 12
  • 与最新的 nvidia-ml-py 部署（11.525.84）对齐
• 版本 11.5.2
  • 将 smi 绑定重新定位到新的 pynvml_utils 模块
  • 更新README，鼓励迁移到nvidia-ml-py
• 版本 11.5.3
  • 更新versioneer