Skip to content

feat: add configurable prefill queue scheduling - #1591

Open
hiworldwzj wants to merge 2 commits into
mainfrom
wzj_queue
Open

hiworldwzj wants to merge 2 commits into
mainfrom
wzj_queue

Conversation

@hiworldwzj

@hiworldwzj hiworldwzj commented Sep 23, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

This PR adds configurable prefill-queue scheduling before compute-token and KV-cache allocation, with three policies:

  • default: preserve the existing FCFS behavior while honoring internal inference priority.
  • promote_shortest: keep high-priority requests first, then promote the shortest normal prefill request without disturbing the relative order of the remaining requests.
  • hrrn: order normal prefill requests with token-based Highest Response Ratio Next (HRRN) aging.

It also separates router admission priority from inference-side scheduling priority, refines PD continuation handling, changes busy-node retry to opt-in, and adds documentation and focused tests.

Scheduling behavior

Decode requests are identified with the same rules used by request classification. They remain at the front of the queue in stable order and are not reordered by prefill policies.

Policy Behavior
default Stable sort by internal infer_high_priority; equal-priority requests remain FCFS.
promote_shortest Keep negative-priority requests first, then promote only the shortest normal prefill request while preserving every other request's relative order.
hrrn Keep negative-priority requests first, then order normal requests by token-based HRRN score.

The HRRN score is based on processed prefill work rather than wall-clock time:

score = waited_prefill_tokens / uncached_prefill_tokens
waited_prefill_tokens =
    processed_prefill_tokens - arrival_processed_prefill_tokens

Implementation details:

  • Each InferReq snapshots the backend's processed-prefill-token counter when it is constructed.
  • The uncached service cost is bound lazily when the request first participates in HRRN ordering, using max(1, input_len - cur_kv_len).
  • That service cost remains fixed across later chunked-prefill rounds, matching the intended HRRN model rather than shrinking dynamically as the request progresses.
  • Request ID is used as a deterministic tie-breaker across TP ranks.
  • The processed-token counter advances only when a selected prefill batch is submitted for execution.
  • Accounting reuses the token count already computed during resource selection, avoiding an extra pass and duplicate prefill_need_token_num calls.
  • Mixed prefill/decode batches include all tokens submitted in the selected prefill run mode.

PD priority and retry behavior

  • high_priority_request remains the router/shared-memory admission-priority flag.
  • infer_high_priority is an internal inference-side field; external requests cannot set it.
  • Only PD continuation segments (segment_index > 0) receive elevated inference priority. The first segment is not promoted merely because it has a cache hit.
  • LIGHTLLM_PD_NODE_BUSY_RETRY_TIMEOUT_SECONDS now defaults to 0, so busy-node retries are disabled unless a positive timeout is configured explicitly.

Motivation and expected impact

  • promote_shortest is intended primarily for PD-disaggregated Prefill nodes. It can improve time to first token for short prompts with a deliberately limited queue reorder.
  • hrrn favors requests with small uncached service cost while token-based aging allows long-waiting requests to overtake newly arrived short work, reducing starvation risk.
  • Token-based aging avoids wall-clock skew across TP ranks and does not require a configured throughput estimate.

Documentation

  • Add a dedicated Chinese guide covering policy semantics, examples, rollout guidance, and extension points.
  • Update the Chinese and English server-argument references.
  • Credit the original HRRN design and implementation inspiration from SGLang PR #32911.

Validation

Completed locally:

  • black
  • flake8
  • Python bytecode compilation with py_compile
  • git diff --check
  • Focused prefill-strategy test bodies, including:
    • empty and singleton queues
    • stable decode-first ordering
    • internal inference priority vs. router priority
    • shortest-request promotion and stable ties
    • HRRN short-job preference and token aging
    • lazy, fixed service-cost binding
    • deterministic request-ID tie-breaking
    • CLI strategy selection and invalid-policy rejection
    • prefill compute-token accounting returned by request classification

The current development environment does not include pytest, so the relevant test functions were executed directly with a lightweight harness.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant