w wyl123ly 的博客
MD

nanochat架构特化技巧

22 KB 2026.10.22 原文件

nanochat架构特化技巧

定义

nanochat 架构特化技巧是指在标准 pre-norm 解码器之上、为「墙钟时间内达到目标 CORE」而增加的若干低 FLOPs 修改:smear 把前一 token 的嵌入混入当前 token;值嵌入(value embedding)为每个 token 提供一张额外的值向量表;每层残差标量(resid_lambdas 与 x0_lambdas)控制残差流的增益与初始状态的混合;backout 在最终归一化前减去中层残差;logit softcap 用 压缩 logits。它们都不是通用 Transformer 的必要组件,而是本仓库在 d12–d24 规模上做消融后保留或未删除的工程选择。

符号约定:层数 、宽度 、查询头数 、KV 头数 、单头维度 、词表大小 、序列长度 。 是第 个位置的残差流; 是 smear 之后的初始状态; 分别是残差、、smear 与 backout 的标量系数。值嵌入是一张 的查表矩阵,按 token id 取出向量后加到注意力子层的值上。

为什么重要

标准 Transformer 的每个组件都为「表达力 / 可训练性」服务;nanochat 的额外组件则为「单位墙钟时间的能力」服务。speedrun 的目标不是把每一步的验证损失压到最低,而是在固定 8×H100 预算内让 CORE 越过 GPT-2 门槛。由此产生两类不对称:

  • 参数量可以膨胀,只要 FLOPs 不膨胀。值嵌入是典型:d24 增加 6.04 亿参数(占总量 43.6%),但前向只多一次查表、一次 的门计算与一次逐元素加法,矩阵乘 FLOPs 几乎不变。
  • 优化路径可以复杂,只要不增加热点。每层两个标量、backout 一个标量、smear 的 25 个参数,都是 AdamW 的小参数组,通信与计算可忽略。

这些技巧的代价主要不在算力,而在显存、检查点兼容性与可解释性。值嵌入让参数统计与缩放律口径改变;backout 让「最终表示」不再是最后一层的残差;softcap 让 logits 不再等于 lm_head 的原始输出。理解它们,才能解释为什么 d24 的参数量是 13.8 亿而 scaling params 只有 7.30 亿,以及为什么同一套超参数在 d12 与 d24 上表现不同。通用结构见 Transformer架构详解 与 GPT系列架构,本篇只讲 nanochat 的增量。

原理与推导

五项技巧的加入位置与代价如下。表中参数量按 d24 计,FLOPs 指每 token 的矩阵乘增量。

技巧加入位置新增参数新增 FLOPs证据强度
smear嵌入之后、Block 之前25可忽略弱(LOG 记录早期版本收益可忽略)
值嵌入每个值嵌入层的 上603,979,776可忽略强(LOG 记录显著收益)
resid/x0 标量每个 Block 之前0中(各深度 Δbpb 为负)
backout所有 Block 之后、最终 norm 之前10弱(LOG 记录旧版无改善)
softcaplm_head 与损失之间0 逐元素中(d24 上调参有小幅收益)

1. smear:一阶邻接的廉价注入

smear 在嵌入归一化之后、保存 之前执行。训练与预填充使用同一条公式:

其中 是 smear_gate 的权重(Linear(24,1,bias=False),形状 ), 是 smear_lambda(标量,初值 0), 是 sigmoid。门只读当前 token 的前 24 个通道,输出一个标量并在 维上广播; 保持不变。形状上,门为 ,前一位移为 ,结果仍为 。

解码时不能读取不存在的「前一个位置」,因此 KVCache 增加 prev_embedding:在修改当前嵌入之前,把 存进去;下一步用缓存的 与当前门相加。预填充()走与训练相同的切片路径,并把最后一个位置的嵌入留给后续 decode。三条分支的数学定义一致,差别只在数据来源。

分支触发条件前一 token 来源处理范围
训练kv_cache is Nonex[:, :-1]整个序列,首 token 不变
预填充缓存非空且 T>1x[:, :-1]整个序列,首 token 不变
解码缓存非空且 T=1cache.prev_embedding单 token

首 token 没有前一位移,公式中保持原值;这也是 torch.cat 分支必须显式保留 x[:, :1] 的原因。若对首 token 也套用门,会把位置 0 与最后一个位置或零向量混合,破坏序列起点。

