NVIDIA/go-nvml

項目簡介

NVIDIA/go-nvml 是 NVIDIA 的 NVML（NVIDIA Management Library）的 Go 語言封裝。NVML 是一個位於驅動提供之共享函式庫 libnvidia-ml.so 中的 C API，可讓程式查詢與控制 NVIDIA GPU（溫度、使用率、電力限制、UUID 等）。本倉儲並未重新實作 NVML；它僅透過 cgo 和少量手寫「包裝器」程式碼，將現有的 C 函數暴露給 Go 程式碼，使 API 更符合 Go 的慣用風格。

適用對象

• 需要查看 Linux 主機上有哪些 GPU 的監控、編排或排程工具的 Go 開發者。
• 希望以 Go 編寫自訂健康檢查、自動擴縮器或資源分配服務的 AI/ML 集群運維人員。
• 需要將工作綁定至特定 GPU 或讀取功耗/溫度指標的 Go 基礎推理或訓練流程開發者。

工作原理（高階）

1. 生成步驟 – 倉儲包含 NVIDIA 的標頭 nvml.h 和一個 c-for-go 描述檔案（nvml.yml）。執行 c-for-go 工具會自動產生與每個 C 函數對應的低階 Go 綁定。
2. 動態載入 – 執行時，該套件會從主機系統載入 libnvidia-ml.so（必須安裝驅動）。它也會偵測哪些版本化符號（例如 nvmlInit_v2）存在，並將預設的 v1 符號替換為較新的版本。
3. 手寫包裝器 – 自動產生的綁定非常接近原始 C API，直接使用相當繁瑣。本專案新增一層薄的、手寫的包裝器（例如 Device.GetUUID()、Device.GetAccountingPids()），用於處理緩衝區配置、錯誤轉換和 Go 風格的回傳值。
4. 錯誤處理 – 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；未推斷任何額外功能。