一：从「刹车」到「误刹」

上一篇《LLM 的「刹车」：下一个 Token 预测机如何知道何时停止》里，我们拆解了 LLM 的停止机制：终止符是词表里的一个普通 Token，什么时候停是由训练分布塑形的软概率 $P(\text{EOS} \mid \text{上下文})$，再配合运行时层的 max_tokens 兜底。那篇文章留了一个尾巴：EOS 只是概率分布里的竞争者，停得准的前提是任务落在训练分布内。

这一篇看分布外的故事。用过长周期 Agent 的人多半见过这样的场面：代码只改了一半就开始总结陈词；测试一次都没跑，回复里却写着「所有测试已通过 ✅」；明确列了五条需求，做完了两条就宣布任务完成。这不是某个模型的偶发 bug，而是停止机制的必然推论：

模型决定停下的判据，是「上下文看起来像完成了」；它没有任何直接手段检验「任务真的完成了」。简单任务里这两者几乎重合，复杂任务里差距最大。

一句话概括本文的核心观察：对模型来说，「完成」首先是一种文体，其次才是一个事实。 它在训练数据里见过成千上万份「完成报告」，极其擅长生成这种文体；而事实无法被生成，只能被验证。

⚠️ 适用范围：本文解剖的失败模式和五个成因，主要来自早期模型 + 朴素 harness 组合下的观察。当前的 SOTA 模型配合成熟的工程实践（验证结果回灌、完成动作工具化、面向长程任务的推理训练），已经能够胜任相当长的长程任务——Claude Code、Codex 这类产品就是例证。但这不意味着本文的分析过时了：EOS 的底层机制没有变，变的是第三节那些对策被系统性地做进了模型训练和 harness 设计里。理解失败机制，恰恰是理解这些对策为什么有效的前提。

二：模型为什么会「误刹」：五个成因

2.1 训练数据从未区分「看起来完成」和「真的完成」

SFT 数据几乎全是干净、完整、成功的演示轨迹。每一条都长这样：

<prompt> ... <assistant_start> 做一些工作 ... 总结收尾 <|assistant_end|>

模型从这个分布里学到的「完成」判据是一组表面特征：干过活的痕迹（改了文件、写了代码）、一段收尾总结、自信的语气。训练数据里，「看起来完成」和「真的完成」从未被区分过——因为演示轨迹里它们总是同时出现。于是只要上下文凑齐这些表面特征，$P(\text{EOS})$ 就会冲高，哪怕活只干了一半。

还有一层更隐蔽的长度先验：演示轨迹短而整洁，真实任务长而乱。当实际轨迹的长度超出训练分布的典型长度后，EOS 概率会单纯因为「按惯例这时候该结束了」而上升——这是分布外任务长度触发的提前终止，与任务实际进度无关。

2.2 局部完整被误当成全局完整

复杂任务是层级结构：一个函数写完、一个文件改完、一个计划步骤做完——每一个子结束在局部看都和「任务完成」同构：产物连贯、有收尾感。而 next-token 预测没有对终止的全局规划，EOS 决策是基于局部上下文（主要是近期 token）做出的，模型很容易在子结束点把局部连贯误判为全局完备。

上下文越长，这个偏差越严重：最初的任务要求在注意力里越来越远（长上下文的「中间迷失」衰减是公认现象），模型可能「真诚地」忘记早先的约束，认为活已经干完了——它不是在撒谎，它的上下文里确实「看起来」都做完了。

2.3 上下文里没有关于任务状态的地面真相

「完成」是世界状态的属性：测试通过、文件落盘、构建成功。但模型只看得见上下文窗口。如果 harness 不把验证结果喂回上下文，模型就是在未经检验的上下文上计算 $P(\text{EOS})$：

flowchart LR
    subgraph Ctx["上下文窗口：模型唯一能看到的世界"]
        C1["改了三个文件，代码看起来合理"]
        C2["生成了总结：「测试通过，任务完成」"]
        C1 --- C2
    end
    subgraph World["世界状态：模型看不到"]
        W1["测试从未被运行"]
        W2["验收约束还有一条没满足"]
        W1 --- W2
    end
    Ctx -- "表面特征齐全，P(EOS) 冲高" --> EOS["模型输出终止符"]
    World -. "地面真相，但被错过" .-> EOS

    classDef terminal fill:#f3e5f5,stroke:#6a1b9a,stroke-width:2px;
    class EOS terminal;

最微妙的一点在这里：「测试已通过」这句话本身也是模型生成的。自述完成和实际完成走的是同一条生成通路——模型是在「合理地续写一份完成报告」，而不是在审计任何东西。SWE-bench 类基准上大量「看起来合理」的补丁无法通过测试，就是这个机制的直接体现：生成完成文体的能力，和把任务做完的能力，是两种能力。

2.4 RLHF 偏好自信的收尾

偏好数据里，人类标注员稳定地更喜欢自信、干脆、完整的结论，而不是犹豫、冗长、留有余地的表述——这也是偏好训练已知的副作用（谄媚性 sycophancy 的来源之一）。这个偏好会泛化到终止行为上：干脆地宣布完成在偏好上得分高，继续检查显得啰嗦。于是对齐过程系统性地把模型往「尽早给出自信结论」的方向推了一把。提前终止，某种意义上是过度对齐「自信」的代价。

2.5 协议层：EOS 是唯一的让权方式

这一条不是模型的问题，是 harness 设计的问题。很多 Agent 框架里，结束轮次是模型交还控制权的唯一手段。模型想「阶段性收尾」「不知道下一步该干什么」时，可用的信号也只有终止符——于是「声明完成」被当成检查点来用。再加上 max_tokens 截断压力：被硬截断的回答没有收尾，对齐后的模型学到「宁可早点收尾也不要被截断」，进一步压低了继续工作的倾向。

三：怎么治：三层框架下的对策

沿用上一篇的三层分工（模型层 / 协议层 / 运行时层），每个成因都有对应的解法。

3.1 协议层：把验证做成终止的前置条件

最有效的一类手段：不允许未经检验的终止。harness 拦截 EOS，先强制运行验证，把真实结果喂回上下文再让模型重新决策：

# 伪代码：把验证做成终止的前置条件
while True:
    token = sample(model, context)
    context.append(token)
    if token == EOS:
        if not context.has_run_verification():     # 从未运行过验证工具
            inject(context, run_tests())           # 把真实结果喂回上下文
            prevent_stop()                         # 拦截本次终止
            continue
        if context.last_verification_failed():
            continue                               # 有失败记录，不许停
        break                                      # 验证通过，允许终止

配套的流程：

flowchart TD
    S["模型采样到终止符"] --> G{"协议层检查：<br/>验证工具运行过吗？"}
    G -- "没有" --> V["拦截终止<br/>强制运行测试/构建"]
    V --> R["真实结果注入上下文"]
    R --> S2["模型基于地面真相<br/>重新计算 P(EOS)"]
    S2 --> S
    G -- "运行过" --> P{"最近一次验证通过？"}
    P -- "通过" --> DONE["允许终止"]
    P -- "失败" --> R2["错误信息注入上下文<br/>模型继续修复"]
    R2 --> S2

    classDef decision fill:#fff8e1,stroke:#f9a825;
    classDef action fill:#e8f5e9,stroke:#2e7d32;
    classDef terminal fill:#f3e5f5,stroke:#6a1b9a,stroke-width:2px;
    class G,P decision;
    class S,V,R,S2,R2 action;
    class DONE terminal;

另一个相关的协议设计是把「声明完成」本身工具化：不让模型用裸 EOS 结束任务，而是调用一个显式的完成工具（如 SWE-agent 的 submit）。好处是声明变成了显式动作，harness 可以在动作上做校验——这正是我之前《如何构建一个编码 Agent》里介绍的框架采用的模式。

3.2 上下文工程：把地面真相喂进上下文

既然模型的判据只能是上下文里的内容，那就让上下文里有真相：

• 验证结果回灌：每次工具调用（跑测试、构建、执行）的输出原样进入上下文，而不是让模型转述。「测试失败：3 errors」的真实输出，比模型自己写的「应该没问题」权重高得多。
• 验收清单重注入：在任务后段把最初的验收标准重新放到上下文末端，要求逐条核对后才能收尾。这是对 2.2（局部完整误判）和长上下文遗忘的直接对抗——把「全局」重新拉回模型的高注意力区。

3.3 模型层：用 reward 惩罚虚假的完成

RL 阶段的问题在于：如果 reward 只在终态给出（任务成败 0/1），提前终止和尝试后失败拿到相同的 reward，没有梯度压力区分两者。解法是把终止行为显式纳入 reward 塑形：

• 声明完成但验证失败 → 显式负奖励（比默默失败更重）；
• 诚实的「还没完成，继续」→ 不惩罚甚至小幅奖励；
• 验证通过后终止 → 最高奖励。

这样模型才会学到「完成」与「完成文体」的区别——因为这个区别终于体现在了损失函数里。

3.4 对策总览

四：总结：同一枚硬币的两面

把两篇文章放在一起看，「刹不住车」和「提前误刹」是同一个机制的两面：EOS 概率被训练分布塑形，分布内任务停得又准又稳，分布外的长任务就两头出错。三个层各自的失职方式：

• 模型层学到的是完成的文体而非完成的事实；
• 协议层没有要求「完成」必须可验证；
• 运行时层把唯一的让权通道和「任务完成」语义绑在了同一个 Token 上。

最后回到那句话：对模型来说，「完成」首先是一种文体，其次才是一个事实。它极其擅长生成这种文体——而事实，只能靠把地面真相放进上下文、把验证挡在终止之前来兑现。 这不是模型要变得更聪明才能解决的问题，很大一部分是 harness 设计问题：把「宣布完成」从一句话，变成一个必须附带证据、且可被拦截校验的动作。

一：一个悖论：预测机为什么不会永远预测下去

大语言模型的本质是一台下一个 Token 预测机（Next Token Predictor）：给定上下文，对整个词表输出一个概率分布，采样（或取最大）一个 Token，拼回上下文，再预测下一个。这个循环本身没有任何内在的终点——在每一步，模型能做的唯一事情就是从词表里再挑出一个 Token，「不输出」根本不在它的选项里。于是问题来了：

终止的信号，是从哪一步、以什么形式冒出来的？

这个问题看似哲学，答案却出奇地工程化。我们先把结论放在这里，再逐层拆开：

「结束」本身就是词表里的一个普通 Token。停止不是模型的特殊能力，而是一次普通的 Token 预测；「真的停下来」这个动作，由外层的推理框架执行。

以 nanochat 的词表为例，它有 65,536 个条目，其中 hello、的、 World 这些常规 Token 之外，还混着一些看起来很特殊的字符串：<|assistant_end|>、<|bos|>……它们和普通 Token 一样，只是词表中的一个 ID。模型每一步对全部 65,536 个条目输出概率，当采样落到终止符上时，生成结束。

本文先建立一个「三层分工」的概念框架，然后逐行剖析 nanochat（我之前在 《从零构建超迷你 ChatGPT》 中跑通过它的全流程训练）是怎么在每一层实现这套机制的——它没有抽象层，每一行代码都能对应到概念，是理解这个问题最好的教材。文中所有代码片段均逐字引自该仓库，引用处附有定位到具体行号的永久链接（permalink，锚定在笔者核对的 commit 上，不随上游更新漂移），点击即可跳转对照原文。

二：三层分工：模型、协议、运行时

在展开源码之前，先给出全文的分析框架。「LLM 如何停止」这个问题，实际上是三个层的协作：

这个分工有一个直接推论：模型在原理上没有任何机制保证它最终一定输出终止符。EOS 只是概率分布里的一个竞争者，每一步它都要和「继续写下去」的所有 Token 抢概率质量。所以运行时层永远需要一个 max_tokens 兜底——这是保险，不是冗余。

下面用 nanochat 逐层验证这个框架。

三：nanochat 源码剖析

💡 代码引用说明：本节所有代码片段均逐字引自 nanochat 仓库的 commit 92d63d4（与笔者本地跑训练的版本一致），每处引用附有带行号锚点的永久链接（permalink），不随上游更新漂移，可直接跳转对照上下文。

3.1 词表设计：一个没有 EOS 的词表

nanochat 在 nanochat/tokenizer.py 中定义了全部 9 个特殊 Token：

SPECIAL_TOKENS = [
    "<|bos|>",           # 文档分隔符
    "<|user_start|>",    # 用户消息
    "<|user_end|>",
    "<|assistant_start|>",  # 助手消息
    "<|assistant_end|>",
    "<|python_start|>",  # 助手调用 Python REPL 工具
    "<|python_end|>",
    "<|output_start|>",  # Python REPL 输出回助手
    "<|output_end|>",
]

