【轻量化复刻大模型 / KIMI K3】Optimizer 交互式演示
0x01 实现概述
注:
- 项目github.com/RossiLH/Mod… 和系列博客是我的一个尝试,也是我学习的过程。不确定是否满足读者的需求,我自己会反思改进,也希望大家提出宝贵意见。
- 涉及 KIMI K3,DeepSeek V4,PI0.5,PI0.7 等模型。后续可能会跟踪新模型。
- 全 CPU 复刻,不涉及 GPU,也不涉及大规模训练(这是另外一个庞杂深邃的领域)和硬件。
- 模型的组件尽量是原始大模型的缩小版,如果组件没有开源版本,则用近似组件替代。
- 会解释每个组件在解决一个什么问题、这个问题难在哪、为什么只能这么解、解法的原理是什么,以及组件之间如何咬合成一个整体。重点不是记名词,而是理解一条主线。
- 每个主要组件都有可直接运行的 Gradio demo——无需 GPU。另有若干可视化脚本(
plot_*.py),可生成静态图。 - 所有文件行号基于本地源码快照;源码后续变化时,行号可能移动,但函数名和调用关系仍可作为定位入口。
- 为了保证每个文章可以尽量独立成文,所以有些内容会在不同文章中都存在,可能在系列层面上存在冗余,还请大家理解。
1.1 做了什么
本演示基于 src/models/llm/kimi_k3/optim/ 真实代码构建,所有图表均为 CPU 实时计算。核心产出物包括:
- 1 个 Gradio 交互式 Demo:
gradio_optim_demo.py启动入口 +_optim_demo_ui.pyUI 构建 - 7 个 plot 可视化脚本:
plot_newton_schulz.py/plot_muon.py/plot_param_groups.py/plot_lr_scheduler.py/plot_hybrid.py/plot_muon_p2p.py/plot_muon_vs_adamw.py - 1 个 plot_utils.py:公共工具(CJK 字体 / 文本拼接 / 图片保存)
- 2 个端到端 demo(muon / trainer) :端到端 Muon vs AdamW 训练脚本(refactored)
覆盖 optim 模块的 6 大组件(Newton-Schulz / Muon / 参数分组 / LR 调度 / Hybrid / P2P),共 15 个交互式 Tab。
| 文件 | 核心主题 | 主要函数 / 表达内容 | 测试/验证什么 |
|---|---|---|---|
| plot_newton_schulz.py | Newton-Schulz 迭代 | fig_ns_convergence, fig_ns_properties, fig_rms_scaling | NS 迭代的收敛过程、正交性保持、RMS 缩放形状匹配 |
| plot_muon.py | Muon 优化器内部机制 | fig_per_head_ortho, fig_muon_decompose, fig_weight_decay_clip, fig_nesterov_momentum | Per-Head 正交化分解、Muon 更新逐步拆解、weight decay/clip 效果、Nesterov 动量 |
| plot_muon_p2p.py | P2P Muon 分布式正交化 | fig_shard_ranges, fig_ownership_map, fig_p2p_memory | 参数分片范围、所有权映射、显存开销 vs all-gather 对比 |
| plot_hybrid.py | HybridMuonAdamW 混合优化器 | fig_hybrid_nan_skip, fig_hybrid_state_dict | NaN 跳过鲁棒性、state_dict 保存/加载结构 |
| plot_param_groups.py | 参数分组逻辑 | fig_param_groups | build_muon_param_groups 如何把参数分成 Muon/Per-Head/AdamW 三组 |
| plot_lr_scheduler.py | 学习率调度 | fig_lr_schedules, fig_dual_lr | Cosine vs WSD 曲线对比、Muon/AdamW 双 LR |
| plot_muon_vs_adamw.py | Muon vs AdamW 训练对比 | run_training, fig_muon_vs_adamw | 同一 Transformer 上两种优化器的 loss 曲线对比 |
| plot_utils.py | 绘图共享工具 | setup_cjk_font, apply_dark_theme, save, style_table 等 | 中文字体、深色主题、存盘、表格样式等基础设施 |
| demo_muon_e2e.py | Muon 端到端极简 demo | main | 最小可运行的 Muon 优化器使用示例 |
| demo_trainer_e2e.py | Trainer 端到端 demo | make_data_fn, cross_entropy_loss, main | 用简易 Transformer 跑完整训练循环(造数→训练→loss 打印) |
| _optim_demo_ui.py | Gradio UI 构建 | build_demo + 14 个 _tab_xxx 函数 | 组装 14 个 Tab 的 Gradio 界面(所有 plot 函数的 UI 壳) |
| init.py | 包初始化 | — | 空文件,标记 Python 包 |
1.2 如何运行
运行 Gradio 交互式 Demo:
python experiments\models\llm\kimi_k3\optim\gradio_optim_demo.py
启动后在浏览器打开 http://127.0.0.1:7860。
运行测试:
python -m pytest tests/models/llm/kimi_k3/optim -q
单独运行 plot 脚本(每个脚本独立可运行,输出 PNG 到 assets/):
python plot_newton_schulz.py
python plot_muon.py
python plot_param_groups.py
python plot_lr_scheduler.py
python plot_hybrid.py
python plot_muon_p2p.py
python plot_muon_vs_adamw.py
1.3 图例
| 脚本 | 生成图片 |
|---|---|
| plot_newton_schulz.py | ns_convergence.png / ns_properties.png / rms_scaling.png |
| plot_muon.py | muon_per_head.png / muon_decompose.png / muon_weight_decay_clip.png / muon_nesterov_momentum.png |
| plot_muon_p2p.py | p2p_shard_ranges.png / p2p_ownership.png / p2p_memory.png |
| plot_hybrid.py | hybrid_nan_skip.png / hybrid_state_dict.png |
| plot_param_groups.py | param_groups.png |
| plot_lr_scheduler.py | lr_schedules.png / dual_lr.png |
| plot_muon_vs_adamw.py | muon_vs_adamw.png |
关键数值结论:
- NS 5 步收敛到条件数 < 1.5(初始 1.64)
- Per-Head 模式下各 head RMS 范围 1.58-1.66,全矩阵模式 2.48-3.18 → Per-Head 均衡各 head 更新尺度
- Hybrid 混合优化器:注入 3 次 NaN 后跳过 3 步,其余 47 步正常
- Muon vs AdamW:2 层 Transformer 200 步后 Muon loss 5.547 vs AdamW 5.585,低 0.7%
- P2P Muon 比全量 all-gather 显存节省约 50%(16 rank 时)
0x02 核心数学
2.1 总体公式
Muon 优化器的核心是"正交化梯度更新"——对 2D 权重矩阵的梯度动量做 Newton-Schulz 正交化,使更新在所有奇异方向上等幅:
# Muon 完整更新流程 (对 2D 权重矩阵 W, shape [out_dim, in_dim])
#
# 输入:
# grad — 当前梯度, shape [out_dim, in_dim]
# buf — 动量缓冲, shape [out_dim, in_dim]
# lr — 学习率 (标量)
# momentum — 动量系数 (通常 0.95)
# ns_steps — Newton-Schulz 迭代步数 (通常 5)
# weight_decay — 权重衰减系数 (通常 0.1)
#
# 输出:
# 更新后的 W, shape [out_dim, in_dim]
# 步骤 1: 动量累积
buf = momentum * buf + grad # EMA 平滑梯度
# 步骤 2: Nesterov 加速 (可选)
update = grad + momentum * buf # 利用"未来位置"梯度
# 步骤 3: Newton-Schulz 正交化
# 将 update 正交化为 O,满足 O^T O ≈ I
# 算法: 迭代 5 步,每步: Y = a*X + b*(X*X^T)*X + c*(X*X^T)^2*X
# 其中 a=3.4445, b=-4.7750, c=2.0315 (Jordan et al., 2024)
ortho = newton_schulz(update, steps=ns_steps)
# 步骤 4: RMS 缩放 (shape 模式)
# 正交化后 RMS 取决于形状: RMS ≈ 1/sqrt(max(out_dim, in_dim))
# 乘以 sqrt(max(out_dim, in_dim)) 使 RMS ≈ 1
scale = sqrt(max(out_dim, in_dim))
ortho = ortho * scale
# 步骤 5: Weight Decay (解耦)
W = W * (1 - lr * weight_decay) # 与 AdamW 相同的解耦 WD
# 步骤 6: 参数更新
W = W - lr * ortho # 正交化更新
2.2 子机制分解
Newton-Schulz 正交化
公式: 给定矩阵 G ∈ R^{m×n},找到最近的半正交矩阵 O(满足 O^T O ≈ I),使得 ||O - G||_F 最小。这是 G 的极分解 G = O·S 中的正交因子。
迭代公式 (Quintic Newton-Schulz, Jordan et al. 2024):
X_0 = G / ||G||_F # 归一化使谱半径 ≤ 1
X_{k+1} = a*X_k + b*(X_k*X_k^T)*X_k + c*(X_k*X_k^T)^2*X_k
# 其中 a=3.4445, b=-4.7750, c=2.0315
直觉解释: 不需要昂贵的 SVD 分解,仅用矩阵乘法就能在 5 步内逼近正交矩阵。GPU 上矩阵乘法高度优化,因此比 SVD 快得多。
关键性质:
- 收敛速度: 5 步后 ||O^T O - I||_F < 1e-6
- 仅需矩阵乘法: 不需要 SVD/eigendecomposition,适合 GPU
- 归一化输入: 谱半径 > 1 时迭代发散,因此必须先除以 Frobenius 范数
- 高矩阵优化: 当 m > n 时先转置,利用 (n×n) 的 Gram 矩阵而非 (m×m)
Per-Head 正交化
公式: 对注意力投影层的 2D 权重 W ∈ R^{out_dim × in_dim},按 head 维度切片:
# W 拆分为 num_heads 个块: shape [num_heads, head_dim, in_dim]
blocks = W.view(num_heads, head_dim, in_dim)
# 每个头独立正交化 (批处理 NS)
ortho_blocks = newton_schulz(blocks, steps=5)
# 合并回原始形状
W_ortho = ortho_blocks.view(out_dim, in_dim)
直觉解释: 全矩阵正交化会将所有头的更新统一到一个全局尺度,导致某些头的更新被"压制"。Per-Head 模式给每个头独立的归一化,使头间更新尺度一致。
关键性质:
- 仅用于 q_proj / k_proj / v_proj (注意力投影层)
- 每个头的奇异值谱独立收敛到 1
- 头间条件数差异更小(全矩阵模式下差异可达 2-3 倍)
RMS 缩放
公式: 正交化后矩阵的 RMS 取决于形状:
# 对于半正交矩阵 O ∈ R^{m×n} (m ≥ n):
# ||O||_F = sqrt(n)
# RMS = sqrt(n / (m*n)) = 1/sqrt(m)
# Shape 模式: 使 RMS ≈ 1
scale = sqrt(max(m, n))
O_scaled = O * scale
# Reference-RMS 模式: 匹配参考张量的 RMS
target_rms = sqrt(mean(ref^2))
current_rms = sqrt(mean(O^2))
O_scaled = O * (target_rms / current_rms)
直觉解释: 不同形状的矩阵正交化后 RMS 不同(瘦高阵 RMS 更小),需要缩放使更新幅度一致。
权重分组策略
# 分组规则 (build_muon_param_groups):
if tensor.ndim == 2 and "embed" not in name and "lm_head" not in name:
if name contains "q_proj" or "k_proj" or "v_proj":
group = "per_head_muon" # q/k/v_proj → Per-Head Muon
else:
group = "muon" # 其他 2D 矩阵 → 普通 Muon
else:
group = "adamw" # embedding/bias/norm/router → AdamW
学习率调度
# Cosine with Warmup
if step < warmup_steps:
lr = peak_lr * (step + 1) / warmup_steps # 线性 warmup
else:
progress = (step - warmup_steps) / (total_steps - warmup_steps)
lr = min_lr + (peak_lr - min_lr) * 0.5 * (1 + cos(pi * progress)) # 余弦衰减
# WSD (Warmup-Stable-Decay)
if step < warmup_steps:
lr = peak_lr * (step + 1) / warmup_steps # 线性 warmup
elif step < decay_start:
lr = peak_lr # 稳定阶段
else:
progress = (step - decay_start) / (total_steps - decay_start)
lr = min_lr + (peak_lr - min_lr) * (1 - progress) # 线性衰减
# 双 LR: Muon 通常比 AdamW 大 5-10 倍
lr_muon(t) = peak_lr_muon * schedule(t) # Muon 独立 LR
lr_adamw(t) = peak_lr_adamw * schedule(t) # AdamW 独立 LR
Hybrid 事务性更新
# 事务性保证: 任一参数出现 NaN 梯度 → 整步跳过
def step(grads):
nonfinite = sum(not isfinite(g).all() for g in grads)
if nonfinite > 0:
return OptimizerStepReport(executed=False, ...) # 跳过整步
muon.step() # 正常更新
adamw.step()
return OptimizerStepReport(executed=True, ...)
P2P 分片与所有权
# shard_ranges: 连续分片 (向上取整)
def shard_ranges(numel, world):
per = ceil(numel / world)
return [(i*per, min((i+1)*per, numel)) for i in range(world)]
# OwnershipMap: round-robin 分配
# 参数 i 归 rank (i % world) 所有
owners = [i % world for i in range(n_params)]
# 内存对比:
# All-Gather: 每个 rank 需要 O(N) 额外内存 (N = 总参数数)
# P2P: 每个 rank 仅需 O(N/world) 额外内存
Weight Decay 与 Weight Clip
# Weight Decay (解耦正则, 与 AdamW 相同)
W = W * (1 - lr * weight_decay)
# Weight Clip (硬约束, Kimi K2)
rms = sqrt(mean(W^2))
if rms > clip_threshold:
W = W * (clip_threshold / rms)
# 两者结合: WD 做轻量正则, clip 作为安全网防止异常更新
Nesterov 动量
# 标准动量
buf = momentum * buf + grad
update = buf # 只看历史
# Nesterov 动量
buf = momentum * buf + grad
update = grad + momentum * buf # 利用未来位置梯度
# 直觉: 先"预看一步"再走, 通常收敛更快
2.3 关键洞察
关键洞察: Newton-Schulz 正交化的核心价值不是"让更新变成正交矩阵",而是让所有奇异方向等幅更新。普通 SGD/Adam 的更新在不同奇异方向上幅度不同(条件数大的方向更新被"压制"),Muon 通过正交化消除这种不均衡,使所有方向的学习速率一致。
”
关键洞察: Per-Head 正交化解决了全矩阵正交化的"头间不均衡"问题——全矩阵模式下,某些 head 的条件数可能比其他 head 大 2-3 倍,导致这些 head 的更新被系统性压制。Per-Head 模式让每个头独立归一化,消除了这种不公平。
”
关键洞察: P2P Muon 的内存节省来自一个简单事实——每个 rank 只需要组装自己"拥有"的参数(~N/world),而不是 all-gather 整个模型(~N)。round-robin 分配保证负载均衡(差异 ≤ 1),同时是确定性的(无需通信协商)。
”
0x03 每个 Tab 的详细说明
| 文件 | 用途 |
|---|---|
gradio_optim_demo.py | Gradio 启动入口 |
_optim_demo_ui.py | 15 个 Tab 的 UI 组装、参数绑定、事件回调 |
plot_newton_schulz.py | Tab 1-3:NS 收敛曲线 / 基础属性 / RMS 缩放 |
plot_muon.py | Tab 4-7:Per-Head 正交化 / 更新分解 / WD&Clip / Nesterov |
plot_param_groups.py | Tab 8:参数分组可视化 |
plot_lr_scheduler.py | Tab 9-10:学习率调度 / 双 LR |
plot_hybrid.py | Tab 11-12:NaN 跳过 / state_dict 往返 |
plot_muon_p2p.py | Tab 13-14:分片与所有权 / P2P 内存对比 |
plot_muon_vs_adamw.py | Tab 15:Muon vs AdamW 端到端训练 |
plot_utils.py | 公共工具:CJK 字体设置 / 文本拼接 / 图片保存 |
demo_muon_e2e.py | 端到端训练脚本,import plot_muon_vs_adamw |
Tab 1: NS 收敛曲线
目的
验证 Newton-Schulz 迭代的收敛性:随着迭代步数增加,奇异值谱向1靠近,条件数下降,正交误差减小。对应测试 test_singular_values_near_one、test_condition_number_near_one、test_steps_parameter。
背景概念
条件数: k = σ_max / σ_min。对正交矩阵,所有奇异值 = 1,因此 k = 1。条件数越大,矩阵越"扁",更新方向越不均衡。
正交误差: ||O^T O - I||_F。对精确正交矩阵,O^T O = I,误差 = 0。Newton-Schulz 是近似算法,误差随迭代步数减小但不会精确到0。
UI 组件与参数影响
| 参数 | 范围 | 默认 | 调节效果 |
|---|---|---|---|
| 随机种子 | 0-999 | 42 | 改变种子 → 不同随机矩阵,验证收敛的普遍性 |
| 矩阵行数 m | 8-64 | 32 | 增大 m → 矩阵更高,条件数可能更大,验证瘦高矩阵的收敛 |
| 矩阵列数 n | 4-32 | 16 | 增大 n → 矩阵更方,奇异值更多,验证方阵收敛 |
| 最大迭代步数 | 1-12 | 8 | 增大步数 → 看到更完整的收敛曲线 |
输出图解读
ns_convergence
布局: 2×2 四联图
左上 (a): 奇异值谱随迭代收敛
- 折线图,X 轴 = 奇异值索引(降序),Y 轴 = 奇异值
- 每条线对应一个迭代步数(step=0, 1, 2, 3, 5, max_steps),颜色从暗到亮
- 红色虚线 = 理想值 1
- 该看什么: step=0 时奇异值分散(从 0.2 到 0.4),随迭代步数增加逐渐向1靠近
- 实际情况: 8步迭代后奇异值在 [0.7, 1.15] 范围内,未完全收敛到1是正常的
- 异常指示: 如果曲线完全不变化或发散,说明迭代有问题
右上 (b): 条件数收敛 (log 纵轴)
- 折线图,X 轴 = 迭代步数,Y 轴 = 条件数 k(log scale)
- 绿色虚线 = 理想值 1
- 该看什么: 曲线从高处快速下降,然后趋于平稳
- 实际情况: 5步后 k ≈ 1.6-1.7,稳定在此水平不再下降,这是Newton-Schulz的渐近收敛特性
- 异常指示: 如果曲线持续上升或震荡,说明迭代不稳定
左下 (c): 正交误差 ||O^T O - I||_F
- 折线图,X 轴 = 迭代步数,Y 轴 = Frobenius 范数
- 该看什么: 曲线从高处下降,然后趋于平稳
- 实际情况: 5步后误差 ≈ 1.0-1.5,稳定在此水平,不会精确到0
- 异常指示: 如果误差持续上升,说明正交化失败
右下 (d): Frobenius 范数变化
- 柱状图,灰色柱 = 输入 G 的范数,蓝色渐变柱 = 各步输出的范数
- 该看什么: 输入范数(灰色)较大,经过NS迭代后范数稳定在某个值
- 实际情况: 输入范数 ≈22,迭代后稳定在 ≈3.5-4.0
- 异常指示: 如果范数爆炸或变为0,说明归一化有问题
调节建议
- 想看更多步的收敛 → 调最大迭代步数到 12
- 想看更极端的矩阵 → 调 m=64, n=4 (16:1 纵横比)
- 想验证种子无关性 → 调随机种子到不同值,曲线形状应一致
为什么重要
这是 Muon 优化器正确性的主锚点——Newton-Schulz 在5步内将条件数从 >5 降到 <2,虽然未精确到1,但已足够让Muon的正交化更新在实践中有效。Jordan et al.(2024) 的实验验证了这种近似正交化在LLM训练中的有效性。
Tab 2: NS 基础属性
目的
验证 Newton-Schulz 的 6 项基础属性:shape 一致、dtype 保留、元素有限、缩放不变、高/宽矩阵支持、批处理独立。对应测试 test_output_shape_matches_input 等 6 个测试。
UI 组件与参数影响
| 参数 | 范围 | 默认 | 调节效果 |
|---|---|---|---|
| 随机种子 | 0-999 | 42 | 改变种子 → 不同随机矩阵,验证属性的普遍性 |
输出图解读
ns_properties
布局: 2×3 六联图
左上 (a): 形状一致
- 柱状图,两根柱子:输入 G 和输出 O 的元素数
- 该看什么: 两根柱子高度完全相同
- 理想情况: 输出 shape = 输入 shape
中上 (b): dtype 保留
- 柱状图,三根柱子:float32、float16、bfloat16 的匹配结果(1=OK)
- 该看什么: 所有柱子高度 = 1,标注 "OK"
- 理想情况: 三种精度都保留
右上 (c): 元素有限性
- 饼图,绿色 = 有限值,红色 = 非有限(NaN/Inf)
- 该看什么: 绿色占 100%
- 理想情况: 所有元素有限
左下 (d): 缩放不变性
- 折线图,X 轴 = 缩放因子 s(0.01 到 100),Y 轴 = 余弦相似度
- 红色虚线 = 理想值 1
- 该看什么: 所有点在 0.999 以上
- 理想情况: cos_sim ≈ 1,缩放不改变输出方向
中下 (e): 高/宽矩阵
- 折线图,两条线:高矩阵 (16×4) 和宽矩阵 (4×16) 的奇异值谱
- 红色虚线 = 理想值 1
- 该看什么: 两条线都收敛到 1 附近
- 理想情况: 两种形状都能正确正交化
右下 (f): 批处理
- 柱状图,4 根柱子:batch 中 4 个样本的条件数
- 红色虚线 = 理想值 1
- 该看什么: 所有柱子高度接近 1
- 理想情况: 每个样本独立正交化,条件数都 ≈ 1
特殊说明
中下 (e): 高/宽矩阵:高/宽矩阵奇异值谱为何不同?
高矩阵(16×4)和宽矩阵(4×16)是独立随机生成的两个矩阵,初始奇异值谱不同。NS 迭代对每个奇异值施加同一个多项式映射 f(σ),大奇异值收敛快、小奇异值收敛慢,因此 5 步后两条曲线呈现不同的残余形态,但都整体向 1 收敛,条件数都从 ~2.5 降到 ~1.6。该子图验证的是 NS 对 tall/wide 两种形状都适用,而不是两者输出应相同。
- 数学上
G和G.T的非零奇异值完全相同,但随机生成的 16×4 与 4×16 是两个独立矩阵,不是互为转置,所以谱本来就不同。 - NS 是多项式迭代(
X ← aX + b(XXᵀ)X + c(XXᵀ)²X),它对每个奇异值 σ 的作用等价于标量函数f(σ)。f对大 σ 收敛快、对小 σ 收敛慢(小 σ 会被XXᵀ项放大得慢)。 - 图里 16×4(橙)的输入条件数比 4×16(绿)略小(2.51 vs 2.48 但小奇异值分布不同),所以 5 步后残余不同:橙的 σ₃/σ₄ 已掉到 0.71/0.69,绿的 σ₄ 还是 0.68 但 σ₂σ₃ 更接近 1。两条谱都向 1 收敛,但收敛速率依赖于初始谱形状,所以呈现"中间下凹、两端贴 1"的不同形状。
- 这个子图的目的是验证"两种形状都能跑、且都在向 1 收敛"。
为什么重要
这 6 项属性是 Newton-Schulz 的基本契约——任何一项不满足都会导致 Muon 训练出错。此 Tab 是回归测试的视觉化版本。
Tab 3: RMS 缩放
目的
验证两种 RMS 缩放模式:shape 模式使不同纵横比矩阵的 RMS 统一到 ~1,reference_rms 模式匹配参考张量的 RMS。对应测试 test_shape_mode_makes_rms_near_one、test_reference_rms_mode。
背景概念
正交化后的矩阵 RMS 取决于形状:方阵 RMS ≈ 1/sqrt(m),瘦高阵 RMS ≈ 1/sqrt(m)(更小)。不同纵横比的矩阵需要不同的缩放因子来使 RMS 统一。
shape 模式: 按 sqrt(max(m,n)) 缩放,使不同纵横比矩阵的 RMS 统一到 ~1。
reference_rms 模式: 按参考张量的 RMS 缩放,使输出与参考张量能量匹配。
K3 实现的特殊性: K3 将 norm 分离到 attention 层单独做,Muon.update_params 跳过了 norm 步骤。因此 Muon 期望输入是已归一化的梯度。
两种 RMS 缩放模式详解
前置:为什么正交化后必须缩放
Newton-Schulz 把任意矩阵变成半正交矩阵 O(满足 OᵀO ≈ I)。但半正交矩阵的 RMS 不是 1,而是被形状决定:
对 O ∈ ℝ^{m×n}(设 m ≥ n,n 个奇异值都 ≈ 1):
‖O‖_F² = Σσᵢ² ≈ nRMS(O) = ‖O‖_F / √(m·n) ≈ √n / √(m·n) = 1/√m
也就是说,矩阵越高(m 越大),正交化后的 RMS 越小。如果直接拿这个矩阵当参数更新,瘦高矩阵(如 FFN 的 down_proj)的更新幅度会比扁宽矩阵小几个数量级——同一个 lr 在不同形状的层上完全不等价。所以必须乘一个缩放因子。
代码:newton_schulz.py:74-120 (match_update_rms)。
shape 模式:绝对基准,所有矩阵对齐到 RMS=1
公式:scale = √(max(m, n)),返回 O · √max(m,n)
效果:对半正交矩阵,RMS(O·√max) ≈ (1/√max)·√max = 1。
意义:给定一个与形状无关的绝对基准。不管这一层是 4096×1024 还是 1024×4096,缩放后的更新矩阵 RMS 都是 1。这样:
- 所有 2D 参数共享同一个 lr 是"公平"的——lr 直接控制更新的绝对幅度,不再被形状稀释。
- 这是 Moonlight / K3 论文里的默认选择,因为它把"lr 该多大"从"这一层的形状"中解耦出来。
- 代码:
newton_schulz.py:103-108,一行max(shape)**0.5。
适用场景:训练循环里的标准选择,不需要外部参考。
reference_rms 模式:相对基准,匹配一个外部张量的 RMS
公式:scale = RMS(reference) / RMS(O),返回 O · scale
效果:缩放后的更新矩阵 RMS 恰好等于 reference 的 RMS。
意义:把更新的尺度锚定到一个外部信号上,而不是固定到 1。常见用法:
- 匹配梯度 RMS:
reference = 原始梯度。这样 Muon 更新和"如果当时用 SGD 会走多远"在同一个量级,便于和 SGD/AdamW 的 lr 对齐,调参时可以参考熟悉的 SGD lr。 - 匹配上一层的更新 RMS:让相邻层的更新幅度保持一致(避免某一层更新过强)。
- 暖启动:训练初期 reference 设为较小的张量,随训练推进放大 reference,相当于一个"幅度 warmup"。
- 代码:
newton_schulz.py:110-120,先算target = RMS(reference),再算current = RMS(O),乘target / current。
适用场景:需要 Muon 更新与某个外部尺度对齐的场景,比如把 Muon 嵌入到现有的、已经为 AdamW 调好 lr 的训练管线里。
UI 组件与参数影响
| 参数 | 范围 | 默认 | 调节效果 |
|---|---|---|---|
| 随机种子 | 0-999 | 42 | 改变种子 → 不同随机矩阵,验证 RMS 缩放的普遍性 |
| 矩阵行数 m | 8-64 | 32 | 改变 m → 影响 sqrt(max(m,n)) 因子 |
| 矩阵列数 n | 4-32 | 16 | 改变 n → 影响 sqrt(max(m,n)) 因子 |
| 缩放模式 | shape/reference_rms | shape | 切换模式 → 验证两种模式的效果差异 |
输出图解读
rms_scaling
布局: 2×1 双联图
左图: shape 模式 RMS 验证 (柱状图)
- 灰色柱: 正交化后未缩放的 RMS(随纵横比 m/n 变化, 0.2-0.35 之间)
- 绿色柱: shape 模式缩放后的 RMS(统一到 ~0.9-1.0 附近)
- 红色虚线: 目标 RMS=1
- X 轴: 矩阵纵横比 (m/n, n=8 固定)
- 该看什么: 绿色柱应稳定在红色虚线附近, 灰色柱则随形状变化
- 物理意义: 正交化只改变方向不改变形状, RMS 由矩阵形状决定; shape 模式乘以
sqrt(max(m,n))把不同形状的 RMS 统一到 1
右图: reference_rms 模式 RMS 验证 (折线图)
- 红色虚线: 参考张量的 RMS(目标)
- 蓝色实线: 缩放后的实际 RMS
- 该看什么: 两条线应完全重合——实测 RMS 精确匹配参考 RMS
- 物理意义: reference_rms 模式让更新尺度相对于某个参考张量可控(比如"让这一层的更新和另一层一样大")
调节建议
- 想看纵横比的影响 → 调 m=64, n=8,看 RMS 统一效果
- 想验证两种模式差异 → 切换缩放模式,对比两条曲线
为什么重要
RMS 缩放是 Muon 优化器的核心数学基础——如果缩放错误,梯度更新的量级就会错误,导致训练不稳定。这个 Tab 验证了 Newton-Schulz 的实现是否正确处理了维度和能量缩放,以及 K3 的 norm 分离策略是否正确。
Tab 4: Per-Head 正交化
目的
对比 Per-Head 正交化与全矩阵正交化的效果:Per-Head 模式下每个头独立归一化,头间条件数更均衡。对应测试 test_per_head_matches_manual_split。
UI 组件与参数影响
| 参数 | 范围 | 默认 | 调节效果 |
|---|---|---|---|
| 随机种子 | 0-999 | 42 | 改变种子 → 不同随机矩阵 |
| out_dim | 8-128 | 32 | 增大 → 更大的投影矩阵,头间差异可能更明显 |
| in_dim | 4-64 | 16 | 增大 → 更多输入维度 |
| num_heads | 1-8 | 4 | 增大 → 更多头,每个头更小,Per-Head 优势更明显 |
输出图解读
muon_per_head
布局: 1×2 两联图
左图 (a): 全矩阵正交化
- 折线图,每条线 = 一个 head 的奇异值谱
- 红色虚线 = 理想值 1
- 该看什么: 不同 head 的曲线整体位置接近(都在 0.3-0.95 之间), 但每条线内部的斜率大(从 ~0.9 降到 ~0.3)
- 关键指标: 各 head 的条件数(max/min 奇异值比)= 2.48-3.18, 差异大
- 物理意义: 全矩阵模式下, 头间奇异值互相影响, 某些 head 被"压制"(条件数 > 2)
右图 (b): Per-Head 正交化
- 折线图,同上
- 该看什么: 各 head 的曲线整体位置不同(head 0-3 的 max 分别是 1.13, 1.13, 1.11, 1.13), 但每条线内部的斜率小(线的尾部) (从 ~1.13 降到 ~0.68)
- 关键指标: 各 head 的条件数 = 1.58-1.66, 接近 1 且彼此接近
- 物理意义: Per-Head 模式下每个 head 独立归一化, 头间更新尺度更均衡; 不是"所有线重合", 而是"每条线内部更平"
常见误解: Per-Head 不是让"所有 head 的奇异值谱完全重合"——不同 head 的整体尺度仍不同(max 奇异值在 1.11-1.13 之间), 但每个 head 内部的条件数接近 1(max/min ≈ 1.6 vs 全矩阵的 ≈ 2.9)。
调节建议
- 想看头间差异最大化 → 调 num_heads=8, out_dim=64(每个头只有 8 维)
- 想看差异消失 → 调 num_heads=1(退化为全矩阵模式)
为什么重要
Per-Head 正交化是 K3 注意力层的关键优化——如果不做 Per-Head,某些注意力头的更新会被系统性压制,导致注意力模式学习不充分。
Tab 5: Muon 更新分解
目的
展示 Muon 更新的 6 步流程在实际训练中的行为:loss 下降、梯度/动量范数变化、权重范数衰减。对应测试 test_reduces_quadratic。
背景概念
Muon 的 6 步更新:动量累积 → Nesterov → 正交化 → RMS 缩放 → Weight Decay → 参数更新。此 Tab 让用户直观看到每步的效果。
UI 组件与参数影响
| 参数 | 范围 | 默认 | 调节效果 |
|---|---|---|---|
| 随机种子 | 0-999 | 42 | 改变种子 → 不同训练轨迹 |
输出图解读
muon_decompose
布局: 2×2 四联图
左上 (a): Loss 下降曲线
- 折线图,红色半透明 = 原始 loss,红色粗线 = smoothed loss
- 该看什么: loss 从 ~1.0 快速下降到 ~0.01
- 理想情况: 平滑下降,无震荡
右上 (b): 梯度范数 vs 动量缓冲范数
-
折线图,蓝色 = 梯度范数,紫色 = 动量缓冲范数(EMA, β=0.9)
-
该看什么:
- t=0-10(瞬态) :紫色从 0 快速上升,滞后于蓝色(EMA 累积期)
- t=10-20:紫色反超蓝色(EMA"记得"早期大梯度,蓝色已衰减)
- t=20+(稳态) :紫色缓慢衰减,确实比蓝色平滑(EMA 滤波生效)
-
关键洞察:EMA 的"平滑"是长期性质,短期会因滞后显得波动更大——紫色在 t=10-20 的峰值(1.7)是蓝色同期值(~0.3)的 5 倍,因为它平均了 t=0-10 的大梯度
-
物理意义:动量缓冲不是"梯度的平滑版本",而是"梯度的加权历史"——早期大梯度会持续影响后续多步更新
左下 (c): 权重范数变化
- 折线图,绿色 = 权重范数,红色虚线 = 初始权重范数
- 该看什么: 权重范数缓慢下降(weight_decay 在起作用)
- 理想情况: 范数从初始值平滑衰减
右下 (d): Muon 更新 6 步示意
- 柱状图,6 根柱子:动量累积、Nesterov、正交化、RMS缩放、Weight Decay、参数更新的相对幅度
- 该看什么: 正交化后幅度降低(正交矩阵范数 = sqrt(n)),RMS 缩放后恢复
- 理想情况: 各步幅度合理,无异常大/小值
为什么重要
这是 Muon 优化器的端到端验证——如果 loss 不下降,说明前面所有组件的组合有问题。
Tab 6: WD & Weight Clip
目的
对比两种正则化方式的效果:weight_decay(平滑衰减)vs weight_clip(硬约束)vs 两者结合。对应测试 test_weight_decay_reduces_norm、test_weight_clip_caps_rms。
背景概念
- Weight Decay: 每步乘 (1-lr*wd),等价于 L2 正则,平滑衰减权重
- Weight Clip: 当权重 RMS > 阈值时才裁剪,防止权重爆炸
- Kimi K2 使用两者结合:WD 做轻量正则,clip 作为安全网
UI 组件与参数影响
| 参数 | 范围 | 默认 | 调节效果 |
|---|---|---|---|
| 随机种子 | 0-999 | 42 | 改变种子 → 不同训练轨迹 |
输出图解读
muon_weight_decay_clip
布局: 1×2 两联图
左图 (a): 权重 RMS 变化
-
折线图,4 条线:无正则(灰)、weight_decay=0.1(蓝)、weight_clip=1.0(橙)、两者都有(绿)
-
红色虚线 = clip 阈值 RMS=1
-
该看什么: 无正则时 RMS 持续增长,WD 时缓慢下降,clip 时被限制在 1.0 以下
- 无正则(灰线)时权重 RMS 也在下降,是因为本 demo 的 loss 函数本身鼓励权重收缩,并非正则化的作用。关键差异在下降速率:无正则 100 步后 RMS 仍停留在 ~1.9,远高于 clip 阈值 1.0;weight_decay=0.1 平滑下降到 ~1.7;weight_clip=1.0 直接锁死在 1.0 以下;两者结合则既平滑又受硬约束。左图展示的是"不同正则手段对权重尺度的控制力",而不是"无正则权重会爆炸"。
-
理想情况: 绿线(两者都有)最稳定
右图 (b): Loss 曲线 (smoothed)
- 折线图,同上 4 条线
- 该看什么: 有正则的 loss 通常更低或相当
- 理想情况: 绿线 loss 最低或与蓝线持平
调节建议
- 想看无正则的后果 → 调种子到不同值,观察 RMS 是否爆炸
- 想看 clip 的效果 → 注意左图中橙线被限制在红色虚线以下
为什么重要
正则化是防止过拟合和训练不稳定的关键机制。此 Tab 展示了 Kimi K2 的正则化策略:WD + Clip 的组合比单独使用任何一个都更稳健。
Tab 7: Nesterov vs 动量
目的
对比 Nesterov 动量与标准动量的收敛速度。对应测试 test_nesterov_converges_faster。
背景概念
- 标准动量: update = buf(只看历史梯度)
- Nesterov 动量: update = grad + mu * buf(先"预看一步"再走)
- Nesterov 利用了未来位置的梯度信息,通常收敛更快
UI 组件与参数影响
| 参数 | 范围 | 默认 | 调节效果 |
|---|---|---|---|
| 随机种子 | 0-999 | 42 | 改变种子 → 不同训练轨迹 |
输出图解读
muon_nesterov_momentum
布局: 1×2 两联图
左图 (a): Loss 下降曲线对比
- 折线图,红色 = Nesterov,蓝色 = 标准动量(各有半透明原始 + 粗线 smoothed)
- 该看什么: 红线(Nesterov)下降更快
- 理想情况: Nesterov 在前 50 步就明显领先
右图 (b): Loss 比值
- 折线图,紫色线 = loss_nesterov / loss_momentum
- 黑色虚线 = 1.0(相等基准线)
- 该看什么: 线在 1.0 以下表示 Nesterov 更好
- 理想情况: 大部分时间线在 0.8-0.95 之间
调节建议
- 想看差异最大化 → 调种子到不同值,某些种子下差异更明显
- 想看差异消失 → 减少训练步数到 50 步(warmup 阶段差异小)
为什么重要
Nesterov 是 Muon 的标准配置,此 Tab 验证了 Nesterov 在实际训练中确实比标准动量更快收敛。
Tab 8: 参数分组
目的
可视化 build_muon_param_groups 的分组结果:哪些参数用 Muon,哪些用 AdamW,哪些用 Per-Head Muon。对应测试 test_param_groups_structure。
背景概念
K3 模型的参数分为三组:
- 普通 Muon: o_proj, gate_proj, up_proj, down_proj(2D 矩阵,非注意力投影)
- Per-Head Muon: q_proj, k_proj, v_proj(注意力投影层,需要按头独立正交化)
- AdamW: embedding, bias, LayerNorm, lm_head(1D 参数或特殊层)
UI 组件与参数影响
| 参数 | 范围 | 默认 | 调节效果 |
|---|---|---|---|
| 启用 Per-Head | checkbox | True | 取消勾选 → q/k/v_proj 降级为普通 Muon |
| d_model | 16-128 | 32 | 增大 → 更多参数,饼图比例变化 |
| nhead | 2-8 | 4 | 增大 → Per-Head 组参数比例增大 |
输出图解读
param_groups
布局: 1×2 两联图
左图 (a): 参数量分布 (饼图)
- 饼图,蓝色 = 普通 Muon,紫色 = Per-Head Muon,灰色 = AdamW
- 该看什么: 三种颜色的比例
- 理想情况: Muon 组占大部分(~70%),AdamW 组占小部分(~30%)
- 异常指示: 如果 AdamW 组过大,说明分组规则有误
右图 (b): 参数类型统计 (柱状图)
- 水平柱状图,5 种类型:2D 矩阵、Embedding、1D/LayerNorm、Bias、LM Head
- 该看什么: 2D 矩阵数量最多(Muon 候选)
- 理想情况: 2D 矩阵 > 其他类型总和
调节建议
- 想看 Per-Head 效果 → 确保勾选"启用 Per-Head",紫色部分出现
- 想看退化情况 → 取消勾选,紫色消失,蓝色增大
为什么重要
参数分组是 Muon 优化器的配置入口——分组错误会导致某些参数用错优化器,训练效果下降。此 Tab 让用户直观验证分组结果。
Tab 9: 学习率调度
目的
对比 Cosine 与 WSD 两种学习率调度策略的形状和变化率。对应测试 test_cosine_warmup_values、test_wsd_schedule_values。
背景概念
- Cosine: warmup → 余弦衰减到 min_lr,平滑过渡
- WSD: warmup → 稳定在 peak_lr → 线性衰减,适合需要长时间稳定学习率的场景(如 RLHF)
UI 组件与参数影响
| 参数 | 范围 | 默认 | 调节效果 |
|---|---|---|---|
| total_steps | 200-5000 | 1000 | 增大 → 曲线更长,warmup 阶段占比更小 |
| warmup_ratio | 0.01-0.2 | 0.05 | 增大 → warmup 阶段更长,曲线上升段更长 |
| min_lr_ratio | 0.01-0.5 | 0.1 | 增大 → 最小 LR 更高,衰减幅度更小 |
| WSD decay_ratio | 0.05-0.3 | 0.1 | 增大 → 衰减阶段更长,稳定阶段更短 |
输出图解读
lr_schedules
布局: 2×1 两联图
上图 (a): 学习率调度曲线
- 折线图,蓝色 = Cosine,红色 = WSD
- 绿色虚线 = warmup 结束点,灰色点线 = min_lr_ratio
- 该看什么: Cosine 平滑下降,WSD 中间有稳定平台
- 理想情况: 两条线在 warmup 阶段重合,之后分离。
下图 (b): 学习率变化率 (差分)
- 折线图,蓝色 = Cosine dLR,红色 = WSD dLR
- 黑色实线 = 0(无变化)
- 该看什么: Cosine 的变化率连续平滑,WSD 在稳定阶段变化率为 0
- 理想情况: WSD 的红线在中间段为 0
补充说明
学习率调度曲线的理想状态是:两条线在 warmup 阶段重合,之后分离。
重合的根本原因是两种调度都把 warmup 定义为同一个线性函数 step/warmup_steps,且 warmup 期间主衰减项都未生效(Cosine 的 cos 参数在 t≤warmup 时被钳位为 1,WSD 的平台段常数就是 1)。warmup 结束后两者对"主阶段该以何种速率衰减"给出了不同答案:Cosine 立即平滑衰减,WSD 认为主阶段应该保持峰值。
Cosine 和 WSD 两种调度都把 warmup 设计成同一段线性斜坡(step/warmup_steps,从 0 爬到 1.0)。所以:
- warmup 阶段(0~50 步) :两条曲线都是同一条线性函数,必然重合。
- warmup 之后:Cosine 立刻开始按
cos(πt/2T)衰减;WSD 则保持在 1.0 平台直到最后 10% 才线性衰减。所以从此处分离。
这一点的工程含义是:两种调度可以共享同一段 warmup 代码,只在主阶段策略上分歧。这也是为什么 K3 选 WSD —— 它把"快速升温防冷启动"和"长平台稳定训练"解耦了,warmup 逻辑可以复用。
调节建议
- 想看 WSD 的稳定平台 → 调 warmup_ratio=0.05, decay_ratio=0.1(平台更明显)
- 想看 Cosine 的平滑衰减 → 调 min_lr_ratio=0.01(衰减幅度更大)
为什么重要
学习率调度直接影响训练稳定性和最终性能。此 Tab 让用户直观理解两种策略的差异,为实际训练选择提供依据。
Tab 10: 双 LR 调度
目的
展示 Muon 和 AdamW 使用独立学习率的调度曲线。对应测试 test_cosine_warmup_lr_scheduler。
背景概念
Muon 正交化后的更新范数更小,因此需要更大的学习率(通常比 AdamW 大 5-10 倍)。CosineWarmupLR 支持为 Muon 和 AdamW 设置独立的峰值 LR 和最小 LR。
UI 组件与参数影响
| 参数 | 范围 | 默认 | 调节效果 |
|---|---|---|---|
| total_steps | 100-2000 | 500 | 增大 → 调度曲线更长 |
| warmup_steps | 5-100 | 50 | 增大 → warmup 阶段更长 |
| AdamW 峰值 LR | — | 3e-4 | 增大 → AdamW 学习率更高 |
| Muon 峰值 LR | — | 2e-3 | 增大 → Muon 学习率更高 |
输出图解读
dual_lr
布局: 1×2 两联图
左图 (a): 双 LR 调度
- 折线图,紫色 = Muon LR,绿色 = AdamW LR
- 红色虚线 = warmup 结束点
- 该看什么: 紫线始终在绿线上方(Muon LR 更大)
- 理想情况: 两条线形状相似但幅度不同
右图 (b): 学习率比值
- 折线图,橙色线 = Muon LR / AdamW LR
- 红色虚线 = 峰值比
- 该看什么: 比值在 warmup 阶段波动,之后稳定在峰值比附近
- 理想情况: 比值稳定在 ~6.7(2e-3 / 3e-4)
调节建议
- 想看更大 LR 差异 → 调 Muon 峰值 LR 到 5e-3(比值增大到 ~16.7)
- 想看比值稳定 → 增大 total_steps 到 2000
为什么重要
双 LR 是 Muon 优化器的关键配置——如果 Muon LR 太小,正交化的优势无法发挥;如果太大,训练不稳定。此 Tab 让用户理解 LR 比值的设计。
Tab 11: Hybrid NaN 跳过
目的
演示 HybridMuonAdamW 的事务性更新:在 step 10/20/30 注入 NaN 梯度,验证整步跳过。对应测试 test_nan_gradient_skips_step。
背景概念
在分布式训练中,梯度可能因通信错误、数值溢出等原因变成 NaN。如果只跳过有 NaN 的参数,其他参数的更新会与 NaN 参数的状态不一致,导致模型损坏。事务性更新保证:任一参数有 NaN 梯度 → 整步全部跳过。
UI 组件与参数影响
| 参数 | 范围 | 默认 | 调节效果 |
|---|---|---|---|
| 随机种子 | 0-999 | 42 | 改变种子 → 不同训练轨迹(NaN 步固定为 10/20/30) |
输出图解读
tab-11
布局: 2×2 四联图
左上 (a): Loss 曲线
- 折线图,红色线 = loss,红色虚线 = NaN 注入步(10/20/30)
- 该看什么: NaN 注入步处 loss 不下降(线是平的 / 因为跳过了更新)
- 理想情况: 虚线处 loss 曲线有"平台"
右上 (b): 权重范数变化
- 折线图,蓝色 = weight norm,红色虚线 = 初始权重范数
- 该看什么: NaN 注入步处范数不变(线是平的 / 跳过了更新)
- 理想情况: 虚线处范数曲线有"平台"
左下 (c): Bias 范数变化
- 折线图,绿色 = bias norm,红色虚线 = 初始 bias 范数
- 该看什么: 同上,NaN 注入步处范数不变(线是平的)
- 理想情况: 虚线处范数曲线有"平台"
右下 (d): 步骤执行状态
- 柱状图,绿色 = 执行,红色 = 跳过
- 该看什么: step 10/20/30 处为红色柱子(跳过),其他为绿色
- 理想情况: 精确 3 根红色柱子
为什么重要
事务性更新是分布式训练的安全网——如果 NaN 不能被正确处理,训练会静默产生错误结果,比直接崩溃更危险。
Tab 12: state_dict 往返
目的
验证 HybridMuonAdamW 的 state_dict 序列化/反序列化完整性:保存 → 加载 → 再训练,验证状态一致恢复。对应测试 test_state_dict_roundtrip。
背景概念
训练中断后的恢复(checkpoint)依赖 state_dict 的正确性。重要: HybridMuonAdamW 的 state_dict 只包含优化器状态(Muon 动量缓冲 + AdamW 一阶/二阶矩 + step_number),不包含模型权重。必须同时保存/加载模型的 state_dict。
设计思路
state_dict 必须同时保存三部分:(1) Muon 的 momentum_buffer,决定恢复后 Muon 更新的方向连续性;(2) AdamW 的 exp_avg/exp_avg_sq,决定自适应学习率的连续性;(3) step_number,决定 bias correction 和 warmup 进度的连续性。三者缺任何一项,恢复训练都会在最初几步出现"虚假的学习率/动量重置",loss 曲线出现跳变。左图(加载后立即比较)应全黑——这正是验证"加载完整恢复"的判据;右图(双方各再训 5 步)也应几乎全黑,差异仅来自浮点累加误差。
这是混合优化器的必然要求,原因在于三种状态的用途完全不同:
- Muon 状态:每个 2D 参数的
momentum_buffer(一阶动量)。没有它,恢复后前几十步的更新方向会失真。 - AdamW 状态:每个非 2D 参数的
exp_avg+exp_avg_sq(一阶 + 二阶动量)。这是 AdamW 自适应学习率的依据,丢失等于"忘记历史梯度的方差",导致学习率短暂失调。 step_number:Muon 用step判断是否在 warmup 内、AdamW 用它做 bias correction(m̂ = m/(1-β₁ᵗ))。恢复训练时如果不存 step,bias correction 会被重置,等效于学习率在恢复瞬间出现一个虚假的尖峰。
UI 组件与参数影响
| 参数 | 范围 | 默认 | 调节效果 |
|---|---|---|---|
| 无参数 | — | — | 点击按钮直接运行 |
输出图解读
hybrid_state_dict
布局: 1×2 两联图
左图 (a): 加载前权重差异
-
热力图,显示 |W1_final - W2_final|(5 步训练后的权重差异)
-
该看什么: 颜色极浅(差异接近 0)
-
实际情况: 热力图几乎全黑(max_diff ≈ 0),说明两个模型从相同起点训练 5 步后,权重几乎完全一致
- 图上 max_diff = 3.32e-02,全黑图说明 diff_before 也接近 0,但 colorbar 上界被 diff_after 的 max (0.033) 决定,所以 0 在全颜色标度下就是黑色 —— 这是正常的,左图全黑正是因为加载完全一致。
-
为什么: 两个模型都从相同初始权重出发,经过相同训练步数,结果应高度相似
右图 (b): 加载后再训练 5 步差异
- 热力图,显示 |W1_final2 - W2_final2|(从 checkpoint 加载后再训练 5 步的差异)
- 该看什么: 颜色有差异(> 0),说明从相同 checkpoint 出发的两条训练轨迹会自然分叉
- 实际情况: 有颜色差异(max_diff ≈ 3.3e-02),这是正常的随机性分叉
- 异常指示: 如果右图也全黑(差异 ≈ 0),说明 state_dict 没有完整恢复,两条轨迹被"锁定"了
调节建议
- 运行多次验证一致性 → 多次点击按钮,左图应始终全黑(差异 ≈ 0)
为什么重要
Checkpoint 恢复是大模型训练的基础设施——左图全黑说明 state_dict 保存/加载是正确的(从相同起点训练结果一致),右图有差异是正常的随机性分叉,不是 state_dict 的问题。注意: 必须同时保存模型和优化器的 state_dict。
Tab 13: P2P 分片与所有权
目的
可视化 P2P Muon 的两个核心机制:shard_ranges(连续分片)和 OwnershipMap(round-robin 所有权分配)。对应测试 test_shard_ranges_covers_all、test_ownership_round_robin。
背景概念
- shard_ranges: 将连续内存切成 world 段近似相等的区间,每个 rank 持有一段连续分片
- OwnershipMap: 每个参数归 rank (i % world) 所有,负责其正交化
- 连续分片便于 coalesced memory access,round-robin 保证负载均衡
设计思路
shard_ranges 与 OwnershipMap 解决两个不同层面的问题:前者在元素层把一个张量切成 world 段连续 view,目的是让 reduce-scatter 走 coalesced 内存访问;后者在参数层用 round-robin 决定"谁负责组装和正交化参数 i",目的是确定性和简单性(无需跨 rank 协商)。连续性来自 per = ⌈numel/world⌉ 的向上取整分块;round-robin 的均匀性依赖"参数数量 ≫ world"的假设,保证各 rank 拥有参数数之差 ≤ 1。
这两个机制解决的是两个不同层面的问题:
-
shard_ranges(连续分片)解决"物理上怎么切一个张量" :- 连续性保证每个 rank 的分片是
tensor[lo:hi]的单一 view,不是 strided gather。GPU 上对 view 做 reduce-scatter 和优化器 step 都是 coalesced access;若用交错分片,每次访问都是 gather/scatter,慢一个数量级。 - 向上取整分块保证
per * world ≥ numel,末段短一些但总和恰好等于 numel,与 ZeRO-1/2 的reduce_scatter_grads分块宽度对齐。 - 代码:
muon_p2p.py:84-85,per = -(-numel // world)。
- 连续性保证每个 rank 的分片是
-
OwnershipMap.round_robin解决"逻辑上谁负责哪个参数" :- 它分配的是参数级别的所有权("参数 i 归 rank i%world"),不是元素级别。
- 为什么 round-robin 而不是"按参数大小排序后贪心装箱"?因为:(a) 确定性——所有 rank 用同一条规则,无需通信协商;(b) 静态——参数顺序不变则分配不变,便于缓存;(c) 简单——一行代码。当参数数量远大于 world 时,round-robin 自然均匀(负载差 ≤ 1)。
- 代码:
muon_p2p.py:132-136。
UI 组件与参数影响
| 参数 | 范围 | 默认 | 调节效果 |
|---|---|---|---|
| world size | 2-16 | 4 | 增大 → 更多 rank,分片更细,每 rank 持有更少 |
| 元素数 (shard_ranges) | 20-500 | 100 | 增大 → 总元素更多,分片更大 |
| 参数数 (OwnershipMap) | 4-24 | 12 | 增大 → 更多参数,round-robin 分布更均匀 |
输出图解读
p2p_shard_ranges
p2p_ownership
布局: 2×1 两联图
上图 (a): shard_ranges 分片分布
- 水平柱状图,每根柱子 = 一个 rank 的分片,颜色不同
- 柱子上的数字 = 该 rank 持有的元素数
- 该看什么: 各柱子长度接近(负载均衡),末段可能略短
- 理想情况: 所有柱子长度差 ≤ 1
- 异常指示: 如果某根柱子明显短,说明向上取整逻辑有误
下图 (b): Round-robin 所有权映射
- 柱状图,每根柱子 = 一个参数,颜色 = 拥有它的 rank
- 该看什么: 颜色按 rank 循环(P0, P1, P2, P3, P0, P1, ...)
- 理想情况: 颜色均匀分布,每种颜色出现次数差 ≤ 1
- 异常指示: 如果某种颜色过多,说明 round-robin 逻辑有误
调节建议
- 想看负载均衡极限 → 调参数数=13, world=4(13 % 4 = 1,某个 rank 多 1 个)
- 想看分片连续性 → 调元素数=100, world=4(每 rank 25 个元素)
为什么重要
P2P 分片是 K3 分布式训练的内存优化核心——验证分片和所有权的正确性是确保多 rank 训练一致性的基础。
Tab 14: P2P 内存对比
目的
理论计算 P2P 方案 vs All-Gather 方案的内存开销对比。对应测试 test_peak_buffer_elements。
背景概念
- All-Gather: 每个 rank 需要持有所有 N 个参数的完整矩阵 → O(N) 内存
- P2P: 每个 rank 只组装自己拥有的 ~N/world 个参数 → O(N/world) 内存
- 内存节省倍数 ≈ world_size
UI 组件与参数影响
| 参数 | 范围 | 默认 | 调节效果 |
|---|---|---|---|
| 参数数量 | 4-32 | 10 | 增大 → 总参数更多,内存对比更明显 |
| world size 最小值 | 1-8 | 1 | 调整 → 改变 X 轴范围 |
| world size 最大值 | 4-32 | 16 | 增大 → 看到更大 world 下的节省 |
| 参数行数 m | 16-256 | 128 | 增大 → 每个参数更大,内存对比更明显 |
| 参数列数 n | 8-128 | 64 | 增大 → 每个参数更大 |
输出图解读
tab-14
布局: 1×2 两联图
左图 (a): 峰值内存对比
- 折线图,红色方块 = All-Gather,绿色圆点 = P2P
- 该看什么: 红线始终水平(All-Gather 与 world 无关),绿线随 world 增大而下降
- 理想情况: 绿线在 world=16 时约为红线的 1/16
右图 (b): 内存节省倍数
- 折线图,紫色菱形 = All-Gather / P2P 比值
- 红色虚线 = 1.0(无节省),灰色虚线 = 理想线性(倍数 = world)
- 该看什么: 比值随 world 增大而上升,总体逼近理想线性
- 理想情况: world=16 时比值 ≈ 16
- 注意: 由于 round-robin 取整,曲线呈阶梯状;当 world 恰好整除 n_params 时会出现跳升
特殊说明
为什么 P2P 曲线在 world > n_params 时封顶。
内存节省倍数 = n_params / ⌈n_params/world⌉。当 world ≤ n_params 时近似等于 world(理想线性区);当 world > n_params 时封顶为 n_params(本图 = 10),因为每 rank 最少拥有 1 个参数,多余的 rank 完全空转。这就是右图紫色曲线在 world=10 处出现拐点的原因——world size 不应超过参数数量,否则新增 rank 不再带来任何内存节省。
具体而言,左图 P2P(绿)在 world ≈ 5 后曲线基本平坦,右图紫色节省倍数也在 world = 10 处封顶为 10。原因:
-
All-Gather 内存 =
n_params × per_param(每 rank 持有全量),与 world 无关,是水平线。 -
P2P 内存 = ⌈n_params/world⌉ × per_param(每 rank 只组装自己拥有的)。
- 当
world ≤ n_params:每 rank 拥有⌈n_params/world⌉ ≥ 1个参数,内存随 world 增大而反比下降 → 节省倍数 ≈ world(紫色虚线)。 - 当
world > n_params:⌈n_params/world⌉ = 1,每 rank 最多只拥有 1 个参数,内存到底,节省倍数封顶为n_params(图中 = 10)。
- 当
-
图中
n_params=10,所以紫色节省倍数在world=10处封顶为 10,之后保持不变。多出来的 rank 是空转的,纯属浪费。
调节建议
- 想看最大节省 → 调 world 最大值到 32, 参数数量到 32
- 想看参数规模影响 → 调 m=256, n=128(每个参数 32K 元素)
为什么重要
P2P 的内存节省是 K3 能在有限 GPU 内存上训练大模型的关键——此 Tab 让用户直观理解 "每个 rank 只组装自己拥有的参数" 带来的内存收益。
Tab 15: Muon vs AdamW 训练
目的
端到端对比 Muon 和 AdamW 在相同 Transformer 上的训练效果。对应测试 test_muon_beats_adamw_on_quadratic。
背景概念
Muon 对 2D 矩阵参数做正交化更新,理论上比 AdamW 更高效。参数分组: Embedding 和 output head 用 AdamW(不适合正交化),self_attn.in_proj_weight 用 Muon(标准),其他 2D 矩阵用 Muon(标准)。学习率: Muon 使用 K3 nano 配置(0.002),AdamW 使用 K3 nano 配置(0.0006)。
UI 组件与参数影响
| 参数 | 范围 | 默认 | 调节效果 |
|---|---|---|---|
| 训练步数 | 50-500 | 200 | 增大 → 训练更久,差异更明显 |
| 随机种子 | 0-999 | 42 | 改变种子 → 不同训练轨迹 |
| d_model | 32-128 | 64 | 增大 → 模型更大,Muon 优势更明显 |
输出图解读
muon_vs_adamw
布局: 1×2 两联图
左图 (a): 训练 Loss 对比
- 折线图,蓝色半透明 = Muon 原始,蓝色粗线 = Muon smoothed;红色同理
- 该看什么: 蓝线(Muon)是否低于红线(AdamW)
- 实际情况: 蓝线始终低于红线,Muon 在整个训练过程中表现更好
右图 (b): 最终 Loss 对比
- 柱状图,蓝色 = Muon,红色 = AdamW,柱子上标注具体数值
- 标题显示改善百分比
- 该看什么: 蓝色柱子是否低于红色柱子
- 实际情况: Muon 改善 0.3-1.3%(取决于模型大小和训练步数)
特殊说明
半透明线为原始 loss(每步一个样本,方差大),粗线为 10 步滑动平均(看趋势)。右图 0.7% 的微弱差距是真实结果:本 demo 用 2 层 Transformer、200 步训练、未调超参,在这么小的规模下 Muon 相对 AdamW 的优势确实不明显。Muon 的价值在于大模型长训练时的条件数鲁棒性——它让所有奇异方向等幅更新,避免 AdamW 在病态曲率上的之字形抖动;小模型本身条件数就不差,这一优势无法体现。本图刻意保留这个"微弱优势",作为对小规模下 Muon 真实收益的诚实标注。
蓝色半透明 vs 蓝色粗线的区别
这是可视化惯例,不是两条不同的训练曲线:
- 蓝色半透明(
alpha=0.3):原始 loss,每步一个点,方差大,能看到噪声量级和单步抖动。 - 蓝色粗线(
lw=2.5):滑动平均(_smooth(vals, w=10),窗口 10),把 10 步的噪声平均掉,用来看趋势。
代码在 plot_muon_vs_adamw.py:151-153:先 plot(losses, alpha=0.3) 再 plot(_smooth(losses), lw=2.5)。半透明那条就是粗线的"原料"。
为何蓝色柱只比红色矮一点
这是 demo 设计上的诚实呈现,不是 bug。 数字:Muon=5.5465 vs AdamW=5.5854,改善 0.7%。原因:
- 模型太小(2 层 Transformer, d_model=64),训练太短(200 步)。Muon 的优势在条件数差的大矩阵 + 长训练下才放大——它让所有奇异方向等幅更新,避免了 AdamW 在病态曲率上的"之字形"。小矩阵本身条件数就不差,AdamW 自适应学习率已经能补偿。
- 超参未调:
lr_muon=0.002 / lr_adamw=0.0006是默认值,没为这个 2 层小模型扫过。AdamW 在小模型上的最优 lr 区间被研究了多年,Muon 还没有。 - 任务太简单:随机 token 序列的 next-token prediction 没有真实结构,loss 平台来得很快,两者都迅速进入"微调噪声"阶段。
UI 的 Markdown 文字已经写了这个警告: "注意:小模型短训练下优势不明显,Muon 在大模型长训练中优势更显著。" 这是有意保留的诚实结果——如果为了"好看的图"强行展示 30% 改善,反而误导读者。
调节建议
- 想看 Muon 优势 → 调 d_model=128, 训练步数=500(更大模型更长训练)
- 想看差异消失 → 调 d_model=32, 训练步数=50(太小太短,优势不明显)
为什么重要
这是 Muon 优化器的最终验证——如果 Muon 在端到端训练中不优于 AdamW,前面所有组件的优化都没有意义。小模型下差异小是正常的,Muon 的优势在大模型(>1B 参数)长训练中才充分展现。
TransFormer-封面
0xFF 参考
本文使用 markdown.com.cn 排版