AI Infra

KV Layout 不该靠猜:从 vLLM #63699 到 RBLN 与 LMCache 的显式轴契约

用 17 张图和两个交互示例,讲清 KV cache 的轴语义、物理布局、内容编码,追踪 allocator 到 connector 的完整调用链,以及 RBLN、MLA、hybrid 模型和 LMCache 接入的边界。

毛宝龙2026/10/26更新于 2026/10/2638 min

同样的 shape、同样的 stride,是否一定表示同样的 KV cache?RBLN 在两个 block 时给出了一个明确的反例:[B,2,H,1,N,D] 和 [2,B,H,1,N,D] 可以在几何信息上完全相同,K/V 的解释却不同。

这篇文章以 vLLM #63699 为主线,说明如何让创建 view 的一方声明轴语义,再沿注册调用链交给 connector。正文、图表和交互都提供完整中英版本,使用页面顶部的语言按钮切换。

如果你还不熟悉 NHD、HND 和 LBHNC,可以先读 vLLM 和 LMCache 的 KV Layout 到底在选什么。本文进一步区分“轴是什么”“字节在哪里”和“内容怎么编码”,并明确标出本 PR 已实现的部分与 LMCache 消费者的后续工作。

文章导航:背景、调用链、相关工作与终态
先读 01–05 了解背景,再对照 diff 阅读 06–11 的调用链,最后用 12–16 判断边界、终态和待办。
01 / 用一张图看懂改动

在创建 view 的地方声明每个轴的含义。

张量提供几何信息,却不会给维度贴上语义标签。新的注册 hook 把这些标签作为独立的类型化声明一起传出去。

图 1 · 生产者 → 注册 → 消费者
Allocator/自定义 backend创建实际的张量 view,知道每个轴的角色。
新增的类型化注册tensors[name]
layouts[name].axes
Connector可以校验并使用声明,也可以继承兼容旧接口的 hook。
LMCache 接入后续:经 adapter、MP 传输和格式解析保留完整语义。
由 #63699 实现现有能力/由集成方负责后续工作

这次增加什么

KVCacheAxis, KVCacheTensorLayout、可选注册 hook、标准 view 的轴声明、runner 传递和 MultiConnector 转发。

哪些信息仍然权威

实际张量的 shape、strides、dtype 和 storage offset。内容编码和 state 粒度仍由 cache spec 定义。

哪些还没完成

硬件插件接入、LMCache 消费、带版本的 MP 协议、任意组件角色,以及不兼容编码之间的转换。

范围: 注册时的 metadata。本 PR 不转置张量、不改 attention kernel,也不声称提升吞吐。

源码: 描述符类型注册契约设计文档

02 / 最初要解决的正确性问题

当 block 数是 2,shape 和 stride 无法判断哪个轴代表 K/V。

RBLN 有两种合法 view:自定义 kernel 使用 [B,2,H,1,N,D];Triton 路径使用 [2,B,H,1,N,D]。当 B=2时,两者的 shape 和连续 strides 完全相同。探测器可以选一种解释,却无法恢复生产者的真实意图。

图 2 · 同一组物理数值,两种语义解释
Shape 和 stride 完全相同

示例取 H=1、N=2、D=1,标量值等于物理偏移。颜色表示声明的组件角色,并非字节中自带的信息。

Block 轴在前

BLOCKKVHEAD1STATEHEAD_DIM

K/V 轴在前

KVBLOCKHEAD1STATEHEAD_DIM

独立构造的标准输出先按组件,再按 block 和 state 排序。B=2 时,相同几何信息会得到不同的 K/V 序列。B=3 时这两种 shape 可区分,但任意 shape 仍不等于语义声明。

为什么仅测往返可能漏掉问题: 用错误解释存储,再用同样的错误解释恢复,仍可能还原原始 buffer。必须与独立构造的 K、V 预期序列比较,才能发现语义错误。

LMCache #5748 增加了两种 RBLN 格式的支持,修复了一项实际部署回归。即使这个探测修复已经存在,两个 block 时的歧义仍说明生产者契约很有价值。

源码: 歧义分析与消费者 RFCRBLN 的 shape 和轴声明独立标准值回归测试

03 / 先把容易混淆的概念分开

“Layout”其实涵盖三份不同的契约。

图 3 · 语义、地址、内容

1 · 轴语义:每个索引是什么意思?

BLOCKHEADSTATECONTENT

KVCacheTensorLayout.axes 描述张量的索引顺序,由本 PR 新增。它不按 stride 给轴排序,也不解释 CONTENT 内部的内容。

2 · 物理几何:字节实际放在哪里?

shape + stride + dtype + storage_offset + storage。现有的 KVCacheLayout 选择 LBHNC、LBNHC 等物理排列。一个 block 不一定是一整段紧密连续的内存。

3 · 内容/state 语义:这些字节存的是什么?

KVCacheSpec 以及 backend 契约定义 packing、head slot、量化、latent/循环状态内容,以及每个 state 对应多少 token。本 PR 不序列化所有这些信息。

名称这里的含义不能据此假设
KVCacheAxis.KV显式二选一轴:索引 0 是 K,索引 1 是 V。不是 cache 数量,也不是 MLA latent 的数量轴。
STATE /逻辑维 N存储的位置或循环状态。一个 state 不一定对应一个原始 token。
CONTENT /维 C每个 head slot、每个 state 的不透明 payload。不隐含 K/V 拆分方式或量化编码。
HEAD /维 H对外 view 中的 head slot。不一定等于模型的 KV head 数量。
层名 key/cache group层名标识注册的张量;group 表达 cache 管理与 spec 的关联。Group 不是张量轴,也不必独占一份 allocation。
LMCache 内部格式消费者内部的语义解释与传输分派方式。它不是 vLLM 物理布局所使用的同一个枚举: KVCacheLayout。

源码: 两类 layout 类型AttentionSpec 的 packing 字段MLAAttentionSpec

04 / 轴含义相同,内存顺序可以不同

标准 view 始终是 BHNC,stride 则可以变化。

公共 allocator 先创建逻辑形状为 [L,B,H,N,C] 的 view,再逐层选取得到 [B,H,N,C]。物理排列和 page padding 由 stride、offset 表达,不需要重命名对外索引的语义。

