diff --git a/docs/docs/advanced_features/server_arguments.mdx b/docs/docs/advanced_features/server_arguments.mdx index 550009fa96..e2082dc951 100644 --- a/docs/docs/advanced_features/server_arguments.mdx +++ b/docs/docs/advanced_features/server_arguments.mdx @@ -3057,7 +3057,7 @@ This option does not disable required attention or MoE collectives, including ex `--disaggregation-decode-enable-radix-cache` - Enable radix cache on decode server (PD mode). Caches KV prefixes to avoid redundant transfers. Incompatible with --enable-hisparse, speculative decoding, and --disaggregation-transfer-backend fake. + Enable radix cache on decode server (PD mode). Caches KV prefixes to avoid redundant transfers. Incompatible with --enable-hisparse, --disaggregation-transfer-backend fake, and speculative algorithms other than EAGLE, EAGLE3, and DSPARK. `False` bool flag (set to enable) diff --git a/python/sglang/srt/mem_cache/kv_cache_builder.py b/python/sglang/srt/mem_cache/kv_cache_builder.py index b8704c0ad1..d0a6902c56 100644 --- a/python/sglang/srt/mem_cache/kv_cache_builder.py +++ b/python/sglang/srt/mem_cache/kv_cache_builder.py @@ -245,6 +245,47 @@ def resolve_decode_retraction_backup(*, tp_worker: BaseTpWorker) -> str: return backend +def validate_decode_radix_cache( + *, + model_config: ModelConfig, + token_to_kv_pool: object, + is_hybrid_swa: bool, + enable_hierarchical_cache: bool, +) -> None: + """Reject decode-side radix cache on KV layouts its prefix reuse cannot serve. + + SWA models go through the unified tree, whose component pools preserve the + full-attention prefix while the SWA window is transferred fresh. Hybrid + SSM/KDA uses UnifiedRadixCache's Mamba component (match + lock + CoW), the + same path as colocated serving. + """ + if not is_hybrid_swa: + return + if enable_hierarchical_cache: + raise ValueError( + "--disaggregation-decode-enable-radix-cache with sliding " + "window attention (SWA) models currently supports only " + "device-resident cache and is incompatible with " + "--enable-hierarchical-cache." + ) + # DeepSeek-V4 qualifies only on the unified KV layout (bf16 or fp8 rows): its + # SWA ring and c128 state are request-scoped and always transferred whole, so + # the tree shares only the compressed full-attention pages. + if getattr(model_config, "is_deepseek_v4_arch", False) and not getattr( + token_to_kv_pool, "_unified_kv", False + ): + raise ValueError( + "--disaggregation-decode-enable-radix-cache with DeepSeek-V4 " + "requires the unified KV layout " + "(SGLANG_HACK_FLASHMLA_BACKEND=unified_kv_triton)." + ) + if getattr(model_config, "is_hybrid_swa_compress", False): + raise ValueError( + "--disaggregation-decode-enable-radix-cache does not support " + "SWA-compress models (e.g. Gemma4 / MiMo-V2) yet." + ) + + def build_kv_cache( *, server_args: ServerArgs, @@ -297,32 +338,16 @@ def build_kv_cache( "Transformers backend to avoid multimodal prefix-cache mismatches." ) - # Decode-side radix cache supports SWA only through the unified tree, whose - # component pools preserve the full-attention prefix while transferring the - # SWA window fresh. Hybrid SSM/KDA uses UnifiedRadixCache's Mamba - # component (match + lock + CoW), the same path as colocated serving. if ( get_disagg().disaggregation_decode_enable_radix_cache and get_disagg().disaggregation_mode == "decode" ): - if is_hybrid_swa: - if enable_hierarchical_cache: - raise ValueError( - "--disaggregation-decode-enable-radix-cache with sliding " - "window attention (SWA) models currently supports only " - "device-resident cache and is incompatible with " - "--enable-hierarchical-cache." - ) - if getattr(model_config, "is_deepseek_v4_arch", False): - raise ValueError( - "--disaggregation-decode-enable-radix-cache does not support " - "DeepSeek-V4 (DSA) compressed KV (c4/c128/indexer) yet." - ) - if getattr(model_config, "is_hybrid_swa_compress", False): - raise ValueError( - "--disaggregation-decode-enable-radix-cache does not support " - "SWA-compress models (e.g. Gemma4 / MiMo-V2) yet." - ) + validate_decode_radix_cache( + model_config=model_config, + token_to_kv_pool=token_to_kv_pool, + is_hybrid_swa=is_hybrid_swa, + enable_hierarchical_cache=enable_hierarchical_cache, + ) effective_chunked_prefill_size = get_schedule().chunked_prefill_size if model_config.is_multimodal and uses_transformers_backend: diff --git a/test/registered/unit/mem_cache/test_decode_radix_cache_validation.py b/test/registered/unit/mem_cache/test_decode_radix_cache_validation.py new file mode 100644 index 0000000000..d4fdf6309e --- /dev/null +++ b/test/registered/unit/mem_cache/test_decode_radix_cache_validation.py @@ -0,0 +1,42 @@ +"""Decode-side radix cache admits DeepSeek-V4 only on the unified KV layout. + +Both the bf16 and fp8 unified rows are admitted; the paged layout stays rejected. + + python -m pytest test/registered/unit/mem_cache/test_decode_radix_cache_validation.py -v +""" + +import unittest +from types import SimpleNamespace + +from sglang.srt.mem_cache.kv_cache_builder import validate_decode_radix_cache +from sglang.test.ci.ci_register import register_cpu_ci +from sglang.test.test_utils import CustomTestCase + +register_cpu_ci(est_time=1, suite="base-a-test-cpu") + +_DSV4 = SimpleNamespace(is_deepseek_v4_arch=True, is_hybrid_swa_compress=False) + + +def _validate(token_to_kv_pool): + validate_decode_radix_cache( + model_config=_DSV4, + token_to_kv_pool=token_to_kv_pool, + is_hybrid_swa=True, + enable_hierarchical_cache=False, + ) + + +class TestValidateDecodeRadixCacheDSV4(CustomTestCase): + def test_unified_kv_bf16_is_admitted(self): + _validate(SimpleNamespace(_unified_kv=True, _unified_kv_fp8=False)) + + def test_unified_kv_fp8_is_admitted(self): + _validate(SimpleNamespace(_unified_kv=True, _unified_kv_fp8=True)) + + def test_paged_layout_is_rejected(self): + with self.assertRaisesRegex(ValueError, "unified KV layout"): + _validate(SimpleNamespace(_unified_kv=False, _unified_kv_fp8=False)) + + +if __name__ == "__main__": + unittest.main()