vllm-prefix-cache-bench

vLLM 前缀缓存基准测试

对 vLLM 的自动前缀缓存（APC）功能进行效率基准测试。离线脚本 benchmarks/benchmark_prefix_caching.py 可直接对 vLLM 引擎运行（无需服务）。对于在线／服务测试，请使用 vllm bench serve 和 prefix_repetition 数据集。

适用场景

• 用户想要衡量前缀缓存对重复提示词或部分共享提示词的性能影响。
• 用户想要比较启用和未启用 --enable-prefix-caching 时的吞吐量／延迟。
• 用户想要使用固定的合成提示词、真实数据集（例如 ShareGPT）或合成前缀／后缀重复模式测试前缀缓存。

选项 1（默认）：使用前缀缓存的固定提示词

运行合成基准测试，多次重复使用固定提示词，直接衡量缓存命中效率。无需下载数据集。

python3 benchmarks/benchmark_prefix_caching.py \
  --model Qwen/Qwen3-8B \
  --enable-prefix-caching \
  --num-prompts 1 \
  --repeat-count 100 \
  --input-length-range 128:256

若要与未启用缓存的基线进行比较：

python3 benchmarks/benchmark_prefix_caching.py \
  --model Qwen/Qwen3-8B \
  --no-enable-prefix-caching \
  --num-prompts 1 \
  --repeat-count 100 \
  --input-length-range 128:256

选项 2：使用前缀缓存的 ShareGPT 数据集

使用 ShareGPT 的真实对话数据，评估自然产生的提示词共享场景下的前缀缓存效果。

首先，下载数据集：

wget https://huggingface.co/datasets/anon8231489123/ShareGPT_Vicuna_unfiltered/resolve/main/ShareGPT_V3_unfiltered_cleaned_split.json

然后运行基准测试：

python3 benchmarks/benchmark_prefix_caching.py \
  --model Qwen/Qwen3-8B \
  --dataset-path ShareGPT_V3_unfiltered_cleaned_split.json \
  --enable-prefix-caching \
  --num-prompts 20 \
  --repeat-count 5 \
  --input-length-range 128:256

选项 3：前缀重复数据集（在线）

使用 vllm bench serve 和合成的 prefix_repetition 数据集，通过服务 API 测试缓存效果。此方法需要运行中的 vLLM 服务。

首先，启动服务：

vllm serve Qwen/Qwen3-8B

然后运行基准测试：

vllm bench serve \
  --backend openai \
  --model Qwen/Qwen3-8B \
  --dataset-name prefix_repetition \
  --num-prompts 100 \
  --prefix-repetition-prefix-len 512 \
  --prefix-repetition-suffix-len 128 \
  --prefix-repetition-num-prefixes 5 \
  --prefix-repetition-output-len 128

prefix_repetition 的关键参数：

参数	描述
--prefix-repetition-prefix-len	共享前缀部分的令牌数
--prefix-repetition-suffix-len	唯一后缀部分的令牌数
--prefix-repetition-num-prefixes	循环使用的不同前缀数量
--prefix-repetition-output-len	每个请求生成的输出令牌数

注意事项

• 从 vLLM 仓库根目录运行所有命令（cd vllm）。
• 保持使用默认模型（Qwen/Qwen3-8B），除非用户指定其他模型或该模型不可用；只更改 --model。
• 选项 1 和 2 中的 --repeat-count 控制每个采样提示词的重放次数；值越高，缓存命中率越高。
• --input-length-range 接受 min:max 格式的令牌范围，例如 128:256。
• 对于多 GPU 设置，请添加 --tensor-parallel-size <N>。
• 若要测试前缀缓存内部使用的不同哈希算法，请使用 --prefix-caching-hash-algo xxhash（需要执行 pip install xxhash）。

benchmark_prefix_caching.py 的参数

参数	必需	描述
--model	是	模型名称或路径（HuggingFace ID 或本地路径）
--num-prompts	是	要处理的提示词数量
--input-length-range	是	输入的令牌长度范围，例如 128:256
--repeat-count	否	每个提示词的重复次数（默认值：1）
--dataset-path	否	数据集文件的路径（例如 ShareGPT JSON）。合成固定提示词模式下省略此项
--prefix-len	否	添加到每个提示词前的固定前缀令牌长度
--output-len	否	每个请求生成的输出令牌数
--sort	否	基准测试前按提示词长度排序
--enable-prefix-caching / --no-enable-prefix-caching	否	切换 APC（建议：启用以测试缓存）
--prefix-caching-hash-algo	否	哈希算法：sha256、sha256_cbor、xxhash、xxhash_cbor
--tensor-parallel-size	否	张量并行使用的 GPU 数量
--disable-detokenize	否	跳过反分词，以减少开销

故障排除

• 如果 python3 benchmarks/*.py 报告找不到文件，请先定位本地 vLLM 仓库，并从该仓库根目录运行命令。
• 如果你还没有该仓库，请先克隆，然后继续：

git clone https://github.com/vllm-project/vllm
cd vllm

• 如果 HuggingFace 模型下载因访问限制而失败，请设置令牌：export HF_TOKEN=<your_token>，或传入 --hf-token <your_token>。
• 如果未安装 xxhash 或 cbor2，且你使用了这些哈希算法，请先安装：pip install xxhash cbor2。