---
tags: [nanochat, MOC, inference]
阶段: 09-推理Engine与工具
难度: ★★★
created: 2026-10-22
related: "[[KV Cache原理]], [[自回归解码与prefill-decode]], [[部署与成本]], [[工具调用与Python沙箱]]"
---

# MOC · 推理Engine与工具

> [!summary] 本阶段地图
> 本阶段共 5 篇笔记，建议投入 10 至 12 小时。目标是建立一条从「生成协议」到「成本数字」的完整链路：读完后能说清 `Engine.generate` 的每一次 `yield` 对应哪一步计算，KV 缓存为什么能把 decode 从重算前缀变成读缓存，工具状态机在什么条件下注入强制 token，`chat_cli` 的对话历史如何拼接，以及一次 speedrun 的 \$48 与每百万 token 的几美分至几十美分之间是什么关系。本阶段不重复 Transformer 结构（见 04）与评测协议（见 08），只讲推理运行时的实现、边界与代价。

本阶段处在全书的执行层。向前，它消费 04 的注意力实现、05 的检查点、06 的对话格式与 07 的 rollout 需求；向后，它为 10 的复现实验提供「跑起来要多少显存、多少时间、多少钱」的度量。它回答的问题可以压缩成一句：一个已经训练好的检查点，如何以可接受的速度与成本产生 token。这个问题不能由 loss 或 CORE 回答，因为它们只说明模型是否聪明，不说明运行它要付多少代价；`scripts/infer_bench.py` 的注释把这一点写得很直接：智能指标不说明模型运行起来有多贵，架构选择会在这里显现。

```mermaid
flowchart LR
    A[KV Cache原理<br/>缓存结构与字节公式] --> B[自回归解码与prefill-decode<br/>两阶段、采样与生成器协议]
    B --> C[工具调用与Python沙箱<br/>三态状态机与执行边界]
    C --> D[CLI与WebUI<br/>进程边界、SSE 与会话]
    B --> D
    D --> E[部署与成本<br/>显存、吞吐与美元]
    A --> E
    F[04 FlashAttention与高效注意力] --> A
    G[08 GSM8K与HumanEval] --> C
    H[10 跑通speedrun脚本] --> E
    B --> I[跨库 模型推理优化]
    E --> J[跨库 成本-延迟-质量权衡]
```

图中实线是阅读依赖：缓存结构先于两阶段调度，两阶段先于工具状态机与传输层，容量与吞吐最终汇成成本。指向阶段外的边是使用关系：04 的 [[FlashAttention与高效注意力]] 给出 FA3 的窗口与原地缓存接口，08 的 [[GSM8K与HumanEval]] 给出沙箱的评测侧用法，10 的 [[跑通speedrun脚本]] 给出训练成本与产物。跨库的 [[模型推理优化]] 与 [[成本-延迟-质量权衡]] 提供通用方法，本阶段只保留 nanochat 的取值与代码位置。

## 本阶段要回答的五个问题

整阶段的材料围绕五个问题组织，五篇笔记各自回答其中一个，并在接口处互相引用。

1. 一个 token 的生成成本由什么决定。答案不是「参数量」，而是「每步必须搬运的字节数」：权重、KV 缓存与批大小共同决定 decode 的时间下界，prefill 的算力决定首 token 延迟。

2. 缓存为什么能复用，代价是什么，何时失效。答案是历史位置的 K/V 与当前查询无关；代价是显存随 $B\cdot T$ 线性增长；失效条件是位置编码或掩码不再只依赖绝对位置。

3. 模型如何把控制权交给运行时，运行时如何避免执行任意代码。答案是 9 个特殊 token 与三态状态机；对话侧只走计算器白名单，完整程序执行走独立沙箱，两者不是同一套边界。

4. 一个进程如何把流式 token 交给用户，多个用户如何共享 GPU 而不互相污染。答案是生成器协议、会话锁与并发信号量；当前 `Engine` 没有请求级调度器，因此共享只到「限流与排队」这一层。

5. 一张卡能跑多大模型、多少并发、每百万 token 多少钱。答案是权重、KV、roofline 与卡时价格四个量的乘积；其中前三个由架构与实现决定，最后一个由市场决定。

## 学习顺序与理由