图 4 · 同一种索引契约,两种物理顺序

LBHNC

同一层、同一 block 内,head 排在 state 前。

H0 N0H0 N1H1 N0H1 N1
cache[b,h,n,c]

LBNHC

同一层、同一 block 内,state 排在 head 前。

N0 H0N0 H1N1 H0N1 H1
cache[b,h,n,c]
示例每层 shape每层 stride,单位为元素轴元组
LBHNC[8,4,16,128][8192,2048,128,1](BLOCK,HEAD,STATE,CONTENT)
LBNHC[8,4,16,128][8192,128,512,1]

彩色条只示意 H/N 单元;数值表取 B=8、H=4、N=16、C=128。这不代表所有 backend 都支持两种顺序。

address(b,h,n,c) = storage_base + element_size × (
    storage_offset + b·stride_B + h·stride_H + n·stride_N + c·stride_C
)

张量的 stride 和 storage_offset 以元素为单位;allocator 规划可能用字节 stride,必须显式换算。轴 metadata 提供 B/H/N/C 的含义,不提供地址公式里的数值。

源码: Stride 计算as_strided 与逐层 view物理布局排列

05 / 推理引擎的哪些地方会产生差异

平台和 backend 约束分配,轴声明描述分配的结果。

图 5 · 现有物理布局选择流程,并非 #63699 新增
Device/平台可用实现、设备能力。
模型与运行配置Attention 类型、dtype、head 维度、显式 backend 设置。
选择 attention backend

选择器调用 current_platform.get_attn_backend_cls(...)。按 cache kind 的配置可以让一个模型使用不同 backend。

Backend 定制 specH/N/C 大小、head slot、packing 和支持的 block 大小。
支持的物理布局每个 backend 声明有偏好的候选集合,或不设限制。
Worker 求交集 → engine core 最终解析

综合各 backend 的兼容集合、worker 报告、混合 spec 与分片约束。显式环境变量必须合法;connector 偏好兼容时采用,否则选择优先候选。

分配时创建实际 view 与轴声明

标准 view 的角色始终是 BHNC;自定义 allocator 必须声明自己实际暴露的 view。

本 PR 没有通用的“device → 轴元组”表。硬件插件使用公共 allocator 时得到标准声明;自建 shape 的插件必须自己声明。本 PR 没有实现或验证 Ascend、MUSA 接入。

源码: 平台选择器Worker 报告布局交集与最终解析Engine core 解析

06 / 跟着主实现走一遍

MRV2:同一个字典,从空容器走到注册。

MRV2 = Model Runner V2,即第二版模型执行器。它属于 vLLM V1 引擎;第 07 节会解释执行器选择,以及 HiSparse 为什么是 MRV2 内部的缓存路径。

tensor_layouts = {} 是输出容器。下面的调用接收同一个字典对象,view 创建函数原地填写它。这不是传给 backend 的“空布局请求”。

图 6 · 点击调用步骤,查看当时的 metadata
注册 metadata 快照

Runner 开始分配

0
已描述的层名数量 · 以两层分配为例

这是对真实调用链的示意,并非某次模型运行的 trace。层名已简化,并额外展示一个共享 cache 的别名。

# GPUModelRunner.initialize_kv_cache
layouts = {}
caches = init_kv_cache(..., tensor_layouts=layouts)
self.kv_connector = get_kv_connector(config, caches, layouts)

# create_kv_cache_views 创建 BHNC view 后填写:
layout = KVCacheTensorLayout((BLOCK, HEAD, STATE, CONTENT))
layouts.update((name, layout) for name in kv_cache_tensor.layers)
为什么在创建 view 时填写: 早期草稿是在后续阶段根据 KVCacheConfig重建标准轴声明。当前 PR 删除了那个 helper,把 metadata 的来源移到实际索引契约建立的地方。

源码: initialize_kv_cacheinit_kv_cacheallocate_kv_cacheView 创建与填写ActiveKVConnector

07 / 执行器选择与 HiSparse 缓存路径

MRV1/MRV2 是执行器,HiSparse 是缓存方案。

MRV1 是 Model Runner V1,即第一版模型执行器;MRV2 是 Model Runner V2,即第二版模型执行器。它们都可以运行在 vLLM V1 引擎中。路径里的 v1 指引擎代际,不是 Model Runner 的版本。

执行器实现位置
MRV1vllm/v1/worker/gpu_model_runner.py
MRV2vllm/v1/worker/gpu/model_runner.py
图 7 · 先选择执行器,再选择 MRV2 内部的 KV 分配路径
Upstream GPU worker

标准 worker 根据 VllmConfig.use_v2_model_runner 决定构造哪一版执行器。

MRV1

第一版模型执行器。

initialize_kv_cache_tensors → 公共 allocator → 类型化 connector 注册。

MRV2

第二版模型执行器。

普通分配

hisparse_config is None
init_kv_cache → allocate_kv_cache

HiSparse 分配

hisparse_config is not None
init_kv_cache → init_hisparse_kv_cache → allocate_hisparse_kv_caches

HiSparse 是 MRV2 内部的一条路径,不是与 MRV1、MRV2 并列的第三版执行器。公共 view 创建函数为 device/host view 生成轴声明;自管理的 raw storage 仍保持未指定。

什么时候选择 MRV1 或 MRV2?

下面按本文固定源码版本的优先级说明。Out-of-tree worker 可以覆写执行器构造逻辑,因此这不是适用于所有 device 的通用选择表。

条件,按优先级排列结果
配置了 HiSparse。必须 MRV2;显式设置 VLLM_USE_V2_MODEL_RUNNER=0 会报错。
配置了 watermarking。必须 MRV2,即使显式设为 0 也会被覆盖。
其余情况下,显式设置 VLLM_USE_V2_MODEL_RUNNER=1。请求 MRV2,仍需通过兼容检查;GPU worker 会拒绝缺少 Triton 的 MRV2 配置。
其余情况下,显式设置 VLLM_USE_V2_MODEL_RUNNER=0。请求 MRV1,仍需通过 MRV1 自身的功能兼容检查。
没有显式设置,且实际平台缺少 Triton。回退到 MRV1。
没有显式设置,且配置命中了 MRV2 尚不支持的功能。回退到 MRV1。
没有显式设置,也不满足以上回退条件。使用 MRV2。

