NVIDIA/go-nvml

项目简介

NVIDIA/go-nvml 是 NVIDIA 的 NVML（NVIDIA 管理库）的 Go 语言封装。NVML 是一个位于驱动提供的共享库 libnvidia-ml.so 中的 C API，允许程序查询和控制 NVIDIA GPU（温度、利用率、功耗限制、UUID 等）。本仓库并未重新实现 NVML；它仅通过 cgo 和少量手写“包装器”代码，将现有的 C 函数暴露给 Go 代码，使 API 更符合 Go 的惯用风格。

适用人群

需要查看 Linux 主机上存在哪些 GPU 的监控、编排或调度工具的 Go 开发者。
希望用 Go 编写自定义健康检查、自动扩缩器或资源分配服务的 AI/ML 集群运维人员。
需要将工作绑定到特定 GPU 或读取功耗/温度指标的 Go 基础推理或训练流水线开发者。

工作原理（高层次）

生成步骤 – 仓库包含 NVIDIA 头文件 nvml.h 和一个 c-for-go 描述文件（nvml.yml）。运行 c-for-go 工具会自动生成与每个 C 函数对应的低级 Go 绑定。
动态加载 – 运行时，该包会从主机系统加载 libnvidia-ml.so（必须安装驱动）。它还会检测哪些版本化符号（如 nvmlInit_v2）存在，并将默认的 v1 符号替换为较新的版本。
手动包装器 – 自动生成的绑定非常接近原始 C API，直接使用很繁琐。该项目添加了一层薄的、手写的包装器（如 Device.GetUUID()、Device.GetAccountingPids()），用于处理缓冲区分配、错误转换和 Go 风格的返回值。
错误处理 – NVML 返回码被封装为 Go 的 error 类型，调用者可以使用熟悉的 if err != nil 模式。

快速示例（来自 README）

import (
    "fmt"
    "log"
    "github.com/NVIDIA/go-nvml/pkg/nvml"
)

func main() {
    if ret := nvml.Init(); ret != nvml.SUCCESS {
        log.Fatalf("NVML init failed: %v", nvml.ErrorString(ret))
    }
    defer nvml.Shutdown()

    count, _ := nvml.DeviceGetCount()
    for i := 0; i < count; i++ {
        dev, _ := nvml.DeviceGetHandleByIndex(i)
        uuid, _ := dev.GetUUID()
        fmt.Println(uuid)
    }
}

在安装了 NVIDIA 驱动的机器上运行此代码，将打印出每个 GPU 的 UUID，与 README 中所示完全一致。

构建与测试工作流

安装 c-for-go 工具（Makefile 固定特定版本）。
运行 make – 这将重新生成绑定并复制到 pkg/nvml。
运行 make test – 执行一个小的测试套件，检查初始化、驱动版本查询、事件集处理等。即使没有实际 GPU 驱动，测试也能正常运行；只需共享库可加载即可。

限制

仅限 Linux – 绑定依赖于 libnvidia-ml.so，该文件仅在 Linux 驱动中提供。
运行时依赖 – 你可以无需驱动编译代码，但调用任何函数时，如果运行时找不到该库，将引发 panic。
测试覆盖率稀疏 – README 指出测试套件目前较小，可进一步扩展。

无需使用的情况

如果你使用 Python、C++ 或 NVIDIA 自带工具（如 nvidia-smi）开发 GPU 友好的软件，则不需要此 Go 包装器。它专门用于希望直接、低开销访问 NVML 的 Go 项目。

以上所有细节均直接取自仓库的 README；未推断任何额外功能。