[Skip to content](https://github.com/deepseek-ai/DeepSpec#start-of-content) You signed in with another tab or window. [Reload](https://github.com/deepseek-ai/DeepSpec) to refresh your session.You signed out in another tab or window. [Reload](https://github.com/deepseek-ai/DeepSpec) to refresh your session.You switched accounts on another tab or window. [Reload](https://github.com/deepseek-ai/DeepSpec) to refresh your session.Dismiss alert {{ message }} ### Uh oh! There was an error while loading. [Please reload this page](https://github.com/deepseek-ai/DeepSpec). [deepseek-ai](https://github.com/deepseek-ai)/ **[DeepSpec](https://github.com/deepseek-ai/DeepSpec)** Public - [Notifications](https://github.com/login?return_to=%2Fdeepseek-ai%2FDeepSpec) You must be signed in to change notification settings - [Fork\\ 510](https://github.com/login?return_to=%2Fdeepseek-ai%2FDeepSpec) - [Star\\ 6.1k](https://github.com/login?return_to=%2Fdeepseek-ai%2FDeepSpec) main [**1** Branch](https://github.com/deepseek-ai/DeepSpec/branches) [**0** Tags](https://github.com/deepseek-ai/DeepSpec/tags) [Go to Branches page](https://github.com/deepseek-ai/DeepSpec/branches)[Go to Tags page](https://github.com/deepseek-ai/DeepSpec/tags) Go to file Code Open more actions menu ## Folders and files | Name | Name | Last commit message | Last commit date | | --- | --- | --- | --- | | ## Latest commit
[![Hannibal046](https://avatars.githubusercontent.com/u/38466901?v=4&size=40)](https://github.com/Hannibal046)[Hannibal046](https://github.com/deepseek-ai/DeepSpec/commits?author=Hannibal046)
[Merge pull request](https://github.com/deepseek-ai/DeepSpec/commit/afdfa7c9382a3341a3e6f17756dd816da79f132c) [#16](https://github.com/deepseek-ai/DeepSpec/pull/16) [from DaoyuanLi2816/fix-scheduler-state-dict-op…](https://github.com/deepseek-ai/DeepSpec/commit/afdfa7c9382a3341a3e6f17756dd816da79f132c)
Open commit details
4 days agoJun 30, 2026
[afdfa7c](https://github.com/deepseek-ai/DeepSpec/commit/afdfa7c9382a3341a3e6f17756dd816da79f132c) · 4 days agoJun 30, 2026
## History
[14 Commits](https://github.com/deepseek-ai/DeepSpec/commits/main/)
Open commit details
[View commit history for this file.](https://github.com/deepseek-ai/DeepSpec/commits/main/) 14 Commits | | [config](https://github.com/deepseek-ai/DeepSpec/tree/main/config "config") | [config](https://github.com/deepseek-ai/DeepSpec/tree/main/config "config") | [Align DSpark/DFlash exp\_name with block\_size=7 (block7)](https://github.com/deepseek-ai/DeepSpec/commit/c938b5424cbcd2e7b4396d9588c5feb120432bd9 "Align DSpark/DFlash exp_name with block_size=7 (block7) The DSpark and DFlash configs set `block_size=7` but name their experiments `*_block8_*`. The Eagle3 configs already follow the parameter value in their names (`*_ttt7_*` with `ttt_length=7`), and the released checkpoints in the README are published as `*_block7_*`. Rename the experiments to `*_block7_*` so the default checkpoint directory matches both `block_size=7` and the published checkpoint names, and update the eval.sh / README examples that reference that path.") | 4 days agoJun 30, 2026 | | [deepspec](https://github.com/deepseek-ai/DeepSpec/tree/main/deepspec "deepspec") | [deepspec](https://github.com/deepseek-ai/DeepSpec/tree/main/deepspec "deepspec") | [Merge pull request](https://github.com/deepseek-ai/DeepSpec/commit/afdfa7c9382a3341a3e6f17756dd816da79f132c "Merge pull request #16 from DaoyuanLi2816/fix-scheduler-state-dict-optimizer-key Fix scheduler state_dict to drop the optimizer key by equality") [#16](https://github.com/deepseek-ai/DeepSpec/pull/16) [from DaoyuanLi2816/fix-scheduler-state-dict-op…](https://github.com/deepseek-ai/DeepSpec/commit/afdfa7c9382a3341a3e6f17756dd816da79f132c "Merge pull request #16 from DaoyuanLi2816/fix-scheduler-state-dict-optimizer-key Fix scheduler state_dict to drop the optimizer key by equality") | 4 days agoJun 30, 2026 | | [eval\_datasets](https://github.com/deepseek-ai/DeepSpec/tree/main/eval_datasets "eval_datasets") | [eval\_datasets](https://github.com/deepseek-ai/DeepSpec/tree/main/eval_datasets "eval_datasets") | [first init](https://github.com/deepseek-ai/DeepSpec/commit/0a03e19e1c57000d5d3d291fa57109944eba6b6a "first init") | last weekJun 27, 2026 | | [scripts](https://github.com/deepseek-ai/DeepSpec/tree/main/scripts "scripts") | [scripts](https://github.com/deepseek-ai/DeepSpec/tree/main/scripts "scripts") | [Align DSpark/DFlash exp\_name with block\_size=7 (block7)](https://github.com/deepseek-ai/DeepSpec/commit/c938b5424cbcd2e7b4396d9588c5feb120432bd9 "Align DSpark/DFlash exp_name with block_size=7 (block7) The DSpark and DFlash configs set `block_size=7` but name their experiments `*_block8_*`. The Eagle3 configs already follow the parameter value in their names (`*_ttt7_*` with `ttt_length=7`), and the released checkpoints in the README are published as `*_block7_*`. Rename the experiments to `*_block7_*` so the default checkpoint directory matches both `block_size=7` and the published checkpoint names, and update the eval.sh / README examples that reference that path.") | 4 days agoJun 30, 2026 | | [.gitignore](https://github.com/deepseek-ai/DeepSpec/blob/main/.gitignore ".gitignore") | [.gitignore](https://github.com/deepseek-ai/DeepSpec/blob/main/.gitignore ".gitignore") | [first init](https://github.com/deepseek-ai/DeepSpec/commit/0a03e19e1c57000d5d3d291fa57109944eba6b6a "first init") | last weekJun 27, 2026 | | [DSpark\_paper.pdf](https://github.com/deepseek-ai/DeepSpec/blob/main/DSpark_paper.pdf "DSpark_paper.pdf") | [DSpark\_paper.pdf](https://github.com/deepseek-ai/DeepSpec/blob/main/DSpark_paper.pdf "DSpark_paper.pdf") | [first init](https://github.com/deepseek-ai/DeepSpec/commit/0a03e19e1c57000d5d3d291fa57109944eba6b6a "first init") | last weekJun 27, 2026 | | [LICENSE](https://github.com/deepseek-ai/DeepSpec/blob/main/LICENSE "LICENSE") | [LICENSE](https://github.com/deepseek-ai/DeepSpec/blob/main/LICENSE "LICENSE") | [first init](https://github.com/deepseek-ai/DeepSpec/commit/0a03e19e1c57000d5d3d291fa57109944eba6b6a "first init") | last weekJun 27, 2026 | | [NOTICE](https://github.com/deepseek-ai/DeepSpec/blob/main/NOTICE "NOTICE") | [NOTICE](https://github.com/deepseek-ai/DeepSpec/blob/main/NOTICE "NOTICE") | [first init](https://github.com/deepseek-ai/DeepSpec/commit/0a03e19e1c57000d5d3d291fa57109944eba6b6a "first init") | last weekJun 27, 2026 | | [README.md](https://github.com/deepseek-ai/DeepSpec/blob/main/README.md "README.md") | [README.md](https://github.com/deepseek-ai/DeepSpec/blob/main/README.md "README.md") | [Align DSpark/DFlash exp\_name with block\_size=7 (block7)](https://github.com/deepseek-ai/DeepSpec/commit/c938b5424cbcd2e7b4396d9588c5feb120432bd9 "Align DSpark/DFlash exp_name with block_size=7 (block7) The DSpark and DFlash configs set `block_size=7` but name their experiments `*_block8_*`. The Eagle3 configs already follow the parameter value in their names (`*_ttt7_*` with `ttt_length=7`), and the released checkpoints in the README are published as `*_block7_*`. Rename the experiments to `*_block7_*` so the default checkpoint directory matches both `block_size=7` and the published checkpoint names, and update the eval.sh / README examples that reference that path.") | 4 days agoJun 30, 2026 | | [eval.py](https://github.com/deepseek-ai/DeepSpec/blob/main/eval.py "eval.py") | [eval.py](https://github.com/deepseek-ai/DeepSpec/blob/main/eval.py "eval.py") | [first init](https://github.com/deepseek-ai/DeepSpec/commit/0a03e19e1c57000d5d3d291fa57109944eba6b6a "first init") | last weekJun 27, 2026 | | [requirements.txt](https://github.com/deepseek-ai/DeepSpec/blob/main/requirements.txt "requirements.txt") | [requirements.txt](https://github.com/deepseek-ai/DeepSpec/blob/main/requirements.txt "requirements.txt") | [Update requirements.txt](https://github.com/deepseek-ai/DeepSpec/commit/ae6712019fb3880cedab918fb683d076e3cf15d6 "Update requirements.txt") | 5 days agoJun 29, 2026 | | [train.py](https://github.com/deepseek-ai/DeepSpec/blob/main/train.py "train.py") | [train.py](https://github.com/deepseek-ai/DeepSpec/blob/main/train.py "train.py") | [first init](https://github.com/deepseek-ai/DeepSpec/commit/0a03e19e1c57000d5d3d291fa57109944eba6b6a "first init") | last weekJun 27, 2026 | | View all files | ## Repository files navigation # DeepSpec [Permalink: DeepSpec](https://github.com/deepseek-ai/DeepSpec#deepspec) DeepSpec is a full-stack codebase for training and evaluating draft models for speculative decoding. It contains data preparation utilities, draft model implementations, training code, and evaluation scripts. ## Environment [Permalink: Environment](https://github.com/deepseek-ai/DeepSpec#environment) Install the Python dependencies: ``` python -m pip install -r requirements.txt ``` Data preparation additionally requires an inference engine to serve the target model when regenerating answers; see [scripts/data/README.md](https://github.com/deepseek-ai/DeepSpec/blob/main/scripts/data/README.md) for details. ## Workflow [Permalink: Workflow](https://github.com/deepseek-ai/DeepSpec#workflow) Run the stages in order — each stage's output feeds the next: 1. **Data Preparation** — download prompts, regenerate target answers, and build the target cache. 2. **Training** — train a draft model against the cached target outputs. 3. **Evaluation** — measure speculative-decoding acceptance on benchmark tasks. ## Data Preparation [Permalink: Data Preparation](https://github.com/deepseek-ai/DeepSpec#data-preparation) See [scripts/data/README.md](https://github.com/deepseek-ai/DeepSpec/blob/main/scripts/data/README.md) for the step-by-step data pipeline: 1. download and split training data, 2. regenerate answers, 3. prepare the target cache (storage warning: this can be very large — roughly 38 TB for the default `Qwen/Qwen3-4B` setting). ## Training [Permalink: Training](https://github.com/deepseek-ai/DeepSpec#training) ``` bash scripts/train/train.sh ``` `train.sh` launches `train.py`, which spawns one worker per visible GPU. Select the algorithm and target model by pointing `config_path` at one of the configs under [config/](https://github.com/deepseek-ai/DeepSpec/blob/main/config) (e.g. `config/dspark/dspark_qwen3_4b.py`); see the script header for the full list of configs, how to override `config_path` / `target_cache_dir`, and how to use `--opts` to override individual config fields. Checkpoints are written to `~/checkpoints///step_*`. Hardware: the default configs and scripts assume a single node with 8 GPUs. For fewer GPUs, reduce `CUDA_VISIBLE_DEVICES`. ## Evaluation [Permalink: Evaluation](https://github.com/deepseek-ai/DeepSpec#evaluation) ``` bash scripts/eval/eval.sh ``` `eval.sh` runs `eval.py` against a trained draft checkpoint over the speculative-decoding benchmarks in [eval\_datasets/](https://github.com/deepseek-ai/DeepSpec/blob/main/eval_datasets) (gsm8k, math500, aime25, humaneval, mbpp, livecodebench, mt-bench, alpaca, arena-hard-v2). Set: - `target_name_or_path` — the target model the draft was trained against (e.g. `Qwen/Qwen3-4B`), - `draft_name_or_path` — the draft checkpoint, e.g. `~/checkpoints/deepspec/dspark_block7_qwen3_4b/step_latest`, or one of the Hugging Face repo IDs listed in [Released Checkpoints](https://github.com/deepseek-ai/DeepSpec#released-checkpoints). ### Released Checkpoints [Permalink: Released Checkpoints](https://github.com/deepseek-ai/DeepSpec#released-checkpoints) The checkpoints below are the ones used for Table 1 in the [paper](https://github.com/deepseek-ai/DeepSpec/blob/main/DSpark_paper.pdf). Each checkpoint was trained on [open-perfectblend](https://huggingface.co/datasets/mlabonne/open-perfectblend) data generated by its corresponding target model in non-thinking mode, and is the direct output of the corresponding training configuration under [config/](https://github.com/deepseek-ai/DeepSpec/blob/main/config). | Algorithm | `Qwen/Qwen3-4B` | `Qwen/Qwen3-8B` | `Qwen/Qwen3-14B` | `google/gemma-4-12B-it` | | --- | --- | --- | --- | --- | | Eagle3 | [deepseek-ai/eagle3\_qwen3\_4b\_ttt7](https://huggingface.co/deepseek-ai/eagle3_qwen3_4b_ttt7) | [deepseek-ai/eagle3\_qwen3\_8b\_ttt7](https://huggingface.co/deepseek-ai/eagle3_qwen3_8b_ttt7) | [deepseek-ai/eagle3\_qwen3\_14b\_ttt7](https://huggingface.co/deepseek-ai/eagle3_qwen3_14b_ttt7) | [deepseek-ai/eagle3\_gemma4\_12b\_ttt7](https://huggingface.co/deepseek-ai/eagle3_gemma4_12b_ttt7) | | DFlash | [deepseek-ai/dflash\_qwen3\_4b\_block7](https://huggingface.co/deepseek-ai/dflash_qwen3_4b_block7) | [deepseek-ai/dflash\_qwen3\_8b\_block7](https://huggingface.co/deepseek-ai/dflash_qwen3_8b_block7) | [deepseek-ai/dflash\_qwen3\_14b\_block7](https://huggingface.co/deepseek-ai/dflash_qwen3_14b_block7) | [deepseek-ai/dflash\_gemma4\_12b\_block7](https://huggingface.co/deepseek-ai/dflash_gemma4_12b_block7) | | DSpark | [deepseek-ai/dspark\_qwen3\_4b\_block7](https://huggingface.co/deepseek-ai/dspark_qwen3_4b_block7) | [deepseek-ai/dspark\_qwen3\_8b\_block7](https://huggingface.co/deepseek-ai/dspark_qwen3_8b_block7) | [deepseek-ai/dspark\_qwen3\_14b\_block7](https://huggingface.co/deepseek-ai/dspark_qwen3_14b_block7) | [deepseek-ai/dspark\_gemma4\_12b\_block7](https://huggingface.co/deepseek-ai/dspark_gemma4_12b_block7) | Important If you cite these results in a new paper, align your setup with the training settings in this repository; otherwise, the comparison is not meaningful. For domain-specific use, fine-tune the draft model again for better results, especially if the target model is expected to run in thinking mode. ## Supported Algorithms [Permalink: Supported Algorithms](https://github.com/deepseek-ai/DeepSpec#supported-algorithms) Currently, DeepSpec includes three draft models: [DSpark](https://github.com/deepseek-ai/DeepSpec/blob/main/DSpark_paper.pdf), [DFlash](https://arxiv.org/abs/2602.06036) and [Eagle3](https://arxiv.org/abs/2503.01840). ## License [Permalink: License](https://github.com/deepseek-ai/DeepSpec#license) DeepSpec is released under the [MIT License](https://github.com/deepseek-ai/DeepSpec/blob/main/LICENSE). It includes code adapted from third-party projects under their own licenses; see [NOTICE](https://github.com/deepseek-ai/DeepSpec/blob/main/NOTICE) for the full attribution. ## Acknowledgements [Permalink: Acknowledgements](https://github.com/deepseek-ai/DeepSpec#acknowledgements) DeepSpec builds on the ideas and code of several excellent open-source projects: - [SpecForge](https://github.com/sgl-project/SpecForge) (Apache-2.0) — the overall training framework and Eagle3 implementation; portions of the Eagle3 modeling, loss, optimizer, attention, and evaluation code are adapted from it. Adapted files carry an in-file attribution comment, and the full notice is recorded in [NOTICE](https://github.com/deepseek-ai/DeepSpec/blob/main/NOTICE). - [DFlash](https://github.com/z-lab/dflash) (MIT) — the DFlash draft-model design and training recipe. - [Qwen3](https://github.com/QwenLM/Qwen3) and [Gemma](https://github.com/google-deepmind/gemma) — the target model families supported in this repo. We thank the authors and maintainers of these projects. Contributions of new algorithms are welcome. ## About DeepSpec: a full-stack codebase for training and evaluating speculative decoding algorithms ### Resources [Readme](https://github.com/deepseek-ai/DeepSpec#readme-ov-file) ### License [MIT license](https://github.com/deepseek-ai/DeepSpec#MIT-1-ov-file) ### Uh oh! There was an error while loading. [Please reload this page](https://github.com/deepseek-ai/DeepSpec). [Activity](https://github.com/deepseek-ai/DeepSpec/activity) [Custom properties](https://github.com/deepseek-ai/DeepSpec/custom-properties) ### Stars [**6.1k**\\ stars](https://github.com/deepseek-ai/DeepSpec/stargazers) ### Watchers [**25**\\ watching](https://github.com/deepseek-ai/DeepSpec/watchers) ### Forks [**510**\\ forks](https://github.com/deepseek-ai/DeepSpec/forks) [Report repository](https://github.com/contact/report-content?content_url=https%3A%2F%2Fgithub.com%2Fdeepseek-ai%2FDeepSpec&report=deepseek-ai+%28user%29) ## [Releases](https://github.com/deepseek-ai/DeepSpec/releases) No releases published ## [Packages\ 0](https://github.com/orgs/deepseek-ai/packages?repo_name=DeepSpec) No packages published ## [Contributors\ 3](https://github.com/deepseek-ai/DeepSpec/graphs/contributors) - [![@Hannibal046](https://avatars.githubusercontent.com/u/38466901?s=64&v=4)](https://github.com/Hannibal046)[**Hannibal046**](https://github.com/Hannibal046) - [![@DaoyuanLi2816](https://avatars.githubusercontent.com/u/94409450?s=64&v=4)](https://github.com/DaoyuanLi2816)[**DaoyuanLi2816** Daoyuan Li](https://github.com/DaoyuanLi2816) - [![@inisis](https://avatars.githubusercontent.com/u/46103969?s=64&v=4)](https://github.com/inisis)[**inisis** inisis](https://github.com/inisis) ## Languages - [Python97.9%](https://github.com/deepseek-ai/DeepSpec/search?l=python) - [Shell2.1%](https://github.com/deepseek-ai/DeepSpec/search?l=shell) You can’t perform that action at this time.