ClawdBot监控实践：Prometheus+Grafana监控vLLM GPU显存与QPS指标

ClawdBot 是一个你可以在自己设备上运行的个人 AI 助手，本应用使用 vLLM 提供后端模型能力。它不是云端黑盒服务，而是一个可完全掌控、可深度定制的本地化智能中枢——从模型加载、推理调度到用户交互，所有环节都暴露在你的视野中。这种透明性，恰恰为精细化监控提供了天然基础。

而真正让 ClawdBot 具备工程级可靠性的，是它对 vLLM 的深度集成。vLLM 作为当前最主流的开源大模型推理引擎之一，不仅以 PagedAttention 技术显著提升显存利用率和吞吐量，更通过 OpenAI 兼容 API 接口，将复杂的 GPU 资源调度封装成简洁的 HTTP 请求。这意味着，我们不需要修改 ClawdBot 源码，也不需要侵入 vLLM 内部，就能通过标准可观测性工具，实时掌握它的“呼吸节奏”：GPU 显存用了多少？每秒处理多少请求？哪个模型正在吃掉最多算力？响应延迟是否开始爬升？

这正是本文要带你完成的实践：用 Prometheus 抓取 vLLM 暴露的原生指标，用 Grafana 构建专属监控看板，把原本藏在日志和命令行里的性能数据，变成一目了然的动态仪表盘。这不是理论推演，而是你在自己机器上几分钟就能跑通的真实链路。

1. 理解监控对象：vLLM 的可观测性能力

vLLM 并非一个“哑巴”服务。自 0.6.0 版本起，它内置了完整的 Prometheus 指标导出功能，无需额外插件或代理。只要启动时开启 --enable-metrics 参数，它就会在默认端口（通常是 8000）的 /metrics 路径下，以标准的 Prometheus 文本格式，持续输出数十个关键运行指标。

这些指标不是抽象的数字，而是直接映射到你最关心的业务问题：

• GPU 显存压力：vllm:gpu_cache_usage_perc 告诉你显存缓存占用百分比，这是判断是否该扩容或优化批处理大小的黄金信号；vllm:gpu_memory_used_bytes 则给出绝对数值，方便你和 nvidia-smi 的结果交叉验证。
• 服务吞吐能力：vllm:request_success_count 和 vllm:request_failure_count 是 QPS（每秒查询数）的直接来源；配合 vllm:request_duration_seconds 的直方图，你能一眼看出 95% 的请求都在多少毫秒内完成。
• 模型调度效率：vllm:num_requests_running 显示当前正在执行的请求数，vllm:num_requests_waiting 则是排队等待的请求数——两者之差，就是你的服务是否已进入瓶颈的直观体现。

更重要的是，这些指标天然携带了丰富的标签（labels）。比如 vllm:request_success_count{model="Qwen3-4B-Instruct-2507",status="2xx"}，意味着你可以按模型名称、HTTP 状态码等维度自由切片分析。当你在 ClawdBot 中同时配置了多个 vLLM 实例（如一个跑 Qwen，一个跑 Llama），这种多维监控能力就变得不可或缺。

1.1 验证 vLLM 指标端点是否就绪

在动手配置 Prometheus 之前，先确认 vLLM 已正确暴露指标。打开终端，执行以下命令：

curl http://localhost:8000/metrics | head -n 20

你应该看到类似这样的输出：

# HELP vllm:gpu_cache_usage_perc GPU cache usage percentage.
# TYPE vllm:gpu_cache_usage_perc gauge
vllm:gpu_cache_usage_perc{gpu_id="0"} 42.3
# HELP vllm:request_success_count Total number of successful requests.
# TYPE vllm:request_success_count counter
vllm:request_success_count{model="Qwen3-4B-Instruct-2507",status="2xx"} 142
# HELP vllm:request_duration_seconds Histogram of request durations.
# TYPE vllm:request_duration_seconds histogram
vllm:request_duration_seconds_bucket{model="Qwen3-4B-Instruct-2507",le="0.1"} 120
vllm:request_duration_seconds_bucket{model="Qwen3-4B-Instruct-2507",le="0.2"} 135
...

