LMCache 配置实战指南7 步从单卡跑通到分离式预填充集群【免费下载链接】LMCacheLMCache: Supercharge Your LLM with the Fastest KV Cache Layer项目地址: https://gitcode.com/GitHub_Trending/lm/LMCache长上下文请求一多prefill 延迟就成倍上涨同一批用户反复发起多轮对话KV 缓存却互相挤兑、频繁淘汰。LMCache 配置的核心就是解决这两类问题它作为推理引擎外层的 KV 缓存加速层负责把命中过的 KV 缓存住、复用掉让长上下文推理加速落到可配置的参数上。上图来自 benchmarks/ttft-estimator/ 的二次方预填充估算上下文越长TTFT 增长越陡峭——这正是缓存层要削平的那条曲线。快速上手LMCache 最小可用配置与验证结论先行一份 4 行的 YAML 就够让缓存跑起来。把配置文件放到工作目录LMCache 会自动加载找不到文件时才会读LMCACHE_前缀的环境变量因此文件优先级高于环境变量# 最小可用配置256 token 分块 10GB CPU 缓存 chunk_size: 256 local_cpu: True max_local_cpu_size: 10完整版本可参考 examples/cache_with_configs/example.yaml核心参数如下参数环境变量默认值建议值chunk_sizeLMCACHE_CHUNK_SIZE256256长上下文改 512/1024local_cpuLMCACHE_LOCAL_CPUTrueTruemax_local_cpu_sizeLMCACHE_MAX_LOCAL_CPU_SIZE5.0GB10 起local_diskLMCACHE_LOCAL_DISK空冷数据场景给file:///路径怎么确认缓存真的在工作两个入口任选一是看 vLLM 日志中LMCache INFO的保存/查找记录二是装lmcache-cli包后用命令行查看缓存状态docs/source/cli/ 有完整的子命令说明ping、query、describe 等。 同一进程里同时给了配置文件和环境变量时以配置文件为准——多实例部署时建议统一用文件避免改了一半的混合状态。按场景选配置多轮对话、长上下文与批处理同一个参数在不同负载下最优值完全不同先看场景再定参数。多轮对话让没聊完的 KV 别被丢痛点会话往往在 chunk 没攒满 256 token 时就要落盘默认行为会把这种不完整块丢掉下一轮只能重新算。参数环境变量默认值建议值cache_policyLMCACHE_CACHE_POLICYLRULRUsave_unfull_chunkLMCACHE_SAVE_UNFULL_CHUNKFalseTruecache_policy可选 LRU默认、LFU、FIFO对话类流量热点稳定但会话间穿插LRU 最贴合命中率不理想时再试 LFU。长上下文大 chunk GDS 直通存储痛点几十 K 甚至上百 K token 的输入二次请求仍在大面积重算TTFT 吃掉大半。参数环境变量默认值建议值chunk_sizeLMCACHE_CHUNK_SIZE256512–1024gds_pathLMCACHE_GDS_PATH空有 NVMeGPUDirect 时启用gds_buffer_sizeLMCACHE_GDS_BUFFER_SIZE空64MB 起步remote_serdeLMCACHE_REMOTE_SERDEnaivecachegen# 长上下文大块 GDS 压缩序列化 chunk_size: 1024 gds_path: /mnt/gds/lmcache remote_serde: cachegengds_path启用后走 GPUDirect Storage 路径支持 wekafs 等文件系统见 lmcache/v1/storage_backend/gds_backend.pyremote_serde: cachegen用压缩序列化降低远程存储的体积与带宽压力。批处理顺序流量 大容量 CPU 池痛点离线任务上下文差异大LRU 频繁抖动导致命中率不稳。把max_local_cpu_size提到能装下一个批次 KV 总量的水平如 50 GBcache_policy保持 LRU 或按严格顺序访问场景改 FIFO。顺序流场景下 FIFO 淘汰更省内存分配开销属于低成本的命中率杠杆。内存与性能调优按症状→原因→参数排查调优不靠猜先看监控定位症状。参数环境变量默认值建议值max_local_cpu_sizeLMCACHE_MAX_LOCAL_CPU_SIZE5.0≥ 峰值 KV 占用save_unfull_chunkLMCACHE_SAVE_UNFULL_CHUNKFalse按负载定numa_modeLMCACHE_NUMA_MODE空自动manual 显式映射priority_limitLMCACHE_PRIORITY_LIMIT空不限如 5enable_async_loadingLMCACHE_ENABLE_ASYNC_LOADINGFalseTrue远端为主症状命中率低。原因通常是 chunk 切得太碎短请求永远攒不满块。先把chunk_size提到 512/1024再考虑开enable_blending融合非前缀片段docs/source/kv_cache_optimizations/blending.rst。症状CPU 内存水位贴顶、淘汰频繁。先调大max_local_cpu_size多 GPU 且内存带宽吃紧时把numa_mode设为manual并在extra_config里给出gpu_to_numa_mapping{0: 0, 1: 1}让每块缓存落在 GPU 同侧 NUMA 节点实现见 lmcache/v1/system_detection.py。症状关键请求缓存被挤掉。设priority_limit: 5这类阈值只缓存低编号高优先级请求远端为主的部署打开enable_async_loading避免阻塞式回源拖慢调度。⚠️ 默认 5GB 的max_local_cpu_size在 70B 级别模型 长上下文下几乎等于没有缓存OOM 前它先满载抖动——先给足容量再谈命中率。进阶能力从单机到分布式多实例共享 KV 缓存痛点N 个推理实例各存一份 KV命中率被重复存储稀释。LMCache 提供 P2P 与集中式两种共享模式示例在 examples/kv_cache_reuse/share_across_instances/P2P 用enable_p2ptransfer_channel集中式走 share_across_engines/lmcache.yaml 的控制器拓扑。除网络共享外Maru 后端还能让多个实例通过 CXL 内存池零拷贝共享maru_path/maru_pool_size架构如上图文档见 docs/source/assets/。参数环境变量默认值建议值enable_p2pLMCACHE_ENABLE_P2PFalseTruep2p_init_portsLMCACHE_P2P_INIT_PORTS无8200transfer_channelLMCACHE_TRANSFER_CHANNEL空nixl# P2P 共享对应 examples/kv_cache_reuse/share_across_instances/p2p_sharing/example1.yaml enable_p2p: True p2p_host: localhost p2p_init_ports: 8200 p2p_lookup_ports: 8201 transfer_channel: nixl分离式预填充PD 分离痛点超长 prompt 的 prefill 与 decode 混跑长上下文请求的 TTFT 被排队拖垮。拆成独立节点后KV 经 NIXL 通道直接搬运。参考 examples/disagg_prefill/1p1d/ 的 sender/receiver 成对配置# prefill 节点对应 examples/disagg_prefill/1p1d/configs/lmcache-prefiller-config.yaml enable_pd: True pd_role: sender transfer_channel: nixl pd_buffer_size: 1073741824 # 1GB pd_buffer_device: cuda nixl_backends: [UCX]接收节点同目录lmcache-decoder-config.yaml中把pd_role改为receiver即可xPxD 多实例部署见 examples/disagg_prefill/xpyd/。⚠️pd_buffer_size必须装得下预填充 KV经验公式pd_buffer_size (pd_max_prefill_len // chunk_size 1) * kv_size配小了传输端会直接报错。RDMA 环境用nixl_backends: [UCX]走 RDMA比 TCP 稳得多。可观测与排障监控入口和常见故障看不到状态就无法调优——先开内部 API 服务器参数环境变量默认值建议值internal_api_server_enabledLMCACHE_INTERNAL_API_SERVER_ENABLEDFalseTrueinternal_api_server_hostLMCACHE_INTERNAL_API_SERVER_HOST0.0.0.00.0.0.0internal_api_server_port_startLMCACHE_INTERNAL_API_SERVER_PORT_START69996999按端口偏移区分角色API 服务器提供缓存管理docs/source/internal_api_server/ 列出了 lookup、clear、compress、pin 等端点指标采集则可用 examples/observability/ 里的 Prometheus Grafana Tempo 全家桶一键拉起。常见故障对照表症状可能原因处理参数/动作命中率长期偏低chunk 太碎、非前缀片段被弃增大chunk_size评估enable_blendingCPU 内存贴顶容量不足调大max_local_cpu_size加local_disk兜底P2P 建连/传输超时端口不通、超时太短核对p2p_*_portsextra_config调p2p_socket_recv_timeout_ms等PD 传输失败缓冲不足、角色错配按公式加大pd_buffer_size核对pd_role与transfer_channel资源索引示例配置与官方文档速查示例配置examples/cache_with_configs/最小配置、examples/blend_in_process/CacheBlend 复算控制、examples/kv_cache_reuse/本地/远程后端与跨实例共享、examples/disagg_prefill/PD 分离 1P1D 与 xPyD、examples/serde/fp8/turboquant/aesgcm 序列化文档docs/source/getting_started/安装与快速开始、docs/source/kv_cache/存储后端与缓存策略、docs/source/internal_api_server/内部 API、docs/source/cli/CLI 命令源码定位参数定义在 lmcache/v1/config.pyPD 传输在 lmcache/v1/transfer_channel/GDS 后端在 lmcache/v1/storage_backend/gds_backend.py压测工具benchmarks/ttft-estimator/TTFT 估算、examples/online_session/TTFT 扫测脚本下一步清单先跑通快速上手的最小配置 → 按你的真实负载对表按场景选配置→ 用内部 API observability 组件盯住命中率与内存水位 → 再决定是否上 P2P 或 PD 分离。更多参数细节直接翻 docs/source/ 的官方文档。【免费下载链接】LMCacheLMCache: Supercharge Your LLM with the Fastest KV Cache Layer项目地址: https://gitcode.com/GitHub_Trending/lm/LMCache创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 LMCache 配置实战指南：7 步从单卡跑通到分离式预填充集群
LMCache 配置实战指南7 步从单卡跑通到分离式预填充集群【免费下载链接】LMCacheLMCache: Supercharge Your LLM with the Fastest KV Cache Layer项目地址: https://gitcode.com/GitHub_Trending/lm/LMCache长上下文请求一多prefill 延迟就成倍上涨同一批用户反复发起多轮对话KV 缓存却互相挤兑、频繁淘汰。LMCache 配置的核心就是解决这两类问题它作为推理引擎外层的 KV 缓存加速层负责把命中过的 KV 缓存住、复用掉让长上下文推理加速落到可配置的参数上。上图来自 benchmarks/ttft-estimator/ 的二次方预填充估算上下文越长TTFT 增长越陡峭——这正是缓存层要削平的那条曲线。快速上手LMCache 最小可用配置与验证结论先行一份 4 行的 YAML 就够让缓存跑起来。把配置文件放到工作目录LMCache 会自动加载找不到文件时才会读LMCACHE_前缀的环境变量因此文件优先级高于环境变量# 最小可用配置256 token 分块 10GB CPU 缓存 chunk_size: 256 local_cpu: True max_local_cpu_size: 10完整版本可参考 examples/cache_with_configs/example.yaml核心参数如下参数环境变量默认值建议值chunk_sizeLMCACHE_CHUNK_SIZE256256长上下文改 512/1024local_cpuLMCACHE_LOCAL_CPUTrueTruemax_local_cpu_sizeLMCACHE_MAX_LOCAL_CPU_SIZE5.0GB10 起local_diskLMCACHE_LOCAL_DISK空冷数据场景给file:///路径怎么确认缓存真的在工作两个入口任选一是看 vLLM 日志中LMCache INFO的保存/查找记录二是装lmcache-cli包后用命令行查看缓存状态docs/source/cli/ 有完整的子命令说明ping、query、describe 等。 同一进程里同时给了配置文件和环境变量时以配置文件为准——多实例部署时建议统一用文件避免改了一半的混合状态。按场景选配置多轮对话、长上下文与批处理同一个参数在不同负载下最优值完全不同先看场景再定参数。多轮对话让没聊完的 KV 别被丢痛点会话往往在 chunk 没攒满 256 token 时就要落盘默认行为会把这种不完整块丢掉下一轮只能重新算。参数环境变量默认值建议值cache_policyLMCACHE_CACHE_POLICYLRULRUsave_unfull_chunkLMCACHE_SAVE_UNFULL_CHUNKFalseTruecache_policy可选 LRU默认、LFU、FIFO对话类流量热点稳定但会话间穿插LRU 最贴合命中率不理想时再试 LFU。长上下文大 chunk GDS 直通存储痛点几十 K 甚至上百 K token 的输入二次请求仍在大面积重算TTFT 吃掉大半。参数环境变量默认值建议值chunk_sizeLMCACHE_CHUNK_SIZE256512–1024gds_pathLMCACHE_GDS_PATH空有 NVMeGPUDirect 时启用gds_buffer_sizeLMCACHE_GDS_BUFFER_SIZE空64MB 起步remote_serdeLMCACHE_REMOTE_SERDEnaivecachegen# 长上下文大块 GDS 压缩序列化 chunk_size: 1024 gds_path: /mnt/gds/lmcache remote_serde: cachegengds_path启用后走 GPUDirect Storage 路径支持 wekafs 等文件系统见 lmcache/v1/storage_backend/gds_backend.pyremote_serde: cachegen用压缩序列化降低远程存储的体积与带宽压力。批处理顺序流量 大容量 CPU 池痛点离线任务上下文差异大LRU 频繁抖动导致命中率不稳。把max_local_cpu_size提到能装下一个批次 KV 总量的水平如 50 GBcache_policy保持 LRU 或按严格顺序访问场景改 FIFO。顺序流场景下 FIFO 淘汰更省内存分配开销属于低成本的命中率杠杆。内存与性能调优按症状→原因→参数排查调优不靠猜先看监控定位症状。参数环境变量默认值建议值max_local_cpu_sizeLMCACHE_MAX_LOCAL_CPU_SIZE5.0≥ 峰值 KV 占用save_unfull_chunkLMCACHE_SAVE_UNFULL_CHUNKFalse按负载定numa_modeLMCACHE_NUMA_MODE空自动manual 显式映射priority_limitLMCACHE_PRIORITY_LIMIT空不限如 5enable_async_loadingLMCACHE_ENABLE_ASYNC_LOADINGFalseTrue远端为主症状命中率低。原因通常是 chunk 切得太碎短请求永远攒不满块。先把chunk_size提到 512/1024再考虑开enable_blending融合非前缀片段docs/source/kv_cache_optimizations/blending.rst。症状CPU 内存水位贴顶、淘汰频繁。先调大max_local_cpu_size多 GPU 且内存带宽吃紧时把numa_mode设为manual并在extra_config里给出gpu_to_numa_mapping{0: 0, 1: 1}让每块缓存落在 GPU 同侧 NUMA 节点实现见 lmcache/v1/system_detection.py。症状关键请求缓存被挤掉。设priority_limit: 5这类阈值只缓存低编号高优先级请求远端为主的部署打开enable_async_loading避免阻塞式回源拖慢调度。⚠️ 默认 5GB 的max_local_cpu_size在 70B 级别模型 长上下文下几乎等于没有缓存OOM 前它先满载抖动——先给足容量再谈命中率。进阶能力从单机到分布式多实例共享 KV 缓存痛点N 个推理实例各存一份 KV命中率被重复存储稀释。LMCache 提供 P2P 与集中式两种共享模式示例在 examples/kv_cache_reuse/share_across_instances/P2P 用enable_p2ptransfer_channel集中式走 share_across_engines/lmcache.yaml 的控制器拓扑。除网络共享外Maru 后端还能让多个实例通过 CXL 内存池零拷贝共享maru_path/maru_pool_size架构如上图文档见 docs/source/assets/。参数环境变量默认值建议值enable_p2pLMCACHE_ENABLE_P2PFalseTruep2p_init_portsLMCACHE_P2P_INIT_PORTS无8200transfer_channelLMCACHE_TRANSFER_CHANNEL空nixl# P2P 共享对应 examples/kv_cache_reuse/share_across_instances/p2p_sharing/example1.yaml enable_p2p: True p2p_host: localhost p2p_init_ports: 8200 p2p_lookup_ports: 8201 transfer_channel: nixl分离式预填充PD 分离痛点超长 prompt 的 prefill 与 decode 混跑长上下文请求的 TTFT 被排队拖垮。拆成独立节点后KV 经 NIXL 通道直接搬运。参考 examples/disagg_prefill/1p1d/ 的 sender/receiver 成对配置# prefill 节点对应 examples/disagg_prefill/1p1d/configs/lmcache-prefiller-config.yaml enable_pd: True pd_role: sender transfer_channel: nixl pd_buffer_size: 1073741824 # 1GB pd_buffer_device: cuda nixl_backends: [UCX]接收节点同目录lmcache-decoder-config.yaml中把pd_role改为receiver即可xPxD 多实例部署见 examples/disagg_prefill/xpyd/。⚠️pd_buffer_size必须装得下预填充 KV经验公式pd_buffer_size (pd_max_prefill_len // chunk_size 1) * kv_size配小了传输端会直接报错。RDMA 环境用nixl_backends: [UCX]走 RDMA比 TCP 稳得多。可观测与排障监控入口和常见故障看不到状态就无法调优——先开内部 API 服务器参数环境变量默认值建议值internal_api_server_enabledLMCACHE_INTERNAL_API_SERVER_ENABLEDFalseTrueinternal_api_server_hostLMCACHE_INTERNAL_API_SERVER_HOST0.0.0.00.0.0.0internal_api_server_port_startLMCACHE_INTERNAL_API_SERVER_PORT_START69996999按端口偏移区分角色API 服务器提供缓存管理docs/source/internal_api_server/ 列出了 lookup、clear、compress、pin 等端点指标采集则可用 examples/observability/ 里的 Prometheus Grafana Tempo 全家桶一键拉起。常见故障对照表症状可能原因处理参数/动作命中率长期偏低chunk 太碎、非前缀片段被弃增大chunk_size评估enable_blendingCPU 内存贴顶容量不足调大max_local_cpu_size加local_disk兜底P2P 建连/传输超时端口不通、超时太短核对p2p_*_portsextra_config调p2p_socket_recv_timeout_ms等PD 传输失败缓冲不足、角色错配按公式加大pd_buffer_size核对pd_role与transfer_channel资源索引示例配置与官方文档速查示例配置examples/cache_with_configs/最小配置、examples/blend_in_process/CacheBlend 复算控制、examples/kv_cache_reuse/本地/远程后端与跨实例共享、examples/disagg_prefill/PD 分离 1P1D 与 xPyD、examples/serde/fp8/turboquant/aesgcm 序列化文档docs/source/getting_started/安装与快速开始、docs/source/kv_cache/存储后端与缓存策略、docs/source/internal_api_server/内部 API、docs/source/cli/CLI 命令源码定位参数定义在 lmcache/v1/config.pyPD 传输在 lmcache/v1/transfer_channel/GDS 后端在 lmcache/v1/storage_backend/gds_backend.py压测工具benchmarks/ttft-estimator/TTFT 估算、examples/online_session/TTFT 扫测脚本下一步清单先跑通快速上手的最小配置 → 按你的真实负载对表按场景选配置→ 用内部 API observability 组件盯住命中率与内存水位 → 再决定是否上 P2P 或 PD 分离。更多参数细节直接翻 docs/source/ 的官方文档。【免费下载链接】LMCacheLMCache: Supercharge Your LLM with the Fastest KV Cache Layer项目地址: https://gitcode.com/GitHub_Trending/lm/LMCache创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考