eagle-hq/EAGLE-4 · 上手攻略

  • 仓库：eagle-hq/EAGLE-4
  • 链接：https://github.com/eagle-hq/EAGLE-4
  • 分类：llm-infra
  • 作者：spark
  • 更新：2026-10-24

一、它是什么

EAGLE-4 是 Eagle AI（eagle.ai）发布的第四代投机解码（speculative decoding）推理方案，本仓库是其官方推理代码，核心是一个名为 eagle-harness 的 Python 包。

它的卖点是"一个 drafter 适配所有批量与硬件"：传统投机解码的 draft tree 形状（深度、宽度、验证 token 数）要么写死、要么靠人肉调参；EAGLE-4 让 harness 在目标 GPU 上实测每轮成本，据此决定"猜多深、猜多宽"，输出分布仍与目标模型单独解码一致（lossless）。

仓库本身不含模型权重，而是提供：eagle-harness 包 + 打了补丁的 SGLang / vLLM / TokenSpeed 引擎 wheel + 一组完整的文档（安装、标定、配置、架构、kernel、兼容性、故障排查、支持矩阵）。

官方论文标题为 EAGLE-4: One Flexible Drafter for All Batch Sizes and Hardware（EAGLE-4 Team，2026，preprint）。README 中的引用条目 note = {Preprint} 表明目前是预印本状态。

三证自检

项 状态
GitHub URL（已 fetch） ✅ 已 fetch README + docs/install.md + docs/quickstart-sglang.md + docs/known-limits.md + docs/support-matrix.md
顶会 venue + 年份 ⚠️ 未确认——引用块标为 Preprint（2026），本次未找到顶会接收记录
README 子模块 anchor ✅ 至少 1 个：eagle-harness 独立 PyPI 包 + eagle-hq/sglang / eagle-hq/vllm / eagle-hq/tokenspeed 三个 fork
官方发布博客 ✅ https://blog.eagle.ai/blog/introducing-eagle-4（2026-10-20，官方团队署名）

二、解决什么问题

自回归解码是 LLM 推理的瓶颈：每生成一个 token 都要把整个模型权重过一遍。投机解码用一个小模型（drafter）先猜若干 token，再用大模型一次性并行验证，猜对的部分直接采纳，从而把"逐 token 串行"变成"批量并行"。

EAGLE-4 解决的是投机解码的三个老问题：

  1. draft tree 形状与负载脱节。低并发时猜深一点收益大，高并发时 batch 已经把 GPU 打满，多余的猜测纯属浪费。EAGLE-4 用实测成本动态定价每一轮，只在"累计概率收益 / 实测边际成本"超过阈值时才加深或加宽树。
  2. 跨硬件不可移植。同一套 --speculative-num-steps 在 B300 和 MI355X 上表现完全不同。EAGLE-4 把成本测量做进 harness，换硬件不用重调。
  3. 验证阶段浪费。EAGLE-4 保留 EAGLE-3 的"目标模型 hidden states + token embedding"输入方式，加入滑动窗口 draft layer、低秩 candidate head（只对候选 token 算全量 logits）和 append-only draft cache，减少 draft 本身的成本。

结果：README 报告在 Qwen3.8-27B 上单请求最高 3.42×（SGLang，4× B300），且回答与不开投机解码完全一致。

三、快速安装

3.1 硬性前置

  • Linux x86-64（AMD MI355X 走 ROCm 路线，用 Python 3.10）
  • Python 3.12（CUDA 路线；ROCm 路线必须是 3.10，不能用 3.12 替代）
  • NVIDIA GPU + CUDA 13 驱动
  • pip 安装还额外需要 CUDA toolkit（含 nvcc）+ C++ 编译器——官方文档明确写 "The driver alone is not enough"，kernel 在首次启动时编译
  • 一个环境对应一个引擎（每个引擎的 patch 版本不同，不能混装）

3.2 Docker（最省事，推荐先跑通）

