LMCache CacheBlend 实战指南突破前缀缓存的非前缀 KV 复用【免费下载链接】LMCacheLMCache: Supercharge Your LLM with the Fastest KV Cache Layer项目地址: https://gitcode.com/GitHub_Trending/lm/LMCache导读CacheBlend 是 LMCache 提供的 KV Cache 复用扩展其核心价值在于任意位置出现的重复文本块都能命中缓存而不局限于共享前缀。它在块边界有选择性地重计算少量 token从而显著降低 RAG、多文档问答等可复用上下文并非干净前缀场景下的首 token 延迟TTFT。读完本文你将掌握MP多进程模式下如何一键启用 blend 引擎、配套服务器参数与联动配置in-process进程内已弃用模式下 CacheBlend 的完整配置项与 RAG 端到端示例以及BlendModule在源码层的实现原理指纹匹配、统一查找、分段前缀等帮助你直接在生产集群中落地非前缀缓存复用。什么是 CacheBlend从前缀命中到任意块命中传统前缀缓存prefix caching只能复用输入序列开头连续重叠的部分一旦两个请求在某个位置分叉分叉点之后的 KV Cache 全部失效必须从头重算。而在 RAG、多文档 QA 等场景中多次请求往往共享的是文档片段——它们以不同的顺序、不同的位置出现在不同的 prompt 里几乎没有公共前缀。CacheBlend 的思路源于论文CacheBlend: Fast Large Language Model Serving with Cached Knowledge Fusion是在存储阶段把写入的 KV Cache 按块chunk切分并建立内容指纹索引不依赖这块内容出现在什么位置在查找阶段对当前 prompt 做任意偏移的 token 级探测找出其中哪些块与已缓存内容重复命中后把已缓存的块直接拼装进当前请求只对块边界处的少量 token 进行重计算恢复拼接带来的注意力上下文偏差。正如 LMCache 文档所总结的CacheBlend 让 LMCache 可以复用任何重复文本块的 KV 缓存而不只是共享前缀——通过在块边界选择性地重计算一小部分 token 实现这削减了 RAG 和多文档负载的 TTFT见 cacheblend.rst。在 MP 模式下启用 CacheBlendLMCache MP多进程模式是当前推荐的生产模式更完整的特性支持与更好性能。启用 CacheBlend 只需在启动服务器时指定--engine-type blendlmcache server --l1-size-gb 20 --eviction-policy LRU --engine-type blendblend引擎会把一个BlendModule组合进服务器multiprocess/server.py 中mp_config.engine_type blend时构建 blend 模块同时它有一个硬性约束--engine-type blend要求--supported-transfer-mode必须为lmcache_driven默认值或auto。原因在于BlendModule包装了LMCacheDrivenTransferModule的 STORE 路径来注册指纹并通过其cache_contexts读取跨模块的 GPU 状态见 multiprocess/modules/blend/module.py 的类注释只有 server-driven 传输路径STORE/RETRIEVE支持 CUDA IPC 与 CPU SHM才能支撑这种服务器侧拉取设备句柄 指纹注册的工作流。若选择纯engine_driven非 GPU 的 PREPARE/COMMIT 路径blend 引擎将无法工作。与 blend 引擎配套的服务器参数根据 mp/configuration.rst以下参数专为 CacheBlend--engine-type blend设计参数默认值说明--supported-transfer-modelmcache_driven服务器加载的 worker→server 传输路径blend 引擎要求lmcache_driven或auto--enable-segmented-prefixFalse仅 blend 引擎生效当中途mid-prefixL2 检索失败时保留带缺口的前缀让缺口之后的块继续留在 L1只重计算被丢弃的缺口段而不是把前缀在缺口处截断--enable-dedup-contentFalse仅 blend 引擎生效跳过对已索引内容的指纹注册使同一段文本在不同前缀下只被索引一次--chunk-size256KV 操作按 token 计的块大小同时是 CacheBlend 指纹匹配的基本单元应与 coordinator 的--chunk-size保持一致其中--enable-segmented-prefix与--enable-dedup-content的默认关闭状态正好对应BlendModule.__init__中的_segmented_prefix标志与传给BlendTokenRangeMatcher的dedup_content开关见 multiprocess/modules/blend/module.py。集群协调器coordinator侧的 CacheBlend 开关若需要在多服务器fleet维度做跨实例的 CacheBlend 复用可在 coordinator 上开启内容索引--enable-blend-lookup索引已存储的块内容使POST /directory/blend-lookup能提供集群级 CacheBlend 匹配。默认关闭因为对每次 store 做内容哈希会消耗 CPU且无 CacheBlend 时无用同时要求 MP 服务器开启--coordinator-event-reporting为其喂数据。--blend-probe-stride N两次 CacheBlend 匹配探测之间的位置间隔1表示在每个偏移量处探测获得完全召回默认1。仅在开启 blend lookup 时生效。以上参数说明见 cli/coordinator.rst。in-process进程内模式下的 CacheBlend 配置注意in-process 模式已被弃用。官方文档明确建议优先使用 MP 模式以获得更好的特性支持与性能见 blending.rst 顶部的警告。此处保留其配置说明一是作为理解 CacheBlend 工作机制的窗口二是为仍在使用旧版集成的读者提供参考。cacheblend.rst 也特别注明in-process 的 CacheBlend 文档如LMCACHE_ENABLE_BLENDING等配置旋钮与端到端示例完整保留在 Legacy 章节 kv_cache_optimizations/blending。核心配置项在 in-process 模式下CacheBlend 通过环境变量启用与调参# Enable blending in LMCache os.environ[LMCACHE_ENABLE_BLENDING] True # Separator string between different chunks os.environ[LMCACHE_BLEND_SPECIAL_STR] # # # Layerwise must be turned on when blending is enabled os.environ[LMCACHE_USE_LAYERWISE] True # Determining which tokens to recompute at layer 1 os.environ[LMCACHE_BLEND_CHECK_LAYERS] 1 # Ratio of tokens to recompute os.environ[LMCACHE_BLEND_RECOMPUTE_RATIOS] 0.15 # Optionally, we can use sparse attention to improve generation quality # by using more accurate attention mask if enable_sparse: os.environ[VLLM_ATTENTION_BACKEND] FLASHINFER os.environ[LMCACHE_EXTRA_CONFIG] {enable_sparse: true}各配置项含义与作用环境变量示例值作用LMCACHE_ENABLE_BLENDINGTrue总开关开启 LMCache 的 blending 功能LMCACHE_BLEND_SPECIAL_STR # # 不同块之间的分隔字符串LMCache 依据它切分并独立存储各块的 KV CacheLMCACHE_USE_LAYERWISETrue启用 blending 时必开。CacheBlend 基于 layerwise 代码路径实现以便流水线化重计算 加载从而掩盖 KV Cache 加载延迟参见 layerwise.rstLMCACHE_BLEND_CHECK_LAYERS1决定在 layer 1 处判定哪些 token 需要重计算LMCACHE_BLEND_RECOMPUTE_RATIOS0.15需要重计算的 token 比例VLLM_ATTENTION_BACKEND可选FLASHINFER配合稀疏注意力用更精确的 attention mask 提升生成质量LMCACHE_EXTRA_CONFIG可选{enable_sparse: true}向 LMCache 传递额外配置此处用于打开稀疏注意力RAG 场景端到端示例仓库在 examples/blend_in_process/blend.py 提供了完整可运行的示例其思路与 blending.rst 中的代码讲解一致。整个流程分三步第一步将文本预处理为 token。关键原因在于对拼接后的字符串做 tokenize与分别 tokenize 各字符串再拼接结果得到的 token 序列可能不同。因此必须先对每个块独立 encodesys_prompt tokenizer.encode(You are a very helpful assistant.) chunk1_prompt tokenizer.encode(Hello, how are you? * 500)[1:] chunk2_prompt tokenizer.encode(Hello, whats up? * 500)[1:] chunk3_prompt tokenizer.encode(Hi, what are you up to? * 500)[1:] blend_special_str tokenizer.encode(os.getenv(LMCACHE_BLEND_SPECIAL_STR))[1:] first_prompt ( sys_prompt blend_special_str chunk1_prompt blend_special_str chunk2_prompt blend_special_str chunk3_prompt blend_special_str tokenizer.encode(Hello, my name is)[1:] )第二步把 tokenized prompt 发给 vLLM。LMCACHE_ENABLE_BLENDINGTrue时LMCache 会按照LMCACHE_BLEND_SPECIAL_STR分隔符把不同 chunk 的 KV Cache 分别存储llm.generate(prompts{prompt_token_ids: first_prompt})第三步构造同一批块、不同顺序的第二个 prompt验证非前缀复用。second_prompt ( sys_prompt blend_special_str chunk2_prompt blend_special_str chunk1_prompt blend_special_str chunk3_prompt blend_special_str tokenizer.encode(Hello, how are you?)[1:] ) llm.generate(prompts{prompt_token_ids: second_prompt})尽管第二个 prompt 的块顺序与第一个完全不同无共享前缀LMCache 依然能复用 chunk1、chunk2、chunk3 的 KV Cache——这正是 CacheBlend非前缀复用的直接验证。完整示例还包含磁盘/内存后端切换--use-disk、分隔符自定义--blend-special-str、稀疏注意力--enable-sparse等命令行选项以及build_llm_with_lmcache中KVTransferConfig(kv_connectorLMCacheConnectorV1, kv_rolekv_both)的接入方式并显式关闭了 vLLM 自带前缀缓存enable_prefix_cachingFalse。源码级原理BlendModule 是如何工作的在 MP 模式下CacheBlend 的实体是BlendModule它由 4 个 mixin 与InstanceLivenessTarget组合而成见 multiprocess/modules/blend/module.pyBlendModule(LookupMixin, RegistrationMixin, RetrieveMixin, StoreMixin, InstanceLivenessTarget)各 mixin 的分工如下1. StoreMixin异步指纹注册存储路径BlendModule包装了LMCacheDrivenTransferModule.store分页存储在 worker 0 上把块哈希以流序stream-ordered的方式入队由后台cb-fingerprint-worker线程异步排空并注册指纹见 multiprocess/modules/blend/store.py。关键设计指纹注册失败只记日志、绝不抛出——不影响 store 的正确性未完成注册的指纹哈希_pending_fp_hashes会被 storage gate 保护防止被逐出懒逐出lazy eviction通过_stale_strike计数只有命中 2 次阈值才真正逐出给异步重存刷新桶的机会。2. BlendTokenRangeMatcher任意偏移的 token 级探测指纹匹配的核心是 multiprocess/modules/blend/matcher.py 中的BlendTokenRangeMatcher它在任意偏移处做 token 级探测注册阶段on_new_token_hashes对存储序列按chunk_size切分非重叠块用 numba 加速的chunk_hash_windows_numba计算每块的多项式哈希poly-hash写入2^20约 100 万槽位的直接寻址表_table_id启用dedup_content时跳过已注册的 poly 哈希匹配阶段match_sub_sequence对查询序列用滚动哈希rolling_hash_windows_numba在所有 token 位置做向量化直接寻址探测命中后用完整 poly 哈希拒绝桶冲突最后做一次 token 级全文哈希校验返回每个唯一复用块在旧序列中的起始位置old_st与在当前序列中的位置cur_st逐出阶段remove_chunks按 token 哈希从表中移除对应条目防止后续探测误命中。从源码看匹配精度是先粗筛后精验直接寻址表承担召回poly 哈希 全文哈希承担准确率而_unique_token_coverage会合并重叠区间统计真实 token 覆盖率滑窗探测可能返回重叠区间直接求和会重复计数。3. LookupMixin统一查找的状态机查找路径是一个四腿leg状态机见 multiprocess/modules/blend/lookup.pyprefix 腿常规前缀预取local-match 腿用本地BlendTokenRangeMatcher找非前缀匹配coordinator 腿向集群 coordinator 发起匹配查询BlendCoordinatorClient支持跨实例复用sparse 腿对非前缀命中块做稀疏预取。整个查找是非阻塞的_CBUnifiedJob记录每个请求的轮询状态匹配结果、prefix/sparse 句柄、分段标记等跨多次 poll 复用避免 handler 跨 L2→L1 加载持有 worker 线程。此外BlendModule通过Session.extras里的cb.unretrieved_read_locked_keys保留稀疏查找预留的读锁若请求从未发送CB_RETRIEVE_PRE_COMPUTED则在该请求的 session 销毁时统一释放这些读锁防止块被永久钉在 L1见 multiprocess/modules/blend/module.py 的_release_unretrieved_locks。4. RetrieveMixin 与 rope拼接与位置编码修正检索路径按请求级规划request-invariant plan工作缓存于_cb_plan_invariants并按 rope 状态失效每个 GPU context 拥有独立的 retrieve 专用流与完成事件避免与共享流上的 store gather/commit 流量竞争。同时 blend 模块维护_cb_rope_state_CBRopeState负责跨块拼接时的位置编码RoPE状态修正——这是 CacheBlend 在块边界重计算少量 token之外的第二个正确性支柱。常见问题与限制为什么必须 layerwiseCacheBlend 的重计算与加载需要按层流水线化以掩盖延迟因此 in-process 模式强制LMCACHE_USE_LAYERWISETrueMP 模式的 blend 引擎内置了分页感知的层级处理。MP 模式下请求级配置无效按 mp/configuration.rst 的说明vLLM 客户端通过kv_transfer_params中lmcache.前缀键转发请求元数据但转发本身不构成服务器端行为除非对应服务端特性明确支持否则不要依赖lmcache.tag.*、lmcache.ttl等做隔离或缓存控制。--isolated-ipc兼容性当前仅 vLLM MP connector 支持SGLang、TensorRT-LLM、CacheBlend、qstore 等集成仍创建原生 CUDA 进程间事件因此服务器端--isolated-ipc默认保持false。bench 工具验证CLI 的 bench 命令提供vLLM LMCache L1 L2 CacheBlend组合基准通过发送一组上下文片段的排列组合来压测混合 KV 复用见 cli/bench.rst可用于在开启 blend 引擎后量化收益。小结CacheBlend 把 LMCache 的复用能力从前缀扩展到任意位置MP 模式下--engine-type blend一键启用配合--supported-transfer-modelmcache_drined/auto与可选的--enable-segmented-prefix、--enable-dedup-content适合直接上生产in-process 模式已弃用则通过LMCACHE_ENABLE_BLENDING等环境变量在 RAG 场景做快速验证。底层BlendModule以分页存储 指纹注册 → 任意偏移滚动哈希匹配 → 统一查找状态机 → 拼接检索与 RoPE 修正的完整链路实现了文档中所承诺的复用任何重复文本块的 KV 缓存是 LMCache 面向 RAG / 多文档工作负载削减 TTFT 的关键能力。【免费下载链接】LMCacheLMCache: Supercharge Your LLM with the Fastest KV Cache Layer项目地址: https://gitcode.com/GitHub_Trending/lm/LMCache创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 LMCache CacheBlend 实战指南：突破前缀缓存的非前缀 KV 复用
LMCache CacheBlend 实战指南突破前缀缓存的非前缀 KV 复用【免费下载链接】LMCacheLMCache: Supercharge Your LLM with the Fastest KV Cache Layer项目地址: https://gitcode.com/GitHub_Trending/lm/LMCache导读CacheBlend 是 LMCache 提供的 KV Cache 复用扩展其核心价值在于任意位置出现的重复文本块都能命中缓存而不局限于共享前缀。它在块边界有选择性地重计算少量 token从而显著降低 RAG、多文档问答等可复用上下文并非干净前缀场景下的首 token 延迟TTFT。读完本文你将掌握MP多进程模式下如何一键启用 blend 引擎、配套服务器参数与联动配置in-process进程内已弃用模式下 CacheBlend 的完整配置项与 RAG 端到端示例以及BlendModule在源码层的实现原理指纹匹配、统一查找、分段前缀等帮助你直接在生产集群中落地非前缀缓存复用。什么是 CacheBlend从前缀命中到任意块命中传统前缀缓存prefix caching只能复用输入序列开头连续重叠的部分一旦两个请求在某个位置分叉分叉点之后的 KV Cache 全部失效必须从头重算。而在 RAG、多文档 QA 等场景中多次请求往往共享的是文档片段——它们以不同的顺序、不同的位置出现在不同的 prompt 里几乎没有公共前缀。CacheBlend 的思路源于论文CacheBlend: Fast Large Language Model Serving with Cached Knowledge Fusion是在存储阶段把写入的 KV Cache 按块chunk切分并建立内容指纹索引不依赖这块内容出现在什么位置在查找阶段对当前 prompt 做任意偏移的 token 级探测找出其中哪些块与已缓存内容重复命中后把已缓存的块直接拼装进当前请求只对块边界处的少量 token 进行重计算恢复拼接带来的注意力上下文偏差。正如 LMCache 文档所总结的CacheBlend 让 LMCache 可以复用任何重复文本块的 KV 缓存而不只是共享前缀——通过在块边界选择性地重计算一小部分 token 实现这削减了 RAG 和多文档负载的 TTFT见 cacheblend.rst。在 MP 模式下启用 CacheBlendLMCache MP多进程模式是当前推荐的生产模式更完整的特性支持与更好性能。启用 CacheBlend 只需在启动服务器时指定--engine-type blendlmcache server --l1-size-gb 20 --eviction-policy LRU --engine-type blendblend引擎会把一个BlendModule组合进服务器multiprocess/server.py 中mp_config.engine_type blend时构建 blend 模块同时它有一个硬性约束--engine-type blend要求--supported-transfer-mode必须为lmcache_driven默认值或auto。原因在于BlendModule包装了LMCacheDrivenTransferModule的 STORE 路径来注册指纹并通过其cache_contexts读取跨模块的 GPU 状态见 multiprocess/modules/blend/module.py 的类注释只有 server-driven 传输路径STORE/RETRIEVE支持 CUDA IPC 与 CPU SHM才能支撑这种服务器侧拉取设备句柄 指纹注册的工作流。若选择纯engine_driven非 GPU 的 PREPARE/COMMIT 路径blend 引擎将无法工作。与 blend 引擎配套的服务器参数根据 mp/configuration.rst以下参数专为 CacheBlend--engine-type blend设计参数默认值说明--supported-transfer-modelmcache_driven服务器加载的 worker→server 传输路径blend 引擎要求lmcache_driven或auto--enable-segmented-prefixFalse仅 blend 引擎生效当中途mid-prefixL2 检索失败时保留带缺口的前缀让缺口之后的块继续留在 L1只重计算被丢弃的缺口段而不是把前缀在缺口处截断--enable-dedup-contentFalse仅 blend 引擎生效跳过对已索引内容的指纹注册使同一段文本在不同前缀下只被索引一次--chunk-size256KV 操作按 token 计的块大小同时是 CacheBlend 指纹匹配的基本单元应与 coordinator 的--chunk-size保持一致其中--enable-segmented-prefix与--enable-dedup-content的默认关闭状态正好对应BlendModule.__init__中的_segmented_prefix标志与传给BlendTokenRangeMatcher的dedup_content开关见 multiprocess/modules/blend/module.py。集群协调器coordinator侧的 CacheBlend 开关若需要在多服务器fleet维度做跨实例的 CacheBlend 复用可在 coordinator 上开启内容索引--enable-blend-lookup索引已存储的块内容使POST /directory/blend-lookup能提供集群级 CacheBlend 匹配。默认关闭因为对每次 store 做内容哈希会消耗 CPU且无 CacheBlend 时无用同时要求 MP 服务器开启--coordinator-event-reporting为其喂数据。--blend-probe-stride N两次 CacheBlend 匹配探测之间的位置间隔1表示在每个偏移量处探测获得完全召回默认1。仅在开启 blend lookup 时生效。以上参数说明见 cli/coordinator.rst。in-process进程内模式下的 CacheBlend 配置注意in-process 模式已被弃用。官方文档明确建议优先使用 MP 模式以获得更好的特性支持与性能见 blending.rst 顶部的警告。此处保留其配置说明一是作为理解 CacheBlend 工作机制的窗口二是为仍在使用旧版集成的读者提供参考。cacheblend.rst 也特别注明in-process 的 CacheBlend 文档如LMCACHE_ENABLE_BLENDING等配置旋钮与端到端示例完整保留在 Legacy 章节 kv_cache_optimizations/blending。核心配置项在 in-process 模式下CacheBlend 通过环境变量启用与调参# Enable blending in LMCache os.environ[LMCACHE_ENABLE_BLENDING] True # Separator string between different chunks os.environ[LMCACHE_BLEND_SPECIAL_STR] # # # Layerwise must be turned on when blending is enabled os.environ[LMCACHE_USE_LAYERWISE] True # Determining which tokens to recompute at layer 1 os.environ[LMCACHE_BLEND_CHECK_LAYERS] 1 # Ratio of tokens to recompute os.environ[LMCACHE_BLEND_RECOMPUTE_RATIOS] 0.15 # Optionally, we can use sparse attention to improve generation quality # by using more accurate attention mask if enable_sparse: os.environ[VLLM_ATTENTION_BACKEND] FLASHINFER os.environ[LMCACHE_EXTRA_CONFIG] {enable_sparse: true}各配置项含义与作用环境变量示例值作用LMCACHE_ENABLE_BLENDINGTrue总开关开启 LMCache 的 blending 功能LMCACHE_BLEND_SPECIAL_STR # # 不同块之间的分隔字符串LMCache 依据它切分并独立存储各块的 KV CacheLMCACHE_USE_LAYERWISETrue启用 blending 时必开。CacheBlend 基于 layerwise 代码路径实现以便流水线化重计算 加载从而掩盖 KV Cache 加载延迟参见 layerwise.rstLMCACHE_BLEND_CHECK_LAYERS1决定在 layer 1 处判定哪些 token 需要重计算LMCACHE_BLEND_RECOMPUTE_RATIOS0.15需要重计算的 token 比例VLLM_ATTENTION_BACKEND可选FLASHINFER配合稀疏注意力用更精确的 attention mask 提升生成质量LMCACHE_EXTRA_CONFIG可选{enable_sparse: true}向 LMCache 传递额外配置此处用于打开稀疏注意力RAG 场景端到端示例仓库在 examples/blend_in_process/blend.py 提供了完整可运行的示例其思路与 blending.rst 中的代码讲解一致。整个流程分三步第一步将文本预处理为 token。关键原因在于对拼接后的字符串做 tokenize与分别 tokenize 各字符串再拼接结果得到的 token 序列可能不同。因此必须先对每个块独立 encodesys_prompt tokenizer.encode(You are a very helpful assistant.) chunk1_prompt tokenizer.encode(Hello, how are you? * 500)[1:] chunk2_prompt tokenizer.encode(Hello, whats up? * 500)[1:] chunk3_prompt tokenizer.encode(Hi, what are you up to? * 500)[1:] blend_special_str tokenizer.encode(os.getenv(LMCACHE_BLEND_SPECIAL_STR))[1:] first_prompt ( sys_prompt blend_special_str chunk1_prompt blend_special_str chunk2_prompt blend_special_str chunk3_prompt blend_special_str tokenizer.encode(Hello, my name is)[1:] )第二步把 tokenized prompt 发给 vLLM。LMCACHE_ENABLE_BLENDINGTrue时LMCache 会按照LMCACHE_BLEND_SPECIAL_STR分隔符把不同 chunk 的 KV Cache 分别存储llm.generate(prompts{prompt_token_ids: first_prompt})第三步构造同一批块、不同顺序的第二个 prompt验证非前缀复用。second_prompt ( sys_prompt blend_special_str chunk2_prompt blend_special_str chunk1_prompt blend_special_str chunk3_prompt blend_special_str tokenizer.encode(Hello, how are you?)[1:] ) llm.generate(prompts{prompt_token_ids: second_prompt})尽管第二个 prompt 的块顺序与第一个完全不同无共享前缀LMCache 依然能复用 chunk1、chunk2、chunk3 的 KV Cache——这正是 CacheBlend非前缀复用的直接验证。完整示例还包含磁盘/内存后端切换--use-disk、分隔符自定义--blend-special-str、稀疏注意力--enable-sparse等命令行选项以及build_llm_with_lmcache中KVTransferConfig(kv_connectorLMCacheConnectorV1, kv_rolekv_both)的接入方式并显式关闭了 vLLM 自带前缀缓存enable_prefix_cachingFalse。源码级原理BlendModule 是如何工作的在 MP 模式下CacheBlend 的实体是BlendModule它由 4 个 mixin 与InstanceLivenessTarget组合而成见 multiprocess/modules/blend/module.pyBlendModule(LookupMixin, RegistrationMixin, RetrieveMixin, StoreMixin, InstanceLivenessTarget)各 mixin 的分工如下1. StoreMixin异步指纹注册存储路径BlendModule包装了LMCacheDrivenTransferModule.store分页存储在 worker 0 上把块哈希以流序stream-ordered的方式入队由后台cb-fingerprint-worker线程异步排空并注册指纹见 multiprocess/modules/blend/store.py。关键设计指纹注册失败只记日志、绝不抛出——不影响 store 的正确性未完成注册的指纹哈希_pending_fp_hashes会被 storage gate 保护防止被逐出懒逐出lazy eviction通过_stale_strike计数只有命中 2 次阈值才真正逐出给异步重存刷新桶的机会。2. BlendTokenRangeMatcher任意偏移的 token 级探测指纹匹配的核心是 multiprocess/modules/blend/matcher.py 中的BlendTokenRangeMatcher它在任意偏移处做 token 级探测注册阶段on_new_token_hashes对存储序列按chunk_size切分非重叠块用 numba 加速的chunk_hash_windows_numba计算每块的多项式哈希poly-hash写入2^20约 100 万槽位的直接寻址表_table_id启用dedup_content时跳过已注册的 poly 哈希匹配阶段match_sub_sequence对查询序列用滚动哈希rolling_hash_windows_numba在所有 token 位置做向量化直接寻址探测命中后用完整 poly 哈希拒绝桶冲突最后做一次 token 级全文哈希校验返回每个唯一复用块在旧序列中的起始位置old_st与在当前序列中的位置cur_st逐出阶段remove_chunks按 token 哈希从表中移除对应条目防止后续探测误命中。从源码看匹配精度是先粗筛后精验直接寻址表承担召回poly 哈希 全文哈希承担准确率而_unique_token_coverage会合并重叠区间统计真实 token 覆盖率滑窗探测可能返回重叠区间直接求和会重复计数。3. LookupMixin统一查找的状态机查找路径是一个四腿leg状态机见 multiprocess/modules/blend/lookup.pyprefix 腿常规前缀预取local-match 腿用本地BlendTokenRangeMatcher找非前缀匹配coordinator 腿向集群 coordinator 发起匹配查询BlendCoordinatorClient支持跨实例复用sparse 腿对非前缀命中块做稀疏预取。整个查找是非阻塞的_CBUnifiedJob记录每个请求的轮询状态匹配结果、prefix/sparse 句柄、分段标记等跨多次 poll 复用避免 handler 跨 L2→L1 加载持有 worker 线程。此外BlendModule通过Session.extras里的cb.unretrieved_read_locked_keys保留稀疏查找预留的读锁若请求从未发送CB_RETRIEVE_PRE_COMPUTED则在该请求的 session 销毁时统一释放这些读锁防止块被永久钉在 L1见 multiprocess/modules/blend/module.py 的_release_unretrieved_locks。4. RetrieveMixin 与 rope拼接与位置编码修正检索路径按请求级规划request-invariant plan工作缓存于_cb_plan_invariants并按 rope 状态失效每个 GPU context 拥有独立的 retrieve 专用流与完成事件避免与共享流上的 store gather/commit 流量竞争。同时 blend 模块维护_cb_rope_state_CBRopeState负责跨块拼接时的位置编码RoPE状态修正——这是 CacheBlend 在块边界重计算少量 token之外的第二个正确性支柱。常见问题与限制为什么必须 layerwiseCacheBlend 的重计算与加载需要按层流水线化以掩盖延迟因此 in-process 模式强制LMCACHE_USE_LAYERWISETrueMP 模式的 blend 引擎内置了分页感知的层级处理。MP 模式下请求级配置无效按 mp/configuration.rst 的说明vLLM 客户端通过kv_transfer_params中lmcache.前缀键转发请求元数据但转发本身不构成服务器端行为除非对应服务端特性明确支持否则不要依赖lmcache.tag.*、lmcache.ttl等做隔离或缓存控制。--isolated-ipc兼容性当前仅 vLLM MP connector 支持SGLang、TensorRT-LLM、CacheBlend、qstore 等集成仍创建原生 CUDA 进程间事件因此服务器端--isolated-ipc默认保持false。bench 工具验证CLI 的 bench 命令提供vLLM LMCache L1 L2 CacheBlend组合基准通过发送一组上下文片段的排列组合来压测混合 KV 复用见 cli/bench.rst可用于在开启 blend 引擎后量化收益。小结CacheBlend 把 LMCache 的复用能力从前缀扩展到任意位置MP 模式下--engine-type blend一键启用配合--supported-transfer-modelmcache_drined/auto与可选的--enable-segmented-prefix、--enable-dedup-content适合直接上生产in-process 模式已弃用则通过LMCACHE_ENABLE_BLENDING等环境变量在 RAG 场景做快速验证。底层BlendModule以分页存储 指纹注册 → 任意偏移滚动哈希匹配 → 统一查找状态机 → 拼接检索与 RoPE 修正的完整链路实现了文档中所承诺的复用任何重复文本块的 KV 缓存是 LMCache 面向 RAG / 多文档工作负载削减 TTFT 的关键能力。【免费下载链接】LMCacheLMCache: Supercharge Your LLM with the Fastest KV Cache Layer项目地址: https://gitcode.com/GitHub_Trending/lm/LMCache创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考