vllm-bench-serve

vLLM Bench Serve

使用 vllm bench serve CLI 对 vLLM 或任何兼容 OpenAI 的服务端点进行基准测试。根据可配置的请求负载，测量吞吐量、延迟（TTFT、TPOT）和有效吞吐量。

参考：vLLM Bench Serve 文档

前置条件

• 已安装 vLLM（或正在运行任何兼容 OpenAI 的服务端）
• 已有正在提供模型服务的 vLLM 服务或 API 端点
• 用于基准测试客户端的 Python 环境，且已安装 vLLM

快速开始

对本地 vLLM 服务进行基础基准测试（默认随机数据集，1000 条提示词）：

vllm bench serve \
  --backend openai-chat \
  --host 127.0.0.1 \
  --port 8000 \
  --model Qwen/Qwen2.5-1.5B-Instruct \
  --endpoint /v1/chat/completions

将结果保存为 JSON：

vllm bench serve \
  --backend openai-chat \
  --host 127.0.0.1 \
  --port 8000 \
  --model Qwen/Qwen2.5-1.5B-Instruct \
  --endpoint /v1/chat/completions \
  --save-result \
  --result-dir ./bench-results \
  --metadata "version=0.6.0" "tp=1"

**注意：**使用 --backend openai-chat 时，必须指定 --endpoint /v1/chat/completions（默认值为 /v1/completions）。

核心参数

参数	默认值	描述
--backend	openai	后端类型：openai、openai-chat、openai-embeddings、vllm、vllm-pooling、vllm-rerank 等。
--host	127.0.0.1	服务端主机
--port	8000	服务端端口
--base-url	-	替代选项：使用完整基础 URL，而不是 host:port
--endpoint	/v1/completions	API 端点；对于 openai-chat，请使用 /v1/chat/completions
--model	（来自 /v1/models）	模型名称
--num-prompts	1000	要处理的提示词数量
--request-rate	inf	每秒请求数；inf = 一次性突发发送全部请求
--max-concurrency	-	最大并发请求数（限制并行度）
--num-warmups	0	测量前的预热请求数

数据集

--dataset-name	用途
random	合成随机提示词（默认）
sharegpt	ShareGPT 对话格式；需要 --dataset-path
sonnet	Sonnet 风格的提示词
hf	HuggingFace 数据集；需要 --dataset-path（数据集 ID）
custom / custom_mm	自定义数据集；需要 --dataset-path
prefix_repetition	前缀重复基准测试
random-mm	随机多模态数据（图像/视频）
spec_bench	Spec 基准测试数据集

数据集专用选项（示例）：

# Random: control input/output length
--dataset-name random --random-input-len 1024 --random-output-len 128

# Sonnet defaults: input 550, output 150, prefix 200
--dataset-name sonnet --sonnet-input-len 550 --sonnet-output-len 150

# HuggingFace dataset
--dataset-name hf --dataset-path "lmarena-ai/VisionArena-Chat" --hf-split test

# General overrides (map to dataset-specific args)
--input-len 512 --output-len 256

负载控制

# Fixed request rate (Poisson process)
--request-rate 10

# More bursty arrivals (gamma distribution, burstiness < 1)
--request-rate 10 --burstiness 0.5

# Ramp-up from low to high RPS
--ramp-up-strategy linear --ramp-up-start-rps 1 --ramp-up-end-rps 50

# Limit concurrency (useful for rate-limited APIs)
--max-concurrency 32

结果与指标

参数	描述
--save-result	将基准测试结果保存为 JSON
--save-detailed	在 JSON 中包含每个请求的 TTFT、TPOT 和错误
--append-result	追加到现有结果文件
--result-dir	结果文件目录
--result-filename	自定义文件名（默认：{label}-{request_rate}qps-{model}-{timestamp}.json）
--percentile-metrics	计算百分位数的指标：ttft、tpot、itl、e2el（默认：ttft,tpot,itl）
--metric-percentiles	百分位数值，例如 25,50,99（默认：99）
--goodput	有效吞吐量的 SLO：ttft:500 tpot:50（毫秒）

采样参数（兼容 OpenAI 的后端）

--temperature 0.7 --top-p 0.95 --top-k 50
--frequency-penalty 0 --presence-penalty 0 --repetition-penalty 1.0

常见工作流

1. 使用随机数据集进行吞吐量测试（突发）：

vllm bench serve --backend openai-chat --host 127.0.0.1 --port 8000 \
  --model Qwen/Qwen2.5-1.5B-Instruct \
  --endpoint /v1/chat/completions \
  --dataset-name random \
  --num-prompts 500 --random-input-len 512 --random-output-len 128

2. 使用固定 QPS 进行延迟测试：

vllm bench serve --backend openai-chat --host 127.0.0.1 --port 8000 \
  --model Qwen/Qwen2.5-1.5B-Instruct \
  --endpoint /v1/chat/completions \
  --request-rate 5 --num-prompts 200 \
  --save-result --percentile-metrics ttft,tpot --metric-percentiles 50,99

3. 对远程 API 进行基准测试（base-url）：

vllm bench serve --backend openai-chat \
  --base-url "https://api.example.com/v1" \
  --model my-model \
  --header "Authorization=Bearer $API_KEY"

4. 在 Docker 中运行（当主机上没有 vLLM 客户端时）：

docker exec <container-name> vllm bench serve \
  --backend openai-chat --host 127.0.0.1 --port 8000 \
  --model Qwen/Qwen2.5-1.5B-Instruct \
  --endpoint /v1/chat/completions \
  --dataset-name random --num-prompts 100

故障排除

• 连接被拒绝：确保服务正在运行，并且 --host/--port 或 --base-url 正确。
• 找不到模型：显式传入 --model，或确保 /v1/models 返回该模型。
• URL 必须以 chat/completions 结尾：当 --backend openai-chat 时，请使用 --endpoint /v1/chat/completions。
• 速率限制 / 429：降低 --request-rate 或 --max-concurrency。
• 就绪检查：使用 --ready-check-timeout-sec 60 在基准测试前等待端点就绪。
• SSL：对于自签名证书，请使用 --insecure。

备注

• 对于嵌入／重排基准测试，请使用 --backend openai-embeddings、vllm-pooling 或 vllm-rerank。
• 在服务器上进行 vLLM 性能分析时，--profile 需要配合 --profiler-config 使用。
• Goodput SLO 适用于 SLA 风格的分析；详情请参阅 DistServe 论文。