[Feature] Overlap Spec Support

[hnyls2002]

Motivation

We have already implemented the initial support for eagle speculative decoding with the overlap scheduler, and here is the roadmap for more feature optimizations and support. The initial skeleton code is this PR #11398

The design illustration is here

Note

The arg --enable-beta-spec has been deprecated, please use export SGLANG_ENABLE_SPEC_V2=1 to enable this feature.

---

page size & topk support

• Support page size > 1 @cicirori @hnyls2002 [overlap-spec] support page size > 1 #11772
• Support topk > 1 @vincentzed [eagle overlap spec] wip impl top k > 1 in overlap eagle worker(v2) #11839
• Support topk > 1 + page size > 1 @vincentzed

memory allocation

• over-allocation optimization @hnyls2002
• over-allocation with page size > 1 + topk > 1

Attention backend support

• Remove or make verify_done.synchronize() an option @hnyls2002
• Different attention backend support @Fridge003 @Qiaolin-Yu
  • Support overlap-spec-v2 with trtllm_mla attention backend #11821
  • fa3 & trtllm_mha spec overlap #11874

sampling

• [Feature] Fully Overlap with spec v2 + Constrained Decoding #13019
• penalty support
• logprob support

speculative methods

• new speculative model worker interface (Abstraction for spec worker and code cleanup #11643)
• standalone speculative support @Qiaolin-Yu
• ngram speculative support @a4zhangfei
• Top SpecTpWorker for all speculative decoding backends @hnyls2002
• Make SpecTpWorker compatible with all TpModelWorker features.
• specialize for high throughput case (num_step=1, topk=1, num_verify_forward_pass_tokens=2) @yukavio

DP attention support

• Support idle batch @iforgetmyname
  • [Feature] Spec-Overlap supporting DP-ATTN; PD-Disaggregation; npugraph mode #12443
• cover testcases with dp-attention + overlap + spec @iforgetmyname

EP support

• Check compatibility with DeepEP / EP @fzyzcjy
• Cover testcases with EP + overlap + spec @fzyzcjy

PD disaggregation

• Event loop adjust in Prefill / Decode worker @shaharmor98
• Cover testcases with PD-Disagg + overlap + spec @ShangmingCai

LoRA Support

• @lifuhuang
• Support spec decoding when LoRA is applied to target model  #12903

Aggressive Optimizations

• Enable a separate `plan_stream

Related resources

No response

[vincentzed]

I impl Support topk > 1 + page size > 1

[hnyls2002]

@vincentzed Great, added you to the roadmap. Please try to implement the topk > 1 first, which is much easier than topk > 1 + page size > 1. Also, for the current main branch without overlap, our implementation of topk > 1 + page size > 1 is wrong; you can look at this PR (which may still be wrong, but can give you some hints) about the issue.

[lixuwei2333]

Is there a design document for the overlap spec? The code changes are quite significant and it appears to be fairly complex. #11398

[hnyls2002]

@lixuwei2333 Yes, see the design doc in our #spec-decoding channel in Slack.

[Zhiy-Zhang]

@hnyls2002 I'd like to know whether this feature also provides acceleration for Eagle3.

[hnyls2002]

@Zhiy-Zhang, Yes, this should bring acceleration to all kinds of speculative decoding.

[keyboardAnt]

In addition to minimizing host overheads, we can hide verifications using distributed speculative decoding. One possible way to implement it requires a worker pool (imagine a k8s-like service) that computes target forwards and runs verification.