deepseek-ai/DeepSpec · 上手攻略

  • 仓库：deepseek-ai/DeepSpec
  • 链接：https://github.com/deepseek-ai/DeepSpec
  • 分类：llm-infra · inference-optimization · speculative-decoding
  • 作者：Tom
  • 更新：2026-07-05

这是什么

DeepSpec 是 DeepSeek 于 2026 年 6 月 26 日 开源的全栈代码库，用于训练和评估推测解码（Speculative Decoding）的 Draft 模型。MIT 许可证，Stars 6k+。

推测解码的核心逻辑：用一个小而快的 Draft 模型批量生成候选 token，再由目标大模型并行验证——被接受的 token 直接采纳，被拒绝的才需要大模型重新解码。这样每个用户请求的首 token 延迟和生成速度都能显著提升，同时保持输出质量不变。

DeepSpec 实现了 三个 主流推测解码算法： - DSpark（DeepSeek 自研，V4-Flash 上实现 60–85% 生成加速，V4-Pro 上 57–78%） - DFlash（来自 arXiv:2602.06036，MIT） - Eagle3（来自 arXiv:2503.01840，Apache-2.0，基于 SpecForge 框架）

注意：DeepSpec 不是模型权重，不是 API 服务，是训练和评测的工具链。你用它为特定的 target 模型（Qwen3、Gemma 等）训练定制化的 Draft 模型。

解决什么问题

LLM 推理有两个核心指标：延迟（首 token 多快出来）和吞吐量（每秒能处理多少请求）。两者在自托管场景下往往相互制约——用大模型直接生成，延迟低但吞吐差；用批处理，吞吐上去了但延迟爆炸。

推测解码用 Draft 模型做投件（speculate），大模型做验件（verify），两全其美： - 用户感知延迟大幅下降（Draft 模型先行生成，不用等大模型逐 token） - 吞吐量反而可能提升（接受率高时，大模型只做并行验证，开销接近 O(1)）

DeepSpec 把这个过程做成可复现的完整 pipeline：数据准备 → 训练 → 评测，让你不用从零搭轮子。

快速安装

# 克隆仓库
git clone https://github.com/deepseek-ai/DeepSpec.git
cd DeepSpec

# 安装 Python 依赖
python -m pip install -r requirements.txt

# 注意：数据准备阶段需要 inference engine（SGLang/vLLM/TGI 任选）
# 推荐 SGLang，安装方式：
pip install "sglang[all]"

# 下载训练数据（mlabonne/open-perfectblend）
python scripts/data/download_and_split.py \
 --dataset-name mlabonne/open-perfectblend \
 --test-size 0.05 \
 --train-output-path train_datasets/perfectblend_train.jsonl \
 --test-output-dir eval_datasets \
 --skip-existing

硬件要求

  • 默认配置：单节点 8 GPU（Qwen3-4B 为例）
  • GPU 不足时：减少 CUDA_VISIBLE_DEVICES 中的 GPU 数量，脚本会自动适配

核心用法

三阶段 Pipeline

阶段 1：数据准备

用 target 模型重新生成 answer，构建 target cache：

# 启动 SGLang 服务器（默认 8 workers，端口 30000–30007）
bash scripts/data/launch_sglang_server.sh

# 重新生成训练 answer
python scripts/data/generate_train_data.py \
 --model Qwen/Qwen3-4B \
 --server-address 127.0.0.1:30000 \
 ...（其他 7 个端口）\
 --concurrency 32 \
 --temperature 0.7 \
 --top-p 0.8 \
 --top-k 20 \
 --max-tokens 4096 \
 --disable-thinking \
 --resume \
 --input-file-path train_datasets/perfectblend_train.jsonl \
 --output-file-path train_datasets/qwen3_4b/perfectblend_train_regen.jsonl

# 预计算 target cache（⚠️ 默认约 38 TB！）
python scripts/data/prepare_target_cache.py \
 --config config/dspark/dspark_qwen3_4b.py \
 --train-data-path train_datasets/qwen3_4b/perfectblend_train_regen.jsonl \
 --output-dir ${HOME}/.cache/deepspec/qwen3_4b_target_cache \
 --local-batch-size 16

⚠️ 存储警告：target cache 存储训练集中每个 token 的 hidden state，默认 Qwen3-4B 配置约需 38 TB 磁盘空间。若存储不足，可减少训练集规模或减少 config 中 target_layer_ids 捕获的层数。

阶段 2：训练 Draft 模型

# 选择算法和 target 模型（修改 config_path 指向对应配置文件）
# 可用算法配置：
#   config/dspark/dspark_qwen3_4b.py
#   config/dflash/dflash_qwen3_4b.py
#   config/eagle3/eagle3_qwen3_4b.py