这个版本中,MRV2 的限制示例包括 external_launcher 搭配 pipeline parallel、suffix/custom_class speculative 方法,以及 draft/target 词表不同的配置。支持范围会随版本变化,环境变量也不保证任意配置都能运行,应以对应版本的检查为准。

HiSparse 到底做什么?

HiSparse 是面向稀疏 MLA 的实验性、本地 KV offload 方案。稀疏 attention 每步只选取一部分历史位置,因此可以把历史 KV 保存在 pinned CPU 内存,GPU 使用 resident page 和热点行缓存,以 host 内存与数据传输为代价,降低历史 KV 的 GPU 显存占用。

本步选中的 top-k 历史位置
          ↓
GPU resident page 命中?── 是 → 使用驻留行
          ↓ 否
GPU hot row 命中?──────── 是 → 使用热点缓存行
          ↓ 否
从 pinned CPU 内存补入 GPU hot cache

融合的 GPU resolver 依次检查 resident page、hot row 和 host 内存。Indexer KV 有独立的管理方式;启用 HiSparse 不等于给模型的每个 KV group 都自动创建一份 CPU 副本。

什么时候启用 HiSparse?

直接配置 HiSparseConnector,或通过 MultiConnector 包含它时,会推导出默认 hisparse_config。Connector 提供 host_pool_gib 容量,HiSparseConfig 用来调节 GPU hot buffer 等字段。仍需一份完整且受支持的配置,显存不足本身不会自动开启 HiSparse。

此版本的主要约束:NVIDIA CUDA、MRV2,以及带 index_topk 的 DSA 模型。目前不支持 pipeline parallel 和 decode context parallel。单独的 cudagraph_mode=FULL 会被拒绝;默认的 FULL_AND_PIECEWISE 仍可以为 decode 捕获 full graph。这些是代码里的兼容条件,不代表本 PR 做过相应硬件验证。

HiSparseConnector 管理本地 host/GPU 驻留状态,可以通过 MultiConnector 与 P/D 或其它 offload connector 组合。它的职责与后文尚待实现的 LMCache adapter/MP 接入不同。

这与 #63699 的关系:普通 MRV2 分配和 HiSparse 的 host/device 分配,都必须把实际注册 view 的匹配轴声明传到 connector。本 PR 接通这些 metadata 路径,并不负责选择执行器或启用 HiSparse。Allocator 原有返回类型不变,共享层继承目标描述符,raw buffer 不会被凭空标为 BHNC。

本文审阅版本的源码: 执行器选择优先级MRV2 不支持的功能Worker 构造执行器HiSparse 配置HiSparse 兼容检查HiSparse 架构MRV2 分配分支HiSparse view 分配

08 / 多层、共享别名和 hybrid 模型

层名字典不意味着只有一种布局、一份 allocation 或一种编码。

图 8 · 共享 backing 不会抹去每层 view 的差异
不同层的张量可以指向同一份共享 allocation第 0、1 层有各自的逻辑 view,block page 在 backing 中交错排列。共享别名指向第 0 层。层名选择 view,offset 与 stride 选择字节。layer.0 → view ABHNC 轴 · 各自的 offset/stridelayer.1 → view BBHNC 轴 · 各自的 offset/stridelayer.2 → A 的共享别名同一张量、同一描述符Block 交错分配示例第 0 层/block 0第 1 层/block 0第 0 层/block 1第 1 层/block 1 …第 0 层的 block stride 可能跨过其它层的 page。

图中示意跨层物理 packing。Hybrid group 还可以按 allocator 规划复用或覆盖 storage;不同层名不代表不同 buffer。

注册的 view,示意轴角色还需要解释的信息
Full attention [B,8,16,C₁]BHNCDense K/V 的 packing 与 dtype。
Sliding attention [B,8,16,C₂]BHNC该组的保留策略、block table 与 spec。
压缩 MLA [B,1,4,C₃]BHNCLatent 编码与每个 state 对应的 token 数。
循环状态/Mamba [B,1,1,C₄]标准 view 的轴角色为 BHNC状态组件、各组件 dtype 和 payload 组织。
自管理的 raw backing不提供 entry由其 owner 明确约定,不能假设默认轴语义。
Hybrid 正确性需要的不止是轴: 必须结合每层声明、实际张量、对应的 cache spec/group,以及 block/state 的解释方式。本 PR 不会让所有层变得可以互换。

Attention 绑定阶段可以在分配之后创建 kernel-block view。Connector 接收的是注册的 allocation view 及其匹配描述符,不是从 backend 私有 view 抄来的轴元组。单独一个 BLOCK 标签无法定义索引如何映射到 scheduler block,仍需要 spec 和 block mapping。

源码: Kernel-block 映射与 connector view共享别名混合 spec 分配测试

09 / 一个真实的 out-of-tree 生产者

RBLN 按自己的 shape 选择逻辑声明布局。

图 9 · 自定义 view 通过 hook 接入,无需走 BHNC allocator
use_custom_kernel → 复用已有的 attention_block_axis(...) 来决定 B 插入的位置。
↓

RBLN 自定义算子

[B,2,H,1,N,D]

BLOCKKVHEADSINGLETONSTATEHEAD_DIM

RBLN Triton 算子

[2,B,H,1,N,D]

KVBLOCKHEADSINGLETONSTATEHEAD_DIM
↓
RBLN runner 注册实际逐层 view 与 layouts

校验 shape、保留共享别名,并在接口可用时调用 register_kv_caches_with_layouts 。旧版 vLLM connector 继续走只传张量的路径。

RBLN #1297 是下游适配,并非 #63699 的前置依赖。它会保持 draft,直到 upstream API 合并、进入 RBLN 支持的依赖版本并完成 SDK/运行验证。草稿没有修改当前依赖 pin。旧原型里的命名 TOKEN 已对齐为 STATE。

RBLN 源码版本 a930b4d: Backend 描述符Runner 传递

10 / Size 为 1 的维度,不自动等于 KV 维度

MLA 的标准 view 没有独立的 K/V 选择轴。

描述符里的 KV 角色表示可分别寻址的两个组件,先 K 后 V。MLA 的共享 latent 不应该被标成只有一个元素的 K/V 选择轴。 MLAAttentionSpec 设置 head_size_v=0;内容如何解释仍由 spec 决定。

