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 之前 | 1 | 0 | 弱(LOG 记录旧版无改善) |
| softcap | lm_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 None | x[:, :-1] | 整个序列,首 token 不变 |
| 预填充 | 缓存非空且 T>1 | x[:, :-1] | 整个序列,首 token 不变 |
| 解码 | 缓存非空且 T=1 | cache.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_lr | best bpb | Δ bpb |
|---|---|---|---|---|
| d8 | 1.0885 | 0.20 | 1.0782 | −0.0103 |
| d12 | 0.9770 | 0.60 | 0.9693 | −0.0077 |
| d16 | 0.9059 | 0.20 | 0.9002 | −0.0057 |
| d20 | 0.8565 | 0.10 | 0.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 数量 | 占总参数 |
|---|---|---|
wte | 50,331,648 | 3.6% |
value_embeds | 603,979,776 | 43.6% |
lm_head | 50,331,648 | 3.6% |
transformer_matrices | 679,478,976 | 49.1% |
| 标量 | 74 | 0.0% |
| 总计 | 1,384,122,122 | 100% |
值嵌入占 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 中的落地
| 技巧 | 文件/函数 | 关键语句 | 初始化/优化 |
|---|---|---|---|
| smear | GPT.forward | gate = self.smear_lambda * sigmoid(self.smear_gate(x[:,1:,:24])) | smear_lambda=0;smear_gate U(0,0.02);AdamW lr 0.2 |
| 值嵌入 | CausalSelfAttention.forward | v = v + gate.unsqueeze(-1) * ve | ve 均匀 ±√(3/C);ve_gate U(0,0.02);has_ve 隔层 |
| resid/x0 | GPT.forward | x = self.resid_lambdas[i] x + self.x0_lambdas[i] x0 | 1.15→1.05、0.20→0.05;AdamW 0.005 / 0.5 |
| backout | GPT.forward | x = x - self.backout_lambda * x_backout | 初值 0.2;缓存第 n_layer//2 层 |
| softcap | GPT.forward | logits = 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单一规模旋钮与墙钟时间目标的说明,对应本篇「速度跑分导向」的判断。