lmcache 基准引擎#

lmcache bench engine 命令对推理引擎（例如 vLLM）进行持续性能基准测试。它支持多种工作负载类型，以测试不同的缓存模式，并报告 TTFT、解码速度和吞吐量指标。

lmcache bench engine [options]

配置基准测试有三种方法：

  1. CLI 参数 -- 在命令行中传递所有选项。

  2. 交互模式 -- 运行 lmcache bench engine 而不需要参数，并按照逐步提示进行操作。

  3. 配置文件 -- 将配置保存为 JSON 并使用 --config 进行重放。

快速开始#

最小化（包含所有必需参数）：

lmcache bench engine \
    --engine-url http://localhost:8000 \
    --workload long-doc-qa \
    --lmcache-url http://localhost:8080

交互模式（引导设置）：

lmcache bench engine

交互模式会引导您完成每个必需的设置，然后询问您是否希望配置通用选项和特定于工作负载的选项，还是使用默认值。

从保存的配置文件中：

lmcache bench engine --engine-url http://localhost:8000 \
    --config my_bench.json

配置文件包含基准测试参数（工作负载、KV Cache 设置等），但不包括引擎 URL，因此您可以在不同的引擎上重用相同的配置。

导出配置而不运行基准测试：

lmcache bench engine \
    --engine-url http://localhost:8000 \
    --workload long-doc-qa \
    --lmcache-url http://localhost:8080 \
    --export-config my_bench.json

这将解析所有自动检测到的值（模型名称、每 GB 的令牌数），并将它们保存到一个便携式 JSON 文件中，该文件可以在没有 LMCache 服务器的情况下使用。

非交互模式（用于脚本和 CI）：

lmcache bench engine \
    --engine-url http://localhost:8000 \
    --workload long-doc-qa \
    --lmcache-url http://localhost:8080 \
    --no-interactive

如果缺少任何必需的参数，则立即报错，而不是进入交互模式。这在自动化管道中非常有用。

如果您没有 LMCache 服务器，可以直接传递 --tokens-per-gb-kvcache，而不是 ``--lmcache-url``（有关如何找到此值，请参见 查找 --tokens-per-gb-kvcache）。

常规选项#

标志

必需

描述

--config FILE

不

从 JSON 文件加载配置。跳过交互模式。CLI 标志会覆盖文件中的值。引擎 URL 不会存储在配置文件中，必须单独提供。

--export-config FILE

不

将解析后的配置导出到 JSON 文件并退出。不会运行基准测试。自动检测的值（模型，每 GB 的令牌数）被解析并保存，以便配置可移植。特定于环境的值（引擎 URL，LMCache URL）被排除在外。

--no-interactive

不

禁用交互模式。如果缺少必需的参数则报错，而不是提示。对脚本和 CI 很有用。

--engine-url URL

是

推理引擎 URL（例如，http://localhost:8000）。如果需要身份验证，请设置 OPENAI_API_KEY 环境变量。

--workload TYPE

是

工作负载类型：long-doc-qa、multi-round-chat、long-doc-permutator、prefix-suffix-tuner 或 random-prefill。

--tokens-per-gb-kvcache N

*

每 GB KV Cache 的令牌数。除非设置了 --lmcache-url，否则这是必需的。有关如何找到此值的信息，请参见 查找 --tokens-per-gb-kvcache。

--lmcache-url URL

不

LMCache HTTP 服务器 URL。当提供时，--tokens-per-gb-kvcache 会从服务器自动检测。

--model NAME

不

模型名称。如果省略，将从引擎自动检测。

--kv-cache-volume GB

不

目标活动 KV Cache 容量（单位：GB，默认值：100）。

--seed N

不

随机种子（默认值：42）。

--output-dir DIR

不

CSV 和 JSON 输出文件的目录（默认：当前目录）。

--no-csv

不

跳过 CSV 导出。

--json

不

导出 JSON 摘要文件。

-q / --quiet

不

抑制实时进度显示。

查找 --tokens-per-gb-kvcache#

