deepseek-tech-notes

Chinese docs home

📖 Read online (mdBook) — same rendering as local IDE Preview. For online reading use Pages, not GitHub blob preview.

Smooth, deep notes on frontier DeepSeek tech — bidirectional navigation from V1 through V4 (DSA, MoE, DSpark, Engram, and beyond): formulas, walkthroughs, and infra patches in wiki + book form. Unofficial; not affiliated with DeepSeek.

Primary language: Chinese. Most articles, the book layout, and deep-dive notes are in Simplified Chinese. For the full article index and navigation hub, see the Chinese docs home or the online mdBook.

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.

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
PNG figures	png/ — raster exports of all SVG diagrams (images only)

Diagram details

Diagram details · DSpark speculative decoding · MTP fusion scheme (qa)

---

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