LMCache KV Cache 源码深度解析cache_engine.py 缓存机制完整拆解【免费下载链接】LMCacheLMCache: Supercharge Your LLM with the Fastest KV Cache Layer项目地址: https://gitcode.com/GitHub_Trending/lm/LMCache本文以 cache_engine.py 为主线完整拆解 LMCache 如何为大模型推理存储、查找并复用 KV 缓存回答一个核心问题为什么重复的长前缀请求不必从头重算。刚接触这个项目的你读完能直接跟上它的数据流向。 它到底在解决什么痛点LMCache 瞄准的是一个很具体的成本问题长上下文请求正在反复执行昂贵的重复计算。先给个名词对齐KV 缓存模型推理到一半时暂存的中间状态避免下一轮请求从头重算。多轮对话、RAG检索增强生成把查到的文档塞进上下文再提问这类负载里前缀往往高度重复——同样的系统提示、同样的文档段落被送进模型一遍又一遍每次都要重新做 prefill预填充生成第一个 token 前的整段上下文计算首 token 延迟TTFT随上下文长度线性恶化GPU 时间大量耗在算过的东西上。换句话说钱和延迟都烧在了重复劳动上这就是 LMCache 存在的理由。️ 一张图看懂整体架构核心就四个角色引擎、哈希库、搬运工、存储管家。示意图为作者根据源码绘制。你只需要记住一条流向推理引擎把 token 序列和 GPU 上的 KV 张量交给LMCacheEngineTokenDatabase负责把 token 变成缓存键GPUConnector负责数据在 GPU 和 CPU 之间搬家StorageManager统一管理内存块并对接各类存储后端。写入和读取就是这条链路的正放与倒放。⚙️ 三个关键机制深挖这三个机制分别回答块怎么编号键怎么防串数据怎么落盘看懂它们整个引擎就通了。分块与链式前缀哈希chunk 编号是怎么算出来的做什么把长 token 序列切成固定大小的 chunk块缓存的最小存取单位默认 256 个 token每个块独立编号、独立存取。怎么做编号不是一次性算完的而是边切边算当前块的哈希以上一块的哈希为输入prefix_hash self._get_init_hash() for token_chunk in token_chunks: prefix_hash self._hash_tokens(token_chunk, prefix_hash) yield prefix_hash白话上一块的指纹和当前块的内容一起喂进哈希函数产出当前块的编号。为什么这么设计这就像接力赛——上一棒选手的指纹决定下一棒的编号。好处有二其一前缀中任何一个 token 变化后面所有块的编号全部失效前缀完全相同成为缓存可复用的充要条件天然杜绝张冠李戴其二后续请求可以在已有前缀哈希上增量续算不必对整条序列重哈希。复合缓存键 CacheEngineKey不同任务怎么不撞库做什么给每个块生成一个带上下文的唯一键让不同模型、不同并行配置的缓存互不干扰。怎么做键不是裸哈希而是一个多维结构定义在lmcache的 utils 模块里dataclass(slotsTrue) class CacheEngineKey: model_name: str world_size: int chunk_hash: int白话模型名、并行规模、块哈希等字段共同组成键缺一维都可能让两条不同的缓存撞上同一个键。为什么这么设计张量并行把一层拆到多卡场景下同样的 token 在不同 worker进程上算出的 KV 内容不同必须用 worker_id 区分模型名与精度dtype不同则张量布局不同。多维键让可复用这件事在集群里是安全的而不只在一台机器上成立。内存对象与批量 I/O一次写入为什么只搬一次做什么KV 张量不直接进存储先转成 MemoryObj内存对象带引用计数的连续 CPU 内存块再统一搬运。怎么做store方法里先给每个块分配内存对象然后两次批量调用完成全部搬运self.gpu_connector.batched_from_gpu(memory_objs, starts, ends, **kwargs) self.storage_manager.batched_put(keys, memory_objs, transfer_spec...)白话先一次性把多块 KV 从 GPU 拉到 CPU再一次性批量写入后端全程只有两个大动作。为什么这么设计PCIe、RDMA 这类总线的单次调用开销不低逐块搬运会把时间花在起步上批量操作把固定成本摊薄到每个块上。引用计数则解决了这块内存还有谁在用的问题取完自动回收。 写进去 vs 取出来一条完整调用链跟着一次真实请求走一遍。写入时你调用store(tokens..., mask...)引擎先做健康检查不健康直接跳过绝不拖垮推理和冻结检查冻结模式只读不写然后stats_monitor记下这笔请求开始统计。接着token_database.process_tokens边切块边产出一串 (start, end, key)引擎为每个块分配 MemoryObj若本地内存吃紧则只存到存满为止优雅降级而不是报错。最后就是上面那两个批量调用GPU→CPU 拉取、落盘统计收尾。读取时故事倒放但多了一个关键动作。retrieve(tokens)用同一套哈希链重算出键序列get_block_mapping查明每块在哪个后端batched_get批量取出内存对象并逐个打上命中掩码。真正体现工程细节的是缺块处理if last_failed_block_start is not None: ret_mask[last_failed_block_start:] False白话从第一个缺失块开始后面全部作废。哪怕缓存里其实还存着后面的块只要前缀断了一环就不给用——因为断点之后的 KV 依赖断点前的状态单独拿出来是错的。最后batched_to_gpu把命中的连续前缀写回 GPU引用计数归零统计模块记下取回多少 token、耗时多少返回给引擎一张布尔掩码标记哪些 token 命中。⚖️ 关键设计取舍与工程收益用块键不独立换前缀增量校验。链式哈希的代价是任意前缀变更会连带废掉后续全部块收益是命中判断可以前缀式增量推进且跨进程共享缓存时哈希语义一致源码里对未设PYTHONHASHSEED的分布式场景有显式告警。用攒够再搬换单次传输吞吐。批量 I/O 要求先收齐块再动手多了一点点排队延迟但省掉的是每块一次的总线起步成本retrieve 中的源码注释给出了量级参照save_only_first_rank模式下leader rank 走 PCIe 的batched_to_gpu约 9 ms其余 rank 读 HBM 约 0.5 ms出处cache_engine.py 源码注释说明数据驻留位置对关键路径是数量级的影响。用缺一环全断换语义正确性。前缀截断会放弃本可命中的尾部块命中率不是最高但保证交给 attention 的 KV 在因果上严格连续。同样的截断逻辑在注释里还给了个直观例子page_size16、chunk_size256 时命中 512 token 而引擎只需 224 token重叠部分直接覆盖出处cache_engine.py retrieve 注释。可量化的收益侧项目 README 记载新的多进程架构将 MoE 推理性能提升 10 倍出处README.md 2026/04 条目而 TTFT、吞吐等指标的系统化测量工具在 benchmarks/rag/README.md它按请求记录 TTFT 与吞吐是验证你本地调优是否有效的入口。 上手路径与延伸阅读最小可运行入口examples/basic_check/一个配置文件加一个校验脚本适合先跑通再谈原理。源码阅读顺序建议三步走先读 cache_engine.py 的store与retrieve两个主干约两百行就能抓住骨架再读 token_database.py 看键是怎么算出来的最后读 storage_manager.py 理解内存块与后端的对接。延伸阅读看 benchmarks/rag/README.md里面写清了如何分别启动带 LMCache 与不带 LMCache 的服务做 A/B 对比。 收束顺着store_layer往下挖一层它是边算边按层落盘的生成器思考一下这条流水线如何与抢占、驱逐策略互相配合。【免费下载链接】LMCacheLMCache: Supercharge Your LLM with the Fastest KV Cache Layer项目地址: https://gitcode.com/GitHub_Trending/lm/LMCache创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 LMCache KV Cache 源码深度解析：cache_engine.py 缓存机制完整拆解
LMCache KV Cache 源码深度解析cache_engine.py 缓存机制完整拆解【免费下载链接】LMCacheLMCache: Supercharge Your LLM with the Fastest KV Cache Layer项目地址: https://gitcode.com/GitHub_Trending/lm/LMCache本文以 cache_engine.py 为主线完整拆解 LMCache 如何为大模型推理存储、查找并复用 KV 缓存回答一个核心问题为什么重复的长前缀请求不必从头重算。刚接触这个项目的你读完能直接跟上它的数据流向。 它到底在解决什么痛点LMCache 瞄准的是一个很具体的成本问题长上下文请求正在反复执行昂贵的重复计算。先给个名词对齐KV 缓存模型推理到一半时暂存的中间状态避免下一轮请求从头重算。多轮对话、RAG检索增强生成把查到的文档塞进上下文再提问这类负载里前缀往往高度重复——同样的系统提示、同样的文档段落被送进模型一遍又一遍每次都要重新做 prefill预填充生成第一个 token 前的整段上下文计算首 token 延迟TTFT随上下文长度线性恶化GPU 时间大量耗在算过的东西上。换句话说钱和延迟都烧在了重复劳动上这就是 LMCache 存在的理由。️ 一张图看懂整体架构核心就四个角色引擎、哈希库、搬运工、存储管家。示意图为作者根据源码绘制。你只需要记住一条流向推理引擎把 token 序列和 GPU 上的 KV 张量交给LMCacheEngineTokenDatabase负责把 token 变成缓存键GPUConnector负责数据在 GPU 和 CPU 之间搬家StorageManager统一管理内存块并对接各类存储后端。写入和读取就是这条链路的正放与倒放。⚙️ 三个关键机制深挖这三个机制分别回答块怎么编号键怎么防串数据怎么落盘看懂它们整个引擎就通了。分块与链式前缀哈希chunk 编号是怎么算出来的做什么把长 token 序列切成固定大小的 chunk块缓存的最小存取单位默认 256 个 token每个块独立编号、独立存取。怎么做编号不是一次性算完的而是边切边算当前块的哈希以上一块的哈希为输入prefix_hash self._get_init_hash() for token_chunk in token_chunks: prefix_hash self._hash_tokens(token_chunk, prefix_hash) yield prefix_hash白话上一块的指纹和当前块的内容一起喂进哈希函数产出当前块的编号。为什么这么设计这就像接力赛——上一棒选手的指纹决定下一棒的编号。好处有二其一前缀中任何一个 token 变化后面所有块的编号全部失效前缀完全相同成为缓存可复用的充要条件天然杜绝张冠李戴其二后续请求可以在已有前缀哈希上增量续算不必对整条序列重哈希。复合缓存键 CacheEngineKey不同任务怎么不撞库做什么给每个块生成一个带上下文的唯一键让不同模型、不同并行配置的缓存互不干扰。怎么做键不是裸哈希而是一个多维结构定义在lmcache的 utils 模块里dataclass(slotsTrue) class CacheEngineKey: model_name: str world_size: int chunk_hash: int白话模型名、并行规模、块哈希等字段共同组成键缺一维都可能让两条不同的缓存撞上同一个键。为什么这么设计张量并行把一层拆到多卡场景下同样的 token 在不同 worker进程上算出的 KV 内容不同必须用 worker_id 区分模型名与精度dtype不同则张量布局不同。多维键让可复用这件事在集群里是安全的而不只在一台机器上成立。内存对象与批量 I/O一次写入为什么只搬一次做什么KV 张量不直接进存储先转成 MemoryObj内存对象带引用计数的连续 CPU 内存块再统一搬运。怎么做store方法里先给每个块分配内存对象然后两次批量调用完成全部搬运self.gpu_connector.batched_from_gpu(memory_objs, starts, ends, **kwargs) self.storage_manager.batched_put(keys, memory_objs, transfer_spec...)白话先一次性把多块 KV 从 GPU 拉到 CPU再一次性批量写入后端全程只有两个大动作。为什么这么设计PCIe、RDMA 这类总线的单次调用开销不低逐块搬运会把时间花在起步上批量操作把固定成本摊薄到每个块上。引用计数则解决了这块内存还有谁在用的问题取完自动回收。 写进去 vs 取出来一条完整调用链跟着一次真实请求走一遍。写入时你调用store(tokens..., mask...)引擎先做健康检查不健康直接跳过绝不拖垮推理和冻结检查冻结模式只读不写然后stats_monitor记下这笔请求开始统计。接着token_database.process_tokens边切块边产出一串 (start, end, key)引擎为每个块分配 MemoryObj若本地内存吃紧则只存到存满为止优雅降级而不是报错。最后就是上面那两个批量调用GPU→CPU 拉取、落盘统计收尾。读取时故事倒放但多了一个关键动作。retrieve(tokens)用同一套哈希链重算出键序列get_block_mapping查明每块在哪个后端batched_get批量取出内存对象并逐个打上命中掩码。真正体现工程细节的是缺块处理if last_failed_block_start is not None: ret_mask[last_failed_block_start:] False白话从第一个缺失块开始后面全部作废。哪怕缓存里其实还存着后面的块只要前缀断了一环就不给用——因为断点之后的 KV 依赖断点前的状态单独拿出来是错的。最后batched_to_gpu把命中的连续前缀写回 GPU引用计数归零统计模块记下取回多少 token、耗时多少返回给引擎一张布尔掩码标记哪些 token 命中。⚖️ 关键设计取舍与工程收益用块键不独立换前缀增量校验。链式哈希的代价是任意前缀变更会连带废掉后续全部块收益是命中判断可以前缀式增量推进且跨进程共享缓存时哈希语义一致源码里对未设PYTHONHASHSEED的分布式场景有显式告警。用攒够再搬换单次传输吞吐。批量 I/O 要求先收齐块再动手多了一点点排队延迟但省掉的是每块一次的总线起步成本retrieve 中的源码注释给出了量级参照save_only_first_rank模式下leader rank 走 PCIe 的batched_to_gpu约 9 ms其余 rank 读 HBM 约 0.5 ms出处cache_engine.py 源码注释说明数据驻留位置对关键路径是数量级的影响。用缺一环全断换语义正确性。前缀截断会放弃本可命中的尾部块命中率不是最高但保证交给 attention 的 KV 在因果上严格连续。同样的截断逻辑在注释里还给了个直观例子page_size16、chunk_size256 时命中 512 token 而引擎只需 224 token重叠部分直接覆盖出处cache_engine.py retrieve 注释。可量化的收益侧项目 README 记载新的多进程架构将 MoE 推理性能提升 10 倍出处README.md 2026/04 条目而 TTFT、吞吐等指标的系统化测量工具在 benchmarks/rag/README.md它按请求记录 TTFT 与吞吐是验证你本地调优是否有效的入口。 上手路径与延伸阅读最小可运行入口examples/basic_check/一个配置文件加一个校验脚本适合先跑通再谈原理。源码阅读顺序建议三步走先读 cache_engine.py 的store与retrieve两个主干约两百行就能抓住骨架再读 token_database.py 看键是怎么算出来的最后读 storage_manager.py 理解内存块与后端的对接。延伸阅读看 benchmarks/rag/README.md里面写清了如何分别启动带 LMCache 与不带 LMCache 的服务做 A/B 对比。 收束顺着store_layer往下挖一层它是边算边按层落盘的生成器思考一下这条流水线如何与抢占、驱逐策略互相配合。【免费下载链接】LMCacheLMCache: Supercharge Your LLM with the Fastest KV Cache Layer项目地址: https://gitcode.com/GitHub_Trending/lm/LMCache创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考