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 的取值与代码位置。
本阶段要回答的五个问题
整阶段的材料围绕五个问题组织,五篇笔记各自回答其中一个,并在接口处互相引用。
- 一个 token 的生成成本由什么决定。答案不是「参数量」,而是「每步必须搬运的字节数」:权重、KV 缓存与批大小共同决定 decode 的时间下界,prefill 的算力决定首 token 延迟。
- 缓存为什么能复用,代价是什么,何时失效。答案是历史位置的 K/V 与当前查询无关;代价是显存随 线性增长;失效条件是位置编码或掩码不再只依赖绝对位置。
- 模型如何把控制权交给运行时,运行时如何避免执行任意代码。答案是 9 个特殊 token 与三态状态机;对话侧只走计算器白名单,完整程序执行走独立沙箱,两者不是同一套边界。
- 一个进程如何把流式 token 交给用户,多个用户如何共享 GPU 而不互相污染。答案是生成器协议、会话锁与并发信号量;当前
Engine没有请求级调度器,因此共享只到「限流与排队」这一层。
- 一张卡能跑多大模型、多少并发、每百万 token 多少钱。答案是权重、KV、roofline 与卡时价格四个量的乘积;其中前三个由架构与实现决定,最后一个由市场决定。
学习顺序与理由
- 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 的短窗口口径写好,本篇不再改写。
- 自回归解码与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 等价性比较。
- 工具调用与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 与评测。读完这一篇,应能判断一个工具路径是走计算器还是走沙箱,并说出两者的安全边界差别。
- CLI与WebUI:把生成器接到进程与网络。它讲
chat_cli.py的 7 个参数、对话 token 拼接、流式解码、退出条件、当前 master 没有 WebUI 的证据,以及 FastAPI + SSE 的最小封装。放在第四位的理由是:CLI 直接消费Engine.generate,Web 封装则要额外处理会话、并发、缓存释放与限流;没有前两篇的协议与状态机,就无法判断封装层哪些状态该保留、哪些该丢弃。读完这一篇,应能写出一个不会泄漏缓存的 SSE 端点,并解释为什么当前Engine不适合直接做多会话缓存复用。
- 部署与成本:最后算账。它给出权重、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 解释它为什么与朴素计数差一。
阶段产物地图
本阶段的验证不依赖训练,只需要一个检查点。四条命令覆盖全部产物:
# 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 | |
| 单行 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/字节 | |
| 吞吐拐点 | 约 32(d24、2048) | |
| TTFT 示例 | 6.98 ms(1792 token、40% MFU) | TFLOP 除以 TFLOPS |
| TPOT 示例 | 2.61 ms(batch=8、60% MBU) | |
| speedrun 成本 | 约 \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 是前向单次而非训练的反向加三倍。把训练口径的 用到推理上,会高估 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 缓存字节数,由 字节得到。乘上 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。
- 跑
tests/test_engine.py,记录 8 个测试的通过情况;把max_tokens改成 1 与 64 各跑一次,观察generate_batch返回长度与终止 token 过滤的差别。这个实验验证协议,不需要检查点。
- 用
chat_cli -p在同一提示、temperature=0下跑两次,比较输出是否逐字相同;再用temperature=0.6跑两次,比较差异。这个实验验证采样与 seed 的语义。
- 用
infer_bench扫描1,8,32,128,从末行 JSON 取出ttft_sec、tpot_sec、tok_per_sec、mbu_percent、peak_vram_bytes,用 自回归解码与prefill-decode 与 部署与成本 的公式手算一遍 MBU,比较误差。这个实验验证指标口径。
- 用
execute_code跑「正常程序、除零、死循环、1 GB 分配、os.system、绝对路径读」六个用例,记录success、timeout、memory_exceeded与error;再跑os._exit(0),观察success=True但测试未执行。这个实验验证沙箱边界。
- 用 部署与成本 的成本脚本计算 d24 在 batch=8 下的每百万 token 成本,再与
infer_bench的tok_per_sec和当时 GPU 的租赁价格对照;改变 MBU 从 0.4 到 0.8,观察成本变化。这个实验验证成本模型对利用率假设的敏感性。
- 用 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,每行的完成标记、工具块与强制队列 | 工具、自回归 |
阶段验收流程
完成本阶段后,按以下顺序验收,避免「读过但跑不通」。
- 在 Linux 或 macOS 上跑
python -m pytest tests/test_engine.py tests/test_execution.py -v,确认 8 个引擎测试与 9 个沙箱测试函数(其中破坏性用例参数化为 5 条)的行为符合预期;Windows 上沙箱测试会因缺少resource失败,记录平台限制即可。
- 用
chat_cli -i sft -p "Why is the sky blue?"做一次单轮对话,确认横幅、Assistant:流式输出与退出行为;再进 REPL,测试clear与quit。
- 用
infer_bench跑一次 batch 扫描,把末行 JSON 保存下来;用成本脚本复算weight_bytes、kv_bytes_per_token、max_full_context_rows与ceiling_bs1_tok_per_sec,与 JSON 对齐。
- 用
execute_code跑沙箱能力表,把「挡得住」与「挡不住」各记录至少三条;对每条「挡不住」写明绕过了哪一层。
- 用 FastAPI 骨架起服务,两个会话并发,确认同一会话返回 429、超过并发返回 503、断开后显存回落。
- 把以上产物写入 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 条目)—— 版本说明中两处历史差异的来源。