Group cache-hit prefills into dense batches (SGLANG_CP_PREFILL_AFFINITY_GROUP)

专题 S4 (design: docs_internal/perf/prefill-compute-intensity-plan.md S4,
amended).  Under FCFS a cold request joining a warm-led batch turns a
1-2s cache-hit forward into a 5-10s one, splitting the warm work into
the 新-cache-新 pattern.  The policy prevents exactly that one thing:

- WARM candidates always admit (into a cold-led batch they are free
  density — the cold extend dominates the forward anyway).
- COLD admits into an empty or cold-led batch (small colds co-batch
  today; the FCFS head always starts a batch so the queue keeps moving).
- COLD into a WARM-led batch is skipped, bounded by a per-pass window
  (W=16 skips), a head defer count (K=3 passes) and an age bound
  (T=5s).  On any bound the scan STOPS instead of force-admitting: the
  cold waits for the same forward either way, but leads its own clean
  batch next pass instead of polluting this one.

The skip is strictly post-match / pre-admit (after init_next_round_input,
before add_one_req): no lock, no allocation, no budget mutation to
unwind, and re-matching a skipped candidate next pass is exactly what
the scan already does after a cap rejection.  Classification is the
in-scan match result (device prefix + host hit vs a 64-token floor) —
under FCFS+L2 no pre-scan signal exists, so this adds zero matching
work for inspected candidates.  Disabled wholesale under priority
scheduling (the skip must not reorder across priority classes).

Three amendments vs the design draft, reasoned in the decision-table
docstring: cold+cold-led admits (STOP would regress today's small-cold
co-batching); starved heads STOP rather than force-admit (clean batch
boundaries at identical latency); priority interaction handled by
disabling rather than per-request comparison.

Decision logic is a pure function with table + bounds unit tests
(28/28 adder suite green).  Default OFF.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

python/sglang/srt/environ.py

@@ -242,6 +242,23 @@ class Envs:
     # chunk still ends the scan by budget.  See
     # docs_internal/perf/prefill-compute-intensity-plan.md S1.
     SGLANG_CP_PREFILL_MIX_CHUNKED = EnvBool(False)
+    # Cache-affinity batch formation (plan doc S4): keep FCFS, but skip a
+    # COLD candidate while the batch is warm-led so cache-hit requests group
+    # into one dense forward instead of being split by a cold 60K chunk.
+    # Bounded by the window/defer/age knobs below; disabled automatically
+    # under priority scheduling.
+    SGLANG_CP_PREFILL_AFFINITY_GROUP = EnvBool(False)
+    # Max cold candidates skipped per batch-formation pass (scan depth bound;
+    # each skip costs one re-match next pass).
+    SGLANG_CP_PREFILL_AFFINITY_WINDOW = EnvInt(16)
+    # Max consecutive passes the FCFS head may be deferred before the scan
+    # stops grouping and lets it lead the next (empty) batch.
+    SGLANG_CP_PREFILL_AFFINITY_MAX_DEFER = EnvInt(3)
+    # Absolute age bound (seconds) with the same effect as MAX_DEFER; must be
+    # well under SGLANG_REQ_WAITING_TIMEOUT when that is set.
+    SGLANG_CP_PREFILL_AFFINITY_MAX_AGE_S = EnvFloat(5.0)
+    # Warm/cold threshold in tokens on (device prefix hit + host hit).
+    SGLANG_CP_PREFILL_AFFINITY_WARM_FLOOR = EnvInt(64)
     # NSA MQA logits are materialized as fp32 [q, k] buffers inside DeepGEMM.
     # Lower values split query rows more aggressively to cap peak temporary memory.
     SGLANG_NSA_MQA_LOGITS_FREE_MEM_FRACTION = EnvFloat(0.2)