lmcache bench server#

lmcache bench server 命令是对 LMCache 多进程 (MP) 缓存服务器的端到端完整性测试。它通过 ZMQ 连接到正在运行的服务器，并对一系列合成请求执行完整的 KV 缓存数据路径，然后可选地通过 HTTP API 验证每个块的校验和。

lmcache bench server [options]

与 lmcache bench engine 不同，此命令**不**需要推理引擎。它只需要一个正在运行的 LMCache MP 服务器（ZMQ + HTTP）和一个 GPU。

它的作用#

对于 [--start, --end) 中的每个序列，该工具运行两个阶段：

  1. 冷启动 -- LOOKUP 预计会未命中，因此生成的 KV 张量会被 STORE\ 存储在服务器上。

  2. 热通道 -- LOOKUP 预计会命中；工具发出 RETRIEVE 并将检索到的 KV 块的校验和与原始值进行比较。

完整的 RPC 路径是:

REGISTER_KV_CACHE → GET_CHUNK_SIZE → LOOKUP
  → QUERY_PREFETCH_STATUS → RETRIEVE → STORE
  → END_SESSION

当 --url 指向服务器的 HTTP 端点时，逐块的校验和会额外与服务器端的计算进行交叉检查，因此生产者和消费者之间的不匹配会以显眼的 CHECKSUM MISMATCH 日志行的形式显现出来。

快速开始#

在一个终端中启动 MP 服务器：

python3 -m lmcache.v1.multiprocess.http_server \
    --host localhost --port 15556 \
    --chunk-size 256 --l1-size-gb 5 \
    --eviction-policy LRU --max-workers 1

然后在另一个终端中：

lmcache bench server \
    --rpc-url tcp://localhost:15556 \
    --url http://localhost:8080

默认情况下，该工具会一直运行（--end 未设置）；您可以随时使用 Ctrl-C 停止它。传递 --end N 以进行有限次运行。

选项#

标志

默认

描述

--rpc-url URL

tcp://localhost:5555

MP 缓存服务器的 ZMQ 端点。

--url URL

http://localhost:8080

服务器的校验和 API 的 HTTP 基础 URL。用于端到端验证每个块的校验和。

--mode {gpu}

gpu

运行模式。目前仅支持 gpu；CPU 模式是计划中的后续功能。

--num-tokens N

512

每个合成请求的令牌数。

--num-blocks N

1024

在 GPU 上分配的分页块数量。

--block-size N

16

每个分页块的令牌数。

--start N

0

要运行的第一个序列号。

--end N

(未设置)

序列号的独占上限。当省略时，循环将永远运行。

--interval SECS

0.5

连续子通道之间的延迟。

--kvcache-shape-spec SPEC

(2,1024,16,8,128):float16:32

KV Cache 形状规格（见下文）。

KV 缓存形状规范#

--kvcache-shape-spec 标志描述了 KV 张量在 GPU 上的布局。规格是一个或多个用 ; 分隔的组：

(kv_size,NB,BS,NH,HS):dtype:layers[;(...):dtype:layers...]

字段：

  • kv_size -- 经典注意力（分离 K/V）为 2，MLA 为 1。

  • NB -- 分页块的数量。

  • BS -- 块大小（每块的令牌数）。

  • NH -- 每层的注意力头数量。

  • HS -- 头部大小（以元素为单位）。

  • dtype -- 元素数据类型（例如 float16、bfloat16、float32、uint8）。完整的集合与 lmcache/v1/kv_layer_groups.py 中的 DTYPE_MAP 的键匹配。

  • layers -- 该组中的层数。

多组规格允许您建模异构层（例如，在同一模型中结合 MLA 层和经典注意力层）：

lmcache bench server \
    --rpc-url tcp://localhost:15556 \
    --kvcache-shape-spec "(1,1024,16,1,128):float16:4;(2,1024,16,8,128):float16:28"

所有组必须共享相同的 NB 和 ``BS``（这是分页 KV 的物理限制）。各组的层数总和等于注册到服务器的总层数。

请参阅 parse_kvcache_shape_spec 在 lmcache/v1/kv_layer_groups.py 中的权威解析规则和验证错误。

示例输出#

Connecting to LMCache MP Server at tcp://localhost:15556 (mode=gpu) ...
Server chunk_size = 256
Resolved KV shape spec: (2,1024,16,8,128):float16:32
[seq=0] LOOKUP cold:  0/2 chunks hit (1.82 ms)
[seq=0] STORE:        2 chunks stored (1.74 ms)
[seq=0] LOOKUP warm:  2/2 chunks hit (1.31 ms)
[seq=0] RETRIEVE:     2 chunks retrieved (1.48 ms)
[seq=0] CHECKSUM MATCH OK
[seq=1] ...

日志中任何 CHECKSUM MISMATCH、ERROR 或 Python 回溯都表示存在值得调查的实际问题。

退出代码#

代码

含义

0

测试循环完成（或通过 Ctrl-C 干净地中断），没有校验和不匹配。

1

致命错误（例如，在 --mode gpu 中 CUDA 不可用、服务器无法访问或校验和不匹配）。

另请参阅#

  • ：doc:bench -- lmcache bench engine 用于引擎端工作负载基准测试。

  • lmcache bench l2 -- lmcache bench l2 for store / lookup / load throughput benchmarks against an L2 cache adapter.

  • lmcache kvcache -- lmcache kvcache 用于管理运行服务器上的 KV Cache 状态（清除等）。