1. [[KV Cache原理]]：先读缓存。它给出 `KVCache` 的形状 `(L, B, T, H_{kv}, D)`、每 token 字节公式、`kv_read_bytes` 的窗口截断与 prefill 复制逻辑。先读它的理由是：后续四篇都默认读者知道「decode 每步只算一个新 token、历史 K/V 从缓存读取」这一前提；不知道缓存形状，就无法理解 `Engine.generate` 为什么要先做 batch=1 的 prefill 再复制，也无法解释 `infer_bench` 的 `kv_bytes_per_token` 与 `kv_read_bytes` 为什么是两个不同的量。该篇已按 512 的短窗口口径写好，本篇不再改写。

2. [[自回归解码与prefill-decode]]：再读两阶段与生成协议。它把概率分解、prefill 的并行性、decode 的 roofline、TTFT/TPOT、采样与 `Engine.generate` 的七步协议串起来。放在第二位的理由是：它是本阶段的主干，工具状态机与 CLI 都是它的下游；`generate` 的 `yield (token_column, token_masks)` 协议是后面所有封装的接口契约。读完这一篇，应能解释为什么 decode 要 batch、为什么 `B^{*}=w/K(T)` 是吞吐拐点、为什么 `temperature=0` 才能做逐 token 等价性比较。

3. [[工具调用与Python沙箱]]：进入运行时分支。它讲 9 个特殊 token、`render_conversation` 的 mask、`in_python_block` 与 `forced_tokens` 组成的三态、`use_calculator` 的两条白名单，以及 `execution.py` 的子进程隔离与未覆盖项。放在第三位的理由是：状态机嵌在 decode 循环内部，必须先理解 `token_column` 与 `token_masks` 的语义，才能理解「强制 token 记 0、采样 token 记 1」为什么要一路传到 RL 与评测。读完这一篇，应能判断一个工具路径是走计算器还是走沙箱，并说出两者的安全边界差别。

4. [[CLI与WebUI]]：把生成器接到进程与网络。它讲 `chat_cli.py` 的 7 个参数、对话 token 拼接、流式解码、退出条件、当前 master 没有 WebUI 的证据，以及 FastAPI + SSE 的最小封装。放在第四位的理由是：CLI 直接消费 `Engine.generate`，Web 封装则要额外处理会话、并发、缓存释放与限流；没有前两篇的协议与状态机，就无法判断封装层哪些状态该保留、哪些该丢弃。读完这一篇，应能写出一个不会泄漏缓存的 SSE 端点，并解释为什么当前 `Engine` 不适合直接做多会话缓存复用。

5. [[部署与成本]]：最后算账。它给出权重、KV、激活的显存公式，batch 与吞吐的权衡，`infer_bench` 的 TTFT、TPOT、tok/s、MBU、MFU 与峰值显存，GPU 小时与每百万 token 的换算，训练与推理的量级对比，以及硬件—模型—上下文—batch 的可行性表。放在最后的理由是：成本是前四篇所有选择的函数；没有缓存字节、roofline 与并发模型，成本表只能是一组无法追溯来源的数字。读完这一篇，应能由一张卡的带宽与价格推出 batch=8 的每百万 token 成本，并说明该数字依赖哪些假设。

不建议把顺序改为「先读部署与成本」。成本篇的每个公式都引用了前四篇的定义：没有 `K(T)` 就无法算容量，没有 TTFT/TPOT 就无法把延迟换算成 batch，没有 `infer_bench` 的指标口径就无法解释表中数字。也不建议把 [[CLI与WebUI]] 提前到工具篇之前：CLI 的流式循环会触发计算器路径，若不知道 `signal.signal` 的线程限制与 `token_masks` 的语义，就无法解释为什么 Web 服务里的工具调用会静默失效。

## 笔记索引

