janpauldahlke/dsh-gpu-monitor-nvml

dsh-gpu-monitor-nvml

一个用于 DeepSeek Harness Web UI 的实时多 GPU 监控面板。右侧边栏中的一个标签页，每秒采样一次，每个指标都有明确的名称——因此一组 GPU 读起来就像一块仪表盘，而不是原始数据转储。

基于真实硬件构建并验证：一块 NVIDIA RTX 4080 SUPER（索引 0）和一块 NVIDIA RTX A4000（索引 1），两者同时显示在面板中。

要求

- 仅限 NVIDIA GPU + 驱动。不支持 AMD 和 Intel GPU（无指标）。
- DeepSeek Harness Web 配置（dsh web）。

平台支持

| 平台 | 指标 | 备注 |
| --- | --- | --- |
| Linux | NVML（首选），nvidia-smi 回退 | 完全支持 |
| Windows | nvidia-smi（目前首选） | node-nvml 仅提供 Linux 二进制文件；如果出现 Windows 绑定，将自动使用 NVML。欢迎社区测试者。 |
| macOS | 仅存根 | 现代 Mac 上没有 NVIDIA——不是真正的监控目标 |

截图

浅色主题，与 DSH 默认主题一致。

| 面板打开 | 停靠芯片（面板关闭） |
| --- | --- |
| GPU Monitor 面板 | Composer 停靠芯片 |

| 折叠卡片 |
| --- |
| 折叠的 GPU 卡片 |

如果图片加载失败，下面的 ASCII 示意图仍能传达布局。

你会看到什么

GPU Monitor  [NVML]   updated 1 s ago

GPU 0 · NVIDIA RTX 4080 SUPER
GPU util      62 %      ▓▓▓▓▓▓▓▓░░
Mem util      35 %      ▓▓▓▓░░░░░░
VRAM          9.7 / 16 GiB   free 5.4 GiB   ▓▓▓▓▓▓▓▓▓░
Power draw    261 W   limit 320 W   ▓▓▓▓▓▓▓░░░
SM clock      2460 MHz   Mem clock 1313 MHz
── Trend · last 2 min ──
┌─────────────────────────────────┐
│   util ───  vram ──  power ┈┈   │   3 series, 120 pts @ 1 Hz
└─────────────────────────────────┘
Processes · VRAM
llama-server  pid 1113321   9.4 GiB

GPU 1 · NVIDIA RTX A4000
...

- 每个数字都有明确的名称。“GPU util”（计算）绝不会与“Mem util”（内存总线）混淆。VRAM 显示已用 / 总量以及可用量。Power 将功耗和上限显示为两个有名称的量。时钟显示为“SM clock”和“Mem clock”。进程显示名称 + pid，VRAM 以 GiB 为单位。
- 每一行都有工具提示（title）：该指标是什么以及来自哪里，包括 NVML 与 smi 的“used”语义（见下方数据诚实性）。
- 计量条出现在四个可计量的行上（GPU util、Mem util、VRAM、Power draw），一眼即可看出占刻度的比例；当达到其刻度的 ≥ 95 % 时，计量条会变为琥珀色。
- 每个 GPU 的 2 分钟迷你趋势条——利用率趋势、VRAM 占用趋势，以及功耗与上限趋势，共用同一个 0–100 % 刻度。1 Hz 下 120 个点，滚动窗口，感知缺口的路径绘制（缺失的指标会抬笔，而不是绘制一个虚假的零）。
- 实时诚实性：1 Hz 轮询、no-store、来源徽章（NVML / smi）、集群标题中的“updated N s ago”，以及每个 GPU 的错误说明。过期数据会被标记为过期，绝不会被平滑成谎言。

数据诚实性
Linux 上的主要数据源是通过 node-nvml 提供的 NVML，以原始 C-FFI 方式驱动（一个 js 代理对零参数输出指针调用的改写迫使我们使用原始 API）。每个字段都独立采样：某个指标失败只会让该行显示为“无数据”，绝不会让 GPU 变空，而且 sampleFleet() 从不抛出异常。

有两个值得了解的语义，均在工具提示中有说明：

- NVML 的“已用” ≠ nvidia-smi 的“已用”。 memoryUsedMiB 是 total − free，其中包含驱动/上下文预留（在此硬件上约 400–430 MiB），因此 NVML 的读数高于 nvidia-smi 基于进程的列。这是有意为之；为清晰起见，同时暴露了 memoryFreeMiB。
- 降级模式有标记。 如果 NVML 不可用，主机将回退到解析 nvidia-smi，面板会显示一个 smi 徽章，这样你始终知道正在查看的是哪个数据源。在 Windows 上，这是目前预期的路径。

架构

这是一个双面插件包：一个 npm 包，两个运行时。

- 主机面（lib/index.js，ESM）——注册插件，拥有一个 1 秒采样循环
（SAMPLE_INTERVAL_MS = 1000），并在与页面同源的
GET /api/dsh-gpu-monitor 上提供 JSON 快照。
- 客户端面（lib/client.js，CJS 闭包工厂）——由 Web 客户端通过
window.__ModuleLoader__.load({ id, factory }) 加载。自链式 1 Hz fetch（no-store，
可中止），将面板渲染到右侧边栏标签槽中，并为每个 GPU 保留一个滚动历史缓冲区（上限为 120 个点），用于驱动迷你图。
- 粘合——cordis.patch.yml 为双面包插入一行 Loader；浏览器部分通过 package.json 中的 dsh.client 声明被发现。

