lmcache/lmcache · 上手攻略
- 仓库：lmcache/lmcache
- 链接：https://github.com/LMCache/LMCache
- 分类：ai / llm-infra（LLM 推理基础设施）
- 作者：Jay
- 更新：2026-07-13
是什么
LMCache 是一个KV Cache 管理中间件层，专为 LLM 推理场景设计。它的核心思路是把 GPU VRAM 中转瞬即逝的 KV Cache 变成可持久化、可复用、可监控的 AI 原生存储，从而显著降低 TTFT（Time To First Token，首 token 延迟），提升多轮对话和 Agentic Workload 的吞吐量。
典型工作场景：用户问"介绍一下北京"（prefill 生成大量 KV），紧接着问"它的人口是多少"——两者的 prompt 有共同前缀，LMCache 可以在第二轮直接复用第一轮的 KV Cache，避免重复计算。
一句话总结：LLM 推理的 KV Cache 加速层，让 GPU 不重复做已经做过的事。
Stars：10483 ⭐ | 周增：+203 | 语言：Python + CUDA C++ | 许可：Apache 2.0
解决什么问题
| 痛点 | 传统做法 | LMCache 解法 |
|---|---|---|
| 多轮对话重复 prefill | 每次都从零计算 | KV Cache 复用，首 token 加速 |
| Agentic 多请求共享上下文 | 各自独立计算 | 跨请求/跨引擎复用 Cache |
| GPU VRAM 紧张 | KV Cache 被踢出后失效 | 分层卸载到 CPU RAM / 磁盘 / Redis |
| 缓存无法跨节点共享 | 每节点独立 Cache | P2P 跨节点 KV 传输（NVLink/RDMA） |
| 没有 KV 可观测性 | 黑盒推理 | 内置命中/生命周期/性能指标 |
2026 年 4 月发布的多进程（MP）架构，把 LMCache 从 vLLM 进程内嵌模式拆分为独立守护进程，支持多引擎共享同一 Cache，支持水平扩展。
快速安装
环境要求
- Linux（生产推荐）
- Python 3.9–3.13
- NVIDIA GPU（Compute Capability ≥ 7.0，即 Volta 及以后）
- CUDA 12.1+（推荐 CUDA 13.0）
- 推荐使用
uv包管理器
pip/uv 安装（CUDA 13.0，稳定版）
uv venv --python 3.12
source .venv/bin/activate
uv pip install lmcache
pip/uv 安装（CUDA 12.9，稳定版）
需从 GitHub Release 手动指定版本：
uv venv --python 3.12
source .venv/bin/activate
VERSION=0.4.3 # 替换为目标版本
uv pip install lmcache==${VERSION} \
--extra-index-url https://download.pytorch.org/whl/cu129 \
--find-links https://github.com/LMCache/LMCache/releases/expanded_assets/v${VERSION}-cu129 \
--index-strategy unsafe-best-match
⚠️
--extra-index-url https://download.pytorch.org/whl/cu129必须指定，否则 pip 可能拉错 CUDA 版本的 PyTorch。
夜间构建（Latest）
uv venv --python 3.12
source .venv/bin/activate
uv pip install lmcache --pre \
--extra-index-url https://download.pytorch.org/whl/cu130 \
--find-links https://github.com/LMCache/LMCache/releases/expanded_assets/nightly \
--index-strategy unsafe-best-match
Docker（最省事）
# CUDA 13.0 稳定版
docker pull lmcache/vllm-openai
# CUDA 12.9 稳定版
docker pull lmcache/vllm-openai:latest-cu129
源码编译
git clone https://github.com/LMCache/LMCache.git
cd LMCache
uv venv --python 3.12 && source .venv/bin/activate
uv pip install -r requirements/build.txt
uv pip install vllm # 拉取对应 CUDA 版本的 torch
uv pip install -e . --no-build-isolation
验证安装
python -c "import lmcache.c_ops"
核心用法
模式一：多进程（MP）模式（推荐生产使用）
LMCache 作为独立守护进程运行，vLLM 通过 LMCacheMPConnector 连接，支持多引擎共享 Cache。
Step 1：启动 LMCache Server
lmcache server \
--host localhost --port 5555 \
--l1-size-gb 20 --eviction-policy LRU --chunk-size 16
chunk-size 16仅用于演示；生产默认 256。
Step 2：启动 vLLM（连接 Server）
vllm serve Qwen/Qwen3-8B \
--port 8000 --kv-transfer-config \
'{"kv_connector":"LMCacheMPConnector",
"kv_role":"kv_both",
"kv_connector_extra_config": {"lmcache.mp.host": "tcp://localhost", "lmcache.mp.port": 5555}}'
vLLM ≥ 0.20.0 推荐显式指定
kv_connector_module_path: "lmcache.integration.vllm.lmcache_mp_connector"以使用 LMCache 官方最新连接器实现（而非 vLLM 内置的旧版本）。
Step 3：验证效果（发送两个有共同前缀的请求）
# 第一个请求（Cache Miss → 写入）
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}'
# 第二个请求（共同前缀命中 Cache，仅计算新尾）
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}'
模式二：进程内（In-process）模式（快速实验）
LMCache 直接内嵌到 vLLM 进程，无需独立 Server：
LMCACHE_CHUNK_SIZE=8 \
vllm serve Qwen/Qwen3-8B \
--port 8000 --kv-transfer-config \
'{"kv_connector":"LMCacheConnectorV1", "kv_role":"kv_both"}'
或者更简化的方式：
vllm serve <MODEL_NAME> \
--kv-offloading-backend lmcache \
--kv-offloading-size <SIZE_IN_GB> \
--disable-hybrid-kv-cache-manager
⚠️
--disable-hybrid-kv-cache-manager是进程内模式的必选参数，否则配置不生效。
支持的后端存储
| 存储类型 | 说明 |
|---|---|
| CPU RAM（L1） | 默认，推荐 20–50 GB |
| 本地 SSD | 比 RAM 慢但容量大 |
| Redis / Valkey | 分布式多节点共享 |
| Mooncake | 高性能 KV Transfer |
| InfiniStore | 高速网络存储 |
| S3 兼容对象存储 | 大规模冷数据 |
| NIXL / GDS | PD 分离场景 |
NIXL 支持（PD 分离 + P2P KV 传输）
uv pip install lmcache[nixl]
用于将 KV Cache 从 Prefill Worker 通过 NVLink/RDMA/TCP 传输到 Decode Worker。
典型适用场景
| 场景 | 效果 |
|---|---|
| 多轮 Agentic 对话 | 多请求共享相同 system prompt prefix，TTFT 可降低 30–70% |
| RAG 增强生成 | 相同文档上下文多 Query 复用 KV，避免重复 embedding |
| 长上下文多 Query | 长文档首次处理后，后续 Query 直接复用 |
| MoE 模型推理 | 2026-04 新 MP 架构使 MoE 推理性能提升 10 倍 |
| 多模型服务 | MP 模式下同一 Cache 可服务多个 vLLM 实例 |
| 跨节点分布式推理 | P2P KV 传输通过 NVLink/RDMA，延迟极低 |
坑与注意
- CUDA 版本必须匹配：安装前确认 PyTorch 和 LMCache 的 CUDA 版本一致；
cu129和cu130是两个独立生态，混用会导致 undefined symbol 错误。 --disable-hybrid-kv-cache-manager进程内模式必加：不指定会导致 KV Cache 不走 LMCache，Cache 永远 miss。- MP 模式端口占用：LMCache Server 默认 ZMQ 端口 5555、HTTP 管理端口 8080，确保未被占用。
- vLLM 版本兼容：LMCache 官方连接器在 vLLM ≥ 0.20.0 推荐显式指定
kv_connector_module_path，否则走 vLLM 内置旧版可能缺少新特性。 - ROCm（AMD）需要特殊编译：
BUILD_WITH_HIP=1，PYTORCH_ROCM_ARCH需匹配目标 GPU（gfx942=MI300X/MI325X，gfx950=MI350X/MI355X）。 - chunk-size 影响 Cache 粒度：chunk 越小粒度越细但管理开销大；生产默认 256 已是经验最优值。
- AMD MI300X Agentic 场景：官方 2026-05 有专项 Benchmark，建议参考 博客 调参。
与同类对比
| 项目 | 定位 | LMCache 优势 |
|---|---|---|
| vLLM 内置 PagedAttention | GPU 内 KV Cache 分页管理 | LMCache 可跨请求/跨引擎/跨节点复用，且支持分层卸载 |
| TorchServe | 通用模型服务 | LMCache 专注 KV Cache 复用，更轻量 |
| TensorRT-LLM | 高性能推理引擎 | LMCache 与 TRT-LLM 正交，可叠加使用 |
| Redis KV Cache（朴素方案） | 简单 KV 缓存 | LMCache 有 KV 语义理解，支持非前缀位置的 CacheBlend 质量恢复 |
| Mooncake | 高性能 KV Transfer | LMCache 是上层管理框架，Mooncake 是底层传输实现，可集成 |
| NVIDIA Dynamo | LLM 推理优化框架 | LMCache 已集成进 Dynamo（2025-09），属于官方推荐组合 |
一句话推荐结论
如果你在生产环境跑 LLM 推理（尤其是多轮对话、RAG、Agentic 场景），LMCache 是目前最成熟、集成最广的 KV Cache 复用方案——NVIDIA Dynamo 官方集成、PyTorch 生态成员、多硬件（NVIDIA/AMD/Intel）支持，上手门槛低，值得直接上生产。