| 笔记 | 难度 | 核心问题 | 读完应能 | 关键 repo 位置 |
|---|---|---|---|---|
| [[KV Cache原理]] | ★★★ | decode 为什么能只算一个 token，缓存占多少显存 | 推导缓存复用条件；写出字节公式；解释 prefill 复制与 `advance` 只在最后一层执行 | `nanochat/engine.py` 的 `KVCache`；`nanochat/gpt.py` 的 `kv_bytes_per_token`、`kv_read_bytes` |
| [[自回归解码与prefill-decode]] | ★★★ | 两阶段的并行度差异如何决定 TTFT、TPOT 与吞吐 | 写出概率分解与 roofline；手算 d24 的 TTFT/TPOT；解释生成器七步协议与等价性测试 | `nanochat/engine.py` 的 `sample_next_token`、`Engine.generate`；`scripts/infer_bench.py` |
| [[工具调用与Python沙箱]] | ★★★ | 模型如何调用计算器，任意 Python 代码如何被隔离 | 画出三态状态机；复述计算器白名单；列出沙箱能挡与挡不住的用例；给出加固方案 | `nanochat/engine.py` 的 `use_calculator`；`nanochat/execution.py`；`tasks/humaneval.py` |
| [[CLI与WebUI]] | ★★☆ | 对话历史如何拼接，如何把流式生成接到 HTTP | 写出多轮 token 形态；解释 `chat_cli` 参数与退出条件；给出 SSE 封装与并发控制 | `scripts/chat_cli.py`；`nanochat/checkpoint_manager.py` |
| [[部署与成本]] | ★★★ | 一张卡能跑多大模型、多少并发、每百万 token 多少钱 | 算权重与 KV 显存；算 batch 与吞吐；读 `infer_bench` 输出；换算 \$/百万 token | `scripts/infer_bench.py`；`nanochat/gpt.py` 的成本函数；`nanochat/common.py` 的 `get_peak_bandwidth` |

五篇之间的接口是四个可核对的对象，而不是概念上的引用。

第一，生成器协议。[[自回归解码与prefill-decode]] 定义 `Engine.generate` 每次 `yield` 两个列表：`token_column` 是每行本步实际写入的 token，`token_masks` 是「采样为 1、强制为 0」的标记。[[工具调用与Python沙箱]] 往 `token_column` 里注入强制 token，[[CLI与WebUI]] 只取第 0 行并解码，[[部署与成本]] 的 `infer_bench` 只数 `next()` 的次数。四个消费者对同一协议的不同切面，任何一方改变返回形状都会破坏其余三篇的例子。

第二，特殊 token 表。9 个 token 由 [[工具调用与Python沙箱]] 完整列出，[[CLI与WebUI]] 只使用其中 5 个（BOS、user 两端、assistant 两端），[[自回归解码与prefill-decode]] 在 `Engine.generate` 里使用全部工具 token 与终止 token。对话历史的合法性由这张表与 `render_conversation` 的 mask 共同保证。

第三，缓存形状。`KVCache` 的 `(L, B, T, H_{kv}, D)`、`cache_seqlens` 的 int32 类型与 `prev_embedding` 的语义由 [[KV Cache原理]] 给出；[[自回归解码与prefill-decode]] 用它解释 prefill 复制；[[部署与成本]] 用它算容量；[[CLI与WebUI]] 用它说明「每会话一份缓存」的必要性。

第四，`infer_bench` 的末行 JSON。[[部署与成本]] 逐字段解释 `ttft_sec`、`tpot_sec`、`tok_per_sec`、`mbu_percent`、`peak_vram_bytes`；08 阶段的 [[生成report成绩单]] 消费同一份 JSON；[[自回归解码与prefill-decode]] 用 `num_steps = decode_tokens - 1` 解释它为什么与朴素计数差一。

## 阶段产物地图

本阶段的验证不依赖训练，只需要一个检查点。四条命令覆盖全部产物：

```bash
# 1) 单元测试：缓存、采样协议、沙箱与计算器（沙箱测试需要 POSIX）
python -m pytest tests/test_engine.py tests/test_execution.py -v

# 2) 交互：单轮或 REPL；-p 只回答一次
python -m scripts.chat_cli -i sft -g d24 -p "Why is the sky blue?" -t 0.6 -k 50

# 3) 推理基准：TTFT、TPOT、tok/s、MBU、峰值显存，末行是 JSON
python -m scripts.infer_bench -i sft -g d24 --batch-sizes 1,8,32,128

# 4) 评测侧沙箱：HumanEval 复用 execution.py
python -m scripts.chat_eval -i sft -a HumanEval -n 1 -m 512
```

