[Perf][Core] Skip the null head of sliding-window block tables (#61724)

Signed-off-by: Juntian Liu <Juntianl777@gmail.com>
Signed-off-by: Nick Hill <nickhill123@gmail.com>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

tests/v1/core/test_kv_cache_utils.py

@@ -52,6 +52,7 @@ from vllm.v1.core.kv_cache_utils import (
     hash_block_tokens,
     init_none_hash,
     make_block_hash_with_group_id,
+    null_head_len,
     tensor_data,
     to_event_extra_keys,
 )
@@ -2156,3 +2157,20 @@ def test_wrapped_mamba_group_requires_block_zeroing():
     )
 
     assert config.needs_kv_cache_zeroing
+
+
+def test_null_head_len():
+    null = KVCacheBlock(0, is_null=True)
+    real = [KVCacheBlock(i) for i in range(1, 4)]
+    tables = [
+        [],
+        real,
+        [null] * 5,
+        [null] * 5 + real,
+        [null] * 2 + real[:1] + [null] * 3 + real[1:],  # not one contiguous head
+    ]
+    for table in tables:
+        expected = next((i for i, b in enumerate(table) if not b.is_null), len(table))
+        assert null_head_len(table) == expected
+    blocks = KVCacheBlocks(([null] * 4 + real, [null] + real[:1] + [null]))
+    assert blocks.get_unhashed_block_ids_all_groups() == [[1, 2, 3], [1]]

tests/v1/core/test_single_type_kv_cache_manager.py

@@ -1012,3 +1012,35 @@ def test_predictor_matches_allocator_blocks_calculation_with_admission_cap():
             f"but allocator pulled {len(new_blocks)}"
         )
         total_computed = num_tokens
+
+
+def test_pop_blocks_for_free_trims_null_head():
+    block_size = 2
+    spec = SlidingWindowSpec(
+        block_size=block_size,
+        num_kv_heads=1,
+        head_size=1,
+        dtype=torch.float32,
+        sliding_window=4,
+    )
+    block_pool = BlockPool(
+        num_gpu_blocks=10, enable_caching=True, hash_block_size=block_size
+    )
+    manager = get_sliding_window_manager(spec, block_pool)
+    null = block_pool.null_block
+    real = block_pool.get_new_blocks(2)
+    manager.req_to_blocks["swa"] = [null] * 3 + real
+    manager.req_to_blocks["dense"] = dense = block_pool.get_new_blocks(2)
+
+    assert manager.pop_blocks_for_free("swa") == real
+    assert manager.pop_blocks_for_free("dense") is dense  # no null head, no copy
+    assert "swa" not in manager.req_to_blocks
+    assert all(b.ref_cnt == 1 for b in real + dense)
+
+    # The null block is never pooled, so touch / free_blocks leave it alone.
+    null_ref_cnt = null.ref_cnt
+    num_free_blocks = block_pool.get_num_free_blocks()
+    block_pool.touch([null])
+    block_pool.free_blocks([null])
+    assert null.ref_cnt == null_ref_cnt
+    assert block_pool.get_num_free_blocks() == num_free_blocks