LMCache 外部清空 KV Cache 实战基于 Cache Controller 的 /clear 接口与全链路解析【免费下载链接】LMCacheLMCache: Supercharge Your LLM with the Fastest KV Cache Layer项目地址: https://gitcode.com/GitHub_Trending/lm/LMCache导读本文以 examples/cache_controller/clear/README.md 为骨架讲解如何在 LMCache 中通过外部 HTTP 接口主动清空 KV Cache从启动 vLLM 推理引擎、拉起 LMCache Controller到调用/clear接口完成缓存清理并用/lookup验证清理结果。读完本文你将掌握清空缓存所需的环境前提、example.yaml配置项含义、完整的命令行操作流程以及从 HTTP 请求到 KVController 再到工作节点执行的底层实现链路并了解 LMCache MP 模式下更现代的DELETE /cache/clear与lmcache kvcache clear两种替代方案。清空 KV Cache 的场景与接口约定KV Cache 是 LLM 推理加速的核心数据。当缓存数据过期、需要释放存储空间或需要重置测试环境时开发者往往希望在不重启 vLLM/LMCache 引擎的前提下从外部直接清空指定实例、指定存储位置上的缓存。LMCache 通过 Cache Controller 提供了一套编排接口其中clear用于完成这一操作。从 docs/source/kv_cache_management/clear.rst 可以看到其接口签名定义clear(instance_id: str, location: str) - event_id: str, num_tokens: int其语义为删除指定instance_id在location存储后端上保存的 KV cache返回一个event_id以及本次计划清理的 token 数num_tokens。注意上述clear接口属于 LMCache 的in-process 模式已弃用deprecated。官方文档建议对功能支持与性能有更高要求的场景改用 LMCache MP 模式见 docs/source/mp/index.rst。本文主体按关联文档演示 in-process 模式下的完整流程并在文末给出 MP 模式的替代接口。环境前提与端口规划按照 examples/cache_controller/clear/README.md 的要求运行该示例需要满足GPU 资源服务器至少 1 张 GPU用于运行 vLLM 推理引擎。端口规划8000vLLM 推理引擎 HTTP 服务端口8001LMCache 工作节点worker端口对应配置项lmcache_worker_ports9000LMCache Controller 主端口接收clear/lookup等编排请求9001LMCache Monitor 端口用于控制器拉取 worker 状态对应配置项controller_pull_url8200P2P 初始化端口对应配置项p2p_init_ports。配置文件 example.yaml 逐项解读关联文档给出的配置示例保存在 examples/cache_controller/clear/example.yaml共三组配置含义如下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_size256KV cache 分块大小LMCache 按该 token 数将 KV 切分为逻辑块进行缓存与寻址local_cpuTrue启用本地 CPU 后端LocalCPUBackend将 KV cache 存放于 CPU 内存max_local_cpu_size5本地 CPU 缓存的最大容量单位GB达到上限后触发缓存淘汰enable_controllerTrue开启 Cache Controller 模式使 LMCache 引擎接受控制器编排clear/lookup 等lmcache_instance_idlmcache_default_instance当前 LMCache 实例的标识符是/clear请求中instance_id的取值依据controller_pull_urllocalhost:9001控制器拉取 worker 状态信息的 monitor 地址lmcache_worker_ports8001LMCache worker 监听端口与 vLLM 引擎联动p2p_hostlocalhostP2PPeer-to-Peer通信主机名p2p_init_ports8200P2P 初始化端口其中chunk_size直接决定了缓存寻址的最小粒度LMCache 以 chunk 为单位进行缓存写入、查找与清理而/clear返回的num_tokens也正是这些 chunk 所覆盖的 token 总数。lmcache_instance_id是本次示例的关键——后续调用/clear时必须与该值保持一致控制器才能正确定位到目标实例。完整操作流程第 1 步启动 vLLM 引擎CUDA_VISIBLE_DEVICES0 LMCACHE_CONFIG_FILEexample.yaml vllm serve meta-llama/Llama-3.1-8B-Instruct --max-model-len 4096 --gpu-memory-utilization 0.8 --port 8000 --kv-transfer-config {kv_connector:LMCacheConnectorV1, kv_role:kv_both}要点通过环境变量LMCACHE_CONFIG_FILEexample.yaml让 LMCache 加载上述配置CUDA_VISIBLE_DEVICES0指定使用第 0 张 GPU模型使用meta-llama/Llama-3.1-8B-Instruct--max-model-len 4096限定最大序列长度--gpu-memory-utilization 0.8设定显存利用率上限--kv-transfer-config中的kv_connector:LMCacheConnectorV1表明通过 LMCache V1 Connector 接管 KV cache 传输kv_role:kv_both表示该实例同时承担 prefill写入与 decode读取角色。第 2 步启动 LMCache Controllerlmcache_controller --host localhost --port 9000 --monitor-port 9001控制器监听localhost:9000monitor 端口为9001与配置文件中controller_pull_url: localhost:9001相呼应保证控制器能够拉取到 worker 的注册与缓存状态。第 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 }该请求让 vLLM 对提示词执行一次补全过程中产生的 KV cache 会被 LMCache 捕获并按chunk_size分块存入本地 CPU 后端为后续的清理演示提供数据。第 4 步调用 /clear 清空 KV Cachecurl -X POST http://localhost:9000/clear \ -H Content-Type: application/json \ -d { instance_id: lmcache_default_instance, location: LocalCPUBackend }instance_id必须与example.yaml中的lmcache_instance_id一致location指定要清理的存储后端此处为LocalCPUBackend对应local_cpu: True。成功时控制器返回类似下面的 JSON{event_id: xxx, num_tokens: 12}其中event_id是该次清理操作的唯一事件标识num_tokens: 12表示系统已安排清理 12 个 token 的 KV cache。第 5 步用 /lookup 验证清理结果关联文档进一步演示了如何验证缓存确实被清除——对刚才提示词对应的 token 序列发起 lookupcurl -X POST http://localhost:9000/lookup \ -H Content-Type: application/json \ -d { tokens: [128000, 849, 21435, 279, 26431, 315, 85748, 6636, 304, 4221, 4211, 13] }由于这 12 个 token 的 KV cache 已被清空lookup 应返回空结果从而证实清理生效。源码视角一次 /clear 请求的完整调用链从源码结构看/clear请求在控制器内部会依次经过消息定义、控制器分发、集群执行器调度、worker 执行四个环节消息定义ClearMsg包含event_id、instance_id、location三个字段见 message.py返回消息ClearRetMsg携带event_id与num_tokens见 message.py与 REST 接口的出入参完全对应。控制器分发KVController.clear 将请求转发给cluster_executor执行。集群调度LMCacheClusterExecutor.clear 通过注册控制器查询该instance_id下的全部 worker逐个构建ClearWorkerMsg每个 worker 使用独立的worker_event_id经 ZMQ socket 广播后汇总各 worker 返回的num_tokens代码还断言所有 worker 清理的 token 数必须一致否则视为缓存一致性异常assert len(set(num_tokens_list)) 1。Worker 执行各 worker 收到ClearWorkerMsg后在指定location上实际删除对应 chunk 的 KV 数据并上报清理的 token 数。这正是 HTTP 返回的num_tokens的由来它是控制器在所有 worker 上汇总后的统一清理量而event_id则贯穿整条链路用于关联本次操作。更多清空缓存的方式除上述 in-process 模式的/clear编排接口外当前仓库还提供了两种更贴近 MP 模式的清空手段方式一vLLM 内部 APIDELETE /cache/clear在 cache_api.py 中定义了DELETE /cache/clear接口可通过locations查询参数按存储后端选择性清理不传则清空全部位置# 清空全部缓存 curl -X DELETE http://localhost:8000/cache/clear # 仅清空指定后端 curl -X DELETE http://localhost:8000/cache/clear?locationsLocalCPUBackendlocationsLocalDiskBackend响应示例{status: success, num_removed: 10, locations: null, request_configs: null}。方式二CLI 子命令lmcache kvcache clearlmcache/cli/commands/kvcache.py 提供了lmcache kvcache clear子命令其实现会向 MP HTTP server 的POST /cache/clear端点发送{tier: l1}请求目前支持清空 L1CPU缓存对应文档 docs/source/cli/kvcache.rst。两种方式分别面向直接操作 vLLM 引擎侧缓存与命令行管理两种场景可作为 in-process 控制器方式的补充。总结本文完整复现了 LMCache 外部清空 KV Cache 的示例通过example.yaml开启 Cache Controller 模式并配置实例标识启动 vLLM 与lmcache_controller后即可用POST /clear定向清空指定实例、指定存储后端的缓存并用返回的num_tokens与后续的/lookup验证清理结果。从源码链路看clear是控制器分发 → 集群执行器广播 → worker 本地删除的协作过程返回的 token 数是所有 worker 汇总后的一致性结果。若需在 MP 架构下工作可改用DELETE /cache/clear或lmcache kvcache clear。关联阅读控制器配置与部署见 docs/source/mp/configuration.rst 与 docs/source/mp/coordinator.rst完整的 KV 管理接口目录见 docs/source/kv_cache_management/index.rst。【免费下载链接】LMCacheLMCache: Supercharge Your LLM with the Fastest KV Cache Layer项目地址: https://gitcode.com/GitHub_Trending/lm/LMCache创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考