KV Layout 不该靠猜:从 vLLM #63699 到 RBLN 与 LMCache 的显式轴契约
用 17 张图和两个交互示例,讲清 KV cache 的轴语义、物理布局、内容编码,追踪 allocator 到 connector 的完整调用链,以及 RBLN、MLA、hybrid 模型和 LMCache 接入的边界。
用 17 张图和两个交互示例,讲清 KV cache 的轴语义、物理布局、内容编码,追踪 allocator 到 connector 的完整调用链,以及 RBLN、MLA、hybrid 模型和 LMCache 接入的边界。
同样的 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 消费者的后续工作。
张量提供几何信息,却不会给维度贴上语义标签。新的注册 hook 把这些标签作为独立的类型化声明一起传出去。
tensors[name]layouts[name].axesKVCacheAxis, KVCacheTensorLayout、可选注册 hook、标准 view 的轴声明、runner 传递和 MultiConnector 转发。
实际张量的 shape、strides、dtype 和 storage offset。内容编码和 state 粒度仍由 cache spec 定义。
硬件插件接入、LMCache 消费、带版本的 MP 协议、任意组件角色,以及不兼容编码之间的转换。
RBLN 有两种合法 view:自定义 kernel 使用 [B,2,H,1,N,D];Triton 路径使用 [2,B,H,1,N,D]。当 B=2时,两者的 shape 和连续 strides 完全相同。探测器可以选一种解释,却无法恢复生产者的真实意图。
示例取 H=1、N=2、D=1,标量值等于物理偏移。颜色表示声明的组件角色,并非字节中自带的信息。
独立构造的标准输出先按组件,再按 block 和 state 排序。B=2 时,相同几何信息会得到不同的 K/V 序列。B=3 时这两种 shape 可区分,但任意 shape 仍不等于语义声明。
LMCache #5748 增加了两种 RBLN 格式的支持,修复了一项实际部署回归。即使这个探测修复已经存在,两个 block 时的歧义仍说明生产者契约很有价值。
KVCacheTensorLayout.axes 描述张量的索引顺序,由本 PR 新增。它不按 stride 给轴排序,也不解释 CONTENT 内部的内容。
shape + stride + dtype + storage_offset + storage。现有的 KVCacheLayout 选择 LBHNC、LBNHC 等物理排列。一个 block 不一定是一整段紧密连续的内存。
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。 |
公共 allocator 先创建逻辑形状为 [L,B,H,N,C] 的 view,再逐层选取得到 [B,H,N,C]。物理排列和 page padding 由 stride、offset 表达,不需要重命名对外索引的语义。
同一层、同一 block 内,head 排在 state 前。
cache[b,h,n,c]同一层、同一 block 内,state 排在 head 前。
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 的含义,不提供地址公式里的数值。
选择器调用 current_platform.get_attn_backend_cls(...)。按 cache kind 的配置可以让一个模型使用不同 backend。
综合各 backend 的兼容集合、worker 报告、混合 spec 与分片约束。显式环境变量必须合法;connector 偏好兼容时采用,否则选择优先候选。
标准 view 的角色始终是 BHNC;自定义 allocator 必须声明自己实际暴露的 view。
本 PR 没有通用的“device → 轴元组”表。硬件插件使用公共 allocator 时得到标准声明;自建 shape 的插件必须自己声明。本 PR 没有实现或验证 Ascend、MUSA 接入。
MRV2 = Model Runner V2,即第二版模型执行器。它属于 vLLM V1 引擎;第 07 节会解释执行器选择,以及 HiSparse 为什么是 MRV2 内部的缓存路径。
tensor_layouts = {} 是输出容器。下面的调用接收同一个字典对象,view 创建函数原地填写它。这不是传给 backend 的“空布局请求”。
这是对真实调用链的示意,并非某次模型运行的 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)
KVCacheConfig重建标准轴声明。当前 PR 删除了那个 helper,把 metadata 的来源移到实际索引契约建立的地方。源码: initialize_kv_cacheinit_kv_cacheallocate_kv_cacheView 创建与填写ActiveKVConnector
MRV1 是 Model Runner V1,即第一版模型执行器;MRV2 是 Model Runner V2,即第二版模型执行器。它们都可以运行在 vLLM V1 引擎中。路径里的 v1 指引擎代际,不是 Model Runner 的版本。
| 执行器 | 实现位置 |
|---|---|
| MRV1 | vllm/v1/worker/gpu_model_runner.py |
| MRV2 | vllm/v1/worker/gpu/model_runner.py |
标准 worker 根据 VllmConfig.use_v2_model_runner 决定构造哪一版执行器。
第一版模型执行器。
initialize_kv_cache_tensors → 公共 allocator → 类型化 connector 注册。
第二版模型执行器。
hisparse_config is Noneinit_kv_cache → allocate_kv_cache
hisparse_config is not Noneinit_kv_cache → init_hisparse_kv_cache → allocate_hisparse_kv_caches
HiSparse 是 MRV2 内部的一条路径,不是与 MRV1、MRV2 并列的第三版执行器。公共 view 创建函数为 device/host view 生成轴声明;自管理的 raw storage 仍保持未指定。
下面按本文固定源码版本的优先级说明。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 是面向稀疏 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 副本。
直接配置 HiSparseConnector,或通过 MultiConnector 包含它时,会推导出默认 hisparse_config。Connector 提供 host_pool_gib 容量,HiSparseConfig 用来调节 GPU hot buffer 等字段。仍需一份完整且受支持的配置,显存不足本身不会自动开启 HiSparse。
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 接入不同。
本文审阅版本的源码: 执行器选择优先级MRV2 不支持的功能Worker 构造执行器HiSparse 配置HiSparse 兼容检查HiSparse 架构MRV2 分配分支HiSparse view 分配
图中示意跨层物理 packing。Hybrid group 还可以按 allocator 规划复用或覆盖 storage;不同层名不代表不同 buffer。
| 注册的 view,示意 | 轴角色 | 还需要解释的信息 |
|---|---|---|
Full attention [B,8,16,C₁] | BHNC | Dense K/V 的 packing 与 dtype。 |
Sliding attention [B,8,16,C₂] | BHNC | 该组的保留策略、block table 与 spec。 |
压缩 MLA [B,1,4,C₃] | BHNC | Latent 编码与每个 state 对应的 token 数。 |
循环状态/Mamba [B,1,1,C₄] | 标准 view 的轴角色为 BHNC | 状态组件、各组件 dtype 和 payload 组织。 |
| 自管理的 raw backing | 不提供 entry | 由其 owner 明确约定,不能假设默认轴语义。 |
Attention 绑定阶段可以在分配之后创建 kernel-block view。Connector 接收的是注册的 allocation view 及其匹配描述符,不是从 backend 私有 view 抄来的轴元组。单独一个 BLOCK 标签无法定义索引如何映射到 scheduler block,仍需要 spec 和 block mapping。
use_custom_kernel → 复用已有的 attention_block_axis(...) 来决定 B 插入的位置。[B,2,H,1,N,D]
[2,B,H,1,N,D]
校验 shape、保留共享别名,并在接口可用时调用 register_kv_caches_with_layouts 。旧版 vLLM connector 继续走只传张量的路径。
RBLN #1297 是下游适配,并非 #63699 的前置依赖。它会保持 draft,直到 upstream API 合并、进入 RBLN 支持的依赖版本并完成 SDK/运行验证。草稿没有修改当前依赖 pin。旧原型里的命名 TOKEN 已对齐为 STATE。
RBLN 源码版本 a930b4d: Backend 描述符Runner 传递
描述符里的 KV 角色表示可分别寻址的两个组件,先 K 后 V。MLA 的共享 latent 不应该被标成只有一个元素的 K/V 选择轴。 MLAAttentionSpec 设置 head_size_v=0;内容如何解释仍由 spec 决定。
[B,1,N,C]
Size 为 1 的维度代表 head slot,保留 HEAD 角色。
[B,N,C]
描述符不强制要求 head 轴或 K/V 轴。
[1,B,N,C]
真正的占位维才使用 SINGLETON;有语义的轴保留其角色。
[1,B,N,C] 描述为 (KV,BLOCK,STATE,CONTENT) 会抛出 ValueError。单个元素并未说明它是 K、V 还是共享 latent。放宽 size 检查只会引入歧义,不会因此编码出 MLA 的语义。validate_shape 检查 rank、KV 必须为 2、SINGLETON 必须为 1。构造描述符时还会拒绝除 SINGLETON 外重复的命名角色。这些检查不能证明声明真实:相同大小的轴仍可能标错。正确性首先依赖生产者已知的 view 契约。
register_kv_caches_with_layouts(caches, layouts)继承新增的 base hook。
检查提供的层名 key 和 shape。
self.register_kv_caches(caches)
旧 hook 收不到 layouts。
覆写新的 hook。
结合 spec/group 上下文,校验并解释声明。
保留支持的语义,供传输分派使用。
Metadata 被实际使用覆写新的 hook。
把张量和描述符映射转发给每个 child。
各 child 自己选择新/旧接口路径。
支持混合 child缺少 entry 表示 未指定语义,不是隐含默认值。Base hook 允许部分映射;要求完整显式语义的消费者必须拒绝缺失/不支持的项,或使用定义清楚的 spec-aware 旧路径。覆写 hook 的实现需要在消费前自行校验。
实际注册的张量、轴声明,以及对应的 spec/group 上下文。无论公共 allocator 还是自定义插件,描述符都必须跟随对外暴露的 view。
Runner → 类型化 hook → 可选 MultiConnector → child。引擎内部这段传递由 #63699 提供。
LMCache 后续工作:在 normalization 和 REGISTER_KV_CACHE 中继续传递语义;定义带版本的协议、显式组件角色,以及必需的编码/粒度上下文。Python IntEnum 数值本身不是 wire protocol。
后续:结合声明、spec 与几何信息,映射到支持的 EngineKVFormat/KVFormatSpec,以及 group/传输行为。显式 metadata 不一致或不受支持时应明确失败,不能改成另一个猜测。
后续:使用正确的地址几何与 kernel 传输;在恢复、重分配、跨进程交接时保留匹配的 metadata。对不兼容编码进行协商或拒绝,而非承诺任意转换。
青色表示本 PR 的生产者/API 工作;金色虚线表示 LMCache RFC #5866 中的消费者接入与更完整契约,尚未由 #63699 实现或验证。
生产者声明优先。消费者针对实际 view 做校验,保留结果,后续分派不必反复猜测轴角色。
当格式受支持且解释无歧义时,继续兼容旧引擎。真正有歧义时需要更多信息,单凭 device 名称选默认值不是证据。
生产者的新布局可能被判为不支持。LMCache #5748 对 RBLN block-first 的支持修复过一项具体集成回归。
大小相同的轴可以通过 shape 和越界检查。独立标准值测试展示了这种风险;本文没有声称已观察到生产模型输出错误。
生产者每次改 shape,都可能要求消费者新增启发式规则,即使生产者本来就知道语义。
并非所有只传张量的集成都不安全。现有 spec-aware 契约可以非常精确,很多布局也没有歧义。问题在于:几何信息或 backend 名称并不总能充当完整语义契约。
| 事件 | 张量变化 | 描述符/上下文应如何更新 |
|---|---|---|
| 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 上下文,并拒绝不支持的版本。 |
在以下版本运行的注册、MultiConnector、attention-utils 和 GPU-connector CPU 测试: 9be42ea。另有一个现有 GPU-only 测试跳过,一个 serving 测试明确未运行。
Packing、planning 和 allocation-scope 测试,版本为 9be42ea;缓存所需的 Qwen 配置后通过。
文档提交 3838746:三个合法 shape 均通过,KV size 为 1 会被拒绝。适用的 pre-commit 检查通过。
rebel,RBLN 定向测试无法完成收集;其 API 对齐改动通过了静态检查。使用 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这节逐项阅读 tests/v1/kv_connector/unit/test_kv_cache_registration.py,固定到 3838746。不是根据测试名猜意图:下面给出输入、执行链路、独立预期值和断言的实际覆盖范围。代码块保留原测试与参数化装饰器,可直接和固定版本源码对照。
| 测试 | 用例数 | 核心保护点 |
|---|---|---|
two_blocks… | 2 | K/V 数值与旧/新 child 兼容 |
allocator_views… | 8 | 六种物理布局、两种 padding、alias |
invalid_descriptor… | 3 | rank / KV / SINGLETON 校验及副作用 |
unknown_layer… | 1 | 拒绝多余的 descriptor key |
duplicate_semantic_axes | 1 | 拒绝重复 BLOCK |
missing_descriptors… | 1 | 保持 unspecified |
hybrid_allocator… | 1 | 逐 view 声明、混合几何、共享 backing |
TensorRegistrationConnector 只实现旧 register_kv_caches,记录收到的字典;它继承新 hook 的基类实现,所以能检验新接口是否继续调用旧 override。AxisRegistrationConnector 先调用 super 完成基类校验/旧 hook,再记录 layouts,模拟一个理解新契约的消费者。make_connector 用 CPU VllmConfig,通过模块路径和类名动态加载两个 child,角色为 WORKER;不是用 mock 替换注册链路,也不会启动模型 serving。
class TensorRegistrationConnector(ExampleConnector):
def register_kv_caches(self, kv_caches: dict[str, torch.Tensor]):
self.registered_caches = kv_cachesclass 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@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 maketest_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),再展开比值。
| 生产者声明 | 按 block 解释的原始数据 | 统一 K-first 输出 |
|---|---|---|
| BLOCK → KV | b0: K=[0,1], V=[2,3] b1: K=[4,5], V=[6,7] | K=[0,1,4,5] V=[2,3,6,7] |
| KV → BLOCK | K: 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 改变”。
@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]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 接线。
@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]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 不在这个测试的保证范围内。
@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
)test_unknown_layer_descriptor_is_rejected 使用空 tensor 字典,却给出 missing 的轴声明。预期是带 unregistered layer 信息的 ValueError。这防止 tensor map 与 layout map 的 key 集合失配,比如模型重建后残留了上一次的层名。
它检查的是“描述符不能指向不存在的 tensor”,并不要求每个 tensor 都必须有描述符;后者恰恰由第 6 项测试允许缺省。
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,))}
)test_rejects_duplicate_semantic_axes 直接构造 (BLOCK,BLOCK),在进入 connector 前就应抛出带 unique 的 ValueError。否则 axis_index(BLOCK) 只能返回第一个位置,消费者会悄悄忽略另一个“BLOCK”。
这项只覆盖重复 BLOCK。实现允许重复的结构 SINGLETON;此用例没有验证该合法场景,也没有覆盖全部轴组合。不能把一个重复轴反例说成完整的 schema 属性测试。
def test_rejects_duplicate_semantic_axes():
with pytest.raises(ValueError, match="unique"):
KVCacheTensorLayout((Axis.BLOCK, Axis.BLOCK))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 没有被生成描述符。
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 == {}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 和实际执行逻辑。
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()
)在本文前一节列出的 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,不能把本文快照当成永远最新。