如果返回 Connection refused，说明 vLLM 未启动或未启用 metrics。请检查你的 ClawdBot 启动命令，确保包含 --enable-metrics 参数。例如，如果你是通过 docker run 启动 vLLM 容器，命令应类似：

docker run --gpus all -p 8000:8000 \
  --env VLLM_ENABLE_METRICS=1 \
  -v /path/to/models:/models \
  ghcr.io/vllm-project/vllm:v0.6.3 \
  --model /models/Qwen3-4B-Instruct-2507 \
  --enable-metrics \
  --host 0.0.0.0 \
  --port 8000

1.2 关键指标解读：从数字到决策

理解指标含义，才能让监控真正产生价值。以下是三个最核心指标的实战解读：

• vllm:gpu_cache_usage_perc
  这不是显卡总显存占用率，而是 vLLM 自身管理的 KV Cache 占用率。当它持续高于 85%，说明你的请求批处理（batch size）可能过大，或者模型上下文（context length）过长，导致显存碎片化严重。此时，即使 nvidia-smi 显示显存还有空闲，vLLM 也可能因无法分配连续块而报错。解决方案是调小 --max-num-seqs 或启用 --block-size 16。

• vllm:request_success_count
  这是计算 QPS 的基石。Prometheus 中，我们通常用 rate(vllm:request_success_count[1m]) 函数来计算过去一分钟的平均每秒成功请求数。这个值会随 ClawdBot 用户并发量实时波动。如果它长期稳定在某个值（如 8.5），而 vllm:num_requests_waiting 却在缓慢上升，说明你的 vLLM 实例已达到吞吐极限，是时候考虑横向扩展了。

• vllm:request_duration_seconds_bucket
  这是一个直方图指标，le 标签代表“小于等于”某个阈值的请求数量。要得到 P95 延迟，你需要查询 histogram_quantile(0.95, rate(vllm:request_duration_seconds_bucket[5m]))。如果 P95 延迟从 300ms 突然跳到 1200ms，结合 vllm:gpu_cache_usage_perc 的飙升，基本可以断定是显存瓶颈触发了频繁的内存交换。

2. 搭建监控栈：Prometheus 抓取与配置

Prometheus 是一个拉取（pull）模式的监控系统，它会周期性地向目标（target）发起 HTTP 请求，获取指标数据。对于 vLLM，我们的目标就是它的 /metrics 端点。

2.1 编写 Prometheus 配置文件

创建一个名为 prometheus.yml 的配置文件。它的核心是 scrape_configs 部分，定义了 Prometheus 应该去哪抓数据、多久抓一次。

global:
  scrape_interval: 15s
  evaluation_interval: 15s

scrape_configs:
  # 抓取 vLLM 的指标
  - job_name: 'vllm'
    static_configs:
      - targets: ['host.docker.internal:8000']  # 在 Docker 容器内访问宿主机的 8000 端口
    # 如果 Prometheus 和 vLLM 运行在同一台物理机上，直接用 localhost
    # - targets: ['localhost:8000']
    metrics_path: '/metrics'
    scheme: 'http'

  # 抓取 Prometheus 自身的健康状态（可选但推荐）
  - job_name: 'prometheus'
    static_configs:
      - targets: ['localhost:9090']

这里的关键点是 targets 的地址。由于 ClawdBot 和 vLLM 很可能运行在不同的 Docker 容器中，容器间网络隔离，localhost 在 Prometheus 容器内指向的是它自己，而非宿主机。因此，我们使用 host.docker.internal 这个特殊的 DNS 名称，它是 Docker Desktop（Mac/Windows）和较新版本 Docker Engine（Linux）提供的，用于从容器内安全地访问宿主机。

2.2 启动 Prometheus 容器

有了配置文件，就可以一键启动 Prometheus。执行以下命令：

docker run -d \
  --name prometheus \
  -p 9090:9090 \
  -v $(pwd)/prometheus.yml:/etc/prometheus/prometheus.yml \
  -v $(pwd)/prometheus-data:/prometheus \
  --restart=unless-stopped \
  prom/prometheus:latest \
  --config.file=/etc/prometheus/prometheus.yml \
  --storage.tsdb.path=/prometheus \
  --web.console.libraries=/usr/share/prometheus/console_libraries \
  --web.console.templates=/usr/share/prometheus/consoles \
  --storage.tsdb.retention.time=24h

