LMCache Integration Modules and Division of Labor

概述

本文档详细说明 LMCache 与 vLLM 集成的完整架构、组件职责、核心数据结构以及调用链路。

一、架构分层与职责边界

LMCache 与 vLLM 的集成涉及两个代码仓库，各层职责明确：

vLLM 仓库层

vLLM 仓库负责 KV Connector 层，作为 vLLM 与 LMCache 之间的适配器。

• 文件位置: vllm/distributed/kv_transfer/kv_connector/v1/
• 核心文件:
  • lmcache_connector.py: 包含 LMCacheConnectorV1，负责工厂注册和实现分发，根据配置选择 v1 或 latest 实现
  • lmcache_integration/vllm_v1_adapter.py: 包含 LMCacheConnectorV1Impl，是核心实现
• Scheduler 侧职责: 请求管理、KV 查找、生成 load/save spec
• Worker 侧职责: 调用 LMCacheEngine 进行 KV 读写
• 核心数据结构: RequestTracker（请求状态追踪）、ReqMeta（请求元数据）、LoadSpec（加载规格）、SaveSpec（保存规格）、DisaggSpec（解聚规格）、LMCacheConnectorMetadata（Step 级元数据）

LMCache 仓库层

LMCache 仓库负责核心引擎、GPU Connector、存储后端以及辅助服务。

核心引擎层 (lmcache/v1/):

• LMCacheEngine 是核心引擎，负责协调 KV cache 的存储和检索，持有 gpu_connector、storage_backend、lookup_server 等组件，提供 retrieve_layer()、store_layer()、retrieve()、store() 等方法
• LMCacheEngineConfig 是引擎配置类，包含 chunk_size（缓存块大小，默认 256）、use_layerwise（是否逐层模式）、enable_blending（是否启用 blending）、save_decode_cache（是否保存 decode 缓存）、enable_async_loading（是否异步加载）、remote_serde（远程序列化方式）等配置项
• LMCacheEngineMetadata 是引擎元数据类，包含 model_name（模型名）、world_size（GPU 数量）、rank（当前 rank）、kv_dtype（KV 数据类型）、kv_shape（KV 张量形状）、use_mla（是否使用 MLA）等信息
• LMCacheEngineBuilder 是引擎工厂，通过 get_or_create() 方法管理引擎实例

GPU Connector 层 (lmcache/v1/gpu_connector.py):

GPU Connector 负责 GPU 内存与缓存存储之间的数据传输，提供三种实现：

• VLLMPagedMemGPUConnectorV2（默认模式）: 一次性读写所有层的 KV cache，支持 MLA，数据结构包含 hidden_dim_size（隐藏层大小）、num_layers（层数）、chunk_size（块大小）、dtype（数据类型）、device（GPU 设备）
• VLLMPagedMemLayerwiseGPUConnector（逐层模式）: 逐层读写 KV cache，返回生成器支持 layer-by-layer 流水线，数据结构同上并增加 layerwise 状态机
• VLLMBufferLayerwiseGPUConnector（逐层 + Blending）: 逐层模式并支持 blending 操作，数据结构同上并增加 blending buffer

Storage Backend 层 (lmcache/v1/storage/):

Storage Backend 负责 KV cache 的持久化存储和检索，提供 LocalStorageBackend（本地内存/磁盘）、RemoteBackend（远程服务器）以及 Serializer/Deserializer（序列化/反序列化）组件。

辅助服务层 (lmcache/v1/):

• lookup_client/: 包含 LookupClientFactory 和 LMCacheAsyncLookupServer（异步查找服务器）
• compute/blend/: 包含 LMCBlenderBuilder 和 LMCBlender（Blending 混合器）
• offload_server/: 包含 ZMQOffloadServer（ZMQ 离线服务器）
• observability/: 包含 LMCStatsMonitor（性能监控）

二、详细组件职责

vLLM 侧

LMCache 侧

三、核心数据结构

请求级别结构

RequestTracker 用于追踪单个请求的完整状态：

@dataclass
class RequestTracker:
    req_id: str                      # 请求 ID
    prompt_len: int                  # prompt 长度
    token_ids: list[int]             # 已调度的 token IDs
    allocated_block_ids: list[int]   # 已分配的 block IDs
    num_saved_tokens: int = 0        # 已保存的 token 数
    disagg_spec: DisaggSpec | None   # 解聚规格
    mm_hashes: list[str] | None      # 多模态 hashes
    mm_positions: list[PlaceholderRange] | None  # 多模态位置
    request_configs: dict | None     # 请求配置
    is_decode_phase = False          # 是否在 decode 阶段
    skip_save: bool = False          # 是否跳过保存

ReqMeta 是请求的运行时元数据：

@dataclass
class ReqMeta:
    req_id: str                      # 请求 ID
    token_ids: list[int]             # token IDs
    slot_mapping: torch.Tensor       # slot 映射
    is_last_prefill: bool = False    # 是否最后一次 prefill
    save_spec: SaveSpec | None       # 保存规格
    load_spec: LoadSpec | None       # 加载规格
    disagg_spec: DisaggSpec | None   # 解聚规格
    request_configs: dict | None     # 请求配置

Step 级别结构

LMCacheConnectorMetadata 是每个调度步骤的元数据容器：

@dataclass
class LMCacheConnectorMetadata(KVConnectorMetadata):
    requests: list[ReqMeta]                    # 本 step 的请求列表
    lookup_requests_in_step: list[str]         # 本 step 需要查找的请求 ID

四、完整调用链

整个调用链分为 Scheduler 线程和 Worker 线程两个部分：

Scheduler 线程流程:

1. 新请求到达时，调用 LMCacheConnectorV1Impl.update_state_after_alloc()，内部调用 RequestTracker.from_new_request() 创建 RequestTracker、LoadSpec、SaveSpec
2. 构造 Step 元数据，通过 LMCacheConnectorMetadata.add_request(ReqMeta) 将请求添加到本 step 的请求列表
3. 执行 KV 查找，通过 LookupClientFactory.create_lookup_client() 创建查找客户端，调用 LMCacheAsyncLookupServer.lookup() 进行异步查找

元数据传递: Scheduler 线程将构造好的 LMCacheConnectorMetadata 传递给 Worker 线程

Worker 线程流程:

1. 加载 KV（forward 前）: 调用 start_load_kv(forward_context)，内部调用 lmcache_engine.retrieve_layer()，通过 VLLMPagedMemLayerwiseGPUConnector.retrieve_layer() 从 StorageBackend.read() 读取数据并写入 GPU 内存
2. 逐层等待加载: 调用 wait_for_layer_load(layer_name)，通过 next(layerwise_retriever) 阻塞等待当前层数据就绪
3. 执行 Forward 计算: 调用 model.forward()
4. 保存 KV（每层 forward 后）: 调用 save_kv_layer(layer_name)，内部调用 lmcache_engine.store_layer()，通过 VLLMPagedMemLayerwiseGPUConnector.store_layer() 从 GPU 内存读取数据并写入 StorageBackend
5. 等待保存完成（forward 全部完成后）: 调用 wait_for_save()，遍历所有 storer 并调用 next(layerwise_storer) 等待保存完成
6. 清理元数据: 调用 clear_connector_metadata() 清理本 step 的元数据

五、一句话总结

核心原则: vLLM 负责”调度”，LMCache 负责”存储和传输”。