手撕实现¶
这里的代码用于固定数学、shape 与状态语义。它比伪代码完整，比生产框架短：只保留不可替代的核心逻辑、退化分支和最小断言，再把性能优化留给专用 kernel 与运行时。
阅读约定¶
每个实现都回答六个问题：
- 输入、输出与状态 shape 是什么；
- 公式里的归一化轴和 mask 在哪里；
- 哪些边界条件必须显式处理；
- 怎样与手算或框架 reference 对照；
- 哪些语义可优化、哪些不可改变；
- 代码在哪个规模以后不再适合直接使用。
代码以 Python 与 PyTorch reference 为主。低效的显式展开若能让语义更清楚，会被有意保留；正文同时指出生产实现应怎样避免复制、同步或无界循环。
代码放在哪里¶
通用原子实现与对应知识点共址：公式刚定义完，最短的主路径就默认展开，读者可以逐行对齐变量、shape 和 mask。完整测试、辅助类、替代实现或较长状态转移按内容命名并默认折叠；折叠标题本身是稳定链接，可以从其他章节直接抵达。
本页以下地图聚合这些入口，专题实践则负责跨机制组装与更完整的验证。为保持实验可独立运行，实践代码可以重述必要的原子逻辑；它应链接对应正文并复用相同不变量。论文深读聚焦工作的特有改动，系统页则说明优化后仍必须满足的语义。
实现地图¶
| 组合实验 | 正文中的语义核 | 主要不变量 |
|---|---|---|
| Tokenizer | BPE merge rank、Unigram Viterbi | round-trip、merge rank、兼容性 |
| 张量原语 | token CE、Decoder Block、RoPE、GQA、online softmax | 数值稳定、mask、head 映射 |
| Decoder-only Transformer | block、增量解码 | 因果性、位置、训练—增量一致 |
| 递推与记忆 | selective scan、kNN memory | chunk 等价、reset、状态容量 |
| 训练目标 | AdamW、LoRA、蒸馏、奖励模型、DPO | mask、归一化、reference 与 behavior |
| LLM 策略优化 | GAE、GRPO、ratio gate | action mask、四策略身份、归约与 gate |
| 分布式与容错 | 全局 token loss、tensor parallel、MoE dispatch、checkpoint | 全局语义、顺序、原子提交 |
| 推理引擎 | KV COW、runtime、量化、推测解码 | COW、幂等、精确分布 |
| 检索与智能体 | 索引、重排、工具调用、事件归约 | 权限前置、去重、终态 |
| 推理时计算 | 采样与预算、搜索与验证 | canonical answer、verifier、预算 |
| 多模态 | patchify、坐标、mask 与 loss、RVQ、video tubelet | 坐标、mask、模态归一、采样 |
| 评测工具 | 语言模型、统计推断、校准、judge、事实性、安全 | 配对、分层、分母与缺失值 |
这些页面不是独立项目模板。需要训练器、服务端、配置系统或部署脚手架时，应选成熟框架；需要核对某个公式、排查 shape 或验证优化前后等价时，先回到这里。
验证阶梯¶
实现按相同顺序升级：
- 手算或解析结果；
- FP64 小张量与退化输入；
- 框架 reference；
- 自定义向量化实现；
- mixed precision；
- backward 与梯度检查；
- 分布式切分；
- 真实 shape 的正确性；
- 端到端质量；
- 性能与资源。
第 4 层更快不代表第 1–3 层可以跳过。若最终 logits 偏差过大，应回到第一个分叉点，而不是直接放宽端到端容差。
代码边界¶
- 示例不包含 CLI、配置加载、日志平台和训练框架封装；
- 随机算法显式传 generator 或 seed；
- 归一化、reduction、mask 与 dtype 不使用含糊默认值；
- 无定义的退化情况抛错或返回明确状态；
- “成功”由断言或环境状态判断，不由打印文本声明；
- 性能代码必须保留一个更慢、更直白的 reference。
实验设计见实验方法，从 loss 到系统逐层排错见调试手册。