[Bugfix] Correct KV cache tensor dimension handling in FlashInfer backend's block operations

[DearPlanet]

For now, swap_blocks and copy_blocks in Flashinfer backend directly reusing PagedAttention implements as follows:

@staticmethod
def swap_blocks(
    src_kv_cache: torch. Tensor,
    dst_kv_cache: torch. Tensor,
    src_to_dst: torch. Tensor,
) -> None:
    PagedAttention.swap_blocks(src_kv_cache, dst_kv_cache, src_to_dst)

@staticmethod
def copy_blocks(
    kv_caches: List[torch. Tensor],
    src_to_dists: torch. Tensor,
) -> None:
    PagedAttention.copy_blocks(kv_caches, src_to_dists)

However, there's a critical shape mismatch between the two impls. Flashinfer assumes the KV cache block shape is (num_blocks, 2, block_size, num_kv_heads, head_size), whereas PagedAttention uses (2, num_blocks, block_size * num_kv_heads * head_size). This discrepancy causes output errors when using swap_blocks and copy_blocks to move cache blocks.

For swap_blocks, we can simply reuse the existing ops.swap_blocks since it only considers the index of the first num_blocks dimension:

def swap_blocks(
    src_kv_cache: torch. Tensor,
    dst_kv_cache: torch. Tensor,
    src_to_dst: torch. Tensor,
) -> None:
    # PageAttention impl, seperating kv at first dim
    # copy k caches
    # src_key_cache = src_kv_cache[0]
    # dst_key_cache = dst_kv_cache[0]
    # ops.swap_blocks(src_key_cache, dst_key_cache, src_to_dst)

    # copy v caches
    # src_value_cache = src_kv_cache[1]
    # dst_value_cache = dst_kv_cache[1]
    # ops.swap_blocks(src_value_cache, dst_value_cache, src_to_dst)

    # The correct impl
    # Directly swap an entire KV Cache block, instead of splitting into K and V at the first dim
    ops.swap_blocks(src_kv_cache, dst_kv_cache, src_to_dst)

For copy_blocks, we need to split KV along the second dimension:

@staticmethod
def copy_blocks(
    kv_caches: List[torch. Tensor],
    src_to_dists: torch. Tensor,
) -> None:
    # PageAttention impl, seperating kv at first dim
    # key_caches = [kv_cache[0] for kv_cache in kv_caches]
    # value_caches = [kv_cache[1] for kv_cache in kv_caches]
    # ops.copy_blocks(key_caches, value_caches, src_to_dists)

    # The correct impl
    # K and V should be seperated at the second dim, not the first dim
    key_caches = [kv_cache[:, 0] for kv_cache in kv_caches]
    value_caches = [kv_cache[:, 1] for kv_cache in kv_caches]

After fixing this issue, features such as CPU offloading (e.g., unmerged #13377) will work properly with Flashinfer backend, and also ensures the correctness of any future functionality that relies on these interfaces.

[github-actions]

👋 Hi! Thank you for contributing to the vLLM project.

💬 Join our developer Slack at https://slack.vllm.ai to discuss your PR in #pr-reviews, coordinate on features in #feat- channels, or join special interest groups in #sig- channels.

Just a reminder: PRs would not trigger full CI run by default. Instead, it would only run fastcheck CI which starts running only a small and essential subset of CI tests to quickly catch errors. You can run other CI tests on top of those by going to your fastcheck build on Buildkite UI (linked in the PR checks section) and unblock them. If you do not have permission to unblock, ping simon-mo or khluu to add you in our Buildkite org.

Once the PR is approved and ready to go, your PR reviewer(s) can run CI to test the changes comprehensively before merging.

To run CI, PR reviewers can either: Add ready label to the PR or enable auto-merge.

🚀

[github-actions]

This pull request has been automatically marked as stale because it has not had any activity within 90 days. It will be automatically closed if no further activity occurs within 30 days. Leave a comment if you feel this pull request should remain open. Thank you!

[mergify]

This pull request has merge conflicts that must be resolved before it can be
merged. Please rebase the PR, @DearPlanet.

https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork

[github-actions]

This pull request has been automatically marked as stale because it has not had any activity within 90 days. It will be automatically closed if no further activity occurs within 30 days. Leave a comment if you feel this pull request should remain open. Thank you!