LMCache 控制器#

概述#

LMCache 控制器的整体架构如图所示，主要由两个部分组成：控制器管理器和 LMCache 工作线程。

控制器管理器主要由 KV 控制器、注册控制器和集群执行器组成。

KV Controller：KV Controller 处理由 LMCache Workers 报告的块信息，并且查找请求从 KV Controller 查询块信息。
Reg Controller: Reg Controller 负责处理来自 LMCache Workers 的注册/注销/心跳请求。
集群执行器：当控制器管理器接收到用户请求，例如清除或移动时，它通过集群执行器将相应的命令发送给 LMCache 工作线程。

LMCache Worker 是一个在排名进程中的线程，负责以下任务：

向注册控制器发送注册、注销和心跳。
将块信息发送到 KV 控制器，包括接纳和逐出消息。
在一个端口上监听以接收来自集群执行器的命令，并执行相应的处理。

关键特性#

暴露一组 API 供用户和调度器管理 KV Cache。

目前，控制器提供以下 API：

清除: 清除 KV 缓存。
压缩: 压缩 KV Cache。
:ref:`Health <health>: 检查缓存工作线程的健康状态。`
查找: 在 KV Cache 中查找给定的令牌列表。
移动: 将 KV Cache 移动到不同的位置。
Pin: 持久化 KV Cache 以防止其被逐出。
:ref:`CheckFinish <check_finish>: 检查一个（非阻塞）控制事件是否已经完成。`
QueryWorkerInfo: 查询工作者信息。

与 LMCache 工作线程交互。

目前，LMCache 工作线程支持以下功能：

向控制器注册
从控制器注销
心跳
接受或逐出块信息（LocalCPUBackend 或 LocalDiskBackend）

快速开始#

启动控制器

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)

控制器配置

--host: 默认值为 0.0.0.0
--port: 默认值为 9000，通过此端口可以访问诸如查找等接口。
--monitor-port: 默认值为 9001，LMCache Worker 与 Controller Manager 通信的端口（已弃用，表示 --monitor-ports 中的拉取端口，回复端口为 None）。
--monitor-ports: 默认值为 None，如果配置，则需要输入 JSON 格式的字符串，例如 {\"pull\": 8300, \"reply\": 8400}。

YAML 配置

enable_controller: True
lmcache_instance_id: "lmcache_instance_id"

controller_pull_url: ip:pull_port
# if controller reply port is None, no need to configure reply url
controller_reply_url: ip:reply_port
# the number of ports for LMCache Worker, must equal to the number of ranks
lmcache_worker_ports: [1, 2, 3]

# p2p configuration
p2p_host: localhost
p2p_init_ports: [11, 12, 13]

LMCache 控制器#

概述#

P2P 相关#

关键特性#

快速开始#