怎么读这本书 / 怎么复现

本章要回答的问题：我该按什么顺序读？每章要动手到什么程度？跑不出一样的结果怎么办？

三种读法，选一种

第一种：最短路径（建议第一次读）。 目标是两周内做出一个能回答真实问题的原型。按下面的顺序读，不要求你理解每一个公式，但要求你把命令真的敲一遍。

第二种：完整路径。 从序章到第八部分顺序读，每节动手。大约需要 6–10 周，取决于你能投入的时间。第七部分需要云 GPU，可以集中几天做完。

第三种：按问题查。 你已经在做项目，遇到具体问题时翻目录。这种读法最容易断章取义，建议至少先读 1.4（KV Cache）和 1.6（显存估算），这两节是后面所有"为什么跑不动"的解释基础。

不论哪种读法，有一件事不能省：序章的 0.3（硬件与环境）。不然后面看到的每个性能数字，你都分不清是模型的属性还是机器的属性。

正文的写法是固定的，知道结构能帮你快速定位：

「动手实验」不是省略，是刻意的设计。一台 M4、一个引擎版本、一份权重，组合起来的结果只对这套组合负责。本书不替你编造结果——你用自己的机器跑出来的数字，才是你能拿去做决策的数字。

书里出现的每个数字都带来源标记，只有三种：

估算：从公式或已知参数推出来的，写法如"约 21 token/s 的理论上限（估算）"。估算会给出推导过程，你可以换参数重算。
引用：来自论文、官方文档、模型卡或协议原文，写法如"120 GB/s（引用 [1]）"，编号对应本节末尾的参考资料。二手博客和榜单截图不作为引用来源。
实测：在明确写出的硬件、软件版本和命令下测出来的，写法如"（实测，见 benchmarks/…）"。原始数据放在仓库的 benchmarks/ 目录，正文只放结论。

这条规矩看似麻烦，但它解决一个很实际的问题：半年后你回来看，能立刻知道哪个数字可以信、哪个数字需要重测。同理，本书不使用 emoji 做标记——正式文档里，文字比符号清楚。

先别怀疑自己。按下面的顺序排查，绝大多数差异能解释：

差异现象	先检查	说明
输出内容不同，但质量相当	采样参数（temperature、top-p、seed）	生成是随机的，默认参数下逐字一致不现实
速度差 2 倍以上	是否用了 GPU 卸载（`-ngl`）、线程数、内存压力	Mac 上 swap 会让速度断崖下跌
模型加载失败或输出乱码	引擎版本、GGUF 文件是否完整、对话模板	新架构需要较新的 llama.cpp
内存占用差很多	上下文长度（`-c`）、批大小（`-ub`）、KV Cache 类型	这三项直接决定 KV 占用
中文效果明显更差	是否用了 instruct 版本、是否套了正确的对话模板	base 模型不会"回答问题"，只会续写

如果排查完还是对不上，记下你的硬件、版本、命令和输出，作为一条独立结论保留。不一致本身也是信息，它往往指向某个版本或平台的特殊行为。涉及模型自身的配置（上下文上限、思考模式、对话模板）时，以模型卡为准（引用 [2]）。

目录	用途
`docs/`	正文。侧边栏就是目录，章节顺序即阅读顺序
`labs/`	与章节对应的可运行脚本，按部分编号组织
`benchmarks/`	原始测量数据（CSV/JSON）与画图脚本
`corpus/`	公开语料清单（`sources.yaml`）与下载脚本，不存正文
`eval/`	测试问题集：v1 80 题（第五部分）、v2 300 题（第六部分）

书里的命令默认在仓库根目录执行。涉及模型下载的命令会注明大小，方便你判断磁盘和时间成本。

这本书的目标不是让你"知道大模型是怎么回事"，而是让你在客户现场被问到"为什么这么慢""为什么答错了""能不能下周上线"时，能给出有依据的回答。所以，读到任何一节，都问自己一个问题：这一节的知识，能让我做出哪个决定？

答不上来的部分，可以先跳过；答得上来的部分，动手验证一遍。