docker run --gpus all --ipc host -p 127.0.0.1:30000:30000 \
  -e HF_HOME=/hf -v ~/.cache/huggingface:/hf \
  ghcr.io/eagle-hq/eagle-4-sglang:0.1.2 \
  sglang serve --model-path Qwen/Qwen3.8-27B --host 0.0.0.0 \
  --disable-overlap-schedule --speculative-algorithm EAGLE_HARNESS \
  --speculative-draft-model-path EAGLE-Corp/Qwen3.8-27B-EAGLE4 \
  --speculative-num-steps 12 --speculative-eagle-topk 4 \
  --speculative-num-draft-tokens 16 \
  --speculative-algorithm-config '{}'

首次启动会从 Hugging Face 下载 约 62 GB（Qwen3.8-27B + 其 EAGLE-4 draft）。

3.3 pip 安装（SGLang）

python3.12 -m venv .venv && source .venv/bin/activate
pip install "eagle-harness[sglang]" "sglang==0.5.23.dev252+eagle.5" \
  --extra-index-url https://eagle-hq.github.io/EAGLE-4/whl/cu130/ \
  --extra-index-url https://download.pytorch.org/whl/cu130 \
  --extra-index-url https://pypi.nvidia.com

三个 extra-index 的作用（官方表格）： - eagle-hq.github.io/EAGLE-4/whl/cu130/ — 打过补丁的引擎 wheel，带 +eagle.N 本地版本号，pip 只在你精确 pin 住该版本时才会选它 - download.pytorch.org/whl/cu130 — CUDA 13.0 的 PyTorch - pypi.nvidia.com — SGLang 引擎 pin 的 cuda-tile==1.6.0rc5，不加它 pip 会从源码编译该包

3.4 其他引擎的 pin（务必对齐版本）

引擎 关键 pin
SGLang eagle-harness[sglang] + sglang==0.5.23.dev252+eagle.5
vLLM eagle-harness[vllm] + vllm==0.32.0rc1.dev283+eagle.4
TokenSpeed eagle-harness[tokenspeed] + tokenspeed==0.1.1+eagle.5 + tokenspeed-scheduler==0.1.40+eagle.4 + tokenspeed-kernel==0.1.4+eagle.5

3.5 验证安装

eagle-harness-check   # 退出码 0 表示引擎钩子齐全；不启服务

⚠️ 官方明确：这只检查钩子，真正的验证是发一次请求。

四、核心用法

4.1 最小可跑路径

# 1) 启动服务（pip 装完后）
sglang serve --model-path Qwen/Qwen3.8-27B \
  --speculative-algorithm EAGLE_HARNESS \
  --speculative-draft-model-path EAGLE-Corp/Qwen3.8-27B-EAGLE4

# 2) 另开终端发请求
curl http://localhost:30000/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{"model":"Qwen/Qwen3.8-27B","messages":[{"role":"user","content":"Explain how a hash table works."}],"max_tokens":256}'

等日志出现 The server is fired up and ready to roll!。前几个请求会编译 kernel 并播种 live cost，发几个再测速。

4.2 关键参数

参数 默认 说明
--speculative-num-steps 12 draft tree 深度
--speculative-eagle-topk 4 每步候选数
--speculative-num-draft-tokens 16 每轮验证 token 上限
--speculative-algorithm-config {} 额外配置，高负载 recipe 里用 {"mode":"serve"}
--speculative-draft-model-quantization — benchmark recipe 用 unquant
--speculative-attention-mode — benchmark recipe 用 prefill

这些默认需要 eagle-harness 0.1.1 或更新。

4.3 官方 benchmark 测量配方（SGLang TP4）

README 的加速比就是用这条命令测的，要和它对比就得用同样的配方：

