参数扫描¶

vllm bench sweep 是一套命令，旨在跨多种配置运行基准测试，并通过可视化结果进行比较。

在线基准测试¶

基本¶

vllm bench sweep serve 启动 vllm serve 并为每个服务器配置迭代运行 vllm bench serve。

提示

如果您只需要为单个服务器配置运行基准测试，请考虑使用 GuideLLM，这是一个成熟的性能基准测试框架，具有实时进度更新和自动报告生成功能。在数据集加载、请求格式化和工作负载模式方面，它也比 vllm bench serve 更灵活。

按照以下步骤运行脚本

构造 vllm serve 的基本命令，并将其传递给 --serve-cmd 选项。
构造 vllm bench serve 的基本命令，并将其传递给 --bench-cmd 选项。

(可选) 如果您想更改 vllm serve 的设置，请创建一个新的 JSON 文件，并用您想测试的参数组合填充它。将文件路径传递给 --serve-params。

示例：调整 --max-num-seqs 和 --max-num-batched-tokens

[
    {
        "max_num_seqs": 32,
        "max_num_batched_tokens": 1024
    },
    {
        "max_num_seqs": 64,
        "max_num_batched_tokens": 1024
    },
    {
        "max_num_seqs": 64,
        "max_num_batched_tokens": 2048
    },
    {
        "max_num_seqs": 128,
        "max_num_batched_tokens": 2048
    },
    {
        "max_num_seqs": 128,
        "max_num_batched_tokens": 4096
    },
    {
        "max_num_seqs": 256,
        "max_num_batched_tokens": 4096
    }
]

(可选) 如果您想更改 vllm bench serve 的设置，请创建一个新的 JSON 文件，并用您想测试的参数组合填充它。将文件路径传递给 --bench-params。

示例：对随机数据集使用不同的输入/输出长度

[
    {
        "_benchmark_name": "scenario_A",
        "random_input_len": 128,
        "random_output_len": 32
    },
    {
        "_benchmark_name": "scenario_B",
        "random_input_len": 256,
        "random_output_len": 64
    },
    {
        "_benchmark_name": "scenario_C",
        "random_input_len": 512,
        "random_output_len": 128
    }
]

设置 --output-dir，并可选地设置 --experiment-name 来控制结果的保存位置。

示例命令

vllm bench sweep serve \
    --serve-cmd 'vllm serve meta-llama/Llama-2-7b-chat-hf' \
    --bench-cmd 'vllm bench serve --model meta-llama/Llama-2-7b-chat-hf --backend vllm --endpoint /v1/completions --dataset-name sharegpt --dataset-path benchmarks/ShareGPT_V3_unfiltered_cleaned_split.json' \
    --serve-params benchmarks/serve_hparams.json \
    --bench-params benchmarks/bench_hparams.json \
    --output-dir benchmarks/results \
    --experiment-name demo

默认情况下，每个参数组合都会进行 3 次基准测试，以使结果更可靠。您可以通过设置 --num-runs 来调整运行次数。

重要

如果同时传递 --serve-params 和 --bench-params，脚本将对它们进行笛卡尔积迭代。您可以使用 --dry-run 预览将要运行的命令。

对于每个 --serve-params，我们只启动服务器一次，并使其为多个 --bench-params 保持运行。在每次基准测试运行之间，我们调用所有 /reset_*_cache 端点，以便为下一次运行获得一个干净的环境。如果您使用自定义的 --serve-cmd，您可以通过设置 --after-bench-cmd 来覆盖用于重置状态的命令。

注意

您应该设置 _benchmark_name 为涉及许多变量的参数组合提供一个人类可读的名称。如果文件名否则会超过文件系统允许的最大路径长度，这会变得强制。

提示

如果发生意外错误（例如，连接到 HF Hub 时超时），您可以使用 --resume 选项继续参数扫描。

工作负载探索器¶

vllm bench sweep serve_workload 是 vllm bench sweep serve 的一个变体，它探索不同的工作负载级别，以找出延迟和吞吐量之间的权衡。结果也可以通过可视化来确定可行的 SLA。

工作负载可以用请求速率或并发性来表示（使用 --workload-var 选择）。

示例命令

vllm bench sweep serve_workload \
    --serve-cmd 'vllm serve meta-llama/Llama-2-7b-chat-hf' \
    --bench-cmd 'vllm bench serve --model meta-llama/Llama-2-7b-chat-hf --backend vllm --endpoint /v1/completions --dataset-name sharegpt --dataset-path benchmarks/ShareGPT_V3_unfiltered_cleaned_split.json --num-prompts 100' \
    --workload-var max_concurrency \
    --serve-params benchmarks/serve_hparams.json \
    --bench-params benchmarks/bench_hparams.json \
    --num-runs 1 \
    --output-dir benchmarks/results \
    --experiment-name demo

探索不同工作负载级别的算法可以概括如下

