LMCache KV Cache 压缩与解压缩实战通过 Controller 对 KV Cache 执行 CacheGen 压缩【免费下载链接】LMCacheLMCache: Supercharge Your LLM with the Fastest KV Cache Layer项目地址: https://gitcode.com/GitHub_Trending/lm/LMCache导读本篇技术指南完整讲解 LMCache 提供的 KV Cache 压缩/解压缩接口compress/decompress从接口语义、配置 YAML 编写、vLLM LMCache 实例启动、Controller 启动到基于curl的端到端压缩/解压缩调用流程。阅读本文后你将掌握如何通过 HTTP API 对指定 token 序列对应的 KV cache 分块执行 CacheGen 压缩与恢复理解event_id与num_tokens返回语义并了解 Controller 到 Worker 的底层分发机制与源码实现路径。⚠️ 本文对应的compress接口文档位于 docs/source/kv_cache_management/compress.rst其记录的是 LMCachein-process进程内模式下的行为。该模式目前已标记为 deprecated官方建议使用特性更完整、性能更好的 LMCache MP 模式MP 模式下的等价文档见 MP 模式 CacheGen 说明。接口定义与语义compress/decompress两个接口的 Python 签名定义如下compress(instance_id: str, method: str, location: str, tokens: list[int]) - event_id: str, num_tokens: int decompress(instance_id: str, method: str, location: str, tokens: list[int]) - event_id: str, num_tokens: int这两个函数使用指定的method在指定的存储location中对由tokens指定的 KV cache 分块进行压缩/解压缩。Controller 收到请求后返回一个event_id以及被调度执行压缩/解压缩的 token 数量num_tokens。参数详解参数类型含义instance_idstrLMCache 实例的唯一标识需与配置中的lmcache_instance_id保持一致methodstr压缩方法。当前支持cachegen其余取值会被拒绝返回 0locationstr存储后端名称例如LocalCPUBackend本地 CPU 存储tokenslist[int]标识待压缩/解压缩 KV cache 分块的 token ID 序列通常为 prompt 经分词得到的完整 token 列表event_id返回str操作的事件 ID可用于查询该操作的执行状态num_tokens返回int被调度进行压缩/解压缩的 token 数量底层实现路径从源码结构可以梳理出完整的调用链路lmcache/v1/cache_controller/controllers/kv_controller.pyController 层KVController.compress/decompress将消息转发给cluster_executor.execute(compress / decompress, msg)Executor 层lmcache/v1/cache_controller/executor.py通过注册中心reg_controller.get_workers(instance_id)获取该实例的全部 worker向每个 worker 分发CompressWorkerMsg/DecompressWorkerMsg收集各 worker 返回的num_tokens并断言所有 worker 的 token 数一致后汇总返回Worker 层lmcache/v1/cache_controller/worker.py调用lmcache_engine.compress(...)/lmcache_engine.decompress(...)引擎层lmcache/v1/cache_engine.py通过CreateSerde(method, self.metadata, self.config)创建序列化器/反序列化器执行 lookup带pinTrue、批量读取、序列化/反序列化、批量删除、批量写回的完整流程。其中CreateSerde在 lmcache/v1/storage_backend/naive_serde/init.py 中按serde_type分发cachegen对应CacheGenSerializer/CacheGenDeserializer实现位于 cachegen_encoder.py 与 cachegen_decoder.py。CacheGen 压缩方法简介compress接口中可用的method为cachegen。CacheGen 利用 KV cache 的分布特性将 KV cache 编码为更紧凑的比特流表示且解码开销可忽略不计详见 CacheGen 文档。在离线推理场景中启用 CacheGen 时需要设置环境变量# 在 LMCache 中启用 CacheGen 压缩 os.environ[LMCACHE_REMOTE_SERDE] cachegen在线推理场景中则需要在配置 YAML 中设置remote_serde# 在 LMCache 中启用 CacheGen 压缩 remote_serde: cachegen仓库还提供了 CacheGen 端到端的 GPU 编解码基准测试 tests/benchmarks/test_cachegen.py它生成合成 KV cache blob测量序列化与反序列化的墙钟时间并记录相对未压缩基线的压缩比可通过pytest tests/benchmarks/test_cachegen.py --benchmark-only运行。该基准需要可用的 CUDA/XPU torch 运行时。配置 LMCache 实例example.yaml在使用compress接口之前需要先编写 YAML 配置文件example.yaml以正确配置 lmcache 实例chunk_size: 256 local_cpu: True max_local_cpu_size: 5 # cache controller 配置 enable_controller: True lmcache_instance_id: lmcache_default_instance controller_pull_url: localhost:9001 lmcache_worker_ports: 8001 # Peer 标识 p2p_host: localhost p2p_init_ports: 8200关键配置项说明配置项取值作用chunk_size256KV cache 分块大小token 数压缩/解压缩按分块粒度进行local_cpuTrue启用本地 CPU 存储后端即LocalCPUBackendmax_local_cpu_size5本地 CPU 存储的最大容量GB 级别配额用于控制缓存占用enable_controllerTrue开启 cache controller 功能使实例参与控制面编排lmcache_instance_idlmcache_default_instance实例标识后续compress请求中的instance_id必须与此一致controller_pull_urllocalhost:9001Controller 的 monitor 端口供实例被 controller 拉取/注册lmcache_worker_ports8001LMCache worker 端口p2p_host/p2p_init_portslocalhost/8200P2P 网络相关标识与初始端口启动 vLLM/LMCache 实例第二步在端口 8000 启动 vLLM/LMCache 实例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 配置文件--kv-transfer-config {kv_connector:LMCacheConnectorV1, kv_role:kv_both}将 vLLM 与 LMCache 连接器打通kv_role为kv_both表示该实例同时承担 KV 的存储与传输角色--max-model-len 4096设置最大模型上下文长度示例 prompt 的 token 数远小于该上限。启动 LMCache Controller第三步在端口 9000 启动 LMCache controller并在端口 9001 启动 monitorlmcache_controller --host localhost --port 9000 --monitor-port 9001--port 9000是 Controller 的 HTTP API 端口compress/decompress请求即发送到该端口--monitor-port 9001与配置中的controller_pull_url对应用于 worker 注册与拉取。端到端压缩/解压缩操作流程1. 验证 vLLM 服务可用向 vLLM 发送一个 completions 请求确认服务正常工作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 }2. 获取 prompt 的 token ID向 vLLM 的/tokenize接口发送请求获得 prompt 对应的 token ID 列表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{count:12,max_model_len:4096,tokens:[128000,849,21435,279,26431,315,85748,6636,304,4221,4211,13],token_strs:null}这里返回了 12 个 token ID128000为 Llama-3.1 系列的 BOS/特殊 token这些 token ID 将作为后续compress/decompress请求中tokens字段的取值。3. 发起压缩请求向 Controller 的/compress端点发送请求curl -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] }Controller 返回类似如下的响应{event_id: xxx, num_tokens: 12}这表示有 12 个 token 被调度压缩。返回的event_id可用于查询该操作的执行状态。从 HTTP API 服务实现lmcache/v1/api_server/main.py可以看到/compress与/decompress端点分别构造CompressMsg/DecompressMsg消息定义见 lmcache/v1/cache_controller/message.py生成形如Compress uuid/Decompress uuid的事件 ID交由 controller manager 编排后返回event_id与num_tokens。tokens字段为可选默认空列表。4. 发起解压缩请求KV cache 被压缩后可以使用同样的 CacheGen 方法将其解压缩回原始形态curl -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] }Controller 返回类似如下的响应{event_id: xxx, num_tokens: 12}这表示有 12 个 token 被调度解压缩。同样地event_id可用于查询操作状态。引擎层压缩/解压缩的内部流程从源码看lmcache/v1/cache_engine.py引擎层的compress/decompress遵循对称的五步流程校验方法仅接受method cachegen其余方法记录 warning 并返回0创建序列化器通过CreateSerde(method, metadata, config)获得(serializer, deserializer)对CacheGen 的编解码器同时需要配置与元数据如模型结构信息才能正确编码/解码Lookup 定位对tokens执行带pinTrue的 lookup限定search_range[location]返回命中的 token 数若为 0 则直接返回 0无可压缩/解压缩数据同时将命中的 chunk 键记录在lookup_pins中避免操作过程中被驱逐批量读 编解码通过storage_manager.batched_get批量取回 memory objects逐个调用serializer.serialize/deserializer.deserialize完成转换随后对已 pin 的对象执行unpin批量替换storage_manager.batched_remove删除原位置上的旧对象再batched_put将新对象写回同一location实现原地格式转换。这一流程保证压缩/解压缩是位置不变的chunk 的 key 不变仅存储的编码形态发生变化因此对上层缓存查询透明。总结通过 Controller 的/compress与/decompressHTTP 接口你可以按 token 粒度对 LMCache 中存储的 KV cache 分块进行 CacheGen 压缩与恢复压缩阶段将 KV cache 编码为紧凑比特流以减少存储占用解压缩阶段则以极低开销恢复原始表示。实际操作时注意三点instance_id必须与配置中的lmcache_instance_id一致、location必须是实际使用的存储后端名称如LocalCPUBackend、tokens应使用/tokenize接口返回的完整 token 列表。由于该接口当前基于已废弃的 in-process 模式生产环境建议迁移至 LMCache MP 模式 以获得更完整的特性支持与更好的性能。【免费下载链接】LMCacheLMCache: Supercharge Your LLM with the Fastest KV Cache Layer项目地址: https://gitcode.com/GitHub_Trending/lm/LMCache创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
LMCache KV Cache 压缩与解压缩实战：通过 Controller 对 KV Cache 执行 CacheGen 压缩
LMCache KV Cache 压缩与解压缩实战通过 Controller 对 KV Cache 执行 CacheGen 压缩【免费下载链接】LMCacheLMCache: Supercharge Your LLM with the Fastest KV Cache Layer项目地址: https://gitcode.com/GitHub_Trending/lm/LMCache导读本篇技术指南完整讲解 LMCache 提供的 KV Cache 压缩/解压缩接口compress/decompress从接口语义、配置 YAML 编写、vLLM LMCache 实例启动、Controller 启动到基于curl的端到端压缩/解压缩调用流程。阅读本文后你将掌握如何通过 HTTP API 对指定 token 序列对应的 KV cache 分块执行 CacheGen 压缩与恢复理解event_id与num_tokens返回语义并了解 Controller 到 Worker 的底层分发机制与源码实现路径。⚠️ 本文对应的compress接口文档位于 docs/source/kv_cache_management/compress.rst其记录的是 LMCachein-process进程内模式下的行为。该模式目前已标记为 deprecated官方建议使用特性更完整、性能更好的 LMCache MP 模式MP 模式下的等价文档见 MP 模式 CacheGen 说明。接口定义与语义compress/decompress两个接口的 Python 签名定义如下compress(instance_id: str, method: str, location: str, tokens: list[int]) - event_id: str, num_tokens: int decompress(instance_id: str, method: str, location: str, tokens: list[int]) - event_id: str, num_tokens: int这两个函数使用指定的method在指定的存储location中对由tokens指定的 KV cache 分块进行压缩/解压缩。Controller 收到请求后返回一个event_id以及被调度执行压缩/解压缩的 token 数量num_tokens。参数详解参数类型含义instance_idstrLMCache 实例的唯一标识需与配置中的lmcache_instance_id保持一致methodstr压缩方法。当前支持cachegen其余取值会被拒绝返回 0locationstr存储后端名称例如LocalCPUBackend本地 CPU 存储tokenslist[int]标识待压缩/解压缩 KV cache 分块的 token ID 序列通常为 prompt 经分词得到的完整 token 列表event_id返回str操作的事件 ID可用于查询该操作的执行状态num_tokens返回int被调度进行压缩/解压缩的 token 数量底层实现路径从源码结构可以梳理出完整的调用链路lmcache/v1/cache_controller/controllers/kv_controller.pyController 层KVController.compress/decompress将消息转发给cluster_executor.execute(compress / decompress, msg)Executor 层lmcache/v1/cache_controller/executor.py通过注册中心reg_controller.get_workers(instance_id)获取该实例的全部 worker向每个 worker 分发CompressWorkerMsg/DecompressWorkerMsg收集各 worker 返回的num_tokens并断言所有 worker 的 token 数一致后汇总返回Worker 层lmcache/v1/cache_controller/worker.py调用lmcache_engine.compress(...)/lmcache_engine.decompress(...)引擎层lmcache/v1/cache_engine.py通过CreateSerde(method, self.metadata, self.config)创建序列化器/反序列化器执行 lookup带pinTrue、批量读取、序列化/反序列化、批量删除、批量写回的完整流程。其中CreateSerde在 lmcache/v1/storage_backend/naive_serde/init.py 中按serde_type分发cachegen对应CacheGenSerializer/CacheGenDeserializer实现位于 cachegen_encoder.py 与 cachegen_decoder.py。CacheGen 压缩方法简介compress接口中可用的method为cachegen。CacheGen 利用 KV cache 的分布特性将 KV cache 编码为更紧凑的比特流表示且解码开销可忽略不计详见 CacheGen 文档。在离线推理场景中启用 CacheGen 时需要设置环境变量# 在 LMCache 中启用 CacheGen 压缩 os.environ[LMCACHE_REMOTE_SERDE] cachegen在线推理场景中则需要在配置 YAML 中设置remote_serde# 在 LMCache 中启用 CacheGen 压缩 remote_serde: cachegen仓库还提供了 CacheGen 端到端的 GPU 编解码基准测试 tests/benchmarks/test_cachegen.py它生成合成 KV cache blob测量序列化与反序列化的墙钟时间并记录相对未压缩基线的压缩比可通过pytest tests/benchmarks/test_cachegen.py --benchmark-only运行。该基准需要可用的 CUDA/XPU torch 运行时。配置 LMCache 实例example.yaml在使用compress接口之前需要先编写 YAML 配置文件example.yaml以正确配置 lmcache 实例chunk_size: 256 local_cpu: True max_local_cpu_size: 5 # cache controller 配置 enable_controller: True lmcache_instance_id: lmcache_default_instance controller_pull_url: localhost:9001 lmcache_worker_ports: 8001 # Peer 标识 p2p_host: localhost p2p_init_ports: 8200关键配置项说明配置项取值作用chunk_size256KV cache 分块大小token 数压缩/解压缩按分块粒度进行local_cpuTrue启用本地 CPU 存储后端即LocalCPUBackendmax_local_cpu_size5本地 CPU 存储的最大容量GB 级别配额用于控制缓存占用enable_controllerTrue开启 cache controller 功能使实例参与控制面编排lmcache_instance_idlmcache_default_instance实例标识后续compress请求中的instance_id必须与此一致controller_pull_urllocalhost:9001Controller 的 monitor 端口供实例被 controller 拉取/注册lmcache_worker_ports8001LMCache worker 端口p2p_host/p2p_init_portslocalhost/8200P2P 网络相关标识与初始端口启动 vLLM/LMCache 实例第二步在端口 8000 启动 vLLM/LMCache 实例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 配置文件--kv-transfer-config {kv_connector:LMCacheConnectorV1, kv_role:kv_both}将 vLLM 与 LMCache 连接器打通kv_role为kv_both表示该实例同时承担 KV 的存储与传输角色--max-model-len 4096设置最大模型上下文长度示例 prompt 的 token 数远小于该上限。启动 LMCache Controller第三步在端口 9000 启动 LMCache controller并在端口 9001 启动 monitorlmcache_controller --host localhost --port 9000 --monitor-port 9001--port 9000是 Controller 的 HTTP API 端口compress/decompress请求即发送到该端口--monitor-port 9001与配置中的controller_pull_url对应用于 worker 注册与拉取。端到端压缩/解压缩操作流程1. 验证 vLLM 服务可用向 vLLM 发送一个 completions 请求确认服务正常工作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 }2. 获取 prompt 的 token ID向 vLLM 的/tokenize接口发送请求获得 prompt 对应的 token ID 列表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{count:12,max_model_len:4096,tokens:[128000,849,21435,279,26431,315,85748,6636,304,4221,4211,13],token_strs:null}这里返回了 12 个 token ID128000为 Llama-3.1 系列的 BOS/特殊 token这些 token ID 将作为后续compress/decompress请求中tokens字段的取值。3. 发起压缩请求向 Controller 的/compress端点发送请求curl -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] }Controller 返回类似如下的响应{event_id: xxx, num_tokens: 12}这表示有 12 个 token 被调度压缩。返回的event_id可用于查询该操作的执行状态。从 HTTP API 服务实现lmcache/v1/api_server/main.py可以看到/compress与/decompress端点分别构造CompressMsg/DecompressMsg消息定义见 lmcache/v1/cache_controller/message.py生成形如Compress uuid/Decompress uuid的事件 ID交由 controller manager 编排后返回event_id与num_tokens。tokens字段为可选默认空列表。4. 发起解压缩请求KV cache 被压缩后可以使用同样的 CacheGen 方法将其解压缩回原始形态curl -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] }Controller 返回类似如下的响应{event_id: xxx, num_tokens: 12}这表示有 12 个 token 被调度解压缩。同样地event_id可用于查询操作状态。引擎层压缩/解压缩的内部流程从源码看lmcache/v1/cache_engine.py引擎层的compress/decompress遵循对称的五步流程校验方法仅接受method cachegen其余方法记录 warning 并返回0创建序列化器通过CreateSerde(method, metadata, config)获得(serializer, deserializer)对CacheGen 的编解码器同时需要配置与元数据如模型结构信息才能正确编码/解码Lookup 定位对tokens执行带pinTrue的 lookup限定search_range[location]返回命中的 token 数若为 0 则直接返回 0无可压缩/解压缩数据同时将命中的 chunk 键记录在lookup_pins中避免操作过程中被驱逐批量读 编解码通过storage_manager.batched_get批量取回 memory objects逐个调用serializer.serialize/deserializer.deserialize完成转换随后对已 pin 的对象执行unpin批量替换storage_manager.batched_remove删除原位置上的旧对象再batched_put将新对象写回同一location实现原地格式转换。这一流程保证压缩/解压缩是位置不变的chunk 的 key 不变仅存储的编码形态发生变化因此对上层缓存查询透明。总结通过 Controller 的/compress与/decompressHTTP 接口你可以按 token 粒度对 LMCache 中存储的 KV cache 分块进行 CacheGen 压缩与恢复压缩阶段将 KV cache 编码为紧凑比特流以减少存储占用解压缩阶段则以极低开销恢复原始表示。实际操作时注意三点instance_id必须与配置中的lmcache_instance_id一致、location必须是实际使用的存储后端名称如LocalCPUBackend、tokens应使用/tokenize接口返回的完整 token 列表。由于该接口当前基于已废弃的 in-process 模式生产环境建议迁移至 LMCache MP 模式 以获得更完整的特性支持与更好的性能。【免费下载链接】LMCacheLMCache: Supercharge Your LLM with the Fastest KV Cache Layer项目地址: https://gitcode.com/GitHub_Trending/lm/LMCache创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考