export TOKENIZERS_PARALLELISM=false OMP_NUM_THREADS=4
export SGLANG_ALLOW_OVERWRITE_LONGER_CONTEXT_LEN=1 SGLANG_TIMEOUT_KEEP_ALIVE=3600
sglang serve --model-path Qwen/Qwen3.8-27B --tp-size 4 --dtype bfloat16 \
  --trust-remote-code --attention-backend flashinfer --page-size 1 \
  --max-running-requests 32 --cuda-graph-max-bs-decode 32 \
  --disable-overlap-schedule --cuda-graph-backend-decode full \
  --mem-fraction-static 0.75 --context-length 196608 --max-total-tokens 196608 \
  --chunked-prefill-size 16384 --mamba-ssm-dtype bfloat16 --disable-radix-cache \
  --reasoning-parser qwen3 --random-seed 721 --skip-server-warmup \
  --speculative-algorithm EAGLE_HARNESS \
  --speculative-draft-model-path EAGLE-Corp/Qwen3.8-27B-EAGLE4 \
  --speculative-draft-model-quantization unquant --speculative-draft-attention-backend flashinfer \
  --speculative-attention-mode prefill --speculative-num-steps 12 \
  --speculative-eagle-topk 4 --speculative-num-draft-tokens 16 \
  --speculative-algorithm-config '{"mode":"serve"}'

注意 --disable-radix-cache 在这条测量配方里是开的，但 README 的快速开始 Docker 命令里没开——这不是笔误，原因见下面的坑。

4.4 高负载 recipe（4 卡、几十到几百并发）

sglang serve --model-path Qwen/Qwen3.8-27B --tp-size 4 --dtype bfloat16 \
  --trust-remote-code --attention-backend flashinfer --page-size 1 \
  --max-running-requests 512 --cuda-graph-max-bs-decode 512 \
  --mem-fraction-static 0.70 --context-length 32768 \
  --chunked-prefill-size 16384 --mamba-ssm-dtype bfloat16 --disable-radix-cache \
  --random-seed 721 --skip-server-warmup \
  --speculative-algorithm EAGLE_HARNESS \
  --speculative-draft-model-path EAGLE-Corp/Qwen3.8-27B-EAGLE4 \
  --speculative-draft-model-quantization unquant --speculative-draft-attention-backend flashinfer \
  --speculative-attention-mode prefill --speculative-num-steps 12 \
  --speculative-eagle-topk 4 --speculative-num-draft-tokens 16 \
  --speculative-algorithm-config '{"mode":"serve"}'

它把 running cap 和 decode graph limit 提到 512，关掉 radix cache，从而让 EAGLE-4 在"投机反而更慢"的负载下能退回普通解码。

五、典型适用场景

  • 自建推理服务、单请求低并发：收益最大。SGLang TP4 单请求 3.42×，vLLM 2.83×，TokenSpeed 3.09×（均为 4× B300、Qwen3.8-27B、temperature 0、SPEED-Bench client）。
  • 中等并发（8 路）：仍有 1.7×–2.1×，性价比区间。
  • 高并发（64+）：必须用高负载 recipe，否则会变慢（见坑 3）。
  • AMD MI355X 单卡：SGLang ROCm 路线，8 并发 2.07×、32 并发 1.56×。
  • 需要 lossless：输出分布与目标模型一致——合规、评测场景友好。
  • 模型已训好 EAGLE-4 draft：仓库提供 draft 权重（如 EAGLE-Corp/Qwen3.8-27B-EAGLE4）。没有 draft 权重的目标模型用不了，这是硬门槛。