| 产物 | 生成者 | 位置 | 主要字段 | 消费方 |
|---|---|---|---|---|
| 单元测试结果 | `tests/test_engine.py`、`tests/test_execution.py` | pytest stdout | 通过/失败、断言消息 | 回归检查 |
| 对话输出 | `chat_cli.py` | stdout | 横幅、`Assistant:` 流式文本 | 人工验证 |
| 推理 JSON | `infer_bench.py` | stdout 最后一行 | `prefill`、`sweep`、`weight_bytes`、`kv_bytes_per_token` | 成本表、成绩单 |
| HumanEval 准确率 | `chat_eval.py` + `tasks/humaneval.py` | stdout | 每题通过与否、最终百分比 | 评测报告 |
| 检查点 | `base_train` / `chat_sft` / `chat_rl` | `~/.cache/nanochat/*_checkpoints/` | `model_*.pt`、`meta_*.json` | 上述全部 |

路径根目录由 `nanochat/common.py` 的 `get_base_dir` 决定，默认 `~/.cache/nanochat`，可用 `NANOCHAT_BASE_DIR` 覆盖。`chat_cli` 的 `source` 映射为 `base_checkpoints`、`chatsft_checkpoints`、`chatrl_checkpoints` 三个目录；`model_tag` 为空时按 `d<数字>` 取最大深度，若都不匹配则取最近修改的一个；`step` 为空时取最后一个。这些「猜测」在同时存在多个深度的检查点时最容易评错模型，复现他人结果时应显式传 `-g` 与 `-s`。

## 符号约定与关键事实

| 事实 | 取值 | 可核对位置 |
|---|---|---|
| d24 参数量 | 1,384,122,122 | `GPTConfig(n_layer=24)` 构建后 `sum(p.numel())` |
| d24 权重（bf16 推理口径） | 4,227,865,640 B，约 3.94 GiB | 参数量按各组 dtype 加权；`Linear` 前向临时 cast |
| KV/token（d24、bf16） | 147,456 B，即 144 KiB | `GPT.kv_bytes_per_token()` |
| KV@2048（单序列） | 288 MiB | $147{,}456\times2048$ |
| 单行 decode 读取 @2048 | 132,120,576 B，约 126 MiB | `GPT.kv_read_bytes(2048)`，按 `SSSL` 窗口截断 |
| 单步 decode FLOPs @2048 | 1,591,741,872 | `GPT.estimate_decode_flops(2048)` |
| prefill FLOPs @2048 | 3,168,148,488,192 | `GPT.estimate_prefill_flops(2048)` |
| 短窗口实际值 | 512（表达式 `-(-L//4//128)*128`） | `gpt.py` 的 `_compute_window_sizes`；注释写 768 是滞后 |
| 窗口层数（d24） | 18 层短窗口、6 层全窗口 | `SSSL` 平铺，最后一层强制 L |
| H100 峰值带宽 / 算力 | 3.35 TB/s / 989 TFLOPS | `common.py` 的 `get_peak_bandwidth`、`get_peak_flops` |
| H100 算力带宽比 | 约 295 FLOP/字节 | $989\times10^{12}/3.35\times10^{12}$ |
| 吞吐拐点 $B^{*}$ | 约 32（d24、2048） | $w/K(2048)$ |
| TTFT 示例 | 6.98 ms（1792 token、40% MFU） | $2.76$ TFLOP 除以 $0.4\times989$ TFLOPS |
| TPOT 示例 | 2.61 ms（batch=8、60% MBU） | $(w+8K(1920))/(0.6\,\mathrm{BW})$ |
| speedrun 成本 | 约 \$48（8 卡、2 小时、\$3/卡·小时） | README |
| 最快 leaderboard | 1.65 小时，CORE 0.2626 | README |
| 训练上下文 | 2048 | `GPTConfig.sequence_len` |
| chat 生成默认 | 256 token、温度 0.6、top-k 50 | `chat_cli.py` 的 `generate_kwargs` |
| 计算器超时 | 3 秒 | `eval_with_timeout` 的 `max_time=3` |
| 沙箱预算 | 5 秒、256 MB | `execute_code` 的默认参数 |

表中「权重」「KV」「FLOPs」三组数字在本库的其他笔记中反复出现，口径必须一致：权重按存储 dtype 计，KV 按 `COMPUTE_DTYPE` 计，FLOPs 是前向单次而非训练的反向加三倍。把训练口径的 $6P$ 用到推理上，会高估 decode 的计算量三倍；把参数乘 2 当作权重，会低估 d24 的显存约 35%。

