[Core] Simplify snapshot resource policies

Assisted-by: AI coding assistant
Signed-off-by: Yunong He <ali_yuno@linux.alibaba.com>

Author: Yunong He

docs/features/sleep_mode.md

@@ -123,11 +123,17 @@ VLLM_SERVER_DEV_MODE=1 vllm serve Qwen/Qwen3-0.6B \
   --enable-engine-snapshot \
   --enable-sleep-mode \
   --engine-snapshot-provider=criu_cuda \
-  --engine-snapshot-resource-policy=l2_prepared \
+  --engine-snapshot-resource-policy=minimized \
   --engine-snapshot-dir=/snapshots \
   --port 8000
 ```
 
+Engine snapshots expose two resource policies. The default `full` policy keeps
+weights, KV cache, and runtime state in the CUDA process image. The `minimized`
+policy removes weights and KV cache before capture, then reloads the weights
+from the configured model files and recreates the KV cache after restore.
+Intermediate resource combinations are not user-configurable.
+
 Use `POST /sleep?level=3&mode=wait` to capture the EngineCore and
 `POST /wake_up` to restore it. `GET /snapshot/status` reports the checkpoint
 state. The snapshot directory contains process-image and model/runtime state;

tests/entrypoints/openai/test_cli_args.py

@@ -313,19 +313,15 @@ def test_engine_snapshot_resource_policy(serve_parser):
     assert args.engine_snapshot_resource_policy == "full"
 
     args = serve_parser.parse_args(
-        args=["--engine-snapshot-resource-policy", "discard_kv"]
+        args=["--engine-snapshot-resource-policy", "minimized"]
     )
-    assert args.engine_snapshot_resource_policy == "discard_kv"
+    assert args.engine_snapshot_resource_policy == "minimized"
 
-    args = serve_parser.parse_args(
-        args=["--engine-snapshot-resource-policy", "l2_prepared"]
-    )
-    assert args.engine_snapshot_resource_policy == "l2_prepared"
-
-    args = serve_parser.parse_args(
-        args=["--engine-snapshot-resource-policy", "l1_prepared"]
-    )
-    assert args.engine_snapshot_resource_policy == "l1_prepared"
+    for unsupported in ("discard_kv", "host_backup", "reload_weights"):
+        with pytest.raises(SystemExit):
+            serve_parser.parse_args(
+                args=["--engine-snapshot-resource-policy", unsupported]
+            )
 
     with pytest.raises(SystemExit):
         serve_parser.parse_args(

tests/snapshot/test_worker.py

@@ -15,7 +15,7 @@ def _checkpoint_worker(worker_class, backend="uni"):
     return worker
 
 
-def test_l2_prepared_worker_lifecycle_order(monkeypatch):
+def test_reload_weights_worker_lifecycle_order(monkeypatch):
     import vllm.v1.worker.gpu_worker as gpu_worker
     from vllm.v1.worker.gpu_worker import Worker
 
@@ -139,7 +139,7 @@ class UnsupportedExecutor(Executor):
     assert worker._checkpoint_prepare_state is None
 
 
-def test_l2_prepared_worker_rolls_back_failed_discard(monkeypatch):
+def test_reload_weights_worker_rolls_back_failed_discard(monkeypatch):
     import vllm.v1.worker.gpu_worker as gpu_worker
     from vllm.v1.worker.gpu_worker import Worker
 
@@ -194,7 +194,7 @@ def wake_up(self, tags):
     assert worker._checkpoint_prepare_state is not None
 
 
-def test_l2_prepared_worker_checks_discard_capability_before_side_effects(
+def test_reload_weights_worker_checks_discard_capability_before_side_effects(
     monkeypatch,
 ):
     import vllm.v1.worker.gpu_worker as gpu_worker
@@ -226,7 +226,7 @@ def unsupported_allocator():
     assert worker._checkpoint_prepare_state is None
 
 
-def test_l2_prepared_worker_rejects_active_lora():
+def test_reload_weights_worker_rejects_active_lora():
     from vllm.v1.worker.gpu_worker import Worker
 
     worker = object.__new__(Worker)
@@ -238,7 +238,7 @@ def test_l2_prepared_worker_rejects_active_lora():
         Worker._validate_checkpoint_weight_reload(worker)
 
 
-def test_l2_prepared_worker_rejects_online_weight_updates():
+def test_reload_weights_worker_rejects_online_weight_updates():
     from vllm.v1.worker.gpu_worker import Worker
 
     worker = object.__new__(Worker)
@@ -250,7 +250,7 @@ def test_l2_prepared_worker_rejects_online_weight_updates():
         Worker._validate_checkpoint_weight_reload(worker)
 
 
-def test_l1_prepared_worker_lifecycle_order(monkeypatch):
+def test_host_backup_worker_lifecycle_order(monkeypatch):
     import vllm.v1.worker.gpu_worker as gpu_worker
     from vllm.v1.worker.gpu_worker import Worker
 
@@ -308,7 +308,7 @@ def allocation_diagnostics(self):
     assert worker._checkpoint_prepare_state is None
 
 
-def test_l1_prepared_worker_rolls_back_failed_backup(monkeypatch):
+def test_host_backup_worker_rolls_back_failed_backup(monkeypatch):
     import vllm.v1.worker.gpu_worker as gpu_worker
     from vllm.v1.worker.gpu_worker import Worker
 

vllm/entrypoints/openai/cli_args.py

@@ -190,10 +190,8 @@ class BaseFrontendArgs:
     """Enable launcher-managed EngineCore snapshots for Sleep Mode level 3."""
     engine_snapshot_provider: Literal["fake", "criu_cuda"] = "criu_cuda"
     """Engine snapshot provider. The fake provider is for lifecycle testing."""
-    engine_snapshot_resource_policy: Literal[
-        "full", "discard_kv", "l1_prepared", "l2_prepared"
-    ] = "full"
-    """Internal Engine snapshot resource policy."""
+    engine_snapshot_resource_policy: Literal["full", "minimized"] = "full"
+    """Engine snapshot state captured in the process image."""
     engine_snapshot_persistence: Literal["durable", "page_cache"] = "durable"
     """Durability mode for Engine snapshot artifacts."""
     engine_snapshot_integrity: Literal["optimistic", "strict"] = "optimistic"

vllm/snapshot/resources.py

@@ -40,15 +40,19 @@ def to_wire(self) -> SnapshotResourcePolicyWire:
     "full": SnapshotResourcePolicy(
         weights="cuda_image", kv="cuda_image", runtime="cuda_image"
     ),
-    "discard_kv": SnapshotResourcePolicy(
+    "minimized": SnapshotResourcePolicy(
+        weights="discard", kv="discard", runtime="cuda_image"
+    ),
+}
+
+_SUPPORTED_RESOURCE_POLICIES = {
+    *_RESOURCE_POLICIES.values(),
+    SnapshotResourcePolicy(
         weights="cuda_image", kv="discard", runtime="cuda_image"
     ),
-    "l1_prepared": SnapshotResourcePolicy(
+    SnapshotResourcePolicy(
         weights="host_backup", kv="discard", runtime="cuda_image"
     ),
-    "l2_prepared": SnapshotResourcePolicy(
-        weights="discard", kv="discard", runtime="cuda_image"
-    ),
 }
 
 
@@ -73,6 +77,6 @@ def decode_snapshot_resource_policy(
         kv=cast(KVResourcePolicy, value["kv"]),
         runtime=cast(RuntimeResourcePolicy, value["runtime"]),
     )
-    if policy not in _RESOURCE_POLICIES.values():
+    if policy not in _SUPPORTED_RESOURCE_POLICIES:
         raise ValueError("unsupported snapshot resource policy")
     return policy

vllm/v1/worker/gpu_worker.py

@@ -298,20 +298,20 @@ def _validate_checkpoint_weight_reload(self) -> None:
 
         if self.get_draft_model() is not None:
             raise NotImplementedError(
-                "l2_prepared does not support speculative draft models"
+                "reload_weights does not support speculative draft models"
             )
         if self.vllm_config.lora_config is not None and self.list_loras():
             raise NotImplementedError(
-                "l2_prepared does not support active LoRA adapters"
+                "reload_weights does not support active LoRA adapters"
             )
         if self.weight_transfer_engine is not None:
             raise NotImplementedError(
-                "l2_prepared does not support online weight updates"
+                "reload_weights does not support online weight updates"
             )
         model_loader = get_model_loader(self.model_runner.load_config)
         if not hasattr(model_loader, "get_all_weights"):
             raise NotImplementedError(
-                "l2_prepared requires a model loader with get_all_weights"
+                "reload_weights requires a model loader with get_all_weights"
             )
 
     @staticmethod