LMCache 外部 KV Cache 压缩实战：通过 Cache Controller API 对请求 KV Cache 进行 CacheGen 压缩与解压-北京尧图网络

LMCache 外部 KV Cache 压缩实战通过 Cache Controller API 对请求 KV Cache 进行 CacheGen 压缩与解压【免费下载链接】LMCacheLMCache: Supercharge Your LLM with the Fastest KV Cache Layer项目地址: https://gitcode.com/GitHub_Trending/lm/LMCache导读本文基于 LMCache 仓库中的 compress 示例完整演示如何在不修改 vLLM 推理流程的前提下通过外部 HTTP API 对某个请求的 KV cache 进行压缩compress与解压decompress。读完本文你将掌握 Cache Controller 模式下端口规划、配置要点以及从 HTTP 请求到 worker 端实际执行的完整调用链并理解 CacheGen 压缩方法在 LMCache 引擎内部的工作机制。一、示例定位外部编排 KV cache 生命周期LMCache 提供了一系列编排式orchestrationHTTP API用于在推理引擎之外对 KV cache 进行路由和热迁移例如 KV cache 查询lookup、移动move、清除clear、固定pin以及本文要讲的压缩 / 解压compress / decompress。相关示例的入口汇总在 examples/cache_controller/README.md其中 compress 示例专注于对一个已完成推理的请求的 KV cache在它被卸载offload到 CPU 之后通过外部 API 触发压缩以进一步节省存储或通过解压还原以便后续复用。整个流程由三部分组成组件端口作用vLLM 引擎8000承载推理挂载 LMCacheConnectorV1 连接器LMCache worker8001实际执行缓存读写与压缩的 LMCache 工作进程Cache Controller含 monitor9000 / 9001接收外部编排 API 请求并分发到各 worker其中 controller 的 9000 端口是编排 API 服务端口9001 是 monitor 端口二者在启动lmcache_controller时一并拉起。二、前置条件与端口规划根据原文档运行本示例需要满足服务器上至少 1 张 GPU端口占用规划vLLM 使用8000LMCache worker 使用8001controller 本身占用9000和9001示例使用meta-llama/Llama-3.1-8B-Instruct模型需要预先准备好该模型权重。端口信息直接决定了后续所有命令的地址拼接vLLM 的补全completions与 tokenize 请求发往localhost:8000压缩/解压编排请求发往localhost:9000worker 通过配置中的controller_pull_url: localhost:9001与 controller 的 monitor 端口保持心跳与注册。三、配置文件 example.yaml 详解示例目录下的 example.yaml 是 vLLM 启动时必须通过LMCACHE_CONFIG_FILE环境变量加载的 LMCache 配置全文如下chunk_size: 256 local_cpu: True max_local_cpu_size: 5 # cache controller configurations enable_controller: True lmcache_instance_id: lmcache_default_instance controller_pull_url: localhost:9001 lmcache_worker_ports: 8001 # Peer identifiers p2p_host: localhost p2p_init_ports: 8200各配置项的作用如下chunk_size: 256KV cache 的分块粒度。LMCache 将 KV cache 按固定 token 数切分成块进行缓存与寻址256 表示每块最多容纳 256 个 token 的 KV 数据。块越小寻址越精细块越大序列化与压缩开销越低需要结合请求长度权衡。local_cpu: True与max_local_cpu_size: 5启用本地 CPU 后端即LocalCPUBackend并将 CPU 侧缓存容量上限设置为 5单位 GB。这解释了为何示例中 KV cache 会被自动卸载到 CPU——vLLM 请求结束后LMCache 默认策略会把 KV cache 从 GPU 上移出并写入该 CPU 后端。enable_controller: True开启 Cache Controller 模式使 worker 能与外部 controller 建立连接、接收编排指令这是/compress、/decompressAPI 可用的前提。lmcache_instance_id: lmcache_default_instance当前推理实例的标识。注意它必须与压缩 API 请求体中的instance_id字段保持一致否则 controller 无法定位到对应的 worker 集合。controller_pull_url: localhost:9001worker 向 controller 的 monitor 端口注册与拉取信息的地址。lmcache_worker_ports: 8001worker 进程监听的端口。p2p_host/p2p_init_ports: 8200多实例 P2P 通信的对端标识与初始端口用于多机多实例场景下的 peer 发现单实例演示中保持 localhost 即可。四、完整操作步骤步骤 1启动 vLLM 引擎端口 8000CUDA_VISIBLE_DEVICES0 LMCACHE_CONFIG_FILEexample.yaml vllm serve meta-llama/Llama-3.1-8B-Instruct --gpu-memory-utilization 0.8 --port 8000 --kv-transfer-config {kv_connector:LMCacheConnectorV1, kv_role:kv_both}要点说明CUDA_VISIBLE_DEVICES0指定使用 0 号 GPULMCACHE_CONFIG_FILEexample.yaml让 vLLM 内部加载上一节所述的 LMCache 配置--gpu-memory-utilization 0.8为 KV cache 预留 80% 的 GPU 显存--kv-transfer-config中的kv_connector: LMCacheConnectorV1是 vLLM 与 LMCache 的 KV 传输连接器kv_role: kv_both表示该实例同时承担 KV cache 的生产存与消费取角色。该连接器对应的适配器实现位于 lmcache/integration/vllm启动成功后 vLLM 会在 8000 端口提供 OpenAI 兼容接口。步骤 2启动 Cache Controller9000 / 9001lmcache_controller --host localhost --port 9000 --monitor-port 9001lmcache_controller是随 LMCache 一起安装的命令行入口它会同时拉起 9000 端口的编排 API 服务和 9001 端口的 monitor 服务。步骤 3向 vLLM 发送一次推理请求curl -X POST http://localhost:8000/v1/completions \ -H Content-Type: application/json \ -d { model: meta-llama/Llama-3.1-8B-Instruct, prompt: Explain the significance of KV cache in language models., max_tokens: 10 }请求结束后LMCache 会自动将本次请求的 KV cache 卸载offload到 CPU 后端——这正是配置文件里local_cpu: True与max_local_cpu_size: 5所控制的默认行为也是后续能够对已落盘的缓存进行压缩的前提。步骤 4Tokenize 获取 token 序列压缩 API 需要以 token 列表定位缓存因此先用 vLLM 的 tokenize 接口拿到提示词的 token idcurl -X POST http://localhost:8000/tokenize \ -H Content-Type: application/json \ -d { model: meta-llama/Llama-3.1-8B-Instruct, prompt: Explain the significance of KV cache in language models. }返回结果{count:12,max_model_len:4096,tokens:[128000,849,21435,279,26431,315,85748,6636,304,4221,4211,13],token_strs:null}即提示词共 12 个 token其 id 序列为[128000, 849, 21435, 279, 26431, 315, 85748, 6636, 304, 4221, 4211, 13]。后续压缩与解压请求中的tokens字段必须与此一致LMCache 正是依据 token 前缀哈希来定位对应的缓存块。步骤 5使用 CacheGen 压缩请求的 KV cachecurl -X POST http://localhost:9000/compress \ -H Content-Type: application/json \ -d { instance_id: lmcache_default_instance, method: cachegen, location: LocalCPUBackend, tokens: [128000, 849, 21435, 279, 26431, 315, 85748, 6636, 304, 4221, 4211, 13] }成功后将返回类似下面的消息表示 KV cache 已开始被压缩{num_tokens: 12, event_id: xxx}其中num_tokens: 12表示系统中有 12 个 token 的 KV cache 正处于压缩流程中event_id是该次压缩操作的标识可用于后续查询压缩操作的状态该查询功能正在开发中coming soon。步骤 6使用 CacheGen 解压请求的 KV cachecurl -X POST http://localhost:9000/decompress \ -H Content-Type: application/json \ -d { instance_id: lmcache_default_instance, method: cachegen, location: LocalCPUBackend, tokens: [128000, 849, 21435, 279, 26431, 315, 85748, 6636, 304, 4221, 4211, 13] }返回消息与压缩时一致{num_tokens: 12, event_id: xxx}num_tokens: 12表示有 12 个 token 的 KV cache 正在被解压event_id同样可用于跟踪该解压操作。压缩与解压使用相同的定位方式因此解压时同样需要提供与压缩时一致的 token 列表与location。五、源码级原理一次压缩请求的完整调用链压缩示例看似只是两个 curl 命令其背后是一条从 controller 到 worker 引擎的完整调用链。以下沿关键文件逐步剖析。5.1 编排 API 入口/compress与/decompresscontroller 的 HTTP 路由定义在 lmcache/v1/api_server/main.py。压缩端点的大致逻辑为app.post(/compress, response_modelCompressResponse) async def compress(req: CompressRequest): event_id Compress str(uuid.uuid4()) msg CompressMsg( event_idevent_id, instance_idreq.instance_id, methodreq.method, locationreq.location, tokensreq.tokens, ) ret_msg await lmcache_controller_manager.handle_orchestration_message(msg) ... return CompressResponse(event_idret_msg.event_id, num_tokensret_msg.num_tokens)请求体CompressRequest包含instance_id、method、location、tokens四个字段与 curl 请求体一一对应响应体CompressResponse只含event_id与num_tokens这正是文档中看到的返回结构。/decompress端点结构完全对称DecompressRequest/DecompressResponse只是消息类型换为DecompressMsg。消息类本身定义在 lmcache/v1/cache_controller/message.py。5.2 消息分发与执行器handle_orchestration_message在 lmcache/v1/cache_controller/controller_manager.py 中按消息类型路由将CompressMsg/DecompressMsg交给 lmcache/v1/cache_controller/controllers/kv_controller.py 的compress/decompress方法最终落到 lmcache/v1/cache_controller/executor.py 的compress/decompress执行器。执行器的职责是把操作广播到该 instance 的所有 worker它通过注册中心reg_controller按instance_id获取 worker 列表及其 socket将CompressWorkerMsg以 msgspec.msgpack 编码后并发发送给每个 worker再汇总各 worker 的返回。代码中还有一个值得注意的一致性约束assert len(set(num_tokens_list)) 1, ( The number of tokens compressed should be the same across all workers. )即分布式TP场景下各 worker 压缩的 token 数必须一致否则视为异常。同时注释也标明当前实现暂不支持 PP 流水线并行与异构 TP分布式使用时需注意这一前提。5.3 worker 端引擎实现LMCacheEngine.compress / decompress真正执行压缩的逻辑在 lmcache/v1/cache_engine.py 的compress约 L1424 起与decompress约 L1483 起方法。compress的核心流程如下方法校验仅接受method cachegen其他方法直接返回 0 并告警创建序列化器通过CreateSerde(method, metadata, config)获取 CacheGen 的序列化器 / 反序列化器定位并固定缓存调用self.lookup(tokens, search_range[location], lookup_idevent_id, pinTrue)按 token 前缀在指定后端如LocalCPUBackend中查找对应缓存块并 pin 住防止在操作期间被淘汰批量读取batched_get(keys, location)取出这些块对应的内存对象逐块压缩对每个内存对象调用serializer.serialize(memory_obj)生成压缩后的对象同时解除原对象的 pin替换存储batched_remove(keys, locations[location])删除旧的未压缩对象再batched_put(keys, memory_objscompressed_memory_objs, locationlocation)将压缩对象写回同一后端返回返回被处理的 token 数num_tokens。decompress是镜像流程用deserializer.deserialize还原对象后再写回后端。方法头部还留有 TODO 注释tokensNone压缩全部 token以及更多压缩方法的支持仍在规划中。5.4 CacheGen 序列化器CreateSerde 与 naive_serde序列化器的工厂函数CreateSerde定义在 lmcache/v1/storage_backend/naive_serde/init.py目前支持三种类型if serde_type naive: s, d NaiveSerializer(), NaiveDeserializer() elif serde_type kivi: s, d KIVISerializer(), KIVIDeserializer() elif serde_type cachegen: s, d ( CacheGenSerializer(config, metadata), CacheGenDeserializer(config, metadata), )其中 CacheGen 的编码器与解码器分别位于 cachegen_encoder.py 与 cachegen_decoder.py。二者都会基于模型名构造CacheGenConfig见 cachegen_basics.py并按 key / value 各自的量化桶bins对 KV 张量做 CacheGen 风格的压缩编码。需要注意的是虽然引擎层CreateSerde已具备 naive / kivi / cachegen 三种能力但当前LMCacheEngine.compress只放行cachegen这是示例与 API 层当前的实际边界。六、相关编排 API 一览压缩 / 解压只是 Cache Controller 编排能力的一部分。在 examples/cache_controller/README.md 中列出了配套示例KV cache 清除clear、查询lookup、移动move、固定pin其中decompress与unpin在该入口文档中被标注为 WIP 接口。这些 API 与本文同属一个 controller 体系可以组合出查询 → 压缩 → 移动 → 解压的完整缓存编排流水线。此外vLLM 8000 端口上的 LMCache 内部 APIlmcache/v1/internal_api_server/vllm/cache_api.py提供了另一组 cache 操作如/cache/store、/cache/retrieve、/cache/clear与 controller 侧的编排 API 互补可结合阅读。七、使用限制与注意事项综合原文档与源码本示例当前存在以下边界使用前请确认压缩方法受限API 与引擎层当前仅支持cachegen其他方法如 kivi在LMCacheEngine.compress中会被拒绝必须提供 token 列表tokens字段用于定位缓存块压缩全部 tokentokensNone尚未实现token 列表应来自 vLLM 的/tokenize接口保证与缓存哈希一致instance 标识需一致请求体instance_id必须与配置文件中的lmcache_instance_id相同分布式前提执行器要求所有 worker 压缩的 token 数一致且当前不支持 PP 与异构 TP状态查询待完善返回的event_id设计用于跟踪操作状态压缩操作的查询功能仍在开发中端口不可冲突8000 / 8001 / 9000 / 9001 / 8200 需保持空闲。结语通过本示例可以看到LMCache 的 Cache Controller 把 KV cache 的压缩 / 解压从推理引擎内部抽离为可外部调用的 HTTP APIvLLM 只负责推理与卸载controller 负责编排worker 通过 CacheGen 序列化器在LocalCPUBackend上完成压缩替换。这一设计为推理完成后统一做缓存瘦身、需要时再按需还原的运维场景提供了干净的落点。你可以在此基础上将压缩、解压与 lookup、move 等 API 组合构建属于自己的 KV cache 生命周期管理策略。【免费下载链接】LMCacheLMCache: Supercharge Your LLM with the Fastest KV Cache Layer项目地址: https://gitcode.com/GitHub_Trending/lm/LMCache创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

