LMCacheRawCudaIPCWrapper深度解析基于驱动级 CUDA IPC 共享 PyTorch 之外的 KV Cache【免费下载链接】LMCacheLMCache: Supercharge Your LLM with the Fastest KV Cache Layer项目地址: https://gitcode.com/GitHub_Trending/lm/LMCacheRawCudaIPCWrapper是 LMCache 多进程MP传输层中专用于共享PyTorch 缓存分配器之外的 CUDA KV Cache 的 IPC 包装器。它绕过UntypedStorage._share_cuda_()直接走驱动级cudaIpcGetMemHandle/cudaIpcOpenMemHandle从而让 TRT-LLM 这类以at::for_blobcudaMalloc分配 KV 池的引擎也能与 LMCache 服务端跨进程共享 KV Cache。读完本文你将掌握它为何存在、完整的共享与重建链路、uint8字节往返背后的设计动机、单一 wire 格式如何通过共享基类实现以及发送端校验、生命周期管理和接入方式。为什么需要第二个包装器默认的CudaIPCWrapper位于 lmcache/v1/platform/cuda/ipc_wrapper.py通过调用tensor.untyped_storage()._share_cuda_()来发布存储走的是 PyTorch 的存储级 IPC 路径。该路径有一个硬性前提存储必须由 PyTorch 的缓存分配器拥有。TRT-LLM 的 KV 池是通过at::for_blob(...)包装一个裸的cudaMalloc指针得到的存储并不归 PyTorch 缓存分配器所有因此_share_cuda_()会直接抛异常vLLM 风格的包装器无法使用。RawCudaIPCWrapper的设计目标就是完全绕开 PyTorch 的 IPC 层只依赖 CUDA 驱动提供的 IPC 原语。从源码看RawCudaIPCWrapper.__init__它还额外解决了另一个问题IPC mem handle 映射的总是整个分配且打开后返回的是分配的基地址而 PyTorch 缓存分配器里的张量通常位于内部指针。因此构造函数通过cuMemGetAddressRange(data_ptr)求出分配基址并记录data_ptr - alloc_base作为字节偏移随句柄一起传输。CudaIPCWrapper → PyTorch storage IPC需共享 /dev/shm RawCudaIPCWrapper → 驱动级 CUDA IPC mem handle无共享 /dev/shm 假设共享与重建的完整链路RawCudaIPCWrapper的发送端和接收端职责划分非常清晰对应源码中的__init__与to_tensor两个方法。发送端包装先做布局归一化attempt_permute_to_contiguous_view把非连续的视图如 vLLM 的 NHD-over-HND置换为连续视图校验tensor.is_contiguous()不连续则直接抛ValueError绝不静默复制调用cuMemGetAddressRange(data_ptr)得到分配基址alloc_base以alloc_base为参数调用cudaIpcGetMemHandle通过cuda.bindings.runtime获取可移植的 IPC handle记录_alloc_offset data_ptr - alloc_base字节偏移、_nbytes、dtype、shape、stride以及device_uuid供接收端按 UUID 解析设备序号。接收端重建to_tensor通过device_uuid反查本地设备序号基类_get_device_index_from_uuid查进程级映射注册表_MAPPED_ALLOCATIONS以 handle 字节为 key未映射则调用cudaIpcOpenMemHandle(handle, cudaIpcMemLazyEnablePeerAccess)建立映射用cupy.cuda.UnownedMemory(base_ptr, alloc_offset nbytes, ownerself)把映射包装成无主内存再以MemoryPointer(mem, alloc_offset)偏移到张量起始处构造一个扁平的uint8CuPyndarray通过 DLPacktorch.from_dlpack转为torch.Tensor用view(self.dtype).reshape(self.shape)恢复逻辑 dtype 与形状。其中第 3 步的无主内存 手动偏移非常关键CUDA IPC handle 只能映射整个分配而张量数据可能落在分配的任意偏移上所以必须由包装器携带并应用这个字节偏移。uint8字节往返刻意为之的 dtype 中立bfloat16与 FP8 这类 dtype 在 CuPy/NumPy 中没有直接的对应类型除非引入ml_dtypes因此重建时不能指望 CuPy 端做 dtype 语义转换。RawCudaIPCWrapper的处理是传输层只关心字节数tensor.numel() * tensor.element_size()一律用扁平uint8数组承载DLPack 对这段字节视图不携带任何 dtype 语义dtype 的恢复完全交给 torch 侧的view(self.dtype)。这样一来一条共享链路即可通吃 FP16、BF16、FP8 等所有 KV Cache dtype无需为每种 dtype 编写转换分支。共享基类而非独立类型单一 wire 格式的基石RawCudaIPCWrapper是CudaIPCWrapper的兄弟类两者共同继承与设备无关的DeviceIPCWrapper基类完整层次见 docs/design/v1/multiprocess/device_ipc_wrapper_design.md。共享单一基类对 wire 格式是承重设计load-bearing原因有三msgspec 不支持自定义 ext 编码类型的 union。KVCache list[DeviceIPCWrapper]是REGISTER_KV_CACHE注册的 msgspec 类型如果为RawCudaIPCWrapper单独引入一个带独立 ext code 的平行类就会迫使解码端使用更宽的 union 类型破坏往返或现有DeviceIPCWrapper消费方。序列化器以基类为 key 分发。_CUSTOMERIZED_SERIALIZERS以DeviceIPCWrapper为 key、ext code 为 1编码钩子按isinstance分发因此每个子类实例都走同一条编码路径。pickle 保留具体子类身份。Serialize是pickle.dumps(obj)Deserialize是pickle.loads具体子类身份随 pickle 穿过 wire 后依然存在接收端to_tensor()据此分发到正确的 override。因此接收端服务不需要任何按类型的分支到达LMCacheDrivenTransferModule.register_kv_cache的list[DeviceIPCWrapper]可以混合任意具体包装器to_tensor()各自做正确的事。基类还统一提供了dtype/shape/stride/storage_offset/device_uuid接口字段、UUID↔序号发现机制以及带type(self) is type(other)严格守卫的__eq__见 lmcache/v1/platform/base/ipc_wrapper.py。发送端校验连续性是硬约束而非可修复项设计文档明确指出RawCudaIPCWrapper.__init__走的是断言连续路线而不是置换permute路线。原因很实际——TRT-LLM 的 KV 池是连续分配的非连续输入只可能是发送端做错了应当响亮地暴露出来而不是静默地.contiguous()复制几个 GB 的 KV Cache。从当前源码看实现把这两者做了结合先attempt_permute_to_contiguous_view处理可置换的常见非连续视图元数据级操作、不搬数据随后显式检查tensor.is_contiguous()仍不连续则抛出带 shape/stride 信息的ValueError。这与gpu_connector/utils.py中assert_contiguous的定位一脉相承LMCache 的传输 kernel 假设逻辑与物理布局一致边界处拿到非连续张量时拒绝而非猜测。tests/v1/platform/test_cuda_ipc_wrapper.py中亦有针对非连续输入的负例测试验证了这一契约。重建生命周期与引用计数接收端映射的生命周期管理是本文最容易踩坑的部分源码用进程级注册表 引用计数解决一个物理映射只建立一次驱动对同一个 (进程, 分配)无论打开多少次都只返回一份映射因此_MAPPED_ALLOCATIONS以 handle 字节为 key 缓存[mapped_ptr, opens]同一分配上的逐层张量共享同一映射只有最后一个包装器关闭时才真正解除映射_MAPPINGS_LOCK保证并发安全。未关闭的映射会钉住导出进程的显存即使导出进程如已退出的 vLLM worker死亡其 KV 池也会驻留直到服务端关闭或退出——这是必须正确释放的原因。UnownedMemory的ownerself包装器实例在张量存活期内钉住映射包装器被 GC 后映射随之释放而底层 TRT-LLM 分配的生命周期由 TRT-LLM 自己管理比包装器更长。没有对称的cudaIpcCloseMemHandle调用点torch 通过 DLPack 引用计数 CuPy/MemoryPointer的 owner 字段来控制生命周期显式的释放走close()方法——它把本包装器的_opens从注册表条目中扣除最后一个引用释放时调用cudaIpcCloseMemHandle且失败只记日志不抛异常因为close常运行在 worker 回收等 teardown 路径上抛异常会中断剩余条目的清理。为什么不做_share_cuda_回退RawCudaIPCWrapper不会先尝试_share_cuda_()再回退。设计文档给出的理由值得重视回退会把两条代码路径耦合在一起而且失败模式是静默损坏——PyTorch 可能为调用者实际想要的内存区域之外的另一块区域返回 handle。与其在错误内存上继续运行不如让RawCudaIPCWrapper作为CudaIPCWrapper的独立兄弟类存在把用哪种 IPC的选择权留在调用点。在项目中的实际接入方式RawCudaIPCWrapper在项目中有两条明确的接入路径其一TRT-LLM 适配器直接实例化。在 lmcache/integration/tensorrt_llm/tensorrt_mp_adapter.py 的register_kv_caches中TRT-LLM 的 4 维 KV 池张量[NB, NL, 2, NH * BS * HS]被包装为wrapped [RawCudaIPCWrapper(kv_cache_tensor)]连同layout_hintskv_layoutHND、num_kv_heads、tokens_per_block、head_dim一起通过register_kv_cache发送给 LMCache 服务端服务端再据此把 4 维张量重塑为 6 维[NB, NL, 2, NH, BS, HS]以命中格式检测。其二多进程注册路径按开关选择。在 lmcache/v1/platform/cuda/init.py 的_select_ipc_wrapper_cls中三个互斥的进程级开关对应三种包装器开关状态包装器适用场景use_vmm_api开启VmmCudaIPCWrappervLLM cumem 分配器、torchexpandable_segments等 VMM 内存isolated_ipc开启单独RawCudaIPCWrapper驱动级 IPC无共享/dev/shm假设可跨完全隔离的容器默认CudaIPCWrapperPyTorch storage IPCisolated_ipc开关定义在 lmcache/v1/platform/isolated_ipc.py默认关闭因为 SGLang、TensorRT-LLM、CacheBlend、qstore 集成仍会创建原始 CUDA 互进程事件而隔离场景下需改选 timeline-semaphore 事件后端。值得注意RawCudaIPCWrapper有意不注册到DeviceSpec.ipc_wrapper_cls的默认绑定上以便与CudaIPCWrapper共存不冲突——TRT-LLM 适配器直接实例化它而 MP 注册路径由开关驱动。小结RawCudaIPCWrapper用最朴素的 CUDA 驱动原语解决了 LMCache 多进程传输中最棘手的一类内存共享问题不归 PyTorch 缓存放分配器管的 CUDA 内存。它的设计处处体现宁可显式失败、不可静默损坏的工程取舍——字节偏移精确定位、uint8往返保证 dtype 中立、共享基类保住单一 wire 格式、引用计数注册表管好映射生命周期、发送端强校验拒绝非连续输入。配合device_ipc_wrapper_design.md中描述的DeviceIPCWrapper层次与platform注册机制任何新的设备后端都可以作为又一个兄弟类接入而无需改动 wire 格式。【免费下载链接】LMCacheLMCache: Supercharge Your LLM with the Fastest KV Cache Layer项目地址: https://gitcode.com/GitHub_Trending/lm/LMCache创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 LMCache `RawCudaIPCWrapper` 深度解析：基于驱动级 CUDA IPC 共享 PyTorch 之外的 KV Cache
LMCacheRawCudaIPCWrapper深度解析基于驱动级 CUDA IPC 共享 PyTorch 之外的 KV Cache【免费下载链接】LMCacheLMCache: Supercharge Your LLM with the Fastest KV Cache Layer项目地址: https://gitcode.com/GitHub_Trending/lm/LMCacheRawCudaIPCWrapper是 LMCache 多进程MP传输层中专用于共享PyTorch 缓存分配器之外的 CUDA KV Cache 的 IPC 包装器。它绕过UntypedStorage._share_cuda_()直接走驱动级cudaIpcGetMemHandle/cudaIpcOpenMemHandle从而让 TRT-LLM 这类以at::for_blobcudaMalloc分配 KV 池的引擎也能与 LMCache 服务端跨进程共享 KV Cache。读完本文你将掌握它为何存在、完整的共享与重建链路、uint8字节往返背后的设计动机、单一 wire 格式如何通过共享基类实现以及发送端校验、生命周期管理和接入方式。为什么需要第二个包装器默认的CudaIPCWrapper位于 lmcache/v1/platform/cuda/ipc_wrapper.py通过调用tensor.untyped_storage()._share_cuda_()来发布存储走的是 PyTorch 的存储级 IPC 路径。该路径有一个硬性前提存储必须由 PyTorch 的缓存分配器拥有。TRT-LLM 的 KV 池是通过at::for_blob(...)包装一个裸的cudaMalloc指针得到的存储并不归 PyTorch 缓存分配器所有因此_share_cuda_()会直接抛异常vLLM 风格的包装器无法使用。RawCudaIPCWrapper的设计目标就是完全绕开 PyTorch 的 IPC 层只依赖 CUDA 驱动提供的 IPC 原语。从源码看RawCudaIPCWrapper.__init__它还额外解决了另一个问题IPC mem handle 映射的总是整个分配且打开后返回的是分配的基地址而 PyTorch 缓存分配器里的张量通常位于内部指针。因此构造函数通过cuMemGetAddressRange(data_ptr)求出分配基址并记录data_ptr - alloc_base作为字节偏移随句柄一起传输。CudaIPCWrapper → PyTorch storage IPC需共享 /dev/shm RawCudaIPCWrapper → 驱动级 CUDA IPC mem handle无共享 /dev/shm 假设共享与重建的完整链路RawCudaIPCWrapper的发送端和接收端职责划分非常清晰对应源码中的__init__与to_tensor两个方法。发送端包装先做布局归一化attempt_permute_to_contiguous_view把非连续的视图如 vLLM 的 NHD-over-HND置换为连续视图校验tensor.is_contiguous()不连续则直接抛ValueError绝不静默复制调用cuMemGetAddressRange(data_ptr)得到分配基址alloc_base以alloc_base为参数调用cudaIpcGetMemHandle通过cuda.bindings.runtime获取可移植的 IPC handle记录_alloc_offset data_ptr - alloc_base字节偏移、_nbytes、dtype、shape、stride以及device_uuid供接收端按 UUID 解析设备序号。接收端重建to_tensor通过device_uuid反查本地设备序号基类_get_device_index_from_uuid查进程级映射注册表_MAPPED_ALLOCATIONS以 handle 字节为 key未映射则调用cudaIpcOpenMemHandle(handle, cudaIpcMemLazyEnablePeerAccess)建立映射用cupy.cuda.UnownedMemory(base_ptr, alloc_offset nbytes, ownerself)把映射包装成无主内存再以MemoryPointer(mem, alloc_offset)偏移到张量起始处构造一个扁平的uint8CuPyndarray通过 DLPacktorch.from_dlpack转为torch.Tensor用view(self.dtype).reshape(self.shape)恢复逻辑 dtype 与形状。其中第 3 步的无主内存 手动偏移非常关键CUDA IPC handle 只能映射整个分配而张量数据可能落在分配的任意偏移上所以必须由包装器携带并应用这个字节偏移。uint8字节往返刻意为之的 dtype 中立bfloat16与 FP8 这类 dtype 在 CuPy/NumPy 中没有直接的对应类型除非引入ml_dtypes因此重建时不能指望 CuPy 端做 dtype 语义转换。RawCudaIPCWrapper的处理是传输层只关心字节数tensor.numel() * tensor.element_size()一律用扁平uint8数组承载DLPack 对这段字节视图不携带任何 dtype 语义dtype 的恢复完全交给 torch 侧的view(self.dtype)。这样一来一条共享链路即可通吃 FP16、BF16、FP8 等所有 KV Cache dtype无需为每种 dtype 编写转换分支。共享基类而非独立类型单一 wire 格式的基石RawCudaIPCWrapper是CudaIPCWrapper的兄弟类两者共同继承与设备无关的DeviceIPCWrapper基类完整层次见 docs/design/v1/multiprocess/device_ipc_wrapper_design.md。共享单一基类对 wire 格式是承重设计load-bearing原因有三msgspec 不支持自定义 ext 编码类型的 union。KVCache list[DeviceIPCWrapper]是REGISTER_KV_CACHE注册的 msgspec 类型如果为RawCudaIPCWrapper单独引入一个带独立 ext code 的平行类就会迫使解码端使用更宽的 union 类型破坏往返或现有DeviceIPCWrapper消费方。序列化器以基类为 key 分发。_CUSTOMERIZED_SERIALIZERS以DeviceIPCWrapper为 key、ext code 为 1编码钩子按isinstance分发因此每个子类实例都走同一条编码路径。pickle 保留具体子类身份。Serialize是pickle.dumps(obj)Deserialize是pickle.loads具体子类身份随 pickle 穿过 wire 后依然存在接收端to_tensor()据此分发到正确的 override。因此接收端服务不需要任何按类型的分支到达LMCacheDrivenTransferModule.register_kv_cache的list[DeviceIPCWrapper]可以混合任意具体包装器to_tensor()各自做正确的事。基类还统一提供了dtype/shape/stride/storage_offset/device_uuid接口字段、UUID↔序号发现机制以及带type(self) is type(other)严格守卫的__eq__见 lmcache/v1/platform/base/ipc_wrapper.py。发送端校验连续性是硬约束而非可修复项设计文档明确指出RawCudaIPCWrapper.__init__走的是断言连续路线而不是置换permute路线。原因很实际——TRT-LLM 的 KV 池是连续分配的非连续输入只可能是发送端做错了应当响亮地暴露出来而不是静默地.contiguous()复制几个 GB 的 KV Cache。从当前源码看实现把这两者做了结合先attempt_permute_to_contiguous_view处理可置换的常见非连续视图元数据级操作、不搬数据随后显式检查tensor.is_contiguous()仍不连续则抛出带 shape/stride 信息的ValueError。这与gpu_connector/utils.py中assert_contiguous的定位一脉相承LMCache 的传输 kernel 假设逻辑与物理布局一致边界处拿到非连续张量时拒绝而非猜测。tests/v1/platform/test_cuda_ipc_wrapper.py中亦有针对非连续输入的负例测试验证了这一契约。重建生命周期与引用计数接收端映射的生命周期管理是本文最容易踩坑的部分源码用进程级注册表 引用计数解决一个物理映射只建立一次驱动对同一个 (进程, 分配)无论打开多少次都只返回一份映射因此_MAPPED_ALLOCATIONS以 handle 字节为 key 缓存[mapped_ptr, opens]同一分配上的逐层张量共享同一映射只有最后一个包装器关闭时才真正解除映射_MAPPINGS_LOCK保证并发安全。未关闭的映射会钉住导出进程的显存即使导出进程如已退出的 vLLM worker死亡其 KV 池也会驻留直到服务端关闭或退出——这是必须正确释放的原因。UnownedMemory的ownerself包装器实例在张量存活期内钉住映射包装器被 GC 后映射随之释放而底层 TRT-LLM 分配的生命周期由 TRT-LLM 自己管理比包装器更长。没有对称的cudaIpcCloseMemHandle调用点torch 通过 DLPack 引用计数 CuPy/MemoryPointer的 owner 字段来控制生命周期显式的释放走close()方法——它把本包装器的_opens从注册表条目中扣除最后一个引用释放时调用cudaIpcCloseMemHandle且失败只记日志不抛异常因为close常运行在 worker 回收等 teardown 路径上抛异常会中断剩余条目的清理。为什么不做_share_cuda_回退RawCudaIPCWrapper不会先尝试_share_cuda_()再回退。设计文档给出的理由值得重视回退会把两条代码路径耦合在一起而且失败模式是静默损坏——PyTorch 可能为调用者实际想要的内存区域之外的另一块区域返回 handle。与其在错误内存上继续运行不如让RawCudaIPCWrapper作为CudaIPCWrapper的独立兄弟类存在把用哪种 IPC的选择权留在调用点。在项目中的实际接入方式RawCudaIPCWrapper在项目中有两条明确的接入路径其一TRT-LLM 适配器直接实例化。在 lmcache/integration/tensorrt_llm/tensorrt_mp_adapter.py 的register_kv_caches中TRT-LLM 的 4 维 KV 池张量[NB, NL, 2, NH * BS * HS]被包装为wrapped [RawCudaIPCWrapper(kv_cache_tensor)]连同layout_hintskv_layoutHND、num_kv_heads、tokens_per_block、head_dim一起通过register_kv_cache发送给 LMCache 服务端服务端再据此把 4 维张量重塑为 6 维[NB, NL, 2, NH, BS, HS]以命中格式检测。其二多进程注册路径按开关选择。在 lmcache/v1/platform/cuda/init.py 的_select_ipc_wrapper_cls中三个互斥的进程级开关对应三种包装器开关状态包装器适用场景use_vmm_api开启VmmCudaIPCWrappervLLM cumem 分配器、torchexpandable_segments等 VMM 内存isolated_ipc开启单独RawCudaIPCWrapper驱动级 IPC无共享/dev/shm假设可跨完全隔离的容器默认CudaIPCWrapperPyTorch storage IPCisolated_ipc开关定义在 lmcache/v1/platform/isolated_ipc.py默认关闭因为 SGLang、TensorRT-LLM、CacheBlend、qstore 集成仍会创建原始 CUDA 互进程事件而隔离场景下需改选 timeline-semaphore 事件后端。值得注意RawCudaIPCWrapper有意不注册到DeviceSpec.ipc_wrapper_cls的默认绑定上以便与CudaIPCWrapper共存不冲突——TRT-LLM 适配器直接实例化它而 MP 注册路径由开关驱动。小结RawCudaIPCWrapper用最朴素的 CUDA 驱动原语解决了 LMCache 多进程传输中最棘手的一类内存共享问题不归 PyTorch 缓存放分配器管的 CUDA 内存。它的设计处处体现宁可显式失败、不可静默损坏的工程取舍——字节偏移精确定位、uint8往返保证 dtype 中立、共享基类保住单一 wire 格式、引用计数注册表管好映射生命周期、发送端强校验拒绝非连续输入。配合device_ipc_wrapper_design.md中描述的DeviceIPCWrapper层次与platform注册机制任何新的设备后端都可以作为又一个兄弟类接入而无需改动 wire 格式。【免费下载链接】LMCacheLMCache: Supercharge Your LLM with the Fastest KV Cache Layer项目地址: https://gitcode.com/GitHub_Trending/lm/LMCache创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考