LMCache 懒卸载Lazy KV Cache Offload用 vLLM LMCacheMPConnector 批量延迟 KV Cache 落盘【免费下载链接】LMCacheLMCache: Supercharge Your LLM with the Fastest KV Cache Layer项目地址: https://gitcode.com/GitHub_Trending/lm/LMCacheLazy KV Cache Offload懒卸载是 LMCache 为 vLLMLMCacheMPConnector提供的可选优化它将 GPU 到 LMCache 的 store 操作推迟到请求完成后再按 FIFO 批量提交从而把 store 工作移出正常的每步per-step执行路径。本文基于 lazy_offload.rst 展开说明其启用方式、四个核心配置参数、底层工作流程与调优策略并结合 lmcache_mp_connector.py、lazy_offload_pending_store.py 等源码讲解实现原理。读完本文你将掌握如何为连续型在线服务场景开启懒卸载、如何按业务特征调参以及它为什么不会破坏推理正确性。一、什么是懒卸载动机与适用边界在默认的 eager即时模式下LMCacheMPConnector会在每个调度步骤同步构造 store 元数据并提交到 LMCache serverKV 块被保护pin直到所有 worker 确认存储完成。这一步是每个请求的必经开销对吞吐敏感、但对缓存立即可用要求不高的服务来说会造成不必要的每请求卸载开销。懒卸载改变了这一行为store 操作被缓冲buffer请求结束后按 FIFO 批次统一提交。它的核心收益是把 store 工作移出正常的每步路径normal per-step path降低每请求的 offload 开销从而提升服务吞吐。需要明确的是本功能默认关闭且仅对 vLLM LMCacheMPConnector可用LMCache server 端无需任何额外 flag配置全部经由 vLLM 的kv_connector_extra_config传入懒卸载只改变 store 的提交时机使用的仍是与默认 eager 行为相同的 LMCache server store 路径见下文工作流程。从源码看连接器在初始化时读取lmcache.mp.lazy_offload仅在 SCHEDULER 角色下创建LazyOffloadPendingStore见 lmcache_mp_connector.pyworker 进程不参与策略决策——这与OffloadPolicy抽象类的设计注释一致Worker processes do not create or invoke policies见 lazy_offload_policy/base.py。二、启用懒卸载vLLM 启动参数详解懒卸载通过 vLLM 的--kv-transfer-config参数开启所有懒卸载选项都嵌套在kv_connector_extra_config中。官方示例配置如下vllm serve Qwen/Qwen3-14B \ --kv-transfer-config \ {kv_connector:LMCacheMPConnector,kv_role:kv_both,kv_connector_extra_config:{lmcache.mp.host:localhost,lmcache.mp.port:5555,lmcache.mp.lazy_offload:true,lmcache.mp.lazy_offload_policy:FIFO,lmcache.mp.lazy_offload_threshold:20,lmcache.mp.lazy_offload_select_count:10}}该示例的效果是20 个请求完成后开始触发卸载每次 FIFO 批次最多选择 10 个请求。四个核心配置参数Key默认值说明lmcache.mp.lazy_offloadfalse启用延迟的、批量化的 store 提交。lmcache.mp.lazy_offload_policyFIFO按插入顺序选择已完成的请求。FIFO 当前是唯一支持的策略。lmcache.mp.lazy_offload_threshold100触发卸载所需的已完成待处理请求数。lmcache.mp.lazy_offload_select_count10每次满足阈值时最多选择的已完成请求数。参数在源码中的落点lmcache.mp.lazy_offload在 lmcache_mp_connector.py 中通过kv_transfer_config.get_from_extra_config(lmcache.mp.lazy_offload, False)读取默认False。lmcache.mp.lazy_offload_policy与lmcache.mp.lazy_offload_threshold在FIFOOffloadPolicy.__init__中解析默认值分别为FIFO与100见 lazy_offload_policy/fifo.py若配置了未知策略名会抛出ValueError: Unknown offload policy。lmcache.mp.lazy_offload_select_count在 lazy_offload_pending_store.py 中解析默认10。确认生效查看 vLLM 日志连接器启用懒卸载后FIFOOffloadPolicy构造时会打印一条日志见 lazy_offload_policy/fifo.pyvLLM 日志中应看到类似信息lazy offload enabled with FIFO policy, offload threshold: 20若未看到该日志请检查kv_connector_extra_config是否被正确传入、kv_connector是否为LMCacheMPConnector。三、工作原理从缓冲到批量提交的完整流程懒卸载复用默认 eager 行为的 LMCache server store 路径仅改变提交时机。整体流程如下new KV blocks | v buffer store metadata and GPU block hashes | v request finishes - add it to the FIFO-ready count | | ready count threshold, on a non-empty scheduling step v select at most lazy_offload_select_count requests | v verify block hashes - protect valid blocks - submit asynchronous stores | v all vLLM workers report completion - release protected GPU blocks三个阶段源码级拆解阶段一缓冲 store 元数据与块哈希add每个调度步骤中连接器在_process_new_requests/_process_cached_requests中生成LMCacheMPRequestMetadataGetStoreMetadata的结果。懒卸载开启时元数据不再立即提交而是调用_pending_store.add(r_meta)进入待处理队列见 lmcache_mp_connector.py。LazyOffloadPendingStore.add会先从绑定的 GPU block pool 读取每个块的block_hash并随元数据一起暂存见 lazy_offload_pending_store.py。在FIFOOffloadPolicy.add中同一请求多次调度产生的元数据会被聚合到同一个PendingStoreItem上见 lazy_offload_policy/fifo.py——这对应注释中提到的场景chunked prefill 或max-num-batched-tokens限制可能让一个请求被多次调度每次只含该次调度步的块。阶段二请求结束入就绪计数mark_req_finished当请求结束时request_finished被调用。懒卸载模式下连接器只调用_pending_store.mark_req_finished(request.request_id)并返回False表示不承担异步释放块的职责见 lmcache_mp_connector.py。mark_req_finished将该请求标记为 finished 并将_finished_requests_count加一见 lazy_offload_policy/fifo.py。阶段三阈值触发、校验哈希、异步提交pop_items_for_offloadpop_items_for_offload(count)是策略的核心当count 0且_finished_requests_count _threshold时按插入顺序弹出至多count个已完成的PendingStoreItem并同步从待处理队列与就绪计数中移除见 lazy_offload_policy/fifo.py。连接器侧_process_lazy_offload_store_requests拿到这批 item 后执行关键校验见 lmcache_mp_connector.py对 item 中每个元数据条目用其中的块 ID 对 GPU block pool 执行touch重新读取块哈希与缓冲时记录的旧哈希比对哈希一致 → 块内容未被复用将元数据加入metadata.add_request_metadata(meta)正式提交异步 store并把块 ID 记入_pending_store的_request_block_ids这些块此时被保护起来等待 worker 完成回调哈希不一致 → 说明 vLLM 已复用该 GPU 块日志打印Part block hashes mismatch for request %s, skip it并跳过该过期元数据。阶段四worker 完成回调与释放保护块worker 侧完成 store 后update_connector_output通过meta.completed_store_requests获取各请求的完成计数当计数满足条件时调用_gpu_block_pool.free_blocks释放被保护的 GPU 块、从_pending_store移除块 ID 记录并调用end_session(req_id)见 lmcache_mp_connector.py。触发时机的两个重要限制只在非空调度步骤触发_process_lazy_offload_store_requests仅在scheduler_output.total_num_scheduled_tokens 0时被调用。源码注释明确解释了原因若总调度 token 数为 0vLLM 的gpu_model_runner会走kv_connector_no_forward路径导致部分 store 操作丢失见 lmcache_mp_connector.py。待处理请求低于阈值、或流量空闲后遗留的尾部请求都不会被自动冲刷。因此懒卸载最适合连续型服务负载continuous serving workloads不适合要求每个请求 KV cache 立即持久化的任务。四、正确性保障块复用时的哈希校验这是懒卸载设计中至关重要的一点请求被选中之前懒卸载不会 pin 它的 GPU 块vLLM 可能把那些块复用于其他请求。连接器通过在两个时间点记录/校验块哈希来防止缓存错误数据缓冲 store 元数据时add记录每个块的block_hash卸载提交前_process_lazy_offload_store_requests重新读取哈希并比对。若块已被复用哈希不一致连接器记录 warning 并跳过该过期 store 元数据而不是把错误的 KV 数据写入缓存。后续对缺失数据的查询将变为 cache missvLLM 会重新计算对应 token——推理正确性完全不受影响代价只是损失一次缓存命中机会。测试用例也验证了这一语义pop_items_for_offload只弹出已完成的请求跳过未完成的且弹出的 item 会从 pending 队列移除并递减就绪计数见 test_lazy_offload_pending_store.py。五、选择计数与就绪计数的联动语义一个需要精确理解的细节被选中的请求会从就绪计数中移除。以阈值为 20、select count 为 10 为例第一次触发时提交 10 个请求剩余 10 个仍处于就绪状态必须再有 10 个请求完成后就绪计数才能重新达到 20从而触发下一批。也就是说阈值衡量的是触发条件当前就绪请求数而不是每批必须清空多少。两个参数都要求配置为正整数。test_pop_items_for_offload_multiple_batches用例完整验证了这种分批语义阈值 1、select count 2 时6 个请求会依次被弹出为 3 批见 test_lazy_offload_pending_store.py。另外pop_items_for_offload对count 0直接返回空列表见 lazy_offload_policy/fifo.py这也解释了为什么 select count 必须为正整数。六、调优指南四个参数的组合策略何时降低lmcache.mp.lazy_offload_threshold缓存需要更早可复用或**流量呈短突发short bursts**时调低阈值会带来更频繁的卸载批次极端情况下可用lmcache.mp.lazy_offload_threshold1获得最早的触发资格但请牢记提交仍需要一个后续的非空调度步骤它不会让卸载立即发生。何时提高阈值想延迟更多 store 工作、减少卸载频率时代价是更长的延迟以及vLLM 在卸载前复用待处理 GPU 块的几率增大更多请求会被哈希校验跳过。如何调整lmcache.mp.lazy_offload_select_count调大每次触发时排空更多请求产生更大的 store 突发burst适合存储带宽充裕、想减少触发次数的场景调小把工作摊薄到更多次阈值跨越中卸载更平滑但触发更频繁。与 LMCache 其他配置的关系懒卸载选项属于kv_connector_extra_config与lmcache.mp.host、lmcache.mp.port等连接器参数并列。若需要按租户、TTL 等维度做请求级控制可在请求的kv_transfer_params中携带lmcache.前缀的键详见 configuration.rst但注意该文档特别提示MP server 目前将请求级配置视为元数据不依赖其做隔离或过期控制。七、适用前提与限制总结维度结论前置条件仅 vLLM LMCacheMPConnectorLMCache server 无需额外 flag默认状态关闭lmcache.mp.lazy_offloadfalse触发时机就绪请求数 ≥ 阈值且处于非空调度步骤策略支持仅FIFO当前正确性哈希校验 跳过过期元数据最多损失缓存命中不影响推理正确性尾部请求低于阈值或流量空闲时不自动冲刷推荐场景连续型在线服务continuous serving对即时缓存可用性不敏感从工程实践看懒卸载的本质是用缓存可用性的延迟换取每步路径上 offload 开销的降低。如果你的服务是持续有流量的在线推理且 KV cache 稍晚几秒可复用完全可接受那么开启懒卸载并配合合理的阈值与 select count是一条低成本的吞吐优化路径反之若每个请求的 KV 都必须立刻落盘例如强一致性的离线批处理则应保持默认的 eager 行为。延伸阅读lazy_offload.rst本功能原始设计文档lmcache_mp_connector.py连接器实现含懒卸载触发与哈希校验逻辑lazy_offload_pending_store.py待处理 store 队列实现lazy_offload_policy/fifo.py 与 lazy_offload_policy/base.pyFIFO 策略与抽象接口test_lazy_offload_pending_store.py策略与队列的单元测试configuration.rstLMCache MP server 配置参考【免费下载链接】LMCacheLMCache: Supercharge Your LLM with the Fastest KV Cache Layer项目地址: https://gitcode.com/GitHub_Trending/lm/LMCache创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
LMCache 懒卸载（Lazy KV Cache Offload）：用 vLLM LMCacheMPConnector 批量延迟 KV Cache 落盘
LMCache 懒卸载Lazy KV Cache Offload用 vLLM LMCacheMPConnector 批量延迟 KV Cache 落盘【免费下载链接】LMCacheLMCache: Supercharge Your LLM with the Fastest KV Cache Layer项目地址: https://gitcode.com/GitHub_Trending/lm/LMCacheLazy KV Cache Offload懒卸载是 LMCache 为 vLLMLMCacheMPConnector提供的可选优化它将 GPU 到 LMCache 的 store 操作推迟到请求完成后再按 FIFO 批量提交从而把 store 工作移出正常的每步per-step执行路径。本文基于 lazy_offload.rst 展开说明其启用方式、四个核心配置参数、底层工作流程与调优策略并结合 lmcache_mp_connector.py、lazy_offload_pending_store.py 等源码讲解实现原理。读完本文你将掌握如何为连续型在线服务场景开启懒卸载、如何按业务特征调参以及它为什么不会破坏推理正确性。一、什么是懒卸载动机与适用边界在默认的 eager即时模式下LMCacheMPConnector会在每个调度步骤同步构造 store 元数据并提交到 LMCache serverKV 块被保护pin直到所有 worker 确认存储完成。这一步是每个请求的必经开销对吞吐敏感、但对缓存立即可用要求不高的服务来说会造成不必要的每请求卸载开销。懒卸载改变了这一行为store 操作被缓冲buffer请求结束后按 FIFO 批次统一提交。它的核心收益是把 store 工作移出正常的每步路径normal per-step path降低每请求的 offload 开销从而提升服务吞吐。需要明确的是本功能默认关闭且仅对 vLLM LMCacheMPConnector可用LMCache server 端无需任何额外 flag配置全部经由 vLLM 的kv_connector_extra_config传入懒卸载只改变 store 的提交时机使用的仍是与默认 eager 行为相同的 LMCache server store 路径见下文工作流程。从源码看连接器在初始化时读取lmcache.mp.lazy_offload仅在 SCHEDULER 角色下创建LazyOffloadPendingStore见 lmcache_mp_connector.pyworker 进程不参与策略决策——这与OffloadPolicy抽象类的设计注释一致Worker processes do not create or invoke policies见 lazy_offload_policy/base.py。二、启用懒卸载vLLM 启动参数详解懒卸载通过 vLLM 的--kv-transfer-config参数开启所有懒卸载选项都嵌套在kv_connector_extra_config中。官方示例配置如下vllm serve Qwen/Qwen3-14B \ --kv-transfer-config \ {kv_connector:LMCacheMPConnector,kv_role:kv_both,kv_connector_extra_config:{lmcache.mp.host:localhost,lmcache.mp.port:5555,lmcache.mp.lazy_offload:true,lmcache.mp.lazy_offload_policy:FIFO,lmcache.mp.lazy_offload_threshold:20,lmcache.mp.lazy_offload_select_count:10}}该示例的效果是20 个请求完成后开始触发卸载每次 FIFO 批次最多选择 10 个请求。四个核心配置参数Key默认值说明lmcache.mp.lazy_offloadfalse启用延迟的、批量化的 store 提交。lmcache.mp.lazy_offload_policyFIFO按插入顺序选择已完成的请求。FIFO 当前是唯一支持的策略。lmcache.mp.lazy_offload_threshold100触发卸载所需的已完成待处理请求数。lmcache.mp.lazy_offload_select_count10每次满足阈值时最多选择的已完成请求数。参数在源码中的落点lmcache.mp.lazy_offload在 lmcache_mp_connector.py 中通过kv_transfer_config.get_from_extra_config(lmcache.mp.lazy_offload, False)读取默认False。lmcache.mp.lazy_offload_policy与lmcache.mp.lazy_offload_threshold在FIFOOffloadPolicy.__init__中解析默认值分别为FIFO与100见 lazy_offload_policy/fifo.py若配置了未知策略名会抛出ValueError: Unknown offload policy。lmcache.mp.lazy_offload_select_count在 lazy_offload_pending_store.py 中解析默认10。确认生效查看 vLLM 日志连接器启用懒卸载后FIFOOffloadPolicy构造时会打印一条日志见 lazy_offload_policy/fifo.pyvLLM 日志中应看到类似信息lazy offload enabled with FIFO policy, offload threshold: 20若未看到该日志请检查kv_connector_extra_config是否被正确传入、kv_connector是否为LMCacheMPConnector。三、工作原理从缓冲到批量提交的完整流程懒卸载复用默认 eager 行为的 LMCache server store 路径仅改变提交时机。整体流程如下new KV blocks | v buffer store metadata and GPU block hashes | v request finishes - add it to the FIFO-ready count | | ready count threshold, on a non-empty scheduling step v select at most lazy_offload_select_count requests | v verify block hashes - protect valid blocks - submit asynchronous stores | v all vLLM workers report completion - release protected GPU blocks三个阶段源码级拆解阶段一缓冲 store 元数据与块哈希add每个调度步骤中连接器在_process_new_requests/_process_cached_requests中生成LMCacheMPRequestMetadataGetStoreMetadata的结果。懒卸载开启时元数据不再立即提交而是调用_pending_store.add(r_meta)进入待处理队列见 lmcache_mp_connector.py。LazyOffloadPendingStore.add会先从绑定的 GPU block pool 读取每个块的block_hash并随元数据一起暂存见 lazy_offload_pending_store.py。在FIFOOffloadPolicy.add中同一请求多次调度产生的元数据会被聚合到同一个PendingStoreItem上见 lazy_offload_policy/fifo.py——这对应注释中提到的场景chunked prefill 或max-num-batched-tokens限制可能让一个请求被多次调度每次只含该次调度步的块。阶段二请求结束入就绪计数mark_req_finished当请求结束时request_finished被调用。懒卸载模式下连接器只调用_pending_store.mark_req_finished(request.request_id)并返回False表示不承担异步释放块的职责见 lmcache_mp_connector.py。mark_req_finished将该请求标记为 finished 并将_finished_requests_count加一见 lazy_offload_policy/fifo.py。阶段三阈值触发、校验哈希、异步提交pop_items_for_offloadpop_items_for_offload(count)是策略的核心当count 0且_finished_requests_count _threshold时按插入顺序弹出至多count个已完成的PendingStoreItem并同步从待处理队列与就绪计数中移除见 lazy_offload_policy/fifo.py。连接器侧_process_lazy_offload_store_requests拿到这批 item 后执行关键校验见 lmcache_mp_connector.py对 item 中每个元数据条目用其中的块 ID 对 GPU block pool 执行touch重新读取块哈希与缓冲时记录的旧哈希比对哈希一致 → 块内容未被复用将元数据加入metadata.add_request_metadata(meta)正式提交异步 store并把块 ID 记入_pending_store的_request_block_ids这些块此时被保护起来等待 worker 完成回调哈希不一致 → 说明 vLLM 已复用该 GPU 块日志打印Part block hashes mismatch for request %s, skip it并跳过该过期元数据。阶段四worker 完成回调与释放保护块worker 侧完成 store 后update_connector_output通过meta.completed_store_requests获取各请求的完成计数当计数满足条件时调用_gpu_block_pool.free_blocks释放被保护的 GPU 块、从_pending_store移除块 ID 记录并调用end_session(req_id)见 lmcache_mp_connector.py。触发时机的两个重要限制只在非空调度步骤触发_process_lazy_offload_store_requests仅在scheduler_output.total_num_scheduled_tokens 0时被调用。源码注释明确解释了原因若总调度 token 数为 0vLLM 的gpu_model_runner会走kv_connector_no_forward路径导致部分 store 操作丢失见 lmcache_mp_connector.py。待处理请求低于阈值、或流量空闲后遗留的尾部请求都不会被自动冲刷。因此懒卸载最适合连续型服务负载continuous serving workloads不适合要求每个请求 KV cache 立即持久化的任务。四、正确性保障块复用时的哈希校验这是懒卸载设计中至关重要的一点请求被选中之前懒卸载不会 pin 它的 GPU 块vLLM 可能把那些块复用于其他请求。连接器通过在两个时间点记录/校验块哈希来防止缓存错误数据缓冲 store 元数据时add记录每个块的block_hash卸载提交前_process_lazy_offload_store_requests重新读取哈希并比对。若块已被复用哈希不一致连接器记录 warning 并跳过该过期 store 元数据而不是把错误的 KV 数据写入缓存。后续对缺失数据的查询将变为 cache missvLLM 会重新计算对应 token——推理正确性完全不受影响代价只是损失一次缓存命中机会。测试用例也验证了这一语义pop_items_for_offload只弹出已完成的请求跳过未完成的且弹出的 item 会从 pending 队列移除并递减就绪计数见 test_lazy_offload_pending_store.py。五、选择计数与就绪计数的联动语义一个需要精确理解的细节被选中的请求会从就绪计数中移除。以阈值为 20、select count 为 10 为例第一次触发时提交 10 个请求剩余 10 个仍处于就绪状态必须再有 10 个请求完成后就绪计数才能重新达到 20从而触发下一批。也就是说阈值衡量的是触发条件当前就绪请求数而不是每批必须清空多少。两个参数都要求配置为正整数。test_pop_items_for_offload_multiple_batches用例完整验证了这种分批语义阈值 1、select count 2 时6 个请求会依次被弹出为 3 批见 test_lazy_offload_pending_store.py。另外pop_items_for_offload对count 0直接返回空列表见 lazy_offload_policy/fifo.py这也解释了为什么 select count 必须为正整数。六、调优指南四个参数的组合策略何时降低lmcache.mp.lazy_offload_threshold缓存需要更早可复用或**流量呈短突发short bursts**时调低阈值会带来更频繁的卸载批次极端情况下可用lmcache.mp.lazy_offload_threshold1获得最早的触发资格但请牢记提交仍需要一个后续的非空调度步骤它不会让卸载立即发生。何时提高阈值想延迟更多 store 工作、减少卸载频率时代价是更长的延迟以及vLLM 在卸载前复用待处理 GPU 块的几率增大更多请求会被哈希校验跳过。如何调整lmcache.mp.lazy_offload_select_count调大每次触发时排空更多请求产生更大的 store 突发burst适合存储带宽充裕、想减少触发次数的场景调小把工作摊薄到更多次阈值跨越中卸载更平滑但触发更频繁。与 LMCache 其他配置的关系懒卸载选项属于kv_connector_extra_config与lmcache.mp.host、lmcache.mp.port等连接器参数并列。若需要按租户、TTL 等维度做请求级控制可在请求的kv_transfer_params中携带lmcache.前缀的键详见 configuration.rst但注意该文档特别提示MP server 目前将请求级配置视为元数据不依赖其做隔离或过期控制。七、适用前提与限制总结维度结论前置条件仅 vLLM LMCacheMPConnectorLMCache server 无需额外 flag默认状态关闭lmcache.mp.lazy_offloadfalse触发时机就绪请求数 ≥ 阈值且处于非空调度步骤策略支持仅FIFO当前正确性哈希校验 跳过过期元数据最多损失缓存命中不影响推理正确性尾部请求低于阈值或流量空闲时不自动冲刷推荐场景连续型在线服务continuous serving对即时缓存可用性不敏感从工程实践看懒卸载的本质是用缓存可用性的延迟换取每步路径上 offload 开销的降低。如果你的服务是持续有流量的在线推理且 KV cache 稍晚几秒可复用完全可接受那么开启懒卸载并配合合理的阈值与 select count是一条低成本的吞吐优化路径反之若每个请求的 KV 都必须立刻落盘例如强一致性的离线批处理则应保持默认的 eager 行为。延伸阅读lazy_offload.rst本功能原始设计文档lmcache_mp_connector.py连接器实现含懒卸载触发与哈希校验逻辑lazy_offload_pending_store.py待处理 store 队列实现lazy_offload_policy/fifo.py 与 lazy_offload_policy/base.pyFIFO 策略与抽象接口test_lazy_offload_pending_store.py策略与队列的单元测试configuration.rstLMCache MP server 配置参考【免费下载链接】LMCacheLMCache: Supercharge Your LLM with the Fastest KV Cache Layer项目地址: https://gitcode.com/GitHub_Trending/lm/LMCache创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考