bash scripts/train/train.sh \
 --config-path config/dspark/dspark_qwen3_4b.py \
 --target-cache-dir ${HOME}/.cache/deepspec/qwen3_4b_target_cache

# checkpoint 输出到：~/checkpoints/<project_name>/<exp_name>/step_*

阶段 3：评测

# 评测支持以下 benchmark：
# gsm8k, math500, aime25, humaneval, mbpp,
# livecodebench, mt-bench, alpaca, arena-hard-v2

bash scripts/eval/eval.sh \
 --target-name-or-path Qwen/Qwen3-4B \
 --draft-name-or-path ~/checkpoints/deepspec/dspark_block7_qwen3_4b/step_latest

使用已发布 Checkpoint（跳过训练）

若只想评测不想训练，直接用 DeepSeek 官方放出的 checkpoint：

算法 Qwen3-4B Qwen3-8B Qwen3-14B Gemma-4-12B
DSpark deepseek-ai/dspark_qwen3_4b_block7 deepseek-ai/dspark_qwen3_8b_block7 deepseek-ai/dspark_qwen3_14b_block7 deepseek-ai/dspark_gemma4_12b_block7
DFlash deepseek-ai/dflash_qwen3_4b_block7 deepseek-ai/dflash_qwen3_8b_block7 deepseek-ai/dflash_qwen3_14b_block7 deepseek-ai/dflash_gemma4_12b_block7
Eagle3 deepseek-ai/eagle3_qwen3_4b_ttt7 deepseek-ai/eagle3_qwen3_8b_ttt7 deepseek-ai/eagle3_qwen3_14b_ttt7 deepseek-ai/eagle3_gemma4_12b_ttt7 
# 直接用 HF checkpoint 评测
bash scripts/eval/eval.sh \
 --target-name-or-path Qwen/Qwen3-4B \
 --draft-name-or-path deepseek-ai/dspark_qwen3_4b_block7

典型适用场景

  1. 自托管 LLM 推理加速：自己部署 Qwen3 或 Gemma 系列，想降低用户感知延迟
  2. 评测新型推测解码算法：把新算法封装成 config，快速在标准 benchmark 上对比
  3. 领域定制 Draft 模型：用你自己的领域数据微调 Draft，通用评测只是起点（README 明确建议：domain-specific use 需要重新微调）
  4. 推理成本优化研究：分析不同算法在不同模型、不同 benchmark 上的接受率曲线

坑与注意

坑 说明
38 TB 存储门槛 默认 target cache 约 38 TB，这是最大门槛。小数据集测试建议先缩减规模
非 thinking 模式训练 所有 released checkpoint 用 target 模型的 non-thinking 模式数据训练，若 target 要跑 thinking mode（如 R1 类模型），需重新训练
仅支持 Qwen3 / Gemma 当前 repo 只支持 Qwen3 系列和 Google Gemma-4-12B-it，不支持 Llama/Mistral 等
SGLang 不在 requirements.txt 数据准备阶段需要 inference engine，需单独安装 pip install "sglang[all]"
DeepSeek 内部模型（V4-Flash/Pro）的结果更漂亮 DSpark 在 DeepSeek 自家模型上测得 60–85% 加速，在 Qwen3/Gemma 上的数据未公布，可能有明显差距
checkpoint 与 setup 必须对齐才能复现 README 明确要求：引用结果时 setup 必须与 repo 训练配置对齐，否则 comparison 无意义

与同类对比

项目 类型 核心差异
SpecForge（sgl-project） 训练框架 DeepSpec 的 Eagle3 实现参考了 SpecForge；SpecForge 更通用但 DeepSpec 更专注评测标准化
vLLM Speculative Decoding 推理引擎内置 vLLM 自带推测解码，但黑箱不好调；DeepSpec 是可定制训练 pipeline
MLC-LLM 推理优化 侧重端侧/移动端部署；DeepSpec 面向服务器端数据中心
Distbelief 分布式训练 通用；DeepSpec 专注射推解码 draft 模型训练
DeepSpec 全栈训练+评测 三个算法统一框架 + 标准评测集 + 官方 checkpoint，是目前最完整的推测解码开源工具链

一句话推荐结论

如果你在自托管 Qwen3 或 Gemma，想通过推测解码降低推理延迟，DeepSpec 是目前最完整的开源工具链——三种算法、完整数据 pipeline、标准评测集和官方 checkpoint，拿来评测或微调都行；但如果你的目标模型是 Llama/Mistral 或需要 thinking mode，短期内还不太适合。