EAGLE3

EAGLE3#

Eagle3是目前最常用、加速效果最好的投机采样算法。本项目包括Eagle3的训练以及benchmark测试，并开源了Qwen3和Hunyuan系列的Eagle3权重。

我们训练的Qwen3系列Eagle3模型的表现可以参见基准测试benchmarks，其中全部数据都是在单张GPU上使用vLLM推理获得。

1. 数据生成#

数据生成包括：1）为目标模型生成采样数据，2）为Eagle3模型离线生成目标模型的hidden states。

1.1 数据组织形式#

所有数据需保存在jsonl文件中，训练数据格式可参考:

数据示例:

{"id": "0", "conversations": [{"role": "user", "content": "xxx"}, {"role": "assistant", "content": "xxx"}]}

典型字段意义如下：
- id: 对话唯一标识

1.2 为目标模型生成采样数据#

生成采样数据为可选项，当有足够数量以及足够质量的目标模型SFT数据时，此步可略过。当训练数据和目标模型不配套时，则需要为目标模型重新采样生成数据。

步骤1：启动vLLM server

首先需要启动vLLM server来提供模型推理服务：

bash scripts/speculative/run_vllm_server.sh

server配置说明：

该脚本会启动目标基础模型的vLLM推理服务
确保服务器成功启动后再进行下一步数据生成
可以通过修改脚本中的参数来调整vLLM server配置（如vLLM启动参数、GPU数量等），来适应不同的目标模型

步骤2：生成采样数据

vLLM server启动后，使用 scripts/speculative/generate_data_for_target_model.sh 脚本生成训练数据：

bash scripts/speculative/generate_data_for_target_model.sh

脚本功能说明：

通过vLLM server调用目标基础模型对输入数据进行采样
生成 .jsonl 格式的训练数据集
数据将用于后续Eagle模型的在线训练

脚本参数说明：

在使用前，需要在脚本中配置以下参数：

DATA_NAME_OR_PATH: 输入数据集的HF名称或本地路径
OUTPUT_DIR: 生成的数据集输出路径
DATA_FORMAT: 输入数据集的格式（sharegpt|ultrachat）
DATA_SHARD_SIZE: 生成数据集的切分子集大小
BASE_PORT: vLLM server的端口号

注意事项：

确保vLLM服务器已成功启动并正常运行
数据生成过程可能需要较长时间，取决于样本数量和模型规模

1.3 为Eagle3模型生成hidden states#

目前仅支持以HF为后端生成hidden states，调用脚本如下：

# For LLMs
bash scripts/speculative/generate_hidden_for_draft_model.sh
# For VLMs
bash scripts/speculative/generate_vlm_hidden_for_draft_model.sh

脚本参数说明：

在使用前，需要在脚本中配置以下参数：

DATASET_PATH: 输入数据集的HF名称或本地路径
MODEL_NAME: 目标模型的HF名称或本地路径
TARGET_BACKEND: 目标模型后端，目前仅支持HF
MODEL_MAX_LENGTH: 生成数据的上下文长度
CHAT_TEMPLATE_TYPE: 目标模型的目标类型，目前支持qwen3/qwen2.5/hunyuan/hunyuan-7b
OUTPUT_DIR: 生成的数据集输出路径

2. 训练Eagle3模型#

目前支持在线训练和离线训练两种模式：在线训练适合显存足够、目标模型不大、训练上下文长度不要求极长的场景，离线训练适合大尺寸目标模型、磁盘空间足够、长上下文训练场景。

2.1 在线训练#

使用下面的脚本进行Eagle3模型的在线训练：

# For LLMs
bash scripts/speculative/train_eagle3_online.sh
# For VLMs
bash scripts/speculative/train_eagle3_vlm_online.sh

脚本参数说明：

在使用前，需要在脚本中配置以下参数：

TARGET_MODEL_NAME_OR_PATH: 目标模型的HF名称或本地名称
DRAFT_MODEL_CONFIG_PATH: 草稿模型的config路径
TRAIN_DATA_PATH: 训练数据路径
EVAL_DATA_PATH: 验证数据路径
OUTPUT_DIR: Eagle3模型输出路径
MODEL_MAX_LENGTH: 训练数据的最大长度
CHAT_TEMPLATE_TYPE: 目标模型的数据模板类型

