【轻量化复刻大模型 / KIMI K3】Optimizer 交互式演示

【轻量化复刻大模型 / KIMI K3】Optimizer 交互式演示

目录

0x01 实现概述

1.1 做了什么

本演示基于 src/models/llm/kimi_k3/optim/ 真实代码构建,所有图表均为 CPU 实时计算。核心产出物包括:

  • 1 个 Gradio 交互式 Demo :gradio_optim_demo.py 启动入口 + _optim_demo_ui.py UI 构建
  • 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 正交化,使更新在所有奇异方向上等幅:

python 复制代码
# 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):

python 复制代码
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 维度切片:

python 复制代码
# 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 取决于形状:

python 复制代码
# 对于半正交矩阵 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 更小),需要缩放使更新幅度一致。

权重分组策略

python 复制代码
# 分组规则 (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

学习率调度

python 复制代码
# 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 事务性更新

python 复制代码
# 事务性保证: 任一参数出现 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 分片与所有权

python 复制代码
# 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

python 复制代码
# 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 动量

python 复制代码
# 标准动量
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 增大步数 → 看到更完整的收敛曲线

输出图解读

布局: 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 改变种子 → 不同随机矩阵,验证属性的普遍性

输出图解读

布局: 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² = Σσᵢ² ≈ n
  • RMS(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。常见用法:

  1. 匹配梯度 RMS :reference = 原始梯度。这样 Muon 更新和"如果当时用 SGD 会走多远"在同一个量级,便于和 SGD/AdamW 的 lr 对齐,调参时可以参考熟悉的 SGD lr。
  2. 匹配上一层的更新 RMS:让相邻层的更新幅度保持一致(避免某一层更新过强)。
  3. 暖启动:训练初期 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 切换模式 → 验证两种模式的效果差异

输出图解读

布局: 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 优势更明显

输出图解读

布局: 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 改变种子 → 不同训练轨迹

输出图解读

布局: 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 改变种子 → 不同训练轨迹

输出图解读

布局: 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 改变种子 → 不同训练轨迹

输出图解读

布局: 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 组参数比例增大

输出图解读

布局: 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 增大 → 衰减阶段更长,稳定阶段更短

输出图解读

布局: 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 学习率更高

输出图解读

布局: 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)

输出图解读

布局: 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 组件与参数影响

参数 范围 默认 调节效果
无参数 --- --- 点击按钮直接运行

输出图解读

布局: 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)。
  • 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 分布更均匀

输出图解读

布局: 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 增大 → 每个参数更大

输出图解读

布局: 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 优势更明显

输出图解读

布局: 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%。原因:

  1. 模型太小 (2 层 Transformer, d_model=64),训练太短 (200 步)。Muon 的优势在条件数差的大矩阵 + 长训练下才放大------它让所有奇异方向等幅更新,避免了 AdamW 在病态曲率上的"之字形"。小矩阵本身条件数就不差,AdamW 自适应学习率已经能补偿。
  2. 超参未调 :lr_muon=0.002 / lr_adamw=0.0006 是默认值,没为这个 2 层小模型扫过。AdamW 在小模型上的最优 lr 区间被研究了多年,Muon 还没有。
  3. 任务太简单:随机 token 序列的 next-token prediction 没有真实结构,loss 平台来得很快,两者都迅速进入"微调噪声"阶段。

UI 的 Markdown 文字已经写了这个警告:"注意:小模型短训练下优势不明显,Muon 在大模型长训练中优势更显著。" 这是有意保留的诚实结果------如果为了"好看的图"强行展示 30% 改善,反而误导读者。

调节建议

  • 想看 Muon 优势 → 调 d_model=128, 训练步数=500(更大模型更长训练)
  • 想看差异消失 → 调 d_model=32, 训练步数=50(太小太短,优势不明显)

为什么重要

这是 Muon 优化器的最终验证------如果 Muon 在端到端训练中不优于 AdamW,前面所有组件的优化都没有意义。小模型下差异小是正常的,Muon 的优势在大模型(>1B 参数)长训练中才充分展现。



0xFF 参考