Principle:Vllm project Vllm Speculation Metrics Evaluation
| Knowledge Sources | |
|---|---|
| Domains | LLM Inference, Speculative Decoding, Observability |
| Last Updated | 2026-02-08 13:00 GMT |
Overview
Speculation metrics evaluation is the process of collecting and analyzing performance counters from the speculative decoding engine to assess acceptance rates, draft efficiency, and identify optimization opportunities.
Description
After running inference with speculative decoding, it is essential to evaluate how well the speculation strategy is performing. vLLM exposes Prometheus-based metrics that capture the key performance indicators of the draft-then-verify loop. These metrics enable operators and researchers to:
- Measure the overall acceptance rate: the fraction of draft tokens that are accepted by the target model
- Analyze per-position acceptance rates: how acceptance rates decay at later speculation positions
- Count the total number of draft rounds and draft tokens generated
- Compute the mean acceptance length: the average number of tokens accepted per draft round (including the bonus token)
These metrics are critical for tuning the num_speculative_tokens parameter. If acceptance rates drop sharply after position 2, setting K=5 wastes draft computation. Conversely, if acceptance rates remain high at position 4, increasing K from 3 to 5 may yield additional speedup.
Usage
Use this principle when evaluating and tuning speculative decoding deployments. Metrics should be collected after a representative workload to make informed decisions about:
- Whether speculative decoding is providing a net speedup
- What the optimal
num_speculative_tokensvalue is - Whether a different speculation method would perform better
- Whether the EAGLE/draft model is well-matched to the target model
Theoretical Basis
Key Metrics and Their Meaning
The speculative decoding metrics form a coherent measurement system:
| Metric Name | Type | Description |
|---|---|---|
vllm:spec_decode_num_drafts |
Counter | Total number of draft rounds executed. Each round proposes K candidate tokens. |
vllm:spec_decode_num_draft_tokens |
Counter | Total number of draft tokens proposed across all rounds. Equals num_drafts * K.
|
vllm:spec_decode_num_accepted_tokens |
Counter | Total number of draft tokens accepted by the target model across all rounds. |
vllm:spec_decode_num_accepted_tokens_per_pos |
Vector | Per-position accepted token counts. Index 0 is the first speculative position, index K-1 is the last. |
Derived Metrics
From the raw counters, several derived metrics provide deeper insight:
# Overall acceptance rate
acceptance_rate = num_accepted_tokens / num_draft_tokens
# Mean acceptance length (tokens accepted per draft round, plus the bonus token)
mean_acceptance_length = 1 + (num_accepted_tokens / num_drafts)
# Per-position acceptance rate
acceptance_rate_at_pos_i = accepted_tokens_per_pos[i] / num_drafts
# Expected tokens per step (the actual speedup driver)
tokens_per_step = 1 + sum(acceptance_rate_at_pos_i for i in 0..K-1)
Acceptance Rate Decay
In practice, acceptance rates decrease monotonically with position:
acceptance_rate[0] > acceptance_rate[1] > ... > acceptance_rate[K-1]
This decay occurs because each position's acceptance is conditioned on all previous positions being accepted. The rate of decay depends on the quality of the draft mechanism:
- High-quality drafts (well-matched EAGLE head, MTP): Slow decay, e.g., 0.90, 0.85, 0.78, 0.70
- Medium-quality drafts (draft model): Moderate decay, e.g., 0.80, 0.65, 0.50, 0.35
- Low-quality drafts (n-gram on dissimilar content): Steep decay, e.g., 0.40, 0.15, 0.05, 0.01
Optimal K Selection
The optimal number of speculative tokens K can be determined from the per-position acceptance rates:
# Marginal benefit of increasing K from k to k+1:
marginal_benefit = acceptance_rate[k] * cost_verify / cost_draft
# Continue increasing K while marginal_benefit > 1
# In practice, K=2..5 is typical for EAGLE, K=2..3 for draft models
The decision depends on the cost ratio between drafting and verification. For EAGLE (very cheap drafting), higher K values are worthwhile even with modest acceptance rates. For draft model methods (expensive drafting), K should be more conservative.