让长上下文推理少算一遍LMCache 缓存配置快速上手指南【免费下载链接】LMCacheLMCache: Supercharge Your LLM with the Fastest KV Cache Layer项目地址: https://gitcode.com/GitHub_Trending/lm/LMCache重启推理服务后第一轮请求为什么总是格外慢因为 GPU 里那份热腾腾的 KV 缓存随进程一起没了长文档、多轮对话的 prefill 只能从零再算一遍。LMCache 就是为此而生的它挂在 vLLM/SGLang 旁边做一层 KV 缓存把算过的 KV 块存到 CPU、磁盘或远端存储下次命中同样的前缀就直接复用省掉重复计算。对刚接触它的人来说LMCache 的参数看着多真正决定体验的其实没几个。下面按先跑通、再按场景挑、最后拆重点参数的顺序走一遍帮你把配置写对而不是抄全。跑起来三步完成最小可用配置第一步装好环境前置条件是 Linux、Python 3.9–3.13、NVIDIA GPUcompute 7.0和 CUDA 12.1。用 uv 安装uv venv --python 3.12 uv pip install lmcache如果后面要玩分离式预填充或 P2P 共享NIXL 是可选扩展装lmcache[nixl]即可。怎么确认成功pip show lmcache能打印出版本号并且import lmcache不报错。不同 vLLM/CUDA 组合对应哪个发布渠道先翻 兼容性文档 再装别默认 latest 一定对。第二步写一份最小配置LMCache 的配置就是一个 YAML默认放在~/.lmcache/config.yaml也可以用LMCACHE_CONFIG_PATH环境变量指到别处容器里更好用。最小配置只需要三行chunk_size: 256 local_cpu: True max_local_cpu_size: 10意思是把 KV 按 256 个 token 一块切好存进 CPU 内存最多用 10GB。更完整的样例可以看 examples/cache_with_configs/example.yaml。怎么确认成功起一个带 LMCache 的 vLLM 服务启动日志里会打印 LMCache banner 和它读到的配置值确认chunk_size、max_local_cpu_size与你写的一致。第三步跑一次内置自检不接推理框架也能验证缓存链路通不通仓库自带 basic check 工具python -m lmcache.v1.basic_check --mode test_storage_manager它会把示例配置复制到~/.lmcache/config.yaml或指向LMCACHE_CONFIG_PATH然后实际读写一次存储管理器。怎么确认成功命令跑完且存储管理器测试通过说明存块、查块、取块这条主链路是好的。这个工具还能测远端后端--mode test_remote用法详见 examples/basic_check/ 的 README。按场景挑配置三种典型部署各一份模板场景不同缓存该放在哪就不一样。下面每份模板都只保留必需的行完整参数以官方配置文档为准。单机多轮对话CPU 缓存就够chunk_size: 256 local_cpu: True max_local_cpu_size: 20对话场景的前缀系统提示 历史轮次复用率很高数据基本不会出机器所以给足 CPU 缓存容量、把容量默认值 5GB 调大到 20GB是为了少被 LRU 淘汰cache_policy默认就是 LRU。多实例集中共享加一个远端后端同一模型开多个推理实例时让大家都把 KV 汇聚到远端存储local_cpu: True remote_url: lm://localhost:65432 remote_serde: cachegenremote_url指向一个远端 LMCache 实例remote_serde: cachegen用压缩序列化省带宽和空间。完整可运行的配置在 examples/kv_cache_reuse/share_across_instances/centralized_sharing/example.yaml。多实例 P2P 共享实例之间直接互取没有中心节点时实例间点对点互相取缓存。除了 P2P 端口还必须配齐 controller 相关字段否则会直接启动失败见下文出了问题时enable_p2p: True p2p_host: localhost p2p_init_ports: 8200 p2p_lookup_ports: 8201 transfer_channel: nixlexamples/kv_cache_reuse/share_across_instances/p2p_sharing/example1.yaml 里有含 controller 配置的完整版照着抄最稳。如果你的目标是分离式预填充prefill 节点算完把 KV 直接递给 decode 节点配置形态是enable_pdpd_rolepd_buffer_sizenixl传输通道模板和启动脚本都在 examples/disagg_prefill/1p1d/。重点参数拆解三个最容易配错的chunk_size缓存块的大小它决定缓存的最小复用单位类比一下书架格子的尺寸。格子太大一本书差几页没放完就得整格重算格子太小格子架子和索引本身就成了负担。默认 256 对大多数场景是好的起点。调过头的表现调到 1024 之后命中率不升反降说明大量差一点就命中的请求被整块拒掉了调得太小则元数据和块间开销变多长尾小请求的命中收益也有限。改它要和实际请求的前缀长度分布对齐——先看看你的流量再动它。save_unfull_chunk不满一块的存不存默认False即不满一个 chunk_size 的尾部不入库。这里有个新手必踩的坑一旦开了enable_blending或enable_pdLMCache 会自动把它翻成 True 并打一条 warning 日志——因为 blending 需要片段级缓存、PD 需要把完整的 KV含不满一块的部分完整传给 decode 节点漏掉尾部就是错的结果。所以如果你看到这条警告不用慌它是提醒不是错误但反过来如果你手动依赖 blending/PD 却把配置里显式写死成 False 又被别处覆盖就要认真查一下配置来源。max_local_cpu_sizeCPU 缓存上限单位是 GB默认只有 5.0。调小的代价是最直观的容量不够 → LRU 频繁淘汰 → 命中率掉。调过头的代价则是宿主机内存被吃满跟 vLLM 进程抢内存轻则系统换页、重则 OOM kill。经验做法看模型 KV 缓存规模CPU 侧给到能装下你希望复用的那部分历史的量级配合下文命中率指标观察淘汰是否频繁而不是拍脑袋拉满。其余几十个参数远程后端、GDS、NUMA、内部 API 服务器、lazy 内存分配器等按需用完整定义和默认值见 配置参考文档。效果怎么观察盯住两个命中率指标配置改完别凭感觉判断看指标。LMCache 的指标通过 Prometheus 暴露接了 vLLM 就出现在 vLLM 的/metrics端点也可以开 LMCache 内部 API 服务器internal_api_server_enabled: True查看。核心就盯两个lmcache:retrieve_hit_rateretrieve 请求的命中率。多轮对话、共享前缀场景下稳态应该明显大于 0且随流量跑起来后趋于平稳。lmcache:lookup_hit_ratelookup 阶段的命中率。它低而lmcache:lookup_0_hit_requests零命中请求数很高时说明请求进来基本查不到东西——先怀疑前缀根本没复用再怀疑配置。补充一个判断命中率长期贴地 CPU 缓存打满通常是max_local_cpu_size太小在淘汰命中率尚可但 retrieve 慢看看是否该开enable_async_loading让加载不阻塞 prefill。指标含义的完整列表在 metrics 文档。出了问题时的排查顺序启动就报lmcache_instance_id is required when enable_controllerTrue原因开了 controller 或 P2P但配套字段没写全。第一步对照 p2p_sharing/example1.yaml把lmcache_instance_id、controller_pull_url、controller_reply_url、lmcache_worker_ports补齐再重启。PD 模式下 assert 失败PD only supports enable_p2pFalse原因分离式预填充和 P2P 共享互斥两个都开了。第一步把enable_p2p改成False另外 receiver 节点要求retrieve_locations: [PDBackend]配错也会被断言拦下。日志里出现Automatically setting save_unfull_chunkTrue原因你开了 blending 或 PD系统替你把尾部缓存开关打开了这是预期行为。第一步确认这条 warning 出现的时机和你开开关的操作一致如果没开 blending/PD 却看到它检查配置里是否残留了多余字段。命中率长期偏低日志里大量零命中原因缓存容量不够被 LRU 淘汰或chunk_size与请求前缀长度不匹配。第一步先用basic_check排除存储链路问题再看lookup_hit_rate和宿主机内存占用决定是扩容max_local_cpu_size还是调整chunk_size。配置只是把 LMCache 的缓存行为调到贴合你的流量而已先用三步跑通最小链路再按场景加远端或 P2P最后拿命中率指标收口。所有参数的权威定义在 docs/source/api_reference/configurations.rst可运行的部署模板都放在 examples/ 目录下从那里找最接近你场景的一份抄比从零拼配置快得多。【免费下载链接】LMCacheLMCache: Supercharge Your LLM with the Fastest KV Cache Layer项目地址: https://gitcode.com/GitHub_Trending/lm/LMCache创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
让长上下文推理少算一遍：LMCache 缓存配置快速上手指南
让长上下文推理少算一遍LMCache 缓存配置快速上手指南【免费下载链接】LMCacheLMCache: Supercharge Your LLM with the Fastest KV Cache Layer项目地址: https://gitcode.com/GitHub_Trending/lm/LMCache重启推理服务后第一轮请求为什么总是格外慢因为 GPU 里那份热腾腾的 KV 缓存随进程一起没了长文档、多轮对话的 prefill 只能从零再算一遍。LMCache 就是为此而生的它挂在 vLLM/SGLang 旁边做一层 KV 缓存把算过的 KV 块存到 CPU、磁盘或远端存储下次命中同样的前缀就直接复用省掉重复计算。对刚接触它的人来说LMCache 的参数看着多真正决定体验的其实没几个。下面按先跑通、再按场景挑、最后拆重点参数的顺序走一遍帮你把配置写对而不是抄全。跑起来三步完成最小可用配置第一步装好环境前置条件是 Linux、Python 3.9–3.13、NVIDIA GPUcompute 7.0和 CUDA 12.1。用 uv 安装uv venv --python 3.12 uv pip install lmcache如果后面要玩分离式预填充或 P2P 共享NIXL 是可选扩展装lmcache[nixl]即可。怎么确认成功pip show lmcache能打印出版本号并且import lmcache不报错。不同 vLLM/CUDA 组合对应哪个发布渠道先翻 兼容性文档 再装别默认 latest 一定对。第二步写一份最小配置LMCache 的配置就是一个 YAML默认放在~/.lmcache/config.yaml也可以用LMCACHE_CONFIG_PATH环境变量指到别处容器里更好用。最小配置只需要三行chunk_size: 256 local_cpu: True max_local_cpu_size: 10意思是把 KV 按 256 个 token 一块切好存进 CPU 内存最多用 10GB。更完整的样例可以看 examples/cache_with_configs/example.yaml。怎么确认成功起一个带 LMCache 的 vLLM 服务启动日志里会打印 LMCache banner 和它读到的配置值确认chunk_size、max_local_cpu_size与你写的一致。第三步跑一次内置自检不接推理框架也能验证缓存链路通不通仓库自带 basic check 工具python -m lmcache.v1.basic_check --mode test_storage_manager它会把示例配置复制到~/.lmcache/config.yaml或指向LMCACHE_CONFIG_PATH然后实际读写一次存储管理器。怎么确认成功命令跑完且存储管理器测试通过说明存块、查块、取块这条主链路是好的。这个工具还能测远端后端--mode test_remote用法详见 examples/basic_check/ 的 README。按场景挑配置三种典型部署各一份模板场景不同缓存该放在哪就不一样。下面每份模板都只保留必需的行完整参数以官方配置文档为准。单机多轮对话CPU 缓存就够chunk_size: 256 local_cpu: True max_local_cpu_size: 20对话场景的前缀系统提示 历史轮次复用率很高数据基本不会出机器所以给足 CPU 缓存容量、把容量默认值 5GB 调大到 20GB是为了少被 LRU 淘汰cache_policy默认就是 LRU。多实例集中共享加一个远端后端同一模型开多个推理实例时让大家都把 KV 汇聚到远端存储local_cpu: True remote_url: lm://localhost:65432 remote_serde: cachegenremote_url指向一个远端 LMCache 实例remote_serde: cachegen用压缩序列化省带宽和空间。完整可运行的配置在 examples/kv_cache_reuse/share_across_instances/centralized_sharing/example.yaml。多实例 P2P 共享实例之间直接互取没有中心节点时实例间点对点互相取缓存。除了 P2P 端口还必须配齐 controller 相关字段否则会直接启动失败见下文出了问题时enable_p2p: True p2p_host: localhost p2p_init_ports: 8200 p2p_lookup_ports: 8201 transfer_channel: nixlexamples/kv_cache_reuse/share_across_instances/p2p_sharing/example1.yaml 里有含 controller 配置的完整版照着抄最稳。如果你的目标是分离式预填充prefill 节点算完把 KV 直接递给 decode 节点配置形态是enable_pdpd_rolepd_buffer_sizenixl传输通道模板和启动脚本都在 examples/disagg_prefill/1p1d/。重点参数拆解三个最容易配错的chunk_size缓存块的大小它决定缓存的最小复用单位类比一下书架格子的尺寸。格子太大一本书差几页没放完就得整格重算格子太小格子架子和索引本身就成了负担。默认 256 对大多数场景是好的起点。调过头的表现调到 1024 之后命中率不升反降说明大量差一点就命中的请求被整块拒掉了调得太小则元数据和块间开销变多长尾小请求的命中收益也有限。改它要和实际请求的前缀长度分布对齐——先看看你的流量再动它。save_unfull_chunk不满一块的存不存默认False即不满一个 chunk_size 的尾部不入库。这里有个新手必踩的坑一旦开了enable_blending或enable_pdLMCache 会自动把它翻成 True 并打一条 warning 日志——因为 blending 需要片段级缓存、PD 需要把完整的 KV含不满一块的部分完整传给 decode 节点漏掉尾部就是错的结果。所以如果你看到这条警告不用慌它是提醒不是错误但反过来如果你手动依赖 blending/PD 却把配置里显式写死成 False 又被别处覆盖就要认真查一下配置来源。max_local_cpu_sizeCPU 缓存上限单位是 GB默认只有 5.0。调小的代价是最直观的容量不够 → LRU 频繁淘汰 → 命中率掉。调过头的代价则是宿主机内存被吃满跟 vLLM 进程抢内存轻则系统换页、重则 OOM kill。经验做法看模型 KV 缓存规模CPU 侧给到能装下你希望复用的那部分历史的量级配合下文命中率指标观察淘汰是否频繁而不是拍脑袋拉满。其余几十个参数远程后端、GDS、NUMA、内部 API 服务器、lazy 内存分配器等按需用完整定义和默认值见 配置参考文档。效果怎么观察盯住两个命中率指标配置改完别凭感觉判断看指标。LMCache 的指标通过 Prometheus 暴露接了 vLLM 就出现在 vLLM 的/metrics端点也可以开 LMCache 内部 API 服务器internal_api_server_enabled: True查看。核心就盯两个lmcache:retrieve_hit_rateretrieve 请求的命中率。多轮对话、共享前缀场景下稳态应该明显大于 0且随流量跑起来后趋于平稳。lmcache:lookup_hit_ratelookup 阶段的命中率。它低而lmcache:lookup_0_hit_requests零命中请求数很高时说明请求进来基本查不到东西——先怀疑前缀根本没复用再怀疑配置。补充一个判断命中率长期贴地 CPU 缓存打满通常是max_local_cpu_size太小在淘汰命中率尚可但 retrieve 慢看看是否该开enable_async_loading让加载不阻塞 prefill。指标含义的完整列表在 metrics 文档。出了问题时的排查顺序启动就报lmcache_instance_id is required when enable_controllerTrue原因开了 controller 或 P2P但配套字段没写全。第一步对照 p2p_sharing/example1.yaml把lmcache_instance_id、controller_pull_url、controller_reply_url、lmcache_worker_ports补齐再重启。PD 模式下 assert 失败PD only supports enable_p2pFalse原因分离式预填充和 P2P 共享互斥两个都开了。第一步把enable_p2p改成False另外 receiver 节点要求retrieve_locations: [PDBackend]配错也会被断言拦下。日志里出现Automatically setting save_unfull_chunkTrue原因你开了 blending 或 PD系统替你把尾部缓存开关打开了这是预期行为。第一步确认这条 warning 出现的时机和你开开关的操作一致如果没开 blending/PD 却看到它检查配置里是否残留了多余字段。命中率长期偏低日志里大量零命中原因缓存容量不够被 LRU 淘汰或chunk_size与请求前缀长度不匹配。第一步先用basic_check排除存储链路问题再看lookup_hit_rate和宿主机内存占用决定是扩容max_local_cpu_size还是调整chunk_size。配置只是把 LMCache 的缓存行为调到贴合你的流量而已先用三步跑通最小链路再按场景加远端或 P2P最后拿命中率指标收口。所有参数的权威定义在 docs/source/api_reference/configurations.rst可运行的部署模板都放在 examples/ 目录下从那里找最接近你场景的一份抄比从零拼配置快得多。【免费下载链接】LMCacheLMCache: Supercharge Your LLM with the Fastest KV Cache Layer项目地址: https://gitcode.com/GitHub_Trending/lm/LMCache创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
