LMCache Controller 实战指南基于 KV Cache 集中式管理 API 的架构解析与操作手册【免费下载链接】LMCacheLMCache: Supercharge Your LLM with the Fastest KV Cache Layer项目地址: https://gitcode.com/GitHub_Trending/lm/LMCacheLMCache 的 Controller 组件位于 docs/source/kv_cache_management/index.rst为 LLM 推理场景下的 KV Cache 提供了一套集中式的管理与编排能力它以独立的控制平面进程监听用户请求通过 Clear、Compress、Lookup、Move、Pin、Health 等 8 类 HTTP API 对集群中各个 LMCache Worker 持有的 KV Cache 进行查询、迁移、压缩、持久化与健康巡检。本文以官方文档为骨架结合仓库源码Controller API 服务、Controller 配置、LMCacheWorker展开帮助读者理解 Controller 的架构组成、通信模型与各 API 的完整调用流程并可直接照抄示例完成一次真实的 KV Cache 管理与 P2P 迁移实验。注意Deprecation官方文档明确提示本文所描述的行为属于 LMCache 的in-process mode已弃用。若需要更完善的功能支持与更好的性能建议迁移到 LMCache MP mode。本文内容用于理解该模式的架构设计与 API 语义仍具备完整的学习与迁移参考价值。Controller 架构总览Controller Manager 与 LMCache Worker 的双层结构LMCache Controller 的整体架构由两大部分构成Controller Manager与LMCache Worker。Controller Manager 作为集中控制节点内部主要由以下三个子组件协同工作KV Controller负责处理 LMCache Worker 上报的 chunk缓存块信息并处理来自用户的 lookup 请求从 KV Controller 处查询 chunk 信息。Reg Controller负责处理来自 LMCache Worker 的 register注册、deregister注销与 heartbeat心跳请求维护集群内 Worker 的存活状态。Cluster Executor当 Controller Manager 收到用户请求例如 Clear、Move 等控制操作时通过 Cluster Executor 将对应命令下发到各个 LMCache Worker 执行。LMCache Worker 则是每个 rank 进程内部的线程承担以下三类职责向 Reg Controller 发送 register、deregister、heartbeat 消息向 KV Controller 发送 chunk 信息包括 admit准入与 evict驱逐两类消息监听一个端口以接收来自 Cluster Executor 的命令并执行相应的处理。下图展示了该架构的核心组件及其数据流向从源码实现看Controller 进程基于 FastAPI 构建lmcache/v1/api_server/main.pycreate_app会实例化LMCacheControllerManager并在应用启动时通过start_all()开启后台监控任务所有管理 API 均注册在该 FastAPI 应用上。而 Worker 侧的实现见 LMCacheWorker每个 Worker 持有自己的lmcache_instance_id与worker_id通过 ZeroMQ PUSH socket 连接controller_pull_url上报消息若配置了controller_reply_url还会建立 REP 请求 socket 以接收回复。P2P 相关启用 P2P 时必须同时启用 Controller当配置项enable_p2p开启时LMCache Controller 必须同时启用。此时 Controller 作为中心节点为每一个 chunk 存储元数据信息P2PBackend从 LMCache Controller 查询 chunk 信息并通过NIXL完成实际的数据传输。也就是说Controller 负责找数据NIXL 负责传数据。关键特性面向用户与编排器的 8 类管理 APIController 对外暴露一组 API供用户与编排器orchestrator管理 KV Cache。当前提供的 API 及对应文档如下API功能详细文档Clear清除 KV CacheclearCompress压缩 KV CachecompressHealth检查缓存 Worker 的健康状态healthLookup根据 token 列表查询 KV CachelookupMove将 KV Cache 迁移到不同位置movePin持久化 KV Cache 防止被驱逐pinCheckFinish检查非阻塞控制事件是否完成check_finishQueryWorkerInfo查询 Worker 信息query_worker_info在 Controller 与 Worker 的交互层面当前 LMCache Worker 支持以下功能向 Controller 注册register、从 Controller 注销deregister、心跳heartbeat以及上报 admit / evict chunk 信息面向 LocalCPUBackend 或 LocalDiskBackend。从 API 服务源码 可以看出每个管理接口/lookup、/clear、/pin、/compress、/decompress、/move、/health、/check_finish、/query_worker_info均以 FastAPI POST 路由实现请求体由 PydanticBaseModel定义每个请求会生成一个 UUID 形式的event_id再将对应的控制消息交给LMCacheControllerManager分发处理。快速开始启动 Controller 与配置说明启动 Controller在命令行直接运行以下命令即可启动 Controllerpython3 -m lmcache.v1.api_server预期输出大致如下[2025-11-11 11:15:35,277] LMCache WARNING: Argument --monitor-port will be deprecated soon. Please use --monitor-ports instead. (__main__.py:361:__main__) INFO 11-11 11:15:36 [__init__.py:239] Automatically detected platform cuda. /usr/local/lib/python3.12/dist-packages/pydantic/_internal/_fields.py:198: UserWarning: Field name copy in create_app.locals.MoveRequest shadows an attribute in parent BaseModel warnings.warn( [2025-11-11 11:15:37,956] LMCache INFO: Starting LMCache controller at 0.0.0.0:9000 (__main__.py:371:__main__) [2025-11-11 11:15:37,956] LMCache INFO: Monitoring lmcache workers at ports None (__main__.py:372:__main__) INFO: Started server process [50664] INFO: Waiting for application startup. INFO: Application startup complete. INFO: Uvicorn running on http://0.0.0.0:9000 (Press CTRLC to quit)从输出可以看到Controller 默认监听0.0.0.0:9000由 Uvicorn 承载 FastAPI 应用。运行日志中的 WARNING 提示--monitor-port即将废弃应改用--monitor-ports。Controller 命令行配置参数参数默认值说明--host0.0.0.0监听地址--port9000对外暴露端口lookup 等管理接口通过该端口访问--monitor-port9001LMCache Worker 与 Controller Manager 通信的端口已废弃对应--monitor-ports中的 pull 端口reply 端口为 None--monitor-portsNone若配置需传入 JSON 格式字符串例如{pull: 8300, reply: 8400}与之对应的服务端配置定义可参见 lmcache/v1/cache_controller/config.pycontroller_host默认0.0.0.0、controller_port默认9000、controller_monitor_ports默认{pull: 8300, reply: 8400}JSON 字符串此外还支持health_check_interval健康检查间隔秒-1表示禁用与lmcache_worker_timeoutWorker 超时时间默认 300 秒。YAML 配置在 LMCache 引擎侧的 YAML 配置文件中与 Controller 相关的配置如下enable_controller: True lmcache_instance_id: lmcache_instance_id controller_pull_url: ip:pull_port # 若 controller reply port 为 None则无需配置 reply url controller_reply_url: ip:reply_port # LMCache Worker 的端口数量必须等于 rank 的数量 lmcache_worker_ports: [1, 2, 3] # p2p 配置 p2p_host: localhost p2p_init_ports: [11, 12, 13]关键字段说明enable_controller是否启用 Controller 模式lmcache_instance_id当前 LMCache 实例的唯一标识后续所有管理 API 都通过它定位实例controller_pull_urlWorker 向 Controller 上报消息的地址对应 pull 端口controller_reply_urlController 向 Worker 回复的地址对应 reply 端口若 reply 端口为 None 则无需配置lmcache_worker_ports各 Worker 监听命令的端口列表其数量必须等于 rank 数p2p_host/p2p_init_portsP2P 模式的初始连接配置。从 LMCacheWorker 源码 可以看到controller_pull_url与lmcache_instance_id在enable_controllerTrue时均为必填项缺失会直接抛出ValueError。Clear清除指定位置的 KV Cacheclear接口定义如下clear(instance_id: str, location: str) - event_id: str, num_tokens: int该函数移除指定instance_id在location处存储的 KV Cache返回event_id与计划清除的 token 数量num_tokens。完整操作流程第一步创建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第二步在 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}第三步在 9000 端口启动 Controller、9001 端口启动 monitorlmcache_controller --host localhost --port 9000 --monitor-port 9001第四步向 vllm 发送一个推理请求以生成 KV Cachecurl -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 }第五步清除系统中的 KV Cachecurl -X POST http://localhost:9000/clear \ -H Content-Type: application/json \ -d { instance_id: lmcache_default_instance, location: LocalCPUBackend }Controller 返回类似如下的响应{event_id: xxx, num_tokens: 12}这表示已有12 个 token的 KV Cache 被计划清除。随后可以通过一次 lookup 验证缓存是否确实被清空curl -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] }若 lookup 返回空结果则确认这些 token 对应的 KV Cache 已被清除。实现上/clear路由见 lmcache/v1/api_server/main.py请求通过ClearMsg消息经LMCacheControllerManager分发给对应 Worker 执行Worker 侧处理ClearWorkerMsg见 worker.py 的消息类型导入。Compress / Decompress压缩与解压 KV Cachecompress与decompress接口定义如下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 chunk 进行压缩/解压。Controller 返回event_id与计划压缩/解压的 token 数量。完整操作流程配置与启动步骤与 Clear 一致example.yaml、vllm 实例、Controller 启动命令均相同此处不再重复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_controller --host localhost --port 9000 --monitor-port 9001先向 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 }再通过 tokenize 接口获取 prompt 对应的 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. }响应中可以看到 12 个 token id{count:12,max_model_len:4096,tokens:[128000,849,21435,279,26431,315,85748,6636,304,4221,4211,13],token_strs:null}随后发起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可用于查询操作状态。压缩完成后可以使用相同的methodcachegen进行解压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 正在被解压。示例中的method: cachegen是 LMCache 支持的 KV 压缩算法之一关于压缩方法的更多细节可参考 KV Cache 压缩优化 与 cachegen.rst。/compress与/decompress的 FastAPI 实现分别见 lmcache/v1/api_server/main.py。Health检查缓存 Worker 健康状态health接口定义如下health(instance_id: str) - event_id: str, error_codes: Dict[int, int]该函数返回event_id以及一个将worker_id映射到error_code的字典。error_code为0表示 Worker 健康非零值表示出现错误。操作示例启动 Controllermonitor 端口 9001PYTHONHASHSEED123 lmcache_controller --host localhost --port 9000 --monitor-port 9001发送健康检查请求curl -X POST http://localhost:9000/health \ -H Content-Type: application/json \ -d {instance_id: lmcache_default_instance}Controller 返回类似如下结果{event_id: health47ce328d-f27e-48ae-ab0c-c2218aabce95, error_codes: {0: 0, 1: 0}}其中error_codes列出每个 Worker 的error_code0表示健康非零值表示异常。注意响应中的event_id以health为前缀参见main.py可据此区分操作类型。Controller Manager 侧还运行着周期性的健康巡检任务health_check见 controller_manager.py配合health_check_interval配置项实现后台的 Worker 存活探测。Lookup按 token 列表查询 KV Cachelookup接口定义如下lookup(tokens: List[int]) - event_id: str, layout_info: Dict[str, Tuple[str, int]]该函数接收一个 token 列表作为输入返回event_id与每个 token 的布局layout信息字典。布局信息表示为instance_id到(location, matched_prefix_length)元组的映射。操作示例配置、启动 vllm 实例与 Controller 的步骤与 Compress 章节相同包括PYTHONHASHSEED123环境变量PYTHONHASHSEED123 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} PYTHONHASHSEED123 lmcache_controller --host localhost --port 9000 --monitor-port 9001发送推理请求与 tokenize 请求获取 token id步骤同 Compress 章节然后向 Controller 发送lookup请求curl -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] }预期响应如下{event_id: xxx, lmcache_default_instance: (LocalCPUBackend, 12)}字段lmcache_default_instance为实例 ID其值(LocalCPUBackend, 12)表示该实例中缓存的位置location为LocalCPUBackend匹配的前缀长度为 12即全部 token 命中。event_id是 Controller 操作的标识符通常可以忽略。/lookup的路由实现见 lmcache/v1/api_server/main.py其LookupRequest仅包含tokens: List[int]字段。Move跨实例迁移 KV Cachemove接口定义如下move(old_position: Tuple[str, str], new_position: Tuple[str, str], tokens: Optional[List[int]] [], copy: Optional[bool] False) - event_id: str, num_tokens: int该函数将由tokens标识的 KV Cache chunk 从old_position迁移到new_position。每个位置都是(instance_id, location)元组。将copy设为True时复制而非移动 KV Cache。前置依赖P2P 传输需要安装NIXL。官方文档说明后续将支持其他传输方式例如 Python socket 与 Mooncake。完整操作流程双实例 P2P 迁移第一步准备两个 yaml 文件配置两个 LMCache 实例instance1.yaml# instance1.yaml chunk_size: 256 local_cpu: True max_local_cpu_size: 5 # cache controller configurations enable_controller: True lmcache_instance_id: lmcache_instance_1 controller_pull_url: localhost:8300 controller_reply_url: localhost:8400 lmcache_worker_ports: 8500 # P2P configurations enable_p2p: True p2p_host: localhost p2p_init_ports: 8200 p2p_lookup_ports: 8201 transfer_channel: nixlinstance2.yaml# instance2.yaml chunk_size: 256 local_cpu: True max_local_cpu_size: 5 # cache controller configurations enable_controller: True lmcache_instance_id: lmcache_instance_1 controller_pull_url: localhost:8300 controller_reply_url: localhost:8400 lmcache_worker_ports: 8501 # P2P configurations enable_p2p: True p2p_host: localhost p2p_init_ports: 8202 p2p_lookup_ports: 8203 transfer_channel: nixl第二步启动两个 vllm 引擎分别使用 GPU 0 与 GPU 1、端口 8000 与 8001PYTHONHASHSEED123 UCX_TLSrc CUDA_VISIBLE_DEVICES0 LMCACHE_CONFIG_FILEinstance1.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} PYTHONHASHSEED123 UCX_TLSrc CUDA_VISIBLE_DEVICES1 LMCACHE_CONFIG_FILEinstance2.yaml vllm serve meta-llama/Llama-3.1-8B-Instruct --max-model-len 4096 \ --gpu-memory-utilization 0.8 --port 8001 --kv-transfer-config {kv_connector:LMCacheConnectorV1, kv_role:kv_both}第三步启动 Controller并使用 JSON 格式的--monitor-ports指定 pull 与 reply 端口PYTHONHASHSEED123 lmcache_controller --host localhost --port 9000 --monitor-ports {pull: 8300, reply: 8400}第四步向引擎 1 发送推理请求再通过 tokenize 获取 token id步骤同前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 } 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 将 KV Cache 从引擎 1 的 CPU 迁移到引擎 2 的 CPUcurl -X POST http://localhost:9000/move \ -H Content-Type: application/json \ -d { old_position: [lmcache_instance_1, LocalCPUBackend], new_position: [lmcache_instance_2, LocalCPUBackend], tokens: [128000, 849, 21435, 279, 26431, 315, 85748, 6636, 304, 4221, 4211, 13] }Controller 返回{num_tokens: 12, event_id: xxx}num_tokens表示有多少 token 的 KV Cache 正在被迁移返回的event_id可用于查询操作状态。此例展示了 Controller 作为中心节点在 P2P 场景下的作用它持有每个 chunk 的元数据P2PBackend向它查询 chunk 位置后通过 NIXL 完成数据搬运。/move路由见 lmcache/v1/api_server/main.py注意其 Pydantic 模型中的copy字段名会触发父类BaseModel的属性遮蔽警告即启动日志中出现的 UserWarning。Pin持久化 KV Cache 防止驱逐pin接口定义如下pin(instance_id: str, location: str, tokens: List[int]) - event_id: str, num_tokens: int该函数将instance_id的指定location中由tokens标识的 KV Cache chunk 固定持久化。Controller 返回event_id与计划固定的 token 数量。固定后的缓存不会被常规的驱逐策略回收适用于热数据保活等场景。操作示例配置与启动步骤与 Clear 章节一致example.yaml、vllm 实例、Controller 启动命令均相同。向 vllm 发送推理请求并 tokenize 获取 token id 后发送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 数量event_id可用于查询操作状态。/pin路由实现见 lmcache/v1/api_server/main.py。CheckFinish查询非阻塞控制事件的完成状态check_finish接口定义如下check_finish(event_id: str) - event_id: str, is_finished: bool该接口用于查询某个非阻塞控制事件是否已经完成。其核心语义是Clear、Compress、Move、Pin 等控制操作都是异步下发的Controller 会立即返回event_id调用方随后用该event_id轮询check_finish以确认操作是否真正执行完毕。该接口的 FastAPI 路由/check_finish已经实现于 lmcache/v1/api_server/main.py内部通过CheckFinishMsg消息查询事件状态。官方文档目前标注该接口的详细说明为 Coming soon...使用时请以仓库实际实现为准。QueryWorkerInfo查询 Worker 信息query_worker_info接口定义如下query_worker_info(instance_id: str, worker_ids: List[int]) - event_id: str, worker_infos: List[WorkerInfo]该函数获取由instance_id与worker_ids指定的 Worker 信息。Controller 返回event_id与 worker 信息列表。操作示例配置与启动步骤与 Clear 章节一致。直接向 Controller 发送请求curl -X POST http://localhost:9000/query_worker_info \ -H Content-Type: application/json \ -d { instance_id: lmcache_default_instance, worker_ids: [0] }Controller 返回类似如下结果{event_id: xxx, worker_infos: [{instance_id: lmcache_default_instance, worker_id: 0, ip: 127.0.0.1, port: 8001, peer_init_url: 127.0.0.1:8200, registration_time: 123456, last_heartbeat_time: 456789}]}worker_infos包含所查询 Worker 的信息其中关键字段有instance_idWorker 所属的 LMCache 实例worker_idWorker 编号ip/portWorker 监听命令的地址与端口对应lmcache_worker_ports中的配置peer_init_urlP2P 初始连接地址对应p2p_init_ports配置registration_time/last_heartbeat_time注册时间与最近一次心跳时间可用于判断 Worker 的活跃程度。/query_worker_info路由见 lmcache/v1/api_server/main.pyWorkerInfo数据结构定义于 cache_controller/message.py 的消息类型集合中。结语一套完整的 KV Cache 集中管理协议LMCache Controller 将 KV Cache 的管理从推理引擎进程中解耦出来形成集中控制平面 分布式执行平面的架构Reg Controller 维护 Worker 生命周期KV Controller 维护 chunk 元数据Cluster Executor 负责指令下发8 类 HTTP API 则覆盖了缓存生命周期中的查询、迁移、压缩、清除、持久化与健康巡检等关键操作。虽然官方已将 in-process mode 标记为弃用并建议迁移至 MP mode但本文涉及的接口语义event_id异步事件模型、(instance_id, location)位置模型、token 级 chunk 寻址在理解 LMCache 的缓存管理理念时仍然通用。进一步阅读可参考 kv_cache_management 目录 下的各 API 文档或结合 clear 示例、move 示例 等仓库内示例进行实操验证。【免费下载链接】LMCacheLMCache: Supercharge Your LLM with the Fastest KV Cache Layer项目地址: https://gitcode.com/GitHub_Trending/lm/LMCache创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考