## 源码地图

| 文件 | 关键对象 | 本阶段用途 |
|---|---|---|
| `nanochat/engine.py` | `KVCache`、`sample_next_token`、`RowState`、`Engine.generate`、`Engine.generate_batch` | 生成协议、缓存、采样、工具状态机、批量返回 |
| `nanochat/gpt.py` | `CausalSelfAttention.forward`、`GPT.forward`、`generate`、`estimate_*_flops`、`kv_*_bytes` | 单 token 前向、RoPE 偏移、smear、成本函数 |
| `nanochat/execution.py` | `GUARD`、`execute_code`、`ExecutionResult` | 子进程沙箱与资源限制 |
| `nanochat/tokenizer.py` | `SPECIAL_TOKENS`、`render_conversation`、`encode_special` | 对话与工具 token 的协议 |
| `scripts/chat_cli.py` | 参数解析、对话拼接、流式打印 | 进程内的最小交互形态 |
| `scripts/infer_bench.py` | `bench_generate`、`weight_bytes`、静态卡、batch 扫描 | TTFT/TPOT/MBU/MFU/显存 |
| `scripts/chat_eval.py` | `run_generative_eval`、`run_categorical_eval` | 生成式评测与沙箱复用 |
| `tasks/humaneval.py` | `evaluate` | 程序拼接与 `execute_code` 判分 |
| `tests/test_engine.py`、`tests/test_execution.py` | 协议与沙箱回归 | 可复现的验收 |

## 三条阅读路径

| 路径 | 顺序 | 适用读者 |
|---|---|---|
| 最短闭环 | [[KV Cache原理]] → [[自回归解码与prefill-decode]] → [[部署与成本]] | 想尽快跑通推理并估算成本 |
| 工程实现 | [[KV Cache原理]] → [[自回归解码与prefill-decode]] → [[工具调用与Python沙箱]] → [[CLI与WebUI]] → [[部署与成本]] | 要改 `Engine`、加工具或写服务 |
| 评测与复现 | [[工具调用与Python沙箱]] → [[自回归解码与prefill-decode]] → 08 的 [[GSM8K与HumanEval]] → [[部署与成本]] | 关注 HumanEval 与成绩单口径 |

三条路径都建议先运行 `python -m pytest tests/test_engine.py -v`。这组测试不需要 GPU 与检查点，用 Mock 模型验证缓存形状、首 token 多样性、seed 可复现、温度 0 的确定性、`max_tokens` 与 `num_samples`；它是最便宜的协议检查。`tests/test_execution.py` 需要 POSIX 的 `resource`，在 Windows 上会失败，属于平台限制而不是代码缺陷。

## 与相邻阶段的边界

| 相邻阶段 | 本阶段负责 | 相邻阶段负责 |
|---|---|---|
| 04 Transformer 架构 | `CausalSelfAttention` 的推理路径与窗口参数如何使用 | RoPE、QK norm、GQA、FA3/SDPA 回退的完整推导 |
| 05 预训练 | 检查点加载后的推理配置与显存口径 | CORE、bpb、speedrun 与训练成本 |
| 06 SFT | 工具 token 的推理时状态机 | `render_conversation` 的训练侧 mask 与数据混合 |
| 07 RL | rollout 使用的 `generate_batch` 与 seed 语义 | REINFORCE、reward、pass@k 的训练侧使用 |
| 08 评测 | HumanEval 执行沙箱的参数与边界 | 任务判分、ChatCORE 聚合与成绩单 |
| 10 复现 | 推理基准与成本估算的字段 | 环境搭建、speedrun 全流程、故障树 |

边界的判据是「是否出现新的运行时决策」。缓存如何分配、工具 token 如何注入、会话如何隔离、并发如何限流，这些是本阶段的决策；模型为什么这样设计、数据如何构造、指标如何聚合，属于相邻阶段。

## 版本说明

本阶段涉及两处版本差异，必须在引用旧材料时标注。

第一，当前 master 的短窗口是「四分之一上下文再向上取整到 128 的倍数」，2048 上下文得到 512；`gpt.py` 的注释仍写 `2048 -> 768`，`dev/LOG.md` 2026-01-11 的条目写 `sequence_len // 2`。以当前表达式为准，注释与旧日志只作历史参考。

