Promote prefix_cache_retention_interval to an argument and change the default to 0

tests/config/test_config_utils.py

@@ -216,6 +216,11 @@ def test_cache_config_hash_ignores_kv_cache_sizing_knobs():
     assert CacheConfig(gpu_memory_utilization=0.5).compute_hash() == base_hash
 
 
+def test_cache_config_hash_ignores_prefix_cache_retention_interval():
+    base_hash = CacheConfig().compute_hash()
+    assert CacheConfig(prefix_cache_retention_interval=64).compute_hash() == base_hash
+
+
 def test_envs_compile_factors_relocation_invariant(tmp_path):
     """Relocating HOME or the XDG roots must not change the compile-cache
     env hash.

tests/engine/test_arg_utils.py

@@ -476,6 +476,7 @@ def test_prefix_cache_default():
     # should be None by default (depends on model).
     engine_args = EngineArgs.from_cli_args(args=args)
     assert engine_args.enable_prefix_caching is None
+    assert engine_args.prefix_cache_retention_interval == 0
 
     # with flag to turn it on.
     args = parser.parse_args(["--enable-prefix-caching"])
@@ -487,6 +488,28 @@ def test_prefix_cache_default():
     engine_args = EngineArgs.from_cli_args(args=args)
     assert not engine_args.enable_prefix_caching
 
+    args = parser.parse_args(["--prefix-cache-retention-interval", "64"])
+    engine_args = EngineArgs.from_cli_args(args=args)
+    assert engine_args.prefix_cache_retention_interval == 64
+
+
+def test_prefix_cache_retention_interval_from_deprecated_env(
+    monkeypatch, caplog, disable_log_dedup
+):
+    monkeypatch.setenv("VLLM_PREFIX_CACHE_RETENTION_INTERVAL", "64")
+
+    engine_args = EngineArgs()
+
+    assert engine_args.prefix_cache_retention_interval == 64
+    assert "VLLM_PREFIX_CACHE_RETENTION_INTERVAL" in caplog.text
+    assert "deprecated" in caplog.text
+    assert "prefix_cache_retention_interval" in caplog.text
+
+    parser = EngineArgs.add_cli_args(FlexibleArgumentParser())
+    args = parser.parse_args(["--prefix-cache-retention-interval", "32"])
+    engine_args = EngineArgs.from_cli_args(args)
+    assert engine_args.prefix_cache_retention_interval == 32
+
 
 @pytest.mark.parametrize(
     ("arg", "expected", "option"),

tests/v1/core/test_contiguous_kv_packing.py

@@ -88,6 +88,7 @@ def _make_groups(n_c4, n_c128, n_swa):
 def _mock_vllm_config(kv_connector_extra_config: dict[str, str] | None = None):
     config = MagicMock()
     config.cache_config.num_gpu_blocks_override = None
+    config.cache_config.prefix_cache_retention_interval = 0
     config.kv_transfer_config = None
     if kv_connector_extra_config is not None:
         config.kv_transfer_config = MagicMock()
@@ -322,6 +323,7 @@ def test_hma_attention_groups_keep_default_backing(self):
         )
 
         assert config.num_blocks == 32
+        assert config.prefix_cache_retention_interval == 0
         assert sum(t.size for t in config.kv_cache_tensors) == page_size * 2 * 32
         assert config.kv_cache_tensors == [
             KVCacheTensor(size=page_size * 32, shared_by=["full.0", "sw.0", "sw.1"]),

tests/v1/core/test_kv_cache_utils.py

@@ -816,6 +816,7 @@ def test_metrics_empty_stats():
 def test_get_kv_cache_configs_multiple_workers():
     model_config = ModelConfig(max_model_len=16)
     vllm_config = VllmConfig(model_config=model_config)
+    vllm_config.cache_config.prefix_cache_retention_interval = None
 
     ref_kv_cache_spec = new_kv_cache_spec()
     same_kv_cache_specs = [
@@ -1173,6 +1174,7 @@ def test_get_kv_cache_configs_multiple_workers():
 def test_get_kv_cache_configs_pp_sharding(asymmetric_memory):
     model_config = ModelConfig(max_model_len=512)
     vllm_config = VllmConfig(model_config=model_config)
+    vllm_config.cache_config.prefix_cache_retention_interval = None
 
     ref_kv_cache_spec = new_kv_cache_spec()
     pp_kv_cache_specs = [
@@ -1702,6 +1704,7 @@ def test_get_kv_cache_config_one_worker():
     # pass max_model_len to pass check_enough_kv_cache_memory
     model_config = ModelConfig(max_model_len=16)
     vllm_config = VllmConfig(model_config=model_config)
+    vllm_config.cache_config.prefix_cache_retention_interval = None
 
     mem_per_block_per_layer = 16 * 2 * 64 * 4 * 2
     # all layers are full attention -> single group
@@ -2015,6 +2018,7 @@ def test_get_kv_cache_config_one_worker():
 def test_get_kv_cache_configs_attention_free():
     kv_cache_specs: dict[str, KVCacheSpec] = {}
     vllm_config = VllmConfig(model_config=ModelConfig(max_model_len=16))
+    vllm_config.cache_config.prefix_cache_retention_interval = None
     kv_cache_configs = get_kv_cache_configs(vllm_config, [kv_cache_specs], [0])
     assert kv_cache_configs == [
         KVCacheConfig(