[Bugfix] Scale KV page size for hidden states extraction with TP (#50894)

Signed-off-by: Claude <noreply@anthropic.com>
Signed-off-by: Orestis Zambounis <orestis-z@users.noreply.github.com>
Signed-off-by: Orestis Zambounis <23146389+orestis-z@users.noreply.github.com>
Signed-off-by: Speculators Bot <bot@speculators.ai>
Signed-off-by: Speculators Bot <speculatorsbot@gmail.com>
Co-authored-by: Orestis Zambounis <orestis-z@users.noreply.github.com>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Co-authored-by: Benjamin Chislett <chislett.ben@gmail.com>
Co-authored-by: Speculators Bot <speculatorsbot@gmail.com>
Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com>
This commit is contained in:
Orestis Zambounis
2026-09-14 10:07:09 -04:00
committed by GitHub
co-authored by Orestis Zambounis Claude Opus 4.6 Benjamin Chislett Speculators Bot mergify[bot] <37929162+mergify[bot]@users.noreply.github.com>
parent c676e4930b
commit ff5f6d41b1
2 changed files with 73 additions and 0 deletions
+39
View File
@@ -3208,6 +3208,45 @@ def test_mla_with_incompatible_swa_uses_one_full_allocation_group(caplog_vllm):
assert "attention compute is unchanged" in caplog_vllm.text assert "attention compute is unchanged" in caplog_vllm.text
def test_hidden_states_with_tp_scales_page_size():
"""When TP shrinks KV pages below the hidden-state per-token cost,
get_kv_cache_groups must scale up target block sizes so that the
common page accommodates the unsharded hidden states."""
# Simulate TP=4 sharding a model with 8 KV heads → 2 per rank.
# KV page = block_size(16) * num_kv_heads(2) * head_size(64) * dtype(2)
# = 16 * 2 * 64 * 2 = 4096 bytes.
kv_spec = new_kv_cache_spec(
block_size=16,
num_kv_heads=2,
head_size=64,
dtype=torch.bfloat16,
)
# Hidden-state per-token cost = num_hidden_states(6) * hidden_size(512)
# * dtype(2) = 6144 bytes, which exceeds the 4096-byte KV page.
hs_spec = HiddenStateCacheSpec(
block_size=16,
num_kv_heads=6,
head_size=512,
dtype=torch.bfloat16,
)
specs = {
"target.0.attn": kv_spec,
"target.1.attn": kv_spec,
"cache_only_layers.48": hs_spec,
}
groups = get_kv_cache_groups(_grouping_config(), specs)
# The hidden-state layer should be present and no assertion should fire.
all_layers = {name for g in groups for name in g.layer_names}
assert "cache_only_layers.48" in all_layers
# The target group block sizes must have been scaled up.
for g in groups:
if "cache_only_layers.48" not in g.layer_names:
assert g.kv_cache_spec.block_size > kv_spec.block_size
def test_get_kv_cache_spec_kind_prefers_specific_attention_subclasses(): def test_get_kv_cache_spec_kind_prefers_specific_attention_subclasses():
assert get_kv_cache_spec_kind(new_mla_spec()) == KVCacheSpecKind.MLA_ATTENTION assert get_kv_cache_spec_kind(new_mla_spec()) == KVCacheSpecKind.MLA_ATTENTION
+34
View File
@@ -2217,6 +2217,38 @@ def _largest_divisor_at_most(value: int, limit: int) -> int:
return 1 return 1
def _ensure_min_page_size(
groups: list[KVCacheGroupSpec],
common_page: int,
hidden_specs: dict[str, HiddenStateCacheSpec],
) -> tuple[list[KVCacheGroupSpec], int]:
"""Scale up group block sizes so the common page is at least as large as
the biggest hidden-state per-token cost.
This protects the hidden state extraction feature, where we store hidden states in
the KV cache, and return them to clients using a custom hidden state connector.
Returns the (possibly scaled) groups and updated common page size.
"""
max_per_token = max(
spec.num_kv_heads * spec.head_size * get_dtype_size(spec.dtype)
for spec in hidden_specs.values()
)
if max_per_token <= common_page:
return groups, common_page
scale = cdiv(max_per_token, common_page)
common_page *= scale
scaled: list[KVCacheGroupSpec] = []
for g in groups:
s = g.kv_cache_spec
kw: dict[str, int] = {"block_size": s.block_size * scale}
if isinstance(s, (AttentionSpec, MambaSpec)) and s.page_size_padded is not None:
kw["page_size_padded"] = s.page_size_padded * scale
scaled.append(KVCacheGroupSpec(g.layer_names, replace(s, **kw)))
return scaled, common_page
def get_kv_cache_groups( def get_kv_cache_groups(
vllm_config: VllmConfig, vllm_config: VllmConfig,
kv_cache_spec: dict[str, KVCacheSpec], kv_cache_spec: dict[str, KVCacheSpec],
@@ -2288,6 +2320,8 @@ def get_kv_cache_groups(
# Add hidden-state layers back with page aligned to the common page. # Add hidden-state layers back with page aligned to the common page.
if hidden_specs: if hidden_specs:
common_page = get_uniform_page_size([g.kv_cache_spec for g in groups]) common_page = get_uniform_page_size([g.kv_cache_spec for g in groups])
# TP may shrink the common page below hidden-state per-token cost.
groups, common_page = _ensure_min_page_size(groups, common_page, hidden_specs)
group_block_size = math.gcd(*(g.kv_cache_spec.block_size for g in groups)) group_block_size = math.gcd(*(g.kv_cache_spec.block_size for g in groups))
for name, spec in hidden_specs.items(): for name, spec in hidden_specs.items():
per_token = spec.num_kv_heads * spec.head_size * get_dtype_size(spec.dtype) per_token = spec.num_kv_heads * spec.head_size * get_dtype_size(spec.dtype)