w wyl123ly 的博客
MD

MOC-推理Engine

29 KB 2026.10.22 原文件

MOC · 推理Engine与工具

本阶段地图

本阶段共 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 的注释把这一点写得很直接:智能指标不说明模型运行起来有多贵,架构选择会在这里显现。

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 延迟。
  1. 缓存为什么能复用,代价是什么,何时失效。答案是历史位置的 K/V 与当前查询无关;代价是显存随 线性增长;失效条件是位置编码或掩码不再只依赖绝对位置。
  1. 模型如何把控制权交给运行时,运行时如何避免执行任意代码。答案是 9 个特殊 token 与三态状态机;对话侧只走计算器白名单,完整程序执行走独立沙箱,两者不是同一套边界。
  1. 一个进程如何把流式 token 交给用户,多个用户如何共享 GPU 而不互相污染。答案是生成器协议、会话锁与并发信号量;当前 Engine 没有请求级调度器,因此共享只到「限流与排队」这一层。
  1. 一张卡能跑多大模型、多少并发、每百万 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 的短窗口口径写好,本篇不再改写。
  1. 自回归解码与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 等价性比较。
  1. 工具调用与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 与评测。读完这一篇,应能判断一个工具路径是走计算器还是走沙箱,并说出两者的安全边界差别。
  1. CLI与WebUI:把生成器接到进程与网络。它讲 chat_cli.py 的 7 个参数、对话 token 拼接、流式解码、退出条件、当前 master 没有 WebUI 的证据,以及 FastAPI + SSE 的最小封装。放在第四位的理由是:CLI 直接消费 Engine.generate,Web 封装则要额外处理会话、并发、缓存释放与限流;没有前两篇的协议与状态机,就无法判断封装层哪些状态该保留、哪些该丢弃。读完这一篇,应能写出一个不会泄漏缓存的 SSE 端点,并解释为什么当前 Engine 不适合直接做多会话缓存复用。
  1. 部署与成本:最后算账。它给出权重、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 输出;换算 \$/百万 tokenscripts/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 解释它为什么与朴素计数差一。

阶段产物地图

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

# 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.pypytest stdout通过/失败、断言消息回归检查
对话输出chat_cli.pystdout横幅、Assistant: 流式文本人工验证
推理 JSONinfer_bench.pystdout 最后一行prefill、sweep、weight_bytes、kv_bytes_per_token成本表、成绩单
HumanEval 准确率chat_eval.py + tasks/humaneval.pystdout每题通过与否、最终百分比评测报告
检查点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,122GPTConfig(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 KiBGPT.kv_bytes_per_token()
KV@2048(单序列)288 MiB
单行 decode 读取 @2048132,120,576 B,约 126 MiBGPT.kv_read_bytes(2048),按 SSSL 窗口截断
单步 decode FLOPs @20481,591,741,872GPT.estimate_decode_flops(2048)
prefill FLOPs @20483,168,148,488,192GPT.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 TFLOPScommon.py 的 get_peak_bandwidth、get_peak_flops
H100 算力带宽比约 295 FLOP/字节
吞吐拐点 约 32(d24、2048)
TTFT 示例6.98 ms(1792 token、40% MFU) TFLOP 除以 TFLOPS
TPOT 示例2.61 ms(batch=8、60% MBU)
speedrun 成本约 \3/卡·小时)README
最快 leaderboard1.65 小时,CORE 0.2626README
训练上下文2048GPTConfig.sequence_len
chat 生成默认256 token、温度 0.6、top-k 50chat_cli.py 的 generate_kwargs
计算器超时3 秒eval_with_timeout 的 max_time=3
沙箱预算5 秒、256 MBexecute_code 的默认参数

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

源码地图

