feat: add request-level spec decode acceptance rate metric

Track speculative decoding acceptance at the finished-request level by carrying per-request draft and accepted token counts through EngineCoreOutput into IterationStats.

Expose vllm:spec_decode_request_acceptance_rate as a Prometheus histogram that observes each finished request's accepted/draft token ratio, while preserving the existing aggregate spec decoding counters.

Add tests for request-level acceptance-rate observation and per-request spec decode stat accumulation.

Author: jeffye-dev

tests/v1/metrics/test_spec_decode_request_acceptance_rate.py

@@ -0,0 +1,75 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM project
+
+from unittest.mock import MagicMock
+
+from vllm.config import SpeculativeConfig
+from vllm.v1.spec_decode.metrics import SpecDecodingProm
+
+
+class MockCounter:
+    def __init__(self, *args, **kwargs):
+        self.children = {}
+
+    def labels(self, *labelvalues):
+        child = MagicMock()
+        self.children[labelvalues] = child
+        return child
+
+
+class MockHistogram(MockCounter):
+    pass
+
+
+def _make_prom(spec_enabled: bool = True) -> SpecDecodingProm:
+    class MockSpecDecodingProm(SpecDecodingProm):
+        _counter_cls = MockCounter
+        _histogram_cls = MockHistogram
+
+    return MockSpecDecodingProm(
+        speculative_config=(
+            SpeculativeConfig(
+                method="ngram",
+                num_speculative_tokens=2,
+            )
+            if spec_enabled
+            else None
+        ),
+        labelnames=["model_name", "engine"],
+        per_engine_labelvalues={0: ["test-model", "0"]},
+    )
+
+
+def test_spec_decode_request_acceptance_rate_not_registered_without_spec_decode():
+    prom = _make_prom(spec_enabled=False)
+
+    prom.observe_finished_request(
+        num_draft_tokens=200,
+        num_accepted_tokens=10,
+    )
+
+    assert not hasattr(prom, "histogram_spec_decode_request_acceptance_rate")
+
+
+def test_spec_decode_request_acceptance_rate_observed_for_finished_request():
+    prom = _make_prom()
+
+    prom.observe_finished_request(
+        num_draft_tokens=200,
+        num_accepted_tokens=10,
+    )
+
+    prom.histogram_spec_decode_request_acceptance_rate[
+        0
+    ].observe.assert_called_once_with(0.05)
+
+
+def test_spec_decode_request_acceptance_rate_skips_request_without_draft_tokens():
+    prom = _make_prom()
+
+    prom.observe_finished_request(
+        num_draft_tokens=0,
+        num_accepted_tokens=0,
+    )
+
+    prom.histogram_spec_decode_request_acceptance_rate[0].observe.assert_not_called()

tests/v1/metrics/test_stats.py

@@ -1,6 +1,8 @@
 # SPDX-License-Identifier: Apache-2.0
 # SPDX-FileCopyrightText: Copyright contributors to the vLLM project