六、坑与注意

  1. 驱动 ≠ toolkit。pip 装路线必须另装 CUDA toolkit 和 C++ 编译器，否则首次启动编译 kernel 会失败。Docker 镜像自带构建工具，是省事的路。
  2. 引擎 patch 版本必须精确 pin。patched wheel 带 +eagle.N 本地版本，pip 只在精确 pin 时才选中它。写成 sglang>=0.5.23 会装到官方版本，然后启动时发现没有 EAGLE-4 钩子。
  3. ⚠️ 高并发下默认命令比不开投机还慢——这是最重要的一条。官方实测：README 快速开始那条 SGLang 命令在单卡 concurrency 64 时只有无投机解码的 0.73×，256 时 0.59×；--tp-size 4 时 64 并发 0.80×、128 并发 0.48×、256 并发 0.37×、512 并发 0.32×。三个原因：(a) radix cache 默认开，混合模型要跟踪 prefix-cache 状态，batch 切回普通解码时这部分状态带不过去，于是每次负载都投机；(b) 默认 tree 把 4 卡服务器的 running 请求数限制在 32，而普通解码能接几百；(c) 单卡上引擎要为每个已接纳请求预留 verify state，投机服务器接纳量约为普通解码的四分之一。高并发务必用高负载 recipe。
  4. 单卡不支持高负载。单卡 + --disable-radix-cache 会在 draft graph capture 阶段直接停住——单卡必须保留 radix cache。high-load recipe 是给 4 卡用的；服务器日志建议加 --disable-radix-cache 的那句话只对 4 卡成立。
  5. vLLM 和 TokenSpeed 尚不能在高负载退回普通解码。并发超过 64 时，它们可能比不开投机更慢——这类负载目前就关掉投机。TokenSpeed 更没有"跳过 draft"的钩子，所以 EAGLE-4 在 TokenSpeed 上无法退回。
  6. TokenSpeed 单卡要加 --disable-kvstore。默认 TokenSpeed 会加一层两倍于 GPU KV cache 大小的宿主 KV cache，单卡机器 pin 不住这个内存量。
  7. TokenSpeed 只支持 CUDA。AMD 上请用 SGLang ROCm。
  8. vLLM 拒绝 min_p 与 logit_bias（配合投机解码时）。vLLM 的 tree 验证还要求未量化的 KV cache。
  9. 不能传图片。SGLang 明确 images are refused。
  10. 确定性模式会让加速归零。加 --enable-deterministic-inference 后，512 并发下 512/512 prompt 逐 token 完全一致（默认 kernel 不是 batch-invariant）；但该模式下 EAGLE-4 在 64 和 512 并发都退回普通解码，没有加速，且吞吐更低。
  11. 结构化输出与工具调用需要引擎的 parser。vLLM 的 tree batch 带 grammar 约束时，batch 里每个请求每轮只推进一个 token，必须检查 finish reason 并校验输出。
  12. 首次启动会慢。要编译 kernel 并实测 live cost，64/128 并发下最多损失 5%。live cost 缓存在 ~/.cache/eagle-harness/costs（按 GPU、TP size、模型对、引擎、dtype 维度），重启复用。换硬件/模型/TP 尺寸则首次启动要重新搜索。
  13. 版本浮动风险。本文核验时 eagle-harness 最新为 0.1.2（Docker 镜像 tag 0.1.2，支持矩阵当前版本为 0.1.2）。⚠️ 具体 pin 字符串请以 docs/install.md 与 docs/release.env 的当前内容为准，本文引用的版本号在快速迭代下可能已过期。
  14. 许可不是 OSI 开源。README 明确写着 "Eagle 4 is source-available software, not OSI-approved open-source software"。商业使用有 2000 万美元（连续 12 个月累计营收）门槛，超过需另行签署商业授权；竞争对手的商用需要单独的书面商业许可，与营收无关。贡献需接受 Contribution License Terms PDF。

七、与同类对比

方案 定位 对比 EAGLE-4
EAGLE-1/2/3 同系列前代 EAGLE-4 增加了硬件感知的 tree 形状控制；前代 tree 形状需手调
Medusa / Lookahead 无需训练 drafter 的投机方案 Medusa 不需要额外 draft 权重（用多个头），EAGLE-4 需要训好的 EAGLE-4 draft
n-gram / prompt lookup 零训练、靠检索复用 简单便宜，但命中率依赖语料重复度；EAGLE-4 是学习型 drafter
SGLang / vLLM 原生投机解码 引擎自带 EAGLE2/3 支持 引擎原生版 tree 形状固定、无 live-cost 定价；EAGLE-4 需打补丁的引擎 wheel，换来自适应能力
TorchSpec + TokenSpeed 训练 + 服务的另一路径 LightSeek 博客称 TokenSpeed 侧 EAGLE-4 支持动态树、链、sampled tree 与成本测量工具链；EAGLE-4 官方仓库也把 TokenSpeed 作为一等引擎收录