文件关键对象本阶段用途
nanochat/engine.pyKVCache、sample_next_token、RowState、Engine.generate、Engine.generate_batch生成协议、缓存、采样、工具状态机、批量返回
nanochat/gpt.pyCausalSelfAttention.forward、GPT.forward、generate、estimate__flops、kv__bytes单 token 前向、RoPE 偏移、smear、成本函数
nanochat/execution.pyGUARD、execute_code、ExecutionResult子进程沙箱与资源限制
nanochat/tokenizer.pySPECIAL_TOKENS、render_conversation、encode_special对话与工具 token 的协议
scripts/chat_cli.py参数解析、对话拼接、流式打印进程内的最小交互形态
scripts/infer_bench.pybench_generate、weight_bytes、静态卡、batch 扫描TTFT/TPOT/MBU/MFU/显存
scripts/chat_eval.pyrun_generative_eval、run_categorical_eval生成式评测与沙箱复用
tasks/humaneval.pyevaluate程序拼接与 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 RLrollout 使用的 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 缓存字节数,由 字节得到。乘上 2048 上下文得到 288 MiB/序列,乘上并发数得到总缓存。这个数字决定了「一张卡能同时服务多少条流」,也决定了 infer_bench 的 max_rows 为什么是几百而不是几千。它的口径是存储字节;decode 每步的读取字节还要按 SSSL 窗口截断,2048 上下文下是 126 MiB,比存储字节少一半。

第二个是 32。它是 d24 在 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 过滤的差别。这个实验验证协议,不需要检查点。
  1. 用 chat_cli -p 在同一提示、temperature=0 下跑两次,比较输出是否逐字相同;再用 temperature=0.6 跑两次,比较差异。这个实验验证采样与 seed 的语义。
  1. 用 infer_bench 扫描 1,8,32,128,从末行 JSON 取出 ttft_sec、tpot_sec、tok_per_sec、mbu_percent、peak_vram_bytes,用 自回归解码与prefill-decode 与 部署与成本 的公式手算一遍 MBU,比较误差。这个实验验证指标口径。
  1. 用 execute_code 跑「正常程序、除零、死循环、1 GB 分配、os.system、绝对路径读」六个用例,记录 success、timeout、memory_exceeded 与 error;再跑 os._exit(0),观察 success=True 但测试未执行。这个实验验证沙箱边界。
  1. 用 部署与成本 的成本脚本计算 d24 在 batch=8 下的每百万 token 成本,再与 infer_bench 的 tok_per_sec 和当时 GPU 的租赁价格对照;改变 MBU 从 0.4 到 0.8,观察成本变化。这个实验验证成本模型对利用率假设的敏感性。
  1. 用 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 失败,记录平台限制即可。
  1. 用 chat_cli -i sft -p "Why is the sky blue?" 做一次单轮对话,确认横幅、Assistant: 流式输出与退出行为;再进 REPL,测试 clear 与 quit。
  1. 用 infer_bench 跑一次 batch 扫描,把末行 JSON 保存下来;用成本脚本复算 weight_bytes、kv_bytes_per_token、max_full_context_rows 与 ceiling_bs1_tok_per_sec,与 JSON 对齐。
  1. 用 execute_code 跑沙箱能力表,把「挡得住」与「挡不住」各记录至少三条;对每条「挡不住」写明绕过了哪一层。
  1. 用 FastAPI 骨架起服务,两个会话并发,确认同一会话返回 429、超过并发返回 503、断开后显存回落。
  1. 把以上产物写入 10 阶段的 实验记录模板:命令、commit、GPU 型号、检查点、batch、TTFT、TPOT、tok/s、MBU、峰值显存、成本假设。缺少任何一项,结果都不可复现。

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

本阶段不重复的内容

内容完整讲解所在本阶段只保留
自注意力、多头、RoPE、FA3 原理04 的 [[自注意力机制]]、[[多头注意力]]、[[FlashAttention与高效注意力]]推理路径的调用点与窗口参数
缩放定律、CORE、bpb、speedrun 全流程05 的 [[CORE指标]]、[[训练脚本与speedrun]]检查点加载后的推理配置与成本口径
对话数据、render_conversation 训练侧 mask06 的 [[有监督微调SFT]]、[[从生成式到对话式]]推理时工具 token 的注入
REINFORCE、GRPO、reward07 的 [[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 条目)—— 版本说明中两处历史差异的来源。