Phase 10 - Lesson 15

Decodificação Especulativa e EAGLE-3

This lesson includes a graded coding exercise that runs in your browser, unlocked with lifetime access.

A Fase 7 · Lição 16 provou a matemática: a regra de rejeição de Leviathan preserva exatamente a distribuição do verificador. Esta lição é a visão da pilha de treinamento da decodificação especulativa em produção em 2026. O EAGLE-3 transformou o modelo de rascunho de uma aproximação barata em uma rede minúscula sob medida treinada nos próprios estados ocultos do verificador, e depois adicionou um loop de teste em tempo de treinamento que alinha suas distribuições de treino e inferência. Resultado: aceleração de 3× a 6,5× de ponta a ponta, taxas de aceitação por token acima de 0,9 no chat, sem perda de distribuição. Toda pilha de inferência em produção em 2026 o inclui por padrão.

Tipo: Build Idiomas: Python (stdlib) Pré-requisitos: Fase 7 · 16 (matemática de decodificação especulativa), Fase 10 · 12 (otimização de inferência) Tempo: ~75 minutos

Objetivos de Aprendizado

• Explicar o teorema de Leviathan em uma única frase e provar que o loop especulativo produz amostras distribuídas identicamente às do verificador.
• Percorrer a evolução de dois anos da decodificação especulativa tradicional (Leviathan 2023) passando por EAGLE, EAGLE-2 e EAGLE-3, nomeando a limitação exata que cada etapa removeu.
• Calcular a aceleração esperada a partir da taxa de aceitação α e da razão de custo entre rascunho e verificador c, e escolher o comprimento ideal de rascunho N para cada cenário.
• Implementar o loop especulativo completo do zero: rascunho, verificação, amostragem por rejeição do resíduo, reversão do KV cache na rejeição e emissão do token de bônus em caso de aceitação completa.

O Problema

A decodificação autorregresiva em um modelo de 70B roda a talvez 35 tokens por segundo em uma H100. A GPU não está nem perto de ser saturada. A largura de banda de memória é o teto: cada token carrega 70B de pesos da HBM, executa uma etapa de aritmética e produz um float. As unidades de computação ficam majoritariamente ociosas.

A decodificação especulativa transforma isso em um problema de vazão que você realmente pode resolver. Um rascunho barato propõe N tokens em N pequenas passagens diretas (forward passes). O verificador executa uma única vez no prefixo somado a todos os N rascunhos. Se a distribuição do verificador na posição i estiver de acordo com a do rascunho (em um sentido estatístico que detalharemos), nós aceitamos; se não, rejeitamos e amostramos uma correção da distribuição residual. Um único passo direto do modelo grande produz até N+1 tokens aceitos em vez de um.

O teorema que importa é o de Leviathan, Kalman, Matias (ICML 2023): a distribuição de saída é idêntica à que a amostragem direta do verificador teria produzido. Não aproximadamente. Identicamente. Esta é a razão de a decodificação especulativa ser aceitável em produção — trata-se de uma otimização puramente de latência, sem perdas de qualidade.

O que a Fase 7 · Lição 16 lhe deu foi a matemática. O que esta lição lhe dá é a pilha de treinamento. Um bom rascunho vale 2× mais aceleração do que um rascunho barato. EAGLE, EAGLE-2 e EAGLE-3 (Li et al., 2024–2025) transformaram o paradigma "rascunho = versão menor do mesmo modelo" em uma disciplina de engenharia precisa. Os servidores de inferência de produção de 2026 utilizam o EAGLE-3 por padrão.

O Conceito

O invariante: amostragem por rejeição de Leviathan

Seja p(t) a distribuição do rascunho para o próximo token dado um certo prefixo, e q(t) a do verificador. Amostre um token de rascunho d ~ p. Aceite com probabilidade min(1, q(d) / p(d)). Em caso de rejeição, amostre da distribuição residual (q - p)_+ / ||(q - p)_+||_1. As amostras resultantes são distribuídas de acordo com q. Isso é verdade independentemente de quão ruim seja p — quanto pior for, mais frequentemente você rejeitará, mas a saída permanecerá exata.

Empilhe N dessas chamadas em sequência usando uma única passagem direta do verificador em prefix + d_1 + ... + d_N. O verificador retorna q_1, q_2, ..., q_{N+1} simultaneamente. Percorra da esquerda para a direita. Na primeira rejeição na posição j, amostre de residual(q_j, p_j) e pare. Em caso de aceitação total, amostre um token de bônus de q_{N+1}.

O que determina a aceleração

Seja α a taxa de aceitação esperada por token rascunhado. Seja c = cost(draft) / cost(verifier) a razão de custos. O número esperado de tokens aceitos por passagem direta do verificador é:

E[accepted] = (1 - α^(N+1)) / (1 - α)