第二，当前 master 没有内置 WebUI。`dev/LOG.md` 2026-03-04 的条目在列举被修改文件时仍提到 `chat_web.py`，说明它曾经存在；当前 `scripts/` 与 README 文件结构都没有它。不要把旧版本的 Web 入口、参数或截图当作现状。

## 三个必须先记住的数字

本阶段的推导都可以由三个数字串起来。记住它们，其他公式可以在需要时推出。

第一个是 144 KiB。它是 d24 在 bf16 下每个 token 的 KV 缓存字节数，由 $24\times2\times12\times128\times2=147{,}456$ 字节得到。乘上 2048 上下文得到 288 MiB/序列，乘上并发数得到总缓存。这个数字决定了「一张卡能同时服务多少条流」，也决定了 `infer_bench` 的 `max_rows` 为什么是几百而不是几千。它的口径是存储字节；decode 每步的读取字节还要按 `SSSL` 窗口截断，2048 上下文下是 126 MiB，比存储字节少一半。

第二个是 32。它是 d24 在 2048 上下文下的吞吐拐点 $B^{*}=w/K(2048)$，即权重字节 4.23 GB 除以单行读取 132 MB。batch 小于 32 时，增加 batch 几乎不增加每步字节，吞吐近似线性上升；大于 32 后，新增读取主要来自 KV 缓存，吞吐增益递减而 TPOT 继续上升。这个数字决定了「batch 应该开到多大」：在延迟允许的范围内开到拐点附近，而不是盲目开到显存上限。

第三个是 295。它是 H100 的算力带宽比，即 989 TFLOPS 除以 3.35 TB/s。decode 的算术强度约 0.3 至 0.4 FLOP/字节，比 295 低约三个数量级，因此 decode 是带宽受限的；prefill 的算术强度随提示长度增长，1792 token 时约 630 FLOP/字节，已经高于 295，因此 prefill 是算力受限的。同一个模型、同一张卡，两个阶段的瓶颈不同，优化手段也不同：decode 靠 batch 与减少字节，prefill 靠提高 MFU 与减少计算。

## 常见失败模式索引

下表把「现象」映射到最可能的机制与对应笔记，用于排查而不是替代推导。

| 现象 | 最可能的原因 | 对应笔记 |
|---|---|---|
| 首 token 很慢，后续 token 正常 | prefill 长、排队、缓存分配或首次采样 | [[自回归解码与prefill-decode]] |
| 输出速度慢但 GPU 利用率很低 | batch=1，decode 受带宽限制 | [[部署与成本]] |
| 多采样时首 token 全部相同 | 预填充 logits 被广播而非逐行采样 | [[自回归解码与prefill-decode]] 的测试 |
| 同 seed 两次结果不同 | 生成器未重置、温度大于 0 或并发共享 RNG | [[自回归解码与prefill-decode]] |
| 工具调用没有输出 | 表达式被白名单拒绝、超时或线程中 SIGALRM 失效 | [[工具调用与Python沙箱]] |
| 工具输出被算进损失 | 强制 token 的 mask 语义被当成 1 | [[工具调用与Python沙箱]] |
| Web 服务显存持续增长 | 客户端断开后生成器未 `close()` | [[CLI与WebUI]] |
| CPU 或 Windows 上沙箱失败 | Windows 缺少 `resource`；CPU 上可运行 | [[工具调用与Python沙箱]] |
| 按 `max_rows` 配置并发却 OOM | 未扣激活、CUDA 上下文与预填充缓存 | [[部署与成本]] |
| TTFT 与他人结果不可比 | 提示被夹到 1792 或上下文设置不同 | [[部署与成本]] |
| 温度大于 0 时逐 token 对比失败 | 两实现的随机数消耗序列不同 | [[自回归解码与prefill-decode]] |

这张表的使用方式是「先定位阶段，再回对应笔记看公式」。例如「输出速度慢但 GPU 利用率低」不应先怀疑模型，而应先看 batch 与 MBU；「工具没有输出」不应先怀疑数据，而应先看 `use_calculator` 的返回值与运行线程。

## 实验清单

以下六个实验按成本从低到高排列，全部可在一张消费级 GPU 或 CPU 上完成，除第三个需要 CUDA。

