[Spec Decode] Support sample_from_anchor for DFlash draft models

[qianlihuang]

Purpose

Support DFlash/DFlash2 checkpoints with sample_from_anchor=True on the V2 GPU model runner.

With anchor sampling, K draft tokens use K query positions instead of the default K + 1. This PR applies that query geometry consistently to scheduler slots, KV lookahead, DFlash2 convolution block size, and the DFlash speculator.

This complements vllm-project/speculators#1006, which added DFlash2 training and checkpoint support.

Test Plan

pytest -q tests/v1/spec_decode/test_dflash2.py
pytest -q tests/v1/spec_decode/test_dflash_prepare_inputs.py

Also run end-to-end generation for both layouts:

sample_from_anchor=False: 8 queries -> 7 draft tokens
sample_from_anchor=True:  7 queries -> 7 draft tokens

Test Result

pytest -q tests/v1/spec_decode/test_dflash2.py
# 7 passed

pytest -q tests/v1/spec_decode/test_dflash_prepare_inputs.py
# 3 passed

End-to-end on NVIDIA H200 with a patched stock vLLM nightly (0.26.1rc1.dev1261+gf25c580af):

CUDA_VISIBLE_DEVICES=0 vllm serve Qwen/Qwen3.8-27B \
  --speculative-config '{
    "method": "dflash",
    "model": "DaoCloud/Qwen3.8-27B-DFlash2-Exp",
    "num_speculative_tokens": 7
  }'

CUDA_VISIBLE_DEVICES=0 vllm serve Qwen/Qwen3.8-27B \
  --speculative-config '{
    "method": "dflash",
    "model": "z-lab/Qwen3.8-27B-DFlash2",
    "num_speculative_tokens": 7
  }'

---

Essential Elements of an Effective PR Description Checklist

• The purpose of the PR, such as "Fix some issue (link existing issues this PR will resolve)".
• The test plan, such as providing test command.
• The test results, such as pasting the results comparison before and after, or e2e results
• (Optional) The necessary documentation update, such as updating supported_models.md and examples for a new model.

[claude]

Claude Code Review

This pull request is from a fork — automated review is disabled. A repository maintainer can comment @claude review to run a one-time review.

[Copilot]

Pull request overview

This PR adds support for DFlash/DFlash2 draft checkpoints that set sample_from_anchor=True, ensuring the “K queries → K draft tokens” geometry is applied consistently across scheduling, KV lookahead sizing, the DFlash2 convolution block width, and the DFlash speculator’s per-request query sizing.

Changes:

• Introduces SpeculativeConfig.dflash_samples_from_anchor() and SpeculativeConfig.num_dflash_query_tokens to centralize the DFlash query-token geometry.
• Updates DFlash speculator and DFlash2 Qwen3 model code to consume num_dflash_query_tokens rather than assuming a fixed 1 + K layout.
• Adjusts KV lookahead sizing and adds an explicit V1-runner unsupported-feature gate for anchor-sampling DFlash checkpoints; extends unit tests to cover both query layouts for DFlash2 conv block sizing.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
vllm/v1/worker/gpu/spec_decode/dflash/speculator.py	Uses config-derived DFlash query count and enables anchor-sampling checkpoints (removes prior hard rejection).
vllm/model_executor/models/qwen3_dflash2.py	Sets DFlash2 grouped-conv block_size to match the checkpoint’s DFlash query layout.
vllm/config/vllm.py	Sizes DFlash lookahead by num_dflash_query_tokens and blocks anchor-sampling DFlash on the V1 runner.
vllm/config/speculative.py	Adds helpers/properties to detect anchor sampling and compute DFlash query token count; updates drafting-slot budgeting logic.
tests/v1/spec_decode/test_dflash2.py	Parametrizes coverage to assert DFlash2 conv block sizing matches both (bonus) and (anchor) layouts.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.