[livingshade]

Motivation

KV events tell external routers which worker has which prefix blocks. For LoRA requests, the events do not identify the adapter:

• block_hashes do not include extra_key. Thus a block of a LoRA adapter has the same hash as a base-model block with the same tokens.
• No event gives the adapter name. lora_id is always None.

The goal of this PR is to support the Dynamo KV router (ai-dynamo/dynamo#15592), so that an external router can use the block hash as an index key and use the adapter name to match requests and hopefully leads to better prefix caching when LoRA being enabled.

Instead of adding Dynamo-specific fields to the SGLang format, this PR adds a dynamo format that follows the stable KV event API that Dynamo already defines (KV event wire format), and keeps the default format unchanged. This keeps the two projects decoupled and the boundary stable on both sides.

Example

--kv-events-config '{"publisher": "zmq", "endpoint": "tcp://*:5557", "format": "dynamo"}'

A base request and a request for adapter adapter-a both store tokens [1, 2, 3, 4] (page_size=2). The ZMQ payload is unchanged, [ts, events, dp_rank]:

[ts, [
  {"type": "BlockStored", "block_hashes": [E0, E1], "parent_block_hash": None,
   "token_ids": [1, 2, 3, 4], "block_size": 2, "lora_id": None, "medium": "GPU"},
  {"type": "BlockStored", "block_hashes": [N0, N1], "parent_block_hash": None,
   "token_ids": [1, 2, 3, 4], "block_size": 2, "lora_id": None, "medium": "GPU",
   "lora_name": "adapter-a"},
], 0]

E0 and E1 are the default block hashes. The default format sends them for both requests. Here the adapter blocks get Ni = namespaced_block_hash(Ei, seed), where the seed comes from the adapter's extra_key.

Modifications

• Add a format option to --kv-events-config: "default" or "dynamo", "default" by default. The default format is the same as before this PR, so deployments that do not set it are not affected. EventPublisherFactory.create drops the option before it builds the publisher.
• In the dynamo format, block_hashes, parent_block_hash and the hashes in BlockRemoved are namespaced hashes (below), so blocks of different adapters or adapter loads never share a hash.
• In the dynamo format, populate BlockStored.lora_name. Req adds lora_id to the end of extra_key, and the scheduler keeps LoRANameTable to map internal uuid to actual lora name.
• Both tree implementations have the change: the Python KVCacheEventRecorder and the Rust UnifiedTreeCore.

How namespaced hashes are calculated

• kv_event_namespace_seed(extra_key, cache_salt) is the SHA-256 of the tag sglang-kv-event-namespace-v1 and the two parts. Each part has a presence byte and a length prefix. The seed is None when both parts are None.
• namespaced_block_hash(block_hash, seed) is the first 8 bytes of SHA-256(seed, block_hash as 8 big-endian bytes), as a signed int64. When the seed is None, the result is block_hash. Thus a base-model block has the same hash in both formats.
• parent_block_hash uses the same function.

We do not reuse the HiCache storage hash (node.hash_value) for two reasons. First, decoupling: a change to the HiCache storage keys should not change the published hashes. Second, the algorithm is simpler: the HiCache hash is a chain over the page tokens, so a copy of it needs cached state on each node and must handle node splits. namespaced_block_hash only mixes the seed into each published block hash, so it needs no state.

Accuracy Tests

Not applicable. This PR does not change model outputs or kernels.

Speed Tests and Profiling

Not benchmarked. The default format adds no work except one dict insert per adapter load. In the dynamo format, overhead mostly comes from:

• LoRANameTable: one entry (id and name) per loaded adapter, kept for the server lifetime. Resolving lora_name is one cheap dict lookup.
• Namespaced hashes: each published block of a node with a namespace (extra_key or cache_salt) costs one SHA-256 over 40 bytes; nodes without a namespace keep block_hash and cost nothing. The namespaced hashes replace the original ones, so the event size does not change apart from lora_name.

Non-goals

Cache invalidation on LoRA unload/reload is out of scope for this PR. See ai-dynamo/dynamo#15746 for the routing implications in Dynamo case. This does not affect other consumers.

Validation

New unit tests in Python and Rust:

• In the dynamo format, base blocks and adapter blocks with the same tokens get different block hashes. Remove events have the same hashes as store events.
• After a node split, the parent link points to the correct page.
• Python and Rust give the same fixed namespaced_block_hash values.
• LoRANameTable finds the adapter name from the end of extra_key.

Ran the affected tests on one H200:

Test	Result
test/registered/rust/test_run_sglang_radix_tree_rust_tests.py (sglang-radix-tree cargo test)	passed
test/registered/unit/disaggregation/test_kv_events.py	18 passed
test/registered/unit/mem_cache/test_radix_cache_unit.py	41 passed
test/registered/unit/mem_cache/test_rust_tree_core_integration.py	443 passed

We will test this end to end on the Dynamo side.

Checklist

• Format your code according to the Format code with pre-commit.
• Add unit tests according to the Run and add unit tests.
• Update documentation according to Write documentations.
• Provide accuracy and speed benchmark results according to Test the accuracy and Benchmark the speed.
• Follow the SGLang code style guidance.

---

CI States

Latest PR Test (Base): ✅ Run #38126200463
Latest PR Test (Extra): ❌ Run #38126200175
Latest PR Test (AMD ROCm 10): ❌ Run #38126200419

[livingshade]

@ShangmingCai Please take a look.

[ShangmingCai]

LGTM

[ShangmingCai]

/tag-and-rerun-ci