LMCache 实用指南：vLLM 推理服务如何复用 KV Cache

LMCache 把重复 prefill 转成可复用的 KV Cache——适合长 prompt、RAG 固定模板和多实例 vLLM 共享前缀的场景。

LMCache 是什么？

LMCache 解决的是大模型推理中的重复 prefill 问题：当很多请求共享长 prompt 前缀时，把临时 KV Cache 抽到可复用、可观测、可扩展的缓存层里，减少重复计算，降低 TTFT，也就是首 token 延迟。

项目与文档：

先判断是否需要 LMCache

LMCache 更适合这些场景：

prompt 很长，且多个请求共享大段前缀。
RAG 请求会反复塞入相似文档片段或固定模板。
多轮对话历史上下文很长，后续请求持续复用前文。
Agent 系统提示词、工具说明、策略文本很长。
多个 vLLM 实例需要共享缓存，而不是每个进程各算各的。
你关注 TTFT，而不只是 decode 阶段的 tokens/s。

如果请求大多很短、互相没有相同前缀，或者瓶颈主要在生成阶段，收益可能不明显。LMCache 省的是重复 prefill，不是让所有 token 都「魔法加速」。

安装

官方 Quickstart 推荐 Python 3.12 环境。

使用 uv：

uv venv --python 3.12
source .venv/bin/activate
uv pip install lmcache vllm

使用普通虚拟环境：

python -m venv .venv
source .venv/bin/activate
pip install lmcache vllm

生产环境建议固定版本，尤其要确认 vLLM、LMCache 和 connector 版本兼容，不要直接裸用最新版。

启动 LMCache 服务

先启动 LMCache：

lmcache server \
  --l1-size-gb 20 \
  --eviction-policy LRU \
  --chunk-size 16

参数含义：

--l1-size-gb 20：给本地一级缓存分配 20GB。
--eviction-policy LRU：缓存满后优先淘汰最久未使用的数据。
--chunk-size 16：演示用的小块大小，方便短 prompt 也能看到命中日志。

注意：chunk-size 16 更适合 demo。生产环境通常使用默认值，例如 256。块越小，命中粒度越细，但管理开销更高；块越大，开销较小，但短前缀不一定命中漂亮。

默认端口：

ZMQ：5555
HTTP 管理和指标：8080

启动 vLLM 并接入 LMCache

另开一个终端启动 vLLM：

vllm serve Qwen/Qwen3-8B \
  --port 8000 \
  --kv-transfer-config \
  '{"kv_connector":"LMCacheMPConnector", "kv_role":"kv_both"}'

如果使用 vLLM 0.20.0 或更新版本，官方建议可显式指定 LMCache 自带 connector：

vllm serve Qwen/Qwen3-8B \
  --port 8000 \
  --kv-transfer-config \
  '{"kv_connector":"LMCacheMPConnector", "kv_connector_module_path":"lmcache.integration.vllm.lmcache_mp_connector", "kv_role":"kv_both"}'

这样可以使用 LMCache 项目中更新的 server protocol 和修复，而不是只依赖 vLLM 内置版本。

用两次请求测试是否命中

测试缓存命中最简单的方法，是发送两个共享前缀的请求。

第一次请求：

curl http://localhost:8000/v1/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Qwen/Qwen3-8B",
    "prompt": "Qwen3 is the latest generation of large language models in Qwen series, offering a comprehensive suite of dense and mixture-of-experts",
    "max_tokens": 100,
    "temperature": 0.7
  }'

第二次保留前缀，只在后面增加内容：

curl http://localhost:8000/v1/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Qwen/Qwen3-8B",
    "prompt": "Qwen3 is the latest generation of large language models in Qwen series, offering a comprehensive suite of dense and mixture-of-experts (MoE) models",
    "max_tokens": 100,
    "temperature": 0.7
  }'

如果 LMCache 正常工作，第一次请求会看到类似 Stored ... tokens 的日志；第二次请求会看到 Retrieved ... tokens，说明共享前缀已从缓存取回。

读懂命中日志

不要只看有没有 Retrieved，还要关注：

