00 · DeepSpec 项目总览与阅读指南

本篇是整套代码分析文档的"总"开篇。DeepSpec 是 DeepSeek 联合北京大学于 2026 年 6 月开源的推测解码（Speculative Decoding）draft 模型全栈训练/评测代码库，随论文《DSpark: Confidence-Scheduled Speculative Decoding with Semi-Autoregressive Generation》（[DSpark_paper.pdf](file:///workspace/DSpark_paper.pdf) / GitHub ）一同发布，MIT 协议。本系列文档以"总分总"结构组织：本篇给出项目地图 → 01–09 分模块深入 → 10 总结闭环。

---

一、DeepSpec 是什么

DeepSpec 不是一个推理引擎，而是为推测解码训练并评估 draft（草稿）模型的全栈框架。它的输入是目标模型（target，例如 Qwen/Qwen3-4B）的 prompt 与重新生成的回答，输出是可直接在生产推理引擎上做 speculative decoding 的 draft 模型权重。

仓库目前内置三种 draft 算法：

算法	来源	范式	本仓库角色
DSpark	本仓库自有论文	半自回归（并行 backbone + 串行 Markov/RNN head + confidence head）	主角，论文核心贡献
DFlash	arxiv 2602.06036	纯并行 draft	DSpark 的退化配置（关闭 Markov + confidence）
Eagle3	arxiv 2503.01840，代码改编自 SpecForge	自回归 + Test-Time Training (TTT)	对照基线

支持 4 个 target 模型：Qwen/Qwen3-{4B,8B,14B}、google/gemma-4-12B-it。

DeepSpec 已部署于 DeepSeek-V4-Flash / V4-Pro 线上服务，在同等系统总吞吐规模下，V4-Flash 单用户生成速度提升 60%–85%，V4-Pro 提升 57%–78%，高并发场景有效吞吐最高 4×（[论文 Section 5](file:///workspace/DSpark_paper.pdf)）。

---

二、项目全景图

图说明： 全景图按"数据 → 训练 → 评测"三阶段顺序绘制，虚线表示 config/ 目录下三种算法配置驱动训练阶段。target cache（约 38TB）是数据阶段产物、训练阶段输入；step_latest checkpoint 是训练阶段产物、评测阶段输入。算法选择通过 --config config/<algo>/<algo>_<target>.py 切换，三算法共用同一套 trainer/evaluator 基类基础设施。

---

三、仓库目录速览

路径	作用	文档
train.py / eval.py	入口脚本	01 架构
config/{dspark,dflash,eagle3}/	12 个算法×target 配置	01 架构
deepspec/modeling/dspark/	DSpark 模型 + Markov head + loss	03 DSpark
deepspec/modeling/eagle3/	Eagle3 模型 + Triton 融合 loss	04 Eagle3
deepspec/data/	target cache + jsonl + parser + prefetcher	05 数据管道
deepspec/trainer/	BaseTrainer + FSDP + ckpt manager	06 训练框架
deepspec/eval/	BaseEvaluator + 拒绝采样 + 校准	07 评测系统
deepspec/utils/	config/distributed/io/metrics/optim/sampling/logger	01 架构
scripts/{train,eval,data}/	shell 编排 + 数据准备脚本	05 数据管道 / 09 使用指南
eval_datasets/	9 个评测集 JSONL	08 实验复现
DSpark_paper.pdf	DSpark 论文	08 实验复现

3.1 模块依赖关系图

图说明： 模块依赖图按"入口 → 配置 → 核心库 → 外部依赖"四层绘制。train.py 与 eval.py 通过 --config 读取算法配置后路由到对应 trainer/evaluator；deepspec/ 核心库内部 modeling 依赖 HuggingFace Transformers 的 Qwen3/Gemma4 backbone，data 依赖 sglang 重生成回答，trainer 依赖 torch.distributed 的 FSDP。三算法共用 BaseTrainer/BaseEvaluator 抽象，新增算法只需在 modeling + config 两处扩展。

---

四、阅读路线图

根据目标选择对应路径：

路径 A · 速读（10 分钟了解全貌）

1. 本篇 → 2. 01 整体架构（前两节）→ 3. 10 总结

路径 B · 工程师上手（接入自己的 target 模型）

1. 本篇 → 2. 01 整体架构 → 3. 05 数据管道 → 4. 06 训练框架 → 5. 09 使用指南

路径 C · 研究者理解原理

1. 本篇 → 2. 02 核心原理 → 3. 03 DSpark 建模 → 4. 04 Eagle3 建模 → 5. 07 评测系统

路径 D · 复现论文实验（重点）

1. 本篇 → 2. 02 核心原理 → 3. 03 DSpark 建模 → 4. 08 实验复现（重点篇，按论文 Section 4–5 逐节对照）→ 5. 09 使用指南

路径 E · 生产部署

1. 本篇 → 2. 02 核心原理 → 3. 03 DSpark 建模（confidence head 部分）→ 4. 08 实验复现 第 5 节生产部署 → 5. 10 总结

---

五、文档索引表

序号	文档	角色	主要读者
00	总览与阅读指南	总·开篇	所有
01	整体架构与设计理念	分	工程师 / 研究者
02	核心原理：推测解码与 draft 模型	分	研究者
03	DSpark 建模：Markov 与 Confidence	分·重点	研究者 / 部署
04	Eagle3 建模：TTT 与 Triton 融合 Loss	分	研究者
05	数据管道：TargetCache 与对话模板	分	工程师
06	训练框架：FSDP 与 BF16 优化器	分	工程师
07	评测系统：拒绝采样与校准	分	研究者 / 部署
08	实验复现：论文对照与流程详解	分·重点	研究者
09	使用指南：从零到评测	分	工程师
10	总结：工程经验与未来方向	总·收篇	所有

---

六、关键术语表

术语	含义	代码线索
target model	被加速的大模型（如 Qwen3-4B），训练时冻结	config/*.py 的 target_model_name_or_path
draft model	轻量推测模型，预测 target 接下来 K 个 token	deepspec/modeling/{dspark,eagle3}/
anchor token	上一轮 target 生成的最后一个 token，作为本轮 draft 的根（论文 footnote 1：anchor 与 bonus 可互换）	[common.py:109-169](file:///workspace/deepspec/modeling/dspark/common.py#L109-169)
bonus token	全部 draft 被接受后，target 多采样的"奖励"token	[base_evaluator.py:287-293](file:///workspace/deepspec/eval/base_evaluator.py#L287-293)
block_size (γ)	一次并行 draft 的 token 数，默认 7	config/dspark/dspark_qwen3_4b.py 的 block_size
TTT (Test-Time Training)	Eagle3 在线多步循环采样，ttt_length 步	[eagle3/loss.py:402-444](file:///workspace/deepspec/modeling/eagle3/loss.py#L402-444)
markov_rank ®	Markov head 低秩分解维度，默认 256	[markov_head.py:8-90](file:///workspace/deepspec/modeling/dspark/markov_head.py#L8-90)
accept rate (τ)	每轮验证平均被接受的 token 数（含 bonus），论文核心指标	[base_evaluator.py:469-511](file:///workspace/deepspec/eval/base_evaluator.py#L469-511)
SPS(B)	Steps Per Second，引擎在不同 batch size 下的吞吐曲线，用于硬件感知调度	论文 Algorithm 1
STS	Sequential Temperature Scaling，逐位置 1D grid search 校准累积生存概率	论文 Section 3.2.1（生产侧）
target cache	预计算的 target hidden states，约 38TB	[target_cache_dataset.py](file:///workspace/deepspec/data/target_cache_dataset.py)
target_layer_ids	从 target 哪几层抽取 hidden，默认 [1,9,17,25,33]	config/dspark/dspark_qwen3_4b.py
loss_mask	标记哪些 token 是 assistant 输出（计算 loss），哪些是 prompt（不计算）	[parser.py:114-138](file:///workspace/deepspec/data/parser.py#L114-138)

6.1 核心术语关系图

图说明： 术语关系图展示 12 个核心术语的依赖链。target model 通过 forward hook 生成 target cache（38TB），draft model 训练时 mmap 读盘。每轮 draft 以 anchor token 为根，按 block_size 并行生成 γ 个 token；Markov head 注入 markov_rank 维前缀依赖，confidence head 输出每位置接受率 c_k。全部 draft 被接受时 target 多采 bonus token。confidence head 的 raw 输出经 STS 校准后，配合 SPS(B) 吞吐曲线，喂给 Algorithm 1 硬件感知调度器，动态截断验证长度，最终影响 accept rate τ。实线表示数据流与配置驱动关系。

---

七、本系列文档约定

1. 代码引用：所有引用以 [basename](file:///workspace/abs/path#Lxx-yy) 形式呈现，可在 IDE / GitHub 直接点击跳转。
2. Mermaid 配图：每篇至少 3 张，每张图下必有 **图说明：** 段落。
3. 公式：与论文 Eq. (5)–(12) 对齐，使用 LaTeX $...$ / $$...$$ 渲染。
4. 总分总：每篇内部"总览 → 分述 → 小结"三段式；全套 11 篇"00 总 → 01–09 分 → 99 总"。
5. 不臆造：所有路径、行号、配置项均来自代码实测；论文数据均来自 PDF 提取。

---

小结（总·开篇收束）

DeepSpec 的工程价值在于：它把"为任意 target 训练 speculative decoding draft 模型"这件事标准化了——从数据生成到训练再到评测，每个阶段都有清晰边界与可替换组件。理解本仓库的关键在于把握三条主线：① 三算法共用基础设施（BaseTrainer/BaseEvaluator/CacheDataset）的差异在 modeling+loss 层；② target cache 把训练时反复跑 target 的成本前置到一次离线准备；③ confidence head 是 DSpark 区别于 DFlash/Eagle3 的核心，把"无脑验证全部 draft"升级为"按硬件负载智能截断"。后续 01–09 篇按这三条主线展开，08 篇专门复现论文实验，99 篇回归工程经验。

延伸阅读：进入 01 整体架构与设计理念 看代码骨架，或直接进入 02 核心原理 理解推测解码为什么有效。论文原文在 [DSpark_paper.pdf](file:///workspace/DSpark_paper.pdf)。