Vibe Engines
YouTube

Vibe Engines is free, interactive AI engineering & system design — runs in your browser. Pick a learning path

~11 min read2024

Medusa,
explained.

Speculative decoding made generation faster, but it came with baggage: a whole second "draft" model to train, serve, and keep in sync. Medusa asked whether the big model could just draft for itself. Its answer: bolt a few extra prediction heads onto the model, each guessing a token further ahead, and let it propose several future tokens in a single pass — then verify them all at once. No draft model, real speedup. Here's the multi-head trick and the arithmetic of how much it buys.

The delta

What changes against a draft model: the model drafts for itself

Rung 4's speed-up is real and its operational cost is a second model — one to obtain, keep aligned with the target, hold in memory, and version alongside it. For many deployments that is the reason it is not used.

The change is to remove it. Attach extra prediction heads to the existing model, each trained to predict a token further ahead than the last, so a single forward pass emits not just the next token but guesses at several following ones. The draft comes from the model itself, at the cost of a few small heads, and there is nothing separate to align because the heads sit on the representation the model already computed.

Head accuracy necessarily decays with distance — predicting four tokens ahead from the current state is harder than one — so instead of committing to one guessed continuation, the top candidates from each head are combined into a tree of possible continuations, and a single pass with an appropriately masked attention pattern verifies many branches at once. Stated in rung 4's units, the accepted length per pass comes from covering several plausible continuations rather than from one accurate draft — breadth substituting for the draft model's depth.

01

The draft-model tax

Recall the bottleneck: language models generate one token at a time, and each token forces the whole model to be read from memory, leaving the hardware's compute mostly idle. Speculative decoding fills that idle compute by having a small, fast draft model guess several tokens ahead, which the big model then verifies in parallel. It works — but the draft model is a real operational cost. You have to find or train one that is both cheap and well-aligned with the target, serve it alongside, and maintain the pairing as models change.

Medusa removes the second model. Its insight: the big model already computes a rich hidden state at each position — enough, with a little extra machinery, to predict not just the next token but the one after, and the one after that. So instead of a separate drafter, give the model a few lightweight heads that read that hidden state and guess further ahead. The model drafts for itself.

The one-sentence version

Add a few extra prediction heads to the model so it guesses several tokens ahead in one pass, then verifies them — speculative decoding with no separate draft model.

02

Prediction heads

A standard model has one output head predicting the next token. Medusa adds K more, each a small feed-forward layer on the same final hidden state, trained to predict the token at position +2, +3, …, +K+1. They are cheap to add (in Medusa-1 the backbone is frozen and only the heads train; Medusa-2 fine-tunes both) and cheap to run (a few extra small layers). In one forward pass, the model now emits its usual next token plus K guesses for the tokens beyond it.

The catch is accuracy. Predicting the very next token is relatively easy; predicting five tokens ahead, with all the uncertainty of the words in between, is much harder. So head accuracy fades with distance — the first head is fairly reliable, later heads much less so. That decay is exactly what governs how many tokens Medusa can actually keep per pass, and it's the number the math below tracks.

03

Tree attention

Because the far heads are unsure, betting everything on their single top guess is wasteful — often it's wrong, and the whole speculation stops there. Medusa hedges: each head proposes its top few candidates, and the combinations form a tree of possible continuations (this head's option A followed by that head's options X or Y, and so on). A single guess per head accepts if it's right with probability a; offering s candidates accepts if any of them is right — probability 1 − (1 − a)^s, which climbs fast.

The clever part is verifying this whole tree in one forward pass. Medusa builds a special attention mask — tree attention — so that each candidate token only attends to its own ancestors in the tree, letting many candidate paths be scored simultaneously without interfering. One pass, many hypotheses checked, and the longest fully-correct path is accepted. It is how Medusa turns uncertain heads into reliable speedups.

04

Verify and accept

Verification keeps the output honest. The tree of candidates is scored by the true model, and Medusa accepts the longest path whose tokens the model agrees with — falling back to the guaranteed correct next token when the heads miss. With greedy acceptance, a position is only kept if every head before it was also right, so each head's contribution is the cumulative product of accuracies. Summing those, plus the always-correct base token, gives the expected tokens per pass:

