vLLM相关的源码实现：https://github.com/vllm-project/vllm/tree/main/vllm/distributed/kv_transfer

##三个核心概念

###1.LookupBuffer

为什么需要它？
prefill 端和 decode 端请求处理顺序可能不一致（A→B→C vs C→A→B）。
如果只有 FIFO 管道（pipe），就会“顺序错配”。LookupBuffer 的职责就是把“顺序流”转成“按 key 可查”的语义：
insert(key, kv)：写入 KV
drop_select(key)：按请求/块 key 查并取走 KV（可阻塞等待）
所以它本质是“可索引的 KV 中转层”，解决乱序匹配问题，而不是提升算力本身。

LookupBuffer怎么实现的？
LookupBuffer提供了两个API：insert KV Cache和drop_select KV Cache。insert和drop_select的语义类似于SQL，其中insert将KV缓存插入到缓冲区中，而drop_select返回匹配给定条件的KV缓存并将其从缓冲区中删除。

备注：它是一个概念层，新版本不是统一有个 LookupBuffer实现，而是由各 connector 自己决定后端介质。
OffloadingConnector：会用 CPU 内存作为 offload 介质（内存型）
MooncakeConnector：主要是网络传输 + 远端 KV 内存注册，不是单机内存 buffer 模式
Nixl/Multi/P2pNccl：也各自有自己的传输/存储方式

###2.Pipe

用于tensor传输的单向先入先出管道，它支持send_tensor和recv_tensor，代码位置：https://github.com/vllm-project/vllm/blob/main/vllm/distributed/kv_transfer/kv_connector/v1/p2p/p2p_nccl_engine.py#L74

通俗理解，是对NCCL通信库(send/recv)的封装，通信是瓶颈，需要传输的数据多了会排队，实现了一个先入先出的队列，排队做send/recv。

Pipe 仍是概念层，具体实现时，Pipe 能力通常被内嵌在各 connector 的 transport 实现里：
p2p/p2p_nccl_engine.py（NCCL 点对点传输）
mooncake/mooncake_connector.py（Moocake transfer engine + side channel）
nixl_connector.py（NIXL 传输）

###3.Connector

对上：给vLLM scheduler 暴露统一的“可命中多少外部 KV、这步要不要异步加载/保存”的接口
对下：驱动gpu worker 在合适时机执行 KV load/store，并回报完成/失败状态

是对LookupBuffer和Pipe的包装，有多种connector：
simple_connector（依赖手写的cuda代码，在传输时量化到fp8）
lmcache_connector（依赖第三方lmcache包）
MooncakeConnector（依赖手写的cuda代码）
P2pNcclConnector
nixl_connector（依赖NVIDIA Inference Xfer Library (NIXL)，英伟达用于加速推理的点对点通信库）
OffloadingConnector（把存不下的kv cache卸载到cpu内存里）
FlexKVConnectorV1（基于分布式kv缓存系统FlexKV的连接器）

##工作流程
下图展示了上述三个组件是如何协同工作的：

![92c2232f-4c50-4357-8cfc-b7df3f90319d.png](https://developer.qcloudimg.com/http-save/yehe-9497423/e9013ab49bb692e8d6245fe38131f8cc.png)

以用户输入一个prompt维度，看PD分离工作流程图：

![03b9162d-71bd-4d89-a382-15c2f5f76443.png](https://developer.qcloudimg.com/http-save/yehe-9497423/8e783c2b48642878cc91a1250da24558.png)


##理解vLLM实现案例：P2pNcclConnector

以P2pNcclConnector为例，理解上述三个概念：

1. P2pNcclConnector类：https://github.com/vllm-project/vllm/blob/main/vllm/distributed/kv_transfer/kv_connector/v1/p2p/p2p_nccl_connector.py

是标准KVConnectorBase_V1 实现，负责把 vLLM 调度器/worker 生命周期对接到 P2P 传输引擎：
调度侧：
get_num_new_matched_tokens
update_state_after_alloc
build_connector_meta
worker 侧：
start_load_kv
save_kv_layer
wait_for_save
get_finished

2. Pipe层P2pNcclEngine类：https://github.com/vllm-project/vllm/blob/main/vllm/distributed/kv_transfer/kv_connector/v1/p2p/p2p_nccl_engine.py#L74

实现真正的单向FIFO传输

提供 send_tensor/recv_tensor

底层实现是：
控制面：ZMQ（NEW/PUT/GET 消息握手）
数据面：NCCL ncclSend/ncclRecv

3. LookupBuffer 层：在 p2p 里是“内嵌状态容器”，不是独立类
在 p2p 实现中没有单独 LookupBuffer 类，但有等价功能：
recv_store：按 tensor_id 存放已收到 tensor（供 recv_tensor 等待/提取）
send_store：GET 模式下按 tensor_id 暂存可被远端拉取的数据
send_request_id_to_tensor_ids / recv_request_id_to_tensor_ids：按请求跟踪 tensor 集合
这就是“lookup by key”的落地：key 是 tensor_id=request_id#layer_name，value 是 KV tensor（或内存池句柄）。


另外，在p2p这级目录下，我也注意到有一个tensor_memory_pool.py文件。https://github.com/vllm-project/vllm/blob/main/vllm/distributed/kv_transfer/kv_connector/v1/p2p/tensor_memory_pool.py

tensor_memory_pool.py 实现的是 TensorMemoryPool：在固定一块 pinned host 内存里，用 buddy 算法做分配/回收，用来把 GPU tensor 暂存到 CPU（pinned），或再拷回 GPU。

它主要给 P2pNcclEngine 用：当接收端 KV 超过 kv_buffer_size 阈值时，不把整块 tensor 长期留在 GPU 显存里，而是 存进池子，只保留 (addr, dtype, shape) 元组（见 p2p_nccl_engine.py 里对 pool.store_tensor / pool.load_tensor / pool.free 的调用）。


最后，如果我们重写了connector，通过修改kv transfer config可以生效：
![d8d87bdf-c802-49ed-996f-4c56e38bde45.png](https://developer.qcloudimg.com/http-save/yehe-9497423/359cb93307c24415da887cae3024564f.png)


vLLM相关的源码实现：https://github.com/vllm-project/vllm/tree/main/vllm/distributed/kv_transfer

vLLM Disaggregated Prefilling源码学习

从源码角度分析vLLM Disaggregated Prefilling功能，理解vLLM如何实现PD分离。

AI Infra工程师

人工智能

vLLM分布式KV传输核心组件解析：LookupBuffer解决乱序匹配问题，Pipe实现NCCL通信封装，Connector统一调度接口。涵盖P2pNcclConnector、MooncakeConnector等实现，优化KV缓存传输效率。深入源码分析tensor内存池管理及异步加载机制，提升大模型推理性能。

容器

4核4G3M云服务器 新用户低至38元/年！

2026新春采购季

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

vLLM Disaggregated Prefilling源码学习-腾讯云开发者社区-腾讯云

vLLM Disaggregated Prefilling源码学习

vLLM Disaggregated Prefilling源码学习

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