[Prefix Cache] Use LoRA name for consistent KV-cache block hashing

[sagiahrac]

Purpose

When loading a new LoRA adapter, vLLM assigns it a unique LoRA integer ID using an atomic counter (ref 1, ref 2).
This ID is then included in the KV-Cache block hash along with the block tokens and other keys.
However, since the LoRA integer ID depends on the registration order, the resulting hashes are inconsistent across runs or instances — making it impossible to deterministically identify or share KV-Cache blocks between different vLLM instances.

This PR replaces the integer ID with the LoRA name in the hash calculation, making KV-Cache hashing consistent across instances and allowing reliable cache lookups, routing, and sharing.

Test Plan

• Test LoRA name inclusion: Checks that when a LoRA request is active, the LoRA name (not ID) appears in the extra keys used for hashing.
• Verified that all existing LoRA and base-model inference tests still pass.

Test Result

All updated tests pass.

Profiling

Performance testing shows negligible overhead when using LoRA names instead of integer IDs for KV-cache block hashing.

• block size: 16
• num blocks: 3125
• total tokens per run: 3,125 × 16 = 50,000 tokens

=== System Information ===
Platform: macOS-15.6.1-arm64-arm-64bit
Processor: arm
Python version: 3.12.11
CPU count: 10
RAM: 64.0 GB
=========================


=== LoRA Key Type Profiling Summary ===
LoRA requests processed per run: 3,125
Profiling config: 1000 runs, 3125 requests/run, block_size=16
---------------------------------------
lora_string: mean=0.0010s, std=0.0000s
    Mean time per LoRA request: 0.00000031s
lora_int: mean=0.0010s, std=0.0000s
    Mean time per LoRA request: 0.00000031s
---------------------------------------
Comparison (relative performance):
    String names are 1.02x slower than int IDs
    Overhead: +0.0000s per 3,125 requests (+0.00000001s per request)
=======================================

code: https://gist.github.com/sagiahrac/dfa26f54f0514fbf8e1c7a99527cfb8b

[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 ask your reviewers to trigger select CI tests on top of fastcheck CI.

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.

If you have any questions, please reach out to us on Slack at https://slack.vllm.ai.

🚀

[gemini-code-assist]

Code Review

This pull request is a great improvement for ensuring deterministic KV-cache block hashing when using LoRA adapters. Replacing the non-deterministic integer ID with the LoRA name is a solid approach to enable reliable cache sharing across different vLLM instances. The added tests and performance profiling are appreciated and confirm the correctness and low overhead of the change.

I've added a couple of suggestions to make the implementation more robust by handling empty LoRA names, which could otherwise lead to cache collisions.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[zhuohan123]

Thanks for the contribution!