2.2 离线训练#

在离线训练前，必须要完成1.2 为Eagle3模型生成hidden states。使用下面的脚本进行Eagle3模型的离线训练：

# For LLMs
bash scripts/speculative/train_eagle3_offline.sh
# For VLMs
bash scripts/speculative/train_eagle3_vlm_offline.sh

脚本参数说明：

在使用前，需要在脚本中配置以下参数：

TARGET_MODEL_NAME_OR_PATH: 目标模型的HF名称或本地名称
DRAFT_MODEL_CONFIG_PATH: 草稿模型的config路径
TRAIN_DATA_PATH: 训练数据路径,.jsonl格式
TRAIN_HIDDEN_PATH: 训练hidden states数据路径
EVAL_HIDDEN_PATH: 验证hidden states数据路径
OUTPUT_DIR: Eagle3模型输出路径
MODEL_MAX_LENGTH: 训练数据的最大长度
CHAT_TEMPLATE_TYPE: 目标模型的数据模板类型
LM_HEAD_KEY: 目标模型lm head的weight key名称，可以在model.safetensors.index.json中查看，默认为lm_head.weight时可不指定这个参数。当为model.embed_tokens.weight时，需要指定。
RUN_NAME: 当report_to设为wand时，可以指定该参数设置wand中的run name。

3. 基准测试#

AngelSlim提供了HF和vLLM两种backend的Eagle3基准测试脚本，用于评估投机采样的性能提升。

3.1 HF基准测试#

3.1.1 基本用法#

使用 tools/spec_benchmark.py 脚本进行投机采样基准测试：

python3 tools/spec_benchmark.py \
    --base-model-path ${BASE_MODEL_PATH} \
    --eagle-model-path ${EAGLE_MODEL_PATH} \
    --model-id ${MODEL_ID} \
    --mode both

3.1.2 参数说明#

模型配置参数：

--base-model-path: 基础模型路径（必需）
--eagle-model-path: Eagle辅助模型路径（必需）
--model-id: 模型标识符（必需）

基准测试配置：

--bench-name: 基准数据集名称，默认为 mt_bench, 可选【alpaca,gsm8k,humaneval,mt_bench】
--mode: 执行模式，可选 eagle（仅投机采样）、baseline（仅基线）、both（两者都执行），默认为 both
--output-dir: 结果输出目录

生成参数：

--temperature: 采样温度，默认为 1.0
--max-new-token: 最大生成token数，默认为 1024
--total-token: 草稿树中的总节点数，默认为 60
--depth: 树深度，默认为 5
--top-k: Top-k采样，默认为 10

硬件配置：

--num-gpus-per-model: 每个模型使用的GPU数量，默认为 1
--num-gpus-total: 总GPU数量，默认为 1
--max-gpu-memory: 每个GPU的最大内存限制

其他设置：

--seed: 随机种子，默认为 42
--question-begin: 问题起始索引（用于调试）
--question-end: 问题结束索引（用于调试）
--no-metrics: 跳过自动指标计算

3.1.3 使用示例#

完整基准测试（推荐）：

python3 tools/spec_benchmark.py \
    --base-model-path /path/to/base/model \
    --eagle-model-path /path/to/eagle/model \
    --model-id qwen3-8b \
    --mode both \
    --output-dir ./results \
    --max-new-token 512 \
    --temperature 0.0

仅运行投机采样：

python3 tools/spec_benchmark.py \
    --base-model-path /path/to/base/model \
    --eagle-model-path /path/to/eagle/model \
    --model-id qwen3-8b \
    --mode eagle

多GPU配置：

python3 tools/spec_benchmark.py \
    --base-model-path /path/to/base/model \
    --eagle-model-path /path/to/eagle/model \
    --model-id qwen3-8b \
    --num-gpus-per-model 1 \
    --num-gpus-total 8

3.1.4 性能报告#

运行完成后，工具会自动生成性能报告，包括：

