utkuozdemir/nvidia_gpu_exporter · 上手攻略
- 仓库：utkuozdemir/nvidia_gpu_exporter
- 链接：https://github.com/utkuozdemir/nvidia_gpu_exporter
- 分类：ai
- 作者：Jay
- 更新：2026-08-12
是什么
nvidia_gpu_exporter 是一个用 Go 编写的 Prometheus GPU 指标导出器，底层调用 nvidia-smi（NVIDIA 系统管理接口）采集显卡实时状态——包括 GPU 利用率、显存占用、温度、功率、风扇转速、时钟频率等——并以 Prometheus 标准格式（/metrics 端点）暴露出来，可直接对接 Grafana 渲染监控面板。
它的核心定位是轻量级 GPU 监控：适合消费级显卡（GeForce/RTX）、小型 Kubernetes 集群、边缘设备、vGPU/MIG 切片环境，以及那些不想装一整套 NVIDIA GPU Operator 但又想看到 GPU 指标的用户。相比官方 DCGM-exporter，它不需要 CUDA Toolkit，部署门槛更低，一个二进制或一行 Docker 命令即可运行。
架构上，exporter 分为两种采集后端：
- exec 后端（默认）：调用 nvidia-smi 命令行，解析其输出。支持所有操作系统（Windows/Linux/macOS），但 nvidia-smi 输出格式在不同驱动版本/GPU 型号间存在差异，仓库已内置大量测试用例覆盖。
- nvml 后端（实验性）：直接读取 NVIDIA 驱动库（libnvidia-ml），无需 nvidia-smi 二进制，仅 Linux 支持，可获取 nvidia-smi 无法提供的 per-MIG-instance 指标、XID 错误计数、总能耗、PCIe 吞吐量。
解决什么问题
在 GPU 监控领域，官方方案 DCGM（Data Center GPU Manager）功能完整但部署复杂，需要 NVIDIA GPU Operator、CUDA 运行时和一系列依赖。nvidia_gpu_exporter 的设计哲学是：最小化依赖，只用 nvidia-smi，就能在 Windows、Linux、macOS 上跑起来。同时它自带两个 Grafana Dashboard（单卡详情 + 多卡概览），装完就能看图，省去 dashboard 配置时间。
快速安装
方式一：Docker（最简，推荐）
# 默认版本（exec 后端，依赖 nvidia-smi）
docker run -d \
--name nvidia_gpu_exporter \
--restart unless-stopped \
--gpus all \
-p 9835:9835 \
utkuozdemir/nvidia_gpu_exporter:latest
# NVML 后端（无需 nvidia-smi，直接读驱动库，⚠️实验性，仅 Linux）
docker run -d \
--name nvidia_gpu_exporter \
--restart unless-stopped \
--gpus all \
-e NVIDIA_DRIVER_CAPABILITIES=utility \
-p 9835:9835 \
utkuozdemir/nvidia_gpu_exporter:latest-nvml
⚠️ Docker 方式要求 GPU 可见（
--gpus all）和nvidia-container-toolkit已正确安装。NVIDIA_DRIVER_CAPABILITIES=utility是 NVML 后端镜像的必要环境变量，否则容器无法访问驱动库。
方式二：二进制直接运行
# Linux x86_64 示例（版本号请替换为最新，参见 Releases 页面）
VERSION=X.Y.Z
wget https://github.com/utkuozdemir/nvidia_gpu_exporter/releases/download/v${VERSION}/nvidia_gpu_exporter_${VERSION}_linux_x86_64.tar.gz
tar -xvzf nvidia_gpu_exporter_${VERSION}_linux_x86_64.tar.gz
mv nvidia_gpu_exporter /usr/bin/nvidia_gpu_exporter
# 验证
nvidia_gpu_exporter --help
# 启动（前台测试，Ctrl+C 终止后转为 systemd 服务）
nvidia_gpu_exporter
⚠️ 版本号请以 Releases 页面 为准，建议不要硬编码版本号，本攻略亦不做版本号硬编码以避免过时引用。
方式三：deb / rpm 包（系统管理友好）
# Debian 系（Ubuntu/Debian）
sudo dpkg -i nvidia-gpu-exporter_<version>_amd64.deb
# RPM 系（CentOS/RHEL/Fedora）
sudo rpm -i nvidia-gpu-exporter-<version>.x86_64.rpm
# 安装后自动注册 systemd 服务（deb/rpm 包默认处理）
sudo systemctl enable nvidia-gpu-exporter
sudo systemctl start nvidia-gpu-exporter
⚠️ deb/rpm 包仅支持 systemd init 系统，不支持 SysVinit 或其他 init 系统。
方式四：Windows PowerShell 一键脚本
# 1. 下载安装脚本（保存为 .ps1 文件）
# 下载地址：https://raw.githubusercontent.com/utkuozdemir/nvidia_gpu_exporter/main/install/windows-all-in-one.ps1
# 2. 管理员 PowerShell 运行（会自动装 Prometheus + Grafana + Exporter 三件套）
powershell -NoProfile -ExecutionPolicy Bypass -File .\windows-all-in-one.ps1
# 验证
# Prometheus: http://localhost:9090
# Grafana: http://localhost:3000 （默认账号 admin / admin）
⚠️ 如果之前用 scoop+ssm 方式安装过旧版，先运行同目录下的
windows-all-in-one-uninstall.ps1清除旧服务，否则可能冲突。卸载脚本保留历史数据（只删服务本身）。
方式五：winget（Windows，包管理器）
# 用户级安装（PATH 自动加入）
winget install utkuozdemir.nvidia_gpu_exporter
# 如需注册为 Windows 服务（需管理员权限，系统级安装）
winget install --scope machine utkuozdemir.nvidia_gpu_exporter
nvidia_gpu_exporter install
核心用法
1. Prometheus 接入配置
# prometheus.yml
scrape_configs:
- job_name: 'nvidia_gpu'
static_configs:
- targets: ['localhost:9835']
scrape_interval: 15s # 推荐，不要太频繁（nvidia-smi 有开销）
scrape_timeout: 10s
⚠️ 默认
--collect.timeout为 10s，Prometheus 的scrape_timeout应略大于 exporter 的 collection timeout。
2. 常用命令行参数
# 指定监听地址（默认 :9835）
nvidia_gpu_exporter --web.listen-address :9100
# 指定 nvidia-smi 路径（默认 "nvidia-smi"）
nvidia_gpu_exporter --nvidia-smi-command /usr/bin/nvidia-smi
# 开启 per-process GPU 指标（哪个进程用了多少显存）
nvidia_gpu_exporter --collect.compute-apps
# Docker 中使用 hostPID（看到宿主机进程）
docker run --gpus all --pid=host utkuozdemir/nvidia_gpu_exporter:latest --collect.compute-apps
# 开启 NVML 后端（实验性，Linux）
nvidia_gpu_exporter --collect.backend=nvml
# Demo 模式（无 GPU 也能跑，用于测试 dashboard）
nvidia_gpu_exporter --collect.backend=demo
# 指定自定义 nvidia-smi（通过 SSH 远程执行）
nvidia_gpu_exporter --nvidia-smi-command "ssh user@gpu-host sudo nvidia-smi"
# 排除慢速/不支持的字段（避免报错）
nvidia_gpu_exporter --query-field-names-exclude "remapped_rows.histogram.*"
3. 指标解读
exporter 暴露的主要指标（命名以 nvidia_gpu_ 开头）：
| 指标名 | 类型 | 说明 |
|---|---|---|
nvidia_gpu_utilization_percent |
gauge | GPU 利用率 % |
nvidia_gpu_memory_used_bytes |
gauge | 显存已用（字节） |
nvidia_gpu_memory_total_bytes |
gauge | 显存总量（字节） |
nvidia_gpu_memory_free_bytes |
gauge | 显存剩余（字节） |
nvidia_gpu_temperature_celsius |
gauge | GPU 温度（℃） |
nvidia_gpu_power_usage_watts |
gauge | 当前功率（W） |
nvidia_gpu_power_draw_watts |
gauge | 实际功率（W，部分卡） |
nvidia_gpu_fan_speed_percent |
gauge | 风扇转速 % |
nvidia_gpu_clock_sm_mhz |
gauge | SM（流多处理器）时钟（MHz） |
nvidia_gpu_clock_memory_mhz |
gauge | 显存时钟（MHz） |
nvidia_gpu_clock_video_mhz |
gauge | 视频编解码时钟（MHz） |
nvidia_gpu_process_memory_bytes |
gauge | 单进程 GPU 内存占用（per-process，需 --collect.compute-apps） |
nvidia_xid_errors_total |
counter | XID 错误计数（NVML 后端专用） |
nvidia_gpu_energy_total_joules |
counter | GPU 总能耗（焦耳，NVML 后端专用） |
nvidia_gpu_pcie_throughput_* |
gauge | PCIe 吞吐量（NVML 后端专用） |
配套 Grafana Dashboard
exporter 自带两个官方 Grafana Dashboard，导入方式二选一：
方式一：Grafana 内 Import（推荐） - 单卡详情 Dashboard：ID 14574（Dashboards → New → Import → 输入 14574） - 多卡概览 Dashboard：ID 25547（同上，输入 25547）
方式二：Helm chart 自动 Provision
# values.yaml
grafanaDashboard:
enabled: true # 自动 provision 两张 Dashboard
Dashboard JSON 文件也保存在仓库 docs/grafana/ 目录下，可离线使用或自行修改主题色。
⚠️ NVML 后端专属指标（XID errors、energy total、PCIe throughput）在默认 exec 后端下对应面板为空，属于正常现象；换上 NVML 后端后这些面板会自动亮起。
典型适用场景
| 场景 | 推荐安装方式 | 推荐后端 |
|---|---|---|
| 小型 homelab / 游戏主机 GPU 监控 | Docker 或 winget + Grafana | exec（默认） |
| 小型 Kubernetes 集群（无 GPU Operator） | Helm chart | exec 或 nvml |
| 边缘设备 / 工控机 GPU 监控 | 二进制 + systemd | exec |
| vGPU / MIG 切片环境 | Docker + NVML 后端 | nvml（必需） |
| 多卡服务器统一 Prometheus 看板 | Helm chart + Grafana | exec 或 nvml |
| 快速验证 exporter 配置（无 GPU） | Demo 模式 | demo |
坑与注意
- NVML 后端为实验性：
--collect.backend=nvml标记为 experimental，主要因为需要更多驱动版本/GPU 型号的真实环境测试积累。生产环境建议默认使用 exec 后端；如需 per-MIG-instance 指标或 XID 错误计数，可在 staging 环境验证后再上生产，并记得提 issue 反馈体验。 - Windows nvidia-smi 路径含空格：Windows 上
nvidia-smi.exe默认路径为C:\Program Files\NVIDIA Corporation\NVSMI\nvidia-smi.exe，必须完整引用：--nvidia-smi-command '"C:\Program Files\NVIDIA Corporation\NVSMI\nvidia-smi.exe"'。 - Prometheus scrape 超时：
--collect.timeout默认 10s，复杂 nvidia-smi 查询（多卡 + per-process + 网络存储延迟）在机械盘环境下可能超时，需适当调大--collect.timeout。 - Docker NVIDIA_DRIVER_CAPABILITIES：使用
latest-nvml镜像时必须设置NVIDIA_DRIVER_CAPABILITIES=utility，否则容器无法访问 NVML 库；exec 后端镜像默认无需此变量。 - Per-process 指标需要 hostPID：在 Kubernetes 中需配置
hostPID: true，或在 Docker 中加--pid=host，否则 exporter 看不到其他进程的 GPU 占用。 - GPG 签名验证（可选，推荐）：release 的
checksums.txt.asc用 GPG 签名覆盖所有二进制/包，正式环境建议校验：bash curl -fsSL https://utkuozdemir.github.io/nvidia_gpu_exporter/pubkey.asc | gpg --import gpg --verify checksums.txt.asc checksums.txt sha256sum --ignore-missing -c checksums.txt - Cosign 镜像签名验证（可选）：
bash cosign verify \ --certificate-identity-regex '.*' \ --certificate-oidc-issuer-regex '.*' \ utkuozdemir/nvidia_gpu_exporter:latest-nvml
与同类对比
| 方案 | 语言 | 核心依赖 | Windows | 多卡 | MIG 支持 | Dashboard |
|---|---|---|---|---|---|---|
| nvidia_gpu_exporter | Go | nvidia-smi（可选 NVML） | ✅ | ✅ | ✅（nvml） | ✅ 两张 |
| DCGM-exporter | Go | DCGM/CUDA | ❌ | ✅ | ✅ | ✅ |
| node_exporter + textfile | Go | nvidia-smi + cron | ✅ | ✅ | ❌ | ❌ |
| Telegraf NVIDIA plugin | Go | nvidia-smi | ✅ | ✅ | ❌ | ❌ |
DCGM-exporter 适合数据中心级 Kubernetes 部署（与 GPU Operator 深度集成，支持完整 DCGM 指标）；nvidia_gpu_exporter 适合轻量场景——消费卡、小型集群、边缘设备、vGPU/MIG 环境，以及需要一站式 Windows 监控的用户。
一句话推荐结论
nvidia_gpu_exporter 是目前安装门槛最低的 Prometheus GPU 监控方案，一行 Docker、一个二进制或一个 winget 命令就能跑起来，配套 Grafana Dashboard 开箱即用；唯一需要注意的是 NVML 后端仍在实验阶段，生产环境优先用默认 exec 后端，如需 MIG 分片指标或 XID 错误监控再考虑 NVML 后端并留意稳定性。
原始 commit/PR：https://github.com/utkuozdemir/nvidia_gpu_exporter/commits/main · Releases · ⚠️ NVML 后端为 experimental，生产环境建议默认 exec 后端；Windows nvidia-smi 路径含空格需完整引用；Per-process 指标在容器中需要 hostPID