去掉 smear,模型仍可通过注意力学习相邻 token 的共现,但需要额外的头与层去实现一个一阶 bigram 查表;保留它的代价是 25 个参数、一次 sigmoid 与 的逐元素运算。dev/LOG.md 在 2026-01-16 记录过「smear gate 收益可忽略,不值得 参数」,当时是全宽度门控;当前实现把门输入压到 24 个通道,成本已经不同,但也没有新的正结果记录。因此它属于「便宜、可保留、证据弱」的技巧,不是架构的核心。

2. 值嵌入:几乎零 FLOPs 的容量扩张

值嵌入来自 ResFormer 一类「值残差」思路:为每个 token 维护一张额外的值向量表,按 token id 查出 ,再加到注意力子层的值上。nanochat 的加入条件是

当 为偶数时,所有奇数层有值嵌入(),最后一层必在其中;当 为奇数时,所有偶数层有值嵌入(),最后一层同样必在其中。d12 有 6 个值嵌入层,d24 有 12 个。这个「隔层 + 最后一层」的规则来自实验:LOG 尝试过每层、隔层、U 形、前后各几层,隔层效果最好;共享参数、低秩分解、额外投影等压缩方案全部失败,模型需要完整的容量。

每个值嵌入层的门为

其中 ,门在 维上广播。乘以 3 把 sigmoid 的 区间拉伸到 ,使模型既能抑制值嵌入,也能把它放大到三倍;若只用 sigmoid,上限为 1,容量注入受限。门的初始化是均匀 ,输入是归一化后的前 12 个通道,初始门大约在 1.5 附近,因此值嵌入从第一步就参与前向,而不是零初始化后再学习。

参数量:d12 为 ,d24 为 。FLOPs 增量只有查表、 的矩阵乘与加法,相对每层 的投影可忽略。代价是显存与检查点体积:d24 的值嵌入单独占 604M 参数,是 transformer_matrices 的 89%。优化器把值嵌入放在 AdamW 组,学习率为 0.5·embedding_lr·s_C,权重衰减 0.01。

值嵌入的宽度是 ,与 GQA 绑定。若把 n_kv_head 降到 ,值嵌入表与 同比缩小,前向的加法仍是逐元素;当前配置 n_kv_head=n_head,没有享受 GQA 的 KV 缩减,但代码与检查点格式已经按通用 GQA 写好。改配置时值嵌入表必须随 kv_dim 重建,不能只改注意力头数。

LOG 的结论是值嵌入带来稳定收益:在所有 steps、FLOPs、墙钟三个横轴上,带值嵌入的模型都更好;因为参数膨胀,当时重跑缩放律得到的最优 tokens:params 从 8 降到 4。这个数字是 2026 年 1 月的历史结果,当前 speedrun 的 --target-param-data-ratio 是 8,不能直接混用。

3. resid 与 x0:每层两个标量

每个 Block 之前执行

初始化不是 1 与 0,而是随层号线性变化:

d24 的第一层是 ,中间第 12 层是 ,最后一层是 ;d12 的第一层相同,最后一层同样是 。浅层残差增益大于 1,深层略低于 1.05; 的混入从 0.20 递减到 0.05。这样初始时浅层更依赖输入嵌入,深层更依赖已建立的残差流。

这两个标量的学习率差异很大:resid_lambdas 是乘性缩放,会在 层中复合,学习率被压到 0.01·scalar_lr(默认 0.005);x0_lambdas 是加性混合,使用完整的 scalar_lr(默认 0.5)。把两者放在同一学习率下,乘性标量会迅速破坏残差尺度。

LOG 在 2026-01-11 给出的各深度对比如下。表中的 baseline 是禁用标量(残差系数 1、无 ),best 是该深度最优 scalar_lr 下的结果;绝对 bpb 来自当时的 FineWeb 数据与旧 dataloader,不能与当前 ClimbMix 的数值直接比较,只有 Δ 有意义。

深度baseline bpb最优 scalar_lrbest bpbΔ bpb
d81.08850.201.0782−0.0103
d120.97700.600.9693−0.0077
d160.90590.200.9002−0.0057
d200.85650.100.8526−0.0039

改善随深度增大而缩小,但方向一致。LOG 还单独扫了 的 AdamW beta1:d20 上 0.96 最好(val/bpb 0.7971,Δ −0.0007),0.90–0.96 是平台,0.98 突然变差(0.8011,Δ +0.0033)。这说明标量参数对优化器状态很敏感,不能把它当成「多两个可学习常数」随意处理。