如果您有一个正在运行的 LMCache 服务器，最简单的方法是传递 --lmcache-url 并让工具自动检测该值。

如果您正在使用 vLLM 而没有 LMCache，请在 vLLM 的启动日志中查找这些行：

INFO: Available KV cache memory: 12.34 GiB
INFO: GPU KV cache size: 567,890 tokens

然后计算:

tokens_per_gb = 567890 / 12.34 = 46,020

工作负载#

长文档问答#

模拟对长文档的重复问答。热身阶段将每个文档发送一次以填充 KV Cache，然后以信号量控制的并发方式发送基准查询。

标志

默认

描述

--ldqa-document-length

10000

每个合成文档的令牌长度。

--ldqa-query-per-document

2

每个文档提问的数量。

--ldqa-shuffle-policy

随机

请求排序：``random``（随机）或``tile``（逐轮）。

--ldqa-num-inflight-requests

3

最大并发进行中的请求数量。

示例：

lmcache bench engine \
    --engine-url http://localhost:8000 \
    --workload long-doc-qa \
    --lmcache-url http://localhost:8080 \
    --kv-cache-volume 50 \
    --ldqa-document-length 8000 \
    --ldqa-query-per-document 4 \
    --ldqa-shuffle-policy tile

多轮聊天#

模拟具有状态的多轮聊天。创建并发用户会话，以固定的 QPS 速率调度请求，并在会话历史中记录响应，以便每个后续查询都包含先前的上下文。

标志

默认

描述

--mrc-shared-prompt-length

2000

每个会话的系统提示令牌长度。

--mrc-chat-history-length

10000

预填充聊天历史令牌长度。

--mrc-user-input-length

50

每个用户查询的令牌数。

--mrc-output-length

200

每个响应生成的最大令牌数。

--mrc-qps

1.0

每秒目标查询数。

--mrc-duration

60.0

基准测试持续时间（以秒为单位）。

示例：

lmcache bench engine \
    --engine-url http://localhost:8000 \
    --workload multi-round-chat \
    --lmcache-url http://localhost:8080 \
    --mrc-qps 2.0 \
    --mrc-duration 120

long-doc-permutator#

通过发送一组上下文文档的排列组合，压力测试混合 KV Cache 的重用。每个请求以不同的顺序连接所有上下文文档：

[System Prompt] + [Doc_i1] + [Doc_i2] + ... + [Doc_iN]

在基准测试阶段之前，会发送一个单一的虚拟预热请求。请求以信号量控制的并发方式分发。

标志

默认

描述

--ldp-num-contexts

5

唯一上下文文档的数量。

--ldp-context-length

5000

每个上下文文档的令牌长度。

--ldp-system-prompt-length

1000

共享系统提示的令牌长度。使用 0 表示没有系统提示。

--ldp-num-permutations

10

发送的不同排列组合的数量。上限为 N!，其中 N = --ldp-num-contexts。

--ldp-num-inflight-requests

1

最大并发进行中的请求数量。

示例：

lmcache bench engine \
    --engine-url http://localhost:8000 \
    --workload long-doc-permutator \
    --lmcache-url http://localhost:8080 \
    --ldp-num-contexts 4 \
    --ldp-context-length 8000 \
    --ldp-num-permutations 24 \
    --ldp-num-inflight-requests 2

prefix-suffix-tuner#

一个两遍顺序工作负载，旨在 不变 地在三个 LMCache 配置中运行，以展示每个缓存层级（L0 HBM、L1 DRAM、L2 磁盘）的价值：

基线

LMCache 配置

目标溢出

预期的 pass-2 命中

1

原生 vLLM (仅 L0)

L0 (HBM)

无 -- 每个请求都是冷预填充

2

vLLM + LMCache L1 + L2

L1 (DRAM)

L2 前缀命中（后缀重计算）

3

vLLM + LMCache L1 + L2 + CacheBlend

L1 (DRAM)

L2 前缀命中 + CacheBlend 后缀命中

将 --kv-cache-volume 设置为您希望溢出的层的大小（基线 1 的 L0 大小，基线 2 和 3 的 L1 大小）。工作负载在各个基线之间是相同的。

