Fix vLLM padded KV page allocation and strides

[shipiyouniao]

Summary

• propagate vLLM's page_size_padded into kvcached KV allocation and view construction
• use the padded physical page size for both block-capacity calculation and tensor block strides
• preserve the existing unpadded path and fail loudly when padding is combined with multiple kernel blocks per virtual page

Validation

• python3 -m pytest -q tests/test_vllm_padded_page_size.py tests/test_hybrid_contiguous_layout.py tests/test_alloc_kv_cache_alignment.py tests/test_vllm_nixl_compat.py (70 passed in a GPU-enabled Linux container)
• Ruff, codespell, isort, clang-format, PyMarkdown, actionlint, and trailing-whitespace hooks passed
• mypy passed for all changed Python files in Linux

Fixes #399

[Copilot]

Pull request overview

This PR aligns kvcached’s vLLM integration with vLLM’s page_size_padded behavior by propagating the padded physical page size into KV-cache capacity calculations and tensor view stride construction, preventing block-count/stride mismatches under vLLM 0.24+ indexes_kv_by_block_stride backends.

Changes:

• Thread page_size_padded from vLLM KVCacheSpec into kvcached allocation/view-building entrypoints.
• Compute physical page size / per-buffer block size via a shared _resolve_page_geometry() helper and use it in both alloc_kv_cache() and build_kv_views().
• Add regression tests covering padded-page stride behavior, block-count computation, and the “padded + multiple kernel blocks” loud failure mode.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

File	Description
tests/test_vllm_padded_page_size.py	Adds regression coverage for padded page size affecting strides and capacity calculations.
kvcached/integration/vllm/patches.py	Passes vLLM’s page_size_padded through to kvcached allocation and view construction.
kvcached/integration/vllm/interfaces.py	Implements padded-page-aware geometry/stride logic for allocations and strided views.

Suppressed comments (1)

kvcached/integration/vllm/interfaces.py:501

• Same ratio>1 stride issue as in build_kv_views: when kernel_block_size < block_size (ratio>1) and pages are unpadded, the KV tensor is shaped at kernel-block granularity, so the blocks dimension stride must be hidden_size_eles (kernel-block bytes) rather than block_mem_bytes (virtual-block bytes). Using block_mem_bytes here will mis-stride the attention views for ratio>1.

            physical_block_stride_eles = block_mem_bytes // dtype.itemsize

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.