图 10 · 三种合法的 MLA 声明

标准 view

[B,1,N,C]

BLOCKHEADSTATECONTENT

Size 为 1 的维度代表 head slot,保留 HEAD 角色。

自定义 squeeze 后的 view

[B,N,C]

BLOCKSTATECONTENT

描述符不强制要求 head 轴或 K/V 轴。

带额外占位维的自定义 view

[1,B,N,C]

SINGLETONBLOCKSTATECONTENT

真正的占位维才使用 SINGLETON;有语义的轴保留其角色。

不合法的声明: 把 [1,B,N,C] 描述为 (KV,BLOCK,STATE,CONTENT) 会抛出 ValueError。单个元素并未说明它是 K、V 还是共享 latent。放宽 size 检查只会引入歧义,不会因此编码出 MLA 的语义。

validate_shape 检查 rank、KV 必须为 2、SINGLETON 必须为 1。构造描述符时还会拒绝除 SINGLETON 外重复的命名角色。这些检查不能证明声明真实:相同大小的轴仍可能标错。正确性首先依赖生产者已知的 view 契约。

源码: 校验的边界MLA specMLA 文档

11 / 兼容旧接口,不等于所有消费者自动接入

传递 metadata,不代表每个 connector 都会使用它。

图 11 · 注册时的接口分派
Runner 调用 register_kv_caches_with_layouts(caches, layouts)
↓

旧 connector

继承新增的 base hook。

↓

检查提供的层名 key 和 shape。

↓

self.register_kv_caches(caches)

保留只传张量的原有行为

旧 hook 收不到 layouts。

主动接入的 connector

覆写新的 hook。

↓

结合 spec/group 上下文,校验并解释声明。

↓

保留支持的语义,供传输分派使用。

Metadata 被实际使用

MultiConnector

覆写新的 hook。

↓

把张量和描述符映射转发给每个 child。

↓

各 child 自己选择新/旧接口路径。

支持混合 child

缺少 entry 表示 未指定语义,不是隐含默认值。Base hook 允许部分映射;要求完整显式语义的消费者必须拒绝缺失/不支持的项,或使用定义清楚的 spec-aware 旧路径。覆写 hook 的实现需要在消费前自行校验。

重要边界: 仅有 #63699 不会让现有 LMCache connector 自动停止探测格式。LMCache 必须实现新 hook,并把声明继续带过自己的 adapter 和注册传输链。

源码: Base 兼容 hookMultiConnector 转发

12 / 终态应该是什么,而本 PR 完成了哪一段

声明 → 保留 → 校验 → 注册时解析一次 → 传输。

图 12 · 完整的生产者到消费者契约

生产者掌握真实语义

实际注册的张量、轴声明,以及对应的 spec/group 上下文。无论公共 allocator 还是自定义插件,描述符都必须跟随对外暴露的 view。

↓

vLLM 注册边界

Runner → 类型化 hook → 可选 MultiConnector → child。引擎内部这段传递由 #63699 提供。

↓

消费者 adapter 与 MP 注册

LMCache 后续工作:在 normalization 和 REGISTER_KV_CACHE 中继续传递语义;定义带版本的协议、显式组件角色,以及必需的编码/粒度上下文。Python IntEnum 数值本身不是 wire protocol。

↓

校验并保留支持的内部格式

后续:结合声明、spec 与几何信息,映射到支持的 EngineKVFormat/KVFormatSpec,以及 group/传输行为。显式 metadata 不一致或不受支持时应明确失败,不能改成另一个猜测。

↓

兼容时复用现有执行路径

后续:使用正确的地址几何与 kernel 传输;在恢复、重分配、跨进程交接时保留匹配的 metadata。对不兼容编码进行协商或拒绝,而非承诺任意转换。

青色表示本 PR 的生产者/API 工作;金色虚线表示 LMCache RFC #5866 中的消费者接入与更完整契约,尚未由 #63699 实现或验证。

显式 metadata 路径

生产者声明优先。消费者针对实际 view 做校验,保留结果,后续分派不必反复猜测轴角色。

旧版路径

当格式受支持且解释无歧义时,继续兼容旧引擎。真正有歧义时需要更多信息,单凭 device 名称选默认值不是证据。

来源: LMCache RFC #5866:阶段划分、传输、校验与验收条件

13 / 不传声明,会丢失什么

错误的轴解释,可能最终变成错误的字节选择。

图 13 · 可能的失效链,不是已确认的生产事故
无语义标签的 view消费者只看到 shape 与 stride。
→
探测存在歧义两种支持的解释都符合几何信息。
→
几何解释错误Block/KV 角色或组件拆分错误。
→
传输了错误的字节标准 chunk 中可能出现错配的 K/V 序列。

可见的拒绝

生产者的新布局可能被判为不支持。LMCache #5748 对 RBLN block-first 的支持修复过一项具体集成回归。

静默的语义歧义

大小相同的轴可以通过 shape 和越界检查。独立标准值测试展示了这种风险;本文没有声称已观察到生产模型输出错误。

维护耦合

生产者每次改 shape,都可能要求消费者新增启发式规则,即使生产者本来就知道语义。

并非所有只传张量的集成都不安全。现有 spec-aware 契约可以非常精确,很多布局也没有歧义。问题在于:几何信息或 backend 名称并不总能充当完整语义契约。

源码: RBLN 探测与格式修复信息不足导致的歧义与正确性边界

14 / Metadata 要跟随 view 的生命周期

把张量和它的声明当作一组匹配的信息来维护。

图 14 · 这些变换都需要同步语义
事件张量变化描述符/上下文应如何更新
Permute[B,H,N,C] → [B,N,H,C]轴元组同步置换为 (BLOCK,STATE,HEAD,CONTENT)。
Squeeze 一个 head slot[B,1,N,C] → [B,N,C]从暴露的 view 声明里移除 HEAD,不能仍保留四维描述符。
共享层别名新的层名指向同一张量。在别名 key 下复制目标描述符,两套 runner 已接通。
组件拆分/reshape一份 payload 拆成多个 view,或合并维度。描述新的 view 角色和组件身份;仅置换轴不一定足够。更完整的 schema 仍是后续工作。
重分配/恢复新的 storage 或新的 view。用匹配的新张量/描述符重新注册,不能依赖旧地址或过期 metadata。
跨进程交接不能原样跨进程传递 Python 对象。序列化为消费者理解的带版本契约;保留 dtype/spec/state 上下文,并拒绝不支持的版本。
只有后续 adapter 保留语义,最初那次声明才有意义。张量被重新解释、squeeze 或 regroup 后仍沿用旧轴标签,会重新制造同样的问题。