这条命令做了几件事：

• 将本地的 prometheus.yml 挂载到容器内，作为其配置；
• 创建一个名为 prometheus-data 的卷，用于持久化存储监控数据；
• 设置数据保留时间为 24 小时，避免磁盘被撑爆；
• 后台运行（-d），并设置自动重启策略。

稍等几秒钟，打开浏览器访问 http://localhost:9090，你将看到 Prometheus 的 Web UI。点击顶部菜单栏的 Status > Targets，你应该能看到 vllm 这个 job 的状态是 UP，并且 Last Scrape 时间是几秒前。这就意味着 Prometheus 已经成功连接到你的 vLLM，并开始收集数据了。

2.3 在 Prometheus UI 中验证数据

现在，让我们亲手查询一下数据。在 Prometheus UI 的搜索框中输入：

vllm:gpu_cache_usage_perc

然后点击 Execute。下方的图表区域会立刻绘制出一条曲线，显示 GPU 缓存占用率的实时变化。你可以尝试向 ClawdBot 发送几个请求（比如在它的 Web UI 里连续提问），观察这条曲线是否随之跳动。如果一切正常，恭喜你，数据采集链路已经打通。

3. 构建可视化看板：Grafana 集成与面板设计

Prometheus 是数据的“心脏”，而 Grafana 则是它的“眼睛”。Grafana 能将原始的时序数据，转化为直观、交互式的仪表盘，让你一眼洞悉系统全貌。

3.1 启动 Grafana 容器并与 Prometheus 对接

同样使用 Docker，启动 Grafana：

docker run -d \
  --name grafana \
  -p 3000:3000 \
  -v grafana-storage:/var/lib/grafana \
  --restart=unless-stopped \
  -e GF_SECURITY_ADMIN_PASSWORD=admin \
  grafana/grafana-enterprise:latest

启动后，访问 http://localhost:3000，使用用户名 admin 和密码 admin 登录（首次登录会提示你修改密码）。

登录后，第一步是添加数据源（Data Source）：

• 点击左侧边栏的齿轮图标（⚙）> Data Sources > Add data source。
• 在搜索框中输入 Prometheus，选择它。
• 在 HTTP 部分的 URL 栏中，填入 http://host.docker.internal:9090（注意，这里是 Grafana 容器访问 Prometheus 容器，所以同样要用 host.docker.internal）。
• 点击右上角的 Save & test。如果看到绿色的 “Data source is working”，说明对接成功。

3.2 创建核心监控面板

现在，我们来构建一个包含三个核心视图的仪表盘：

3.2.1 GPU 资源概览面板

这个面板要回答：“我的 GPU 现在忙不忙？”

• 点击左上角 + > Dashboard > Add new panel。
• 在查询编辑器（Query）中，输入 PromQL：

  100 - (vllm:gpu_cache_usage_perc{gpu_id="0"} or vector(0))
  

  这个表达式计算的是 GPU 缓存的剩余百分比，比直接看占用率更符合直觉（100% 剩余 = 完全空闲）。
• 在右侧的 Panel options 中，将 Visualization 设为 Gauge（仪表盘）。
• 设置 Min 为 0，Max 为 100，Unit 为 percent (0-100)。
• 给面板起个名字，比如 GPU Cache Available。

3.2.2 QPS 实时流量面板

这个面板要回答：“我的服务现在每秒处理多少请求？”

• 新建一个面板。
• 查询语句：

  sum(rate(vllm:request_success_count[1m]))
  

  这里 sum() 是为了聚合所有模型的请求，rate() 计算每秒速率。
• Visualization 设为 Stat（单值统计）。
• 在 Options 中，勾选 Show last value only，并设置 Unit 为 req/sec。
• 面板名：Current QPS。

3.2.3 请求延迟分布面板

这个面板要回答：“用户的等待时间是否在可接受范围内？”

• 新建一个面板。
• 查询语句（计算 P95 延迟）：

  histogram_quantile(0.95, sum by (le) (rate(vllm:request_duration_seconds_bucket[5m])))
  