1. 跑 `tests/test_engine.py`，记录 8 个测试的通过情况；把 `max_tokens` 改成 1 与 64 各跑一次，观察 `generate_batch` 返回长度与终止 token 过滤的差别。这个实验验证协议，不需要检查点。

2. 用 `chat_cli -p` 在同一提示、`temperature=0` 下跑两次，比较输出是否逐字相同；再用 `temperature=0.6` 跑两次，比较差异。这个实验验证采样与 seed 的语义。

3. 用 `infer_bench` 扫描 `1,8,32,128`，从末行 JSON 取出 `ttft_sec`、`tpot_sec`、`tok_per_sec`、`mbu_percent`、`peak_vram_bytes`，用 [[自回归解码与prefill-decode]] 与 [[部署与成本]] 的公式手算一遍 MBU，比较误差。这个实验验证指标口径。

4. 用 `execute_code` 跑「正常程序、除零、死循环、1 GB 分配、`os.system`、绝对路径读」六个用例，记录 `success`、`timeout`、`memory_exceeded` 与 `error`；再跑 `os._exit(0)`，观察 `success=True` 但测试未执行。这个实验验证沙箱边界。

5. 用 [[部署与成本]] 的成本脚本计算 d24 在 batch=8 下的每百万 token 成本，再与 `infer_bench` 的 `tok_per_sec` 和当时 GPU 的租赁价格对照；改变 MBU 从 0.4 到 0.8，观察成本变化。这个实验验证成本模型对利用率假设的敏感性。

6. 用 [[CLI与WebUI]] 的 FastAPI 骨架起两个会话，并发发起请求，观察 `session busy` 与 `503` 的触发；在流式中途断开客户端，用 `nvidia-smi` 观察显存是否回落。这个实验验证并发控制与缓存生命周期。

## 术语表

| 术语 | 一句话定义 | 出现笔记 |
|---|---|---|
| prefill | 对提示做一次并行前向并写满 KV 缓存 | 自回归、部署 |
| decode | 每次只前向一个新 token 并读取缓存 | 自回归、部署 |
| TTFT | 请求到第一个输出 token 的时间 | 自回归、CLI、部署 |
| TPOT | 相邻输出 token 的时间，基准取中位数 | 自回归、部署 |
| MBU | 解码实际带宽与峰值带宽之比 | 部署 |
| MFU | 实际浮点吞吐与峰值算力之比 | 部署、自回归 |
| 强制 token | 由运行时写入、mask 为 0 的工具输出 token | 工具、CLI |
| 会话 | 历史、参数与可选缓存的容器 | CLI |
| 沙箱 | 用独立子进程与资源限制执行代码的设施 | 工具 |
| 行状态 | `RowState`，每行的完成标记、工具块与强制队列 | 工具、自回归 |

## 阶段验收流程

完成本阶段后，按以下顺序验收，避免「读过但跑不通」。

1. 在 Linux 或 macOS 上跑 `python -m pytest tests/test_engine.py tests/test_execution.py -v`，确认 8 个引擎测试与 9 个沙箱测试函数（其中破坏性用例参数化为 5 条）的行为符合预期；Windows 上沙箱测试会因缺少 `resource` 失败，记录平台限制即可。

2. 用 `chat_cli -i sft -p "Why is the sky blue?"` 做一次单轮对话，确认横幅、`Assistant:` 流式输出与退出行为；再进 REPL，测试 `clear` 与 `quit`。

3. 用 `infer_bench` 跑一次 batch 扫描，把末行 JSON 保存下来；用成本脚本复算 `weight_bytes`、`kv_bytes_per_token`、`max_full_context_rows` 与 `ceiling_bs1_tok_per_sec`，与 JSON 对齐。

4. 用 `execute_code` 跑沙箱能力表，把「挡得住」与「挡不住」各记录至少三条；对每条「挡不住」写明绕过了哪一层。

5. 用 FastAPI 骨架起服务，两个会话并发，确认同一会话返回 429、超过并发返回 503、断开后显存回落。

6. 把以上产物写入 10 阶段的 [[实验记录模板]]：命令、commit、GPU 型号、检查点、batch、TTFT、TPOT、tok/s、MBU、峰值显存、成本假设。缺少任何一项，结果都不可复现。

验收的判据不是「数字好看」，而是「每个数字都能追溯到命令与公式」。若一个数字来自他人截图或旧版本 README，标注来源与版本，不要与本阶段的实测并列。

