LMCache KV Cache Pin 接口实战通过 Controller 持久化 KV Cache 防止被驱逐【免费下载链接】LMCacheLMCache: Supercharge Your LLM with the Fastest KV Cache Layer项目地址: https://gitcode.com/GitHub_Trending/lm/LMCache导读LMCache 的pin接口允许用户将指定 token 序列对应的 KV Cache 分块chunk钉住persist在指定实例instance_id的指定存储位置location从而防止这些缓存块被缓存策略驱逐。本文以 docs/source/kv_cache_management/pin.rst 为骨架完整演示从 YAML 配置、vLLM 实例启动、Controller 启动到通过 HTTP 调用/pin接口的全流程并结合 lmcache/v1/api_server/main.py、lmcache/v1/cache_controller/executor.py 等源码剖析 pin 请求从 API Server 到 LMCache Worker 再到底层存储后端的完整调用链。读完本文你将掌握 pin 接口的调用方式、返回语义以及它在缓存生命周期管理中的定位。注意本文档描述的是 LMCache 的 in-process 模式已弃用下的行为。如需更完善的功能支持与性能建议使用 LMCache MP 模式。一、接口定义与语义pin接口的定义如下pin(instance_id: str, location: str, tokens: List[int]) - event_id: str, num_tokens: int各参数含义instance_idLMCache 实例的标识符。在分布式场景下同一个模型服务实例内的所有 rank 会共享同一个instance_idController 据此找到该实例下注册的所有 Workerlocation目标存储位置名称例如LocalCPUBackend本地 CPU 内存后端或LocalDiskBackend本地磁盘后端。只有被 pin 的后端需要实现pin/unpin语义tokens要钉住的 token ID 列表。Controller 会依据 token 序列在 token 数据库中按 chunk 粒度进行匹配。该函数将tokens指定的 KV Cache 分块持久化到instance_id实例的指定location中。Controller 会返回一个event_id操作事件 ID以及本次被调度去 pin 的 token 数量num_tokens。返回值的语义num_tokens表示有多少个 token 的 KV Cache 被成功 pin 住。如果某些 token 对应的 chunk 在当前实例的指定位置中不存在则不会计入该数字event_id本次操作的唯一事件标识可用于后续查询操作状态例如配合check_finish接口确认异步操作是否完成。在 Controller 的 KV 缓存管理 API 家族中pin 与clear清空、lookup查询、move迁移、compress压缩等接口并列属于面向用户与编排器orchestrator的缓存管理能力之一详见 docs/source/kv_cache_management/index.rst。二、环境准备编写 LMCache 实例配置首先创建一个 YAML 文件example.yaml来配置 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_size256KV Cache 分块大小以 token 数计。pin 操作按 chunk 粒度匹配与处理 token 序列local_cpuTrue启用本地 CPU 内存后端LocalCPUBackend使 KV Cache 可落盘到 CPU 内存max_local_cpu_size5本地 CPU 缓存的最大容量单位为 GB超出部分由缓存策略按需驱逐被 pin 的块不受驱逐影响enable_controllerTrue开启 LMCache Controller这是 pin 等管理接口生效的前提lmcache_instance_idlmcache_default_instance本实例的 IDController 依此注册与管理 Workercontroller_pull_urllocalhost:9001Worker 向 Controller Manager 主动拉取命令的地址即 Controller 的 monitor 端口lmcache_worker_ports8001LMCache Worker 监听的端口端口数量需与 rank 数量一致p2p_hostlocalhostP2P 传输的主机地址p2p_init_ports8200P2P 初始化端口注意lmcache_worker_ports的端口数量必须等于实例的 rank 数量。若开启enable_p2p则必须同时启用 Controller由 Controller 作为中心节点保存每个 chunk 的元信息P2PBackend通过查询 Controller 获取 chunk 信息并借助 NIXL 完成数据传输。三、三步启动vLLM 实例、Controller 与请求下发3.1 启动 vLLM/LMCache 实例端口 8000CUDA_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指定上一步编写的配置vLLM 内部的 LMCache 集成会据此初始化缓存引擎与 Controller 通信--kv-transfer-config中的LMCacheConnectorV1是 in-process 模式下 vLLM 与 LMCache 之间的 KV 传输连接器kv_role为kv_both表示该实例同时承担 KV 的生成produce与消费consume角色建议保持--gpu-memory-utilization有一定余量避免因显存不足导致缓存写入失败。3.2 启动 LMCache Controller端口 9000与 Monitor端口 9001lmcache_controller --host localhost --port 9000 --monitor-port 9001Controller 由 Controller Manager 与 LMCache Worker 两部分构成架构详见 docs/source/kv_cache_management/index.rstKV Controller处理 LMCache Worker 上报的 chunk 信息并响应 lookup 等查询请求Reg Controller处理 Worker 的 register / deregister / heartbeat注册、注销、心跳Cluster Executor当 Controller Manager 收到用户的控制请求如 pin、clear、move时通过它向 LMCache Worker 下发对应命令。LMCache Worker 是 rank 进程内的一个线程负责向 Reg Controller 发送注册/注销/心跳、向 KV Controller 上报 admit/evict 的 chunk 信息并监听端口接收 Cluster Executor 下发的命令。3.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 实际处理上述 prompt从而在 LMCache 中生成并缓存对应的 KV Cache 分块为后续 pin 操作提供数据基础。3.4 获取 token ID 序列pin 接口接收的是 token ID 列表因此需要先将 prompt 分词curl -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. }从返回结果中取出 token ID 列表用于下一步的 pin 请求。四、调用 Pin 接口4.1 发起 pin 请求curl -X POST http://localhost:9000/pin \ -H Content-Type: application/json \ -d { tokens: [128000, 849, 21435, 279, 26431, 315, 85748, 6636, 304, 4221, 4211, 13], instance_id: lmcache_default_instance, location: LocalCPUBackend }Controller 将返回类似下面的响应{event_id: xxx, num_tokens: 12}其中num_tokens表示有多少个 token 的 KV Cache 被成功 pin返回的event_id可用于查询该操作的状态。4.2 请求字段与响应结构从源码看lmcache/v1/api_server/main.py 中定义了对应的 Pydantic 模型与处理逻辑PinRequestinstance_idstr、locationstr、tokenslist[int]PinResponseevent_idstr、num_tokensint服务端在收到请求后会以Pin uuid4()的形式生成一个全局唯一的event_id并将其与请求字段一起封装为PinMsg交给handle_orchestration_message分发到 KV Controller。PinMsg的完整定义位于 lmcache/v1/cache_controller/message.py包含event_id、instance_id、location、tokens四个字段并提供了describe()方法用于日志描述Pin tokens ... in instance ... and location ...。五、源码视角pin 请求的完整调用链理解 pin 在 Controller 内部的流转有助于在实际部署中排查pin 后num_tokens不符合预期等问题。完整调用链如下5.1 KV Controller 分发lmcache/v1/cache_controller/controllers/kv_controller.py 中的pin方法将消息委托给cluster_executor.execute(pin, msg)。5.2 Cluster Executor 向所有 Worker 广播lmcache/v1/cache_controller/executor.py 中的pin执行逻辑如下通过reg_controller.get_workers(instance_id)获取该实例注册的所有 Worker ID并对每个 Worker 获取其命令 Socket为每个 Worker 生成独立的worker_event_id形如Worker{worker_id}{event_id}将 tokens 与 location 封装成PinWorkerMsg使用msgspec.msgpack序列化后通过execute_workers并发下发汇总所有 Worker 返回的num_tokens并断言各 Worker 返回的数量一致源码注释提到后续需要保证跨 Worker 的缓存一致性最终以第一个 Worker 的结果构造PinRetMsg(event_id, num_tokens)返回。5.3 Worker 侧执行复用 lookup pin 语义LMCache Worker 在收到PinWorkerMsg后见 lmcache/v1/cache_controller/worker.py并非调用独立的 pin 函数而是调用缓存引擎的lookup并携带pinTrue标志num_pinned_tokens self.lmcache_engine.lookup( tokensrequest.tokens, search_range[request.location], lookup_idrequest.worker_event_id, pinTrue, )也就是说pin 本质上是限定location的查找 命中即钉住的组合操作——只有那些在指定位置真实存在的 chunk 才会被 pin这也是num_tokens可能小于请求 token 总数的原因。5.4 存储后端pin 计数与驱逐保护以文档示例中的LocalCPUBackend为例lmcache/v1/storage_backend/local_cpu_backend.py 在cpu_lock保护下对hot_cache中命中的键调用memory_obj.pin()或unpin()。底层内存对象的 pin 语义在 lmcache/v1/memory_management.py 中实现pin()首次 pinpin_count从 0 变为 1时更新监控计数随后pin_count 1并注册到PinMonitor以便做超时跟踪unpin()pin_count - 1当pin_count 0时更新监控计数并注销PinMonitor仅当pin_count 0且ref_count 0时才会真正把内存归还给父级分配器释放。因此被 pin 的内存对象不会因缓存策略如 LRU而被驱逐pin_count相当于一把驱逐保护锁且支持多次 pin / 多次 unpin 的引用式计数。5.5 不同后端的 pin 支持情况可推断从 lmcache/v1/storage_backend/abstract_backend.py 的抽象定义看pin(key)是后端接口的组成部分但各后端实现存在差异LocalCPUBackend真实支持见上文LocalDiskBackend实现了 pin/unpinlmcache/v1/storage_backend/local_disk_backend.pyRemoteBackendpin 为 no-op 并直接返回 Truelmcache/v1/storage_backend/remote_backend.pyP2PBackend源码注释明确pin is useless for P2P backend nowlmcache/v1/storage_backend/p2p_backend.pyGDSBackend由于 GDS 当前没有驱逐机制pin 返回 Falselmcache/v1/storage_backend/gds_backend.py。因此在实际使用时应根据location选择支持 pin 语义的后端例如LocalCPUBackend否则可能出现请求成功但实际并未持久化的情况。六、与其他缓存管理接口的关系pin 通常与以下接口配合使用共同构成 Controller 的 KV 缓存管理能力详见 docs/source/kv_cache_management/index.rstlookup查询 token 序列的缓存布局pin 的内部实现即带 pin 标志的 lookupclear清空指定实例、指定位置的 KV Cache被 pin 的块不受普通驱逐影响但clear是显式操作move将 KV Cache 迁移到不同位置compress/decompress对缓存进行压缩与解压check_finish查询某个非阻塞控制事件是否已完成——可用于轮询 pin 这类异步操作的最终状态query_worker_info查询 Worker 信息。从架构上看pin 是 Controller 面向需要长期保留的 KV Cache例如高频复用的系统提示词、常用文档前缀、稳定知识库片段提供的关键能力既可以把宝贵的 KV Cache 从驱逐风险中保护起来又可以在多实例间通过instance_id精确定位目标实例与目标后端。七、常见问题排查建议num_tokens远小于请求的 token 数说明指定instance_idlocation下没有完整的 chunk 命中。请确认已先向 vLLM 发送过包含该 prompt 的推理请求、local_cpu: True已开启且chunk_size与 token 序列匹配pin 按 chunk 粒度对齐。Controller 返回错误检查lmcache_controller是否已启动且端口一致--port 9000对应/pin接口--monitor-port 9001对应controller_pull_url检查 YAML 中的lmcache_instance_id与请求中的instance_id是否一致。多 rank 场景lmcache_worker_ports需配置与 rank 数相同的端口否则 Worker 无法全部注册executor 会因找不到部分 Worker 的 Socket 而返回错误。in-process 模式弃用如需更完善的功能与性能支持请迁移到 LMCache MP 模式docs/source/mp/index.rst其中驱逐控制器通过维护_pin_counts将 pin 键排除在驱逐之外见 lmcache/v1/mp_coordinator/controllers/eviction_controller.py实现了同样防驱逐的语义。【免费下载链接】LMCacheLMCache: Supercharge Your LLM with the Fastest KV Cache Layer项目地址: https://gitcode.com/GitHub_Trending/lm/LMCache创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考