[Core] Make prefix-cache NONE_HASH deterministic by default (#51875)

Signed-off-by: Russell Bryant <rbryant@redhat.com>
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
Russell Bryant
2026-08-18 23:14:39 +00:00
committed by GitHub
co-authored by Claude Opus 4.8
parent 8f4a7f45c5
commit ef47a897e2
10 changed files with 204 additions and 77 deletions
+63 -5
View File
@@ -20,7 +20,7 @@ from vllm.multimodal.inputs import (
PlaceholderRange,
)
from vllm.sampling_params import SamplingParams
from vllm.utils.hashing import sha256, sha256_cbor
from vllm.utils.hashing import sha256, sha256_cbor, xxhash, xxhash_cbor
from vllm.utils.mem_constants import GiB_bytes
from vllm.v1.core.kv_cache_manager import KVCacheManager
from vllm.v1.core.kv_cache_utils import (
@@ -199,14 +199,20 @@ def new_mamba_spec(
def test_none_hash(monkeypatch, hash_fn):
import vllm.v1.core.kv_cache_utils
# case 1: PYTHONHASHSEED is not set, use random
# case 1: PYTHONHASHSEED is not set -> deterministic default seed so that
# independent processes compute identical block hashes for identical
# content (e.g. for KV cache reuse across nodes).
with monkeypatch.context() as m:
m.delenv("PYTHONHASHSEED", raising=False)
reloaded_kv_cache_utils = importlib.reload(vllm.v1.core.kv_cache_utils)
reloaded_kv_cache_utils.init_none_hash(hash_fn)
assert reloaded_kv_cache_utils.NONE_HASH is not None
assert isinstance(reloaded_kv_cache_utils.NONE_HASH, bytes)
assert reloaded_kv_cache_utils.NONE_HASH != b""
none_hash = reloaded_kv_cache_utils.NONE_HASH
assert isinstance(none_hash, bytes)
assert none_hash != b""
assert none_hash == hash_fn(reloaded_kv_cache_utils.DEFAULT_NONE_HASH_SEED)
# deterministic across re-initialization within the same environment
reloaded_kv_cache_utils.init_none_hash(hash_fn)
assert none_hash == reloaded_kv_cache_utils.NONE_HASH
# case 2: PYTHONHASHSEED is set, use the seed and hash_fn
with monkeypatch.context() as m:
@@ -218,6 +224,58 @@ def test_none_hash(monkeypatch, hash_fn):
assert hash_fn("python hash seed") == reloaded_kv_cache_utils.NONE_HASH
@pytest.mark.parametrize("non_crypto_fn", [xxhash, xxhash_cbor])
def test_none_hash_seed_random_for_non_crypto(monkeypatch, non_crypto_fn):
"""Non-cryptographic algorithms keep the per-process random seed.
A deterministic seed is safe for SHA-256, whose collision resistance does
not depend on a secret, but xxHash is not collision resistant: a known seed
would let an attacker precompute colliding blocks offline. Keep the
unpredictable seed there unless the operator opts into a shared one.
"""
# PYTHONHASHSEED unset -> unpredictable, differs per resolution.
with monkeypatch.context() as m:
m.delenv("PYTHONHASHSEED", raising=False)
seeds = {kv_cache_utils.resolve_none_hash_seed(non_crypto_fn) for _ in range(5)}
assert len(seeds) == 5
assert kv_cache_utils.DEFAULT_NONE_HASH_SEED not in seeds
# PYTHONHASHSEED set -> operator opt-in wins, so peers can share a cache.
with monkeypatch.context() as m:
m.setenv("PYTHONHASHSEED", "12345")
assert kv_cache_utils.resolve_none_hash_seed(non_crypto_fn) == "12345"
@pytest.mark.parametrize("hash_fn", [sha256, sha256_cbor])
def test_none_hash_seed_deterministic_for_crypto(monkeypatch, hash_fn):
with monkeypatch.context() as m:
m.delenv("PYTHONHASHSEED", raising=False)
seed = kv_cache_utils.resolve_none_hash_seed(hash_fn)
assert seed == kv_cache_utils.DEFAULT_NONE_HASH_SEED
assert seed == kv_cache_utils.resolve_none_hash_seed(hash_fn)
def test_get_none_hash_seed_reports_effective_seed(monkeypatch):
"""P2P advertises the seed NONE_HASH was actually derived from.
The P2P tier is constructed before init_none_hash runs, so it must read the
resolved seed lazily rather than re-deriving it.
"""
import vllm.v1.core.kv_cache_utils
with monkeypatch.context() as m:
m.delenv("PYTHONHASHSEED", raising=False)
reloaded = importlib.reload(vllm.v1.core.kv_cache_utils)
reloaded.init_none_hash(sha256)
assert reloaded.get_none_hash_seed() == reloaded.DEFAULT_NONE_HASH_SEED
with monkeypatch.context() as m:
m.setenv("PYTHONHASHSEED", "12345")
reloaded = importlib.reload(vllm.v1.core.kv_cache_utils)
reloaded.init_none_hash(sha256)
assert reloaded.get_none_hash_seed() == "12345"
def test_kv_cache_block():
# Test KVCacheBlock initialization
block = KVCacheBlock(block_id=0)
+35 -16
View File
@@ -15,6 +15,8 @@ from types import SimpleNamespace
import numpy as np
import pytest
from vllm.utils.hashing import sha256
from vllm.v1.core.kv_cache_utils import DEFAULT_NONE_HASH_SEED, init_none_hash
from vllm.v1.kv_offload.base import LookupResult, ReqContext, ScheduleEndContext
from vllm.v1.kv_offload.tiering.base import JobResult, TransferJob
from vllm.v1.kv_offload.tiering.p2p import manager as manager_module
@@ -123,23 +125,12 @@ def _init_offloading_spec() -> SimpleNamespace:
# ---------------------------------------------------------------------------
# Tests for __init__ PYTHONHASHSEED assertion
# Tests for __init__ hash seed resolution
# ---------------------------------------------------------------------------
class TestInitHashSeedAssertion:
def test_missing_pythonhashseed_raises(self, monkeypatch):
"""P2P instance refuses to start when PYTHONHASHSEED is unset."""
monkeypatch.delenv("PYTHONHASHSEED", raising=False)
with pytest.raises(ValueError, match="PYTHONHASHSEED"):
P2PSecondaryTierManager(
offloading_spec=_init_offloading_spec(),
primary_kv_view=memoryview(bytearray(16)),
)
def test_pythonhashseed_set_succeeds(self, monkeypatch):
"""With PYTHONHASHSEED set, __init__ records it for the handshake."""
monkeypatch.setenv("PYTHONHASHSEED", "12345")
class TestInitHashSeed:
def _build(self, monkeypatch) -> P2PSecondaryTierManager:
monkeypatch.setattr(manager_module, "NixlTransport", lambda *a, **k: object())
monkeypatch.setattr(manager_module, "ZmqTransport", lambda *a, **k: object())
monkeypatch.setattr(
@@ -147,11 +138,39 @@ class TestInitHashSeedAssertion:
"from_offloading_spec",
lambda **k: SimpleNamespace(get_run_config=lambda: {}),
)
mgr = P2PSecondaryTierManager(
return P2PSecondaryTierManager(
offloading_spec=_init_offloading_spec(),
primary_kv_view=memoryview(bytearray(16)),
)
assert mgr._hash_seed == "12345"
def test_missing_pythonhashseed_uses_default(self, monkeypatch):
"""P2P falls back to the deterministic default seed when unset."""
monkeypatch.delenv("PYTHONHASHSEED", raising=False)
mgr = self._build(monkeypatch)
init_none_hash(sha256)
assert mgr._get_hash_seed() == DEFAULT_NONE_HASH_SEED
def test_pythonhashseed_set_succeeds(self, monkeypatch):
"""With PYTHONHASHSEED set, the handshake advertises it."""
monkeypatch.setenv("PYTHONHASHSEED", "12345")
mgr = self._build(monkeypatch)
init_none_hash(sha256)
assert mgr._get_hash_seed() == "12345"
def test_seed_resolved_after_init_none_hash(self, monkeypatch):
"""The seed is read lazily, not at construction time.
This tier is built before init_none_hash runs, and a non-cryptographic
hash algorithm seeds NONE_HASH randomly, so resolving in __init__ would
advertise a value that does not match the NONE_HASH actually in use.
"""
monkeypatch.delenv("PYTHONHASHSEED", raising=False)
mgr = self._build(monkeypatch)
assert mgr._hash_seed is None
monkeypatch.setattr(
manager_module, "get_none_hash_seed", lambda: "random-seed-abc"
)
assert mgr._get_hash_seed() == "random-seed-abc"
# ---------------------------------------------------------------------------