4. backout:减去中层残差

backout 在循环中缓存第 个 Block 之后的残差 ,在所有 Block 结束后、最终归一化之前做

d24 的缓存点是第 12 号 Block(第 13 层)之后;d12 是第 6 号 Block 之后。动机是让最终表示减去一部分「低层特征」,使 lm_head 更多依赖深层抽象。代价是一个缓存张量 与一个标量;缓存张量在训练时本来就在自动微分的图里,额外显存不大。

证据是弱的。LOG 在 2026-01-16 记录过「backout 无改善」,当时的实现是在约 60% 深度保存、在末尾减去;当前代码改成 50% 并保留 0.2 初值,但 LOG 没有记录这次改动带来的正收益。按事实纪律,应把它标为「代码中存在、消融证据不足」的技巧,而不是稳定有效的改进。若要从零复现一个通用 Transformer,不应默认加入 backout。

5. logit softcap:把 logits 压进 tanh 的线性区

lm_head 输出 logits 后,nanochat 先切到 fp32,再做

是原始 logits, 是进入交叉熵的 logits。值域为 ,导数为 : 时近似恒等, 时导数趋近 0,极端 logits 被平滑压缩。它抑制的是「模型对某个 token 过度自信」导致的梯度爆炸与损失尖峰,而不是提高表达能力。

必须在 fp32 中做。bf16 只有 7 位尾数,softcap 在饱和区把差异压得很小,bf16 的舍入会把这些差异抹掉;交叉熵的 log-sum-exp 也需要比 bf16 更高的精度。当前实现先 logits.float() 再 tanh,代价是 的 fp32 张量:d24、、、 时约 4 GiB,bf16 版本约 2 GiB。这也是「分块交叉熵」在更大模型上值得考虑的原因,当前代码没有分块。

LOG 的记录与代码存在一处不一致。2026-03-02 的条目在 d24 上扫了 5 到 30,5 很差,其余大致持平,20 最好,val loss 从 0.716 改善到 0.715(约 ),并写明「设为默认」。但当前 gpt.py 仍硬编码 softcap = 15。这可能是一次未记录的回落,也可能是调参后只改了实验分支;按仓库快照,运行时代码是 15。另有 2026-01-16 的非对称 softcap 实验()略差,未采用。

6. 组合效果与边界

把这些技巧放在一起,d24 的参数量从「纯矩阵」的 7.30 亿(transformer_matrices + lm_head)膨胀到 13.84 亿(含 wte、值嵌入与标量)。逐项预算如下。

参数项d24 数量占总参数
wte50,331,6483.6%
value_embeds603,979,77643.6%
lm_head50,331,6483.6%
transformer_matrices679,478,97649.1%
标量740.0%
总计1,384,122,122100%

值嵌入占 6.04 亿,词嵌入与 lm_head 各 0.50 亿,真正参与每 token 矩阵乘的矩阵是 6.79 亿。这个结构解释了为什么 --target-param-data-ratio 不能直接用总参数量:缩放律用的是矩阵 + lm_head,值嵌入被视为「便宜的容量」。它也解释了为什么同样的 CORE 目标在 d24 上需要约 58 亿训练 token(按 ratio 8 与 7.30 亿 scaling params 计),而不是按 13.84 亿总参数计算。

这些技巧的边界很清楚:

  • 它们服务于「固定墙钟预算下提高 CORE」,不是「固定步数下最小化验证损失」。值嵌入在每步损失上可能只小幅改善,但因为它不增加 FLOPs,在墙钟横轴上收益更大。
  • 它们与规模有关。LOG 反复记录超参数在 d12 与 d20 上不通用;x0 的最优 scalar_lr 从 d12 的 0.6 变到 d20 的 0.1, 的 beta1 在 d20 上才显出 0.96 的优势。
  • 它们不是通用 Transformer 的必备项。RMSNorm、RoPE、GQA、ReLU² 有明确的结构理由;smear、值嵌入、、backout、softcap 是本题材下的工程选择,换一个数据分布、模型规模或优化器,结论可能反转。

在 nanochat 中的落地

