(#307) [v0.10] fix(vllm): require a fixed Python hash seed

Author: ArnavBalyan

docs/developer/kv_offload.rst

@@ -36,6 +36,13 @@ Before using OpenLake as a KV offload backend, ensure that you have:
 * A working OpenLake configuration.
 * RDMA-capable hardware if you plan to use cross-node KV offload.
 
+For the vLLM connector, set the same fixed ``PYTHONHASHSEED`` on every
+worker before starting Python, for example ``PYTHONHASHSEED=0 vllm serve
+<model> ...``. The connector accepts decimal integers from ``0`` through
+``4294967295``; unset, empty, ``random``, and invalid values fail startup.
+Changing this environment variable after Python has started does not
+change that process's hash seed.
+
 Model revisions in the vLLM cache
 --------------------------------
 

external/connectors/vllm/openlake_adapter.py

@@ -54,14 +54,20 @@
 EXPANS_MAX_BATCH_BLOCKS = 64
 
 _HASH_SEED_HELP = (
-    "OpenLake external KV offloading requires PYTHONHASHSEED to be set for "
-    "block-hash consistency. Please set it, e.g. "
+    "OpenLake external KV offloading requires PYTHONHASHSEED to be a fixed "
+    "decimal integer between 0 and 4294967295 for block-hash consistency. "
+    "Set the same value before starting every Python worker, e.g. "
     "PYTHONHASHSEED=0 vllm serve <model> ..."
 )
 
 
 def _require_fixed_hash_seed() -> None:
-    if os.getenv("PYTHONHASHSEED") is None:
+    seed = os.getenv("PYTHONHASHSEED", "")
+    try:
+        valid = seed.isascii() and seed.isdecimal() and int(seed) <= 4294967295
+    except ValueError:
+        valid = False
+    if not valid:
         raise RuntimeError(_HASH_SEED_HELP)
 
 

external/connectors/vllm/tests/test_openlake_adapter.py

@@ -21,7 +21,7 @@
 import unittest
 from pathlib import Path
 from types import SimpleNamespace
-from unittest.mock import Mock
+from unittest.mock import Mock, patch
 
 
 def _module(name: str) -> types.ModuleType:
@@ -167,6 +167,23 @@ def _parallel(**overrides):
     return SimpleNamespace(**values)
 
 
+class OpenLakeHashSeedTests(unittest.TestCase):
+    def test_requires_fixed_in_range_decimal_seed(self):
+        for seed in (None, "", "random", "abc", "-1", "4294967296", "1.5", "１２", "9" * 5000):
+            with self.subTest(seed=seed), patch.dict(os.environ):
+                if seed is None:
+                    os.environ.pop("PYTHONHASHSEED", None)
+                else:
+                    os.environ["PYTHONHASHSEED"] = seed
+                with self.assertRaisesRegex(RuntimeError, "before starting every Python worker"):
+                    ADAPTER._require_fixed_hash_seed()
+
+    def test_accepts_fixed_seed_including_range_boundaries(self):
+        for seed in ("0", "1", "42", "00042", "4294967295"):
+            with self.subTest(seed=seed), patch.dict(os.environ, PYTHONHASHSEED=seed):
+                ADAPTER._require_fixed_hash_seed()
+
+
 class OpenLakeRankNamespaceTests(unittest.TestCase):
     def test_compression_config_rejects_non_lossless_codecs(self):
         for field, codec, mode in (