LMCache 快速上手指南在 vLLM、SGLang 与 TensorRT-LLM 中端到端启用 KV Cache 复用【免费下载链接】LMCacheLMCache: Supercharge Your LLM with the Fastest KV Cache Layer项目地址: https://gitcode.com/GitHub_Trending/lm/LMCacheLMCache 是面向 LLM 推理的 KV Cache 加速层核心能力是把 GPU 上被逐出的 KV 块卸载到 CPU 内存L1乃至本地磁盘、远程存储L2并在后续请求中按前缀命中复用从而显著降低 TTFT首 token 延迟。本指南以 docs/source/getting_started/quickstart.rst 为主体完整演示如何在 vLLM、SGLang 与 TensorRT-LLM 三大推理引擎上分别接入 LMCache从安装、启动、配置到发送共享前缀请求验证缓存命中的全过程并补充仓库源码与配置文档中的底层细节。读完本文你将掌握 LMCache 的进程内in-process与多进程MP两种部署模式能够独立跑通并验证 KV Cache 的存储与复用效果。部署模式总览LMCache 为 vLLM 提供两种部署模式两者通过kv-transfer-config中的连接器connector区分多进程MP模式推荐LMCache 以独立服务lmcache server运行vLLM 通过LMCacheMPConnector挂载。该模式扩展性更好暴露管理/可观测性端点并支持多个引擎实例共享同一份缓存。进程内in-process模式LMCache 通过LMCacheConnectorV1内嵌在 vLLM 进程中运行。单条命令即可启动适合单机快速实验。下图直观对比了两种部署模式的拓扑差异进程内模式下每个 Serving Engine 各自携带一个 KV Library多进程模式下多个 Serving Engine 共享一个集中式 LMCache ServervLLM安装与两种部署模式安装 LMCache建议使用uv创建 Python 3.12 虚拟环境并安装 LMCache 与 vLLMuv venv --python 3.12 source .venv/bin/activate uv pip install lmcache vllmMP 模式推荐第一步启动 LMCache 服务器。--host/--port设置 vLLM 连接的 ZMQ 地址下面显式写出以便两条命令对齐这两个值同时也是默认值# chunk-size 16 仅为演示值让短 prompt 也能产生可见的缓存流量 # 生产环境请使用默认值256。 lmcache server \ --host localhost --port 5555 \ --l1-size-gb 20 --eviction-policy LRU --chunk-size 16ZMQ 端口--port默认5555接受来自 vLLM 的连接HTTP 前端默认8080提供管理与指标端点。lmcache server的完整参数列表见 docs/source/mp/configuration.rst。第二步在另一个终端用 MP 连接器启动 vLLM。通过kv_connector_extra_config中的lmcache.mp.host/lmcache.mp.port指向上述服务器。host 可带 ZMQ 传输前缀如tcp://裸的host/host:port也会被自动归一化为tcp://支持的端点协议与传输选择行为见 docs/source/mp/request_transport.rstvllm serve Qwen/Qwen3-8B \ --port 8000 --kv-transfer-config \ {kv_connector:LMCacheMPConnector, kv_role:kv_both, kv_connector_extra_config: {lmcache.mp.host: localhost, lmcache.mp.port: 5555}}LMCacheMPConnector解析到哪个实现取决于你的 vLLM 版本vLLM 0.20.0kv_connector:LMCacheMPConnector始终解析为 vLLM 内置的vllm.distributed.kv_transfer.kv_connector.v1.LMCacheMPConnector无法重定向到 LMCache 自带实现。vLLM 0.20.0默认仍使用 vLLM 内置连接器但可通过kv_connector_module_path显式启用 LMCache 自带实现lmcache/integration/vllm/lmcache_mp_connector.pyvllm 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 自带的连接器跟踪最新 LMCache 服务端协议功能修复与特性迭代快于 vLLM 内置的 vendored 版本。只要使用 vLLM 0.20.0 及以上都建议优先使用它。第三步验证。打开新终端发送两条共享前缀的请求第一条请求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 }预期日志—— MP 模式下store/retrieve 日志来自独立的lmcache server进程每个 chunk 一条。第一条请求时缓存为空所有对齐的 chunk 被卸载offload[2026-04-22 19:49:56,316] LMCache INFO: Stored 16 tokens in 0.023 seconds (server.py:390:lmcache.v1.multiprocess.server) [2026-04-22 19:49:56,555] LMCache INFO: Stored 16 tokens in 0.005 seconds (server.py:390:lmcache.v1.multiprocess.server) [2026-04-22 19:49:56,691] LMCache INFO: Stored 16 tokens in 0.005 seconds (server.py:390:lmcache.v1.multiprocess.server) ...第二条请求时共享前缀从 CPU 内存命中取回只有新增的尾部被存储[2026-04-22 19:50:04,686] LMCache INFO: Retrieved 16 tokens in 0.003 seconds (server.py:573:lmcache.v1.multiprocess.server) [2026-04-22 19:50:04,832] LMCache INFO: Stored 16 tokens in 0.005 seconds (server.py:390:lmcache.v1.multiprocess.server) [2026-04-22 19:50:04,968] LMCache INFO: Stored 16 tokens in 0.005 seconds (server.py:390:lmcache.v1.multiprocess.server) ...这些日志由 lmcache/v1/multiprocess/server.py 中的存储管理模块输出。请求级统计命中率、传输字节数可参考 docs/source/mp/observability/index.rst。进程内in-process模式将 LMCache 嵌入引擎进程启动 vLLM# 这里的 chunk size 仅用于演示后续请使用默认值256 LMCACHE_CHUNK_SIZE8 \ vllm serve Qwen/Qwen3-8B \ --port 8000 --kv-transfer-config \ {kv_connector:LMCacheConnectorV1, kv_role:kv_both}如需进一步定制可创建配置文件全部选项见 docs/source/api_reference/configurations.rst。更简单的替代命令vllm serve MODEL NAME \ --kv-offloading-backend lmcache \ --kv-offloading-size SIZE IN GB \ --disable-hybrid-kv-cache-manager--disable-hybrid-kv-cache-manager标志是必须的。所有 docs/source/api_reference/configurations.rst 中的配置项依然适用。验证发送与 MP 模式相同的两条共享前缀 curl 请求后第一条请求—— prompt 被卸载到 LMCache进程内模式下日志内联在 vLLM 引擎核心输出中(EngineCore_DP0 pid458469) [2025-09-30 00:08:43,982] LMCache INFO: Stored 31 out of total 31 tokens. size: 0.0040 gb, cost 1.95 ms, throughput: 1.98 GB/s; offload_time: 1.88 ms, put_time: 0.07 ms第二条请求—— 命中缓存并存储新的尾部Reqid: cmpl-6709d8795d3c4464b01999c9f3fffede-0, Total tokens 32, LMCache hit tokens: 24, need to load: 8 (EngineCore_DP0 pid494270) [2025-09-30 01:12:36,502] LMCache INFO: Retrieved 8 out of 24 required tokens (from 32 total tokens). size: 0.0011 gb, cost 0.55 ms, throughput: 1.98 GB/s; (EngineCore_DP0 pid494270) [2025-09-30 01:12:36,509] LMCache INFO: Storing KV cache for 8 out of 32 tokens (skip_leading_tokens24) (EngineCore_DP0 pid494270) [2025-09-30 01:12:36,510] LMCache INFO: Stored 8 out of total 8 tokens. size: 0.0011 gb, cost 0.43 ms, throughput: 2.57 GB/s; offload_time: 0.40 ms, put_time: 0.03 ms逐项解读这批日志帮助理解 LMCache 的按块哈希与 vLLM 自动前缀缓存的协同机制Total tokens 32新 prompt 分词后共 32 个 token。LMCache hit tokens: 24第一条请求存储了 31 个 token其中 24 个 token3 个完整的 8-token chunk在缓存中命中。Need to load: 8vLLM 自动前缀缓存使用 block size 1616 个 token 已在 GPU 内存中因此 LMCache 只需加载 24 − 16 8 个。为什么命中 24 个而不是 31 个LMCache 对每 8 个 token 做哈希8、16、24、31只匹配按页对齐的 chunk因此使用 24-token 的哈希。又存储了 8 个 token新增的 8 个 token 构成完整 chunk被存储以备后续复用。该日志由 lmcache/integration/vllm/lmcache_connector_v1.py 对应的引擎适配链路产生skip_leading_tokens即命中的前缀长度。SGLang通过 MP 模式集成SGLang 集成现在默认使用 MP多进程模式完整的当前配置说明见 examples/sgl_integration/README.md。安装 SGLanguv venv --python 3.12 source .venv/bin/activate uv pip install --prereleaseallow lmcache sglang用 LMCache 启动 SGLangcat lmc_config.yaml EOF chunk_size: 8 # 仅演示用生产环境使用 256 local_cpu: true use_layerwise: true max_local_cpu_size: 10 # GB EOF export LMCACHE_CONFIG_FILE$PWD/lmc_config.yaml python -m sglang.launch_server \ --model-path Qwen/Qwen3-8B \ --host 0.0.0.0 \ --port 30000 \ --enable-lmcacheLMCache 侧通过配置文件定制完整参数见 docs/source/api_reference/configurations.rst。验证—— 发送两条共享前缀的 chat 请求第一条请求curl http://localhost:30000/v1/chat/completions \ -H Content-Type: application/json \ -d { model: Qwen/Qwen3-8B, messages: [{role: user, content: 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:30000/v1/chat/completions \ -H Content-Type: application/json \ -d { model: Qwen/Qwen3-8B, messages: [{role: user, content: 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 }预期日志—— 第一条请求prompt 与生成 token 都被存储Prefill batch, #new-seq: 1, #new-token: 35, #cached-token: 0, token usage: 0.00, #running-req: 0, #queue-req: 0, Decode batch, #running-req: 1, #token: 74, token usage: 0.00, cuda graph: True, gen throughput (token/s): 1.63, #queue-req: 0, Decode batch, #running-req: 1, #token: 114, token usage: 0.00, cuda graph: True, gen throughput (token/s): 87.95, #queue-req: 0, LMCache INFO: Stored 128 out of total 135 tokens. size: 0.0195 GB, cost 12.8890 ms, throughput: 1.5153 GB/s (cache_engine.py:623:lmcache.v1.cache_engine)第二条请求Radix Cache 与 LMCache 共享前缀仅存储新增部分Prefill batch, #new-seq: 1, #new-token: 10, #cached-token: 30, token usage: 0.00, #running-req: 0, #queue-req: 0, Decode batch, #running-req: 1, #token: 64, token usage: 0.00, cuda graph: True, gen throughput (token/s): 8.29, #queue-req: 0, Decode batch, #running-req: 1, #token: 104, token usage: 0.00, cuda graph: True, gen throughput (token/s): 87.95, #queue-req: 0, Decode batch, #running-req: 1, #token: 144, token usage: 0.00, cuda graph: True, gen throughput (token/s): 87.89, #queue-req: 0, LMCache INFO: Stored 112 out of total 140 tokens. size: 0.0171 GB, cost 11.1986 ms, throughput: 1.5261 GB/s (cache_engine.py:623:lmcache.v1.cache_engine)逐项解读Total tokens 140SGLang 将 prefill 与 decode 的 KV cache 一起存储因此 total 40 prompt 100 generated 140 tokens。Cached tokens: 30SGLang 的 Radix Attention Cache 复用了第一条请求的 30 个 token。LMCache hit tokens: 24LMCache 检测到第一条请求存储的 24 个 token3 个完整 8-token chunk。由于 Radix Cache 已在 GPU 内存提供 30 个 token这 24 个 token 既无需从 LMCache 加载也无需重复存储。New tokens: 10仅 10 个 prompt token 需要 prefill 计算40 − 30 10。Stored 112 out of 14024 个 token3 个完整 chunk已在 LMCache 中并被跳过。剩余 116 个 token 中112 个14 个完整 8-token chunk被存储。TensorRT-LLM通过 KV Cache Connector API 集成该集成依赖 NVIDIA/TensorRT-LLM 的 connector preset registry 及配套的 LMCache 适配器两者尚未进入稳定版本。在稳定版发布前需要从源码安装uv venv --python 3.12 source .venv/bin/activate # 从源码安装 LMCachedev 分支 uv pip install githttps://github.com/LMCache/LMCache.gitdev # 从源码安装 TensorRT-LLM —— 参考 NVIDIA 官方构建指南两者进入稳定版后安装命令将是uv pip install lmcache tensorrt_llmversion \ --extra-index-url https://pypi.nvidia.comLMCache 通过 TRT-LLM 的KV Cache ConnectorAPI 集成支持两种部署模式进程内模式connector: lmcacheLMCache 以单例运行在 TRT-LLM 进程内。设置最简单无需管理额外服务。MP 模式connector: lmcache-mpLMCache 作为独立服务器运行同一节点上的多个 TRT-LLM worker 可以共享缓存且缓存能在 TRT-LLM 崩溃后幸存。进程内模式通过环境变量配置 LMCacheexport PYTHONHASHSEED0 # 必须设置 —— chunk 哈希依赖稳定的 hash() export LMCACHE_CHUNK_SIZE256 export LMCACHE_LOCAL_CPUTrue export LMCACHE_MAX_LOCAL_CPU_SIZE2.0 # GiB构建 TRT-LLMLLM对象并指定connector: lmcachefrom tensorrt_llm import LLM, SamplingParams from tensorrt_llm.llmapi.llm_args import ( KvCacheConfig, KvCacheConnectorConfig, ) llm LLM( modelQwen/Qwen2-1.5B-Instruct, backendpytorch, kv_cache_configKvCacheConfig(enable_block_reuseTrue), kv_connector_configKvCacheConnectorConfig(connectorlmcache), ) out llm.generate([Your prompt here], SamplingParams(max_tokens64)) print(out[0].outputs[0].text)MP 模式PYTHONHASHSEED0必须在两个终端中都设置 —— chunk 哈希依赖稳定的hash()服务器与客户端必须使用相同的种子export PYTHONHASHSEED0 lmcache server \ --l1-size-gb 10 --eviction-policy LRU --chunk-size 256在另一个终端通过server_url将 TRT-LLM 指向该服务器export PYTHONHASHSEED0 python run_trtllm.py其中run_trtllm.py内容如下from tensorrt_llm import LLM, SamplingParams from tensorrt_llm.llmapi.llm_args import ( KvCacheConfig, KvCacheConnectorConfig, ) llm LLM( modelQwen/Qwen2-1.5B-Instruct, backendpytorch, kv_cache_configKvCacheConfig(enable_block_reuseTrue), kv_connector_configKvCacheConnectorConfig( connectorlmcache-mp, server_urltcp://localhost:5555, ), ) out llm.generate([Your prompt here], SamplingParams(max_tokens64)) print(out[0].outputs[0].text)TRT-LLM 适配器lmcache/integration/tensorrt_llm/tensorrt_adapter.py与 vLLM 适配器一样读取LMCacheEngineConfig设置了LMCACHE_CONFIG_FILE则读 YAML 文件否则读取各个LMCACHE_*环境变量。全部选项见 docs/source/api_reference/configurations.rst。至此三个引擎都已启用 LMCache 的 KV Cache 存储与复用。更多 MP 服务器选项上文 vLLM 的 MP 示例在本地默认端口运行lmcache server常见变体如下。自定义端口或远程主机—— 连接器默认连接localhost:5555。改用其他端口或另一台主机上的服务器时在kv_connector_extra_config中传入lmcache.mp.host/lmcache.mp.portvllm serve Qwen/Qwen3-8B --kv-transfer-config \ {kv_connector:LMCacheMPConnector, kv_role:kv_both, kv_connector_extra_config: {lmcache.mp.host: tcp://10.0.0.1, lmcache.mp.port: 6555}}CPU-only无 GPU—— 服务器以StubCPUDevice运行并通过 POSIX 共享内存与 vLLM 共享 KV 张量。正常启动lmcache server后在 vLLM 侧设置lmcache.mp.mp_transfer_modelmcache_driven以启用零拷贝 SHM 句柄路径默认的auto路由将非 CUDA 设备映射到engine_driven—— 一种 worker 侧 gather/scatter 拷贝路径服务器只有在以--supported-transfer-mode engine_driven或auto启动时才会加载。Docker 部署—— 见 docs/source/production/docker_deployment.rst。HTTP 管理端点health、clear-cache、status—— 见 docs/source/mp/http_api.rst。关键配置速查MP 服务器核心参数以下参数来自 lmcache/v1/multiprocess/config.py 与 lmcache/v1/distributed/config.py完整清单见 docs/source/mp/configuration.rst参数默认值说明--host/--portlocalhost/5555ZMQ 服务器绑定地址vLLM 等引擎经此前缀连接--http-host/--http-port0.0.0.0/8080HTTPFastAPI/uvicorn前端提供管理与指标端点--chunk-size256KV 缓存操作的分块大小token 数--l1-size-gb必填L1 层容量GB默认为钉扎 DRAM 大小--eviction-policy必填逐出策略LRU、IsolatedLRU、noopnoop用于纯写缓冲模式--eviction-trigger-watermark/--eviction-ratio0.8/0.2触发逐出的内存使用率阈值与逐出比例--hash-algorithmblake3token 级操作哈希算法builtin、sha256_cbor、blake3--max-workers1基础工作线程数GPU 亲和池与 CPU 池的默认值--max-gpu-workers继承--max-workersGPU 亲和池STORE/RETRIEVE同实例请求固定分发到同一线程消除 GPU 传输锁竞争--max-cpu-workers继承--max-workers普通 CPU 池LOOKUP 等--supported-transfer-modelmcache_drivenlmcache_driven服务端驱动支持 CUDA IPC 与 CPU SHM、engine_driven非 GPU PREPARE/COMMIT 路径、auto两者皆载--instance-id未设置随机 UUID v4服务器稳定身份用作协调器成员键并投影到 OTelservice.instance.id--l2-adapter可重复配置 L2 适配器nixl_store、fs、mooncake_store、aerospike、s3等按出现顺序构成级联--prometheus-port9090Prometheus/metrics端点端口一个完整的服务器示例含 L2 适配器与可观测性配置lmcache server \ --host 0.0.0.0 \ --port 6555 \ --chunk-size 512 \ --max-workers 4 \ --max-gpu-workers 2 \ --hash-algorithm blake3 \ --l1-size-gb 100 \ --l1-use-lazy \ --l1-init-size-gb 20 \ --eviction-policy noop \ --l2-store-policy skip_l1 \ --l2-prefetch-max-in-flight 8 \ --l2-adapter {type: nixl_store, backend: POSIX, backend_params: {file_path: /data/lmcache/l2, use_direct_io: false}, pool_size: 64} \ --prometheus-port 9090 \ --enable-tracing \ --otlp-endpoint http://localhost:4317vLLM 客户端连接配置vLLM 侧通过kv_connector_extra_config指定 LMCache 服务器地址lmcache.mp.前缀的键是连接器专属配置。lmcache.mp.host上的tcp://前缀可省略裸 host 会被连接器归一化vllm serve Qwen/Qwen3-14B \ --kv-transfer-config \ {kv_connector:LMCacheMPConnector, kv_role:kv_both, kv_connector_extra_config: {lmcache.mp.host: 127.0.0.1, lmcache.mp.port: 6000}}其他常用连接器键完整列表见 docs/source/mp/configuration.rstlmcache.mp.server_urls多服务器部署的 URL 列表逗号分隔设置后优先于host/portvLLM 世界大小必须能被服务器数量整除且目前仅支持张量并行。lmcache.mp.mq_timeout默认300.0秒阻塞式消息队列请求超时。lmcache.mp.heartbeat_interval默认10.0秒连接器向服务器发送心跳的间隔。lmcache.mp.eager_prefetch默认false请求进入 vLLM 等待队列时即提交 LMCache lookup让 L2→L1 的 KV 预取与调度队列等待重叠。lmcache.mp.lazy_offload默认false延迟 store 操作并按 FIFO 批量提交已完成的请求。lmcache.mp.mp_transfer_mode默认autoworker→server 传输上下文路由模式auto/lmcache_driven/engine_driven。通用配置方式进程内模式进程内模式支持两种配置来源详见 docs/source/api_reference/configurations.rst配置文件YAML推荐或 JSON 文件通过LMCACHE_CONFIG_FILE环境变量指定路径。环境变量以LMCACHE_前缀命名的环境变量如LMCACHE_CHUNK_SIZE、LMCACHE_LOCAL_CPU、LMCACHE_MAX_LOCAL_CPU_SIZE、LMCACHE_LOCAL_DISK、LMCACHE_REMOTE_URL、LMCACHE_CACHE_POLICY等。注意配置文件存在时环境变量配置将被忽略。核心通用配置项速查YAML 配置名环境变量说明chunk_sizeLMCACHE_CHUNK_SIZE缓存分块大小默认256local_cpuLMCACHE_LOCAL_CPU是否启用 CPU 缓存默认truemax_local_cpu_sizeLMCACHE_MAX_LOCAL_CPU_SIZECPU 缓存上限GB默认5.0local_diskLMCACHE_LOCAL_DISK本地磁盘缓存目录路径可逗号分隔多个max_local_disk_sizeLMCACHE_MAX_LOCAL_DISK_SIZE磁盘缓存上限GB默认0.0remote_urlLMCACHE_REMOTE_URL远端存储 URL格式protocol://host:portremote_serdeLMCACHE_REMOTE_SERDE序列化格式naive或cachegen默认naivesave_decode_cacheLMCACHE_SAVE_DECODE_CACHE是否存储 decode 阶段的 KV cache默认falseuse_layerwiseLMCACHE_USE_LAYERWISE是否启用 layerwise 流水线默认falsecache_policyLMCACHE_CACHE_POLICY逐出策略LRU、LFU、FIFO默认LRUenable_p2pLMCACHE_ENABLE_P2P是否启用 P2P 共享默认falseenable_pdLMCACHE_ENABLE_PD是否启用 Prefill-Decode 分离默认false验证与基准测试跑通基本流程后可以用 docs/source/getting_started/benchmarking.rst 中的lmcache bench engine工作负载做对比验证对同一套long-doc-qa基准分别跑纯 vLLM与vLLM LMCache两个环境比较 TTFT 与耗时。基准配置可导出为 JSON 文件并跨环境重放保证对比公平。下一步性能测试参考 docs/source/getting_started/benchmarking.rst 用更全面的示例体验 LMCache 的性能收益。生产部署使用 Docker 或 Kubernetes 部署并配置可观测性与调优 —— 见 docs/source/mp/deployment.rst。进阶主题多引擎共享缓存见 examples/kv_cache_reuse/share_across_engines/README.mdKV Cache 卸载与在线会话见 docs/source/getting_started/quickstart/offload_kv_cache.rst 与 docs/source/getting_started/quickstart/share_kv_cache.rst。【免费下载链接】LMCacheLMCache: Supercharge Your LLM with the Fastest KV Cache Layer项目地址: https://gitcode.com/GitHub_Trending/lm/LMCache创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 LMCache 快速上手指南：在 vLLM、SGLang 与 TensorRT-LLM 中端到端启用 KV Cache 复用
LMCache 快速上手指南在 vLLM、SGLang 与 TensorRT-LLM 中端到端启用 KV Cache 复用【免费下载链接】LMCacheLMCache: Supercharge Your LLM with the Fastest KV Cache Layer项目地址: https://gitcode.com/GitHub_Trending/lm/LMCacheLMCache 是面向 LLM 推理的 KV Cache 加速层核心能力是把 GPU 上被逐出的 KV 块卸载到 CPU 内存L1乃至本地磁盘、远程存储L2并在后续请求中按前缀命中复用从而显著降低 TTFT首 token 延迟。本指南以 docs/source/getting_started/quickstart.rst 为主体完整演示如何在 vLLM、SGLang 与 TensorRT-LLM 三大推理引擎上分别接入 LMCache从安装、启动、配置到发送共享前缀请求验证缓存命中的全过程并补充仓库源码与配置文档中的底层细节。读完本文你将掌握 LMCache 的进程内in-process与多进程MP两种部署模式能够独立跑通并验证 KV Cache 的存储与复用效果。部署模式总览LMCache 为 vLLM 提供两种部署模式两者通过kv-transfer-config中的连接器connector区分多进程MP模式推荐LMCache 以独立服务lmcache server运行vLLM 通过LMCacheMPConnector挂载。该模式扩展性更好暴露管理/可观测性端点并支持多个引擎实例共享同一份缓存。进程内in-process模式LMCache 通过LMCacheConnectorV1内嵌在 vLLM 进程中运行。单条命令即可启动适合单机快速实验。下图直观对比了两种部署模式的拓扑差异进程内模式下每个 Serving Engine 各自携带一个 KV Library多进程模式下多个 Serving Engine 共享一个集中式 LMCache ServervLLM安装与两种部署模式安装 LMCache建议使用uv创建 Python 3.12 虚拟环境并安装 LMCache 与 vLLMuv venv --python 3.12 source .venv/bin/activate uv pip install lmcache vllmMP 模式推荐第一步启动 LMCache 服务器。--host/--port设置 vLLM 连接的 ZMQ 地址下面显式写出以便两条命令对齐这两个值同时也是默认值# chunk-size 16 仅为演示值让短 prompt 也能产生可见的缓存流量 # 生产环境请使用默认值256。 lmcache server \ --host localhost --port 5555 \ --l1-size-gb 20 --eviction-policy LRU --chunk-size 16ZMQ 端口--port默认5555接受来自 vLLM 的连接HTTP 前端默认8080提供管理与指标端点。lmcache server的完整参数列表见 docs/source/mp/configuration.rst。第二步在另一个终端用 MP 连接器启动 vLLM。通过kv_connector_extra_config中的lmcache.mp.host/lmcache.mp.port指向上述服务器。host 可带 ZMQ 传输前缀如tcp://裸的host/host:port也会被自动归一化为tcp://支持的端点协议与传输选择行为见 docs/source/mp/request_transport.rstvllm serve Qwen/Qwen3-8B \ --port 8000 --kv-transfer-config \ {kv_connector:LMCacheMPConnector, kv_role:kv_both, kv_connector_extra_config: {lmcache.mp.host: localhost, lmcache.mp.port: 5555}}LMCacheMPConnector解析到哪个实现取决于你的 vLLM 版本vLLM 0.20.0kv_connector:LMCacheMPConnector始终解析为 vLLM 内置的vllm.distributed.kv_transfer.kv_connector.v1.LMCacheMPConnector无法重定向到 LMCache 自带实现。vLLM 0.20.0默认仍使用 vLLM 内置连接器但可通过kv_connector_module_path显式启用 LMCache 自带实现lmcache/integration/vllm/lmcache_mp_connector.pyvllm 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 自带的连接器跟踪最新 LMCache 服务端协议功能修复与特性迭代快于 vLLM 内置的 vendored 版本。只要使用 vLLM 0.20.0 及以上都建议优先使用它。第三步验证。打开新终端发送两条共享前缀的请求第一条请求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 }预期日志—— MP 模式下store/retrieve 日志来自独立的lmcache server进程每个 chunk 一条。第一条请求时缓存为空所有对齐的 chunk 被卸载offload[2026-04-22 19:49:56,316] LMCache INFO: Stored 16 tokens in 0.023 seconds (server.py:390:lmcache.v1.multiprocess.server) [2026-04-22 19:49:56,555] LMCache INFO: Stored 16 tokens in 0.005 seconds (server.py:390:lmcache.v1.multiprocess.server) [2026-04-22 19:49:56,691] LMCache INFO: Stored 16 tokens in 0.005 seconds (server.py:390:lmcache.v1.multiprocess.server) ...第二条请求时共享前缀从 CPU 内存命中取回只有新增的尾部被存储[2026-04-22 19:50:04,686] LMCache INFO: Retrieved 16 tokens in 0.003 seconds (server.py:573:lmcache.v1.multiprocess.server) [2026-04-22 19:50:04,832] LMCache INFO: Stored 16 tokens in 0.005 seconds (server.py:390:lmcache.v1.multiprocess.server) [2026-04-22 19:50:04,968] LMCache INFO: Stored 16 tokens in 0.005 seconds (server.py:390:lmcache.v1.multiprocess.server) ...这些日志由 lmcache/v1/multiprocess/server.py 中的存储管理模块输出。请求级统计命中率、传输字节数可参考 docs/source/mp/observability/index.rst。进程内in-process模式将 LMCache 嵌入引擎进程启动 vLLM# 这里的 chunk size 仅用于演示后续请使用默认值256 LMCACHE_CHUNK_SIZE8 \ vllm serve Qwen/Qwen3-8B \ --port 8000 --kv-transfer-config \ {kv_connector:LMCacheConnectorV1, kv_role:kv_both}如需进一步定制可创建配置文件全部选项见 docs/source/api_reference/configurations.rst。更简单的替代命令vllm serve MODEL NAME \ --kv-offloading-backend lmcache \ --kv-offloading-size SIZE IN GB \ --disable-hybrid-kv-cache-manager--disable-hybrid-kv-cache-manager标志是必须的。所有 docs/source/api_reference/configurations.rst 中的配置项依然适用。验证发送与 MP 模式相同的两条共享前缀 curl 请求后第一条请求—— prompt 被卸载到 LMCache进程内模式下日志内联在 vLLM 引擎核心输出中(EngineCore_DP0 pid458469) [2025-09-30 00:08:43,982] LMCache INFO: Stored 31 out of total 31 tokens. size: 0.0040 gb, cost 1.95 ms, throughput: 1.98 GB/s; offload_time: 1.88 ms, put_time: 0.07 ms第二条请求—— 命中缓存并存储新的尾部Reqid: cmpl-6709d8795d3c4464b01999c9f3fffede-0, Total tokens 32, LMCache hit tokens: 24, need to load: 8 (EngineCore_DP0 pid494270) [2025-09-30 01:12:36,502] LMCache INFO: Retrieved 8 out of 24 required tokens (from 32 total tokens). size: 0.0011 gb, cost 0.55 ms, throughput: 1.98 GB/s; (EngineCore_DP0 pid494270) [2025-09-30 01:12:36,509] LMCache INFO: Storing KV cache for 8 out of 32 tokens (skip_leading_tokens24) (EngineCore_DP0 pid494270) [2025-09-30 01:12:36,510] LMCache INFO: Stored 8 out of total 8 tokens. size: 0.0011 gb, cost 0.43 ms, throughput: 2.57 GB/s; offload_time: 0.40 ms, put_time: 0.03 ms逐项解读这批日志帮助理解 LMCache 的按块哈希与 vLLM 自动前缀缓存的协同机制Total tokens 32新 prompt 分词后共 32 个 token。LMCache hit tokens: 24第一条请求存储了 31 个 token其中 24 个 token3 个完整的 8-token chunk在缓存中命中。Need to load: 8vLLM 自动前缀缓存使用 block size 1616 个 token 已在 GPU 内存中因此 LMCache 只需加载 24 − 16 8 个。为什么命中 24 个而不是 31 个LMCache 对每 8 个 token 做哈希8、16、24、31只匹配按页对齐的 chunk因此使用 24-token 的哈希。又存储了 8 个 token新增的 8 个 token 构成完整 chunk被存储以备后续复用。该日志由 lmcache/integration/vllm/lmcache_connector_v1.py 对应的引擎适配链路产生skip_leading_tokens即命中的前缀长度。SGLang通过 MP 模式集成SGLang 集成现在默认使用 MP多进程模式完整的当前配置说明见 examples/sgl_integration/README.md。安装 SGLanguv venv --python 3.12 source .venv/bin/activate uv pip install --prereleaseallow lmcache sglang用 LMCache 启动 SGLangcat lmc_config.yaml EOF chunk_size: 8 # 仅演示用生产环境使用 256 local_cpu: true use_layerwise: true max_local_cpu_size: 10 # GB EOF export LMCACHE_CONFIG_FILE$PWD/lmc_config.yaml python -m sglang.launch_server \ --model-path Qwen/Qwen3-8B \ --host 0.0.0.0 \ --port 30000 \ --enable-lmcacheLMCache 侧通过配置文件定制完整参数见 docs/source/api_reference/configurations.rst。验证—— 发送两条共享前缀的 chat 请求第一条请求curl http://localhost:30000/v1/chat/completions \ -H Content-Type: application/json \ -d { model: Qwen/Qwen3-8B, messages: [{role: user, content: 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:30000/v1/chat/completions \ -H Content-Type: application/json \ -d { model: Qwen/Qwen3-8B, messages: [{role: user, content: 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 }预期日志—— 第一条请求prompt 与生成 token 都被存储Prefill batch, #new-seq: 1, #new-token: 35, #cached-token: 0, token usage: 0.00, #running-req: 0, #queue-req: 0, Decode batch, #running-req: 1, #token: 74, token usage: 0.00, cuda graph: True, gen throughput (token/s): 1.63, #queue-req: 0, Decode batch, #running-req: 1, #token: 114, token usage: 0.00, cuda graph: True, gen throughput (token/s): 87.95, #queue-req: 0, LMCache INFO: Stored 128 out of total 135 tokens. size: 0.0195 GB, cost 12.8890 ms, throughput: 1.5153 GB/s (cache_engine.py:623:lmcache.v1.cache_engine)第二条请求Radix Cache 与 LMCache 共享前缀仅存储新增部分Prefill batch, #new-seq: 1, #new-token: 10, #cached-token: 30, token usage: 0.00, #running-req: 0, #queue-req: 0, Decode batch, #running-req: 1, #token: 64, token usage: 0.00, cuda graph: True, gen throughput (token/s): 8.29, #queue-req: 0, Decode batch, #running-req: 1, #token: 104, token usage: 0.00, cuda graph: True, gen throughput (token/s): 87.95, #queue-req: 0, Decode batch, #running-req: 1, #token: 144, token usage: 0.00, cuda graph: True, gen throughput (token/s): 87.89, #queue-req: 0, LMCache INFO: Stored 112 out of total 140 tokens. size: 0.0171 GB, cost 11.1986 ms, throughput: 1.5261 GB/s (cache_engine.py:623:lmcache.v1.cache_engine)逐项解读Total tokens 140SGLang 将 prefill 与 decode 的 KV cache 一起存储因此 total 40 prompt 100 generated 140 tokens。Cached tokens: 30SGLang 的 Radix Attention Cache 复用了第一条请求的 30 个 token。LMCache hit tokens: 24LMCache 检测到第一条请求存储的 24 个 token3 个完整 8-token chunk。由于 Radix Cache 已在 GPU 内存提供 30 个 token这 24 个 token 既无需从 LMCache 加载也无需重复存储。New tokens: 10仅 10 个 prompt token 需要 prefill 计算40 − 30 10。Stored 112 out of 14024 个 token3 个完整 chunk已在 LMCache 中并被跳过。剩余 116 个 token 中112 个14 个完整 8-token chunk被存储。TensorRT-LLM通过 KV Cache Connector API 集成该集成依赖 NVIDIA/TensorRT-LLM 的 connector preset registry 及配套的 LMCache 适配器两者尚未进入稳定版本。在稳定版发布前需要从源码安装uv venv --python 3.12 source .venv/bin/activate # 从源码安装 LMCachedev 分支 uv pip install githttps://github.com/LMCache/LMCache.gitdev # 从源码安装 TensorRT-LLM —— 参考 NVIDIA 官方构建指南两者进入稳定版后安装命令将是uv pip install lmcache tensorrt_llmversion \ --extra-index-url https://pypi.nvidia.comLMCache 通过 TRT-LLM 的KV Cache ConnectorAPI 集成支持两种部署模式进程内模式connector: lmcacheLMCache 以单例运行在 TRT-LLM 进程内。设置最简单无需管理额外服务。MP 模式connector: lmcache-mpLMCache 作为独立服务器运行同一节点上的多个 TRT-LLM worker 可以共享缓存且缓存能在 TRT-LLM 崩溃后幸存。进程内模式通过环境变量配置 LMCacheexport PYTHONHASHSEED0 # 必须设置 —— chunk 哈希依赖稳定的 hash() export LMCACHE_CHUNK_SIZE256 export LMCACHE_LOCAL_CPUTrue export LMCACHE_MAX_LOCAL_CPU_SIZE2.0 # GiB构建 TRT-LLMLLM对象并指定connector: lmcachefrom tensorrt_llm import LLM, SamplingParams from tensorrt_llm.llmapi.llm_args import ( KvCacheConfig, KvCacheConnectorConfig, ) llm LLM( modelQwen/Qwen2-1.5B-Instruct, backendpytorch, kv_cache_configKvCacheConfig(enable_block_reuseTrue), kv_connector_configKvCacheConnectorConfig(connectorlmcache), ) out llm.generate([Your prompt here], SamplingParams(max_tokens64)) print(out[0].outputs[0].text)MP 模式PYTHONHASHSEED0必须在两个终端中都设置 —— chunk 哈希依赖稳定的hash()服务器与客户端必须使用相同的种子export PYTHONHASHSEED0 lmcache server \ --l1-size-gb 10 --eviction-policy LRU --chunk-size 256在另一个终端通过server_url将 TRT-LLM 指向该服务器export PYTHONHASHSEED0 python run_trtllm.py其中run_trtllm.py内容如下from tensorrt_llm import LLM, SamplingParams from tensorrt_llm.llmapi.llm_args import ( KvCacheConfig, KvCacheConnectorConfig, ) llm LLM( modelQwen/Qwen2-1.5B-Instruct, backendpytorch, kv_cache_configKvCacheConfig(enable_block_reuseTrue), kv_connector_configKvCacheConnectorConfig( connectorlmcache-mp, server_urltcp://localhost:5555, ), ) out llm.generate([Your prompt here], SamplingParams(max_tokens64)) print(out[0].outputs[0].text)TRT-LLM 适配器lmcache/integration/tensorrt_llm/tensorrt_adapter.py与 vLLM 适配器一样读取LMCacheEngineConfig设置了LMCACHE_CONFIG_FILE则读 YAML 文件否则读取各个LMCACHE_*环境变量。全部选项见 docs/source/api_reference/configurations.rst。至此三个引擎都已启用 LMCache 的 KV Cache 存储与复用。更多 MP 服务器选项上文 vLLM 的 MP 示例在本地默认端口运行lmcache server常见变体如下。自定义端口或远程主机—— 连接器默认连接localhost:5555。改用其他端口或另一台主机上的服务器时在kv_connector_extra_config中传入lmcache.mp.host/lmcache.mp.portvllm serve Qwen/Qwen3-8B --kv-transfer-config \ {kv_connector:LMCacheMPConnector, kv_role:kv_both, kv_connector_extra_config: {lmcache.mp.host: tcp://10.0.0.1, lmcache.mp.port: 6555}}CPU-only无 GPU—— 服务器以StubCPUDevice运行并通过 POSIX 共享内存与 vLLM 共享 KV 张量。正常启动lmcache server后在 vLLM 侧设置lmcache.mp.mp_transfer_modelmcache_driven以启用零拷贝 SHM 句柄路径默认的auto路由将非 CUDA 设备映射到engine_driven—— 一种 worker 侧 gather/scatter 拷贝路径服务器只有在以--supported-transfer-mode engine_driven或auto启动时才会加载。Docker 部署—— 见 docs/source/production/docker_deployment.rst。HTTP 管理端点health、clear-cache、status—— 见 docs/source/mp/http_api.rst。关键配置速查MP 服务器核心参数以下参数来自 lmcache/v1/multiprocess/config.py 与 lmcache/v1/distributed/config.py完整清单见 docs/source/mp/configuration.rst参数默认值说明--host/--portlocalhost/5555ZMQ 服务器绑定地址vLLM 等引擎经此前缀连接--http-host/--http-port0.0.0.0/8080HTTPFastAPI/uvicorn前端提供管理与指标端点--chunk-size256KV 缓存操作的分块大小token 数--l1-size-gb必填L1 层容量GB默认为钉扎 DRAM 大小--eviction-policy必填逐出策略LRU、IsolatedLRU、noopnoop用于纯写缓冲模式--eviction-trigger-watermark/--eviction-ratio0.8/0.2触发逐出的内存使用率阈值与逐出比例--hash-algorithmblake3token 级操作哈希算法builtin、sha256_cbor、blake3--max-workers1基础工作线程数GPU 亲和池与 CPU 池的默认值--max-gpu-workers继承--max-workersGPU 亲和池STORE/RETRIEVE同实例请求固定分发到同一线程消除 GPU 传输锁竞争--max-cpu-workers继承--max-workers普通 CPU 池LOOKUP 等--supported-transfer-modelmcache_drivenlmcache_driven服务端驱动支持 CUDA IPC 与 CPU SHM、engine_driven非 GPU PREPARE/COMMIT 路径、auto两者皆载--instance-id未设置随机 UUID v4服务器稳定身份用作协调器成员键并投影到 OTelservice.instance.id--l2-adapter可重复配置 L2 适配器nixl_store、fs、mooncake_store、aerospike、s3等按出现顺序构成级联--prometheus-port9090Prometheus/metrics端点端口一个完整的服务器示例含 L2 适配器与可观测性配置lmcache server \ --host 0.0.0.0 \ --port 6555 \ --chunk-size 512 \ --max-workers 4 \ --max-gpu-workers 2 \ --hash-algorithm blake3 \ --l1-size-gb 100 \ --l1-use-lazy \ --l1-init-size-gb 20 \ --eviction-policy noop \ --l2-store-policy skip_l1 \ --l2-prefetch-max-in-flight 8 \ --l2-adapter {type: nixl_store, backend: POSIX, backend_params: {file_path: /data/lmcache/l2, use_direct_io: false}, pool_size: 64} \ --prometheus-port 9090 \ --enable-tracing \ --otlp-endpoint http://localhost:4317vLLM 客户端连接配置vLLM 侧通过kv_connector_extra_config指定 LMCache 服务器地址lmcache.mp.前缀的键是连接器专属配置。lmcache.mp.host上的tcp://前缀可省略裸 host 会被连接器归一化vllm serve Qwen/Qwen3-14B \ --kv-transfer-config \ {kv_connector:LMCacheMPConnector, kv_role:kv_both, kv_connector_extra_config: {lmcache.mp.host: 127.0.0.1, lmcache.mp.port: 6000}}其他常用连接器键完整列表见 docs/source/mp/configuration.rstlmcache.mp.server_urls多服务器部署的 URL 列表逗号分隔设置后优先于host/portvLLM 世界大小必须能被服务器数量整除且目前仅支持张量并行。lmcache.mp.mq_timeout默认300.0秒阻塞式消息队列请求超时。lmcache.mp.heartbeat_interval默认10.0秒连接器向服务器发送心跳的间隔。lmcache.mp.eager_prefetch默认false请求进入 vLLM 等待队列时即提交 LMCache lookup让 L2→L1 的 KV 预取与调度队列等待重叠。lmcache.mp.lazy_offload默认false延迟 store 操作并按 FIFO 批量提交已完成的请求。lmcache.mp.mp_transfer_mode默认autoworker→server 传输上下文路由模式auto/lmcache_driven/engine_driven。通用配置方式进程内模式进程内模式支持两种配置来源详见 docs/source/api_reference/configurations.rst配置文件YAML推荐或 JSON 文件通过LMCACHE_CONFIG_FILE环境变量指定路径。环境变量以LMCACHE_前缀命名的环境变量如LMCACHE_CHUNK_SIZE、LMCACHE_LOCAL_CPU、LMCACHE_MAX_LOCAL_CPU_SIZE、LMCACHE_LOCAL_DISK、LMCACHE_REMOTE_URL、LMCACHE_CACHE_POLICY等。注意配置文件存在时环境变量配置将被忽略。核心通用配置项速查YAML 配置名环境变量说明chunk_sizeLMCACHE_CHUNK_SIZE缓存分块大小默认256local_cpuLMCACHE_LOCAL_CPU是否启用 CPU 缓存默认truemax_local_cpu_sizeLMCACHE_MAX_LOCAL_CPU_SIZECPU 缓存上限GB默认5.0local_diskLMCACHE_LOCAL_DISK本地磁盘缓存目录路径可逗号分隔多个max_local_disk_sizeLMCACHE_MAX_LOCAL_DISK_SIZE磁盘缓存上限GB默认0.0remote_urlLMCACHE_REMOTE_URL远端存储 URL格式protocol://host:portremote_serdeLMCACHE_REMOTE_SERDE序列化格式naive或cachegen默认naivesave_decode_cacheLMCACHE_SAVE_DECODE_CACHE是否存储 decode 阶段的 KV cache默认falseuse_layerwiseLMCACHE_USE_LAYERWISE是否启用 layerwise 流水线默认falsecache_policyLMCACHE_CACHE_POLICY逐出策略LRU、LFU、FIFO默认LRUenable_p2pLMCACHE_ENABLE_P2P是否启用 P2P 共享默认falseenable_pdLMCACHE_ENABLE_PD是否启用 Prefill-Decode 分离默认false验证与基准测试跑通基本流程后可以用 docs/source/getting_started/benchmarking.rst 中的lmcache bench engine工作负载做对比验证对同一套long-doc-qa基准分别跑纯 vLLM与vLLM LMCache两个环境比较 TTFT 与耗时。基准配置可导出为 JSON 文件并跨环境重放保证对比公平。下一步性能测试参考 docs/source/getting_started/benchmarking.rst 用更全面的示例体验 LMCache 的性能收益。生产部署使用 Docker 或 Kubernetes 部署并配置可观测性与调优 —— 见 docs/source/mp/deployment.rst。进阶主题多引擎共享缓存见 examples/kv_cache_reuse/share_across_engines/README.mdKV Cache 卸载与在线会话见 docs/source/getting_started/quickstart/offload_kv_cache.rst 与 docs/source/getting_started/quickstart/share_kv_cache.rst。【免费下载链接】LMCacheLMCache: Supercharge Your LLM with the Fastest KV Cache Layer项目地址: https://gitcode.com/GitHub_Trending/lm/LMCache创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考