企业官网建设流程全解析

LMCache Query Worker Info 接口实战指南：查询 KV Cache 集群 Worker 状态

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

导读

query_worker_info是 LMCache 缓存控制器（cache controller）提供的一组接口，用于按instance_id与worker_id查询集群中各 KV Cache 工作节点（worker）的注册信息与心跳状态。本文基于 LMCache 仓库中的 query_worker_info.rst 文档，完整讲解该接口的请求/响应格式、示例 YAML 配置、vLLM 与 controller 的启动流程、HTTP 调用方法，并结合 registration_controller.py、message.py 与 api_server/main.py 等源码，深入剖析接口的底层实现原理。读完本文，你将能够独立配置并启动一个带 controller 的 LMCache 实例，熟练调用query_worker_info获取 Worker 的 IP、端口、注册时间、心跳时间等关键信息，并理解其与GET /controller/workers内部 API 的异同。

注意：本文档描述的是 LMCache 的in-process 模式（已弃用）行为。官方建议使用功能更完善、性能更好的 LMCache MP 模式。文中的接口语义（Worker 注册信息、心跳、实例管理）在 MP 模式中同样成立，只是入口与部署形态不同。

一、接口定义与核心概念

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与一组WorkerInfo对象。

1.1 关键数据结构：WorkerInfo

从源码 message.py 可以看到WorkerInfo是一个@dataclass，字段含义如下：

1.2 请求消息 QueryWorkerInfoMsg

在 controller 内部，该接口被封装为QueryWorkerInfoMsg（继承自OrchMsg，编排类消息），其定义见 message.py：

class QueryWorkerInfoMsg(OrchMsg): """Query worker info message""" event_id: str instance_id: str worker_ids: Optional[list[int]] def describe(self) -> str: return f"Query worker info of {self.instance_id} : {self.worker_ids}"

注意这里worker_ids是Optional[list[int]]。从实现来看，当worker_ids为空或未提供时，controller 会返回该实例下的全部 worker 信息（见下文源码分析）。

二、完整实操：配置、启动与调用

2.1 第一步：创建 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_size: 256：KV Cache 分块大小（以 token 数为单位）。该值决定了缓存项的最小粒度，直接影响前缀复用的命中率与存储开销，需要与模型实际推理时的 block 大小配合考虑。
• local_cpu: True：启用本地 CPU 内存作为缓存层级。置为True后 KV Cache 除 GPU 外还可以缓存到本地 CPU 内存。
• max_local_cpu_size: 5：本地 CPU 缓存的最大容量（单位：GB）。达到上限后按缓存淘汰策略逐出旧块。
• enable_controller: True：开启缓存控制器。只有开启后，实例才会向 controller 注册自身、上报心跳，query_worker_info才能查询到该实例的 worker。
• lmcache_instance_id: "lmcache_default_instance"：当前实例在 controller 侧的唯一标识。query_worker_info的第一个参数即与此对应；同一实例的多个 worker 共享该 ID。
• controller_pull_url: "localhost:9001"：controller 的 PULL 监听地址（用于接收 worker 推送的消息），必须与下文启动 controller 时的--monitor-port 9001保持一致。
• lmcache_worker_ports: 8001：worker 对外暴露的服务端口，该值会登记到 controller 中，并出现在WorkerInfo.port字段里。
• p2p_host: "localhost"、p2p_init_ports: 8200：P2P 对等连接的 host 与初始端口，用于 worker 之间建立直连（如 KV 传输），对应WorkerInfo.peer_init_url字段。

2.2 第二步：启动 vLLM / LMCache 实例

在端口 8000 上启动 vLLM 服务，并通过LMCACHE_CONFIG_FILE环境变量加载上面的配置：

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_CONFIG_FILE=example.yaml：LMCache 通过该环境变量加载自定义配置（未设置时使用默认配置）。
• --kv-transfer-config '{"kv_connector":"LMCacheConnectorV1", "kv_role":"kv_both"}'：将 vLLM 的 KV 传输层接到 LMCacheConnectorV1，kv_role为kv_both（同时承担 KV 生产与消费角色），这是 LMCache in-process 模式的标准接入方式。
• 模型与显存参数（--max-model-len、--gpu-memory-utilization）请按实际 GPU 显存调整。

2.3 第三步：启动 LMCache Controller

在端口 9000 启动 controller 主服务、端口 9001 启动 monitor 服务：

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

这里--monitor-port 9001与配置文件中的controller_pull_url: "localhost:9001"对应：controller 在 9001 端口上接收来自 worker 的注册与心跳消息，在 9000 端口上对外提供 HTTP API（包括query_worker_info）。

2.4 第四步：发送查询请求

通过 curl 向 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 的完整信息；返回的event_id可用于后续查询该操作的状态（例如配合check_finish接口使用）。

2.5 请求参数的灵活用法

从源码实现 registration_controller.py 可以看出，query_worker_info对参数的处理存在几个隐含约定，实战中可直接利用：

• instance_id == "all"：查询全部实例下的所有 worker。若同时传入了worker_ids，则会先取全量缓存再按worker_id过滤。对应代码如下：

# Handle special case: instance_id = "all" if msg.instance_id == "all": worker_infos = self.registry.get_all_worker_infos_cached() if msg.worker_ids is not None and len(msg.worker_ids) > 0: worker_infos = [ worker_info for worker_info in worker_infos if worker_info.worker_id in msg.worker_ids ] return QueryWorkerInfoRetMsg(event_id=event_id, worker_infos=worker_infos)

