llama.cpp 投机解码实战：draft、EAGLE-3 等加速方案让推理速度翻倍

llama.cpp 投机解码（Speculative Decoding）实战指南：本文带你快速上手 llama.cpp 内置的 draft 草稿模型、EAGLE-3、DFlash、DSpark 与 n-gram 系列等 7 种推理加速方案，通过"小模型打草稿 + 大模型批量验证"的思路，把大模型推理速度提升数倍，并教你调优--spec-type等关键参数、看懂接受率统计。

为什么投机解码能让 LLM 推理变快？

如果你用过llama-server或llama-cli，一定对"生成阶段（Token Generation）"的速度有印象：模型每次只吐一个 token，一次要算完整个大模型，串行解码成了吞吐瓶颈。

而"预填充阶段（Prompt Processing）"却是并行的：一次 batch 同时算成百上千个 token，GPU 利用率很高。

投机解码就是利用了这个差异：

1. 打草稿：用一个小得多的模型（draft model）快速"猜"出接下来的若干个 token；
2. 批量验证：大目标模型（target model）一次性把这串草稿 token 全部算完，并和草稿比对；
3. 采纳前缀：从第一个不一致的位置截断，采纳所有正确的前缀 token，再继续下一轮。

只要草稿猜得比较准，一轮就能"免费"拿到多个 token，速度自然翻倍甚至更多。

💡 核心直觉：猜错的代价只有一次验证，猜对的收益是跳过整段串行解码。这也是为什么官方文档强调"当草稿预测频繁正确时，可获得可观的加速"。

原理详见 docs/speculative.md。

llama.cpp 支持的投机解码方案一览

llama.cpp 在llama-server中内置了多种实现，通过--spec-type参数选择，支持逗号分隔组合多种方案。核心实现在 common/speculative.cpp 和 common/speculative.h 中。

📌 选型速记：

• 有 GPU、追求极限速度→ 上 EAGLE-3 / DSpark 这类专用草稿
• 没有额外模型、场景有大量重复文本（代码重构、总结、推理模型复述思考过程）→ n-gram 系列零成本起步
• 手边只有一个同系列小模型→draft-simple最简单直接

快速上手：用 draft 模型加速

最简单的玩法：准备一个和目标模型同系列、同 tokenizer的小模型（例如用 0.5B 草稿 + 8B 目标），启动时通过-md指定草稿模型：

llama-server -m model-8B.gguf -md model-0.5B.gguf --spec-type draft-simple

常用参数：

• --spec-draft-n-max：每轮最多打几个草稿 token（默认 3）
• --spec-draft-ngl：草稿模型放多少层到显存（默认auto）
• --spec-draft-p-min：greedy 模式下的最低投机概率

💡 草稿模型越小越好——它的职责只是"猜"，精度要求远低于目标模型。

examples/speculative/目录下还有一个最小化演示程序 examples/speculative/speculative.cpp，可以看到草稿-验证流程的完整调用。

EAGLE-3：读取隐状态的"开卷草稿"，接受率更高

普通 draft 模型只能看到 token 本身，而EAGLE-3 草稿是一个单层 transformer，它直接读取目标模型的隐状态（hidden states）来预测下一个 token，信息量大得多，因此同体积下接受率显著更高。它可以复用目标模型的 tokenizer，并支持缩减版词表 +d2t映射表。

启用方式（需要先转换 EAGLE-3 检查点）：

python convert_hf_to_gguf.py AngelSlim/Qwen3-4B_eagle3 \ --target-model-dir Qwen/Qwen3-4B --outtype bf16 --outfile Qwen3-4B-eagle3.gguf llama-server -m Qwen3-4B.gguf -md Qwen3-4B-eagle3.gguf --spec-type draft-eagle3

关键技巧：转换时带上--target-model-dir，让草稿模型继承目标模型的 tokenizer 和需要读取的层索引。Qwen3、Llama 3、Gemma、gpt-oss 等模型都有社区现成的 EAGLE-3 草稿可用，完整清单见 docs/speculative.md。

DFlash 与 DSpark：块扩散草稿，GPU 更友好

