LMCache Controller 实战指南：基于 KV Cache 集中式管理 API 的架构解析与操作手册

LMCache Controller 实战指南：基于 KV Cache 集中式管理 API 的架构解析与操作手册

【免费下载链接】LMCacheLMCache: Supercharge Your LLM with the Fastest KV Cache Layer项目地址: https://gitcode.com/GitHub_Trending/lm/LMCache

LMCache 的 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.py），create_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 类管理 API

Controller 对外暴露一组 API，供用户与编排器（orchestrator）管理 KV Cache。当前提供的 API 及对应文档如下：

在 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

在命令行直接运行以下命令即可启动 Controller：

python3 -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 CTRL+C to quit)

从输出可以看到：Controller 默认监听0.0.0.0:9000，由 Uvicorn 承载 FastAPI 应用。运行日志中的 WARNING 提示--monitor-port即将废弃，应改用--monitor-ports。

Controller 命令行配置参数

与之对应的服务端配置定义可参见 lmcache/v1/cache_controller/config.py：controller_host默认0.0.0.0、controller_port默认9000、controller_monitor_ports默认{"pull": 8300, "reply": 8400}（JSON 字符串），此外还支持health_check_interval（健康检查间隔，秒，-1表示禁用）与lmcache_worker_timeout（Worker 超时时间，默认 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_url：Worker 向 Controller 上报消息的地址（对应 pull 端口）；
• controller_reply_url：Controller 向 Worker 回复的地址（对应 reply 端口），若 reply 端口为 None 则无需配置；
• lmcache_worker_ports：各 Worker 监听命令的端口列表，其数量必须等于 rank 数；
• p2p_host/p2p_init_ports：P2P 模式的初始连接配置。

从 LMCacheWorker 源码 可以看到，controller_pull_url与lmcache_instance_id在enable_controller=True时均为必填项，缺失会直接抛出ValueError。

Clear：清除指定位置的 KV Cache

clear接口定义如下：

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_DEVICES=0 LMCACHE_CONFIG_FILE=example.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 端口启动 monitor

lmcache_controller --host localhost --port 9000 --monitor-port 9001

第四步：向 vllm 发送一个推理请求，以生成 KV Cache

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 }'

第五步：清除系统中的 KV Cache

curl -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 Cache

compress与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_DEVICES=0 LMCACHE_CONFIG_FILE=example.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 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." }'

响应中可以看到 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可用于查询操作状态。压缩完成后，可以使用相同的method（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 正在被解压。示例中的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 健康，非零值表示出现错误。

操作示例

启动 Controller（monitor 端口 9001）：

PYTHONHASHSEED=123 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_code：0表示健康，非零值表示异常。注意响应中的event_id以health为前缀（参见main.py），可据此区分操作类型。Controller Manager 侧还运行着周期性的健康巡检任务（health_check，见 controller_manager.py），配合health_check_interval配置项实现后台的 Worker 存活探测。

Lookup：按 token 列表查询 KV Cache

lookup接口定义如下：

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 章节相同（包括PYTHONHASHSEED=123环境变量）：

PYTHONHASHSEED=123 CUDA_VISIBLE_DEVICES=0 LMCACHE_CONFIG_FILE=example.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"}' PYTHONHASHSEED=123 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 Cache

move接口定义如下：

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: "nixl"

instance2.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 与 8001）：

PYTHONHASHSEED=123 UCX_TLS=rc CUDA_VISIBLE_DEVICES=0 LMCACHE_CONFIG_FILE=instance1.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"}' PYTHONHASHSEED=123 UCX_TLS=rc CUDA_VISIBLE_DEVICES=1 LMCACHE_CONFIG_FILE=instance2.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 端口：

PYTHONHASHSEED=123 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 的 CPU：

curl -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_id：Worker 所属的 LMCache 实例；
• worker_id：Worker 编号；
• ip/port：Worker 监听命令的地址与端口（对应lmcache_worker_ports中的配置）；
• peer_init_url：P2P 初始连接地址（对应p2p_init_ports配置）；
• registration_time/last_heartbeat_time：注册时间与最近一次心跳时间，可用于判断 Worker 的活跃程度。

/query_worker_info路由见 lmcache/v1/api_server/main.py，WorkerInfo数据结构定义于 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