• Visualization 设为 Time series（时间序列）。
• 在 Options > Display 中，将 Unit 设为 seconds，并勾选 Show points 以增强可读性。
• 面板名：P95 Request Latency (s)。

完成这三个面板后，点击右上角的 Save dashboard，给你的仪表盘起个名字，比如 ClawdBot vLLM Monitoring。现在，你已经有了一个能反映服务健康度的核心看板。

4. 深度实践：将监控融入 ClawdBot 日常运维

监控的价值，不在于它“能看”，而在于它能“帮你做决定”。下面是一些基于这个监控栈的真实运维场景。

4.1 场景一：识别模型性能瓶颈

假设你发现 Current QPS 面板的数值一直徘徊在 5 左右，远低于你预期的 15。此时，不要急着加机器，先看 P95 Request Latency。如果延迟也同步升高到了 2 秒以上，再去看 GPU Cache Available。如果它已经跌到了 5%，那问题就很清晰了：你的 Qwen3-4B-Instruct-2507 模型在高并发下，KV Cache 占满了显存。

解决方案很简单：回到 ClawdBot 的配置文件 clawdbot.json，找到 models.providers.vllm 部分，增加一个 --max-model-len 2048 的参数（默认是 32768），强制限制最大上下文长度。保存后重启 vLLM，你会发现 QPS 瞬间翻倍，延迟也回归到 300ms 以内。

4.2 场景二：自动化告警

Grafana 不仅能看，还能“喊”。你可以为关键指标设置告警规则。

例如，当 GPU 缓存可用率低于 10% 持续 2 分钟，就认为服务即将不可用。在 Grafana 中：

• 进入你的仪表盘，点击右上角的 Edit（铅笔图标）。
• 找到 GPU Cache Available 面板，点击右上角的 Alert > Create alert rule。
• 在 Condition 中，设置 WHEN avg() OF query(A, 2m, now) IS BELOW 10。
• 在 Notifications 中，配置一个 Slack 或邮件通知渠道。

这样，当你的 ClawdBot 服务真的遇到资源危机时，你不会等到用户投诉才发觉，而是第一时间收到预警。

4.3 场景三：效果对比与选型决策

ClawdBot 支持多种模型。如果你想评估 Qwen3-4B 和 Phi-3-mini 哪个更适合你的硬件，监控就是最客观的裁判。

• 部署两个 vLLM 实例，分别加载这两个模型。
• 在 Prometheus 配置中，为它们设置不同的 job_name（如 vllm-qwen 和 vllm-phi）。
• 在 Grafana 中，创建一个对比面板，查询：

  sum by (job) (rate(vllm:request_success_count[1m]))
  

  这条查询会自动按 job 标签分组，画出两条线。运行一段时间后，你就能清晰地看到，在相同硬件和负载下，哪个模型的吞吐量更高、延迟更低。

5. 总结：让 AI 服务从“能用”走向“可控”

ClawdBot + vLLM 的组合，赋予了你一个强大且私密的个人 AI 助手。但真正的工程成熟度，不在于它能生成多么惊艳的文本，而在于你能否像驾驶一辆汽车一样，随时掌握它的“油量”（GPU 显存）、“转速”（QPS）和“水温”（延迟）。

本文所介绍的 Prometheus + Grafana 监控方案，其价值远不止于“看图说话”。它是一套可复用的方法论：

• 标准化：利用 vLLM 原生的 Prometheus 指标，避免了任何侵入式改造；
• 可扩展：同样的配置逻辑，可以轻松接入其他支持 Prometheus 的组件，比如你的 Nginx 反向代理、PostgreSQL 数据库，甚至 ClawdBot 自身的进程状态；
• 可行动：每一个指标背后，都对应着一个明确的运维动作。从调整参数到扩容实例，决策依据不再是猜测，而是确凿的数据。

当你下次在 clawdbot dashboard 中看到那个熟悉的 Web UI 时，不妨也打开 http://localhost:3000，看看你的 AI 助手此刻的“生命体征”。这才是掌控技术的真正开始。

---

获取更多AI镜像

想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。