deepseek-tech-notes

DeepSeek 全系列论文通俗拆解 — 从 V1 到 V4、R1 reasoning、sparse attention (DSA)、DSpark speculative decoding，统一排版、双向 wiki、配套公式与 SVG 图解。区别于零散博客，可在线成书阅读。

Comprehensive DeepSeek full-series paper explanation, including DeepSeek-V2/V3/V4, R1 reasoning, sparse attention, DSpark speculative decoding — easy-to-understand technical notes for LLM researchers and engineers. Unofficial; not affiliated with DeepSeek.

📖 Read online (mdBook) · 中文导读

如果这份笔记对你有帮助，欢迎 Star ⭐ 方便后续查阅。
If these notes help you, please Star to bookmark for later.

---

公式图解预览

版本演进全图 · 演进总览

MLA 前向流程 · MLA 详解

GRPO vs PPO · R1 · RLVR

MTP 融合 · DSpark

DSpark 投机解码 · 投机解码专文

---

论文目录 · Paper Catalog

主题	文档	关键词
V1	DeepSeek-LLM	scaling laws, 稠密基座
V2	DeepSeek-V2	MLA, DeepSeekMoE, 128K
V3	DeepSeek-V3	671B MoE, MTP, aux-loss-free
R1	DeepSeek-R1	reasoning model, RLVR, GRPO
V3.2	DeepSeek-V3.2	sparse attention, DSA
V4	DeepSeek-V4	CSA/HCA, mHC, 1M context
DSA	稀疏注意力	indexer, top-k, lightning indexer
DSpark	投机解码	speculative decoding, MTP fusion
MLA	低秩注意力	latent KV, KV cache 压缩
MoE	DeepSeekMoE	routed experts, shared experts
Index Share	IndexCache	跨层 index 复用, infra 补丁
ESS	Latent offload	CPU KV offload
CSA / HCA	混合压缩注意力	4:1 sparse + 128:1 dense
Hash MoE	Hash MoE + FP4	hash routing, FP4 quantization

完整索引：中文导读 · 文章表 · 版本目录 · 在线成书

搜索关键词：DeepSeek paper · DeepSeek-V2 · DeepSeek-V3 · DeepSeek-V4 · DeepSeek R1 · reasoning model · sparse attention · DSpark · MLA · MoE · llm-papers · paper explanation

---

Recommended reading

These notes form a bidirectional wiki — every article links back at the top and forward in the body. To get the most out of that navigation, use one of these (not GitHub’s in-repo blob preview):

Mode	When	Navigation
IDE Preview (VS Code / Cursor)	Cloned repo, deep reading or editing	Click ← back-links and in-text links; split preview or preview history — best for forward / back references
GitHub Pages (mdBook)	Online, no clone	Same math/diagram rendering as the IDE; use the browser Back / Forward buttons to retrace your reading path

Either IDE Preview or Pages works. Edit and PR in docs/ as usual.

Why an online book (not GitHub Preview)?

Local IDE Preview (VS Code / Cursor) and GitHub’s in-repo .md Preview use different Markdown + math renderers — blockquotes, $...$ / $$...$$, and inline math inside links often look wrong on GitHub even when they look fine in the IDE. Source Markdown is not rewritten to chase GitHub Preview; instead, docs/ is built into an mdBook site on GitHub Pages (KaTeX, same $...$ source as the IDE). Use that for online reading; use the repo for editing and PRs.

---

What this repo is

I follow DeepSeek's open-model line V1 → V2 → V3 → R1 / V3.2 → V4, and unpack most (not every) major technical reports into readable walkthroughs: architecture changes, training/inference tricks, formulas, and how versions relate.

Differentiation — vs scattered blog posts: unified layout, bidirectional wiki navigation, SVG formula diagrams, per-paper 核心结论摘要 modules, and a living mdBook mirror.

Coverage includes:

• Core DeepSeek releases — MLA, MoE routing, MTP, DSA, CSA/HCA, mHC, Hash MoE, V4 KV layout, etc.
• V4 inference stack — DSpark speculative decoding, HiSparse, disk prefix cache.
• Adjacent infra work layered on DeepSeek checkpoints — Index Share / IndexCache (Tsinghua + Zhipu) and ESS latent-cache offload (Baidu BaiGe), with a dedicated infrastructure thread alongside algorithm and MoE.

Organized as wiki-style articles, SVG diagrams, and a book-style layout under 《ds-技术报告》/. For full navigation and article list, use the Chinese docs home or the online mdBook.

Why reading here feels smooth

This repo is built for bidirectional navigation: every article, deep-dive, and Q&A page links back to where you came from — the Chinese home, this English homepage, the evolution hub, or the parent section. Follow a link into DSA logic, MTP fusion, or Engram notes; when you are done, one click returns you to the article or index you started from. No dead ends, no guessing how to resume the thread.

In IDE Preview, click links to jump; on Pages, use browser Back / Forward for the same effect.

Work in progress. Summaries, mirroring, links, and diagrams are still being updated. Prefer arXiv / official PDFs cited at the top of each article. Broken links or errors — issues welcome.

---

Start here

Online book (Pages)	fooSynaptic.github.io/deepseek-tech-notes — or clone and use IDE Preview
Chinese home (source hub)	docs/README.md
Evolution hub	Version lineage overview — algorithm / infrastructure / MoE threads
Book mirror (repo)	《ds-技术报告》/01-总览/01-版本演进总览.md

---

Repository layout

Path	Role
docs/	Source of truth — edit articles here
《ds-技术报告》/	Book mirror — generated by build_book.py (do not hand-edit)
book.toml + theme/	mdBook config & CSS for GitHub Pages
scripts/build_pages.sh	build_book → SUMMARY.md → mdbook build
.github/workflows/pages.yml	Deploy mdBook to GitHub Pages on push to main

Reading: Recommended reading — IDE Preview or GitHub Pages mdBook; not GitHub blob preview. See Why an online book for rendering details.

---

Contributing & book layout

Source of truth is docs/. The folder 《ds-技术报告》/ is a generated book mirror — do not edit those Markdown files by hand; they are overwritten by build_book.py.

When you add or move content:

1. Write the article under docs/ (e.g. docs/versions/, docs/dsa/, docs/reports/, docs/versions/qa/).
2. Register it for the book in 《ds-技术报告》/build_book.py:
   • CHAPTER_MAP — map docs/... → book chapter path;
   • READING_ORDER — prev/next chapter navigation;
   • QA_DESTINATIONS — if it is a Q&A page (may mirror to multiple book folders);
   • ASSET_MAP — only if new figures need copying into the book tree.
3. Add navigation — blockquote top bar with ← links back to the parent section / index (see existing articles); link the new page from the relevant overview or index.
4. Add ## 核心结论摘要 at the top of each new paper article (3–5 bullet takeaways).
5. Rebuild & check (from repo root):

python3 《ds-技术报告》/build_book.py
python3 scripts/validate_refs.py
python3 scripts/validate_backlinks.py

Or run the full gate: bash scripts/doc_series_gate.sh.

To preview the mdBook site locally (requires mdBook):

bash scripts/build_pages.sh
# open mdbook-out/index.html

Wiki-style reading in docs/ works without the book step; run build_book.py when the chapter should appear in 《ds-技术报告》 with rewritten links and chapter nav. Push to main rebuilds GitHub Pages automatically.

---

License

Scope	License
Notes, diagrams, book layout	CC BY 4.0
scripts/	MIT
docs/engram/	Apache 2.0
docs/material/ mirrors	upstream / original paper terms

DeepSeek papers, weights, and official code remain under their own licenses.