投机采样与基线模型的性能对比
加速比统计
生成质量指标（如果启用）

结果将保存在指定的输出目录中，便于后续分析和比较。

3.2 vLLM基准测试#

3.2.1 基本用法#

使用 tools/vllm_spec_benchmark.py 脚本进行投机采样基准测试：

python3 tools/vllm_spec_benchmark.py \
    --target_model ${TARGET_MODEL_PATH} \
    --draft_model ${EAGLE_MODEL_PATH} \
    --dataset "gsm8k" \
    --output_file ${OUTPUT_FILE} \
    --method eagle3 \
    --output_len 1024 \
    --max_num_seqs ${BATCH_SIZE}

3.2.2 参数说明#

模型配置参数：

--target_model: 目标模型的HF名称或本地路径
--draft_model: 草稿模型（Eagle模型）的HF名称或本地路径

数据集配置：

--dataset: 基准数据集名称或本地JSONL文件路径，默认为 gsm8k。支持逗号分隔指定多个数据集（如 mt_bench,gsm8k,/path/to/local/question.jsonl）。如果路径为已存在的文件则直接加载，否则视为 dataset/ 目录下的benchmark名称
--num_prompts: 从数据集中加载的prompt数量，默认为 80

投机采样配置：

--method: 投机采样方法，可选 eagle、eagle3、ngram、mtp、ar（无投机采样的基线），默认为 eagle3
--num_spec_tokens: 投机采样token数量，默认为 2
--prompt_lookup_max: ngram方法的最大查找长度，默认为 5
--prompt_lookup_min: ngram方法的最小查找长度，默认为 2

生成参数：

--temp: 采样温度，默认为 0
--top_p: Top-p采样，默认为 1.0
--top_k: Top-k采样，默认为 -1（不启用）
--output_len: 最大生成token数，默认为 1024

硬件与引擎配置：

--tp: tensor parallel大小，默认为 1
--max_model_len: 模型最大上下文长度，默认为 16384
--max_num_seqs: 最大并发序列数（batch size），默认为 1
--enforce_eager: 启用eager模式（禁用CUDA graph）
--enable_chunked_prefill: 启用chunked prefill

其他设置：

--seed: 随机种子，默认为 42
--output_file: 结果输出文件路径（jsonl格式）
--print_output: 打印生成的文本内容
--test: 测试模式

3.2.3 使用示例#

单数据集测试：

python3 tools/vllm_spec_benchmark.py \
    --target_model /path/to/base/model \
    --draft_model /path/to/eagle/model \
    --dataset "gsm8k" \
    --output_file ./results/benchmark_stats.jsonl \
    --method eagle3 \
    --output_len 1024 \
    --max_num_seqs 1

多数据集测试（逗号分隔，支持混合使用benchmark名称和本地文件路径）：

python3 tools/vllm_spec_benchmark.py \
    --target_model /path/to/base/model \
    --draft_model /path/to/eagle/model \
    --dataset "mt_bench,gsm8k,/path/to/local/question.jsonl" \
    --output_file ./results/benchmark_stats.jsonl \
    --method eagle3 \
    --output_len 1024 \
    --max_num_seqs 1

使用基线模式（无投机采样）进行对比：

python3 tools/vllm_spec_benchmark.py \
    --target_model /path/to/base/model \
    --dataset "gsm8k" \
    --method ar \
    --output_len 1024

多GPU配置：

python3 tools/vllm_spec_benchmark.py \
    --target_model /path/to/base/model \
    --draft_model /path/to/eagle/model \
    --dataset "gsm8k" \
    --method eagle3 \
    --tp 4 \
    --output_len 1024

3.2.4 性能报告#

运行完成后，工具会自动生成性能报告，包括：

输出吞吐量（tokens/s）
请求吞吐量（requests/s）
平均每个样本的耗时
投机采样的平均接受长度（mean acceptance length）
各token位置的接受率

当指定多个数据集时，还会额外输出所有数据集的平均统计结果。所有结果将以jsonl格式保存在指定的输出文件中，便于后续分析和比较。

完整的vLLM benchmark结果可见Benchmark。