源码: 描述符生命周期契约Normalization、分组、传输与恢复路线图

16 / Reviewer 可以怎样审阅

先审契约,再跟传递链路。

  1. 1. 类型与校验。 KV 选择轴、HEAD、STATE、不透明 CONTENT 的区别是否清楚?校验是否拒绝不合法的固定大小轴,同时不假装能证明语义正确?
  2. 2. View 创建。 声明是否在实际 BHNC view 创建处产生?是否跳过 raw storage 路径?
  3. 3. Runner 传递。 跟踪新的输出字典,覆盖标准/HiSparse 分配和共享别名,确认注册描述的是 connector 真正拿到的 view。
  4. 4. 兼容性。 继承新接口时是否保留旧 override 的行为?MultiConnector 是否给所有 child 传递相同语义?
  5. 5. 行为测试。 比较独立构造的 K/V 预期值、张量身份、stride、混合 spec、共享别名和错误处理。
  6. 6. 下游边界。 确认 RBLN 使用 upstream 共享契约,而 LMCache 消费者/MP 接入仍明确属于后续工作。
132

通过

在以下版本运行的注册、MultiConnector、attention-utils 和 GPU-connector CPU 测试: 9be42ea。另有一个现有 GPU-only 测试跳过,一个 serving 测试明确未运行。

94

通过

Packing、planning 和 allocation-scope 测试,版本为 9be42ea;缓存所需的 Qwen 配置后通过。

3

MLA 示例检查

文档提交 3838746:三个合法 shape 均通过,KV size 为 1 会被拒绝。适用的 pre-commit 检查通过。

验证边界: 这些检查不代表完成了 GPU/模型 serving E2E、RBLN NPU 运行、Ascend/MUSA 接入或 LMCache 消费者/MP E2E。本地 macOS 环境缺少 rebel,RBLN 定向测试无法完成收集;其 API 对齐改动通过了静态检查。
CPU 复现命令与前置条件

使用 vLLM 开发环境,安装 Python 3.12、pytest 和 tblib;测试运行于 macOS arm64、PyTorch 2.14.1。测试版本为 9be42ea,基于 4b1c04e。现有测试要求缓存 facebook/opt-125m 的配置及 Qwen/Qwen1.5-7B/config.json;这些 CPU 测试不需要模型权重。

VLLM_TARGET_DEVICE=cpu HF_HUB_OFFLINE=1 uv run --no-sync .venv/bin/python -m pytest \
  tests/v1/kv_connector/unit/test_kv_cache_registration.py \
  tests/v1/kv_connector/unit/test_multi_connector.py \
  tests/v1/worker/test_attn_utils.py \
  tests/v1/worker/test_gpu_kv_connector.py \
  -k 'not multi_example_connector_consistency' -q -rs
# 132 passed, 1 skipped, 1 deselected

VLLM_TARGET_DEVICE=cpu HF_HUB_OFFLINE=1 uv run --no-sync .venv/bin/python -m pytest \
  tests/v1/core/test_contiguous_kv_packing.py \
  tests/v1/core/test_kv_cache_planning.py \
  tests/v1/worker/test_kv_cache_allocation_scope.py -q -rs
# 94 passed

验证依据: PR 描述、精确测试版本与 CIRBLN 验证边界与合并前置条件

17 / 测试代码逐项拆解

7 个测试函数,17 个用例:每条断言在保护什么?

这节逐项阅读 tests/v1/kv_connector/unit/test_kv_cache_registration.py,固定到 3838746。不是根据测试名猜意图:下面给出输入、执行链路、独立预期值和断言的实际覆盖范围。代码块保留原测试与参数化装饰器,可直接和固定版本源码对照。

测试用例数核心保护点
two_blocks…2K/V 数值与旧/新 child 兼容
allocator_views…8六种物理布局、两种 padding、alias
invalid_descriptor…3rank / KV / SINGLETON 校验及副作用
unknown_layer…1拒绝多余的 descriptor key
duplicate_semantic_axes1拒绝重复 BLOCK
missing_descriptors…1保持 unspecified
hybrid_allocator…1逐 view 声明、混合几何、共享 backing

先看测试装置:真实 MultiConnector,加两个只记录输入的 child。

TensorRegistrationConnector 只实现旧 register_kv_caches,记录收到的字典;它继承新 hook 的基类实现,所以能检验新接口是否继续调用旧 override。AxisRegistrationConnector 先调用 super 完成基类校验/旧 hook,再记录 layouts,模拟一个理解新契约的消费者。make_connector 用 CPU VllmConfig,通过模块路径和类名动态加载两个 child,角色为 WORKER;不是用 mock 替换注册链路,也不会启动模型 serving。

图 16 · 测试实际执行的注册链路
新 hook:tensor 字典 + layouts
↓
MultiConnector 依次转发
↓
旧 child:基类校验 → 旧 override
新 child:super → 保存 layouts
展开 fixture 与两个 connector 的完整代码

原始测试代码 · L36–L38

class TensorRegistrationConnector(ExampleConnector):
    def register_kv_caches(self, kv_caches: dict[str, torch.Tensor]):
        self.registered_caches = kv_caches

原始测试代码 · L41–L48

class AxisRegistrationConnector(TensorRegistrationConnector):
    def register_kv_caches_with_layouts(
        self,
        kv_caches: dict[str, torch.Tensor],
        layouts: Mapping[str, KVCacheTensorLayout],
    ) -> None:
        super().register_kv_caches_with_layouts(kv_caches, layouts)
        self.layouts = layouts

原始测试代码 · L51–L83