-from vllm.v1.engine import FinishReason
+from unittest.mock import MagicMock
+
+from vllm.v1.engine import EngineCoreOutput, FinishReason
 from vllm.v1.metrics.stats import (
     IterationStats,
     PrefillStats,
@@ -122,6 +124,49 @@ def test_prefill_kv_computed_edge_cases():
     assert finished_req2.request_id == "test-req-004"
 
 
+def test_finished_request_includes_spec_decode_stats():
+    iteration_stats = IterationStats()
+    req_stats = RequestStateStats(arrival_time=0.0)
+    req_stats.scheduled_ts = 0.1
+    req_stats.first_token_ts = 0.5
+    req_stats.last_token_ts = 1.0
+
+    for output in (
+        EngineCoreOutput(
+            request_id="test-req-005",
+            new_token_ids=[1, 2],
+            num_draft_tokens=4,
+            num_accepted_tokens=1,
+        ),
+        EngineCoreOutput(
+            request_id="test-req-005",
+            new_token_ids=[3, 4, 5],
+            num_draft_tokens=4,
+            num_accepted_tokens=2,
+        ),
+    ):
+        iteration_stats.update_from_output(
+            output=output,
+            engine_core_timestamp=2.0,
+            is_prefilling=False,
+            req_stats=req_stats,
+            lora_states=MagicMock(),
+            lora_name=None,
+        )
+
+    iteration_stats.update_from_finished_request(
+        finish_reason=FinishReason.STOP,
+        request_id="test-req-005",
+        num_prompt_tokens=2000,
+        max_tokens_param=300,
+        req_stats=req_stats,
+    )
+
+    finished_req = iteration_stats.finished_requests[0]
+    assert finished_req.num_draft_tokens == 8
+    assert finished_req.num_accepted_tokens == 3
+
+
 def test_prompt_token_stats_all_computed():
     """Test all tokens computed locally, no caching."""
     stats = PromptTokenStats()

vllm/v1/core/sched/scheduler.py

@@ -1414,26 +1414,33 @@ def update_from_output(
             scheduled_spec_token_ids = (
                 scheduler_output.scheduled_spec_decode_tokens.get(req_id)
             )
+            num_draft_tokens = 0
+            num_accepted_tokens = 0
+            num_invalid_spec_tokens = 0
             if scheduled_spec_token_ids and generated_token_ids:
                 num_draft_tokens = len(scheduled_spec_token_ids)
-                num_accepted = len(generated_token_ids) - 1
-                num_rejected = num_draft_tokens - num_accepted
+                num_accepted_tokens = len(generated_token_ids) - 1
+                num_rejected_tokens = num_draft_tokens - num_accepted_tokens
+                if scheduler_output.num_invalid_spec_tokens:
+                    num_invalid_spec_tokens = (
+                        scheduler_output.num_invalid_spec_tokens.get(req_id, 0)
+                    )
                 # num_computed_tokens represents the number of tokens
                 # processed in the current step, considering scheduled
                 # tokens and rejections. If some tokens are rejected,
                 # num_computed_tokens is decreased by the number of rejected
                 # tokens.
                 if request.num_computed_tokens > 0:
-                    request.num_computed_tokens -= num_rejected
+                    request.num_computed_tokens -= num_rejected_tokens
                 # If async scheduling, num_output_placeholders also includes
                 # the scheduled spec tokens count and so is similarly adjusted.
                 if request.num_output_placeholders > 0:
-                    request.num_output_placeholders -= num_rejected
+                    request.num_output_placeholders -= num_rejected_tokens
                 spec_decoding_stats = self.make_spec_decoding_stats(
                     spec_decoding_stats,
                     num_draft_tokens=num_draft_tokens,
-                    num_accepted_tokens=num_accepted,
-                    num_invalid_spec_tokens=scheduler_output.num_invalid_spec_tokens,
+                    num_accepted_tokens=num_accepted_tokens,
+                    num_invalid_spec_tokens=num_invalid_spec_tokens,
                     request_id=req_id,
                 )
 
@@ -1565,6 +1572,9 @@ def update_from_output(
                         trace_headers=request.trace_headers,
                         routed_experts=routed_experts,
                         num_nans_in_logits=request.num_nans_in_logits,
+                        num_draft_tokens=num_draft_tokens,
+                        num_accepted_tokens=num_accepted_tokens,
+                        num_invalid_spec_tokens=num_invalid_spec_tokens,
                     )
                 )
             else:
@@ -2063,15 +2073,14 @@ def make_spec_decoding_stats(
         spec_decoding_stats: SpecDecodingStats | None,
         num_draft_tokens: int,
         num_accepted_tokens: int,
-        num_invalid_spec_tokens: dict[str, int] | None,
+        num_invalid_spec_tokens: int,
         request_id: str,
     ) -> SpecDecodingStats | None:
         if not self.log_stats or not num_draft_tokens:
             return None
         if spec_decoding_stats is None:
             spec_decoding_stats = SpecDecodingStats.new(self.num_spec_tokens)
-        if num_invalid_spec_tokens:
-            num_draft_tokens -= num_invalid_spec_tokens.get(request_id, 0)
+        num_draft_tokens -= num_invalid_spec_tokens
         spec_decoding_stats.observe_draft(
             num_draft_tokens=num_draft_tokens, num_accepted_tokens=num_accepted_tokens
         )

vllm/v1/engine/__init__.py

@@ -194,6 +194,9 @@ class EngineCoreOutput(
     # The number of NaNs in logits.
     # A value greater than 0 indicates that the output is corrupted.
     num_nans_in_logits: int = 0
+    num_draft_tokens: int = 0
+    num_accepted_tokens: int = 0
+    num_invalid_spec_tokens: int = 0
 
     @property
     def finished(self) -> bool:

vllm/v1/metrics/loggers.py

@@ -1216,6 +1216,12 @@ def record(
                     finished_request.max_tokens_param
                 )
 
+            self.spec_decoding_prom.observe_finished_request(
+                num_draft_tokens=finished_request.num_draft_tokens,
+                num_accepted_tokens=finished_request.num_accepted_tokens,
+                engine_idx=engine_idx,
+            )
+
     def record_sleep_state(self, sleep: int = 0, level: int = 0):
         awake = 1
         discard_all = 0

vllm/v1/metrics/stats.py

@@ -218,6 +218,8 @@ class RequestStateStats:
 
     # Track if this request is corrupted (NaNs in logits)
     is_corrupted: bool = False
+    num_draft_tokens: int = 0
+    num_accepted_tokens: int = 0
 
 
 @dataclass
@@ -237,6 +239,8 @@ class FinishedRequestStats:
     mean_time_per_output_token: float = 0.0
     is_corrupted: bool = False
     num_cached_tokens: int = 0
+    num_draft_tokens: int = 0
+    num_accepted_tokens: int = 0
 
 
 @dataclass
@@ -371,6 +375,10 @@ def update_from_output(
             req_stats.first_token_latency = first_token_latency
 
         req_stats.num_generation_tokens += num_new_generation_tokens
+        req_stats.num_draft_tokens += max(
+            0, output.num_draft_tokens - output.num_invalid_spec_tokens
+        )
+        req_stats.num_accepted_tokens += output.num_accepted_tokens
 
         # Track if this request is corrupted (only check once per request)
         # Early exit if already marked as corrupted to avoid redundant checks
@@ -472,6 +480,8 @@ def update_from_finished_request(
             mean_time_per_output_token=mean_time_per_output_token,
             is_corrupted=req_stats.is_corrupted,
             num_cached_tokens=num_cached_tokens,
+            num_draft_tokens=req_stats.num_draft_tokens,
+            num_accepted_tokens=req_stats.num_accepted_tokens,
         )
         self.finished_requests.append(finished_req)
 

vllm/v1/spec_decode/metrics.py

@@ -140,6 +140,7 @@ class SpecDecodingProm:
     """
 
     _counter_cls = prometheus_client.Counter
+    _histogram_cls = prometheus_client.Histogram
 
     def __init__(
         self,
@@ -148,9 +149,35 @@ def __init__(
         per_engine_labelvalues: dict[int, list[object]],
     ):
         self.spec_decoding_enabled = speculative_config is not None
+
         if not self.spec_decoding_enabled:
             return
 
+        histogram_request_acceptance_rate = self._histogram_cls(
+            name="vllm:spec_decode_request_acceptance_rate",
+            documentation=(
+                "Histogram of request-level speculative decoding draft "
+                "acceptance rates for finished requests."
+            ),
+            buckets=[
+                0.0,
+                0.1,
+                0.2,
+                0.3,
+                0.4,
+                0.5,
+                0.6,
+                0.7,
+                0.8,
+                0.9,
+                1.0,
+            ],
+            labelnames=labelnames,
+        )
+        self.histogram_spec_decode_request_acceptance_rate = create_metric_per_engine(
+            histogram_request_acceptance_rate, per_engine_labelvalues
+        )
+
         counter_drafts = self._counter_cls(
             name="vllm:spec_decode_num_drafts",
             documentation="Number of spec decoding drafts.",
@@ -213,3 +240,17 @@ def observe(self, spec_decoding_stats: SpecDecodingStats, engine_idx: int = 0):
             self.counter_spec_decode_num_accepted_tokens_per_pos[engine_idx]
         ):
             counter.inc(spec_decoding_stats.num_accepted_tokens_per_pos[pos])
+
+    def observe_finished_request(
+        self,
+        num_draft_tokens: int,
+        num_accepted_tokens: int,
+        engine_idx: int = 0,
+    ) -> None:
+        if not self.spec_decoding_enabled or num_draft_tokens <= 0:
+            return
+
+        acceptance_rate = num_accepted_tokens / num_draft_tokens
+        self.histogram_spec_decode_request_acceptance_rate[engine_idx].observe(
+            acceptance_rate
+        )