Because each term multiplies one more (sub-1) accuracy, later heads add less and less — a fading geometric-like series. With four heads at accuracies 0.8/0.65/0.5/0.35 the model produces ~2.7 tokens per pass instead of 1; perfect heads would give K+1. Tree candidates raise each head's effective accuracy toward 1, pushing the sum higher. Crucially, the accepted tokens are exactly the model's own, so under greedy decoding the output matches the base model's own (with the typical-acceptance rule used for sampling, it is only close to it, not guaranteed identical). The runnable version below computes both formulas.

How it works

How Medusa drafts, builds a tree and verifies, step by step

Medusa (Cai, Li, Geng, Peng, Lee, Chen and Dao) keeps the base model and its usual next-token head, and adds K decoding heads on top of the last hidden state ht. Head k guesses the token k + 1 positions ahead, so head 1 predicts position t + 2 while the original head predicts t + 1. The procedure:

base head head 1: top 2 head 2: top 2 sat next token 1 on 2 down 3 the 4 a 5 the 6 a tree attention mask each row sees only its ancestors 1 2 3 4 5 6 1 on 2 down 3 the 4 a 5 the 6 a 4 paths checked in one forward pass every row also sees the prefix and sat
Flattening the candidate tree into one sequence and masking attention to ancestors lets the base model verify every path at once; a shared prefix such as "on" is scored only once.
  1. Build the heads. Each head is a single feed-forward layer with a residual connection followed by its own vocabulary projection: p^(k) = softmax(W2^(k)(SiLU(W1^(k)ht) + ht)). W2 is initialized from the base model's output head and W1 at zero, so at the start every head reproduces the base model's next-token prediction and training only has to shift it.
  2. Medusa-1: train the heads on a frozen model. The backbone does not change, so the base model's own outputs are untouched. Each head gets a cross-entropy loss against the true token k + 1 places ahead, weighted by λk = 0.8^k so the more predictable near heads dominate. The authors report that heads for a 7B model train in a few hours on one GPU, and the frozen backbone can even be quantized meanwhile.
  3. Medusa-2: train heads and backbone together. For higher head accuracy the backbone is fine-tuned jointly, with the ordinary next-token loss kept in the objective so the model's own predictions do not degrade. Two precautions make this work: the heads are warmed up alone first, and they get a higher learning rate than the backbone.
  4. Self-distill when the training data is missing. For a chat model whose fine-tuning data is not public, the model generates its own training set from a collection of prompts. For Medusa-2 the next-token loss is then replaced by a KL divergence to the original model's predictions; with LoRA adapters, that teacher is simply the same weights with the adapters switched off.
  5. Propose a tree. At inference each head offers its top few tokens. Every combination of one choice per head is a candidate continuation; instead of the full product, the paper keeps a sparse tree built from head accuracies measured on a calibration set, adding the branches most likely to be accepted.
  6. Verify the tree in one pass. The tree is flattened into one sequence with an attention mask that lets each candidate see only the prefix and its own ancestors, and position indices are set by depth. One forward pass of the base model scores every node, and the heads read the same pass's hidden states to propose the next tree.
  7. Accept the longest valid path. Under greedy decoding a token is valid when it equals the base model's argmax at that node, and the output matches ordinary greedy decoding. For sampling, Medusa can use speculative sampling's rejection rule, which preserves the distribution, or its own typical acceptance, which is faster but approximate.

Typical acceptance

Typical acceptance keeps a candidate whenever the base model gives it probability above min(ε, δ · exp(−H)), where H is the entropy of the base model's distribution at that point. The first token of each step is always the base model's own greedy choice, so every step yields at least one token. Because the threshold drops when the model is uncertain, lower-probability candidates can pass in open-ended contexts, while in a confident, low-entropy context only near-certain tokens clear it.

The limitation later work attacked

Every Medusa head reads the same state ht and never sees the tokens chosen by the heads before it, so head 2's guess for position t + 3 does not know which token head 1 proposed for t + 2. Hydra makes the heads depend on earlier guesses, and EAGLE drafts autoregressively in the model's feature space, conditioning each step on the sampled token; both report higher acceptance for that reason.