O tempo real esperado (wall time) por token aceito é (N * c + 1) / E[accepted]. Minimize isso em relação a N e você encontrará o ponto ideal. Para α = 0.8, c = 0.05: o N ideal é em torno de 5–7, e a aceleração é de 3.2×. Para α = 0.95, c = 0.02: o N ideal é em torno de 8–10, com aceleração chegando a 5×.

A maior alavanca isolada é α. Ir de α = 0.6 (rascunho tradicional) para α = 0.9 (EAGLE-3) com N = 5 fixo eleva os tokens aceitos esperados por passagem do verificador de 2.2 para 4.1. Quase 2× mais vazão com o mesmo verificador.

A evolução de dois anos

Especulativa tradicional (Leviathan, 2023). O modelo de rascunho é um LLM menor treinado de forma independente pertencente à mesma família. Fácil de conectar, α ≈ 0.6, aceleração de no máximo 2×.

EAGLE-1 (Li et al., 2024). O rascunho é um transformador minúsculo — normalmente de uma ou duas camadas — que recebe como entrada o estado oculto da última camada do verificador e prevê o próximo token diretamente. Como o rascunho vê a representação de características do verificador, sua distribuição é muito mais próxima da dele. α sobe para 0,7–0,8.

EAGLE-2 (Li et al., 2024). Adiciona uma árvore de rascunhos dinâmica: em vez de propor uma única sequência de N tokens, propõe uma pequena árvore de candidatos, avalia cada um com o verificador em um único passo direto (atenção em árvore) e segue o caminho de maior probabilidade. O comprimento do rascunho torna-se adaptativo por etapa. A α por token no caminho aceito ultrapassa 0,85.

EAGLE-3 (Li et al., 2025, NeurIPS). Duas modificações adicionais. Primeiro, descarta completamente a perda de previsão de características (feature-prediction loss) — o EAGLE-1/2 treinava o rascunho para corresponder aos estados ocultos do verificador, o que limitava o quanto o volume de dados ajudava. O EAGLE-3 treina diretamente na previsão de tokens. Segundo, teste em tempo de treinamento (TTT): durante o treino do rascunho, realimenta as previsões anteriores do próprio rascunho como entradas ao longo de várias etapas, exatamente como ele opera na inferência. Isso alinha as distribuições de treino e teste e interrompe o acúmulo de erros. Aceleração medida: até 6,5× em chat, melhoria de 38% na vazão com batch 64 no SGLang em H100.

Reversão de KV cache

A verificação estende o KV cache do verificador em N entradas em um único passo. Se ocorrer uma rejeição na posição j, o conteúdo do cache após a posição j-1 passa a estar incorreto. Duas implementações comuns: gravar em um buffer temporário (scratch buffer) e confirmar na aceitação (vLLM, TensorRT-LLM), ou manter um KV cache físico acompanhado de um comprimento lógico e truncá-lo na rejeição. De qualquer forma, o custo da reversão é de bytes por camada por cabeça, o que é insignificante em comparação ao custo da passagem direta.

Para a busca em árvore do EAGLE-2, o verificador executa atenção com uma máscara não causal que respeita a topologia da árvore. A engenharia é complexa, mas a computação é uma chamada padrão de flash-attention com uma máscara personalizada.

Arquiteturas de rascunho em 2026

Em produção em 2026: vLLM e SGLang usam o EAGLE-3 por padrão quando disponível, e EAGLE-2 nos outros casos. O TensorRT-LLM possui o caminho mais rápido para Medusa nos modelos públicos da Meta e NVIDIA. O llama.cpp distribui rascunhos tradicionais para implantações em CPU.

Implementando

Consulte code/main.py. Este é o loop especulativo completo de Leviathan com todas as suas partes: rascunho-de-N, passagem paralela do verificador, rejeição por posição, amostragem residual, token de bônus, reversão de KV e verificação empírica de que a distribuição de saída corresponde à amostragem direta de q.

Passo 1: a regra de rejeição

def accept(q_prob, p_prob, u):
    if p_prob <= 0:
        return True
    return u < min(1.0, q_prob / p_prob)

Passo 2: distribuição residual

def residual(q, p):
    raw = [max(0.0, qi - pi) for qi, pi in zip(q, p)]
    s = sum(raw)
    if s == 0:
        return list(q)
    return [r / s for r in raw]

Passo 3: uma etapa especulativa completa

A função spec_step gera N tokens de rascunho a partir de p, e em seguida verifica todos eles em uma única avaliação paralela de q. Para cada token rascunhado, ela aplica a regra de rejeição e, na primeira rejeição, amostra a correção do resíduo. Se tudo for aceito, emite um token de bônus de q_{N+1}.

Passo 4: controle de reversão de KV

O simulador rastreia um kv_length lógico por worker. Ao aceitar k rascunhos, kv_length += k. Em caso de rejeição na posição j, o cache já terá sido gravado além de j, mas o comprimento lógico é definido como prefix_length + j + 1 — uma posição após o token de correção. As leituras subsequentes truncam o cache para o comprimento lógico.