命中了多少 tokens。
缓存从哪里取回，比如 CPU RAM、本地磁盘或远端存储。
取回耗时是否真的比重新 prefill 更划算。
是否只命中很短一段，实际收益有限。
是否因为 chunk 对齐问题，导致相似前缀没有完整命中。

判断标准要结合 prompt 长度。比如 5000 tokens 的 prompt 命中 4000 tokens，TTFT 可能明显下降；如果 200 tokens 的 prompt 只命中 32 tokens，业务体感可能很弱。

最容易吃到收益的业务

长系统提示词

企业内部助手常有角色设定、规则、工具说明、输出格式要求。只要这段内容在多次请求中一致，就适合缓存。

RAG 固定模板

RAG 不只有文档片段，通常还有固定提示模板、引用规则和回答约束。如果检索结果重复度高，或用户围绕同一批资料连续提问，LMCache 更有价值。

Agent 工具说明

Agent 经常把工具列表、调用规则、错误处理策略放入上下文。这类内容长、重复度高，是典型可复用前缀。

多实例推理服务

单个 vLLM 进程已有自己的前缀缓存，但多实例扩容后缓存容易碎片化。LMCache 独立出来后，可让多个服务实例共享缓存层。

不建议一开始追求复杂后端

LMCache 支持多种后端，例如 CPU RAM、本地磁盘、Redis/Valkey、S3 兼容对象存储、Mooncake、InfiniStore、NIXL 等。

第一次接入不建议直接上分布式存储。更稳妥的路线是：

先用本地 CPU RAM 跑通链路。
观察命中率和 TTFT 是否改善。
确认真实业务收益后，再考虑跨机器共享、持久化和远端存储。

扩展前需要评估：

缓存是否需要跨机器共享。
是否需要持久化。
网络传输成本是否会抵消缓存收益。
淘汰策略是否符合业务访问模式。

缓存层越复杂，排查成本越高。先证明业务 prompt 真的可复用，再扩大架构。

In-process 模式

如果只是本机快速试验，也可以用 In-process 模式：

LMCACHE_CHUNK_SIZE=8 \
vllm serve Qwen/Qwen3-8B \
  --port 8000 \
  --kv-transfer-config \
  '{"kv_connector":"LMCacheConnectorV1", "kv_role":"kv_both"}'

这种方式简单，但缓存跟着 vLLM 进程走。进程重启、崩溃或扩容时，独立性不如 MP 模式。它适合验证概念，不太适合作为长期生产默认结构。

上线前检查清单

接入 LMCache 前，建议做一轮小压测：

对比开启和关闭 LMCache 的 TTFT。
单独记录 prefill 延迟，而不是只看总耗时。
统计 prefix cache hit tokens 和 hit ratio。
观察 LMCache 进程内存是否稳定。
测试 vLLM 重启后缓存是否还能按预期复用。
检查高并发下 ZMQ、HTTP 指标和日志是否正常。
用真实业务 prompt 测，不要只用 demo prompt。

如果真实业务 prompt 重复度低，压测结果通常会很直接地告诉你：暂时不该上。

常见坑

把 LMCache 当成普通结果缓存

LMCache 缓的是 KV Cache，不是最终回答。它减少的是模型重新处理前缀的成本，不保证两次输出一样。

只看 tokens/s

LMCache 更直接影响 TTFT 和 prefill 成本。decode 阶段的 tokens/s 可能不会明显变化。

chunk-size 乱调

demo 中使用小 chunk 是为了方便观察命中。生产中要结合 prompt 长度、重复模式、内存和吞吐测试来调，不要照抄演示参数。

版本没对齐

vLLM、LMCache 和 connector 之间存在兼容关系。升级前要看文档和 release note，避免生产环境临时拉最新版。

没有观测指标

缓存系统没有指标就很难排查。至少应观察命中率、命中 tokens、读写耗时、缓存容量、淘汰次数和错误日志。

总结

LMCache 适合「长 prompt 重复出现」的 LLM 推理服务。它不是让模型生成更快的万能按钮，而是把重复 prefill 转成可复用的 KV Cache。

如果已经在用 vLLM，推荐入门路线是：先用 MP 模式本机跑通，再用两条共享前缀的请求确认命中，最后拿真实业务流量对比 TTFT。只有真实命中率足够高，LMCache 才值得进入生产架构。