The math

Medusa's head, its training losses and typical acceptance

pt^(k) = softmax(W2^(k) · (SiLU(W1^(k) · ht) + ht))
LMedusa-1 = Σk=1^K −λk log pt^(k)(yt+k+1), λk = 0.8^k
LMedusa-2 = LLM + λ0 · LMedusa-1
keep x if porig(x | prefix) > min(ε, δ · exp(−H(porig(· | prefix))))
  • ht — the backbone's last hidden state at position t; W1 (d × d, zero-initialized) and W2 (d × vocabulary, copied from the output head) — head k's only parameters.
  • yt+k+1 — the true token k + 1 positions ahead, the target for head k.
  • λk — decaying weights: far heads are less accurate and matter less, because a far guess is used only if every nearer one was accepted.
  • LLM, λ0 — the backbone's own next-token loss (a KL to the original model under self-distillation) and its balance against the head losses.
  • ε, δ, H — a hard probability floor, the scale of an entropy-dependent floor, and the entropy of the base model's prediction.

At the extremes: with ε and δ near zero almost any candidate passes, so steps get longer and outputs drift from the base model; with high thresholds only near-argmax tokens pass, and decoding approaches greedy decoding.

The evidence

What the Medusa paper measured

The paper evaluated Vicuna-7B, 13B and 33B and Zephyr-7B, chat models that differ in size and in how they were trained, on MT-Bench at batch size 1 on A100 GPUs. Speedup is wall-clock generation time against standard decoding of the same model, and quality is checked with MT-Bench's GPT-4-judged scores.

ConfigurationResult
Medusa-1, heads on a frozen backboneover 2.2× faster, generation quality unchanged
Medusa-2, heads and backbone trained jointly2.3–3.6× faster
Medusa-2 MT-Bench qualityclose to each original model's score
Speedup by MT-Bench categorylargest on coding and extraction

The ablations explain where the speed comes from and where it stops. Sparse trees built from calibration accuracies accepted more tokens per step than dense Cartesian trees with the same number of nodes. Adding nodes kept raising the tokens accepted per step, but past a point real speed fell, because a bigger tree makes every verification pass more expensive: the gain is bounded by the spare arithmetic in the pass. Raising the typical-acceptance threshold improved quality and reduced speed, a direct dial between the two. For Medusa-2, the paper reports that fine-tuning heads and backbone together directly, without the two-stage warm-up, degraded generation quality, which is why the recipe includes it, and self-distillation was what made the method usable on models whose training data was unavailable.

All of these numbers are for one request at a time. Because the acceleration spends the same spare arithmetic as speculative decoding, the gains should be expected to shrink as batch size grows.

Since then

What the authors admit, and what happened next

The honest comparison against rung 4 has costs on both sides. The heads are weaker predictors than a real small model, because they are shallow functions of a state computed for a different purpose, so acceptance per position is lower. Tree verification recovers that by checking more candidates, which spends the arithmetic headroom the whole approach depends on — and at high batch sizes, where that headroom is gone, the tree's cost stops being free before a single draft's does. And unlike a drop-in draft model, the heads must be trained for the specific model, so this is not something you switch on for an arbitrary checkpoint.

The acceptance criterion is also worth reading carefully. The variant that makes this fastest relaxes rung 4's exact distributional guarantee in favour of accepting tokens that are merely sufficiently likely — which is usually unobjectionable and is a real difference in kind from a method that changes nothing. Anyone who chose rung 4 because of the guarantee should not assume it carries over.

How it held up: self-drafting became a standard family, and the tree-verification idea outlived the specific design — verifying a branching set of continuations in one masked pass is now common in speculative decoding generally, including with external drafts. Read rungs 4 and 5 together as the ladder's closing argument: once memory traffic is the constraint, the way to go faster is to get more tokens out of each weight read, and where the guesses come from is an engineering choice.

SOLVE IT YOURSELF

Heads, accuracy decay, and tokens per pass