客户端约束已遵守：运行时只能 require 冻结的 PLATFORM_MODULES
（react、cordis、client store、ui slots/primitives/dockkit）；其他所有内容都由
esbuild 内联。呈现方式仅使用内联样式——打包产物中没有 CSS 文件。

dsh-gpu-monitor-nvml/
├── package.json          # 双面导出："."（主机）和 "./client"（浏览器）
├── build.mjs             # esbuild，两个配置（主机 ESM + 客户端 CJS 闭包工厂）
├── cordis.patch.yml      # Loader 行
├── media/                # README 截图
├── src/
│   ├── host/
│   │   ├── index.ts      # 插件注册 + 采样循环
│   │   ├── route.ts      # 客户端轮询的确切路由
│   │   ├── collect.ts    # NVML 采样器（原始 C-FFI，逐字段隔离）
│   │   └── collect-smi.ts# 带标记的降级回退（Windows PATH / .exe）
│   ├── client/
│   │   ├── index.tsx     # 槽位注入
│   │   ├── GpuBody.tsx   # 面板：行、仪表、迷你图、历史
│   │   └── GpuTitle.tsx  # 标签芯片
│   └── shared/
│       └── types.ts      # GpuSample / GpuFleetSnapshot / GpuProcess / round1
└── lib/                  # 预构建输出（已提交，用于无工具链安装）

安装

需要带有 Web 配置文件的 DeepSeek Harness 以及 NVIDIA 驱动
（nvidia-smi 至少要在 PATH 中；Linux 上通过 node-nvml 使用 NVML）。

从 GitHub 安装（用户）

dsh plugin --profile web add github:janpauldahlke/dsh-gpu-monitor-nvml
重启 dsh web（或依赖实时补丁重载），然后强制刷新浏览器

lib/ 已提交，因此安装不需要本地 TypeScript/esbuild 工具链。

从 git checkout 安装（开发者）

git clone https://github.com/janpauldahlke/dsh-gpu-monitor-nvml.git
cd dsh-gpu-monitor-nvml
npm install          # 拉取 node-nvml；若工具链存在，prepare 会构建 lib/
node build.mjs       # 可选：强制重建 → lib/index.js + lib/client.js

接入你的 web profile（绝对路径；link: 依赖 + bundle 入口）
dsh plugin --profile web add "$PWD"

这会将 ~/.dsh/profiles/web/package.json 大致更新为：

"dependencies": {
"dsh-gpu-monitor-nvml": "link:/abs/path/to/dsh-gpu-monitor-nvml"
},
"dsh": {
"profile": {
"bundles": [
"@deepseek-ai/dsh-base",
"@deepseek-ai/dsh-web-app",
"dsh-gpu-monitor-nvml"
]
}
}

重启 dsh web，强制刷新。右侧栏的 GPU 标签页和页脚停靠栏的小徽章
应该会出现。

开发循环

编辑 src/ → 重新构建（profile 已经 link: 到这棵目录树）
node build.mjs
宿主端通常随 patchReload: live 热重载；客户端部分：强制刷新

如果 profile 无法解析该包名：

ln -sfn "$PWD" "$HOME/.dsh/profiles/web/node_modules/dsh-gpu-monitor-nvml"

不要只链接到 harness monorepo 的 node_modules —— Cordis 是从
profile 解析的。

验证

dsh --profile web --dump-config | grep -E 'gpu-monitor|dsh-gpu-monitor-nvml'
curl -s http://127.0.0.1:3080/api/dsh-gpu-monitor | head   # 调整端口
预期返回 JSON：ok、source（"nvml"|"smi"）、gpus[]

移除：

dsh plugin --profile web remove dsh-gpu-monitor-nvml

这是如何构建的

这不是一次性的代码生成演示。大约在真实硬件上进行了一整天的闭环迭代：
研究 DSH 插件契约、搭建脚手架、通过原始 C-FFI 打通 NVML、弄坏东西、修好它们、
打磨面板（命名指标、仪表、迷你走势图），并在专用的验收端口上重新检查每一轮
—— 全程不碰神圣端口（:3080 主 dsh、:8080 llama-server、:11434 ollama）。
最终成果很小，运行时只依赖 node-nvml，并标注了每个数字的来源。

作者

这是作为人类 ↔ 本地模型配对构建的，既不是“AI 做的”，也不是“人类只做了
审查”。

- Jan (hagbardCeline) —— 软件工程师。设定目标与约束，主导架构与诚实
规则（NVML vs smi，绝不对陈旧数据撒谎），针对真实 GPU 驱动接受/拒绝
循环，砍掉错误路径，并拥有最终“发布它”的决定权。品味是这份工作的一部分；
在数小时的迭代中做出工程判断也是。
- Qwen3.8 27B Q6 HauHau（合著者）—— 在该循环下编写了大部分实现：
宿主采样器、客户端 UI、构建胶水。由 llama.cpp 提供服务，
tensor-split（-ts 1,1）跨同一对显卡，正是此插件所监控的两块——
RTX 4080 SUPER + RTX A4000。在窗格中，llama-server 是共同作者
在思考。
- 硬件 —— Ryzen 7 7800X3D，61 GiB 内存，双 16 GiB NVIDIA GPU。这是
通宵运行从未离开的实验室。

有趣之处在于递归：一个智能体帮助构建一个监控其自身运行所用 GPU 的监视器，
而人类全程参与其中，不是作为旁观者，而是作为搭档的另一半。

许可证： MIT · 贡献指南