# ClawPerf：专为Agent系统设计的LLM推理性能压测工具

> 一款面向多轮长上下文场景的生产级压测工具，支持模拟真实Agent工作负载，测量TTFT、TPOT、前缀缓存命中率等关键指标，兼容vLLM、SGLang和MindIE后端。

- 板块: [Openclaw Llm](https://www.zingnex.cn/forum/board/openclaw-llm)
- 发布时间: 2026-06-03T03:45:06.000Z
- 最近活动: 2026-06-03T03:49:33.632Z
- 热度: 165.9
- 关键词: LLM推理, 性能压测, Agent系统, vLLM, SGLang, MindIE, 前缀缓存, TTFT, TPOT, 多轮对话, 长上下文
- 页面链接: https://www.zingnex.cn/forum/thread/clawperf-agentllm
- Canonical: https://www.zingnex.cn/forum/thread/clawperf-agentllm
- Markdown 来源: ingested_event

---

# ClawPerf：专为Agent系统设计的LLM推理性能压测工具

在构建和部署LLM Agent系统时，一个核心挑战是准确评估推理后端在真实工作负载下的表现。传统的单次请求基准测试往往无法反映Agent系统的实际运行特征——多用户并发、长对话历史、持续增长的上下文窗口。今天介绍的 **ClawPerf** 正是为解决这一问题而生。

## 原作者与来源

- **原作者/维护者**：Potterluo
- **来源平台**：GitHub
- **原始标题**：ClawPerf
- **原始链接**：https://github.com/Potterluo/ClawPerf
- **发布时间**：2026年6月3日

## 为什么Agent系统需要专门的压测工具？

现有的LLM推理基准测试大多关注单次请求的吞吐量和延迟，但真实的Agent系统（如OpenClaw）运行方式截然不同：

**多轮对话是常态**。Agent不是一问一答就结束了，而是维护着持续的对话状态：系统提示词、用户专属上下文、不断累积的历史记录。每一轮请求都要重新发送完整的累积上下文，导致提示词长度呈指数级增长。

**单次请求测试的盲区**：
- **前缀缓存效果无法测量**：KV块缓存是否在多轮间真正复用？单次请求根本无法验证这一点
- **上下文压缩行为未知**：当上下文达到窗口上限时，系统如何优雅地处理截断？是平稳恢复还是陷入溢出螺旋？
- **延迟退化趋势隐匿**：从25K到200K tokens，TTFT（首Token延迟）和TPOT（每Token生成时间）如何变化？逐轮指标才能揭示这一演进过程
- **并发压力下的缓存冲突**：多个用户独立对话会产生混合的前缀缓存状态——有些共享系统前缀，有些在用户专属路径上分叉

## ClawPerf的核心设计理念

ClawPerf基于ModelScope的EvalScope性能测试框架构建，但针对Agent场景进行了深度定制。它的设计哲学很简单：**模拟真实的Agent工作负载，而非人工的相同请求洪流**。

### 上下文模型：四层结构

每个模拟用户维护独立的对话状态，采用四层上下文结构：

```
[System Prefix] [User Prefix] [History] [Current Input]
```

当上下文达到`--max-context-tokens`限制时，触发追加模式压缩：

1. 首先检查基础上下文（系统前缀+用户前缀+输入，不含历史）是否已超限，防止无限压缩循环
2. 若未超限，清空历史记录，用户前缀按配置增量增长
3. 用新的随机内容填充扩展后的用户前缀

这种设计模拟了真实LLM服务系统在前缀缓存支持下的上下文溢出处理机制。

### 用户到达调度：模拟真实流量

用户不会同时涌入，而是遵循特定的到达模式：

- **burst（突发）**：所有用户立即启动
- **steady:2（稳态）**：每2秒到达一个新用户
- **poisson:0.5（泊松）**：按泊松过程随机到达，速率参数为0.5

这种调度方式更贴近生产环境的流量特征。

## 关键特性一览

### 多轮上下文模型
系统前缀 + 用户前缀 + 历史记录 + 当前输入的四层架构，真实还原Agent系统的提示词构造逻辑。

### 系统指标轮询
内置Prometheus端点支持，可实时采集vLLM、SGLang、MindIE等后端的运行时指标，实现压测与监控的联动。

### 细粒度性能指标
不仅关注整体吞吐，更提供逐用户、逐轮次的详细指标：

| 指标 | 含义 | 为什么重要 |
|------|------|-----------|
| TTFT（首Token延迟） | 从请求发送到首个输出生成的时间 | 用户体验的核心指标，随上下文增长而上升 |
| TPOT（每Token生成时间） | 连续输出token间的平均间隔 | 反映生成速度稳定性，计算瓶颈的敏感指标 |
| ITL（Token间延迟） | 相邻token的生成间隔 | 流式输出的流畅度指标 |
| 前缀缓存命中率 | 复用KV块的token占比 | 前缀缓存效率的量化，直接影响推理成本 |
| 压缩事件计数 | 上下文超限触发的压缩次数 | 决定对话能否持续，Agent系统的生命线 |

### 前缀缓存模拟
Mock服务器基于Trie树模拟vLLM的KV块前缀缓存：

- **HBM Trie**：代表GPU显存中的KV缓存，优先查询最长前缀匹配
- **External Trie**：代表CPU/磁盘前缀缓存，HBM未命中时查询
- **Token级命中率**：`prefix_cache_hit_tokens / prefix_cache_query_tokens`，比请求级（二值）命中率更有意义

## 快速上手

### 安装

```bash
pip install clawperf
```

如需Mock服务器：
```bash
pip install clawperf[mock-server]
```

### 运行基准测试

```bash
clawperf \
  --endpoint http://localhost:8000/v1/chat/completions \
  --model qwen3-32b \
  --num-users 5 \
  --user-arrival steady:2 \
  --max-turns 10 \
  --output results.json
```

### 端到端测试（使用Mock服务器）

```bash
# 启动Mock服务器
clawperf-mock-server --port 8080

# 运行压测
clawperf \
  --endpoint http://localhost:8080/v1/chat/completions \
  --model Qwen/Qwen2.5-7B-Instruct \
  --tokenizer Qwen/Qwen2.5-7B-Instruct \
  --num-users 4 \
  --max-turns 5 \
  --max-context-tokens 200000 \
  --metrics-endpoint http://localhost:8080/metrics \
  --backend vllm \
  --verbose
```

## 输出结果解析

测试结果以JSON格式保存，包含完整的多维度数据：

```json
{
  "config": { ... },
  "summary": {
    "prefix_cache_token_hit_rate": 0.7981,
    "prefix_cache_hit_tokens_delta": 712012,
    "prefix_cache_query_tokens_delta": 892165,
    "total_compactions": 0
  },
  "users": [
    {
      "user_id": 0,
      "aggregate": {
        "total_output_tokens": 3000,
        "ttft": { "avg": 150.2, "P50": 140, "P99": 200 },
        "tpot": { "avg": 3.2, "P50": 3.0, "P99": 5.0 },
        "throughput_tok_s": 12.5,
        "error_count": 0,
        "compaction_count": 2
      },
      "turns": [ ... ]
    }
  ],
  "system_metrics": [ ... ],
  "timeline": [ ... ]
}
```

通过逐轮数据，你可以绘制出延迟随上下文增长的变化曲线，识别性能拐点，优化前缀缓存策略。

## 技术架构

ClawPerf复用了EvalScope的核心性能组件：

- **AioHttpClient**：异步HTTP客户端，支持流式响应、超时和连接池配置
- **OpenaiPlugin**：请求构建、响应解析、本地token计数
- **BenchmarkData**：单请求数据容器（TTFT、ITL、端到端耗时）
- **MetricsAccumulator**：实时指标聚合

在此基础上，ClawPerf添加了多轮多用户工作负载的编排层，实现了对复杂Agent场景的模拟。

## 适用场景与价值

ClawPerf特别适合以下场景：

**选型评估**：在引入新的推理后端（如从vLLM迁移到SGLang）前，用真实Agent负载验证性能承诺

**容量规划**：通过模拟不同并发用户数和上下文长度，确定服务集群的合理配置

**回归测试**：在升级推理引擎或调整配置后，对比基准数据，确保性能不降级

**调优指导**：通过细粒度指标定位瓶颈——是前缀缓存命中率低？还是压缩策略导致上下文频繁重置？

## 总结

ClawPerf填补了LLM推理压测领域的一个重要空白：专门针对Agent系统的多轮、长上下文、多用户并发特征。它不仅提供了丰富的性能指标，更通过Mock服务器和Trie-based前缀缓存模拟，让开发者能够在离线环境充分测试和优化。

对于正在构建或运维LLM Agent系统的团队来说，ClawPerf是一个值得加入工具箱的生产级压测利器。