ClawdBot监控实践：Prometheus+Grafana监控vLLM GPU利用率与QPS

ClawdBot监控实践：Prometheus+Grafana监控vLLM GPU利用率与QPS

1. ClawdBot是什么：你的本地AI助手中枢

ClawdBot不是另一个云端API调用工具，而是一个真正能装进你笔记本、工作站甚至家用NAS的个人AI助手运行时环境。它不依赖外部服务，所有推理、记忆、工具调用都在你自己的设备上完成。你可以把它理解成“AI时代的本地Shell”——输入自然语言指令，它自动调度模型、调用插件、读写文件、执行代码，最后把结果清晰呈现给你。

它的核心后端由vLLM驱动，这意味着你获得的不只是一个能聊天的界面，而是一个具备工业级吞吐能力的本地大模型服务引擎。当你在ClawdBot UI里点击发送、上传图片或发起语音转写时，背后是vLLM在毫秒级完成KV缓存管理、PagedAttention调度和连续批处理。这种设计让4B级别模型在单张3090/4090上轻松支撑5–8路并发请求，而不是卡在排队等待中。

更关键的是，ClawdBot把vLLM从“需要写脚本启动的服务”变成了“开箱即用的组件”。你不需要手动配置--tensor-parallel-size、--gpu-memory-utilization或--enable-chunked-prefill——这些参数已内建为可选策略，并通过JSON配置文件和Web UI双通道暴露。模型切换只需改一行ID，服务重启由系统自动触发，连日志轮转和错误重试都已预置妥当。

这正是监控的起点：当AI能力下沉到本地，可观测性就不再是运维团队的附加项，而是每个使用者保障体验、排查问题、优化资源的必备技能。

2. 为什么必须监控vLLM：GPU不是黑盒，QPS不是数字

很多人部署完ClawdBot后只做两件事：测试能否对话、检查响应速度。但真实使用中，你会遇到这些无声的问题：

• 某天下午模型突然变慢，但UI没报错，clawdbot models list仍显示在线；
• 连续提问10次后，第11次开始超时，重启服务又恢复正常；
• 同一型号显卡（如RTX 4090），在A机器上跑Qwen3-4B稳定6.2 QPS，在B机器上只有3.8 QPS，差异原因不明；
• 多个子代理（subagents）并发调用时，GPU显存占用飙升至98%，但vLLM日志里没有OOM提示。

这些问题的根源，往往藏在GPU利用率、显存分配、请求队列长度、token生成速率这些底层指标里。而ClawdBot本身不提供实时性能仪表盘——它专注业务逻辑，监控则需你主动构建。

vLLM自带Prometheus指标端点（默认http://localhost:8000/metrics），但原始指标对普通用户极不友好：vllm:gpu_cache_usage_ratio是0.73还是0.92？vllm:request_waiting_count是2还是17？这些数字本身不说话，需要放在时间轴上对比、叠加、关联才能形成判断依据。

这就是Prometheus+Grafana组合的价值：把离散的指标变成会呼吸的图表，让“GPU是否吃饱”、“请求是否积压”、“模型是否健康”一目了然。

3. 零配置接入Prometheus：三步暴露vLLM指标

ClawdBot的vLLM服务默认已启用指标导出，无需修改源码或重新编译。你只需确认三点：

3.1 确认vLLM服务已开启metrics端点

检查ClawdBot启动日志或配置文件，确保vLLM是以如下方式启动的（ClawdBot v2026.1+版本默认启用）：

# 实际启动命令类似（由ClawdBot内部调用） python -m vllm.entrypoints.api_server \ --model /models/Qwen3-4B-Instruct-2507 \ --host 0.0.0.0 \ --port 8000 \ --tensor-parallel-size 1 \ --gpu-memory-utilization 0.9 \ --enable-metrics # ← 关键：启用指标导出

验证方式：直接访问http://localhost:8000/metrics，应返回纯文本格式的Prometheus指标，包含vllm:gpu_cache_usage_ratio、vllm:request_success_count等前缀的指标。

注意：如果返回404，请检查ClawdBot版本是否≥2026.1；旧版本需手动在clawdbot.json中添加vLLM启动参数。

3.2 配置Prometheus抓取目标

在Prometheus配置文件prometheus.yml的scrape_configs区域添加：

- job_name: 'vllm-clawdbot' static_configs: - targets: ['localhost:8000'] metrics_path: '/metrics' scheme: 'http' scrape_interval: 5s scrape_timeout: 3s

保存后重启Prometheus：

sudo systemctl restart prometheus # 或直接运行 ./prometheus --config.file=prometheus.yml

5秒后，进入Prometheus Web UI（默认http://localhost:9090），在“Status → Targets”页面确认vllm-clawdbot状态为UP。

3.3 验证核心指标可用性

在Prometheus表达式浏览器中输入以下查询，确认数据流正常：

• vllm:gpu_cache_usage_ratio→ 查看GPU KV缓存占用率（理想值0.6–0.85）
• vllm:request_waiting_count→ 当前排队等待处理的请求数（持续>5需警惕）
• rate(vllm:request_success_count[1m])→ 每分钟成功请求数（即QPS）
• vllm:gpu_used_bytes→ 已用GPU显存字节数（配合machine_memory_bytes看占比）

若以上查询返回非空时间序列，则指标链路已打通。

4. Grafana可视化实战：一张图看清GPU与QPS关系

Prometheus提供数据，Grafana负责讲故事。我们构建一个聚焦“资源-性能”关系的看板，核心逻辑是：GPU不是越忙越好，QPS不是越高越稳。

4.1 创建Grafana数据源