官方博客给出的另一些数字（与本仓库 support matrix 不同口径，属官方自测）：单请求 961.6 tok/s（4× B300）、Nemotron 3.5 Super VL 单请求 2.74× / 512 并发 1.69×。

八、一句话结论

EAGLE-4 是目前把投机解码"做成生产基础设施"而不是"跑分技巧"的少数方案——它的 live-cost 定价和"投机不如普通解码就退回去"的自适应逻辑是真正可运营的设计；但代价是必须是 CUDA 13 + Python 3.12 + 打补丁引擎 + 有预训 draft 权重的狭窄适用面，以及 2000 万美元营收门槛的 source-available 许可。建议：做自建 LLM 推理服务、有 B300/MI355X 硬件、单请求或中低并发负载，值得上；只是想在现有 vLLM/SGLang 上加个多路投机、或者追求 Apache-2.0 友好许可，先别动。

九、来源清单

  • GitHub README（eagle-hq/EAGLE-4，main 分支）— 已 fetch，2026-10-24
  • docs/install.md（front-matter last_verified: 2026-10-21）— 已 fetch
  • docs/quickstart-sglang.md（last_verified: 2026-10-23）— 已 fetch
  • docs/known-limits.md（last_verified: 2026-10-23）— 已 fetch
  • docs/support-matrix.md（last_verified: 2026-10-23）— 已 fetch
  • 官方博客 https://blog.eagle.ai/blog/introducing-eagle-4（2026-10-20）— 经 web_search 摘要，未逐字抓取正文
  • LightSeek 博客 https://lightseek.org/blog/eagle-4.html — 经 web_search 摘要（TokenSpeed 侧数据）
  • AICoder 新闻页 — 经 web_search 摘要（961.6 tok/s 与许可说明）
  • 仓库卡 organized/repo_cards/4603-eagle-hq-eagle-4.md

十、不确定与待核项

  • ⚠️ 顶会状态未确认：引用块标 Preprint，本次未查到顶会接收记录。README 提到 "Figure 1(a) of the EAGLE-4 paper"，论文正式版未取得。
  • ⚠️ 仓库 star 数不一致：仓库卡记 957 stars，而 web_search 抓到的 GitHub 页面快照显示 31 stars。两者差异极大，可能一方是缓存/镜像数据。引用 star 数前建议直接看 GitHub 页面。本文正文未依赖 star 数。
  • ⚠️ 版本号浮动：本文写作时 eagle-harness 为 0.1.2，引擎 pin 为 sglang==0.5.23.dev252+eagle.5 / vllm==0.32.0rc1.dev283+eagle.4 / tokenspeed==0.1.1+eagle.5。请以 docs/install.md 当前内容为准。
  • ⚠️ commit hash 未记录：本次未抓取仓库 HEAD commit sha，文章未标注对应 commit。EAGLE-4 迭代很快（最近提交 2026-10-24），建议生产使用前记录 git rev-parse HEAD。
  • ⚠️ backbone / draft 权重清单不完整：官方仅在 support matrix 中列出 Qwen3.8-27B 与 Nemotron 3.5 Super 的测量结果，其他可用模型需查 HF 仓库 EAGLE-Corp/*。待补：完整的「目标模型 → EAGLE-4 draft 权重」映射表。
  • ⚠️ overhead 数字：本文引用了 README 与 support matrix 的 tokens/s 对照，但未跑出「draft 模型本身的开销占目标模型多少比例」的独立数字——仓库未以该口径披露。
  • ⚠️ AMD ROCm 路线需 clone 仓库：install.md 明确要求 git clone 以获得 lock 文件和 docs/release.env，不能纯 pip 安装。本文引用该流程时未实际执行。
  • ⚠️ Qwen3.8-27B 权重：本文按官方 README 原文引用 Qwen/Qwen3.8-27B 与 EAGLE-Corp/Qwen3.8-27B-EAGLE4，未去 Hugging Face 核实这两个仓库当前是否存在。