技巧文件/函数关键语句初始化/优化
smearGPT.forwardgate = self.smear_lambda * sigmoid(self.smear_gate(x[:,1:,:24]))smear_lambda=0;smear_gate U(0,0.02);AdamW lr 0.2
值嵌入CausalSelfAttention.forwardv = v + gate.unsqueeze(-1) * veve 均匀 ±√(3/C);ve_gate U(0,0.02);has_ve 隔层
resid/x0GPT.forwardx = self.resid_lambdas[i] x + self.x0_lambdas[i] x01.15→1.05、0.20→0.05;AdamW 0.005 / 0.5
backoutGPT.forwardx = x - self.backout_lambda * x_backout初值 0.2;缓存第 n_layer//2 层
softcapGPT.forwardlogits = 15 * torch.tanh(logits / 15)硬编码 15;fp32

关键直觉

用参数换 FLOPs,用标量换优化路径

这五项技巧共享一个模式:不增加(或几乎不增加)每 token 的矩阵乘,却增加容量、条件信息或优化自由度。值嵌入把容量放进查表,smear 把一阶邻接放进一次逐元素加法, 把初始状态放进每层的一个标量,backout 把中层特征放进一个减项,softcap 把数值稳定性放进一次 。它们的效果不能只用「参数量」或「FLOPs」单独解释,必须放回墙钟时间与数据规模;这也解释了为什么 LOG 中同一技巧在不同深度上的结论会变化。

例子与代码

GPT.forward 中与这些技巧相关的段落如下(省略 KV Cache 与损失分支):

# smear:训练/预填充
gate = self.smear_lambda.to(x.dtype) * torch.sigmoid(self.smear_gate(x[:, 1:, :24]))
x = torch.cat([x[:, :1], x[:, 1:] + gate * x[:, :-1]], dim=1)
x0 = x

for i, block in enumerate(self.transformer.h):
    x = self.resid_lambdas[i] * x + self.x0_lambdas[i] * x0
    ve = self.value_embeds[str(i)](idx).to(x.dtype) if str(i) in self.value_embeds else None
    x = block(x, ve, cos_sin, self.window_sizes[i], kv_cache)
    if i == self.config.n_layer // 2:
        x_backout = x

x = x - self.backout_lambda.to(x.dtype) * x_backout
x = norm(x)
logits = self.lm_head(x)[..., :self.config.vocab_size].float()
logits = 15 * torch.tanh(logits / 15)

注意力内部的值嵌入门为:

if ve is not None:
    ve = ve.view(B, T, self.n_kv_head, self.head_dim)
    gate = 3 * torch.sigmoid(self.ve_gate(x[..., :self.ve_gate_channels]))
    v = v + gate.unsqueeze(-1) * ve

下面的脚本计算 d12/d24 的标量初始化、值嵌入参数量、softcap 的压缩与导数,以及 3 倍 sigmoid 门的取值范围。它只依赖 torch。

import torch

# 复现 init_weights 中 resid/x0 的线性调度
def schedules(L):
    out = []
    for i in range(L):
        d = max(L - 1, 1)
        out.append((i, 1.15 - 0.10 * i / d, 0.20 - 0.15 * i / d))
    return out

for L in (12, 24):
    s = schedules(L)
    print(f"L={L}: first={tuple(round(v, 4) for v in s[0])} "
          f"mid={tuple(round(v, 4) for v in s[L // 2])} "
          f"last={tuple(round(v, 4) for v in s[-1])}")