@pytest.fixture
def make_connector():
    def make(kv_cache_config: KVCacheConfig) -> MultiConnector:
        config = VllmConfig(
            device_config=DeviceConfig(device="cpu"),
            scheduler_config=SchedulerConfig(
                max_model_len=16,
                max_num_batched_tokens=16,
                max_num_seqs=1,
                is_encoder_decoder=False,
                disable_hybrid_kv_cache_manager=True,
            ),
            kv_transfer_config=KVTransferConfig(
                kv_connector="MultiConnector",
                kv_role="kv_both",
                kv_connector_extra_config={
                    "connectors": [
                        {
                            "kv_connector": cls.__name__,
                            "kv_connector_module_path": __name__,
                            "kv_role": "kv_both",
                        }
                        for cls in (
                            TensorRegistrationConnector,
                            AxisRegistrationConnector,
                        )
                    ]
                },
            ),
        )
        return MultiConnector(config, KVConnectorRole.WORKER, kv_cache_config)

    return make

1. 两个 block 时,传对描述符还不够,K/V 数值也必须读对。

test_two_blocks_keep_kv_semantics_through_mixed_connectors 有两个参数用例:blocks-first 和 kv-first。两者都把 arange(8) 放进 (2,2,1,1,2,1),所以 shape 和 stride 相同,只有轴声明不同。测试消费者按描述符把 view 置换到 (KV,BLOCK,STATE,HEAD,HEAD_DIM,SINGLETON),再展开比值。

图 17 · 先手算标准答案,再检查消费结果
生产者声明按 block 解释的原始数据统一 K-first 输出
BLOCK → KVb0: K=[0,1], V=[2,3]
b1: K=[4,5], V=[6,7]
K=[0,1,4,5]
V=[2,3,6,7]
KV → BLOCKK: b0=[0,1], b1=[2,3]
V: b0=[4,5], b1=[6,7]
K=[0,1,2,3]
V=[4,5,6,7]

为什么预期值直接写成数组? 标准答案独立于被测代码。如果也用同一套轴解析逻辑算 expected,测试和实现可能一起算错。is caches 检查两个 child 拿到同一个字典;数值断言检查消费者确实保住了 K/V 的含义。offset=0,100 在同一个 connector 上注册两批新 tensor,防止第二次还沿用旧数据;它没有切换描述符,因此不能据此声称已验证“重注册时 layout 改变”。

原始测试代码 · L86–L113

@pytest.mark.parametrize(
    ("axes", "expected"),
    [
        ((Axis.BLOCK, Axis.KV), [0, 1, 4, 5, 2, 3, 6, 7]),
        ((Axis.KV, Axis.BLOCK), list(range(8))),
    ],
    ids=["blocks-first", "kv-first"],
)
def test_two_blocks_keep_kv_semantics_through_mixed_connectors(
    make_connector, axes, expected
):
    """Equal shapes must still give the consumer the producer's K/V values."""
    connector = make_connector(KVCacheConfig(2, [], []))
    layout = KVCacheTensorLayout(
        (*axes, Axis.HEAD, Axis.SINGLETON, Axis.STATE, Axis.HEAD_DIM)
    )
    order = (Axis.KV, Axis.BLOCK, Axis.STATE, Axis.HEAD, Axis.HEAD_DIM, Axis.SINGLETON)
    for offset in (0, 100):
        caches = {"layer": (torch.arange(8) + offset).reshape(2, 2, 1, 1, 2, 1)}
        connector.register_kv_caches_with_layouts(caches, {"layer": layout})
        legacy, consumer = connector.sub_connectors
        assert isinstance(legacy, TensorRegistrationConnector)
        assert isinstance(consumer, AxisRegistrationConnector)
        assert legacy.registered_caches is consumer.registered_caches is caches
        canonical = consumer.registered_caches["layer"].permute(
            *(consumer.layouts["layer"].axis_index(axis) for axis in order)
        )
        assert canonical.flatten().tolist() == [value + offset for value in expected]

2. allocator 创建的 view,经过不同物理布局和共享别名,数值还能找对吗?

test_allocator_views_and_aliases_keep_their_values 展开成 8 个用例:KVCacheLayout 的 6 个成员,加上 LBHNC、BLHNC 的 padded 版本。这里真正调用 compute_layout_strides 和 allocate_kv_cache,没有伪造分配结果;两个层共用 backing allocation,却有各自的 view。

它往 first 写入 0…63,给 second 填 -1,再把 alias 指向 first。消费者根据收到的轴元组构造语义坐标 B=1,H=0,N=2,C=3;在逻辑 (2,2,4,4) 中,该值应为 (((1×2+0)×4+2)×4+3)=43。这个数与物理排列无关,因而能发现“声明和实际 view 对不上”。

最后还检查 second 没被意外覆盖,以及 stride(0) × element_size() 与配置的 block 字节 stride 一致。page_size_padded=144 对比无 padding 的 128 字节页,防止注册过程把页间空隙抹掉。注意:测试只明确断言了 block stride;layer stride 参与构造,但没有单独等式断言。alias 的 tensor 和 descriptor 都由测试手动接线,证明接好后能正确传递,不等于执行了两套 runner 的自动 alias 接线。

原始测试代码 · L116–L176

