llmtop：面向LLM推理集群的实时监控利器

一款类htop的终端监控工具，支持vLLM、SGLang、NVIDIA NIM等主流推理框架，提供KV缓存、队列深度、延迟指标和GPU资源的实时可视化，原生支持Kubernetes自动发现。

传统的系统监控工具如htop、top专注于CPU、内存、进程级别的资源消耗，而LLM推理服务有其独特的监控需求：KV缓存命中率、请求队列深度、首Token延迟（TTFT）、Token间延迟（ITL）、Token吞吐量等。这些指标直接影响用户体验和模型服务的响应质量。

llmtop的设计理念借鉴了htop的成功经验——在终端中提供实时、交互式的监控视图，但针对LLM推理场景进行了深度定制。它支持多种主流推理框架，原生兼容Kubernetes环境，能够在不暴露额外端口、无需复杂配置的情况下，快速接入现有推理集群。

llmtop提供了多层次的监控视图，满足不同场景下的运维需求。

实时推理指标监控是llmtop的基础能力。工具默认展示所有工作节点的KV缓存状态、请求队列深度、TTFT和ITL延迟、Token吞吐量等关键指标。这些数据以秒级刷新，帮助运维人员快速识别性能瓶颈。例如，当KV缓存接近饱和时，系统响应延迟会显著上升，llmtop能够及时预警这类风险。

GPU资源视图（快捷键g）通过集成NVIDIA DCGM exporter，展示GPU利用率、显存占用、温度和功耗等硬件级指标。这对于GPU集群的容量规划和故障排查至关重要。在多卡部署场景下，运维人员可以快速定位哪张卡出现瓶颈或异常。

模型分组视图（快捷键m）提供了按模型聚合的统计视角。当集群中部署了多个模型（如不同版本的Llama、不同参数的Qwen）时，这一视图能够直观对比各模型的负载分布和资源消耗，辅助进行调度决策。

快照模式（--once --output json）适合集成到CI/CD流水线或自动化脚本中，用于定期采集集群状态或作为健康检查的一部分。

llmtop的一大亮点是其广泛的后端兼容性。目前支持的主流推理框架包括：

vLLM：作为目前最流行的开源推理引擎，vLLM提供了完整的指标暴露，llmtop能够自动识别vLLM的metric前缀并采集所有关键指标。

SGLang：由伯克利大学开发的推理框架，以其高效的调度机制著称。llmtop完整支持SGLang的指标采集。

LMCache：专注于KV缓存优化的项目，llmtop能够监控其缓存命中率和效率指标。

NVIDIA NIM：NVIDIA推出的企业级推理微服务，llmtop支持其标准的metrics端点。

NVIDIA Dynamo：NVIDIA的新一代推理框架，llmtop能够自动识别前端节点，并区分预填充（prefill）和解码（decode）工作节点进行标签化管理。

其他支持：包括TGI（HuggingFace）、TensorRT-LLM、Triton Inference Server、llama.cpp、LiteLLM代理和Ollama等。这种广泛的兼容性使得llmtop成为异构推理环境的统一监控入口。

在云原生时代，大多数LLM推理服务都部署在Kubernetes集群中。llmtop针对这一场景进行了深度优化。

自动发现机制是核心特性之一。当在K8s环境中运行时，llmtop能够通过API Server代理自动发现推理Pod，无需手动配置端点列表或维护端口转发。这大大简化了运维复杂度，特别是在Pod动态扩缩容的场景下。

命名空间支持允许用户通过-n参数指定监控范围，适用于多租户环境或按业务线隔离的部署模式。

RBAC友好的设计理念意味着llmtop只需要读取Pod和Service的基本权限即可工作，不需要集群管理员权限，符合安全最小权限原则。

对于非K8s环境，llmtop也支持通过-e参数直接指定端点，或通过--config参数加载YAML配置文件，灵活适应各种部署拓扑。

llmtop的交互设计遵循htop的惯例，降低了学习成本。常用快捷键包括：

• s：循环切换排序列，便于按不同维度（如延迟、吞吐量、显存占用）查看
• f：循环切换后端过滤器，快速聚焦特定推理框架
• d：详情视图，查看单个节点的完整指标
• g：GPU视图，切换到硬件资源监控
• m：模型分组视图，按模型聚合展示
• r：强制刷新，立即更新数据
• e：导出JSON，便于后续分析或集成

这种键盘驱动的交互方式使得在终端中的操作流畅高效，特别适合SSH远程排查或在没有图形界面的服务器上使用。

llmtop的安装非常简便，支持多种方式：

Homebrew（macOS/Linux）：brew install InfraWhisperer/tap/llmtop

Go安装：go install github.com/InfraWhisperer/llmtop/cmd/llmtop@latest

二进制下载：从GitHub Releases页面下载对应平台的预编译二进制。

快速启动命令示例：

# Kubernetes环境 - 自动发现
llmtop

# 指定命名空间
llmtop -n inference

# 直接指定端点
llmtop -e http://10.0.0.1:8000 -e http://10.0.0.2:8000

# 快照模式导出JSON
llmtop --once --output json

llmtop采用Go语言开发，这保证了其跨平台能力和出色的性能表现。项目的架构设计充分考虑了可扩展性——新的推理后端可以通过标准化的接口接入，社区贡献者可以相对容易地添加对新框架的支持。

指标采集层通过HTTP端点轮询各推理服务的Prometheus格式指标，解析后聚合展示。对于Kubernetes环境，llmtop利用client-go库与API Server交互，动态维护端点列表。

UI层采用终端UI框架（如tview或类似库）实现，支持颜色主题、响应式布局和键盘事件处理。项目的文档中详细描述了配置格式、K8s发现机制、RBAC要求和架构设计，便于深度用户进行二次开发或集成。