vLLM Bench Serve 参数详解

vllm bench serve参数详解 这是 vLLM 的端到端服务压测工具模拟真实用户通过 HTTP 请求调用服务测的是包含网络/调度/并发在内的真实用户体验。和别的命令的区别bench latency/throughput→ 实验室测引擎性能无网络开销bench serve→模拟真实用户压测含网络/调度/并发最接近生产环境serve→ 真正上线跑服务处理真实请求 参数分类速览 基础连接--host / --port / --base-url / --endpoint / --backend 数据集--dataset-name / --dataset-path / --num-prompts / --random-input-len 请求控制--request-rate / --burstiness / --max-concurrency 模型配置--model / --tokenizer / --tokenizer-mode 结果输出--save-result / --result-dir / --percentile-metrics / --goodput 可视化--plot-timeline / --plot-dataset-stats 高级采样--temperature / --top-p / --logprobs / --ignore-eos 一、基础连接参数 核心参数表参数默认值解释典型取值--host127.0.0.1vLLM 服务监听的主机地址192.168.1.100内网/0.0.0.0所有网卡--port8000vLLM 服务监听的端口8000默认/8080避免冲突--base-url-完整的 API 基础 URL覆盖 hostport--base-url https://api.example.com/v1--endpoint/v1/completions要测试的 API 端点/v1/chat/completions聊天//v1/completions补全--backendopenai后端协议类型openai标准/vllm原生/openai-chat聊天格式--header-自定义请求头格式keyvalue--header AuthorizationBearer sk-xxx--insecureFalse禁用 SSL 证书验证用于自签名证书--insecure测试环境用 场景示例 1压测本地开发服务业务场景刚用vllm serve启动了本地服务想快速测一下响应速度# 直接复制运行vllm bench serve\--host127.0.0.1\--port8000\--endpoint/v1/chat/completions\--backendopenai-chat\--modelmeta-llama/Llama-3-8b\--num-prompts50\# 先发 50 个请求试试--request-rate2# 每秒发 2 个请求别把服务打挂你会看到✅ 连接服务成功... 发送 50 个请求... 接收响应... 压测结果 总请求数: 50 成功数: 50 | 失败数: 0 总耗时: 28.5 秒 平均吞吐量: 1.75 请求/秒 平均首字延迟 (TTFT): 420 ms ← 用户等多久看到第一个字 平均每字延迟 (TPOT): 45 ms ← 生成每个字等多久 平均端到端延迟: 2.1 秒 ← 完整回复等多久 决策如果 TTFT 1 秒用户会觉得反应慢需要优化模型或加缓存。 场景示例 2压测生产环境服务带认证业务场景服务已上线带 API Key 认证 HTTPS要定期做性能巡检vllm bench serve\--base-url https://api.your-company.com/v1\--endpoint/v1/chat/completions\--backendopenai-chat\--modelmeta-llama/Llama-3-8b\--headerAuthorizationBearer sk-prod-abc123\--insecure\# ⚠️ 仅测试环境生产请用正规证书--num-prompts200\--request-rate10\# 模拟 10 QPS 的正常流量--save-result\# ✅ 保存结果做趋势对比--result-dir ./benchmarks\--labelweekly-check-2026W10结果文件./benchmarks/weekly-check-2026W10.json{label:weekly-check-2026W10,total_requests:200,success_rate:1.0,throughput:9.8,metrics:{ttft:{median:385,p99:820},tpot:{median:42,p99:95},e2el:{median:1950,p99:4200}}}趋势分析每周跑一次对比p99延迟是否上涨提前发现性能退化。 二、数据集参数让压测更真实 参数表参数默认值解释典型取值--dataset-namerandom用哪种数据生成请求random随机/sharegpt真实对话/sonnet诗歌/burstgpt突发负载--dataset-path-自定义数据集文件路径./data/my_prompts.json--num-prompts1000总共发送多少个请求100快速测试/1000标准/5000压力--random-input-len1024random 数据集的输入长度100短问/512段落/2000长文--random-output-len128random 数据集的输出长度50简答/200详解/512长文--random-range-ratio0.0输入/输出长度的波动比例0.3±30% 波动更真实--disable-shuffleFalse是否保持数据原始顺序--disable-shuffle复现特定顺序 场景示例用真实对话数据压测业务场景不想用随机数据想用真实的用户提问来测服务承载能力# 1️⃣ 准备 ShareGPT 格式数据示例# data/sharegpt_sample.json[{conversations:[{value:怎么重置密码},{value:请点击设置-安全-重置密码...}]},{conversations:[{value:订单多久能到},{value:通常 1-3 个工作日...}]}]# 2️⃣ 用真实数据压测vllm bench serve\--host127.0.0.1\--port8000\--dataset-name sharegpt\--dataset-path ./data/sharegpt_sample.json\--num-prompts200\--request-rate5\--save-result\--labelreal-user-simulation记忆口诀random→ 快速摸底控制变量sharegpt→ 真实场景发现瓶颈sonnet→ 长文本生成测显存压力⚡burstgpt→ 模拟突发流量测弹性⚡ 三、请求速率控制参数模拟真实流量 参数表参数默认值解释典型取值--request-rateinf每秒发送多少个请求RPS2低负载/10正常/50高压/inf瞬间打满--burstiness1.0请求到达的突发程度0.3扎堆突发/1.0自然随机/2.0均匀稳定--max-concurrency-最大同时进行的请求数限流50防服务过载/200高并发测试 场景示例 1模拟早高峰突发流量业务场景早上 9 点用户集中登录请求突然暴涨服务能不能扛住vllm bench serve\--host127.0.0.1\--port8000\--dataset-name sharegpt\--num-prompts500\--request-rate30\# ✅ 模拟 30 QPS 高峰--burstiness0.3\# ✅ 请求扎堆到达更真实--max-concurrency100\# ✅ 最多 100 个并发防服务崩溃--save-result\--labelmorning-rush-test关键指标解读指标健康值危险值含义success_rate≥ 99% 95%请求成功率低了说明服务扛不住p99_ttft 800ms 2000ms99% 用户的首字延迟影响响应快慢感知p99_e2el 5s 15s99% 用户的完整等待时间影响耐心决策如果p99_ttft 2s考虑加缓存、优化模型、或扩容实例。 场景示例 2找服务的最大承载量业务场景想知道服务最多能扛多少并发为扩容提供依据#!/bin/bash# find_max_capacity.shHOST127.0.0.1PORT8000MODELmeta-llama/Llama-3-8becho 开始寻找最大承载量...forRATEin510204080;doecho 测试 request-rate$RATEQPS...vllm bench serve\--host$HOST\--port$PORT\--model$MODEL\--dataset-name random\--random-input-len100\--random-output-len150\--num-prompts200\--request-rate$RATE\--max-concurrency200\--save-result\--result-dir ./capacity_test\--labelrate_${RATE}\--disable-log-stats# 提取关键指标result$(python3-cimportjson datajson.load(open(./capacity_test/rate_${RATE}.json))print(f\{data[success_rate]*100:.1f}%,{data[metrics][ttft][p99]:.0f}ms\)) echo → 成功率:${result%%,*}%|P99首字延迟:${result#*,}echodone预期输出 开始寻找最大承载量... 测试 request-rate5 QPS... → 成功率: 100.0% | P99首字延迟: 320ms 测试 request-rate20 QPS... → 成功率: 99.5% | P99首字延迟: 580ms 测试 request-rate40 QPS... → 成功率: 96.2% | P99首字延迟: 1450ms ← ⚠️ 开始下降 测试 request-rate80 QPS... → 成功率: 78.3% | P99首字延迟: 3200ms ← ❌ 服务过载 ✅ 结论建议生产环境控制在 30 QPS 以内 四、结果输出参数保存分析可视化 参数表参数默认值一句话解释使用场景--save-resultFalse是否保存结果为 JSON 文件✅ 必开方便对比和归档--save-detailedFalse是否保存每个请求的详细数据调试时用文件会很大--result-dir当前目录结果文件保存目录--result-dir ./benchmarks--label-结果标签用于文件名/图表--label llama3-awq-v1--append-resultFalse追加结果到现有文件而非覆盖多次测试合并分析--percentile-metricsttft,tpot,itl要计算百分位的指标--percentile-metrics ttft,e2el--metric-percentiles99要报告的百分位数--metric-percentiles 50,90,99--goodput-设置服务等级目标SLO计算达标请求比例--goodput ttft:500 e2el:5000 场景示例生成带百分位的详细报告业务场景老板问99% 的用户体验如何你需要 P50/P90/P99 数据vllm bench serve\--host127.0.0.1\--port8000\--modelmeta-llama/Llama-3-8b\--dataset-name sharegpt\--num-prompts500\--request-rate10\--save-result\--result-dir ./reports\--labelq2-performance-review\--percentile-metrics ttft,e2el\# ✅ 重点关注首字延迟和端到端延迟--metric-percentiles50,90,99\# ✅ 报告三个关键百分位--goodputttft:500 e2el:5000# ✅ 定义好体验标准结果解读JSON 片段{label:q2-performance-review,goodput:{ttft:500:0.87,# ✅87%的请求首字延迟500mse2el:5000:0.94# ✅94%的请求完整延迟5秒},percentile_metrics:{ttft_ms:{50:320,90:580,99:1120},e2el_ms:{50:1850,90:3200,99:6800}}}决策建议goodput 90%→ ✅ 体验优秀可上线goodput 70~90%→ ⚠️ 可接受但建议优化goodput 70%→ ❌ 体验差必须优化后再上线 五、可视化参数 参数表参数默认值解释输出效果--plot-timelineFalse生成 HTML 时间线图展示每个请求的执行过程直观看到请求排队/执行/完成的时间线--timeline-itl-thresholds25.0,50.0时间线图中 token 间隔的颜色阈值毫秒红色慢绿色快一眼定位瓶颈--plot-dataset-statsFalse生成数据集统计图prompt/output token 分布确认测试数据是否符合预期--disable-tqdmFalse禁用进度条显示自动化脚本中用避免日志混乱 场景示例生成时间线图定位性能瓶颈业务场景压测发现偶尔有请求特别慢想看看到底卡在哪一步vllm bench serve\--host127.0.0.1\--port8000\--modelmeta-llama/Llama-3-8b\--dataset-name random\--num-prompts100\--request-rate5\--plot-timeline\# ✅ 生成时间线图--timeline-itl-thresholds30,80\# ✅ 30ms 绿色30~80ms 黄色80ms 红色--save-result\--result-dir ./debug_timeline打开生成的 HTML 文件./debug_timeline/timeline.html┌─────────────────────────────────────────────┐ │ 请求#42 (慢!) │ │ [] │ │ ↑ ↑ ↑ ↑ │ │ 发送 首字 token间隔变慢(红色) 完成 │ │ │ │ 请求#43 (正常) │ │ [] │ └─────────────────────────────────────────────┘分析技巧如果大量请求开头就 → 网络或调度瓶颈如果中间集中 → 模型生成阶段瓶颈考虑量化/多卡如果结尾 → 响应传输或客户端处理瓶颈⚙️ 六、高级采样参数控制生成质量 参数表参数默认值解释典型取值--temperature-采样温度控制随机性0.0确定性/0.7创意/1.0高随机--top-p-Top-p 核采样控制多样性0.9常用/0.95更丰富--top-k-Top-k 采样限制候选词数量40平衡/100更自由--frequency-penalty-频率惩罚减少重复0.2轻微/0.5较强--presence-penalty-存在惩罚鼓励新话题0.1轻微/0.3较强--logprobs-返回每个 token 的 logprobs 数量5调试用--ignore-eosFalse忽略结束符强制生成到 max_tokens--ignore-eos测极限长度 场景示例对比不同采样参数对延迟的影响业务场景想知道用 beam search 会不会让响应变慢很多# 测试普通采样快vllm bench serve\--host127.0.0.1\--port8000\--modelmeta-llama/Llama-3-8b\--dataset-name random\--random-input-len100\--random-output-len150\--num-prompts100\--request-rate5\--temperature0.7\--top-p0.9\--save-result\--labelsample_normal# 测试束搜索准但慢vllm bench serve\--host127.0.0.1\--port8000\--modelmeta-llama/Llama-3-8b\--dataset-name random\--random-input-len100\--random-output-len150\--num-prompts100\--request-rate5\--use-beam-search\# ✅ 开启束搜索--best-of5\# ✅ 生成 5 个选最佳--save-result\--labelsample_beam对比结果示例采样方式平均端到端延迟吞吐量适用场景普通采样2.1 秒47 tokens/s✅ 聊天/客服要快束搜索8.7 秒17 tokens/s✅ 代码/数学要准决策实时对话 → 用普通采样 低 temperature代码生成/数学推理 → 用束搜索 高 best-of创意写作 → 用普通采样 高 temperature 低 top-p 完整实战工作流从压测到优化 目标为智能客服做上线前压测#!/bin/bash# bench_serve_workflow.shSERVICE_URLhttp://127.0.0.1:8000MODELmeta-llama/Llama-3-8b-InstructDATASET./data/customer_service_prompts.jsonecho 开始 vLLM 服务压测工作流...# 1️⃣ 快速冒烟测试10 个请求确认服务正常echo 1/4 冒烟测试...vllm bench serve\--base-url$SERVICE_URL\--model$MODEL\--dataset-path$DATASET\--num-prompts10\--request-rate1\--labelsmoke-test# 2️⃣ 标准负载测试模拟日常流量echo 2/4 标准负载测试 (10 QPS)...vllm bench serve\--base-url$SERVICE_URL\--model$MODEL\--dataset-path$DATASET\--num-prompts500\--request-rate10\--max-concurrency50\--save-result\--result-dir ./results\--labelnormal-load\--percentile-metrics ttft,e2el\--metric-percentiles50,90,99\--goodputttft:500 e2el:5000# 3️⃣ 压力测试找瓶颈echo 3/4 压力测试 (30 QPS 突发)...vllm bench serve\--base-url$SERVICE_URL\--model$MODEL\--dataset-path$DATASET\--num-prompts500\--request-rate30\--burstiness0.3\--max-concurrency100\--save-result\--result-dir ./results\--labelstress-test\--plot-timeline# 4️⃣ 生成对比报告echo 4/4 生成对比报告...python3EOF import json, glob print(\n 压测结果对比) print(f{测试场景:20} {成功率:10} {P99首字(ms):15} {Goodput:12}) print(- * 60) for f in sorted(glob.glob(results/*.json)): name f.split(/)[-1].replace(.json, ) data json.load(open(f)) success f{data[success_rate]*100:.1f}% p99_ttft data[metrics][ttft][p99] goodput f{data[goodput].get(ttft:500, 0)*100:.1f}% print(f{name:20} {success:10} {p99_ttft:15.0f} {goodput:12}) EOFecho✅ 压测完成报告在 ./results/ 目录预期输出 压测结果对比 测试场景 成功率 P99首字(ms) Goodput ------------------------------------------------------------ normal-load 100.0% 420 92.3% stress-test 96.8% 1280 68.5%✅上线决策normal-load各项指标达标 → ✅ 可上线stress-testgoodput 70% → ⚠️ 高并发时需扩容或限流建议配置日常 10 QPS 自动扩容阈值 25 QPS⚠️ 常见问题速查表问题现象可能原因解决方案❌Connection refused服务没启动 / host:port 写错确认vllm serve已运行 检查--host/--port401 Unauthorized没带 API Key 或 Key 错误加--header AuthorizationBearer xxxSSL: CERTIFICATE_VERIFY_FAILEDHTTPS 自签名证书加--insecure仅测试环境 成功率突然下降服务过载 / 显存不足降低--request-rate或--max-concurrency 首字延迟特别高长 prompt / 没开前缀缓存服务端加--enable-prefix-caching--enable-chunked-prefill 结果文件找不到--result-dir路径不对用绝对路径或先mkdir -p ./results最后 Checklist✅ 先用--num-prompts 10冒烟测试确认服务连通✅ 生产压测必须带--api-key通过--header✅ 关注p99_ttft和goodput比平均值更能反映用户体验✅ 长文本场景服务端要开--enable-prefix-caching--enable-chunked-prefill✅ 每次压测加--label--save-result方便后续对比分析