DeepSeek Mechanism Atlas

An atlas of DeepSeek mechanisms — architecture, sparse attention, speculative decoding, MoE routing, and adjacent inference infra — organized as a bidirectional wiki + mdBook.

Unofficial. Not affiliated with DeepSeek.

Read online (mdBook) · 中文导读 / Chinese README

If this atlas helps you, please Star to bookmark for later.

New · Agent runtime thread: DeepSeek Harness (dsh) — Cordis plugins · Code Mode · session log. Fourth narrative beside algorithm / infrastructure / MoE.

New · V4.1-Flash: KV cache compression notes — CED · CSA2 · FP4 main KV · SWA Bounded Replay.

---

Paper catalog

Full index: Chinese docs home · article list · Version index · Online book

Search keywords: DeepSeek paper · DeepSeek-V2 · DeepSeek-V3 · DeepSeek-V4 · DeepSeek-V4.1-Flash · DeepSeek R1 · reasoning model · sparse attention · CSA2 · DSpark · MLA · MoE · DeepSeek Harness · agent runtime · Code Mode · llm-papers · paper explanation

---

Diagrams

Figures live under diagrams/ and are linked from articles. Prefer the online book or IDE Preview for rendering. Selected entry points:

---

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):

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

This project follows DeepSeek's open-model line V1 → V2 → V3 → R1 / V3.2 → V4, and unpacks 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 takeaway sections, 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.
• Agent runtime — DeepSeek Harness (dsh): Cordis plugin coding agent; a fourth narrative thread beside algorithm / infrastructure / MoE.
• 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 Chinese navigation and article list, use the Chinese README 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

---

Repository layout

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 a takeaway section at the top of each new paper article (3–5 bullet points; Chinese articles use ## 核心结论摘要).
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

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