从零理解 CUDA VMM、POSIX FD、FABRIC 与 LMCache:一块 GPU 显存如何跨进程共享
从虚拟地址与物理显存讲起,用交互动画解释 legacy CUDA IPC、VMM、POSIX file descriptor、FABRIC handle、IMEX channel,以及 vLLM extensible KV cache 与 LMCache MP 为什么必须先协商内存访问方式。
从虚拟地址与物理显存讲起,用交互动画解释 legacy CUDA IPC、VMM、POSIX file descriptor、FABRIC handle、IMEX channel,以及 vLLM extensible KV cache 与 LMCache MP 为什么必须先协商内存访问方式。
第一次看到下面这些词时,很容易把它们理解成几种“传输协议”:
VMM / FD / FABRIC / IMEX / CUDA IPC
于是问题越想越乱:FD 是不是一个文件?FABRIC 是不是数据一定经过 NVLink?VMM 是不是把 GPU 显存放进虚拟机?既然 vLLM worker 和 LMCache server 都在同一台机器,为什么不能直接把 GPU pointer 发过去?isolated_ipc 又和 Docker 的 --ipc host 有什么关系?
这篇文章从零开始,只解决一个核心问题:
vLLM worker 拥有一块 GPU KV Cache,LMCache server 是另一个进程。后者怎样安全地“看见”并映射前者的显存?
理解这件事以后,VMM、POSIX FD、FABRIC、IMEX 和这次 LMCache PR #6499 的自动检测,就不再是五个互不相干的名词,而是一条完整因果链。
本文状态固定到 2026-11-11:vLLM extensible KV cache #56492 与 connector access contract #66605 已合并;让 extensible allocation 真正支持 POSIX FD 导出的 #66674 仍是 open PR;LMCache 自动检测 #6499 仍是 Draft。后续状态变化请以链接中的当前代码为准。
CUDA memory sharing · visual field guide
先分清“显存本体、进程内地址、跨进程凭证、传递凭证的通道”四层,几乎所有概念都会自动归位。
假设 vLLM worker 打印出一个地址:
0x7f20_8000_0000
这个数字不是“GPU 上的全球门牌号”。它只在当前 CUDA context / 进程的虚拟地址空间里有意义。另一个进程即使收到完全相同的整数,也没有对应映射;它可能得到错误地址,也可能那里根本没有任何东西。
CPU 进程早就遵循同样规则。进程 A 的 0x1234 和进程 B 的 0x1234 可以指向完全不同的物理页。操作系统用页表完成“虚拟地址 → 物理页”的翻译。GPU 也有类似的虚拟地址与映射机制。
因此跨进程共享显存至少需要四样东西:
真正保存 K/V bytes 的物理显存对象。它不是消息中的 pointer。
把 allocation 映射到 worker 自己的 GPU 虚拟地址,模型 kernel 才能读写。
一个可导出、可导入的能力凭证,让 Server 能引用同一个 allocation。
把凭证从 worker 送到 Server。不同 handle 类型需要不同传递方式。
Server 导入 handle,在自己的地址空间里重新 reserve/map,得到自己的 pointer。
exporter 释放 allocation 之前,importer 必须停止使用并解除映射。
这里最重要的一句话是:
Pointer 是“我从哪里访问”;handle 是“我凭什么重新映射同一块物理内存”。 两个进程不需要得到相同 pointer,只需要最终映射到同一个 allocation。
最经典的路径是:进程 A 用 cudaMalloc / cuMemAlloc 得到普通 device allocation,然后调用 cudaIpcGetMemHandle() 或 cuIpcGetMemHandle() 导出一个 opaque IPC handle。进程 B 收到 handle 后调用 cudaIpcOpenMemHandle() / cuIpcOpenMemHandle(),CUDA driver 在 B 的地址空间中建立映射,返回 B 自己可用的 device pointer。
Process A Process B
cuMemAlloc() receive CUipcMemHandle
│ │
├─ local pointer ├─ cuIpcOpenMemHandle()
│ │
└─ cuIpcGetMemHandle() ── opaque handle ───────────┘
│
└─ B's local pointer
这条路的特点是:
在 LMCache 中,如果 use_vmm_api=false:
isolated_ipc=true 时走 driver-level RawCudaIPCWrapper;为什么要有 Raw wrapper?因为默认 PyTorch storage IPC 路径可能依赖共享 IPC 资源,而隔离容器不应该假设双方共享 /dev/shm 或 host IPC namespace。Raw wrapper 直接传 driver-level handle metadata,减少这层环境耦合。
VMM 是 Virtual Memory Management。这里的“虚拟”不是虚拟机,也不是把显存自动 swap 到磁盘;它表示应用显式管理 GPU 虚拟地址与 physical allocation 的映射。
传统 cudaMalloc(size) 把几件事绑在一起:选择大小、分配 physical memory、建立 mapping、返回 pointer。CUDA VMM 把它拆开:
cuMemAddressReserve:预留一段连续虚拟地址;cuMemCreate:创建 physical allocation handle;cuMemMap:把某个 physical allocation 映射到某段虚拟地址;cuMemSetAccess:授予指定 device 的访问权限;cuMemUnmap、cuMemRelease、cuMemAddressFree。
VMM 的价值不是“pointer 更快”,而是地址稳定、backing 可晚绑定、physical chunks 可精确控制。NVIDIA 官方文档还列出按 allocation 控制 peer accessibility、减少 fragmentation、动态扩展与跨进程共享等用途。CUDA VMM Programming Guide
常见误区:VMM allocation 不是一块普通 `cudaMalloc` memory 加了新名字。它的 physical memory 由 `CUmemGenericAllocationHandle` 表示,所以 legacy `cuIpcGetMemHandle(pointer)` 不是正确共享契约。
VMM physical allocation 是否能被另一个进程导入,必须在创建 allocation 时声明 requestedHandleTypes。LMCache 当前关心两类:
当 allocation 支持 CU_MEM_HANDLE_TYPE_POSIX_FILE_DESCRIPTOR 时,worker 可以调用:
cuMemExportToShareableHandle(..., POSIX_FILE_DESCRIPTOR, ...) -> fd
这个 fd 不是“装着 KV 的普通文件”,也不是把 GPU 数据写进磁盘。它是 Linux 内核维护的一条 process-local descriptor,引用 driver 暴露的 memory object。
这里有一个非常反直觉的细节:
worker 里的 fd = 17
把整数 17 序列化进 ZMQ/gRPC 消息,server 收到 17,并不会得到同一个 fd。server 的 descriptor table 里,17 可能指向日志文件,也可能没有打开。
真正传 fd 必须使用 Unix domain socket 的 ancillary data,也就是 SCM_RIGHTS。内核在接收进程中创建一个新的 fd number,让它引用同一个 kernel object。
LMCache 因此有一条独立于业务 request transport 的 fd channel:
/dev/shm/lmcache_fd_<port>.sock
AF_UNIX + SOCK_SEQPACKET + SCM_RIGHTS
所以 ZMQ/gRPC 使用 TCP 并不等于“fd 也能走 TCP”。worker 和 LMCache server 还必须能看到同一个 Unix socket 路径;在容器部署中,这通常意味着共享对应的 /dev/shm。LMCache 的实现与生命周期说明可见 vmm_cuda_ipc.md。
CUDA 12.4+ 提供 CU_MEM_HANDLE_TYPE_FABRIC。导出的 CUmemFabricHandle 是一个 opaque blob;LMCache 当前按 64 bytes 处理并随 descriptor 传递,不需要在两端共享 Unix socket 文件。
但 FABRIC 不是“免费跨容器魔法”。exporter 与 importer 必须:
IMEX 是 inter-node memory exchange。channel 是 driver 提供的安全与隔离边界,常见设备节点位于:
/dev/nvidia-caps-imex-channels/channel0
同一 channel 的访问权相当于“允许这些进程交换/import fabric memory handle”。NVIDIA 文档明确说明,同一个 IMEX domain 可以覆盖一个 OS,也可以覆盖通过 NVIDIA IMEX daemon 安全连接的多个 OS;在支持的 NVLink fabric 系统上,FABRIC handle 也能用于跨节点映射。NVIDIA VMM / FABRIC 文档
但是本文讨论的 LMCache MP 场景仍然是 vLLM worker 与 LMCache server 的 allocation sharing。不要因为底层 handle 叫 FABRIC,就自动推导出当前 LMCache MP 已经实现任意跨节点 KV cache 映射。
把它压缩成一句判断:
普通 allocation 用 legacy IPC;VMM allocation 必须使用它创建时声明的 shareable handle。非隔离环境可用 POSIX fd,隔离环境通常需要 FABRIC + IMEX。
LLM 推理中的 KV Cache 往往占用大量 GPU memory。vLLM 过去需要在 CUDA graph capture 之前决定 KV cache 大小,因为 graph 会把地址固化进去。
问题在于:真正完成 graph capture、warmup、attention workspace、sampler、speculative decode 等初始化以后,才知道还剩多少显存。提前 profile 只能估算,容易出现两种结果:
vLLM #56492 引入 extensible KV cache,核心技巧正是 VMM:
graph capture 之前:reserve 足够大的 virtual address range
graph capture / warmup:地址保持不变
知道最终可用显存后:create + map 实际需要的 physical chunks
这样 graph 看到的 pointer 不变,而 physical backing 可以在最终 sizing 后确定。该 PR 在 V2 CUDA/ROCm model runner 上默认启用这条路径。
但这又带来一个外部 connector 问题:一段虚拟连续的 KV cache 可能由多个 physical chunks 拼成;RDMA registration 常要求单个物理 allocation;LMCache MP 还需要把 physical allocation 导出给另一个进程。vLLM 不知道每个 out-of-tree connector 怎样访问内存,就无法在 allocation 阶段做对选择。
这就是 vLLM #66605 引入 KVCacheAccess contract 的原因。connector 可以提前声明:
KVCacheAccess |
connector 的含义 | allocation 要求 |
|---|---|---|
IN_PROCESS |
只在 worker 内用 kernel/copy | 任意 allocation |
REGISTERS |
用 UCX/RDMA 注册 | 每段单一 physical chunk |
EXPORTS_FD |
另一个进程通过 POSIX fd import | 单一 chunk,且 fd-exportable |
EXPORTS_FABRIC |
另一个进程通过 FABRIC import | 单一 chunk,且 FABRIC-exportable + IMEX |
LEGACY_IPC |
只支持 legacy CUDA IPC | extensible VMM cache 不兼容 |
注意这里的方向:不是 vLLM 读取 LMCache 私有配置,而是 LMCache connector 公布自己的内存访问契约。 vLLM 再把 connector 需求、GPU 能力、IMEX 条件和其他 MultiConnector 子项组合起来,解析最终 allocation。
截至 2026-11-11,contract 已经合并;EXPORTS_FD 对 extensible allocation 的真正实现仍在 #66674 中。也就是说,枚举值存在不等于所有 allocation path 已经能生产对应 handle。
vLLM worker 拥有真正的 GPU KV cache。LMCache server 需要在另一个进程里映射它,之后才能按 block IDs 执行 store/retrieve。
完整链路可以分成六步:
配置解析阶段返回 `EXPORTS_FD`、`EXPORTS_FABRIC` 或 `LEGACY_IPC`,让 vLLM 在分配前知道共享要求。
结合平台能力与所有 connector,决定是否启用 extensible KV cache,以及 physical allocation 的 requested handle types。
LMCache 根据已解析的 extensible / cuMem allocator 状态选择 `VmmCudaIPCWrapper`;显式 `use_vmm_api` 仍可覆盖。
VMM wrapper 查询 pointer 对应的 allocation,导出 POSIX fd 或 64-byte FABRIC handle,同时保存 shape、stride、offset 等 metadata。
FABRIC handle 可随 descriptor;POSIX fd 必须额外通过 fd channel 的 `SCM_RIGHTS` 发送,并用 export ID 与业务消息配对。
Server 导入同一 physical allocation、reserve/map 自己的地址,再按 metadata 重建 tensor view。之后的 KV 操作访问的是同一显存,不是注册时复制出来的一份。
这也解释了为什么 request transport 与 fd channel 是两回事:
ZMQ / gRPC request channel
└─ 传配置、tensor metadata、export ID、状态
AF_UNIX fd channel(仅 POSIX-fd path)
└─ 通过 SCM_RIGHTS 传真正的 descriptor capability
GPU allocation
└─ KV bytes 留在 GPU,双方映射同一个 physical object
FABRIC path 不需要 fd channel,因为 handle 是可复制的 opaque bytes;但它把环境依赖换成了 IMEX channel access。两条路径不是谁“更高级”,而是安全域与部署边界不同。
在自动检测之前,用户需要手工写:
{
"lmcache.mp.use_vmm_api": true
}
问题是用户配置发生在很早,而 vLLM 的最终 allocation 结果取决于 model runner、平台能力、extensible cache、cuMem allocator、connector access、IMEX 与可能的 MultiConnector 组合。
于是出现一个循环依赖:
LMCache:你最终是不是 VMM?我才能选 wrapper。
vLLM:你需要怎样共享?我才能决定 allocation。
LMCache #6499 把它拆成两个时间点:
use_vmm_api 时,普通 IPC 声明 EXPORTS_FD;isolated_ipc 声明 EXPORTS_FABRIC;显式 false 才声明 LEGACY_IPC。enable_extensible_kv_cache 或 enable_cumem_allocator 得到真实 use_vmm_api。显式 true/false 仍然最高优先级,既用于兼容,也用于故障回退。旧版 vLLM 没有 KVCacheAccess 时,connector 返回 None,继续保留 import compatibility。
| 用户配置 | 分配前声明 | worker 最终行为 | 主要要求 |
|---|---|---|---|
| 未设置 | EXPORTS_FD | 跟随 vLLM 最终 allocation | vLLM 支持 fd-exportable extensible allocation;共享 fd channel 路径 |
| 未设置 + isolated | EXPORTS_FABRIC | 跟随 vLLM 最终 allocation | 设备支持 FABRIC;两端可访问同一 IMEX channel |
false | LEGACY_IPC | 强制 legacy wrapper | vLLM 不应选择只可 VMM 共享的 allocation |
true | FD 或 FABRIC | 强制 VMM wrapper | 实际 allocation 必须导出对应 handle |
引入 extensible KV cache:先 reserve 地址,最终 sizing 后再 map physical chunks。
让 connector 用 `KVCacheAccess` 声明注册、FD、FABRIC 或 legacy IPC 需求。
让 `EXPORTS_FD` 真正创建 fd-exportable extensible allocations,并组合 FABRIC handle types。
默认自动声明 access,并让 worker 跟随 vLLM 已解析的 VMM allocation。
所以“自动检测 PR 已经写完”并不代表整条生产链已经在 released vLLM 中闭环。只有 contract、allocation support、LMCache export/import 与部署环境同时满足,VMM KV cache 才能被 LMCache server 正确映射。
VmmCudaIPCWrapper?use_vmm_api;自动模式要看 vLLM 的 resolved config。CU_MEM_HANDLE_TYPE_POSIX_FILE_DESCRIPTOR?/dev/shm/lmcache_fd_<port>.sock?nvidia-caps-imex-channels 是否存在?CUDA_ERROR_NOT_PERMITTED 时,优先检查 IMEX 权限,而不是 tensor shape。handle 成功只代表“拿到了那块 memory”。要重建正确 tensor,还需要 dtype、shape、stride、storage offset 与 byte span。尤其是 hybrid model 的 dim-0 padding,VMM/Raw wrapper 必须映射包含空洞的完整 byte span,再用 as_strided 恢复 view。关于这部分,可以继续阅读:一段合法的内存空洞,如何让 LMCache CUDA IPC 失效。
SCM_RIGHTS,另一个需要双方访问同一 IMEX channel。如果只记住一个画面,请记住:vLLM worker 与 LMCache server 各自有自己的 pointer;中间传递的 handle 让两边最终映射到同一个 physical allocation。跨进程共享的核心不是“把地址发过去”,而是“把重新映射的能力安全地交过去”。