llm-grill：大语言模型推理服务器的综合基准测试工具

llm-grill是一个命令行工具，用于对vLLM、SGLang、llama.cpp和LiteLLM等LLM推理服务器进行全面基准测试，支持多轮对话场景和负载渐变测试。

传统的API性能测试工具（如Apache Bench、wrk）虽然可以测量请求延迟和吞吐量，但它们无法捕捉LLM推理的独特特性。大语言模型的推理过程涉及：

• 流式生成：token逐个返回，需要测量首token时间（TTFT）和每个token的生成时间（TPOT）
• 上下文依赖：多轮对话中，KV缓存的命中与否会显著影响性能
• 资源密集型：GPU显存、KV缓存利用率直接影响服务能力
• 负载敏感：并发请求的增加可能导致非线性性能下降

llm-grill专门针对这些特性设计，提供了传统工具无法提供的深度洞察。

llm-grill支持当前主流的LLM推理服务器：

后端	类型	指标来源	特殊功能
vLLM	vllm	Prometheus /metrics	KV缓存利用率监控
SGLang	sglang	Prometheus /metrics	缓存命中率
llama.cpp	llamacpp	/health端点	GGUF模型支持
LiteLLM	litellm	网关路由	多后端代理
OpenAI兼容	openai	—	复用vLLM客户端

工具测量的核心指标包括：

延迟指标：

• TTFT（Time to First Token）：从发送请求到接收到第一个token的时间（客户端测量，包含网络延迟）
• TPOT（Time Per Output Token）：(端到端延迟 - TTFT) / (生成token数 - 1)
• 端到端延迟：从请求发送到接收最后一个token的总时间

吞吐量指标：

• tokens/s：生成token数 / 端到端延迟
• 成功率：无错误完成的请求百分比

对话质量指标（多轮对话场景）：

• 轮次间比率：平均(第n轮TTFT) / 平均(第0轮TTFT)，小于1表示KV缓存减少了预填充时间
• 上下文增长因子：平均(最后一轮端到端延迟) / 平均(第一轮端到端延迟)，大于1表示延迟随上下文增加
• KV缓存命中率：从缓存服务的提示token比例（仅SGLang）
• KV缓存利用率：GPU KV缓存容量使用比例（仅vLLM）

llm-grill使用YAML文件定义测试场景，支持高度灵活的配置：

name: my-scenario
description: 可选描述

backends:
  - name: gpu-vllm
    url: http://gpu-vllm:8000
    api_key: none
    type: vllm
    timeout: 120.0

models:
  - name: devstral-small-2-24b
    max_tokens: 512
    temperature: 0.0

conversations:
  - name: multi-turn-debug
    turns:
      - role: system
        content: "You are an expert developer."
      - role: user
        content: "My FastAPI app returns 500 errors under load. What should I check?"
      - role: user
        content: "The DB connection pool is exhausted. How do I configure it in SQLAlchemy?"

targets:
  - backend: gpu-vllm
    model: devstral-small-2-24b
    conversation: multi-turn-debug

load:
  concurrent_users: 10
  iterations: 3
  ramp_up_seconds: 5.0
  think_time_seconds: 0.0

每个role: user的turn会触发一个推理请求。对话历史（包括助手回复）会被传递，因此服务器看到的是不断增长的上下文。

通过添加ramp_levels配置，可以在单次运行中扫描多个并发级别：

load:
  iterations: 3
  ramp_levels: [1, 5, 10, 20, 50, 100]
  ramp_pause_seconds: 10.0
  think_time_seconds: 0.0

结果会标记concurrent_users_level，并在负载渐变结果表格中按(server, model, users)排序显示，帮助识别系统的性能拐点。

llm-grill需要Python 3.11+和uv包管理器：

uv tool install llm-grill

验证安装：

llm-grill --version

1. 检查连通性

llm-grill ping scenarios/my-bench.yaml

2. 运行基准测试

llm-grill run scenarios/my-bench.yaml --output results.jsonl

运行后自动打印：

• 基准测试摘要——每个服务器/模型的延迟、吞吐量、成功率
• 对话质量指标——KV缓存命中率、轮次间延迟比率、上下文增长因子
• 负载渐变结果——（如果设置了ramp_levels）每个并发级别的结果

3. 从已有结果生成报告

# 终端表格（摘要+对话指标）
llm-grill report results.jsonl

# JSON格式（可管道传输）
llm-grill report results.jsonl --format json

# CSV格式（原始请求，适合pandas分析）
llm-grill report results.jsonl --format csv --output summary.csv

llm-grill支持通过SSH收集GPU指标（利用率、显存、温度、功耗）：

backends:
  - name: gpu-vllm
    url: http://gpu-vllm:8000
    type: vllm
    gpu_monitoring: true
    ssh_host: gpu-vllm
    ssh_user: root

这需要在目标主机上安装nvidia-smi并配置SSH密钥访问。