这两个方案代表了新一代草稿技术：

• DFlash（draft-dflash）：不再逐 token 自回归地打草稿，而是一次前向传播输出一整块草稿 token（block diffusion），并把目标模型的隐状态注入草稿模型的注意力中。块越大，GPU 上的批量效率越高。
• DSpark（draft-dspark）：在 DFlash 基础上加了半自回归的Markov 头——每个位置的 logits 会被"上一个 token"低秩修正，在保持"一次出整块"的同时找回一部分从左到右的语言信号。

# DSpark 示例（以 Qwen3-4B 为例） llama-server -m Qwen3-4B.gguf -md Qwen3-4B-DSpark.gguf \ --spec-type draft-dspark --spec-draft-n-max 7 -fa on --jinja

⚠️ 注意--spec-draft-n-max会被钳制到草稿模型训练时的块大小，不是越大越好。官方用 M5 Pro 实测了一组 DFly 数据，很有启发性：

最优值在中间——具体多少取决于你的硬件和目标模型，建议自己扫一遍，而不是直接取默认值。

n-gram 系列：不用额外模型的"免费加速"

n-gram 方案完全不需要草稿模型：它们在已经生成的 token 历史里找重复模式，把历史上出现过多次的片段直接作为草稿。

就像旧报纸上充斥着"NEW YORK, MONDAY"这类固定排版文本一样，以下场景天然适合 n-gram：

• 代码重构：源码里有大量重复的函数调用、缩进结构（官方推荐案例）
• 推理模型：把思考过程复述进最终答案
• 总结/摘要：反复引用原文片段

三个主要变体的区别：

零成本开启ngram-mod甚至只要加一个参数：

llama-server -m model.gguf --spec-default # 或手动指定：--spec-type ngram-mod

调参要点（来自官方文档）：n太小不建议；MoE 模型需要更长的草稿；密集模型可以适当调小--spec-ngram-mod-n-min/max。

调优与效果验证：看懂接受率统计

每种实现运行结束时都会打印统计信息，这是判断"值不值"的关键：

draft acceptance rate = 0.57576 ( 171 accepted / 297 generated) statistics ngram_simple: #calls = 15, #gen drafts = 5, #acc drafts = 5, #gen tokens = 187, #acc tokens = 73

• draft acceptance rate：草稿 token 被采纳的比例，越高加速越明显
• #gen tokens/#acc tokens：草稿生成总数 vs 被主模型接受的 token 数
• dur(b,g,a)：begin（新 prompt）、generation、accumulation（处理接受）三段耗时

📊 想系统测量端到端加速效果（吞吐、延迟、接受率），可以配合 SPEED-Bench 客户端，对同一llama-server分别跑"基线"和"投机解码"两组对比，说明见 tools/server/bench/README.md。

实用调优清单

1. 先用--spec-type ngram-mod白嫖：零成本，若文本重复度高就有立竿见影的效果
2. 有资源再上专用草稿：EAGLE-3 / DSpark 接受率更高，适合生产级吞吐场景
3. 扫--spec-draft-n-max：默认值不一定是你硬件上的最优值
4. 用 greedy 采样做 A/B 对比：随机采样下浮点差异可能导致不同实现的 token 不完全一致，greedy 下对比最干净
5. 多方案可叠加：如--spec-type ngram-mod,ngram-map-k4v，无草稿的方案与有草稿的方案可以混用（无草稿方案优先级更高）

总结

llama.cpp 的投机解码生态相当完整：draft-simple 打底、EAGLE-3 提接受率、DFlash/DSpark 走块扩散路线、n-gram 系列零成本兜底。对新手来说，建议从--spec-default（即 ngram-mod）开始体验，有 GPU 和小模型储备后再升级到 EAGLE-3，配合接受率统计和 SPEED-Bench 量化加速收益——让 LLM 推理速度翻倍，并不需要更换模型，只是换一种"猜"的方式。

📚 延伸阅读：docs/speculative.md（完整参数表）· examples/speculative/README.md（演示程序）· common/speculative.h（核心 API）