1. 登录Grafana（默认http://localhost:3000，初始账号admin/admin）
2. “Configuration → Data Sources → Add data source”
3. 选择“Prometheus”，填入URL：http://localhost:9090
4. 点击“Save & test”，确认连接成功

4.2 构建核心面板：GPU利用率与QPS联动视图

新建Dashboard，添加第一个Panel，配置如下：

标题：GPU负载 vs 请求吞吐（实时联动）
可视化类型：Time series（时间序列图）
查询A（左Y轴）：

100 * avg by (instance) (vllm:gpu_cache_usage_ratio)

→ 显示GPU缓存占用百分比（反映计算单元繁忙度）

查询B（右Y轴）：

rate(vllm:request_success_count[1m])

→ 显示每分钟成功请求数（即QPS）

关键设置：

• Y轴A：Range为0–100，Label设为“GPU Cache %”
• Y轴B：Range自动，Label设为“QPS”
• 图表选项 → “Draw mode”选“Line”，“Fill opacity”设为20
• 启用“Legend”并自定义显示为“GPU Usage”和“QPS”

此面板揭示关键规律：当GPU缓存占用率持续高于90%时，QPS曲线常出现平台期甚至下降——说明模型已逼近显存瓶颈，继续加压只会增加排队，而非提升吞吐。

4.3 补充诊断面板：请求队列与延迟分布

添加第二个Panel，类型选“Stat”（单值统计）：

标题：当前排队请求数
查询：

max(vllm:request_waiting_count)

显示设置：

• Value options → Stat选“Current”，Color mode选“Background”
• Thresholds：0→green, 3→yellow, 6→red
  → 一眼识别是否出现请求积压

添加第三个Panel，类型选“Histogram”（直方图）：

标题：请求处理延迟分布（P50/P90/P99）
查询：

histogram_quantile(0.5, sum by (le) (rate(vllm:request_time_seconds_bucket[5m]))) histogram_quantile(0.9, sum by (le) (rate(vllm:request_time_seconds_bucket[5m]))) histogram_quantile(0.99, sum by (le) (rate(vllm:request_time_seconds_bucket[5m])))

→ 直观看到50%请求在多少秒内完成，99%请求的最差情况

5. 实战问题定位：从图表到根因的三步法

监控不是摆设，而是故障排查的导航仪。以下是三个典型场景的定位路径：

5.1 场景一：QPS骤降50%，但GPU占用率仅60%

现象：看板中QPS曲线突然腰斩，GPU Usage却未飙升
排查路径：

1. 查看vllm:request_failed_count是否上升 → 若是，检查失败原因标签reason="invalid_prompt"或"context_length_exceeded"
2. 查看vllm:prompt_tokens_total与vllm:generation_tokens_total比值 → 若提示词token远超生成token，说明用户在提交超长文档，触发vLLM的max_model_len限制
3. 检查ClawdBot日志：grep "max_model_len" ~/.clawdbot/logs/gateway.log→ 确认是否因截断导致响应异常

解决：在clawdbot.json中为该模型增加max_tokens限制，或在UI中调整“Max Context Length”滑块。

5.2 场景二：GPU显存占用100%，但QPS为0

现象：vllm:gpu_used_bytes达峰值，vllm:request_waiting_count为0，无新请求被处理
排查路径：

1. 查看vllm:gpu_cache_usage_ratio→ 若接近1.0，说明KV缓存占满，但无新请求进入（可能客户端断连）
2. 执行nvidia-smi→ 观察Volatile GPU-Util是否为0 → 若是，GPU空闲但显存未释放，属vLLM内存泄漏
3. 检查vllm:cache_num_blocks_used与vllm:cache_num_blocks_total→ 若前者=后者且长期不变，确认缓存未回收

解决：升级vLLM至0.6.3+（修复了部分场景下block未释放问题），或临时重启ClawdBot服务。

5.3 场景三：QPS稳定，但用户反馈“有时卡顿”

现象：QPS曲线平滑，GPU Usage波动正常，但个别请求耗时超10秒
排查路径：

1. 在直方图面板中拖动时间范围至“过去1小时”，观察P99延迟是否突增
2. 查询rate(vllm:request_time_seconds_sum[1m]) / rate(vllm:request_success_count[1m])→ 计算平均延迟
3. 对比vllm:request_time_seconds_sum与vllm:prompt_tokens_total→ 若单位token耗时陡增，说明模型在处理特定提示时陷入低效计算（如重复解码）

解决：启用vLLM的--enable-chunked-prefill参数（已在ClawdBot 2026.1+配置模板中预置），提升长上下文首token生成效率。

6. 总结：让本地AI运行得明白、调得安心

ClawdBot把前沿的vLLM能力封装成人人可用的本地助手，但这不意味着我们可以放弃对底层资源的掌控。GPU利用率不是越高越好，QPS数字不是越大越强——真正的稳定性，来自对“请求如何排队、显存如何分配、token如何生成”的透彻理解。

本文带你走通了从vLLM指标暴露、Prometheus抓取、Grafana可视化到问题定位的完整闭环。你不需要成为SRE专家，只需记住三个黄金指标：

• vllm:request_waiting_count > 5→ 检查客户端或网络
• vllm:gpu_cache_usage_ratio > 0.92→ 检查模型配置或显存泄漏
• rate(vllm:request_time_seconds_sum[1m]) / rate(vllm:request_success_count[1m]) > 3s→ 检查提示词质量或模型参数

监控不是给系统加锁，而是给使用者发钥匙。当你能随时看清GPU的呼吸节奏、QPS的脉搏跳动，ClawdBot才真正从“能用”走向“好用”，从“玩具”变成“生产力伙伴”。

获取更多AI镜像

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