Medusa's speedup is a fading product you can compute. This sums each head's contribution — the cumulative product of accuracies, since a position is kept only if every earlier head was right — and shows four decaying heads yielding ~2.7 tokens per pass, no heads giving exactly 1, and perfect heads hitting the K+1 ceiling. It also prices tree attention: offering more candidates per head raises its acceptance via 1−(1−a)ˢ, from 0.6 to 0.97 at four candidates. Change the head accuracies or candidate count and watch the tokens-per-pass move.

YOUR TASK

Write the body of expected_tokens. Everything else in the file is already written; this is the function the paper is about. Press ▶ Run to check it against the 5 assertions below — they start red.

WHAT IT HAS TO SATISFY — 5 ASSERTIONS
  1. No heads gives exactly 1 token per pass
  2. Perfect heads give K+1 tokens per pass
  3. More/better heads yield more tokens per pass
  4. Each further head contributes less as accuracy fades
  5. Tree candidates raise per-head acceptance
CPython · WebAssembly
05

The trade-offs

Medusa and draft-model speculative decoding are two routes to the same goal; each has a personality:

AspectMedusa
No draft modelNothing extra to train, serve, or keep aligned — the big model drafts for itself.
Cheap to addA few small heads trained on top of a frozen backbone (Medusa-1); optionally fine-tuned jointly (Medusa-2).
Head accuracy limits reachFar heads are weak, so gains taper — tree attention props them up but there's a ceiling.
~2–3× speedupExact under greedy decoding and near-lossless with typical acceptance, with a simpler serving stack than a two-model setup.

Where a well-matched draft model can sometimes propose longer accurate runs, Medusa wins on operational simplicity — one model, a handful of heads, no second system. For many deployments that trade is exactly right.

06

Where it fits

Medusa is part of a fast-moving family of self-speculative decoding methods — including EAGLE, Hydra, and lookahead decoding — all aiming to get speculative decoding's speed without the burden of a separate draft model. They differ in how they draft (extra heads, feature-space prediction, n-gram pools) but share the skeleton established by speculative decoding: propose cheaply, verify in parallel, keep what's correct.

Its contribution to that lineage is a clean, practical recipe: reuse the model's own hidden state through lightweight heads, and hedge their uncertainty with tree attention. That combination — self-drafting plus batched candidate verification — turned out to be a sweet spot of simplicity and speed, and it's why Medusa became a widely-used, easy-to-adopt inference accelerator.

Worth knowing

Because Medusa's heads sit on the model's own hidden states, they can be trained on a modest dataset in hours on a single machine — you don't retrain the base model, just teach a few heads to read what it already computes.

Questions

Questions people ask about Medusa

What is typical acceptance in Medusa, and is it lossless?

Typical acceptance is Medusa's rule for deciding which candidate tokens to keep when sampling. A candidate is accepted if the base model gives it probability above the smaller of a hard floor and a floor that falls as the base model's entropy rises, and the first token of each step is always the base model's own greedy choice. It is not lossless: unlike the rejection rule from speculative sampling, it does not guarantee that outputs follow the base model's sampling distribution. Medusa stays exact under greedy decoding, where a candidate is kept only if it equals the base model's top token, and it can use the standard rejection rule instead when exactness matters.

How is Medusa different from EAGLE?

Both draft from the target model's own internals instead of a separate draft model. Medusa's heads each read the same final hidden state and predict a fixed offset ahead, independently of one another, so a later head never learns which token an earlier head guessed. EAGLE, from Li and colleagues in 2024, trains a small autoregressive layer that predicts the next feature vector one step at a time, feeding back the sampled token, so each guess is conditioned on the ones before it. That dependence is why the EAGLE authors report higher acceptance and larger speedups than Medusa on the same models. Both verify a tree of candidates in one masked forward pass.

How are Medusa heads trained?

In Medusa-1 the base model is frozen and only the heads learn. Each head is one feed-forward layer with a residual connection plus an output projection, initialized so that it starts out copying the base model's next-token prediction, and it is trained with cross-entropy against the token k + 1 positions ahead, weighted by 0.8 to the power k. In Medusa-2 the backbone is fine-tuned too, with its ordinary next-token loss kept in the objective, the heads warmed up first and given a higher learning rate. When the original fine-tuning data is unavailable, the model generates its own training data, and the backbone is held close to the original with a KL divergence term.

How does Medusa choose its tree of candidates?

