DeepSpec README

The project's README from github.com/deepseek-ai/DeepSpec. As one markdown file: README.md.

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

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 for details.

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

See 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

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/ (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/<project_name>/<exp_name>/step_*.

Hardware: the default configs and scripts assume a single node with 8 GPUs. For fewer GPUs, reduce CUDA_VISIBLE_DEVICES.

Evaluation

bash scripts/eval/eval.sh

eval.sh runs eval.py against a trained draft checkpoint over the speculative-decoding benchmarks in eval_datasets/ (gsm8k, math500, aime25, humaneval, mbpp, livecodebench, mt-bench, alpaca, arena-hard-v2). Set:

Released Checkpoints

The checkpoints below are the ones used for Table 1 in the paper. Each checkpoint was trained on 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/.

Algorithm Qwen/Qwen3-4B Qwen/Qwen3-8B Qwen/Qwen3-14B google/gemma-4-12B-it
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
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
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

[!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

Currently, DeepSpec includes three draft models: DSpark, DFlash and Eagle3.

License

DeepSpec is released under the MIT License. It includes code adapted from third-party projects under their own licenses; see NOTICE for the full attribution.

Acknowledgements

DeepSpec builds on the ideas and code of several excellent open-source projects:

We thank the authors and maintainers of these projects. Contributions of new algorithms are welcome.

Citation

@misc{cheng2026dsparkconfidencescheduledspeculativedecoding,
      title={DSpark: Confidence-Scheduled Speculative Decoding with Semi-Autoregressive Generation}, 
      author={Xin Cheng and Xingkai Yu and Chenze Shao and Jiashi Li and Yunfan Xiong and Yi Qian and Jiaqi Zhu and Shirong Ma and Xiaokang Zhang and Jiasheng Ye and Qinyu Chen and Chengqi Deng and Jiping Yu and Damai Dai and Zhengyan Zhang and Yixuan Wei and Yixuan Tan and Wenkai Yang and Runxin Xu and Yu Wu and Zhean Xu and Xuanyu Wang and Muyang Chen and Rui Tian and Xiao Bi and Zhewen Hao and Shaoyuan Chen and Huanqi Cao and Wentao Zhang and Anyi Xu and Huishuai Zhang and Dongyan Zhao and Wenfeng Liang},
      year={2026},
      eprint={2607.05147},
      archivePrefix={arXiv},
      primaryClass={cs.AI},
      url={https://arxiv.org/abs/2607.05147}, 
}

DeepSpec (deepseek-ai/DeepSpec)

Searching Database…

7.2K ·GitHub
DeepSpec
Что это такое?DeepSpec — это полнофункциональная Python-кодовая база от DeepSeek для обучения и оценки черновых (draft) моделей для спекулятивного декодирования — техники, где небольшая черновая модель ускоряет работу более крупной целевой LLM.
Это библиотека, которую можно установить в моё приложение, или набор скриптов для запуска?Это исследовательский код, который запускается как конвейер из этапов — подготовка данных, затем обучение через train.sh, затем оценка через eval.sh, — а не устанавливаемая библиотека для инференса.
Как его запустить?Установите Python-зависимости, затем выполните три этапа по порядку: подготовка данных (пошагово в scripts/data/README.md), обучение через train.sh и оценка через eval.sh — результат каждого этапа подаётся на вход следующему.
Мне нужен целый GPU-узел, чтобы это запустить?Конфигурации по умолчанию рассчитаны на один узел с 8 GPU — train.sh запускает по одному воркеру на каждую видимую GPU, с меньшим числом GPU можно работать через CUDA_VISIBLE_DEVICES, — плюс движок инференса, который обслуживает целевую модель во время подготовки данных.
Сколько места на диске мне предусмотреть?Очень много: кэш целевой модели, создаваемый при подготовке данных, может достигать примерно 38 ТБ для настройки по умолчанию с Qwen/Qwen3-4B, так что хранилище — первое, о чём стоит позаботиться.
Могу ли я использовать выпущенные черновые модели как есть для своих задач?Возможно, нет: они обучались на данных open-perfectblend со своими целевыми моделями в режиме non-thinking. Для задач в конкретной предметной области README советует дообучить черновую модель заново, особенно если ваша целевая модель будет работать в режиме thinking.
Весь ли код написан с нуля?Нет — DeepSpec опирается на SpecForge (Apache-2.0) как на фреймворк для обучения и на Eagle3, а также на рецепт DFlash (MIT); в адаптированных файлах есть указание авторства внутри самих файлов, полные уведомления — в NOTICE, а сам DeepSpec распространяется по лицензии MIT.
Могу ли я переиспользовать его результаты бенчмарков в своей статье?Только если ваша конфигурация совпадает с настройками обучения из репозитория — README прямо предупреждает, что несогласованное сравнение не имеет смысла.
What are similar projects?jeeves, NanoJev, open-r1, jeff, Valen, CLM, airllm, Intern-Decision
Which topics is it in?model-training, speculative-decoding, training, llm-inference, dataset, qwen, evaluation, fine-tuning, deepseek, huggingface, cuda, benchmark
Creator
deepseek-ai
Size
4 MB
Stars
7.2K
Updated
CommitJul 09
Age
3mo
Commits · 90 Days