Passo 5: a verificação de Leviathan

Execute 50.000 etapas especulativas. Conte a distribuição empírica dos tokens aceitos. Compare com 50.000 amostras diretas de q. A estatística qui-quadrado deve ficar bem abaixo do valor crítico. O teorema se confirma na prática.

Passo 6: aceleração vs. α

Varra a qualidade do rascunho perturbando p para longe de q em diferentes amplitudes. Meça α e plote os tokens esperados por chamada do verificador como uma função de α e N. O código imprime uma tabela demonstrando como a qualidade de rascunho de classe EAGLE-3 (α ≈ 0.9) libera de 4 a 5 tokens por chamada do verificador.

Uso

Instância de vllm serve em nível de produção com EAGLE-3:

vllm serve meta-llama/Llama-3.3-70B-Instruct \
  --speculative-config '{
    "model": "yuhuili/EAGLE3-LLaMA3.3-Instruct-70B",
    "num_speculative_tokens": 5,
    "method": "eagle3"
  }'

SGLang com EAGLE-3 em batch 64 na H100: aproximadamente 1,38× maior vazão do que a decodificação tradicional em batch 64, de acordo com o artigo do EAGLE-3.

Quando recorrer à decodificação especulativa:

• Qualquer carga de trabalho de chat interativo em que a latência p50 seja mais importante do que a vazão de pico.
• Geração de código e saídas estruturadas (JSON, SQL). α fica acima de 0,9 porque a distribuição de destino é altamente previsível.
• Geração de textos locais (milhares de tokens). A aceleração amortizada continua gerando ganhos.

Quando não recorrer:

• Modelos muito pequenos (< 3B). O rascunho não é tão mais barato do que o verificador.
• Implantações minúsculas em CPU com batch-1. O custo de memória do modelo de rascunho pode não valer a pena.
• Amostragem criativa com temperaturas muito altas, em que α entra em colapso.

Produção

Esta lição produz outputs/skill-eagle3-tuner.md. Dada uma carga de trabalho de inferência (modelo, tamanho de lote/batch size, latência desejada, perfil da tarefa), ela recomenda uma estratégia de decodificação especulativa e parâmetros de ajuste (família de rascunho, N, profundidade da árvore, alternância com base em temperatura).

Exercícios

1. Execute code/main.py. Confirme que a estatística qui-quadrado na verificação de distribuição de Leviathan permanece abaixo do valor crítico de 95% em 50.000 amostras.

2. Varra N de 1 a 10 com α mantido em 0,9 e c mantido em 0,04. Plote os tokens esperados por chamada do verificador e o tempo real (wall time) de processamento por token. Encontre o N que minimiza o tempo real. Explique o formato da curva.

3. Modifique o código para simular a busca em árvore do EAGLE-2: em cada etapa, o rascunho propõe uma árvore de formato [2, 2, 2] (oito caminhos candidatos). O verificador é executado uma vez, e o caminho aceito com maior probabilidade vence. Calcule α por folha e o total de tokens por chamada do verificador. Compare com a decodificação especulativa em cadeia linear com computação equivalente.

4. Implemente um simulador de reversão de KV em lote para duas sequências simultâneas. A sequência A tem todos os rascunhos aceitos; a sequência B rejeita na posição 2. Mostre que o kv_length correto é atualizado por sequência e que nenhum processamento é desperdiçado.

5. Leia a Seção 4 (Training-Time Test) do artigo do EAGLE-3. Explique em duas frases por que o treinamento simples de rascunho sem TTT sofre de viés de exposição, e por que alimentar o rascunho com suas próprias previsões durante o treinamento resolve isso. Relacione isso à literatura de amostragem programada (scheduled sampling) em seq2seq.

Termos-Chave

Leituras Recomendadas

• Leviathan, Kalman, Matias — Fast Inference from Transformers via Speculative Decoding (arXiv:2211.17192, ICML 2023) — o artigo fundamental e o teorema de equivalência
• Chen et al. — Accelerating Large Language Model Decoding with Speculative Sampling (arXiv:2302.01318) — introdução independente e simultânea com uma demonstração limpa
• Li et al. — EAGLE: Speculative Sampling Requires Rethinking Feature Uncertainty (arXiv:2401.15077) — EAGLE-1, rascunho condicionado ao estado oculto
• Li et al. — EAGLE-2: Faster Inference of Language Models with Dynamic Draft Trees (arXiv:2406.16858) — busca dinâmica em árvore
• Li et al. — EAGLE-3: Scaling up Inference Acceleration via Training-Time Test (arXiv:2503.01840, NeurIPS 2025) — o padrão de produção em 2026
• Cai et al. — Medusa: Multiple Decoding Heads (arXiv:2401.10774) — abordagem alternativa sem rascunho
• vLLM Speculative Decoding documentation — referência canônica de produção com todas as estratégias integradas