shanselman/gputaskman

项目介绍

gputaskman 是一个终端 UI，作者把它比作「GPU 内部的 htop」：任务管理器只说「已用 15 GB」，它则试图回答这些显存被什么占用——模型权重、KV 缓存、浏览器还是桌面合成器，以及为什么有这么多显存落在系统内存里。它把每个进程的 GPU 内存和引擎活动与已加载的运行时、映射的模型文件以及 LLM 的权重/KV 缓存/计算缓冲估算关联起来，面向本地的决策模型、视觉、语音、LLM 推理、训练、图形和视频负载，覆盖 Windows（NVIDIA/AMD）、原生 Linux 与 WSL（NVIDIA）以及 Apple Silicon macOS。云端、纯 CPU 和纯 NPU 负载不在范围内。

README 明确区分证据等级：设备和进程计数器是测量值，模型识别与 GGUF 推导出的拆分是估算；加载了某个 DLL 或映射了某个文件，并不能证明模型驻留在 GPU 上或正在执行。设备视图显示显存、GPU/内存活动、PCIe、温度、功耗和历史图表；进程视图显示各进程内存、Spill（可被 GPU 访问的系统内存）和估算的 Paged，并识别 CUDA、HIP、Vulkan、Direct3D、ggml、ONNX Runtime 等运行时；模型检查器在证据充分时给出模型名称和权重/KV 拆分。

快速使用

在 64 位 Windows 10/11、NVIDIA 或 AMD GPU 与较新 WDDM 驱动下，最快路径是从 Releases 页面下载便携版：取 gputaskman-VERSION-windows-x64.zip（ARM64 用 arm64 包），把整个 ZIP 解压并保持 _internal 与 gputaskman.exe 同级，然后在该目录运行：

.\gputaskman.exe
.\gputaskman.exe --once
.\gputaskman.exe --json

便携版无需 Python、uv 或 CUDA Toolkit；当前构建未签名，并提供 .zip.sha256 校验文件。

从源码运行则先安装 Git for Windows 和 uv，打开新的 PowerShell 窗口后执行：

winget install --id Git.Git --exact
winget install --id astral-sh.uv --exact
git clone https://github.com/shanselman/gputaskman.git
cd gputaskman
uv run --locked gputaskman

uv 会取用固定版本的 Python、创建 .venv 并安装锁定依赖，首次运行需要联网；首次采样完成后进入 TUI。原生 Linux 和 WSL 使用同样的 uv run --locked gputaskman，也可用 Linux 压缩包（要求 glibc 2.35+）；macOS 目前只能从克隆运行。

常用操作

方向键选择进程，s 循环排序（VRAM、GPU%、spill、paged、名称），c 切换图表视图，a 切换顶部/全部进程，p 暂停采集，? 查看计数器说明，q 退出。终端宽度约 140 列以上时表格更易读，新加载的模型可能需要约 15 秒才出现。

脚本化使用可先输出 JSON 快照，再用 diff 对比两次快照：

uv run --locked gputaskman --json > before.json
# 加载模型或修改上下文长度，然后发送一次请求
uv run --locked gputaskman --json > after.json
uv run --locked gputaskman diff before.json after.json

「after」快照应在模型完成一次请求后再取，因为分配器会缓存已释放内存，减小可能延迟显现。--list-gpus 与 --gpu N 用于选择适配器，--no-host 在 WSL 中关闭 Windows 主机计数器流。

使用约束

• Windows：按进程内存来自 WDDM 计数器；GeForce 在 WDDM 下 NVML 可能把进程内存报为 N/A，这正是该工具要解决的场景。AMD 设备遥测依赖驱动提供的 ADL，AMD SMI 作为可选后备，需要单独安装 Python 包。
• 原生 Linux：读取 NVML 进程列表和利用率采样；Linux 没有 WDDM 对应物，因此 Spill 和 Paged 为空。查看其他用户的进程需要 sudo。
• WSL：Linux 看不到自己进程的显存，gputaskman 通过 interop 转发 Windows 主机计数器。vmwp.exe 给出精确的 VM 总量，但进程归属是推断（*）或猜测（?）。关闭 interop 或使用 --no-host 时，Linux 行显示 n/a。
• macOS：Apple GPU 与 CPU 共享内存，没有显存拆分；其他用户的进程显示 GPU% 但内存为 n/a，除非用 sudo 运行。Metal 只按进程提供 GPU 时间，没有引擎拆分。
• 测量与估算：KV 和权重数字来自 GGUF 元数据、启动参数、运行时日志和本地服务 API，永远不会加到测量总量上。缺失计数器在文本中显示 N/A，在 JSON 中为 null，而不是零。
• 隐私：检查器和 JSON 输出可能包含路径、命令行参数、模型名称和本地端口，公开分享前应做脱敏；工具不发送遥测。

项目状态

项目自述为早期实验性软件。README 列出的实机验证包括 RTX 4080 SUPER、Windows ARM64 上的 RTX Spark N1X、M4 Mac mini 以及 Vast.ai 上 RTX 3060 Ti 容器，同时明确未验证的领域：裸金属 Linux 硬件、多 GPU 与混合厂商、AMD SMI 遥测、Vulkan/ROCm 负载以及 Copilot+ PC 上的 WinML/Studio Effects。MIT 许可证允许商用和修改。

HotRepo 点评

项目非常新：创建于 2026-11-03，次日进入 Python 新项目榜，在截至 2026-11-04 22:45 UTC 的约两小时窗口内新增 5 星，当时累计 105 星、6 个 fork。样本很小，不能据此判断趋势。更值得注意的是文档对「测量、推断、估算」三者边界的坚持，包括 WSL 上下文匹配方案和与 llama.cpp 日志的抽样对照。对调整本地 LLM 显存的人来说，这种严谨是尝试它的主要理由，也应在自己的硬件上自行复核。