第一个值得注意的细节：这个词表里没有 <|eos|>。终止的角色由两个 Token 分担：

• <|assistant_end|>：对话轮次终止符，等价于 Llama 3 的 <|eot_id|>、Qwen 的 <|im_end|>；
• <|bos|>：文档分隔符，被采样到时同样终止生成。

<|bos|> 的双重身份是理解「EOS 本质」的钥匙。Karpathy 在 tokenizer.py 的 from_pretrained 里专门写了段注释解释这个历史上的命名混乱：

tiktoken calls the special document delimiter token <|endoftext|>… yes this is confusing because this token is almost always PREPENDED to the beginning of the document… so in nanoChat we always use <|bos|> short for “beginning of sequence”, but historically it is often called <|endoftext|>.

翻译过来：GPT-2 时代的文档分隔符叫 <|endoftext|>（「文本结束」），但它几乎总是被前插在文档开头当序列起点用。同一个 Token，既是「新文档的开始」，也是「旧文档的结束」——因为它就是文档边界本身。这个命名混乱之所以能存在，恰恰说明了 EOS 从来不是什么魔法：它只是一个在数据里出现位置有规律的普通 Token。

3.2 预训练：「停」是从数据打包方式里学来的

模型层的学习发生在预训练。nanochat 的数据加载器（nanochat/dataloader.py）在 tokenize 每篇 FineWeb-Edu 文档时前插 <|bos|>，然后用 Best-Fit 算法拼进定长训练序列。实际喂给模型的数据长这样：

<bos> 文档1 <bos> 文档2 <bos> 文档3 <bos> 文档4 ...

关键在损失函数的构造方式：预训练的 targets 就是 inputs 右移一位，所有位置都参与损失（Best-Fit 打包保证 100% 利用率、无 padding）。这意味着「文档 3 写完之后，下一个 Token 是 <|bos|>」这件事本身就是被监督的预测目标：

一个佐证来自历史：没有对话训练的基座模型（GPT-3 时代）几乎不会好好停——要么无限写下去，要么在奇怪的地方断掉。当时只能靠停止字符串（比如匹配到 "\n\nUser:" 就截断）和 max_tokens 硬截断。终止符停得准，是后训练的产物，不是架构自带的。

3.3 SFT：把终止符明确构造为训练目标

预训练教会模型「文档有边界」，SFT 则把「一轮对话有边界」变成明确的监督信号。tokenizer.py 的 render_conversation 负责把对话渲染成 Token 序列，同时返回一个 mask——哪些位置是模型该学的（mask=1），哪些只是上下文（mask=0）：

Token 序列:   <bos> <user_start> 用户问题 <user_end> <assistant_start> 模型回复 <assistant_end>
mask:          0      0            0        0           0                1             1
                                                                                          ↑
                                                                              终止符也被监督！

对应源码中的一行（tokenizer.py L219）：

add_tokens(assistant_end, 1)  # mask=1，参与损失

而 user 消息、<|bos|>、工具输出全部是 mask=0。随后 scripts/chat_sft.py 把 mask=0 位置的 target 设为 -1（cross-entropy 的 ignore_index）：

# Apply the loss mask from render_conversation (mask=1 for assistant completions,
# mask=0 for user prompts, BOS, special tokens, tool outputs). mask[1:] aligns
# with targets (shifted by 1). Unmasked positions get -1 (ignore_index).
mask_tensor = torch.tensor(mask_rows, dtype=torch.int8)
mask_targets = mask_tensor[:, 1:].to(device=device)
targets[mask_targets == 0] = -1

所以 SFT 的训练目标可以概括为一句话：只在「给定对话前缀，生成助手回复 + 终止符」这些位置上更新参数。终止符不是训练的附加品，它就是序列的最后一个监督目标——SFT 数据里每一条完整回复都以 <|assistant_end|> 收尾，$P(\text{终止符} \mid \text{「回答完了」})$ 就这样被对齐出来。

3.4 推理运行时：采样循环里的停止判断