@pytest.mark.parametrize(
    ("physical_layout", "padded"),
    [(layout, False) for layout in KVCacheLayout]
    + [(KVCacheLayout.LBHNC, True), (KVCacheLayout.BLHNC, True)],
)
def test_allocator_views_and_aliases_keep_their_values(
    make_connector, physical_layout, padded
):
    """Registration describes indexing order while preserving real strides."""
    spec = FullAttentionSpec(
        block_size=4,
        num_kv_heads=2,
        head_size=2,
        dtype=torch.float32,
        page_size_padded=144 if padded else None,
    )
    nb, nl = 2, 2
    strides = compute_layout_strides(spec, nb, nl, physical_layout)
    config = KVCacheConfig(
        num_blocks=nb,
        kv_cache_tensors=[
            KVCacheTensor(
                size=nb * nl * spec.page_size_bytes,
                layers=["first", "second"],
                layer_stride=strides[0],
                block_stride=strides[1],
            )
        ],
        kv_cache_groups=[
            KVCacheGroupSpec(
                ["first", "second"],
                UniformTypeKVCacheSpecs(
                    block_size=4, kv_cache_specs={"first": spec, "second": spec}
                ),
            )
        ],
    )
    layouts: dict[str, KVCacheTensorLayout] = {}
    caches = allocate_kv_cache(
        config, torch.device("cpu"), physical_layout, tensor_layouts=layouts
    )
    caches["first"].copy_(torch.arange(64).reshape(2, 2, 4, 4))
    caches["second"].fill_(-1)
    add_kv_sharing_layers_to_kv_cache_groups({"alias": "first"}, config.kv_cache_groups)
    caches["alias"] = caches["first"]
    layouts["alias"] = layouts["first"]
    connector = make_connector(config)
    connector.register_kv_caches_with_layouts(caches, layouts)
    consumer = connector.sub_connectors[1]
    assert isinstance(consumer, AxisRegistrationConnector)
    assert consumer.registered_caches is caches
    assert set(consumer.layouts) == set(caches)
    assert consumer.layouts["alias"] == consumer.layouts["first"]
    layout = consumer.layouts["first"]
    index = tuple(
        {Axis.BLOCK: 1, Axis.HEAD: 0, Axis.STATE: 2, Axis.CONTENT: 3}[axis]
        for axis in layout.axes
    )
    assert consumer.registered_caches["alias"][index].item() == 43
    assert torch.all(caches["second"] == -1)
    assert caches["first"].stride(0) * caches["first"].element_size() == strides[1]

3. 描述符不合法时,要在旧注册函数产生副作用之前失败。

test_invalid_descriptor_is_rejected_before_legacy_registration 固定声明 (BLOCK,KV,SINGLETON,HEAD_DIM),分别传入三种错误:(3,2,1) 少一维;(3,3,1,4) 的 KV 大小不是 2;(3,2,2,4) 的结构 singleton 不是 1。

pytest.raises(ValueError, match=message) 同时检查异常类型和错误类别;之后检查所有 child 都没有 registered_caches 属性,证明本 fixture 中旧 hook 尚未执行。这里第一个 child 继承了基类校验,所以它先拒绝,再停止 MultiConnector 的循环。这个断言不能推广成“任意自定义 child 都有事务回滚”;绕过基类校验的 override 不在这个测试的保证范围内。

原始测试代码 · L179–L194

@pytest.mark.parametrize(
    ("shape", "message"),
    [((3, 2, 1), "rank"), ((3, 3, 1, 4), "KV axis"), ((3, 2, 2, 4), "SINGLETON")],
)
def test_invalid_descriptor_is_rejected_before_legacy_registration(
    make_connector, shape, message
):
    connector = make_connector(KVCacheConfig(3, [], []))
    layout = KVCacheTensorLayout((Axis.BLOCK, Axis.KV, Axis.SINGLETON, Axis.HEAD_DIM))
    with pytest.raises(ValueError, match=message):
        connector.register_kv_caches_with_layouts(
            {"layer": torch.empty(shape)}, {"layer": layout}
        )
    assert all(
        not hasattr(child, "registered_caches") for child in connector.sub_connectors
    )

4. 一个不存在的层名,不能凭空带着描述符混进注册。

test_unknown_layer_descriptor_is_rejected 使用空 tensor 字典,却给出 missing 的轴声明。预期是带 unregistered layer 信息的 ValueError。这防止 tensor map 与 layout map 的 key 集合失配,比如模型重建后残留了上一次的层名。

它检查的是“描述符不能指向不存在的 tensor”,并不要求每个 tensor 都必须有描述符;后者恰恰由第 6 项测试允许缺省。

原始测试代码 · L197–L202

def test_unknown_layer_descriptor_is_rejected(make_connector):
    connector = make_connector(KVCacheConfig(2, [], []))
    with pytest.raises(ValueError, match="unregistered layer"):
        connector.register_kv_caches_with_layouts(
            {}, {"missing": KVCacheTensorLayout((Axis.BLOCK,))}
        )

5. 重复的语义轴在构造描述符时就拒绝。

test_rejects_duplicate_semantic_axes 直接构造 (BLOCK,BLOCK),在进入 connector 前就应抛出带 unique 的 ValueError。否则 axis_index(BLOCK) 只能返回第一个位置,消费者会悄悄忽略另一个“BLOCK”。

这项只覆盖重复 BLOCK。实现允许重复的结构 SINGLETON;此用例没有验证该合法场景,也没有覆盖全部轴组合。不能把一个重复轴反例说成完整的 schema 属性测试。

原始测试代码 · L205–L207

def test_rejects_duplicate_semantic_axes():
    with pytest.raises(ValueError, match="unique"):
        KVCacheTensorLayout((Axis.BLOCK, Axis.BLOCK))

6. 没有声明就是 unspecified,不能自动补一个“看起来合理”的布局。

test_missing_descriptors_stay_unspecified 建立一个带 HiSparse raw spec、但 kv_cache_tensors=[] 的配置。allocator 因为没有 allocation record 而返回空字典,输出 layouts 也保持为空。随后测试手动注册 raw 与 custom 两个 tensor,仍然传空描述符。

消费者必须拿到原 tensor 字典和空 layouts,不能根据 rank、层名或 spec 自动猜 BHNC。要注意这个用例本身没有真正分配 HiSparse raw storage:它验证空分配输出和“外部提供 tensor 可以无声明注册”。下一项 hybrid 测试才实际走到 raw-storage 分支,并检查 raw 没有被生成描述符。

原始测试代码 · L210–L232

def test_missing_descriptors_stay_unspecified(make_connector):
    config = KVCacheConfig(
        num_blocks=2,
        kv_cache_tensors=[],
        kv_cache_groups=[
            KVCacheGroupSpec(["raw"], HiSparseResidentSpec(block_size=4, page_size=128))
        ],
    )
    caches = {"raw": torch.empty(256, dtype=torch.uint8), "custom": torch.empty(2)}
    connector = make_connector(config)
    layouts: dict[str, KVCacheTensorLayout] = {}
    assert (
        allocate_kv_cache(
            config, torch.device("cpu"), KVCacheLayout.LBHNC, tensor_layouts=layouts
        )
        == {}
    )
    assert layouts == {}
    connector.register_kv_caches_with_layouts(caches, layouts)
    consumer = connector.sub_connectors[1]
    assert isinstance(consumer, AxisRegistrationConnector)
    assert consumer.registered_caches is caches
    assert consumer.layouts == {}