每个请求的布局:

[prefix_i with unique-ID][random breaker][shared suffix]

  • num_prefixes 个不同的前缀，每个前缀以 PREFIX_<8-hex> 开头，因此前缀的标记化哈希在池中是不同的。

  • 每个请求一个新的随机 32-token 断路器，打破普通前缀缓存的前缀边界。

  • 每个请求使用的单个共享后缀——这是 CacheBlend 唯一可以重用的条目。

第 1 次传递（预热）将每个前缀发送一次以填充缓存；其统计数据会被丢弃。第 2 次传递以相同的顺序再次发送它们。由于 LRU 在每次第 2 次访问时逐出下一个所需的前缀，即使目标层溢出 1.05 倍也足以使每个第 2 次请求未命中该层并降级到下一层。

标志

默认

描述

--psf-context-length

8000

每个请求的总令牌数（前缀 + 分隔符 + 后缀）。

--psf-prefix-ratio

0.8

前缀使用的上下文长度的比例。必须在 (0.0, 1.0) 之间。其余部分（减去 32 个标记的分隔符）是共享后缀。

--psf-thrash

20.0

KV-cache 层的大小（以 GB 为单位），用于溢出。 对于普通的 vLLM，请使用 L0（HBM）大小，或者对于分层基线，请使用 L1（LMCache DRAM）大小。工作负载将其前缀池的大小设置为略大于此值（内部溢出 5%），足以使每个顺序调度 + LRU 的 pass-2 请求在该层中未命中。

通过 floor(psf_thrash * 1.05 * tokens_per_gb / prefix_tokens) 计算的 pass-2（测量）请求数量等于前缀池大小。此工作负载未使用 --kv-cache-volume — 尺寸完全由 --psf-thrash 驱动。

示例：

lmcache bench engine \
    --engine-url http://localhost:8000 \
    --workload prefix-suffix-tuner \
    --lmcache-url http://localhost:8080 \
    --psf-context-length 8000 \
    --psf-prefix-ratio 0.8 \
    --psf-thrash 100

备注

为了使分析模型声明“thrash ≈ L1 大小 → ~0% LMCache 命中率”在经验上成立，LMCache 服务器必须以 --eviction-ratio 0.99 启动（默认的 0.20 仅在每个周期清除 20%，在第 2 次传递中大约保留 60% 的第 1 次传递内容）：

lmcache server --l1-size-gb <SIZE> --eviction-policy LRU \
    --eviction-trigger-watermark 0.80 \
    --eviction-ratio 0.99

工作负载在第 1 次（热身）和第 2 次（测量）之间会休眠 5 秒，因此 LMCache 的 1Hz 批量逐出轮询线程有时间实际运行。没有这个休眠，快速基准测试在任何逐出触发之前就完成了。

随机预填充#

同时发送所有请求，max_tokens=1，以测量纯粹的 Prefill 性能。没有预热阶段。

标志

默认

描述

--rp-request-length

10000

每个 Prefill 请求的令牌长度。

--rp-num-requests

50

要发送的请求数量。

示例：

lmcache bench engine \
    --engine-url http://localhost:8000 \
    --workload random-prefill \
    --lmcache-url http://localhost:8080 \
    --rp-request-length 15000 \
    --rp-num-requests 100

交互模式#

交互模式演示

当未提供 --engine-url 或 --workload``（并且未设置 ``--no-interactive）时，工具将进入交互模式。它将引导您完成四个阶段：

  1. 必需设置 -- 引擎 URL、工作负载类型、LMCache 服务器（或每 GB 的令牌）。

  2. **通用设置**（可选门）-- 模型名称，KV Cache 容量。

  3. **工作负载设置**（可选网关）-- 工作负载特定参数。

  4. 摘要和操作 -- 审查配置，然后启动基准测试或导出到 JSON 文件。

每个提示专注于单个设置。选择提示使用箭头键；文本和数字提示接受键入的输入，默认值以括号显示。

══════════════════════════════════════════════════
 lmcache bench engine -- Interactive Setup