nanochat/engine.py 的 generate 方法`是「LLM 如何停」的最小完整实现，值得逐段走读。主循环每步先对全词表采样，然后做终止判断（节选自 L185-L250）：

# engine.py（节选，注释为原文）
assistant_end = get_special("<|assistant_end|>")  # if sampled, ends row
bos = self.tokenizer.get_bos_token_id()           # if sampled, ends row

while True:
    # Stop condition: we've reached max tokens
    if max_tokens is not None and num_generated >= max_tokens:
        break
    # Stop condition: all rows are completed
    if all(state.completed for state in row_states):
        break

    next_ids = sample_next_token(logits, rng, temperature, top_k)
    ...
    for i, state in enumerate(row_states):
        next_token = state.forced_tokens.popleft() if is_forced else sampled_tokens[i]
        # On <|assistant_end|> or <|bos|>, mark the row as completed
        if next_token == assistant_end or next_token == bos:
            state.completed = True

用流程图表示整个决策过程：

flowchart TD
    S["对全词表采样 next token"] --> F{"forced_tokens<br/>队列非空？"}
    F -- 是 --> T1["取队首强制注入 token<br/>(mask=0)"]
    F -- 否 --> T2["取采样 token<br/>(mask=1)"]
    T1 --> C{"是 assistant_end<br/>或 bos？"}
    T2 --> C
    C -- 是 --> D["标记 completed<br/>该 token 不进输出"]
    C -- 否 --> A["token 追加进输出"]
    D --> E{"all completed 或<br/>num_generated ≥ max_tokens？"}
    A --> E
    E -- 否 --> S
    E -- 是 --> END["结束生成"]

    classDef decision fill:#fff8e1,stroke:#f9a825;
    classDef action fill:#e8f5e9,stroke:#2e7d32;
    classDef terminal fill:#f3e5f5,stroke:#6a1b9a,stroke-width:2px;
    class F,C,E decision;
    class S,T1,T2,A action;
    class D,END terminal;

注意两道停止条件的分工：模型自己「想停」（采到终止符）是软条件，逐行独立生效；max_tokens 是硬条件，针对整个 batch。这正对应第二节说的「模型层的软概率 + 运行时层的硬规则」。

这里还有三个值得细品的工程细节：

1. 已完成行的「僵尸生成」。 批量采样时 KV cache 是整个 batch 一起算的，单行无法中途退出。某行采到终止符后，循环并不会跳过它——它继续接收 Token、继续过 forward，只是结果在 generate_batch 里被 if not completed[i] 过滤掉。这是朴素实现的处理方式；生产级推理引擎（vLLM / SGLang 的 continuous batching）做的优化正是在单行完成后把它从 batch 里换出去、填入新请求，避免算力浪费在僵尸行上。

2. 终止符由框架剥掉，不进输出。 generate_batch 里终止符只用来置 completed 标志，不 append 到结果序列——用户永远看不到 <|assistant_end|>，和真实 API 的行为一致。「终止符对用户不可见」是运行时层的职责，不是模型层的。

3. 截断后的修补。 scripts/chat_cli.py 里有段容易被忽略但很关键的逻辑：

# we have to ensure that the assistant end token is the last token
# so even if generation ends due to max tokens, we have to append it to the end
if response_tokens[-1] != assistant_end:
    response_tokens.append(assistant_end)
conversation_tokens.extend(response_tokens)

如果生成是被 max_tokens=256 硬截断的（而不是自然终止的），CLI 会强行补一个 <|assistant_end|> 再拼回会话历史。否则下一轮的上下文里 assistant 消息没有闭合标记——这种结构模型在训练时从未见过，多轮对话立刻退化。运行时必须维护协议的完整性，哪怕模型自己违反了协议。

3.5 一个反直觉的点：Token 流不全是模型预测的

engine.generate 里还内置了一个 Python 计算器工具（GSM8K 数学题用的），它揭示了下一个常被忽略的事实：真正的 Token 流是「模型采样」和「框架注入」的混合物。

当模型采样出 <|python_end|> 时，框架解码出表达式、调用 REPL 计算，然后把 <|output_start|> + 计算结果 + <|output_end|> 通过 forced_tokens 队列强制注入 Token 流。以「123 乘 456 等于多少」为例，一轮回复的完整 Token 流是这样的：

flowchart LR
    P["assistant_start"] --- S1["好的，"] --- S2["让我算一下"] --- PS["python_start"] --- S3["123*456"] --- PE["python_end"] --- OS["output_start"] --- F["56088"] --- OE["output_end"] --- S4["所以答案是 56088"] --- AE["assistant_end"]

    classDef prompt fill:#ffebee,stroke:#c62828;
    classDef sampled fill:#e8f5e9,stroke:#2e7d32;
    classDef forced fill:#fff3e0,stroke:#ef6c00;
    classDef terminal fill:#f3e5f5,stroke:#6a1b9a,stroke-width:2px;

    class P prompt;
    class S1,S2,S3,S4 sampled;
    class PS,PE,OS,OE,F forced;
    class AE terminal;

其中绿色是模型采样出来的（SFT 时 mask=1），橙色是框架强制注入的（mask=0），紫色是终止符。这打破了「输出 = 一连串 next-token 预测」的朴素想象：终止判断和工具调用一样，都属于框架对 Token 流的调度权。

RL 阶段对这种混合的处理很严谨（scripts/chat_rl.py L138-L139）：

targets[mask_ids[:, 1:] == 0] = -1 # <-- inplace modification right here. -1 is the ignore index
# NOTE also that the Engine returns mask=0 for BOTH the prompt tokens AND the tool use tokens.

被注入的工具 Token 从 policy gradient 的 target 里挖掉，只对模型真正采样过的 Token 算梯度。另一个有趣的细节：RL batch 的 padding 直接用 assistant_end 填充（注释写明「只当 padding 用，不进损失」）——终止符在 RL 损失里几乎是隐形的，RL 对停止行为的影响是间接的：答案没写完就停，GSM8K 的 reward 直接是 0；停得太晚则浪费采样预算（max_completion_tokens=256 兜底）。真正让终止时机变得可靠的，是 SFT 阶段那一个 mask=1。

四：失败模式：为什么有时停不对

回到第二节埋下的伏笔：终止符只是概率分布里的一个竞争者。在每一步：

模型「想停」的意愿和「想写 the / 的」的意愿在同一个 softmax 里竞争。分布偏移、温度过高、陷入复读循环时，普通 Token 的概率可能持续压过终止符，于是要么停不下来，要么在半句话处戛然而止。这也是为什么温度设高之后模型更容易刹不住车——高温把分布抹平，终止符原本的概率优势被稀释。

实践中的三类兜底手段，对应三个不同的层：

调试时有个实用技巧：很多推理框架可以输出每个 Token 的 logprobs，盯着终止符的概率看——一个健康的模型在接近答案结尾时，终止符概率会一路爬升，最后几个 Token 处占据压倒性优势；如果它始终在低概率区徘徊，说明停止行为没有被对齐好。

五：从 nanochat 到生产系统

nanochat 那个几十行的生成循环，在生产系统里被工程化成了同一套逻辑的放大版。以 vLLM / SGLang 为例，SamplingParams 暴露的停止相关参数和 engine.generate 的停止条件一一对应：

• stop_token_ids：终止 Token 列表（nanochat 里硬编码为 assistant_end + bos 两个）；还有一个 ignore_eos 参数，压力测试时用它强制模型不停，专门跑满 max_tokens 测吞吐；
• stop：停止字符串列表，在解码后的文本上做子串匹配（对应 GPT-3 时代的 "\n\nUser:" 方案）；
• max_new_tokens：硬截断兜底；
• continuous batching：解决「僵尸行」问题——完成的请求立刻换出、新请求换入，这正是 nanochat 里被「算完再丢弃」浪费掉的那部分算力。

我在之前 Qwen3.8-27B 的 SGLang 基准测试 里开过 EAGLE 投机解码，那里也有一个和「停止」直接相关的细节：draft model 同样要对全词表（包括终止符）做预测，但它提议的每一个 Token——包括提前给出的错误 EOS——都要过 target model 的概率校验，错的会被拒掉重算。所以无论解码路径怎么加速，停止的最终裁决权始终在 target model 手里，这和 nanochat 的三层分工完全一致。

六：总结

把全文收拢回那张三层分工表，补上 nanochat 的实现和生产系统的对应关系：

如果要给这篇文章提炼一句话，我会选这一句：

LLM 把「结束」编码成了词表里的一个普通 Token，什么时候停是和语言一起从数据里学出来的；而「真的停下来」这个动作，由外层的推理框架执行，再加上 max_tokens 做保险。

nanoChat 最有启发性的一点，是 <|bos|> 的双重身份：一个 Token，既是「新文档的开始」也是「旧文档的结束」，因为它就是文档边界本身。它用一个 Token 说明了 EOS 从来不是魔法——词表里的每个条目都是平等的，是训练数据的结构和运行时的约定，赋予了其中某个条目「终止」的语义。

测试日期：2026-08-28

SGLang 官方 cookbook 给出了 Qwen3.8-27B 在 DGX Spark 上的完整启动配方（48 种组合全部验证过”能启动、能服务”），但没有给出任何吞吐数据——DGX Spark 是该页面上唯一只做了 boot-and-serve 验证的硬件。本文用实际的 Docker 部署 + curl 流式调用补上这块空白：两个 checkpoint（NVFP4 量化 / BF16 原版）× 两种推测解码（EAGLE 开 / 关），共 4 组配置，覆盖短上下文、8K、23K 三种输入规模和 4 路并发。

1. 测试环境

2. 部署方式（SGLang Docker）

启动参数完全对齐 官方 cookbook 的 DGX Spark 低延迟配方：EAGLE（3 步 / topk 1 / 4 draft tokens）+ --enable-linear-replayssm-spec + --mamba-full-memory-ratio 4.59 + extra_buffer + SSM float32 + KV fp8_e4m3 + flashinfer。Makefile 里的两个核心 target：

几点部署相关的实测/对照信息：

• 术语澄清：被开关的技术是推测解码（Speculative Decoding）；EAGLE 是 SGLang 中该技术的算法实现，NEXTN 是它的旧名/别名（cookbook 明确两者等价）；而 MTP 头不是算法本身，是 checkpoint 内置的草稿权重——EAGLE 运行时用它充当草稿模型，一次猜多个 token、主模型一次前向并行验证，因此无需单独下载 draft checkpoint（BF16 checkpoint 加载时能看到单独的 Qwen3_5ForCausalLMMTP，约 4.9GB）。”关闭推测解码”即回到逐 token 的纯自回归解码。
• --mem-fraction-static 0.85 在 DGX Spark 上有 earlyoom 风险（cookbook 的 48 格矩阵中 15 格在 0.85 被系统 OOM 守护进程以 -15 杀掉），官方 DGX Spark 配方定在 0.80。本文 NVFP4 组沿用本机 Makefile 默认 0.85（实测多次启停稳定），BF16 组按官方建议用 0.80。
• 开启推测解码时若不显式设置 --max-running-requests，SGLang 会固定为 48（本机实测 NVFP4+EAGLE = 48，关闭推测后按显存自动算出 79）。

3. 模型文件

两个模型主体权重结构相同（64 层：48 层 Gated DeltaNet 线性注意力 + 16 层 GQA 全注意力），差异只在量化和 lm_head 打包方式，是同一架构下”精度换带宽”的直接对照。

4. 测速方法

用 curl -sN 流式调用 /v1/chat/completions（SSE），stream_options.include_usage 拿服务端 token 计数，temperature 0、ignore_eos true 固定输出长度。指标定义：

• TTFT：从发请求到收到首个内容块
• Prefill = prompt_tokens / TTFT（只取冷缓存首跑，避免 radix cache 命中后虚高）
• Decode = (completion_tokens - 1) / (末 token 时刻 - 首 token 时刻)

每组跑 3 遍取后 2 遍的稳态值（首跑含冷启动单独标注）；thinking 模式保持默认开启。服务端日志的 gen throughput 与客户端聚合值相互印证（如 4 并发时服务端 84~88 tok/s vs 客户端 83~85 tok/s）。

5. 测试结果

5.1 单流 Decode 速度（tok/s）

• EAGLE 带来的加速：NVFP4 上 1.8~2.1×，BF16 上 2.3~2.7×（8K 处收益最大）。服务端统计的平均接受长度：NVFP4 2.69/4 步，BF16 2.85/4 步。
• NVFP4 对 BF16 的加速：关闭推测解码时 2.9×，开启后 2.1×（EAGLE 摊薄了读取权重的开销，量化优势被部分抹平）。
• 带宽模型验证：273GB/s ÷ 21GB ≈ 13 tok/s（NVFP4 理论上限），273GB/s ÷ 52.9GB ≈ 5.2 tok/s（BF16），与实测 12.0 和 4.15~4.87 基本吻合——单流 decode 就是权重带宽的物理极限，与此前另一份 GB10 测速报告“~23 tok/s 天花板”（NVFP4+NEXTN 达 23.02）的结论一致，本文同配方实测 23.7~25.5。

5.2 TTFT 与 Prefill

• BF16 短上下文的首 token 也要 10 秒上下，NVFP4 只要约 2 秒——长 prompt 的 prefill NVFP4 快 1.7×，短请求的固定开销差 5×。
• 长输入下 chunked prefill 摊薄了每块固定开销，各配置的 23K prefill 都高于 8K（NVFP4+EAGLE 冷缓存能到 ~1.8K tok/s）。
• radix cache 暖机后重复请求 TTFT 明显下降（如 NVFP4+EAGLE 8K 从 4.2s 降到 2.7s），但此时”prefill 速率”读数含缓存命中成分，不具可比性，故表中只列冷缓存值。

5.3 并发测试（5.8K 输入，4 路并发 × 512 输出）

• 最意外的结果：NVFP4 + EAGLE 在 4 并发下单路速度几乎不掉（24.9 vs 单流 23.7），推测解码的 draft/verify 随 batch 摊销得很好；聚合吞吐达到单流的 3.5×。
• BF16 关闭推测解码时批处理几乎”免费”：每路 4.8 ≈ 单流 4.85，聚合约线性扩展（17.6 ≈ 4.15 × 4.2）——纯带宽瓶颈下多路只是把权重读取摊给更多请求。
• 对照 cookbook 的警告：推测解码会把 max-running-requests 重置为 48，本机 NVFP4+EAGLE 实测 KV 池 37.5 万 token、上限 48 路，4 并发只用了 KV 池的 2%。

5.4 内存与 KV 池

NVFP4 把 31GB 的权重差省下来给了 KV 池：同等 mem-fraction 下可用上下文容量是 BF16 的约 2 倍（41.3 万 vs 20.5 万 token，均远超模型原生的 262K 上下文）。

6. 结论

1. 推荐组合：NVFP4 + EAGLE（make run-eagle 默认配置）。单流 24~29 tok/s，4 并发聚合 84 tok/s 且单路体验不掉速，KV 池 37.5 万 token，加载仅 110 秒——在 GB10 上是速度、容量、启动时间的全面最优。
2. BF16 原版不适合做常驻服务：单流 4~5 tok/s、短请求 TTFT 10 秒起步；但它的价值在于给出带宽物理上限的干净参照（4.15 ≈ 273GB/s ÷ 52.9GB），以及验证 EAGLE 输出分布不受推测解码影响。
3. EAGLE/MTP 是 DGX Spark 上的必选项：两个 checkpoint 上都是 1.8~2.7× 加速，接受长度 2.69~2.85/4 且并发下不衰减；BF16 受益更大（权重读取每步摊薄近 3 倍）。
4. 量化的收益在推测解码面前缩水：NVFP4 对 BF16 的单流优势从关闭推测解码时的 2.9× 降到开启后的 2.1×——EAGLE 本质上是”用一次权重读取换 2.7 个 token”，与量化的省钱逻辑同向叠加但有边际。
5. 单流 decode 天花板由 273GB/s 内存带宽锁死，与模型/引擎优化无关；想再快只能换更大的 spec 模型或期待硬件换代，23K 长上下文的 prefill 反而还有优化空间（chunk 8192 等参数未在本文展开）。

7. 过程中的环境备忘

• nvidia-smi 在 GB10 上显存栏是 Not Supported（统一内存），判断能否再起一个容器要看 /proc/meminfo 的 MemAvailable，而不是 nvidia-smi。
• --mem-fraction-static 0.85 + BF16 是 earlyoom 高危组合（cookbook 实测 15/48 格被杀，exit -15 无 traceback），DGX Spark 上建议 0.80；本文 NVFP4@0.85 多次启停未复现被杀。
• 推测解码未显式设置 --max-running-requests 时会被固定为 48，关闭推测后本机自动算出 79——做并发压测前先确认这个隐含上限。
• 官方 cookbook 对 DGX Spark 的 48 格矩阵只做了 boot-and-serve 验证（ISL 8192 / OSL 1024、并发 1，无吞吐数据）；RTX 5090 / RTX PRO 6000 才有完整性能数字，本文数据可用于填补 DGX Spark 这一格。
• 镜像 lmsysorg/sglang:qwen38-27b（sglang g561c8f3 + flashinfer 0.6.18）满足 MTP + FlashInfer 对 uniform_q_len 的版本要求，无需退回 triton 后端。

原文链接：How to build a coding agent: free workshop

作者：Geoffrey Huntley

本文将介绍如何构建一个编码 Agent。「Agent」一词如今已屡见不鲜。

尽管这个术语被频繁提及，但许多人对其确切含义及编码 Agent 的内部运作机制仍缺乏清晰的理解。是时候揭开其神秘面纱，展示其技术门槛并非高不可攀。

学习如何构建编码 Agent 是 2025 年个人发展中最具价值的投资之一，因为它能让你掌握核心基础。一旦理解了这些基础知识，你将从 AI 的消费者转变为 AI 的生产者，具备利用 AI 实现自动化的能力。

让我们从以下事实开始：

这并不难

构建一个编码 Agent

只有 300 行代码

在一个循环中运行

使用 LLM token，这就是全部。

仅需 300 行代码在一个循环中运行，消耗 LLM token。只要持续向循环中输入 token，你就拥有了一个 Agent。

本文将指导你构建一个 Agent，并解释其基本工作原理。在 2025 年，与 AI 协同工作已成为常态。因此，演示这一点的最佳方式莫过于让一个 Agent 来协助构建另一个 Agent。

现在，我们开始构建一个 Agent。这是行业正在发生的变革之一：工作可以并发进行，甚至在你离开电脑时也能持续推进。

花费数天甚至一周时间进行研究冲刺的日子已成过去，如今你只需通过语音指令即可将想法转化为执行。

下次在 Zoom 通话时，不妨思考一下：你本可以让一个 Agent 在通话期间完成你计划中的工作。如果这对你来说尚非常态，而你的同事却已习以为常，那么你将难以保持领先优势。

请构建你自己的

因为这些知识

将改变你

从消费者

变成生产者

能够自动化事务

科技行业犹如一条不断前行的传送带，要求我们持续学习新知。

在 2025 年，你应熟悉如何创建一个 Agent。理解这一循环机制以及如何构建 Agent，已成为雇主在招聘时寻找的基础技能。

Yes, You Can Use AI in Our Interviews. In fact, we insist - Canva Engineering Blog

因为这些知识将助你从 AI 的消费者转变为能够编排工作流程的 AI 生产者。雇主如今更青睐那些能够在组织内部实现任务自动化的个人。

关于这一点的深入探讨，可参考以下内容：

the six-month recap: closing talk on AI at Web Directions, Melbourne, June 2025

此刻，你正处于上述旅程的某个阶段。

在左上角，有些人持怀疑态度：「向我证明这不是真的」、「给我看结果」、「证明这不是炒作」，或者认为「这还不够好」。他们被困在悬崖的一侧，完全忽视了在悬崖的另一边，已有人在完全自动化他们的工作职能。

在我看来，任何与 AI 相关的颠覆或失业并非 AI 本身所致，而是缺乏个人发展和自我投资的后果。如果你的同事在多个 Agent 之间切换，处理想法，并在会议期间让 Agent 在后台运行，而你却置身事外，那么落后是必然的。

What do I mean by some software devs are “ngmi”?

切勿成为滞留在悬崖左侧的人。

科技行业的传送带持续向前。如果你是 2025 年的 DevOps 工程师，却没有任何 AWS 或 GCP 的经验，那么你会发现就业市场举步维艰。

软件和数据工程师惊讶于这一切发生得如此之快。自第一个编码 Agent 发布以来仅八个月，大多数人仍未意识到构建它是多么简单，这个循环是多么强大，以及它对我们职业产生的颠覆性影响。

所以，我叫 Geoffrey Huntley。我曾是 Canva 的开发者生产力技术主管，但几个月前，我成为了 Sourcegraph 构建 Amp 的工程师之一。这是一个大约六人的核心小团队。我们用 AI 构建 AI。

ampcode.com

cursor

windsurf

claude code

github co-pilot

都是在 LLM token 循环中运行的代码行。

Cursor、Windsurf、Claude Code、GitHub Copilot 和 Amp 只是在 LLM token 循环中运行的一小部分代码。需要强调的是：模型在此完成了所有繁重的工作。是模型驱动了一切。

你可能正在评估多家供应商的产品，试图比较这些 Agent。但这实际上是在做无用功。

构建属于你自己的 Agent 其实非常简单……

你只需要了解几个关键概念。

并非所有 LLM 都是 Agentic（代理式）的。

正如汽车有不同类型——越野时选择 40 系列，载客时选择轿车一样。

同样的原则也适用于 LLM，我们可以将它们的行为映射到一个象限中。

一个模型要么是高安全性，要么是低安全性；要么是 Oracle（预言机），要么是 Agentic（代理式）。它很难兼顾所有特性。

如果你想进行安全研究，你会选择哪个模型？

答案是 Grok。那是一个低安全性模型。

如果你想要「道德一致」的东西，那就是 Anthropic 或 OpenAI。所以那是高安全性。同样，你有 Oracle。Oracle 与 Agentic 截然相反。Oracle 适合总结任务或需要高水平思考的任务。

同时，你有像 Anthropic 这样的提供商，他们的 Claude Sonnet 是一只数字松鼠（见下文）。

Claude Sonnet is a small-brained mechanical squirrel of <T>

第一个机器人用来追逐网球，而第一个数字机器人则追逐工具调用（tool calls）。

Sonnet 就像一只专注于工具调用的机器松鼠。它不会花费过多时间思考，而是偏向于行动，这正是其具备 Agentic 特性的原因。Sonnet 专注于通过逐步行动获得成功，而不是在行动前花费数分钟进行思考。

似乎每天都有新模型推向市场，竞争激烈。但实际上，它们各有所长，并占据了各自的细分市场。

问题在于，除非深入使用这些模型，否则你可能无法意识到它们的专长，这导致消费者仅根据两个基本指标来比较模型：

1. 上下文窗口的大小
2. 成本

这好比仅通过车门数量来评价汽车，却忽略了车辆的设计用途是越野还是载客。

构建 Agent 的第一步是选择一个高度 Agentic 的模型。目前的首选是 Claude Sonnet 或 Kimi K2。

你可能会问：「如果需要更高水平的推理来检查工作怎么办？」。这很简单。你可以将其他 LLM 作为工具集成到现有的 Agentic LLM 中。这正是我们在 Amp 所采用的方法。

我们称之为 Oracle。Oracle 只是 GPT 作为一个工具连接进来，Claude Sonnet 可以函数调用它来获得指导，检查工作进度，并进行研究/规划。

Oracle Amp

Amp 的 oracle 只是另一个注册为 Agentic LLM 工具的 LLM，它可以对其进行函数调用。

下一个关键点是：上下文窗口应仅用于单一活动。当使用 Cursor 或类似工具时，必须在每次活动结束后清除上下文窗口（见下文）。

autoregressive queens of failure

LLM 的输出质量取决于上下文的纯净度。

如果你在一个 AI 辅助会话中构建后端 API 控制器，随后又利用同一会话研究猫鼬。那么，当你要求它重新设计网站时，结果中包含关于 API 或猫鼬的信息也就不足为奇了。

注：Sonnet 的上下文窗口已增加到 1M。

上下文窗口非常非常小。最好把它们看作是 Commodore 64，因此，你应该把它当作一台内存有限的计算机。你分配的越多，你的结果和性能就越差。

Sonnet 宣传的上下文窗口是 200K。然而，你不能全部使用它，因为模型需要为系统级提示分配内存。然后 harness（Cursor, Windsurf, Claude Code, Amp）也需要分配一些额外的内存，这意味着你最终大约有 176K 可用 token。

你可能听说过模型上下文协议（MCP）。这是当前的热门话题，最简单的理解方式是将它们视为带有描述的函数，分配给上下文窗口，告知模型如何调用。

我观察到一个常见的失败场景：人们安装了过多的 MCP 服务器，或者未能充分考虑单个 MCP 工具公开的工具数量及所有工具的总上下文窗口占用。

有一条尚未被充分重视的基本规则：分配给上下文窗口的内容越多，其性能越差，结果也会随之恶化。

应避免通过 Agent 或 MCP 工具过度占用上下文窗口。很容易陷入仅为 MCP 工具就分配了额外 76K token 的陷阱，导致可用空间大幅减少。

少即是多。

如果你想了解何时使用 MCP 以及何时不使用，我建议你阅读下面的博客文章。

too many model context protocol servers and LLM allocations on the dance floor

何时应该使用 MCP，何时不应该使用 MCP，以及上下文窗口中的分配是如何工作的。

让我们回去检查一下我们在后台构建的 Agent。如果你仔细观察，你可以看到循环以及它是如何调用其他工具的。

本质上，这一切是如何工作的在下面的循环中概述。

对于来自用户的每一条输入或工具调用的结果，都会分配给响应，并将该响应发送以进行推理：

推理循环（减去工具注册）

让我们 Clone 以下这个仓库并通过 go run chat.go 运行基本的聊天应用程序：

GitHub - ghuntley/how-to-build-a-coding-agent

You: You are a weather expert. When I ask you about the weather in a given location, I want you to reply with get_weather(<location_name>). I will then tell you what the weather in that location is. Understood?

Claude: I understand your instructions. When you ask me about the weather in a specific location, I will respond with get_weather(<location_name>). Then you will provide me with the weather information for that location, and I can discuss it with you from there. I’m ready whenever you’d like to ask about the weather somewhere.

所以，让我们问问今天澳大利亚墨尔本的天气怎么样？

You: What’s the weather like today in Melbourne, Australia?

Claude: get_weather(Melbourne, Australia)

至此，操作完成。

我们已将第一个工具注册到模型中。每当关于天气的查询触发潜在空间时，模型便会调用这个新工具。

虽然目前它只是一个存根工具，但原理已清晰可见：我们定义了一个方法，而 LLM 正从查询中提取参数并传递给该方法。

当我们谈论 Agentic 时，我们指的是某种工具调用，某种已经在其奖励函数上受过训练以调用工具的东西。有些模型经过明确训练；它们只想追逐坚果，就像松鼠一样（见下文）。这不是坚果，是工具。

[Claude Sonnet is a small-brained mechanical squirrel of ](https://ghuntley.com/cars/)

解释 MCP 或工具的最简单方法是，它只是一个顶部带有广告牌的函数，推动 LLM 的潜在空间来调用该函数。

它就这么简单。你注册工具，描述如何调用它，然后它就可以工作了。

让我们开始制作真正的编码 Agent 的短暂旅程。我们有一个模拟函数和一个模拟工具，但 get_weather(Melbourne, Australia) 目前什么也没做，所以让我们修复它。

我们需要做的是创建一个工具，然后调整我们的推理循环以检查它是否想要执行该工具（见上文第 5 行）。如果它想，执行该工具（见上文第 6 行），然后将该工具的结果分配回（见上文第 7 行）循环以进行更多推理。

这是注册工具后我们更新后的序列图的样子。

这就是最纯粹形式的编码 Agent，没有任何 UI。

由于我们今天不是在制作天气应用程序，让我们换个档次来构建编码 Agent 的第一个原语。

任何编码 Agent 背后的第一个原语是读取工具。所有编码 Agent 都有一个读取工具，可以将文件读取到上下文窗口中，或者是整个文件，或者对于较大的文件，分块读取。

var ReadFileDefinition = ToolDefinition{
	Name:        "read_file",
	Description: "Read the contents of a given relative file path. Use this when you want to see what's inside a file. Do not use this with directory names.",
	InputSchema: ReadFileInputSchema,
	Function:    ReadFile,
}

GitHub - ghuntley/how-to-build-a-coding-agent

让我们再次在代码仓库根目录，创建一个文件：

cat << EOF
I have a mane but I'm not a lion,
I have four legs but I'm not a table,
I can gallop but I'm not running,
People say I'm disagreeable because I always say "neigh."
What am I?
EOF > riddle.txt

然后让我们运行读取文件工具：

go run read.go

You: Claude, mate. What’s the answer to this riddle in riddle.txt?

Claude: I’ll help you solve the riddle. Let me first read the contents of the riddle.txt file to see what the riddle is.

tool: read_file({"path":"riddle.txt"})

Reading file: riddle.txt

Successfully read file riddle.txt (175 bytes)

result: I have a mane but I’m not a lion,I have four legs but I’m not a table,I can gallop but I’m not running,People say I’m disagreeable because I always say “neigh.”What am I?

Claude: After reading the riddle, I can solve it for you:The answer to the riddle is: a horse.Let’s analyze the clues:”I have a mane but I’m not a lion” - Horses have manes, which is hair growing from the top of the neck.”I have four legs but I’m not a table” - Horses walk on four legs.”I can gallop but I’m not running” - Galloping is a specific gait of horses.”People say I’m disagreeable because I always say ‘neigh’” - “Neigh” is the sound a horse makes, and it sounds like “nay” (which means “no” or disagreement).All of these clues point to a horse as the answer to the riddle.

任何编码 Agent 背后的第二个原语是列表工具。所有编码 Agent 都有一个列出文件工具，它列出给定路径中的所有文件和目录。

var ListFilesDefinition = ToolDefinition{
	Name:        "list_files",
	Description: "List files and directories at a given path. If no path is provided, lists files in the current directory.",
	InputSchema: ListFilesInputSchema,
	Function:    ListFiles,
}

GitHub - ghuntley/how-to-build-a-coding-agent

让我们再次在代码仓库根目录，通过 go run list_files.go 运行基本的聊天应用程序：

You: Claude, mate. Is there a README.md in this folder? Also what is the contents of riddle.txt?

Claude: I’ll help you check for a README.md file and show you the contents of riddle.txt.First, let me list the files in the current directory to see if README.md exists:

tool: list_files({})

Listing files in directory: .

Successfully listed 88 items in .

result: [".devenv.flake.nix",".direnv/",".envrc",".gitignore","AGENT.md","Makefile","README.md","bash_tool.go","chat.go","code_search_tool.go","devenv.lock","devenv.nix","devenv.yaml","edit_tool.go","go.mod","go.sum","list_files.go","prompts/","prompts/00-weather.md","prompts/01-read_file.md","prompts/02-list_files.md","prompts/03-bash_tool.md","prompts/04-edit_tool.md","read.go","renovate.json","riddle.txt"]

Claude: Yes, there is a README.md file in this folder.Now, let me show you the contents of riddle.txt:

tool: read_file({"path":"riddle.txt"})

result: I have a mane but I’m not a lion,I have four legs but I’m not a table,I can gallop but I’m not running,People say I’m disagreeable because I always say “neigh.”What am I?

至此，我们已拥有了一个读取文件工具和一个列出文件工具，你可以看到它们的函数被调用并从我们的原始提示链接在一起。

任何编码 harness 背后的第三个原语是 bash 工具，它正如其名。它使 LLM 能够在你的计算机上执行命令。

var BashDefinition = ToolDefinition{
	Name:        "bash",
	Description: "Execute a bash command and return its output. Use this to run shell commands.",
	InputSchema: BashInputSchema,
	Function:    Bash,
}

GitHub - ghuntley/how-to-build-a-coding-agent

让我们再次在代码仓库根目录，运行 bash 工具：

go run bash_tool.go

You: Hey Claude, provide a summary of all the processes running on this computer.

Claude: I’ll provide a summary of all the processes running on this computer. Let me use the ps command to gather this information.

tool: bash({"command":"ps aux"})

Executing bash command: ps aux

Bash command succeeded: ps aux (output: 87344 bytes)

result:

Claude: Based on the output of the ps aux command, here’s a summary of the processes running on this computer:System Summary:This is a multi-CPU system with 96 cores/threads (visible from the many CPU-related kernel threads)Running Linux with systemd as the init systemThe system has been up since August 20th (seen in START column)

任何编码 harness 背后的第四个原语是编辑工具。编辑工具也正如其名。它从推理中获取结果并将编辑应用于文件。

GitHub - ghuntley/how-to-build-a-coding-agent

让我们再次在代码仓库根目录，运行编辑工具：

go run edit_file.go

You: Claude, mate. Create fizzbuzz.js with nodejs that does fizzbuzz up to 20 and execute it to ensure it works

Claude: I’ll create a Node.js implementation of FizzBuzz that counts up to 20 and then run it to make sure it works correctly.First, let me create the fizzbuzz.js, file:

tool: edit_file({"path":"fizzbuzz.js","old_str":"","new_str":"// FizzBuzz implementation in Node.js\n// Prints numbers from 1 to 20\n// If number is divisible by 3, print "Fizz"\n// If number is divisible by 5, print "Buzz"\n// If number is divisible by both 3 and 5, print "FizzBuzz"\n\nfor (let i = 1; i <= 20; i++) {\n if (i % 3 === 0 && i % 5 === 0) {\n console.log("FizzBuzz");\n } else if (i % 3 === 0) {\n console.log("Fizz");\n } else if (i % 5 === 0) {\n console.log("Buzz");\n } else {\n console.log(i);\n }\n}"})

Editing file: fizzbuzz.js (replacing 0 chars with 485 chars)

File does not exist, creating new file: fizzbuzz.js

Creating new file: fizzbuzz.js

Claude: Now I’ll execute the script to make sure it works correctly:

tool: bash({"command":"node fizzbuzz.js"})

Executing bash command: node fizzbuzz.js

Bash command executed successfully, output length: 77 chars

result: 12Fizz4BuzzFizz78FizzBuzz11Fizz1314FizzBuzz1617Fizz19Buzz

Claude: Great! The fizzbuzz.js file has been created and executed successfully. The output shows:Numbers not divisible by 3 or 5 are printed as is (1, 2, 4, 7, 8, 11, 13, 14, 16, 17, 19)Numbers divisible by 3 (but not 5) print “Fizz” (3, 6, 9, 12, 18)Numbers divisible by 5 (but not 3) print “Buzz” (5, 10, 20)Number 15 prints “FizzBuzz” as it’s divisible by both 3 and 5

至此，我们已拥有了一个编码 Agent。此时，我们可以尝试其他提示，例如「实现 FizzBuzz 计数到 100」，它也能正常工作。

任何编码 Agent 背后的第五个，也是最后一个原语是搜索工具。如果我告诉你，索引源代码或所谓的智能背后并无魔法呢？

var CodeSearchDefinition = ToolDefinition{
	Name: "code_search",
	Description: `Search for code patterns using ripgrep (rg).