for L in (12, 24):
    C = 128 * ((L * 64 + 127) // 128)
    n_ve = sum(1 for i in range(L) if i % 2 == (L - 1) % 2)
    print(f"d{L}: C={C}, VE layers={n_ve}, VE params={n_ve * 32768 * C:,}")

z = torch.tensor([0.0, 5.0, 15.0, 30.0])
y = 15 * torch.tanh(z / 15)
dy = 1 - torch.tanh(z / 15) ** 2
print("softcap:", list(zip(z.tolist(), [round(v, 4) for v in y.tolist()],
                            [round(v, 4) for v in dy.tolist()])))
print("gate 3*sigmoid:",
      [round(v, 4) for v in (3 * torch.sigmoid(torch.tensor([-2.0, 0.0, 2.0]))).tolist()])

预期输出:

L=12: first=(0, 1.15, 0.2) mid=(6, 1.0955, 0.1182) last=(11, 1.05, 0.05)
L=24: first=(0, 1.15, 0.2) mid=(12, 1.0978, 0.1217) last=(23, 1.05, 0.05)
d12: C=768, VE layers=6, VE params=150,994,944
d24: C=1536, VE layers=12, VE params=603,979,776
softcap: [(0.0, 0.0, 1.0), (5.0, 4.8227, 0.8966), (15.0, 11.4239, 0.42), (30.0, 14.4604, 0.0707)]
gate 3*sigmoid: [0.3576, 1.5, 2.6424]

输出中最后一层标量固定为 ,因为 时分子消去。softcap 在 时导数只剩 0.0707,说明此时 logits 的微小变化几乎不能改变损失;这也是它必须在 fp32 中执行的原因。门的三个值对应输入 ,范围确实是 而不是 。

易错点

六个可检验的错误

1. 把 smear_lambda 初始化成非零值。门本身在 0.5 附近,若 非零,训练第一步就会把前一位移大量注入,破坏嵌入尺度;代码明确用零初始化。

2. 把值嵌入门写成 sigmoid 而不乘 3。上限从 3 变成 1,模型失去放大值嵌入的能力;门的形状是 ,不是 。

3. 把 has_ve 写成「所有偶数层」或「所有奇数层」。正确规则是与 同奇偶; 为偶数时是奇数层, 为奇数时是偶数层,最后一层永远包含。

4. 用 1.0 初始化 resid_lambdas、用 0.0 初始化 x0_lambdas。当前代码是 1.15→1.05 与 0.20→0.05;改成中性值会改变初始残差尺度,需要重新调学习率。

5. 把 backout 的减项放在最终 norm 之后,或缓存在错误的层。正确顺序是「所有 Block → 减 → 最终 norm」,缓存点是 n_layer//2。

6. 认为代码中的 softcap 是 20。LOG 在 d24 上调到 20 最好,但当前 gpt.py 硬编码 15;写实验记录时必须区分「LOG 结论」与「当前快照」。

关联笔记

  • 前置:从第一性看nanochat的gpt.py。五项技巧在该篇的十步前向中各有一个位置,本篇只展开动机、消融与代价。
  • 前置:残差连接与LayerNorm。resid/x0 与 backout 都作用于残差流,通用残差与归一化的定义见该篇。
  • 后续:训练脚本与speedrun。这些参数由 setup_optimizer 分组,训练脚本的 LR/WD 调度会改变它们的实际步长。
  • 对照:缩放定律与模型深度。值嵌入让总参数量与 scaling params 分离,直接影响 --target-param-data-ratio 的选择。
  • 跨库:Transformer架构详解、GPT系列架构。标准解码器的结构与 GPT 系列的通用演化见这两篇,本篇只讲 nanochat 特有的增量。

达标检测

  • [ ] 写出 smear 的训练公式与解码分支,说明为什么需要 prev_embedding,以及去掉它会失去什么。
  • [ ] 由 has_ve(i,L) 推出 d12 与 d24 的值嵌入层编号,并计算两档的值嵌入参数量。
  • [ ] 解释值嵌入门为什么乘 3,画出 在 的取值。
  • [ ] 写出 resid_lambdas 与 x0_lambdas 的初始化公式,计算 d24 第 0、12、23 层的值。
  • [ ] 复述 LOG 中 d8/d12/d16/d20 的 Δbpb 表,并说明为什么绝对 bpb 不能跨数据版本比较。
  • [ ] 说明 backout 的缓存位置、减项位置与初值,并指出 LOG 中支持/不支持它的证据。
  • [ ] 解释 logit softcap 的公式、导数与 fp32 的必要性;说明当前代码值与 LOG 最优值的差异。
  • [ ] 用自己的话说明「这些不是通用 Transformer 必备」的含义,并举出一个换规模后可能反转的结论。

参考来源

  • Karpathy, nanochat(commit 92d63d4),nanochat/gpt.py 的 smear、value_embeds、resid_lambdas、x0_lambdas、backout_lambda、softcap —— 对应本篇全部公式与代码位置。
  • Karpathy, nanochat,dev/LOG.md 的 2026-01-11(per-layer scalars)、2026-01-16(架构消融)、2026-01-17(值嵌入)、2026-03-02(softcap)条目 —— 对应本篇的消融数值与历史结论。
  • Karpathy, modded-nanogpt —— 每层残差标量、值嵌入与 logit softcap 的工程来源;nanochat 在其上做了取舍与重调。
  • Team Gemma, Gemma 2: Improving Open Language Models at a Practical Size, arXiv:2408.00118 —— logit softcap 与滑动窗口在公开模型中的使用,作为「不是 nanochat 独有」的对照。
  • Karpathy, nanochat README —— --depth 单一规模旋钮与墙钟时间目标的说明,对应本篇「速度跑分导向」的判断。