Each head offers its top few tokens, and every combination of one choice per head is a candidate continuation, so the full Cartesian product grows multiplicatively with the number of heads and choices. Medusa instead keeps a sparse tree. On a calibration set it measures how often each head's first, second and third choices are right, estimates the acceptance probability of every possible node as a product of those accuracies along its path, and adds the most promising nodes until a node budget is reached. The paper found such sparse trees accept more tokens per step than dense ones of the same size, while very large trees slow each verification pass.

Why do Medusa heads get less accurate for tokens further ahead?

Two reasons compound. A guess several positions ahead must account for every uncertain token in between, which is simply harder than predicting the next one. And Medusa's heads are independent: head 3 predicts its position from the same hidden state as head 1 without knowing what head 1 or head 2 proposed, so it has to hedge across all the continuations those intermediate tokens could take. Because a far guess is only usable if every nearer one is accepted, its contribution shrinks quickly, which is why the loss weights far heads less and why later methods such as Hydra and EAGLE condition each guess on the previous ones.

Is Medusa faster than speculative decoding with a draft model?

It depends on the draft you would otherwise use. The paper's argument for Medusa is mainly operational: no second model to obtain, align, host and keep in sync, and heads that train in hours on one GPU, with reported speedups of more than 2.2 times for Medusa-1 and 2.3 to 3.6 times for Medusa-2. A well-matched draft model from the same family can propose longer correct runs than shallow heads, and later self-drafting methods such as EAGLE report higher acceptance than Medusa. Both approaches spend the same spare arithmetic of a memory-bound forward pass, so both lose ground as the batch size grows.

Check yourself

4 questions to test what you just read

Work each one out before you open it — a number, a prediction or a reason, not a definition. Producing the answer is what makes it stick. Your progress is kept on this device.

Head 1 offers its top 3 tokens and head 2 its top 2. How many candidate continuations does the full Cartesian tree contain, and how many candidate tokens must the verification pass score?

Show answer

3 × 2 = 6 continuations. The tree has 3 nodes at depth one and 3 × 2 = 6 at depth two, so 9 candidate tokens are scored in one pass, against 12 if the six paths were checked as separate two-token sequences. Sharing prefixes is what the tree mask buys.

Why is W2 initialized from the base model's output head and W1 at zero, and what does every head predict at the start of training?

Show answer

With W1 = 0, SiLU(0) = 0, so the input to W2 is just ht, and with W2 copied from the output head every head starts out predicting the base model's next-token distribution. That is a reasonable first guess for nearby positions, and training begins from a stable, sensible point instead of random logits.

With λk = 0.8^k, how much weight does head 4's loss get relative to head 1's, and why decay the weights at all?

Show answer

0.8^4 / 0.8^1 = 0.8^3 ≈ 0.51. Far heads are inherently less accurate, and their guesses are only used when every nearer guess was accepted, so their errors matter less; the decay keeps their noisy losses from dominating the heads that contribute most.

Predict: with fixed ε and δ, is a candidate more likely to pass typical acceptance after "Write a poem about" or after "The capital of France is", and why?

Show answer

After "Write a poem about". That context has high entropy, so δ · exp(−H) is small and lower-probability candidates clear the threshold. After the factual prompt the distribution is peaked, the entropy floor is close to δ, and only the near-certain token passes.

Where this sits

Serving it cheaply

Five papers about the bill. Each one buys throughput back from a different part of the stack: the weights, the memory hierarchy, the KV cache, the decode loop.

  1. 1Knowledge Distillation2014
  2. 2FlashAttention2022
  3. 3PagedAttention2023
  4. 4Speculative Decoding2023
  5. 5Medusa2024

All 110 papers, in 19 ladders →

Medusa: Simple LLM Inference Acceleration Framework with Multiple Decoding Heads · Cai, Li, Geng, Peng, Lee, Chen, Dao · 2024 · read the original paper on arXiv → · Vibe Engines · 2026
Finished this one? 0 / 110 Paper Breakdowns done
NextAttention Is All You Need Closest paper breakdown to this one

Explore the topic

See this alongside everything else on the same subject — handbooks, system designs, challenges and tools, in one place.

More Paper Breakdowns