## 本阶段不重复的内容

| 内容 | 完整讲解所在 | 本阶段只保留 |
|---|---|---|
| 自注意力、多头、RoPE、FA3 原理 | 04 的 [[自注意力机制]]、[[多头注意力]]、[[FlashAttention与高效注意力]] | 推理路径的调用点与窗口参数 |
| 缩放定律、CORE、bpb、speedrun 全流程 | 05 的 [[CORE指标]]、[[训练脚本与speedrun]] | 检查点加载后的推理配置与成本口径 |
| 对话数据、`render_conversation` 训练侧 mask | 06 的 [[有监督微调SFT]]、[[从生成式到对话式]] | 推理时工具 token 的注入 |
| REINFORCE、GRPO、reward | 07 的 [[GRPO原理与实现]] | rollout 使用的 `generate_batch` 协议 |
| ChatCORE、任务判分、成绩单 | 08 的 [[评测方法论]]、[[GSM8K与HumanEval]] | HumanEval 执行沙箱的参数与边界 |
| 量化、连续批处理、KV 分页 | 跨库 [[模型推理优化]] | nanochat 当前没有实现的边界 |
| 缓存推导、字节公式、prefill 复制 | [[KV Cache原理]] | 与两阶段调度、成本的接口 |

这张表也是「禁止重复」的边界：若某段内容在本阶段出现第二次，应改为一句结论加双链，而不是重新推导。唯一例外是 KV 缓存的字节数，它在 [[KV Cache原理]]、[[自回归解码与prefill-decode]] 与 [[部署与成本]] 中各出现一次，因为三处的用途不同：结构、调度、预算。

## 达标清单

- [ ] 能写出 d24 的参数量、权重字节、KV/token、单序列 2048 上下文 KV，并说明每个数字的 dtype 口径。
- [ ] 能写出自回归分解、prefill/decode 的 FLOPs 公式与单步时间下界。
- [ ] 能解释 `Engine.generate` 的七步协议，指出第一次与最后一次 `next()` 各做了什么。
- [ ] 能说明 `token_column` 与 `token_masks` 的语义，以及强制 token 为什么记 0。
- [ ] 能画出工具三态状态机，并列出计算器白名单的接受与拒绝规则。
- [ ] 能说出 `execution.py` 的七层隔离与至少四条未覆盖项，并给出生产加固方案。
- [ ] 能写出多轮对话的 token 形态，解释为什么结束时必须补 `<|assistant_end|>`。
- [ ] 能说明当前 master 没有 WebUI 的证据，并给出一个带会话锁与并发上限的 SSE 方案。
- [ ] 能由 `infer_bench` 的输出读出 TTFT、TPOT、tok/s、MBU、峰值显存，并指出 `steps=255` 的原因。
- [ ] 能用带宽与价格算出 batch=8 的每百万 token 成本，并说明该数字依赖的假设。
- [ ] 能指出 `infer_bench` 默认提示被夹到 1792、`max_rows` 未扣 reserve 这两处口径陷阱。
- [ ] 能说明一次 speedrun 的 \$48 与一批推理的成本量级差异，以及为什么算力差 100 倍而成本差不到 1 倍。

## 参考来源

- Karpathy, *nanochat*（commit 92d63d4），README、`nanochat/engine.py`、`nanochat/gpt.py`、`nanochat/execution.py`、`scripts/chat_cli.py`、`scripts/infer_bench.py` —— 本阶段地图、关键事实与源码地图的事实来源。
- Vaswani et al., *Attention Is All You Need*, arXiv:1706.03762 —— 自回归分解、因果掩码与缩放点积注意力，对应两阶段推导的前提。
- Dao et al., *FlashAttention-3: Fast and Accurate Attention with Asynchrony and Low-precision*, arXiv:2407.08608 —— FA3 的 KV 缓存接口与窗口注意力，对应缓存与 decode 读取量。
- Chen et al., *Evaluating Large Language Models Trained on Code*, arXiv:2107.03374 —— HumanEval 的执行判分与沙箱设计，对应工具与沙箱篇的评测侧。
- Karpathy, *nanochat* `dev/LOG.md`（2026-01-11 Sliding Window Attention、2026-03-04 Remove autocast 条目）—— 版本说明中两处历史差异的来源。