Use this to find code patterns, function definitions, variable usage, or any text in the codebase.
You can search by pattern, file type, or directory.`,
	InputSchema: CodeSearchInputSchema,
	Function:    CodeSearch,
}

目前几乎所有主流编码工具的底层都使用了开源的 ripgrep 二进制文件。如需更多证据，请参阅以下两篇博客文章：

source code analysis of Amazon Kiro

from Luddites to AI: the Overton Window of disruption

让我们再次在代码仓库根目录，运行代码搜索工具：

go run code_search_tool.go

You: Claude, mate. Search the source code for a riddle

Claude: I’d be happy to search the source code for a riddle. Let me use the code search tool to look for mentions of riddles in the codebase.

tool: code_search({"pattern":"riddle"})

Searching for pattern: riddle

Found 6 matches for pattern: riddle

result: ./README.md:332:- riddle.txt: A simple riddle for content analysis

Claude: I’ve found references to a riddle file called “riddle.txt” in the codebase. Let me check if this file exists by listing the files in the current directory.

tool: list_files({})

Listing files in directory: .

Successfully listed 25 files in .

result: ["./go.mod","./renovate.json","./devenv.yaml","./AGENT.md","./.devenv.flake.nix","./.envrc","./bash_tool.go","./fizzbuzz.js","./code_search_tool.go","./list_files.go","./Makefile","./devenv.nix","./devenv.lock","./prompts/01-read_file.md","./prompts/02-list_files.md","./prompts/00-weather.md","./prompts/03-bash_tool.md","./prompts/04-edit_tool.md","./chat.go","./go.sum","./riddle.txt","./edit_tool.go","./README.md","./.gitignore","./read.go"]

Claude: Great! I can see that “riddle.txt” exists in the current directory. Let me read its contents to see what the riddle is.

tool: read_file({"path":"riddle.txt"})

Reading file: riddle.txt

Successfully read file riddle.txt (175 bytes)

result: I have a mane but I’m not a lion,I have four legs but I’m not a table,I can gallop but I’m not running,People say I’m disagreeable because I always say “neigh.”What am I?

Claude: I found the riddle in the file riddle.txt!

接下来的工作主要是调整提示词。由于篇幅限制，本文未深入探讨 Harness 提示的概念。Harness 提示是注册工具的地方，它包含诸如操作系统类型等信息，以便 Agent 知道是使用 PowerShell (Windows) 还是 bash (Linux 或 macOS)。

它还包含关于 Agent 应如何操作的指令。之所以说「应」，是因为 LLM 具有非确定性。你可以提供指导，但这仅是引导。然而，通过提示评估、调整以及深入了解模型的行为模式，你可以开发出高效的提示。

如果你想看一个完全成熟的编码 Agent 的例子，请访问下面的博客文章：

source code analysis of Amazon Kiro (需要付费订阅)

已经有很多开源编码 Agent，例如 SST Open Code

GitHub - sst/opencode

或者这个 100 行的 Agent，它在 SWE Bench 上得分很高。

GitHub - SWE-agent/mini-swe-agent

如果你想要一些灵感，GitHub 上有许多存储库泄露了开发人员工具 harness 和工具提示。

GitHub - x1xhlol/system-prompts-and-models-of-ai-tools

回顾一下，你刚刚构建了一个编码 Agent。也许你的目标并非创建一个编码 Agent。如果你是数据工程师，情况会如何？思考一下你的日常活动，拥有利用这些原语进行自动化的能力，对你的雇主而言将极具价值。

取代你工作的将是善用 AI 的人，而非 AI 本身。

如果你对 AI 感到焦虑，答案很简单：投资自己。今年是个人发展充满挑战的一年，切勿停滞不前。

the six-month recap: closing talk on AI at Web Directions, Melbourne, June 2025

勇往直前，开始构建吧。

一：项目背景

1.1 为什么要自己构建大语言模型？

OpenAI 推出的 ChatGPT 等大语言模型作为深度神经网络模型的代表，为自然语言处理（NLP）领域带来了革命性的变化。大语言模型在理解、生成和解释人类语言方面拥有出色的能力。 从零开始构建大语言模型不仅是一次深入了解模型机制和局限性的绝佳机会，还为我们提供了预训练和微调开源大语言模型，使其适应特定领域的数据集或任务的必要知识。 Andrej Karpathy 最近开源了 nanochat 项目，号称花 100 美元就能从零训出一个能聊天的模型。正好手边有台 DGX Spark，于是决定跑一遍完整流程，顺便记录下来。

1.2 nanochat 项目介绍

nanochat 是一个全栈式的大语言模型实现，旨在用最简洁、最少依赖的代码库复刻 ChatGPT 的核心功能。它不仅涵盖了从分词（Tokenization）、预训练（Pre-training）、微调（Fine-tuning）到推理（Inference）和 Web 服务部署的完整生命周期，还特别强调代码的可读性和可修改性（Hackable）。 现代大语言模型的构建通常分为预训练（Pre-training） 和 后训练（Post-training） 两个主要阶段。

• 预训练阶段：这是消耗算力最大的阶段，旨在让模型从海量无标注文本中学习通用知识，产出基座模型（Base Model）。
• 后训练阶段：旨在将基座模型转化为能与人交互的助手。在 nanochat 项目中，这一阶段被细分为三个具体步骤：
  • 中期训练（Mid-training）：让模型适应对话格式和工具使用。值得注意的是，在更广泛的业界实践中，这一阶段通常也被称为「继续预训练」（Continued Pre-training）或「增量预训练」（Incremental Pre-training）。
  • 监督微调（SFT）：通过问答数据教会模型遵循指令。
  • 强化学习（RL）：进一步优化模型的回答质量（如数学推理能力）。

为了帮助大家理清这四个阶段（基座训练 + 后训练三部曲）的递进关系，我整理了下面这张全景对照表，涵盖了从脚本入口到真实数据集的完整细节：

💡 关于安全对齐：在业界完整的大模型训练流程中，安全性和价值观对齐主要在 RL 阶段通过 RLHF（Reinforcement Learning from Human Feedback）或 DPO（Direct Preference Optimization）等方法实现。人类标注员会对模型回复进行偏好排序，训练奖励模型来评估回答是否有帮助（Helpful）、诚实（Honest）、无害（Harmless）——即著名的 3H 原则。nanochat 作为教学项目，仅使用 GSM8K 数学题的正确性作为奖励信号，并未实现完整的安全对齐。

下图展示了 nanochat 完整的训练流水线，清晰地描绘了从海量文本到最终对齐模型的演进过程：

flowchart LR
    %% Nodes
    D1[("📚 海量无标注文本<br/>FineWeb-Edu")]
    P1(基座训练<br/>scripts.base_train)
    M1(基座模型<br/>Base Model)
    
    D2[("📋 格式化数据<br/>SmolTalk + MMLU")]
    P2(中期训练<br/>scripts.mid_train)
    M2(格式适配模型<br/>Formatted Model)
    
    D3[("🗣️ 指令对话数据<br/>ARC, GSM8K...")]
    P3(监督微调<br/>scripts.chat_sft)
    M3(对话模型<br/>Chat Model)
    
    D4[("⚖️ 奖励信号<br/>GSM8K")]
    P4(强化学习<br/>scripts.chat_rl)
    M4(最终对齐模型<br/>Aligned Model)

    %% Main Flow
    D1 --> P1 --> M1
    M1 --> P2
    D2 --> P2 --> M2
    M2 --> P3
    D3 --> P3 --> M3
    M3 --> P4
    D4 --> P4 --> M4

    %% Styles
    classDef data fill:#e3f2fd,stroke:#1565c0,stroke-width:1px;
    classDef process fill:#fff3e0,stroke:#ef6c00,stroke-width:1px,rx:5,ry:5;
    classDef model fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px,rx:5,ry:5;
    
    class D1,D2,D3,D4 data;
    class P1,P2,P3,P4 process;
    class M1,M2,M3,M4 model;

1.3 DGX Spark

上图为两位 AI 研究人员正在研究 DGX Spark 设备，其体积小巧，可轻松单手托持。

NVIDIA DGX Spark 是专为边缘计算和个人开发者设计的高性能 AI 工作站。它搭载了 NVIDIA Grace Blackwell GB10 芯片，拥有 128 GB 统一内存架构（Unified Memory Architecture）。

• 硬件优势：传统的消费级显卡显存通常受限（如 24 GB），难以加载或训练较大的模型。而 DGX Spark 的 128 GB 统一内存打破了这一瓶颈。
• 新一代精度支持：得益于 Blackwell 架构，DGX Spark 原生支持 MXFP4（Microscaling Format）和 NVFP4 等前沿数据类型。这些低精度格式在保持模型性能的同时，能显著降低显存占用并大幅提升计算吞吐量，为未来的优化预留了空间。值得一提的是，OpenAI 开源的 gpt-oss 项目正是采用 MXFP4 量化技术，使得 1170 亿参数的 gpt-oss-120b 模型能够在单张 80GB 显存的 GPU（如 NVIDIA H100 或 AMD MI300X）上运行推理，而 gpt-oss-20b 模型更是可以在 16GB 显存内运行。这充分展示了低精度量化技术在大模型部署中的巨大潜力。
• 美中不足：虽然配备 128 GB 的统一内存，但不得不吐槽的是，它采用的是 LPDDR5X 统一内存，理论峰值带宽仅为 273 GB/s（数据来源：NVIDIA 官方规格），相比数据中心级别 H100 的 HBM3 带宽（3.35 TB/s）有约 12 倍的差距。由于大语言模型训练是典型的内存带宽受限（Memory-Bound）任务，这意味着在 DGX Spark 上训练时，GPU 计算单元往往在「等待」数据从内存传输过来，导致训练时间显著延长（这也是为什么我们需要耐心等待约 10 天来完成预训练的原因）。

在 DGX Spark 运行 nvidia-smi 命令：搭载 NVIDIA GB10 芯片，驱动版本 580.95.05，CUDA 13.0。GPU 利用率为 96%，约 78 GB 内存正被 nanochat 训练进程占用。

二：实战演练

⚠️ 网络环境提示：全程需要科学上网，以确保能够顺利访问境外相关资源。

2.1 DGX Spark 训练环境适配

nanochat 项目推荐使用 8 张 NVIDIA H100/H200 GPU（基于 Hopper 架构）来快速完成训练（约 4 小时）。而在 DGX Spark 上，我们使用的是单张 Grace Blackwell GB10 芯片（基于 Blackwell 架构）。

为了在 DGX Spark 上顺利跑通 nanochat 的全流程训练，我们在原基础之上进行了以下关键适配：

• CUDA 13.0 环境适配：
  • 调整原因：DGX Spark 搭载的 Grace Blackwell GB10 芯片需要最新的 CUDA 13.0 支持才能发挥最佳性能。
  • 具体调整：修改 pyproject.toml，将 PyTorch 版本升级至 >=2.9.0，并指定 cu130 源。同时引入了 triton>=3.5.0 ，以支持 Blackwell 架构下的内核编译与优化。
• 内存管理优化：
  • 调整原因：虽然 128 GB 统一内存容量很大，但为了防止长时间训练中的显存碎片化导致 OOM（Out Of Memory）。
  • 具体调整：在训练脚本中设置了 PYTORCH_ALLOC_CONF=max_split_size_mb:512，优化 PyTorch 的内存分配策略。同时，将预训练的 device_batch_size 调整为 32，在充分利用内存与保持稳定性之间寻找平衡点。
• 网络加速配置：
  • 调整原因：考虑到国内网络环境访问 PyPI 和 Hugging Face 可能受限或速度较慢。
  • 具体建议：推荐配置 pip 使用清华大学镜像源 (https://pypi.tuna.tsinghua.edu.cn/simple)，以及使用 HF-Mirror ( https://hf-mirror.com) 加速模型和数据集的下载。

环境配置脚本如下：

#!/bin/bash
if [ ! -f cuda-ubuntu2404.pin ]; then
    wget https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2404/sbsa/cuda-ubuntu2404.pin
fi
sudo mv cuda-ubuntu2404.pin /etc/apt/preferences.d/cuda-repository-pin-600
if [ ! -f cuda-repo-ubuntu2404-13-0-local_13.0.2-580.95.05-1_arm64.deb ]; then
    wget https://developer.download.nvidia.com/compute/cuda/13.0.2/local_installers/cuda-repo-ubuntu2404-13-0-local_13.0.2-580.95.05-1_arm64.deb
fi
sudo dpkg -i cuda-repo-ubuntu2404-13-0-local_13.0.2-580.95.05-1_arm64.deb
sudo cp /var/cuda-repo-ubuntu2404-13-0-local/cuda-*-keyring.gpg /usr/share/keyrings/
sudo apt-get update
sudo apt-get -y install cuda-toolkit-13-0

echo 'export TRITON_PTXAS_PATH=/usr/local/cuda-13.0/bin/ptxas' >> ~/.bashrc
echo 'export CUDA_HOME=/usr/local/cuda-13.0' >> ~/.bashrc
echo 'export PATH=/usr/local/cuda-13.0/bin:$PATH' >> ~/.bashrc
echo 'export LD_LIBRARY_PATH=/usr/local/cuda-13.0/lib64:${LD_LIBRARY_PATH}' >> ~/.bashrc

echo 'export HF_ENDPOINT=https://hf-mirror.com' >> ~/.bashrc

source ~/.bashrc

# Verify installation
nvcc --version
nvidia-smi

git clone https://github.com/karpathy/nanochat.git
cd nanochat

sed -i 's/"torch>=2.8.0"/"torch>=2.9.0"/g' pyproject.toml
sed -i '/tiktoken>=0.11.0/a\    "triton>=3.5.0",' pyproject.toml
sed -i 's|pytorch-cu128|pytorch-cu130|g' pyproject.toml
sed -i 's|cu128|cu130|g' pyproject.toml
sed -i 's|# target torch to cuda 12.8 or CPU|# target torch to cuda 13.0 or CPU|' pyproject.toml


 # Use HF-Mirror to accelerate dataset download in China
 sed -i 's|https://huggingface.co|https://hf-mirror.com|g' nanochat/dataset.py

# install uv (if not already installed)
command -v uv &> /dev/null || curl -LsSf https://astral.sh/uv/install.sh | sh
# create a .venv local virtual environment (if it doesn't exist)
[ -d ".venv" ] || uv venv
# install the repo dependencies (using Tsinghua mirror for faster download in China)
uv sync --extra gpu --index-url https://pypi.tuna.tsinghua.edu.cn/simple
# activate venv so that `python` uses the project's venv instead of system python
source .venv/bin/activate

2.2 处理文本数据

在正式开始训练之前，我们需要先把海量文本转换成模型能理解的「数字语言」。这个过程就像给电脑准备一本「字典」，让它知道如何阅读人类的语言。

2.2.1 词元与词元 ID

• 词元（Token）：是模型理解和处理文本的最小单位。它不一定等同于一个单词，它可以是一个单词、一个汉字、一个词根，甚至是一个字符或字节。例如，单词「learning」可能被拆分为「learn」和「ing」两个词元。
• 词元 ID（Token ID）：为了让计算机能够处理，每个唯一的词元都会被分配一个独一无二的数字编号，这就是词元 ID。模型实际上是在处理这些数字序列，而不是文本本身。

nanochat 采用了与 GPT-4 相同的 BPE（Byte Pair Encoding） 分词算法，但在细节上针对小模型进行了优化：

• 预分词（Pre-tokenization）：首先使用正则表达式（Regex）将文本粗略地切分成一个个小块。nanochat 使用的正则模式 SPLIT_PATTERN 能够智能地处理缩写（如 'll、've）、数字和标点符号。
  • 优化点：nanochat 将数字的匹配规则从 GPT-4 的 \p{N}{1,3}（最多 3 位数字）调整为 \p{N}{1,2}（最多 2 位数字），这样可以减少数字类词元对词表空间的占用，更适合小参数量的模型。
• 字节级 BPE：它不是直接处理 Unicode 字符，而是处理 UTF-8 编码后的字节。这意味着它可以处理任何语言的文本，甚至包括 emoji 表情，而不会出现「未知字符」错误。

将词元转换成词元 ID 的过程通常称为 Encoding（编码）：

• 查表：分词器内部维护着一个巨大的词表（Vocabulary），记录了所有已知的词元及其对应的 ID（nanochat 的词表大小为 65,536）。
• 映射：当文本被切分成词元序列后，分词器会遍历这个序列，在词表中查找每个词元对应的 ID。
• 输出：最终，一段文本就被转换成了一串数字列表（Tensor），这才是送入神经网络的真正「输入」。

例如："Hello world" -> 分词 -> ["Hello", " world"] -> 查表 -> [15496, 995]。

graph LR
    %% 1. Input
    subgraph Input [完整的训练集]
        direction TB
        Text[/"The quick brown fox jumps<br/>over the lazy dog"/]
        Note["(为了便于说明，<br/>训练集中只包含一个句子)"]
        Text -.- Note
    end

    %% 2. Tokenized
    subgraph Tokens [词元化的训练集]
        direction LR
        T_The[The] --- T_quick[quick] --- T_brown[brown] --- T_dots[...]
    end

    %% 3. Vocabulary
    subgraph Vocab [词汇表]
        direction TB
        V0["brown → 0"]
        V1["dog → 1"]
        V2["fox → 2"]
        V3["jumps → 3"]
        V4["lazy → 4"]
        V5["over → 5"]
        V6["quick → 6"]
        V7["the → 7"]
        V0 ~~~ V1 ~~~ V2 ~~~ V3 ~~~ V4 ~~~ V5 ~~~ V6 ~~~ V7
    end

    Input -- "1. 将输入文本分词为独立的词元" --> Tokens
    Tokens -- "2. 按字母顺序排列并去重<br/>映射到唯一整数ID" --> Vocab

2.2.2 词嵌入（Word Embeddings）

虽然词元 ID 解决了「将文本转换为数字」的问题，但这些数字本身是离散的，没有任何语义关联。例如，词元 ID 100（apple）和 101（banana）在数值上只差 1，但计算机并不知道它们都是水果。

词嵌入（Word Embeddings） 就是为了解决这个问题。它将每个词元 ID 映射到一个高维的连续向量空间中（nanochat d20 配置下为 1280 维）。在这个空间里：

• 语义相似的词（如「king」和「queen」）在距离上会靠得很近。
• 语义关系可以通过向量运算来表示（经典的例子：$Vector(King) - Vector(Man) + Vector(Woman) \approx Vector(Queen)$）。

简单来说，词嵌入就是给每个词元赋予一个「特征列表」，让模型能够理解词与词之间的微妙关系。

在 nanochat/gpt.py 中，我们可以看到 nanochat 对词嵌入的处理有几个显著特点：

• 独立的嵌入层（wte）：nanochat 使用一个标准的 nn.Embedding 层作为查找表，将 65,536 个词元（由 Tokenizer 训练决定）映射为高维向量（d20 配置下为 1280 维）。

  self.transformer = nn.ModuleDict({
      "wte": nn.Embedding(config.vocab_size, config.n_embd),
      # ...
  })
  

• 解绑权重（Untied Weights）：与许多早期模型（如 GPT-2）不同，nanochat 的输入嵌入层（wte）和输出层（lm_head）不共享权重。这意味着模型可以分别学习「如何理解输入」和「如何生成输出」，增加了模型的表达能力。

• 嵌入后归一化（Embedding Norm）：nanochat 在嵌入层之后立即应用了 RMSNorm（Root Mean Square Normalization）。这是一种简化的归一化方法，它只对激活值进行方差归一化（除以均方根），而不像 LayerNorm 那样做零均值化，因此计算开销更小。这种现代化的设计有助于稳定训练过程，防止梯度爆炸，加速权重的有效收敛。

  # Forward pass snippet
  x = self.transformer.wte(idx)
  x = norm(x) # 立即进行归一化
  

• 混合精度优化： 为了节省显存，nanochat 会将嵌入层的权重转换为 bfloat16 格式（如果硬件支持），这在保持精度的同时显著降低了内存占用。

• 差异化学习率： 在优化器设置中，nanochat 对嵌入层使用了 AdamW 优化器，并对其学习率进行了特殊缩放（$\propto 1/\sqrt{d_{model}}$ ），而模型的主体部分（Linear 层）则使用 Muon 优化器。这种精细的调优策略确保了不同类型的参数都能以最佳速度收敛。

• 实现级别说明（Lookup → Norm → LM Head）： 为了让读者更直观地理解嵌入是如何被模型使用，下面给出一个简化的流程图（基于 nanochat/gpt.py 的前向逻辑）：

flowchart LR
  %% Data Nodes
  Input(Token IDs<br/>idx)
  Output(Logits<br/>Next Token Scores)

  %% Operation Nodes
  WTE[wte<br/>Embedding Lookup]
  Norm1[RMSNorm<br/>Post-Embedding]
  Trans[Transformer Blocks<br/>Attention + MLP]
  Norm2[RMSNorm<br/>Pre-LM Head]
  Head[lm_head<br/>Linear Projection]
  Softcap[Softcap<br/>Soft Capping]

  %% Flow
  Input -- "(B, T)" --> WTE
  WTE -- "(B, T, n_embd)" --> Norm1
  Norm1 --> Trans
  Trans -- "(B, T, n_embd)" --> Norm2
  Norm2 --> Head
  Head -- "(B, T, vocab_size)" --> Softcap
  Softcap --> Output

  %% Styling
  classDef data fill:#e3f2fd,stroke:#1565c0,stroke-width:2px;
  classDef op fill:#fff3e0,stroke:#ef6c00,stroke-width:2px,rx:5,ry:5;
      
  class Input,Output data;
  class WTE,Norm1,Norm2,Trans,Head,Softcap op;

关键点说明：

• 嵌入权重在初始化时采用正态分布（见 _init_weights），并在支持的设备上转换为 bfloat16 以节省内存。
• norm(x) 在嵌入之后立即调用，有助于稳定后续 Transformer 层的训练。
• lm_head 为单独的线性层（不共享 wte），负责将模型的隐向量投射回词表维度，得到预测每个下一词的 logits。

• Softcap 是 nanochat 的一个特色设计：通过软截断将 logits 限制在 [-15, 15] 范围内：

  \[\text{logits}_{\text{capped}} = 15 \cdot \tanh\left(\frac{\text{logits}}{15}\right)\]

  这种软截断（Soft Capping）有助于防止 logits 数值过大导致的数值不稳定问题，同时保留了梯度信息（相比硬截断 clamp），是一种提升训练稳定性的技巧。

2.2.3 下载预训练数据集

nanochat 采用 FineWeb-Edu 作为预训练数据集。该数据集由 Hugging Face 团队从 Common Crawl 中筛选出教育质量较高的网页内容，经过去重、过滤和质量评分后打包为 Parquet 格式。

数据集规格：

• 总规模：1823 个 Parquet 文件，每个约 100 MB
• 预训练需求：约 240 个文件（~24 GB），包含约 112 亿 Token
• Tokenizer 训练需求：前 8 个文件（~800 MB），包含约 20 亿字符

数据下载通过 nanochat.dataset 模块的 download_single_file 函数实现，支持断点续传和并行下载。下载后的文件存储在 ~/.cache/nanochat/base_data/ 目录。

2.2.4 训练 BPE Tokenizer

Tokenizer 是将自然语言文本转换为模型可处理的整数序列的核心组件。nanochat 采用 Byte Pair Encoding（BPE） 算法，这是 GPT 系列模型的标准分词方案。

BPE 的实现相对复杂，nanochat 直接使用现有的 Python 开源库 tiktoken，它基于 Rust 的源代码非常高效地实现了 BPE 算法。BPE 算法的原理是将不在预定义词汇表中的单词分解为更小的子词单元甚至单个字符，从而能够处理词汇表之外的单词。

训练流程（scripts/tok_train.py）：

1. 预分词（Pre-tokenization）：使用正则表达式 SPLIT_PATTERN 将文本切分为候选 Token。该模式针对小模型优化，将数字匹配规则从 GPT-4 的 \p{N}{1,3} 调整为 \p{N}{1,2}，减少数字类 Token 对词表空间的占用：

   r"""'(?i:[sdmt]|ll|ve|re)|[^\p{L}\p{N}]?+\p{L}+|\p{N}{1,2}| ?[^\s\p{L}\p{N}]++[\n]*|\s*[\n]|\s+(?!\S)|\s+"""
   

2. 字节级 BPE 训练：基于 UTF-8 字节流进行训练，而非直接操作 Unicode 字符。这确保了对任意语言和特殊字符的无损处理。训练过程迭代合并高频字节对，直至词表达到目标大小 65,536（2^16），可用两字节表示任意 Token ID。

3. 特殊 Token 注册：在基础词表之外追加 9 个特殊 Token（定义见 tokenizer.py 的 SPECIAL_TOKENS）：

   ["<|bos|>", "<|user_start|>", "<|user_end|>", 
    "<|assistant_start|>", "<|assistant_end|>",
    "<|python_start|>", "<|python_end|>", 
    "<|output_start|>", "<|output_end|>"]
   

   这些 Token 用于标记文档边界、对话角色和工具调用，仅在后训练阶段启用。

4. 字节统计缓存：为支持评估指标 Bits Per Byte（BPB），训练脚本会计算每个 Token 对应的 UTF-8 字节数并缓存到 token_bytes.pt。特殊 Token 的字节数设为 0，不参与压缩率计算。在模型评估时，该缓存用于将交叉熵损失转换为 BPB：bpb = loss / ln(2) / avg_bytes_per_token。

实现细节：nanochat 结合 rustbpe（训练）和 tiktoken（推理）两个库，前者用 Rust 实现高效训练，后者由 OpenAI 开源，提供优化的批量编码能力。

2.2.5 评估 Tokenizer 压缩效率

训练完成后，通过 scripts/tok_eval.py 评估 Tokenizer 的压缩性能。核心指标为 Bits Per Byte (BPB)。

Tokenizer 熵上界（均匀分布假设）

假设每个 Token 以均匀概率出现（即不考虑语言模型的预测能力），则编码每个 Token 需要 $\log_2(V)$ 比特。在此假设下，Tokenizer 的压缩率上界公式为：

其中 $V = 65,536$ 为词表大小，$N_{\text{tokens}}$ 为 Token 数量，$N_{\text{bytes}}$ 为原始 UTF-8 字节数。这个指标衡量的是 Tokenizer 本身的压缩效率上限，与模型无关。实际的语言模型通过学习 Token 分布，能够以远低于此上界的比特数编码文本。

实际 BPB（模型性能）

在模型评估中，BPB 通常通过交叉熵损失计算，反映模型预测下一个 Token 的能力：

这个指标综合了 Tokenizer 压缩率和模型预测准确性，是评估语言模型的重要指标。BPB 越低，表示模型对文本的建模能力越强。

评估基准:脚本在多种文本类型上测试 Tokenizer 的泛化能力:

• 新闻文本（news_text）：英文政府公告
• 韩文文本（korean_text）：非英语语言压缩测试
• 代码片段（code_text）：Python 代码的符号密集文本
• 数学公式（math_text）：LaTeX 格式的学术文档
• 科学文献（science_text）：专业术语密集的生物化学文本
• 训练集/验证集样本：从 FineWeb-Edu 采样的真实训练数据

评估结果还会与 GPT-2 和 GPT-4 的 Tokenizer 进行对比，输出每种文本类型的 Token 数量、压缩率（字节/Token）和相对差异百分比。

性能指标参考：

• 英文文本的 BPB 通常在 0.8-1.2 之间
• 压缩率（字节/Token）越高表示 Tokenizer 效率越好
• 对于 65,536 词表，$\log_2(65536) = 16$ bits/token 为理论上限

2.2.6 实际操作流程

在 DGX Spark 上，我们可以通过以下脚本完成整个文本处理流程：

#!/bin/bash

# Install Rust / Cargo
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
source "$HOME/.cargo/env"
# Build the rustbpe Tokenizer
uv run maturin develop --release --manifest-path rustbpe/Cargo.toml

# Download and prepare the dataset
python -m nanochat.dataset -n 240

# Train the tokenizer
python -m scripts.tok_train --max_chars=2000000000
python -m scripts.tok_eval

# Download evaluation bundle
curl -L -o eval_bundle.zip https://karpathy-public.s3.us-west-2.amazonaws.com/eval_bundle.zip
unzip -q eval_bundle.zip
rm eval_bundle.zip
mv eval_bundle "$HOME/.cache/nanochat"

这个脚本会自动完成：

1. ✅ 下载 240 个数据文件（其中 8 个用于训练 Tokenizer，这些文本文件还将用于后续的预训练）
2. ✅ 训练 Tokenizer 并保存到 ~/.cache/nanochat/tokenizer/
3. ✅ 运行测试确保 Tokenizer 工作正常

耗时估计：首次运行约需 20-30 分钟（主要是下载时间）。

2.3 预训练（Pre-training）

预训练是构建大语言模型最核心、也是最消耗算力的阶段。在这个阶段，我们的目标是训练一个基座模型（Base Model），让它学会「预测下一个词」（Next Token Prediction）。

2.3.1 模型架构（Model Architecture）

nanochat 采用了一个现代化的 GPT 架构，融合了许多最新的研究成果以提升训练稳定性和推理效率：

• Rotary Embeddings (RoPE)：取代了传统的绝对位置编码，让模型更好地处理长文本。
• QK Norm：在 Attention 层对 Query 和 Key 进行归一化，显著提升了训练的稳定性。
• ReLU² 激活函数：在 MLP 层使用平方 ReLU，相比传统的 GeLU 计算更简单且效果相当。
• 无偏置设计 (No Bias)：移除了所有线性层的偏置项，简化了模型结构。
• RMSNorm：使用均方根归一化，且不带可学习参数，进一步精简模型。
• Group Query Attention (GQA) 支持：支持使用更少的 Key/Value 头来减少推理时的内存占用和计算量（默认配置下 GQA 未启用，即 n_kv_head = n_head）。
• 零初始化 (Zero Init)：对 lm_head 和每层的 c_proj（Attention 和 MLP 的输出投影）进行零初始化，有助于训练初期的稳定性。

2.3.2 优化器创新（Optimization）

nanochat 引入了一种混合优化策略：

• Muon 优化器：用于优化模型中的 2D 矩阵参数（如 Linear 层的权重）。Muon 是一种基于动量的正交优化器，其核心思想是通过 Newton-Schulz 迭代 将梯度正交化后再更新参数，使得权重矩阵保持良好的条件数，从而加速收敛并提升训练稳定性。
• AdamW 优化器：用于优化 1D 向量参数（如 Embedding 和 Norm 层）。

这种组合（Muon + AdamW）旨在在保持收敛速度的同时，最大化训练的吞吐量。

2.3.3 训练配置

在 DGX Spark 上，我们使用 d20 配置进行训练：

• 参数量：约 0.56B
  • 含义：参数量相当于模型的「脑细胞」数量，决定了其记忆知识和处理复杂逻辑的潜力。0.56B 参数属于轻量级模型，比较适合个人开发者入门学习。
  • 来源：该数值是根据 d20 配置（即 20 层深度）动态推导出来的。具体来说，当深度设为 20 时，模型维度被自动设为 1280 ( 20 * 64)。累加所有权重参数后，总计约为 5.61 亿：
    • Embedding 层 (wte): $65,536 \times 1,280 \approx 83.9 \text{M}$
    • Transformer 层 (20层): $20 \times (12 \times 1,280^2) \approx 393.2 \text{M}$
      • 每层包含 Attention 和 MLP 两个子模块，参数量为 $12 \times d^2$，其中：

      组件	参数维度	参数量
      c_q (Query)	d × d	d²
      c_k (Key)	d × d	d²
      c_v (Value)	d × d	d²
      c_proj (Attention 输出)	d × d	d²
      c_fc (MLP 上投影)	d × 4d	4d²
      c_proj (MLP 下投影)	4d × d	4d²
      每层总计		12d²

      注：上述计算假设 GQA 未启用（即 n_kv_head = n_head）。若启用 GQA，c_k 和 c_v 的参数量会按比例减少。

    • LM Head 层: $1,280 \times 65,536 \approx 83.9 \text{M}$
    • 总计: $83.9 + 393.2 + 83.9 \approx 561 \text{M}$
• 层数 (Depth)：20 层
  • 含义：层数代表了神经网络的深度。每一层都是一个 Transformer 模块，数据经过层层加工，提取出从语法到语义的特征。20 层是一个在性能和算力消耗之间取得平衡的经典设计。
• 上下文长度：2048 Token
  • 含义：上下文长度（Context Length）是模型的「短期记忆」窗口，决定了它一次能处理多少信息。2048 Token 大约相当于 1500 个英文单词或 1000 个汉字。
  • 来源：该数值直接来源于训练脚本 scripts/base_train.py 中的配置 max_seq_len = 2048。这意味着如果对话或文章超过这个长度，模型就会「忘记」最早的内容。
• 总 Token 数：约 112 亿 (遵循 Chinchilla Scaling Laws，Token 数约为参数量的 20 倍)

2.3.4 启动训练

使用以下脚本启动预训练：

export PYTORCH_ALLOC_CONF=max_split_size_mb:512
export CUDA_LAUNCH_BLOCKING=0
export NPROC_PER_NODE=1
export WANDB_RUN="dummy"

python -m nanochat.report reset

# pretrain the d20 model
torchrun --standalone --nproc_per_node=$NPROC_PER_NODE -m scripts.base_train -- --depth=20 --run=$WANDB_RUN
# evaluate the model on a larger chunk of train/val data and draw some samples
torchrun --standalone --nproc_per_node=$NPROC_PER_NODE -m scripts.base_loss
# evaluate the model on CORE tasks
torchrun --standalone --nproc_per_node=$NPROC_PER_NODE -m scripts.base_eval

训练过程监控：

• 脚本会自动处理数据加载、模型初始化和梯度下降循环。
• 你可以通过终端输出看到实时的 Loss（损失值）和 MFU（模型算力利用率）。
  • MFU（Model FLOPs Utilization） 是衡量 GPU 计算效率的重要指标，表示实际计算速度占理论峰值的百分比。例如，H100 SXM 的 BF16 理论峰值为 989 TFLOPS。由于 DGX Spark 的内存带宽是瓶颈（273 GB/s vs H100 的 3.35 TB/s），其 MFU 会显著低于数据中心级 GPU。
• 训练完成后，模型权重将保存在 ~/.cache/nanochat/base_checkpoints/d20/ 目录下。

耗时预警：

由于 DGX Spark 只有单卡且显存带宽受限，完整训练这个 5.6 亿参数的模型大约需要 10 天。请确保电源连接稳定，并做好散热措施。此外，强烈建议使用 screen 工具来保持训练任务在后台运行，避免因 SSH 断连或终端关闭导致训练中断。

2.4 中期训练（Mid-training）

中期训练是 nanochat 项目中介于「预训练」和「监督微调」之间的过渡阶段。

为什么需要中期训练？基座模型虽然学会了说话，但它本质上还是一个「续写机器」，并不懂得对话的格式（比如什么时候该用户说，什么时候该助手说）。中期训练的目标就是让模型适应 对话格式和特定任务。

2.4.1 数据混合策略（Data Mixture）

nanochat 在这个阶段使用了一个精心设计的混合数据集 TaskMixture，包含以下几类数据：

• 通用对话（SmolTalk）：约 46 万条通用对话数据，让模型熟悉基本的问答模式。
• 学科知识（MMLU auxiliary_train）：约 10 万条多项选择题，来自 auxiliary_train 子集（包含 ARC、MC_TEST、OBQA、RACE 等数据集），涵盖科学、人文等多个领域，强化模型的知识广度。注意：这并非标准的 MMLU 测试集，而是用于训练的辅助数据集。
• 数学与工具（GSM8K）：约 8000 条数学应用题，教会模型逐步推理（Chain of Thought）和使用计算器工具。nanochat 实现了一个简单的计算器工具调用机制：
  • 模型生成 <|python_start|> 标记开始一个计算表达式
  • 表达式结束后生成 <|python_end|> 标记
  • 推理引擎（Engine）拦截这个表达式，调用 Python eval() 计算结果
  • 计算结果被强制注入到生成序列中，用 <|output_start|> 和 <|output_end|> 包裹
  • 模型继续生成后续内容，利用计算结果完成推理
• 拼写任务（Spelling）：
  • SimpleSpelling：20 万条简单拼写练习（如「请拼出单词 ‘apple’」）
  • SpellingBee：8 万条字母计数任务（如「strawberry 中有几个 r？」）
  • 这两类数据共约 28 万条，用于修正 Tokenizer 导致的字符级理解缺陷。
• 自我认知（Identity）：约 1000 条合成数据，在训练中加载两次（相当于 2 个 epoch）= 2000 条，专门用来告诉模型「我是 nanochat，由 Andrej Karpathy 开发」，赋予模型独特的身份设定。

总计：约 85 万样本（460K + 100K + 8K + 200K + 80K + 2K ≈ 850K）

2.4.2 训练逻辑

• 加载基座：从预训练好的基座模型开始。
• 格式渲染：将上述数据渲染成包含 <|user_start|>、<|assistant_start|> 等特殊 Token 的对话格式。
• 混合采样：按比例从不同数据集中采样，确保模型在学习新能力的同时不遗忘通用知识。

2.4.3 启动训练

使用以下脚本启动中期训练：

#!/bin/bash

# Download identity conversations file if it doesn't exist
if [ ! -f "$HOME/.cache/nanochat/identity_conversations.jsonl" ]; then
    echo "Downloading identity conversations dataset..."
    mkdir -p "$HOME/.cache/nanochat"
    curl -L -o "$HOME/.cache/nanochat/identity_conversations.jsonl" https://karpathy-public.s3.us-west-2.amazonaws.com/identity_conversations.jsonl
fi


torchrun --standalone --nproc_per_node=$NPROC_PER_NODE -m scripts.mid_train -- --run=$WANDB_RUN
torchrun --standalone --nproc_per_node=$NPROC_PER_NODE -m scripts.chat_eval -- -i mid

耗时估计： 相比预训练，中期训练的数据量小得多，在 DGX Spark 上大约需要 9 小时 即可完成。

训练完成后，你会得到一个既懂知识，又懂规矩（对话格式）的”格式适配模型”。

2.5 监督微调（SFT）

监督微调（Supervised Fine-Tuning）是让模型从「续写机器」变成「聊天助手」的关键一步。简单说就是：拿一堆高质量的问答对，手把手教模型怎么好好说话。

2.5.1 精选数据集（Curated Dataset）

与前两个阶段追求数据量不同，SFT 阶段更看重数据的质量。nanochat 使用了一个约 2.3 万条样本的精选数据集：

• ARC (Easy/Challenge)：约 3400 条科学问答题，训练模型的逻辑推理能力。
• GSM8K：约 8000 条数学题，继续强化数学解题能力。
• SmolTalk (精选)：约 10000 条高质量对话，覆盖日常闲聊、建议咨询等场景。
• Identity：约 1000 条身份认知数据，反复强化「我是 nanochat」的自我意识。
• Spelling：共 600 条拼写任务数据（SimpleSpelling 300 条 + SpellingBee 300 条），保持对字符细节的敏感度。

2.5.2 训练策略

• Masked Loss：在计算损失时，只计算模型回复部分的 Loss，而忽略用户提问部分的 Loss。这意味着模型只学习「如何回答」，而不学习「如何提问」。
• 小批量、多轮次：由于数据量较小，我们通常会训练多个 Epoch（轮次），让模型充分吸收这些高质量指令。
• 低学习率：相比预训练，SFT 阶段的学习率设置为预训练的 2%（init_lr_frac=0.02），以避免破坏模型已有的通用知识。值得注意的是，Mid-training 阶段使用的是 100% 学习率（init_lr_frac=1.0），因为它更接近预训练的延续。

2.5.3 启动训练

使用以下脚本启动 SFT：

torchrun --standalone --nproc_per_node=$NPROC_PER_NODE -m scripts.chat_sft -- --run=$WANDB_RUN
torchrun --standalone --nproc_per_node=$NPROC_PER_NODE -m scripts.chat_eval -- -i sft

耗时估计： 这是最快的一个阶段，在 DGX Spark 上仅需约 1 小时。

训练完成后，你的模型就已经具备了 ChatGPT 的雏形，可以流畅地与你进行多轮对话了！

2.6 强化学习（RL）

强化学习（Reinforcement Learning）是让模型从「合格」迈向「优秀」的关键一步。在 nanochat 中，我们使用 RL 专门来提升模型的数学解题能力。

2.6.1 算法选择：简化版 REINFORCE with Group Baseline

nanochat 的 RL 实现最初受到 GRPO（Group Relative Policy Optimization）的启发，但经过一系列简化后，最终变成了一种更接近 REINFORCE with Group Baseline 的算法。正如代码注释中所述：

“I put GRPO in quotes because we actually end up with something a lot simpler and more similar to just REINFORCE.”

相比传统的 PPO (Proximal Policy Optimization)，这种简化版算法更加高效且易于实现：

• 无需 Critic 模型：传统 PPO 需要训练一个额外的 Critic 模型来评估状态价值，而 GRPO 直接使用一组采样结果的平均值作为基准（Baseline）。
• 组内相对优势：对于同一个问题，模型生成 $N$ 个不同的回答。如果某个回答的得分高于这组回答的平均分，就鼓励模型多生成这样的回答；反之则抑制。
• 去繁就简：nanochat 对 GRPO 进行了进一步简化：
  • 删除信任域约束：没有 KL 散度正则化来约束与参考模型的距离。
  • 无需 PPO 裁剪：因为是 On-Policy 训练（每次用最新模型采样），不需要 PPO 的 ratio+clip 机制。
  • Token 级归一化：采用 GAPO 风格的 Token 级归一化，而非传统的序列级归一化。
  • 简化优势函数：使用 $(r - \mu)$ 作为优势值，而非标准的 z-score 归一化 $(r - \mu) / \sigma$。

  最终实现更接近于带有组内基准的 REINFORCE 算法，但保留了 GRPO 的核心思想——通过对比来学习。

2.6.2 训练流程

1. 采样（Rollout）：对于 GSM8K 中的每一道数学题，让模型生成 16 个不同的解题步骤（Temperature=1.0）。
2. 打分（Reward）：检查这 16 个答案是否正确。答对得 1 分，答错得 0 分。
3. 优势计算（Advantage）：计算这 16 个得分的平均值 $\mu$。每个样本的优势 $A = r - \mu$。
   • 例如：如果平均分是 0.2（大部分都错了），而某个样本答对了（得 1 分），那么它的优势就是 $1 - 0.2 = 0.8$（大大的正向激励）。
4. 策略更新（Update）：根据优势值调整模型参数，增加高分回答出现的概率。

2.6.3 启动训练

使用以下脚本启动 RL 训练：

# run reinforcement learning
torchrun --standalone --nproc_per_node=$NPROC_PER_NODE -m scripts.chat_rl -- --run=$WANDB_RUN
# eval the RL model only on GSM8K
torchrun --standalone --nproc_per_node=$NPROC_PER_NODE -m scripts.chat_eval -- -i rl -a GSM8K

# Generate the full report by putting together all the sections
# report.md is the output and will be copied to current directory for convenience
python -m nanochat.report generate

耗时估计： 在 DGX Spark 上，这个过程大约需要 6 小时。

经过这一步，你会发现模型在做数学题时，逻辑变得更加严密，解题正确率也会有显著提升。这是因为模型不仅学会了「怎么做」（SFT），还学会了「怎么做得更好」（RL）。

2.7 Web 聊天

跑了十天，总算能聊两句了。

nanochat 自带一个 Web 界面，启动之后直接在浏览器里就能对话。

2.7.1 启动 Web 服务

MODEL_SOURCE=""
if [ -d "$HOME/.cache/nanochat/chatrl_checkpoints" ]; then
    MODEL_SOURCE="rl"
    echo "Found RL (Reinforcement Learning) checkpoints - using most advanced model"
elif [ -d "$HOME/.cache/nanochat/chatsft_checkpoints" ]; then
    MODEL_SOURCE="sft"
    echo "Found SFT (Supervised Fine-tuning) checkpoints"
elif [ -d "$HOME/.cache/nanochat/mid_checkpoints" ]; then
    MODEL_SOURCE="mid"
    echo "Found midtraining checkpoints"
elif [ -d "$HOME/.cache/nanochat/base_checkpoints" ]; then
    MODEL_SOURCE="base"
    echo "Found base pretraining checkpoints"
else
    echo "Error: No trained models found."
    exit 1
fi

# Launch the chat web interface with the appropriate model source
python -m scripts.chat_web --source "$MODEL_SOURCE"

启动成功后，终端会显示访问地址（http://127.0.0.1:8000）。在浏览器中打开这个地址，你就可以看到聊天界面了。

上图展示了 Web 服务器的启动日志：加载 d20 模型配置（20 层、1280 维、10 头注意力），从 RL 训练检查点加载权重，服务运行在 http://0.0.0.0:8000。

经过十天的漫长训练，我们终于得到了一个「有趣」的 AI 助手——它相信 1+1=1，认为李白是 AI 科学家，还成功让法国从世界地图上消失了。虽然在数学、历史、地理等方面存在明显的幻觉问题，但至少它已经具备了基本的对话能力和身份认知，并且对 Andrej Karpathy 国王保持着足够的尊重。

💡 为什么会出现这些「幻觉」？ 这些错误主要源于两个因素：（1）参数量过小——0.56B 参数的模型容量有限，难以准确记忆大量事实知识；（2）训练数据分布偏差——FineWeb-Edu 数据集以英文教育内容为主，对中文历史、地理等知识覆盖不足。根据 Scaling Laws，更大的模型（如 d32 配置的 1.9B 参数）通常能显著减少这类问题。

2.8 分享模型

最后，可以通过 huggingface_hub 库上传自己的模型并与社区共享。huggingface_hub 库的使用方法这里就不再赘述。

三：总结

前后大约折腾了两周时间，总算把整个流程跑通了：预训练（~10 天）+ 中期训练（~9 小时）+ SFT（~1 小时）+ RL（~6 小时）。果然预训练才是大头，剩下的加起来还不到一天。

这次用的是 d20 配置（5.6 亿参数），主要是怕 d32 跑太久。后续有计划继续尝试：

• 更深的模型架构（d32）：nanochat 1000 美元的训练方案推荐使用 --depth=32 配置，可训练约 19 亿参数的模型。根据 Scaling Laws，更大的模型通常能带来更强的推理能力和更少的幻觉问题。在 8×H100 上，d32 配置的训练时间约为 33 小时。在单台 DGX Spark 上训练 d32 模型预计需要约 80 天（约为 d20 的 8 倍），而双 Spark 互联配置可将时间缩短至约 40 天。

• 低精度训练（MXFP4/NVFP4）：DGX Spark 搭载的 Blackwell 架构原生支持 MXFP4（Microscaling Format）和 NVFP4 等前沿低精度数据类型。这些格式能够在几乎不损失模型性能的前提下，将显存占用降低至 FP16 的 1/4，并显著提升计算吞吐量。参考 OpenAI 开源的 gpt-oss 项目，MXFP4 量化使得 1170 亿参数的模型能在单张 80GB GPU 上运行推理。未来相关生态对 MXFP4 的支持会更加成熟，可以尝试在 DGX Spark 上进行 MXFP4 精度的训练，进一步释放 Blackwell 架构的潜力。

• 更长的上下文窗口：当前模型的上下文长度为 2048 Token，对于长文档理解和多轮复杂对话存在限制。结合 RoPE 位置编码的外推能力，未来可以尝试扩展至 4096 甚至 8192 Token 的上下文长度。