• worker_ids为空（None或[]）：返回该实例下全部worker 的信息；只有显式给出worker_ids时才按 ID 过滤。
• 实例或 worker 不存在：不会报错，而是记录 warning（instance ... not registered./worker ... not registered.）并返回空列表worker_infos，调用方需自行判断结果是否为空。

三、源码级原理：请求在 controller 中的处理链路

3.1 HTTP 层 → 编排消息层

POST /query_worker_info路由定义在 api_server/main.py。它先为请求生成唯一event_id（"QueryWorkerInfo" + str(uuid.uuid4())），再构造QueryWorkerInfoMsg交给handle_orchestration_message分发，最后将返回的QueryWorkerInfoRetMsg包装成 HTTP 响应：

@app.post("/query_worker_info", response_model=QueryWorkerInfoResponse) async def query_worker_info(req: QueryWorkerInfoRequest): try: event_id = "QueryWorkerInfo" + str(uuid.uuid4()) msg = QueryWorkerInfoMsg( event_id=event_id, instance_id=req.instance_id, worker_ids=req.worker_ids, ) ret_msg = await lmcache_controller_manager.handle_orchestration_message(msg) ... return QueryWorkerInfoResponse( event_id=ret_msg.event_id, worker_infos=ret_msg.worker_infos )

3.2 编排分发 → 注册控制器

LMCacheControllerManager.handle_orchestration_message是 controller 所有编排类消息的总入口（controller_manager.py）。QueryWorkerInfoMsg被路由到RegistrationController.query_worker_info：

elif isinstance(msg, QueryWorkerInfoMsg): return await self.reg_controller.query_worker_info(msg)

3.3 注册控制器 → 注册表查询

RegistrationController（注册控制器）负责 worker 的注册、注销、心跳与实例管理，其内部维护一个registry（注册表）。query_worker_info本质上是对注册表的只读查询：先按instance_id找到InstanceNode，再遍历worker_ids取出每个WorkerNode，通过to_worker_info()转换为面向外部 API 的WorkerInfo结构（registration_controller.py）。

值得注意的是，注册表的数据由 worker 的心跳持续驱动：controller 的health_check线程每隔health_check_interval秒检查一次所有 worker 的last_heartbeat_time，若超过lmcache_worker_timeout仍未收到心跳，会主动执行deregister将该 worker 从注册表移除（controller_manager.py）。因此：

通过query_worker_info查询到的结果可以视为“当前 controller 视角下仍存活的 worker 集合”；过期 worker 会在被健康检查清理后不再出现在worker_infos中。

3.4 消息序列化

Controller 内部的消息采用msgspec进行序列化：worker 上报消息使用 MessagePack，而来自外部系统（如 Mooncake）的请求则兼容 JSON（controller_manager.py）。QueryWorkerInfoRetMsg同样是一个OrchRetMsg（见 message.py），最终通过 HTTP JSON 序列化后返回给调用方。

四、补充视角：内部 HTTP APIGET /controller/workers

除了query_worker_info，仓库还提供了另一条查询 worker 信息的内部 HTTP 接口：GET /controller/workers，实现在 worker_info_api.py。两者对比：

若你关心某个 worker 当前缓存了多少 KV 块，GET /controller/workers的key_count字段（通过worker_node.get_kv_count()获取）是更直接的选择；而query_worker_info作为对外编排接口，语义更偏“事件驱动 + 状态查询”，返回的event_id便于与后续状态跟踪接口联动。

五、典型应用场景

1. 集群健康巡检：定期调用query_worker_info（或内部接口）拉取所有实例的worker_infos，检查last_heartbeat_time是否接近当前时间，快速定位失联的 KV Cache worker。
2. P2P 拓扑发现：peer_init_url字段暴露了 worker 的 P2P 初始化地址（如127.0.0.1:8200），上层调度器可根据该信息为新的推理请求规划 KV 传输路径，或判断哪些 worker 适合建立直连。
3. 容量与分布审计：结合registration_time（注册时间）与port/ip字段，可还原实例的扩缩容历史，配合内部接口的key_count评估各 worker 的 KV 负载分布。
4. 配合其他 controller 接口：event_id可与check_finish等接口联动，构成“发起操作 → 查询状态”的异步控制流，适用于大规模集群下的编排场景。

六、总结

query_worker_info是 LMCache 缓存控制器对外提供的一个轻量、只读的 Worker 状态查询接口：它把分布在集群各节点上的 KV Cache worker 的注册信息、P2P 地址与心跳状态统一收敛到 controller，并以(event_id, worker_infos)的结构化形式返回。从源码链路看，一次查询经历HTTP 路由 → 编排消息分发 → 注册表查询三个层次，最终结果由心跳机制持续保鲜。掌握该接口，是理解 LMCache 多实例部署、进行集群健康监控与 P2P 拓扑管理的基础一步；更长期的方案请参考仓库文档中的 LMCache MP 模式 相关章节。

参考文件索引

• 接口定义文档：docs/source/kv_cache_management/query_worker_info.rst
• WorkerInfo与消息定义：lmcache/v1/cache_controller/message.py
• query_worker_info核心实现：lmcache/v1/cache_controller/controllers/registration_controller.py
• 编排消息分发：lmcache/v1/cache_controller/controller_manager.py
• HTTP 路由实现：lmcache/v1/api_server/main.py
• 内部 APIGET /controller/workers：lmcache/v1/internal_api_server/controller/worker_info_api.py
• 健康检查与心跳超时清理：lmcache/v1/cache_controller/controller_manager.py

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