7. hybrid 不是一个全模型的 layout 字符串:要检查每个实际 view。

test_hybrid_allocator_registers_each_created_view 把 full attention、sliding attention、Mamba 和 HiSparse raw 四种 spec 放进同一配置。所有 KVCacheTensor 的 size 都是整块 backing storage 的总字节数,offset 则逐段推进;因此这些 view 共用 allocation,但访问不同区域。

层实际 shape测试中的含义
full(2,2,4,4)float32;2 heads、4 states,CONTENT=4。
sliding(2,1,2,4)float16;1 head、2 states,同一组轴角色不代表相同几何。
mamba(2,1,1,24)每块 24 字节的不透明状态:(2 + 2×2) × 4;HEAD/STATE 是大小为 1 的 slot。
raw一维 backing buffer没有 layer view,不应生成 tensor layout。

关键断言有三组:layouts 的 key 恰好是 full/sliding/mamba;三层的轴都为 (BLOCK,HEAD,STATE,CONTENT);逐层写入不同值后,注册消费者能读到各自的数据,并且三层的 untyped_storage().data_ptr() 都等于 raw 的 storage 地址。这同时约束了“每层声明”和“共用 backing”的关系。

代码只对 full/sliding 显式断言 dtype,对 Mamba 的 24 字节 shape 和值做检查;它没有把 Mamba 的两份 float32 状态解码回来,更没有证明 state 和 token 的推进比例。这些信息仍属于 spec 和实际执行逻辑。

原始测试代码 · L235–L298

def test_hybrid_allocator_registers_each_created_view(make_connector):
    """Hybrid specs share axis roles, not shapes, dtype or content encoding."""
    specs = {
        "full": FullAttentionSpec(
            block_size=4, num_kv_heads=2, head_size=2, dtype=torch.float32
        ),
        "sliding": SlidingWindowSpec(
            block_size=2,
            num_kv_heads=1,
            head_size=2,
            dtype=torch.float16,
            sliding_window=8,
        ),
        "mamba": MambaSpec(
            block_size=4,
            shapes=((2,), (2, 2)),
            dtypes=(torch.float32, torch.float32),
        ),
        "raw": HiSparseResidentSpec(block_size=4, page_size=64),
    }
    num_blocks = 2
    size = sum(num_blocks * spec.page_size_bytes for spec in specs.values())
    tensors = []
    offset = 0
    for name, spec in specs.items():
        tensors.append(
            KVCacheTensor(
                size=size,
                layers=[name],
                offset=offset,
                layer_stride=num_blocks * spec.page_size_bytes,
                block_stride=spec.page_size_bytes,
            )
        )
        offset += num_blocks * spec.page_size_bytes
    config = KVCacheConfig(
        num_blocks,
        tensors,
        [KVCacheGroupSpec([name], spec) for name, spec in specs.items()],
    )
    layouts: dict[str, KVCacheTensorLayout] = {}
    caches = allocate_kv_cache(
        config, torch.device("cpu"), KVCacheLayout.LBHNC, tensor_layouts=layouts
    )
    assert set(layouts) == {"full", "sliding", "mamba"}
    assert caches["full"].shape == (2, 2, 4, 4)
    assert caches["sliding"].shape == (2, 1, 2, 4)
    assert caches["mamba"].shape == (2, 1, 1, 24)
    assert caches["raw"].ndim == 1
    assert caches["full"].dtype == torch.float32
    assert caches["sliding"].dtype == torch.float16
    for value, name in enumerate(layouts, start=1):
        caches[name].fill_(value)
    connector = make_connector(config)
    connector.register_kv_caches_with_layouts(caches, layouts)
    consumer = connector.sub_connectors[1]
    assert isinstance(consumer, AxisRegistrationConnector)
    for value, name in enumerate(layouts, start=1):
        axes = consumer.layouts[name]
        assert axes.axes == (Axis.BLOCK, Axis.HEAD, Axis.STATE, Axis.CONTENT)
        assert torch.all(consumer.registered_caches[name] == value)
        assert consumer.registered_caches[name].untyped_storage().data_ptr() == (
            caches["raw"].untyped_storage().data_ptr()
        )
这份测试证明到哪一步? CPU 上的真实 allocator → view metadata → MultiConnector → 测试消费者,以及错误路径。它没有运行 MRV1/MRV2 的完整 initialize_kv_cache、HiSparse host/device 绑定、attention kernel、模型 serving 或 LMCache IPC。原始 RBLN 用例也不是 rebel SDK 测试。7 个函数经参数化得到 17 个 pytest 用例;offset 循环和逐层循环是同一个用例里的额外断言,不应再加进用例数。

怎样单独复现这一份测试?

在本文前一节列出的 vLLM CPU 开发环境中,切换到固定提交 383874621325a7057190711527ad268c183e0b19,使用 Python 3.12、PyTorch 2.14.1、pytest 与 tblib,确保已装好 vLLM 测试依赖。2026-10-27 针对该文件重新执行:17 passed;唯一警告是源码环境缺少生成的 vllm._version。没有下载模型权重,也没有运行 GPU 推理。

VLLM_TARGET_DEVICE=cpu HF_HUB_OFFLINE=1 python -m pytest \
  tests/v1/kv_connector/unit/test_kv_cache_registration.py -q -rs
# 17 passed
源码索引/固定代码版本,讨论链接保持实时

每个实现链接都固定到被审阅的源码版本。

本文 vLLM 链接固定到 383874621325a7057190711527ad268c183e0b19;RBLN 链接固定到 a930b4daaf19ea083f3f7d8f80ed3fa82cc7a27d。PR 和 issue 链接仍指向实时讨论。实现更新后应检查新的 diff,不能把本文快照当成永远最新。

Reviewer 要记住的重点: 这个改动让已知的轴语义跨过现有的所有权边界。它提供兼容的生产者 API;要完整理解布局,仍需结合描述符、张量几何、spec,以及真正保留并使用这些信息的消费者。
在 OpenAI Codex 协助下编写 · 2026-10-26 · 基于固定源码的工程讲解,不是性能测试或硬件验证报告。
图表为原理示意;中文和英文版本通过博客顶部的按钮切换。
Discussion

评论与点赞

当前文章的评论线程还没有初始化。