[Scheduler] Honor explicit min-free-slots thresholds (#33403)

Co-authored-by: hnyls2002 <lsyincs@gmail.com>
Co-authored-by: Liangsheng Yin <hnyls2002@gmail.com>

python/sglang/srt/managers/min_free_slots_delayer.py

@@ -8,21 +8,18 @@ def resolve_min_free_slots(
 ) -> Optional[int]:
     """Resolve the min-free-slots threshold (None = disabled).
 
-    A user value (>1) is capped to the DFlash formula so the trigger never
-    delays more aggressively than the legacy heuristic. When unset, DFlash
-    workloads fall back to the formula (preserving the always-on behavior);
-    other workloads stay disabled. Also disabled when max_running_requests < 8.
+    An explicit user value always wins, capped by max_running_requests
+    (<= 1 disables). When unset, DFlash workloads fall back to the legacy
+    formula (preserving the always-on behavior, disabled when
+    max_running_requests < 8); other workloads stay disabled.
     """
     max_running_requests = max(0, int(max_running_requests))
-    formula = min(4, max(2, (max_running_requests + 5) // 6))
-    if user_value is None:
-        user_value = formula if is_dflash_family else None
-
-    if user_value is None or user_value <= 1:
-        return None
-    if max_running_requests < 8:
-        return None
-    return min(user_value, formula)
+    if user_value is not None:
+        threshold = min(user_value, max_running_requests)
+        return threshold if threshold > 1 else None
+    if is_dflash_family and max_running_requests >= 8:
+        return min(4, max(2, (max_running_requests + 5) // 6))
+    return None
 
 
 class MinFreeSlotsDelayer:

python/sglang/srt/server_args.py

@@ -3234,10 +3234,11 @@ class ServerArgs:
             "Hold new prefills until at least N running-request slots have freed "
             "up, so they are admitted in one batch instead of one at a time. "
             "Useful when each admission is disproportionately expensive, e.g. "
-            "speculative decoding with a separate draft prefill pass. Capped to "
-            "the DFlash formula (disabled when max-running-requests < 8; "
-            "min(4, max(2, (max-run + 5) // 6))). DFlash workloads auto-enable "
-            "this with the formula when unset; other workloads stay disabled."
+            "speculative decoding with a separate draft prefill pass. An "
+            "explicit value always wins, capped by max-running-requests "
+            "(1 disables). When unset, DFlash workloads auto-enable the "
+            "formula; other workloads stay disabled. Not supported with "
+            "pipeline parallelism."
         ),
         NS("schedule"),
     ] = None
@@ -8722,6 +8723,11 @@ class ServerArgs:
             assert (
                 self.disable_overlap_schedule and self.speculative_algorithm is None
             ), "Pipeline parallelism is not compatible with overlap schedule, speculative decoding"
+            assert self.min_free_slots_delay is None, (
+                "--min-free-slots-delay is not supported with pipeline "
+                "parallelism: allocatable slots per microbatch are bounded by "
+                "pp-max-micro-batch-size, so the threshold may never be reached"
+            )
 
         assert not (
             self.dp_size > 1 and self.nnodes != 1 and not self.enable_dp_attention