CLI 参考#
LMCache 提供了一个统一的 lmcache 命令行接口，用于与 KV Cache 服务器交互、运行基准测试和检查缓存状态。
lmcache <command> [options]
安装#
lmcache CLI 可在两个软件包中使用：
包 |
安装 |
何时使用 |
|---|---|---|
|
|
完整安装：服务器、CLI 和 CUDA 扩展。需要 Linux + GPU。 |
|
|
仅限 CLI：查询、ping、基准测试、描述。无需 GPU，任何操作系统均可。 |
备注
请勿在同一环境中安装这两个软件包 — 它们都提供 lmcache 入口点。
快速开始#
安装 LMCache 后，可以使用 lmcache 命令：
# Show available commands
lmcache -h
# Check if the KV cache server is alive
lmcache ping kvcache
# Launch the LMCache server (ZMQ + HTTP)
lmcache server --host 0.0.0.0 --port 5555 --l1-size-gb 100 --eviction-policy LRU
# Run a benchmark against the engine
lmcache bench engine --engine-url http://localhost:8000 \
--workload long-doc-qa --lmcache-url http://localhost:8080
# JSON on stdout (for scripts)
lmcache ping kvcache --format json
# Save metrics to a file (format follows --format, default: terminal)
lmcache describe kvcache --format json --output status.json
可用命令#
命令 |
描述 |
|---|---|
|
显示正在运行的 LMCache 服务的详细状态，包括缓存健康状况、L1 存储、注册的模型和 L2 适配器。 |
|
用于服务引擎和 KV Cache 工作线程的单次查询接口。 |
|
启动 LMCache 服务器（ZMQ + HTTP）。需要完整的 |
|
LMCache 或 vLLM 服务器的存活检查。 |
|
对推理引擎运行持续性能基准测试。 |
|
在运行的服务器上管理 KV Cache 状态（例如，清除 L1 缓存）。 |
bench — 引擎基准测试#
对推理引擎运行持续基准测试，使用多种工作负载类型：
# Minimal: all required args on the command line
lmcache bench engine \
--engine-url http://localhost:8000 \
--workload long-doc-qa \
--lmcache-url http://localhost:8080
# Interactive mode: guided step-by-step setup
lmcache bench engine
# From a saved config file (engine URL provided separately)
lmcache bench engine --engine-url http://localhost:8000 \
--config my_bench.json
# Export config for later reuse (resolves auto-detected values)
lmcache bench engine \
--engine-url http://localhost:8000 \
--workload long-doc-qa \
--lmcache-url http://localhost:8080 \
--export-config my_bench.json
# Non-interactive mode for scripts/CI (errors if args missing)
lmcache bench engine \
--engine-url http://localhost:8000 \
--workload long-doc-qa \
--lmcache-url http://localhost:8080 \
--no-interactive
提供五种工作负载：
long-doc-qa -- 在长文档上进行重复的问答（测试 KV Cache 重用）。
多轮聊天 -- 带有状态会话的多轮聊天。
long-doc-permutator -- 上下文文档的排列组合（混合缓存重用压力测试）。
prefix-suffix-tuner -- 两次传递的顺序工作负载，演示分层 KV Cache 重用 (L0/L1/L2)。
随机预填 -- 同时发起的仅预填请求。
请参阅 lmcache 基准引擎 以获取完整文档，包括所有工作负载选项、交互模式详细信息和配置文件格式。
describe — 服务状态仪表板#
检查正在运行的 LMCache KV Cache 服务器的状态：
lmcache describe kvcache --url http://localhost:8000
============ LMCache KV Cache Service ============
Health: OK
URL: http://localhost:8000
Engine type: BlendEngine
Chunk size: 256
L1 capacity (GB): 60.00
L1 used (GB): 42.30 (70.5%)
Eviction policy: LRU
Cached objects: 1024
Active sessions: 3
---- Model: meta-llama/Llama-3.1-70B-Instruct ----
Model: meta-llama/Llama-3.1-70B-Instruct
World size: 4
GPU IDs: 0, 1, 2, 3
Attention backend: vLLM non-MLA flash attention
GPU KV shape: NL x [2, NB, BS, NH, HS]
GPU KV tensor shape: 80 x [2, 2048, 128, 8, 128]
Num layers: 80
Block size: 128
Hidden dim size: 1024
Dtype: torch.float16
MLA: False
Num blocks: 2048
------------- L2: NixlStoreL2Adapter -------------
Type: NixlStoreL2Adapter
Health: OK
Backend: nixl_rdma
Stored objects: 512
Pool used: 480 / 512 (93.8%)
==================================================
输出显示：
概述 — 健康状态、引擎类型、块大小。
L1 存储 — 容量、使用情况、逐出策略、缓存对象数量。
注册模型 — 每个模型的 KV Cache 布局，包括 GPU KV 张量形状（符号和具体）、注意力后端和层详细信息。
L2 适配器 — 类型、健康状况、后端、存储对象和利用率。
参数#
标志 |
描述 |
|---|---|
|
描述的目标（目前仅支持 |
|
LMCache HTTP 服务器 URL（默认： |
|
输出格式： |
|
将指标保存到文件中（格式遵循 |
JSON 输出#
使用 --format json 以机器可读的输出格式。模型和 L2 适配器被收集到列表中，以便于程序访问：
lmcache describe kvcache --url http://localhost:8000 --format json
{
"title": "LMCache KV Cache Service",
"metrics": {
"health": "OK",
"url": "http://localhost:8000",
"engine_type": "BlendEngine",
"chunk_size": 256,
"l1_capacity_gb": 60.0,
"l1_used_gb": "42.30 (70.5%)",
"eviction_policy": "LRU",
"cached_objects": 1024,
"active_sessions": 3,
"models": [
{
"model": "meta-llama/Llama-3.1-70B-Instruct",
"world_size": 4,
"gpu_ids": "0, 1, 2, 3",
"attention_backend": "vLLM non-MLA flash attention",
"gpu_kv_shape": "NL x [2, NB, BS, NH, HS]",
"gpu_kv_concrete_shape": "80 x [2, 2048, 128, 8, 128]",
"num_layers": 80,
"block_size": 128,
"hidden_dim_size": 1024,
"dtype": "torch.float16",
"is_mla": false,
"num_blocks": 2048
}
],
"l2_adapters": [
{
"type": "NixlStoreL2Adapter",
"health": "OK",
"backend": "nixl_rdma",
"stored_object_count": 512,
"pool_used": "480 / 512 (93.8%)"
}
]
}
}
GPU KV 形状缩写#
gpu_kv_shape 字段使用 GPUKVFormat 枚举中的简短名称：
缩写 |
含义 |
|---|---|
注意事项 |
num_blocks |
NL |
num_layers |
批量大小 |
块大小 |
NH |
num_heads |
HS |
head_size |
PBS |
页面缓冲区大小 (NB × BS) |
query#
query engine 子命令向引擎 API 发送一个请求并报告指标。 --prompt 支持占位符： {lmcache} 加载 lmcache/cli/documents/lmcache.txt，自定义文档可以通过 --documents NAME=PATH 传递。提示的令牌计数直接来自引擎报告的使用数据 (stream_options: {include_usage: true})。
lmcache query engine --url http://localhost:8000/v1 \
--prompt "{lmcache} Summarize LMCache usage." \
--format terminal \
--max-tokens 128
================= Query Engine =================
Model: facebook/opt-125m
Input tokens: 618
--------------- Latency Metrics ----------------
Output tokens: 9
TTFT (ms): 26.88
TPOT (ms/token): 0.91
Total latency (ms): 35.05
Throughput (tokens/s): 1100.64
================================================
ping — 存活检查#
检查 LMCache KV Cache 服务器或 vLLM 服务引擎是否可达：
# Ping the KV cache server (default: http://localhost:8080)
lmcache ping kvcache
# Ping the serving engine (default: http://localhost:8000)
lmcache ping engine --url http://localhost:8000
======= Ping KV Cache ========
Status: OK
Round trip time (ms): 3.42
==============================
选项#
标志 |
描述 |
|---|---|
|
要 ping 的目标（位置参数，必填）。 |
|
服务器 URL。默认值为 |
|
输出格式： |
|
将指标保存到文件中（格式遵循 |
|
抑制标准输出。仅返回退出代码。 |
退出代码#
代码 |
含义 |
|---|---|
|
服务器可达（HTTP 200）。 |
|
连接失败或非 200 响应。 |
kvcache — KV Cache 管理#
在运行中的 LMCache 服务器上管理 KV Cache 状态。有关完整文档，包括示例、选项和常见模式，请参见 lmcache kvcache。
快速示例：
# Clear all L1 (CPU) cache
lmcache kvcache clear --url http://localhost:8000
指标输出#
所有生成指标的命令支持两种输出格式：
终端输出#
可读的 ASCII 表：
======= Ping KV Cache ========
Status: OK
Round trip time (ms): 3.42
==============================
JSON 输出#
机器可读的输出，带有结构化的键，可以通过 ``--format json``（标准输出）或 ``--output``（文件）获得：
lmcache ping kvcache --format json
{
"title": "Ping KV Cache",
"metrics": {
"status": "OK",
"round_trip_time_ms": 3.42
}
}
终端输出使用人类可读的标签（例如，"往返时间（毫秒）"），而 JSON 输出使用机器可读的键（例如，"round_trip_time_ms"）。
添加新命令#
可以通过创建 BaseCommand 子类并注册它来添加新的 CLI 子命令。有关详细信息，请参见 扩展 CLI。