LMCache 外部 KV Cache 压缩实战：通过 Cache Controller API 对请求 KV Cache 进行 CacheGen 压缩与解压

相关推荐

ClickHouse函数生态解析与2025年趋势

如何用curl调用ReClip：10分钟写出你的第一个命令行视频下载脚本

CubeSandbox 快照、回滚与克隆实战指南：cubesandbox Python SDK 端到端示例详解

更多资讯

ASP.NET+SQL Server校园新闻发布系统：从数据库设计到IIS部署全指南

RGB-Thermal双模态数据集构建与多模态融合技术实践

LiteLLM 部署在嵌入式 Linux，模型请求也走 TaoToken 行不行？

浪潮NC5280M5装Win2012 R2实战：驱动注入与RAID配置全记录

Flask+MySQL外卖订餐系统：从建表到订单闭环的毕设实践

SkyPilot 优先级调度与抢占实战：利用 Kubernetes PriorityClass 实现高优任务抢占

今日更新

基于MATLAB的CRI显色指数计算：从SPD光谱到Ra的完整流程

JSP+Servlet+MySQL博客系统源码部署与优化全攻略

蜂窝调度算法 MATLAB 实现：比例公平、轮询与最大 C/I 对比

本周精选

AI驱动的自动化专利分析平台技术解析

LeetCode-Go 题解：1252. Cells with Odd Values in a Matrix（奇数值单元格计数）双解法剖析

在线答疑系统Java毕设实战：Spring Boot前后端分离与状态流转

本月热门

基于YOLO的焊缝缺陷检测：从数据标注到工业部署全流程实践

分布式服务的决策记录

创业产品的首版范围

读完文章，想聊聊您的网站？