══════════════════════════════════════════════════

Engine URL
  URL of the inference engine.
  [default: http://localhost:8000] >

Workload
  The type of benchmark workload to run.
  Use up/down to navigate, Enter to select.

  * long-doc-qa           Repeated Q&A over long documents
    multi-round-chat       Multi-turn chat with stateful sessions
    long-doc-permutator    Permutations of context documents
    prefix-suffix-tuner    Two-pass tiered KV-cache demonstrator
    random-prefill         Prefill-only requests fired simultaneously

LMCache Server
  Do you have a running LMCache server?
  It can auto-detect KV cache size information.
  [default: Y] (Y/n) >

...

──────────────────────────────────────────────────
 Configuration Summary
──────────────────────────────────────────────────
  Workload:             long-doc-qa
  Model:                Qwen/Qwen3-14B
  Tokens per GB:        6553
  ...
──────────────────────────────────────────────────

What would you like to do?
  * Start benchmark
    Export configuration for later use and exit

当您选择“导出配置”时，所有自动检测到的值（模型名称、每 GB 的令牌数）将被解析并保存到一个可移植的 JSON 文件中。

配置文件#

配置文件存储基准测试参数，但**不**存储特定于环境的值，例如引擎 URL 或 LMCache URL。这使您可以在不同环境中重用相同的配置。

您可以通过三种方式创建配置文件：

  1. 交互模式 -- 在摘要步骤选择“导出配置”。

  2. ``--export-config`` -- 从 CLI 解析并导出，而不运行。

  3. 手动 -- 编写 JSON，键名与 CLI 参数名称匹配（用下划线替换破折号）。

示例配置文件：

{
  "model": "Qwen/Qwen3-14B",
  "workload": "long-doc-qa",
  "tokens_per_gb_kvcache": 6553,
  "kv_cache_volume": 100.0,
  "ldqa_document_length": 10000,
  "ldqa_query_per_document": 2,
  "ldqa_shuffle_policy": "random",
  "ldqa_num_inflight_requests": 3
}

使用 --config 加载它（引擎 URL 必须单独提供）：

lmcache bench engine --engine-url http://localhost:8000 \
    --config my_bench.json

CLI 参数会覆盖配置文件中的值，因此您可以使用基本配置并调整单个设置：

# Use saved config but override KV cache volume
lmcache bench engine --engine-url http://localhost:8000 \
    --config my_bench.json --kv-cache-volume 200

输出#

终端（实时进度）#

在基准测试期间，实时进度显示会显示正在进行的请求、平均 TTFT、解码速度和吞吐量。使用 -q 可以抑制它。

终端（最终摘要）#

完成后，将打印一个摘要表：

======= Engine Benchmark Result (long-doc-qa) ========
---------------------- Configuration ------------------
Engine URL:                       http://localhost:8000
Model:                            Qwen/Qwen3-14B
Workload:                         long-doc-qa
------------------------- Results ---------------------
Successful requests:              20
Failed requests:                  0
Benchmark duration (s):           31.34
Total input tokens:               200000
Total output tokens:              2560
Input throughput (tok/s):         6381.62
Output throughput (tok/s):        81.69
--------------- Time to First Token -------------------
Mean TTFT (ms):                   313.41
P50 TTFT (ms):                    272.83
P90 TTFT (ms):                    587.21
P99 TTFT (ms):                    837.32
------------------ Decoding Speed ---------------------
Mean decode (tok/s):              48.23
P50 decode (tok/s):               47.91
P90 decode (tok/s):               42.10
P99 decode (tok/s):               38.55
======================================================

CSV 和 JSON#

  • bench_results.csv -- 每个请求的指标（TTFT、延迟、解码速度、令牌计数）。默认情况下写入；使用 --no-csv 跳过。

  • bench_summary.json -- 聚合统计数据，包括百分位数和配置元数据。通过 --json 选项启用。

两个文件都写入到 ``--output-dir``（默认：当前目录）。

退出代码#

代码

含义

0

所有请求均成功。

1

一个或多个请求失败。