逐个发送请求（串行推理，最低工作负载）来运行基准测试。这会导致最低的延迟和吞吐量。
一次性发送所有请求（批量推理，最高工作负载）来运行基准测试。这会导致最高的延迟和吞吐量。
估计与步骤 2 对应的 workload_var 值。
使用剩余的迭代，均匀地运行 workload_var 中间值的基准测试。

您可以通过设置 --workload-iters 来覆盖算法中的迭代次数。

提示

这是我们对应于 GuideLLM 的 --profile sweep。

通常，--workload-var max_concurrency 会产生更可靠的结果，因为它直接控制施加在 vLLM 引擎上的工作负载。尽管如此，我们仍默认使用 --workload-var request_rate 以保持与 GuideLLM 类似的行为。

启动基准测试¶

vllm bench sweep startup 运行 vllm bench startup 跨参数组合，以比较不同引擎设置的冷/热启动时间。

按照以下步骤运行脚本

(可选) 构造 vllm bench startup 的基本命令，并将其传递给 --startup-cmd (默认: vllm bench startup)。
(可选) 重用 vllm bench sweep serve 中的 --serve-params JSON 以改变引擎设置。只有 vllm bench startup 支持的参数才会被应用。
(可选) 创建一个 --startup-params JSON 以改变启动特定的选项，例如迭代次数。
确定您想在哪里保存结果，并将其传递给 --output-dir。

--serve-params 示例

[
    {
        "_benchmark_name": "tp1",
        "model": "Qwen/Qwen3-0.6B",
        "tensor_parallel_size": 1,
        "gpu_memory_utilization": 0.9
    },
    {
        "_benchmark_name": "tp2",
        "model": "Qwen/Qwen3-0.6B",
        "tensor_parallel_size": 2,
        "gpu_memory_utilization": 0.9
    }
]

--startup-params 示例

[
    {
        "_benchmark_name": "qwen3-0.6",
        "num_iters_cold": 2,
        "num_iters_warmup": 1,
        "num_iters_warm": 2
    }
]

示例命令

vllm bench sweep startup \
    --startup-cmd 'vllm bench startup --model Qwen/Qwen3-0.6B' \
    --serve-params benchmarks/serve_hparams.json \
    --startup-params benchmarks/startup_hparams.json \
    --output-dir benchmarks/results \
    --experiment-name demo

重要

默认情况下，--serve-params 或 --startup-params 中不支持的参数将被忽略并发出警告。使用 --strict-params 可以在遇到未知键时快速失败。

可视化¶

基本¶

vllm bench sweep plot 可用于从参数扫描结果中绘制性能曲线。

通过 --var-x 和 --var-y 控制要绘制的变量，可选地对值应用 --filter-by 和 --bin-by。图表根据 --fig-by、--row-by、--col-by 和 --curve-by 进行组织。

用于可视化工作负载探索器结果的示例命令

EXPERIMENT_DIR=${1:-"benchmarks/results/demo"}

# Latency increases as the workload increases
vllm bench sweep plot $EXPERIMENT_DIR \
    --var-x max_concurrency \
    --var-y median_ttft_ms \
    --col-by _benchmark_name \
    --curve-by max_num_seqs,max_num_batched_tokens \
    --fig-name latency_curve

# Throughput saturates as workload increases
vllm bench sweep plot $EXPERIMENT_DIR \
    --var-x max_concurrency \
    --var-y total_token_throughput \
    --col-by _benchmark_name \
    --curve-by max_num_seqs,max_num_batched_tokens \
    --fig-name throughput_curve

# Tradeoff between latency and throughput
vllm bench sweep plot $EXPERIMENT_DIR \
    --var-x total_token_throughput \
    --var-y median_ttft_ms \
    --col-by _benchmark_name \
    --curve-by max_num_seqs,max_num_batched_tokens \
    --fig-name latency_throughput

提示

您可以使用 --dry-run 预览将要绘制的图。

帕累托图¶

vllm bench sweep plot_pareto 有助于选择平衡了每用户和每 GPU 吞吐量的配置。

更高的并发性或批处理大小可以提高 GPU 效率（每 GPU），但会增加每用户延迟；较低的并发性可以提高每用户速率但 GPU 利用率不足；帕累托前沿显示了您运行中最佳可实现对。

x 轴：tokens/秒/用户 = output_throughput ÷ 并发数 (--user-count-var，默认 max_concurrency，备用 max_concurrent_requests)。
y 轴：tokens/秒/GPU = output_throughput ÷ GPU 数量 (如果设置了 --gpu-count-var；否则 gpu_count 是 TP×PP*DP)。
输出：OUTPUT_DIR/pareto/PARETO.png 中的单个图。
显示每个数据点中使用的配置 --label-by (默认: max_concurrency,gpu_count)。

示例

EXPERIMENT_DIR=${1:-"benchmarks/results/demo"}

vllm bench sweep plot_pareto $EXPERIMENT_DIR \
  --label-by max_concurrency,tensor_parallel_size,pipeline_parallel_size

提示

您可以使用 --dry-run 预览将要绘制的图。