【轻量化复刻大模型 / KIMI K3】Muon 优化器及 KIMI K3 训练系统

【轻量化复刻大模型 / KIMI K3】Muon 优化器及 KIMI K3 训练系统

目录

  • [【轻量化复刻大模型 / KIMI K3】Muon 优化器及 KIMI K3 训练系统](#【轻量化复刻大模型 / KIMI K3】Muon 优化器及 KIMI K3 训练系统)
    • [0x00 论文溯源](#0x00 论文溯源)
      • [0.1 原始论文定位](#0.1 原始论文定位)
      • [0.2 论文相关图表](#0.2 论文相关图表)
      • [0.3 注意说明](#0.3 注意说明)
    • [0x01. 演进脉络与定位](#0x01. 演进脉络与定位)
      • [1.1 前身:从 SGD 到 AdamW 的"向量化"缺陷](#1.1 前身:从 SGD 到 AdamW 的"向量化"缺陷)
      • [1.2 同期竞品](#1.2 同期竞品)
      • [1.3 定位一句话](#1.3 定位一句话)
    • [0x02 原理讲解](#0x02 原理讲解)
      • [2.1 直觉类比视角](#2.1 直觉类比视角)
      • [2.2 准专业水平视角](#2.2 准专业水平视角)
      • [2.3 专家视角](#2.3 专家视角)
      • [2.4 代码](#2.4 代码)
    • [0x03 本项目实现](#0x03 本项目实现)
      • [3.1 与 kimi3-master 实现对比](#3.1 与 kimi3-master 实现对比)
      • [3.2 模块结构(文件级)](#3.2 模块结构(文件级))
      • [3.3 类继承与组合关系](#3.3 类继承与组合关系)
      • [3.4 与 kimi3-master 的文件映射](#3.4 与 kimi3-master 的文件映射)
      • [3.5 数据流图](#3.5 数据流图)
      • [3.6 依赖关系图](#3.6 依赖关系图)
      • [3.7 训练循环关键流程图](#3.7 训练循环关键流程图)
    • [0x04. 子知识点深度分析](#0x04. 子知识点深度分析)
      • [4.0 共享抽象与设计动机](#4.0 共享抽象与设计动机)
      • [4.1 Newton-Schulz 正交化](#4.1 Newton-Schulz 正交化)
        • [4.1.1 要解决的问题](#4.1.1 要解决的问题)
        • [4.1.2 三视角原理](#4.1.2 三视角原理)
        • [4.1.3 对比基线](#4.1.3 对比基线)
        • [4.1.4 工程实现](#4.1.4 工程实现)
        • [4.1.5 Per-Head Newton-Schulz](#4.1.5 Per-Head Newton-Schulz)
        • [4.1.6 代码位置汇总](#4.1.6 代码位置汇总)
      • [4.2 Muon 更新规则](#4.2 Muon 更新规则)
        • [4.2.1 要解决的问题](#4.2.1 要解决的问题)
        • [4.2.2 三视角原理](#4.2.2 三视角原理)
        • [4.2.3 对比基线](#4.2.3 对比基线)
        • [4.2.4 工程实现](#4.2.4 工程实现)
        • [4.2.5 Kimi K2 Weight Clipping](#4.2.5 Kimi K2 Weight Clipping)
      • [4.3 参数分组策略](#4.3 参数分组策略)
        • [4.3.1 要解决的问题](#4.3.1 要解决的问题)
        • [4.3.2 原理](#4.3.2 原理)
        • [4.3.3 工程实现](#4.3.3 工程实现)
      • [4.4 QK-Clip(Q/K 权重重缩放)](#4.4 QK-Clip(Q/K 权重重缩放))
        • [4.4.1 要解决的问题](#4.4.1 要解决的问题)
        • [4.4.2 原理](#4.4.2 原理)
        • [4.4.3 工程实现](#4.4.3 工程实现)
      • [4.5 混合优化器包装器(Hybrid Optimizer)](#4.5 混合优化器包装器(Hybrid Optimizer))
        • [4.5.1 要解决的问题](#4.5.1 要解决的问题)
        • [4.5.2 工程实现](#4.5.2 工程实现)
      • [4.7 学习率调度](#4.7 学习率调度)
        • [4.7.1 Cosine with Warmup](#4.7.1 Cosine with Warmup)
        • [4.7.2 Warmup-Stable-Decay(消融用)](#4.7.2 Warmup-Stable-Decay(消融用))
        • [4.7.3 双学习率调度](#4.7.3 双学习率调度)
        • [4.7.4 实现](#4.7.4 实现)
      • [4.8 训练循环(Train Loop)](#4.8 训练循环(Train Loop))
        • [4.8.1 单步训练](#4.8.1 单步训练)
        • [4.8.2 梯度累积 + 梯度裁剪](#4.8.2 梯度累积 + 梯度裁剪)
        • [4.8.3 Router Bias 延迟更新](#4.8.3 Router Bias 延迟更新)
        • [4.8.4 Context Curriculum](#4.8.4 Context Curriculum)
      • [4.9 配置系统](#4.9 配置系统)
        • [4.9.1 OptimConfig(kimi3-master)](#4.9.1 OptimConfig(kimi3-master))
        • [4.9.2 KimiOptimizerConfig(kimi-k3-pytorch-main)](#4.9.2 KimiOptimizerConfig(kimi-k3-pytorch-main))
        • [4.9.3 YAML 配置示例](#4.9.3 YAML 配置示例)
    • [附录A. 计算复杂度分析](#附录A. 计算复杂度分析)
      • [A.1 FLOPs 对比](#A.1 FLOPs 对比)
      • [A.2 内存对比](#A.2 内存对比)
      • [A.3 参数敏感性](#A.3 参数敏感性)
    • [附录B. 交付核对](#附录B. 交付核对)
    • [附录C. 端到端的优化器测试demo](#附录C. 端到端的优化器测试demo)
      • [C.1 loop.py 功能覆盖状态](#C.1 loop.py 功能覆盖状态)
      • [C.2 端到端 Demo 结构](#C.2 端到端 Demo 结构)
    • [0xFF 参考文献](#0xFF 参考文献)

0x00 论文溯源

分析范围: Muon 优化器原理、Per-Head 变体、Newton-Schulz 正交化、参数分组策略、QK-Clip、分布式 P2P Muon、学习率调度、训练循环、配置系统。

0.1 原始论文定位

论文 作者 机构 年份 出处 arXiv ID
Muon: An Optimizer for Hidden Layers in Neural Networks Keller Jordan, Yuchen Jin, Vlado Boza, You Jiacheng, Franz Cesista, Laker Newhouse, Jeremy Bernstein 独立研究者 2024 博客 + 社区 blog
Muon is Scalable for LLM Training Jingyuan Liu, Jianlin Su 等 (Moonshot AI + UCLA) Moonshot AI, UCLA 2025.02 技术报告 arXiv:2502.16982
Old Optimizer, New Norm: An Anthology Jeremy Bernstein, Laker Newhouse --- 2024 论文 arXiv:2409.20325

核心关系:

  • Jordan et al. (2024) 首次提出 Muon 优化器,基于 Newton-Schulz 迭代对梯度动量矩阵做正交化
  • Bernstein & Newhouse (2024) 从谱范数最陡下降角度给出 Muon 的理论基础
  • Liu et al. (2025, Moonshot AI) 解决了 Muon 的规模化问题------引入 weight decay、update RMS scaling、Per-Head 正交化,使 Muon 能够训练数十亿参数的 LLM。KIMI K3 的 Muon 实现直接基于此论文

0.2 论文相关图表

图/表 含义
Liu et al. Figure 1 Muon vs AdamW 的 SVD 熵对比------Muon 训练的权重矩阵保持更高的 SVD 熵,意味着更多方向的均匀学习
Liu et al. Figure 3 Update RMS 一致性分析------Per-Head 缩放使所有层的更新 RMS 保持一致
Liu et al. Table 1 超参数配置表------Muon 和 AdamW 的最佳超参数组合

Figure 1

Figure 3

Table 1

0.3 注意说明

  • 项目https://github.com/RossiLH/Model-Viz 和系列博客是我的一个尝试,也是我学习的过程。不确定是否满足读者的需求,我自己会反思改进,也希望大家提出宝贵意见。
  • 涉及 KIMI K3,DeepSeek V4,PI0.5,PI0.7 等模型。后续可能会跟踪新模型。
  • 全 CPU 复刻,不涉及 GPU,也不涉及大规模训练(这是另外一个庞杂深邃的领域)和硬件。
  • 模型的组件尽量是原始大模型的缩小版,如果组件没有开源版本,则用近似组件替代。
  • 会解释每个组件在解决一个什么问题、这个问题难在哪、为什么只能这么解、解法的原理是什么,以及组件之间如何咬合成一个整体。重点不是记名词,而是理解一条主线。
  • 每个主要组件都有可直接运行的 Gradio demo------无需 GPU。另有若干可视化脚本(plot_*.py),可生成静态图。
  • 所有文件行号基于本地源码快照;源码后续变化时,行号可能移动,但函数名和调用关系仍可作为定位入口。
  • 为了保证每个文章可以尽量独立成文,所以有些内容会在不同文章中都存在,可能在系列层面上存在冗余,还请大家理解。

0x01. 演进脉络与定位

1.1 前身:从 SGD 到 AdamW 的"向量化"缺陷

Muon 的诞生源于一个长期被忽视的问题:标准优化器将矩阵参数视为一维向量,完全忽略了其矩阵结构。

前代方案 核心机制 关键缺陷
SGD + Momentum 逐元素更新,动量缓冲 不区分参数矩阵的不同方向,学习速率受最大奇异方向主导
Adam/AdamW 逐元素自适应学习率(二阶矩归一化) 每个元素独立缩放,破坏矩阵的几何结构;计算开销大(维护两个动量缓冲)

核心痛点 :假设一个权重矩阵 \(W \in \mathbb{R}^{m \times n}\) 的梯度动量为 \(M\),其奇异值分布不均匀(某些方向梯度大,某些方向梯度小)。Adam 对每个元素独立缩放,等价于在不同方向使用不同的学习率,导致:

  • 梯度大的方向过度校正
  • 梯度小的方向学习不足
  • 整体训练动态不稳定

1.2 同期竞品

方案 核心机制 优势 劣势
Muon 矩阵正交化(Newton-Schulz) 保持矩阵几何结构,更新方向均匀 仅适用于2D矩阵,需要额外正交化计算
AdamW 逐元素自适应 + 解耦 weight decay 通用性强,工程成熟 忽略矩阵结构,SVD 熵低
Lion 符号动量(sign-based) 内存高效(仅一个动量缓冲) 粗糙的量化,丢失梯度幅值信息
LAMB 逐层信任比率缩放 大 batch 训练稳定 仍然逐元素操作,不利用矩阵结构
SOAP 分解 + Adam 风格 利用二阶信息 计算开销大,实现复杂
Muon + AdamW 混合 矩阵参数用 Muon,其余用 AdamW 兼顾两者优势 需要参数分组策略

1.3 定位一句话

不同于 AdamW 将权重矩阵视为独立元素集合逐元素归一化的做法,Muon 通过对梯度动量矩阵做整体正交化(Newton-Schulz 迭代),使更新方向在所有奇异方向上等幅,从而在保持矩阵几何结构的前提下实现更均匀、更高效的学习。


0x02 原理讲解

2.1 直觉类比视角

想象你站在一个山谷里(损失函数的低处),想走到更低的地方。Adam 相当于给你每只脚(每个参数)一双不同高度的鞋子------右脚的鞋子让你迈大步,左脚的鞋子让你迈小步。Muon 则不同:它给你一根"登山杖"(正交化的更新方向),让你在所有方向上以均匀的步伐前进,不会因为某个方向坡度陡就走得太猛,也不会因为某个方向坡度缓就走不动。

2.2 准专业水平视角

Muon 的核心更新公式:

\W_{t} = W_{t-1} - \\eta \\left( \\text{NS}(\\mu M_{t-1} + \\nabla L_{t-1}) \\cdot \\sqrt{\\max(1, m/n)} + \\lambda W_{t-1} \\right) \\

其中:

  • \(W \in \mathbb{R}^{m \times n}\): 权重矩阵
  • \(M_t\): 动量缓冲,\(M_t = \mu M_{t-1} + \nabla L_{t-1}\)
  • \(\text{NS}(\cdot)\): Newton-Schulz 正交化------寻找最近的半正交矩阵
  • \(\mu = 0.95\): 动量系数
  • \(\sqrt{\max(1, m/n)}\): RMS 缩放因子------补偿正交化后矩阵纵横比对更新幅度的影响
  • \(\lambda\): weight decay 系数

Newton-Schulz 迭代(5 步 quintic 近似):

c 复制代码
输入: 梯度动量 G ∈ R^{m×n}
步骤1: 归一化使谱半径 ≤ 1
步骤2: 重复5次:  X ← a·X + b·(X·X^T)·X + c·((X·X^T)²)·X
系数: a=3.4445, b=-4.7750, c=2.0315
输出: 近似半正交矩阵 O ≈ UV^T (G 的极分解正交因子)

与标准 AdamW 的公式级对比:

维度 AdamW Muon
更新方向 逐元素: \(\frac{m_t}{\sqrt{v_t} + \epsilon}\) 矩阵级: \(\text{NS}(M_t)\)
缩放依据 二阶矩(每个元素独立) 矩阵谱范数(全局统一)
动量缓冲 两个(一阶矩 + 二阶矩) 一个(仅一阶动量)
Weight Decay 解耦:\(W \leftarrow W(1 - \eta\lambda)\) 解耦:\(W \leftarrow W(1 - \eta\lambda)\)(同)
适用参数 所有参数 仅2D矩阵(其余用 AdamW)

2.3 专家视角

为什么正交化在理论上有效?

从谱范数约束的角度(Chen et al., 2025),Muon 等价于在谱范数约束下的最优化问题。正交化后的更新方向 \(O\) 满足 \(O^T O = I\),这意味着:

  1. 更新方向的等幅性 :对于任意单位向量 \(v\),\(\|Ov\| = \|v\|\),即所有方向的更新幅度相同
  2. SVD 熵最大化:正交化使权重矩阵的奇异值分布更均匀,保持更高的 SVD 熵,促进多方向学习
  3. 计算效率 :Newton-Schulz 迭代仅需矩阵乘法(无 SVD 分解),复杂度 \(O(mn \cdot \min(m,n))\),5 步内收敛

Liu et al. (2025) 的关键发现:

  • Weight Decay 的关键作用:原始 Muon(无 weight decay)在大规模训练中不稳定。加入 weight decay 后,权重的增长被约束,正交化更有效
  • Update RMS 一致性 :不同大小的矩阵经正交化后,更新 RMS 差异很大。通过 \(\sqrt{\max(m,n)}\) 缩放 + 0.2 固定系数,使所有层的更新 RMS 保持在 0.2~0.4(与 AdamW 对齐)
  • Per-Head 正交化:全矩阵正交化会将所有头的更新统一到一个尺度,导致头间不均衡。Per-Head 模式将矩阵按注意力头拆分,独立正交化

未解决的理论问题:

  • Newton-Schulz 迭代的收敛边界与模型规模的关系
  • Muon 在 SFT(监督微调)阶段的理论保证
  • 分布式设置下的最优通信-计算权衡

2.4 代码

python 复制代码
"""Muon 优化器核心实现。

Muon 通过对梯度动量矩阵做 Newton-Schulz 正交化来计算更新方向,
使更新在所有奇异方向上等幅,从而更高效地训练神经网络的2D权重矩阵。

参考:
    - Jordan et al., 2024, "Muon: An optimizer for hidden layers"
    - Liu et al., 2025, "Muon is Scalable for LLM Training" (arXiv:2502.16982)
"""
from optim.newton_schulz import match_update_rms, newton_schulz

# Per-Head 正交化的注意力投影层后缀
_PER_HEAD_SUFFIXES = ("q_proj", "k_proj", "v_proj", "q_up", "k_up", "v_up")

def per_head_orthogonalize(
    matrix: Tensor,
    num_heads: int,
    *,
    steps: int = 5,
    eps: float = 1e-7,
) -> Tensor:
    """Per-Head 正交化:将矩阵按注意力头拆分,独立正交化每个头。

    全矩阵正交化会将所有头的更新统一到一个尺度,导致头间不均衡。
    Per-Head 模式给每个头独立的归一化,使头间更新尺度一致。

    注意:RMS 缩放不在此函数内执行,而是在 Muon step 中用全矩阵维度统一处理(与 kimi3-master 一致)。

    Args:
        matrix: 权重矩阵,shape (out_dim, in_dim),其中 out_dim = num_heads * head_dim
        num_heads: 注意力头数
        steps: Newton-Schulz 迭代步数
        eps: 数值稳定性常数

    Returns:
        正交化后的矩阵,shape 与输入相同
    """
    out_dim, in_dim = matrix.shape
    assert out_dim % num_heads == 0, (
        f"out_dim {out_dim} 不能被 num_heads {num_heads} 整除"
    )
    head_dim = out_dim // num_heads

    # 拆分为 per-head 块: (num_heads, head_dim, in_dim)
    blocks = matrix.view(num_heads, head_dim, in_dim)

    # 对每个头独立正交化(批处理 NS)
    ortho_blocks = newton_schulz(blocks, steps=steps, eps=eps)

    # 合并回原始形状
    return ortho_blocks.view(out_dim, in_dim)

class Muon(torch.optim.Optimizer):
    """Muon 优化器:对2D矩阵参数使用 Newton-Schulz 正交化更新。

    Muon 的更新规则:
    1. 动量累积: buf = μ * buf + grad
    2. Nesterov 加速: update = grad + μ * buf
    3. 正交化: ortho = NS(update)
    4. RMS 缩放: scale = sqrt(max(1, out_dim / in_dim))
    5. Weight Decay: p = p * (1 - lr * λ)
    6. 参数更新: p = p - lr * scale * ortho

    参数分组:
    - use_muon=True: 2D 矩阵参数,使用 Muon 更新
    - use_muon=False: 1D 参数(bias/norm/embedding),使用 AdamW 更新
    - num_heads: 注意力投影层的头数,启用 Per-Head 正交化

    示例:
        >>> model = nn.Linear(64, 128)
        >>> groups = [{"params": model.parameters(), "use_muon": True}]
        >>> optimizer = Muon(groups, lr=1e-3)
    """

    def __init__(
        self,
        param_groups: list[dict[str, Any]],
        *,
        lr: float = 1e-3,
        adamw_lr: float = 3e-4,
        momentum: float = 0.95,
        nesterov: bool = True,
        ns_steps: int = 5,
        weight_decay: float = 0.1,
        betas: tuple[float, float] = (0.9, 0.95),
        eps: float = 1e-8,
        weight_clip: float = 0.0,
        update_rms_scaling: bool = True,
    ):
        """
        Args:
            param_groups: 参数组列表,每组包含 params, use_muon, num_heads
            lr: Muon 学习率
            adamw_lr: AdamW 学习率(用于 use_muon=False 的组)
            momentum: 动量系数
            nesterov: 是否使用 Nesterov 加速
            ns_steps: Newton-Schulz 迭代步数
            weight_decay: weight decay 系数
            betas: AdamW 的 beta 参数
            eps: AdamW 的 epsilon
            weight_clip: Kimi K2 权重裁剪阈值(0=禁用)
            update_rms_scaling: 是否启用 RMS 缩放
        """
        defaults = dict(
            lr=lr,
            adamw_lr=adamw_lr,
            momentum=momentum,
            nesterov=nesterov,
            ns_steps=ns_steps,
            weight_decay=weight_decay,
            betas=betas,
            eps=eps,
            weight_clip=weight_clip,
            update_rms_scaling=update_rms_scaling,
            use_muon=True,
            num_heads=None,
        )
        super().__init__(list(param_groups), defaults)

    @torch.no_grad()
    def step(self, closure=None):
        """执行一步优化。

        Returns:
            loss(如果提供了 closure),否则 None
        """
        loss = None
        if closure is not None:
            with torch.enable_grad():
                loss = closure()

        for group in self.param_groups:
            if group.get("use_muon", True):
                self._muon_step(group)
            else:
                self._adamw_step(group)

        return loss

    def _muon_step(self, group: dict[str, Any]) -> None:
        """Muon 更新:正交化动量 + RMS 缩放 + weight decay。"""
        lr = group["lr"]
        momentum = group["momentum"]
        heads = group.get("num_heads")
        ns_steps = group["ns_steps"]
        eps = group["eps"]
        weight_decay = group["weight_decay"]
        weight_clip = group["weight_clip"]
        rms_scaling = group["update_rms_scaling"]

        for p in group["params"]:
            if p.grad is None:
                continue

            grad = p.grad
            state = self.state[p]

            # 初始化动量缓冲
            if "momentum_buffer" not in state:
                state["momentum_buffer"] = torch.zeros_like(grad)

            buf = state["momentum_buffer"]

            # 步骤1: 动量累积
            buf.mul_(momentum).add_(grad)

            # 步骤2: Nesterov 加速
            update = grad.add(buf, alpha=momentum) if group["nesterov"] else buf

            # 步骤3: 正交化(与 kimi3-master 一致:per_head 不额外做 RMS 缩放)
            if heads is not None and heads > 1:
                ortho = per_head_orthogonalize(
                    update, heads, steps=ns_steps, eps=eps
                )
            else:
                ortho = newton_schulz(update, steps=ns_steps, eps=eps)
                if rms_scaling:
                    ortho = match_update_rms(ortho, mode="shape")

            # 步骤4: Weight Decay(解耦)
            if weight_decay:
                p.mul_(1.0 - lr * weight_decay)

            # 步骤5: 参数更新
            out_dim, in_dim = p.shape[-2], p.shape[-1]
            scale = math.sqrt(max(1.0, out_dim / in_dim))
            p.add_(ortho, alpha=-lr * scale)

            # 步骤6: Kimi K2 Weight Clipping
            if weight_clip > 0:
                rms = p.pow(2).mean().sqrt()
                if float(rms) > weight_clip:
                    p.mul_(weight_clip / rms)

    def _adamw_step(self, group: dict[str, Any]) -> None:
        """标准 AdamW 更新(用于非矩阵参数)。"""
        lr = group.get("adamw_lr", group["lr"])
        beta1, beta2 = group["betas"]
        eps = group["eps"]
        weight_decay = group["weight_decay"]

        for p in group["params"]:
            if p.grad is None:
                continue

            grad = p.grad
            state = self.state[p]

            # 初始化状态
            if "step" not in state:
                state["step"] = 0
                state["exp_avg"] = torch.zeros_like(p)
                state["exp_avg_sq"] = torch.zeros_like(p)

            state["step"] += 1
            t = state["step"]
            exp_avg, exp_avg_sq = state["exp_avg"], state["exp_avg_sq"]

            # 一阶矩和二阶矩
            exp_avg.mul_(beta1).add_(grad, alpha=1 - beta1)
            exp_avg_sq.mul_(beta2).addcmul_(grad, grad, value=1 - beta2)

            # 偏差校正
            bc1 = 1 - beta1 ** t
            bc2 = 1 - beta2 ** t

            # 更新
            denom = (exp_avg_sq / bc2).sqrt_().add_(eps)
            if weight_decay:
                p.mul_(1.0 - lr * weight_decay)
            p.addcdiv_(exp_avg / bc1, denom, value=-lr)

0x03 本项目实现

3.1 与 kimi3-master 实现对比

维度 kimi3-master 我们的实现 区别说明
文件结构 muon.py 单文件(276行)含 NS + Muon + 参数分组 + build_optimizer 拆分为 3 文件:newton_schulz.py + muon.py + param_groups.py 更模块化,NS 可独立测试复用
Newton-Schulz 内联在 muon.py,batched 用 .mT 独立文件,显式分 2D 路径(.T)和 batched 路径(.mT) 逻辑等价,PyTorch 3.7 兼容性更好
_head_count isinstance(owner, (KimiDeltaAttention, GatedMLA)) 硬编码类型检查 hasattr(owner, "num_heads") 鸭子类型 零耦合,不依赖具体模块导入
muon_param_groups 接收 optim_cfg dataclass 对象 接收 per_head: bool 直接参数 更简洁,但缺少 build_optimizer 工厂
embedding 排除 仅排除 "embed_tokens" 额外排除 "embed"(覆盖 pos_embed 等) 更宽泛的排除规则
build_optimizer 有,从 optim_cfg 读全部超参构造 Muon 缺失 需手动构造 Muon 实例
RMS 缩放 内联 scale = sqrt(max(1, out/in)),无独立函数 独立 match_update_rms() 函数,支持 shape/reference_rms 两种模式 更灵活,但多了一层抽象
Weight Clipping 独立 _clip() 静态方法 内联到 _muon_step 逻辑相同,组织不同
Muon.__init__ 无 update_rms_scaling 参数 有 update_rms_scaling 开关 可控制是否启用 RMS 缩放
HybridMuonAdamW 无(Muon 类自身同时处理 Muon+AdamW 组) 额外提供 HybridMuonAdamW 包装器,含 NaN 检测、事务性 step 更模块化,但 kimi3-master 不需要
CosineWarmupLR 无调度器类,仅函数 + 训练循环内 set_lr 完整 CosineWarmupLR 类,支持双 LR 更工程化,但 kimi3-master 在训练循环中手动处理
P2P Muon 完整实现(168行) ✅ 已实现(~220行) 功能等价,28 项测试通过,详见附录 G

说明:

  • build_optimizer 工厂:可从 OptimConfig 读取超参自动构造,但我们的设计允许更灵活的手动构造

  • lr_lambda_for:被 CosineWarmupLR 类替代(内部 dispatch cosine/wsd)

  • schedules.py (63行)→ 已覆盖 ,功能在 lr_scheduler.py 中:

    • cosine_with_warmup() → 直接复刻,逻辑一致
    • wsd_schedule() → 直接复刻,逻辑一致
    • lr_lambda_for() → 被 CosineWarmupLR 类替代(内部 dispatch cosine/wsd)
  • muon_p2p.py (168行)→ ✅ 已实现 (src/optim/muon_p2p.py,~220行):
    • OwnershipMap → round-robin 所有权分配
    • P2PMuonOrthogonalizer → P2P 收集 → NS 正交化 → P2P 分发
    • orthogonalize_owned() → 一次性便捷函数
    • shard_ranges() → 本地实现,与 parallel/zero.py 共享

3.2 模块结构(文件级)

python 复制代码
src/optim/
├── __init__.py              # 公开 API 导出
├── newton_schulz.py         # [基础层] Newton-Schulz 正交化 + RMS 缩放
│   ├── newton_schulz()      #   2D 和 batched 正交化
│   └── match_update_rms()   #   RMS 缩放(shape/reference_rms 两种模式)
├── muon.py                  # [核心层] Muon 优化器
│   ├── per_head_orthogonalize()  # Per-Head 正交化(按注意力头拆分)
│   └── class Muon           #   动量+Nesterov+NS+RMS+WD+Clip
├── param_groups.py          # [策略层] 参数自动分组
│   ├── _head_count()        #   检测注意力头数(鸭子类型)
│   └── build_muon_param_groups()  # 2D矩阵→Muon / 其余→AdamW
├── hybrid.py                # [包装层] 混合优化器
│   └── class HybridMuonAdamW  # NaN检测+事务性step+双LR
├── lr_scheduler.py          # [调度层] 学习率调度
│   ├── cosine_with_warmup() #   Cosine 函数
│   ├── wsd_schedule()       #   WSD 函数
│   └── class CosineWarmupLR #   调度器(支持双LR)
├── base.py                  # [抽象层] Optimizer 基类(可选)
└── schedule.py              # [抽象层] LRSchedule 基类(可选)

3.3 类继承与组合关系

python 复制代码
torch.optim.Optimizer
    └── Muon                          # 继承 PyTorch Optimizer
            ├── 内部 dispatch:
            │   ├── _muon_step()      # Muon 组更新
            │   └── _adamw_step()     # AdamW 组更新
            └── 依赖:
                ├── newton_schulz()   # 标准正交化
                └── per_head_orthogonalize()  # Per-Head 正交化

HybridMuonAdamW                      # 独立包装器(非继承)
    ├── muon: Muon                    # 组合 Muon 实例
    ├── adamw: torch.optim.AdamW      # 组合 AdamW 实例
    └── 功能: NaN检测 / 事务性step / set_lr / state_dict

CosineWarmupLR                       # 独立调度器
    └── 持有 optimizer 引用,直接操作 param_groups["lr"]

3.4 与 kimi3-master 的文件映射

python 复制代码
kimi3-master/optim/              →    Model-Viz/src/optim/
─────────────────────────────────────────────────────────
muon.py (276行)                      newton_schulz.py (120行)
  ├── newton_schulz()                ├── newton_schulz()
  ├── _orthogonalise()               └── match_update_rms()
  ├── class Muon                     muon.py (242行)
  ├── _head_count()                  ├── per_head_orthogonalize()
  ├── muon_param_groups()            └── class Muon
  └── build_optimizer()              param_groups.py (95行)
                                      ├── _head_count()
schedules.py (63行)                   └── build_muon_param_groups()
  ├── cosine_with_warmup()           lr_scheduler.py (143行)
  ├── wsd_schedule()                 ├── cosine_with_warmup()
  └── lr_lambda_for()                ├── wsd_schedule()
                                      └── class CosineWarmupLR
muon_p2p.py (168行)                  hybrid.py (118行)
  ├── OwnershipMap                   └── class HybridMuonAdamW
  └── P2PMuonOrthogonalizer          (无直接对应,分布式专用)

3.5 数据流图

单步训练数据流

Newton-Schulz 正交化数据流

参数分组决策流


3.6 依赖关系图

文件级依赖

python 复制代码
experiments/optim/demo_muon_e2e.py
    └── src/optim/
        ├── muon.py ──────────→ newton_schulz.py
        ├── param_groups.py ──→ (无外部依赖)
        ├── hybrid.py ────────→ muon.py + torch.optim.AdamW
        └── lr_scheduler.py ──→ muon.py + torch.optim.Optimizer

函数级调用链

python 复制代码
Muon.step()
    │
    ├── _muon_step(group)
    │   ├── torch.optim.Optimizer (动量缓冲管理)
    │   ├── per_head_orthogonalize(matrix, num_heads, steps)
    │   │   ├── torch.view() (拆分为 per-head 块)
    │   │   ├── newton_schulz(block, steps)  ← 对每个头独立调用
    │   │   └── torch.cat() (合并回完整矩阵)
    │   ├── newton_schulz(update, steps)     ← 非 per-head 路径
    │   │   ├── torch.float32 (提升精度)
    │   │   ├── torch.mT / .T (转置优化)
    │   │   ├── torch.norm() (归一化)
    │   │   └── 5x 矩阵乘法迭代
    │   └── match_update_rms(ortho, mode)    ← 可选 RMS 缩放
    │
    └── _adamw_step(group)
        └── 标准 AdamW 更新(exp_avg / exp_avg_sq / 偏差校正)

build_muon_param_groups(model, per_head)
    ├── model.named_parameters() (遍历所有参数)
    ├── _head_count(model, name) (检测头数)
    │   ├── model 模块遍历 (getattr 逐层访问)
    │   └── hasattr(owner, "num_heads") (鸭子类型检测)
    └── 返回 [{"params": [...], "use_muon": bool, "num_heads": int|None}, ...]

CosineWarmupLR.step()
    ├── cosine_with_warmup(step, total_steps) 或 wsd_schedule(...)
    └── group["lr"] = base_lr * scale (对每个 param_group)

HybridMuonAdamW.step()
    ├── 梯度 NaN/Inf 检查 → 非有限则跳过
    ├── Muon.step()
    ├── AdamW.step()
    └── OptimizerStepReport (执行报告)

外部依赖

python 复制代码
src/optim/
    └── 仅依赖:
        ├── torch (PyTorch 张量运算)
        ├── torch.nn (nn.Module 类型标注)
        └── torch.optim.Optimizer (基类)
    
    不依赖:
        ├── torch.distributed (分布式通信)
        ├── kimi3 模块 (零耦合,鸭子类型)
        └── 第三方库 (纯 PyTorch 实现)

3.7 训练循环关键流程图

python 复制代码
┌─────────────────────────────────────────────────────┐
│                    train_step()                       │
├─────────────────────────────────────────────────────┤
│ 1. model.train()                                     │
│ 2. optimizer.zero_grad(set_to_none=True)             │
│                                                      │
│ 3. for batch in micro_batches:    ← 梯度累积          │
│    ├── batch.to(device)                              │
│    ├── out = model(input_ids, labels, doc_ids)       │
│    ├── loss = out.loss / grad_accum                  │
│    └── loss.backward()                               │
│                                                      │
│ 4. grad_norm = clip_grad_norm_(params, max_norm)    │
│ 5. lr = set_lr(step)              ← 学习率调度        │
│    ├── Muon groups: lr *= scale                      │
│    └── AdamW groups: adamw_lr *= scale               │
│                                                      │
│ 6. optimizer.step()              ← Muon + AdamW 更新  │
│    ├── Muon 组:                                      │
│    │   ├── buf = μ*buf + grad      (动量累积)         │
│    │   ├── update = NS(grad+μ*buf) (正交化)           │
│    │   ├── scale = sqrt(max(1,m/n)) (RMS 缩放)       │
│    │   └── p -= lr * scale * update                  │
│    ├── AdamW 组:                                     │
│    │   ├── 标准 AdamW 更新(偏置校正 + 解耦衰减)      │
│    └── QK-Clip: 对称缩放 Q/K 权重                    │
│                                                      │
│ 7. model.update_router_biases()  ← 延迟 Router 更新  │
│ 8. state.step += 1                                   │
└─────────────────────────────────────────────────────┘
python 复制代码
┌─────────────────────────────────────────────────────┐
│                   train() 主循环                      │
├─────────────────────────────────────────────────────┤
│ for step in range(total_steps):                      │
│   ├── curriculum.stage_for_step(step)  ← 课程学习     │
│   ├── batches = dataset.sample()                     │
│   ├── record = train_step(batches)                   │
│   ├── metrics.log(record)                           │
│   └── if step % log_every == 0: print metrics       │
└─────────────────────────────────────────────────────┘

0x04. 子知识点深度分析

4.0 共享抽象与设计动机

为什么需要"混合"优化器?

Muon 的正交化操作本质上是一个矩阵级操作------它假设参数具有2D矩阵结构。但是,对于 embedding(通常是3D或2D但语义特殊)、lm_head、norm层、bias、router 等参数,正交化既无意义也可能有害。因此 KIMI K3 采用混合策略:2D 矩阵参数用 Muon,其余用 AdamW。

共享状态约定:

状态 Muon 组 AdamW 组
动量缓冲 momentum_buffer(一个 FP32 张量) exp_avg + exp_avg_sq(两个 FP32 张量)
学习率 lr(独立控制) adamw_lr(独立控制)
Weight Decay weight_decay weight_decay(同参数)
梯度 FP16/BF16 → FP32 计算 FP16/BF16 → FP32 计算

内存开销对比(per parameter):

优化器 权重副本 动量缓冲 总计
AdamW 4 bytes (FP32 master) 8 bytes (2× FP32) 12 bytes
Muon 4 bytes (FP32 master) 4 bytes (1× FP32) 8 bytes

Muon 的内存效率优势:比 AdamW 少 33%(仅需一个动量缓冲,而非两个)。


子知识点拆解如下:

python 复制代码
Muon 优化器系统
├── 4.1 Newton-Schulz 正交化
│   ├── 4.1.1 标准 Newton-Schulz(全矩阵)
│   └── 4.1.2 Per-Head Newton-Schulz(按注意力头拆分)
├── 4.2 Muon 更新规则
│   ├── 4.2.1 动量累积 + Nesterov 加速
│   ├── 4.2.2 正交化 + RMS 缩放
│   └── 4.2.3 Weight Decay + Weight Clipping
├── 4.3 参数分组策略
│   ├── 4.4.1 Muon 组(2D 矩阵)
│   ├── 4.4.2 AdamW 组(1D 参数 + 特殊矩阵)
│   └── 4.4.3 Per-Head 组(注意力投影)
├── 4.4 QK-Clip(Q/K 权重重缩放)
├── 4.5 混合优化器包装器(Hybrid Optimizer)
├── 4.6 分布式 P2P Muon
├── 4.7 学习率调度
│   ├── 4.7.1 Cosine with Warmup
│   ├── 4.7.2 Warmup-Stable-Decay(消融用)
│   └── 4.7.3 双学习率调度(Muon LR + AdamW LR)
├── 4.8 训练循环(Train Loop)
│   ├── 4.8.1 单步训练(train_step)
│   ├── 4.8.2 梯度累积 + 梯度裁剪
│   ├── 4.8.3 Router Bias 延迟更新
│   └── 4.8.4 Context Curriculum
└── 4.9 配置系统
    ├── 4.9.1 OptimConfig(kimi3-master)
    ├── 4.9.2 KimiOptimizerConfig(kimi-k3-pytorch-main)
    └── 4.9.3 YAML 配置文件

4.1 Newton-Schulz 正交化

4.1.1 要解决的问题

Muon 需要对梯度动量矩阵 \(M\) 做正交化,找到最近的半正交矩阵 \(O\),使得:

\O = \\arg\\min_{Q: Q\^TQ=I} \\\|Q - M\\\|_F \\

精确求解需要 SVD 分解(\(M = U\Sigma V^T \Rightarrow O = UV^T\)),但 SVD 在 GPU 上不高效。Newton-Schulz 迭代提供了一种仅需矩阵乘法的近似方案。

4.1.2 三视角原理

直觉:Newton-Schulz 就像一个"磨平"过程------把一个歪歪扭扭的矩阵(奇异值分布不均)通过反复的矩阵乘法磨成一个"圆"的矩阵(奇异值都接近1)。

准专业 :给定矩阵 \(X\),Newton-Schulz 迭代计算:

\X_{k+1} = a \\cdot X_k + b \\cdot (X_k X_k\^T) X_k + c \\cdot (X_k X_k\^T)\^2 X_k \\

系数 \((a, b, c) = (3.4445, -4.7750, 2.0315)\) 来自 Jordan et al.,经过精心调优使5步内收敛到 \(\|X_k X_k^T - I\| < 10^{-6}\)。

关键步骤:

  1. 归一化 :\(X \leftarrow X / \|X\|_F\),使谱半径 ≤ 1
  2. 转置优化 :若矩阵高大于宽(\(m > n\)),先转置再正交化,减少计算量
  3. 迭代:5 步 quintic 近似

专家 :Newton-Schulz 是对极分解 \(M = O \cdot S\)(\(O\) 正交,\(S\) 半正定)的迭代逼近。从矩阵 Lie 群的角度,它在正交群上做梯度流的离散化。

4.1.3 对比基线

维度 精确 SVD Newton-Schulz (5步)
精度 \(10^{-16}\)(机器精度) \(10^{-6}\)(足够训练)
计算复杂度 \(O(mn^2)\) 或 \(O(n^3)\) \(O(5 \cdot m \cdot n \cdot \min(m,n))\)
GPU 友好度 低(SVD 内核不高度并行) 高(纯矩阵乘法,cuBLAS 高度优化)
内存 额外 \(\Sigma\) 和 \(V^T\) 仅工作矩阵

4.1.4 工程实现

kimi3-master 版本 (kimi3-master/kimi3/optim/muon.py:38-59):

python 复制代码
_NS_COEFFS = (3.4445, -4.7750, 2.0315)

def newton_schulz(g: Tensor, steps: int = 5, eps: float = 1e-7) -> Tensor:
    a, b, c = _NS_COEFFS
    x = g.to(torch.float32)          # 提升到 FP32 避免数值下溢
    transposed = x.shape[-2] > x.shape[-1]
    if transposed:
        x = x.mT                      # 转置优化:高矩阵先转置
    norm = x.norm(dim=(-2, -1), keepdim=True).clamp_min(eps)
    x = x / norm                      # 归一化使谱半径 ≤ 1
    for _ in range(steps):
        aa = x @ x.mT                 # A = X · X^T
        bb = b * aa + c * (aa @ aa)   # B = b·A + c·A²
        x = a * x + bb @ x            # X = a·X + B·X
    if transposed:
        x = x.mT
    return x.to(g.dtype)              # 恢复原始 dtype

kimi-k3-pytorch-main 版本 (kimi-k3-pytorch-main/training/optimizer/newton_schulz.py:11-42):

python 复制代码
def zeropower_via_newton_schulz(matrix, *, steps=5, eps=1e-7, output_dtype=None):
    work = matrix.detach().float().clone()
    if not torch.isfinite(work).all():
        raise FloatingPointError("Newton-Schulz input contains NaN or Inf")
    if float(work.norm().item()) <= eps:
        return torch.zeros_like(matrix, dtype=output_dtype or matrix.dtype)
    transposed = work.shape[0] > work.shape[1]
    if transposed:
        work = work.T
    work.div_(work.norm().clamp_min(eps))
    a, b, c = 3.4445, -4.7750, 2.0315
    for _ in range(steps):
        gram = work @ work.T
        work = a * work + b * (gram @ work) + c * ((gram @ gram) @ work)
    if transposed:
        work = work.T
    return work.to(device=matrix.device, dtype=output_dtype or matrix.dtype)

差异分析:

  • kimi3-master: 使用 x.mT(modern transpose),不检查 NaN/Inf
  • kimi-k3-pytorch-main: 使用 work.T,增加了 NaN/Inf 检查和零输入保护
  • 两者数学上完全等价

4.1.5 Per-Head Newton-Schulz

要解决的问题:全矩阵正交化将所有注意力头的更新统一到一个尺度。如果某个头的梯度/动量特别大,它会主导正交化后的尺度,导致其他头的更新过小。

解决方案:将矩阵按注意力头拆分,独立正交化每个头的块。

python 复制代码
原始矩阵 W_q: [out_dim, in_dim] = [num_heads × head_dim, in_dim]
拆分: [num_heads, head_dim, in_dim]
每个块独立 NS → [num_heads, head_dim, in_dim]
合并: [out_dim, in_dim]

kimi3-master 实现 (kimi3/optim/muon.py:62-71):

python 复制代码
def _orthogonalise(update: Tensor, steps: int, heads: int | None) -> Tensor:
    if heads is None or heads <= 1:
        return newton_schulz(update, steps)
    out_dim, in_dim = update.shape
    blocks = update.view(heads, out_dim // heads, in_dim)
    return newton_schulz(blocks, steps).view(out_dim, in_dim)

kimi-k3-pytorch-main 实现 (training/optimizer/per_head_muon.py:78-159):

更详细的实现,支持 separate 和 fused_qkv 两种布局,收集每个头的 RMS 指标:

python 复制代码
def per_head_orthogonalize(matrix, layout, *, steps, eps, rms_scaling=True):
    # 1. 按 layout 拆分为 per-head 块
    # 2. 对每个块独立 NS 正交化
    # 3. 收集 raw/orthogonal/final RMS
    # 4. 可选 RMS 缩放 (match_update_rms)
    # 5. 合并并返回指标

关键指标:

  • per_head_muon/head_update_rms_cv: 头间更新 RMS 的变异系数(CV < 0.05 表示头间均衡)
  • per_head_muon/head_update_rms_max_to_median: 最大头与中位数头的 RMS 比值

4.1.6 代码位置汇总

文件 位置 内容
kimi3-master/kimi3/optim/muon.py:38-59 newton_schulz() 标准 NS 实现
kimi3-master/kimi3/optim/muon.py:62-71 _orthogonalise() Per-Head 分发
kimi-k3-pytorch-main/training/optimizer/newton_schulz.py:11-42 zeropower_via_newton_schulz() 带 NaN 检查的 NS
kimi-k3-pytorch-main/training/optimizer/per_head_muon.py:78-159 per_head_orthogonalize() Per-Head NS + 指标

4.2 Muon 更新规则

4.2.1 要解决的问题

如何将 Newton-Schulz 正交化整合到完整的优化器更新规则中,包括动量累积、Nesterov 加速、RMS 缩放、weight decay 和 weight clipping。

4.2.2 三视角原理

直觉:Muon 的更新就像一个精心编排的"四步舞":

  1. 收集信号(梯度 + 历史动量)
  2. 整形信号(正交化使所有方向等幅)
  3. 缩放信号(补偿矩阵形状差异)
  4. 应用信号(更新权重 + 约束增长)

准专业:完整的 Muon 更新步骤:

python 复制代码
对于每个参数 p:
  1. 动量累积:  buf = μ * buf + grad
  2. Nesterov:  update = grad + μ * buf    (如果启用)
  3. 正交化:    ortho = NS(update, steps)
  4. RMS 缩放:  scale = sqrt(max(1, out_dim / in_dim))
  5. Weight Decay: p = p * (1 - lr * λ)    (解耦)
  6. 参数更新:  p = p - lr * scale * ortho
  7. Weight Clipping: if RMS(p) > threshold: p *= threshold / RMS(p)

专家 :从优化理论角度,Muon 的更新方向 \(O\) 是在正交群上的最速下降方向。RMS 缩放因子 \(\sqrt{\max(1, m/n)}\) 的推导:对于半正交矩阵 \(O \in \mathbb{R}^{m \times n}\)(\(m > n\)),\(\|O\|_F = \sqrt{n}\),因此 \(\text{RMS}(O) = \sqrt{n/(mn)} = 1/\sqrt{m}\)。为使更新 RMS 与 AdamW 对齐,需要乘以 \(\sqrt{m} = \sqrt{\max(m,n)}\)。

4.2.3 对比基线

维度 标准 SGD+Momentum AdamW Muon
更新方向 \(v_t = \mu v_{t-1} + g_t\) \(m_t/(\sqrt{v_t}+\epsilon)\) \(\text{NS}(\mu M_{t-1} + g_t)\)
方向性质 梯度方向(可能偏斜) 逐元素归一化 正交化(所有方向等幅)
缩放 固定 lr 自适应(per-element) RMS 缩放(per-matrix)
动量缓冲 1个 2个 1个
Weight Decay L2 正则化 解耦 解耦(同 AdamW)

4.2.4 工程实现

kimi3-master 版本 (kimi3/optim/muon.py:127-151):

python 复制代码
def _muon_group(self, group):
    lr = group["lr"]
    momentum = group["momentum"]
    heads = group.get("num_heads")
    for p in group["params"]:
        if p.grad is None:
            continue
        grad = p.grad
        state = self.state[p]
        if "momentum_buffer" not in state:
            state["momentum_buffer"] = torch.zeros_like(grad)
        buf = state["momentum_buffer"]
        buf.mul_(momentum).add_(grad)                              # 步骤1: 动量累积
        update = grad.add(buf, alpha=momentum) if group["nesterov"] else buf  # 步骤2: Nesterov

        ortho = _orthogonalise(update, group["ns_steps"], heads)   # 步骤3: 正交化
        out_dim, in_dim = p.shape[-2], p.shape[-1]
        scale = math.sqrt(max(1.0, out_dim / in_dim))              # 步骤4: RMS 缩放

        if group["weight_decay"]:
            p.mul_(1.0 - lr * group["weight_decay"])               # 步骤5: Weight Decay
        p.add_(ortho, alpha=-lr * scale)                           # 步骤6: 参数更新
        self._clip(p, group["weight_clip"])                        # 步骤7: Weight Clipping

kimi-k3-pytorch-main 版本 (training/optimizer/muon.py:54-142):

增加了指标收集和 NaN 检查:

python 复制代码
def step(self, closure=None):
    # ... NaN 检查 ...
    for group in self.param_groups:
        for parameter in group["params"]:
            grad = parameter.grad.detach()
            state = self.state[parameter]
            buffer = state.setdefault("momentum_buffer", torch.zeros_like(grad))
            buffer.mul_(group["momentum"]).add_(grad)
            raw = grad.add(buffer, alpha=group["momentum"]) if group["nesterov"] else buffer
            
            # 根据参数类型选择正交化方式
            spec = self.spec_by_parameter[id(parameter)]
            if spec.optimizer_family == "per_head_muon":
                update, head_metrics = per_head_orthogonalize(raw, spec.head_layout, ...)
            else:
                update = zeropower_via_newton_schulz(raw, ...)
                if group["update_rms_scaling"]:
                    update = match_update_rms(update, mode="shape")
            
            # Weight Decay + 更新
            if group["weight_decay"]:
                parameter.mul_(1.0 - group["lr"] * group["weight_decay"])
            parameter.add_(update, alpha=-group["lr"])

4.2.5 Kimi K2 Weight Clipping

python 复制代码
@staticmethod
def _clip(p: Tensor, threshold: float) -> None:
    if threshold <= 0:
        return
    rms = p.pow(2).mean().sqrt()
    if float(rms) > threshold:
        p.mul_(threshold / rms)

作用:当参数 RMS 超过阈值时,等比缩放回阈值。这防止了某些参数因更新累积而无限增长,导致 attention logit 爆炸。Kimi K2/K3 论文将此作为稳定大模型训练的关键技术之一。


4.3 参数分组策略

4.3.1 要解决的问题

模型中包含多种类型的参数------2D 矩阵(Linear 层权重)、1D 向量(bias、norm gain)、特殊矩阵(embedding、lm_head、router)。Muon 的正交化仅适用于"常规"2D 矩阵,其他参数需要使用 AdamW。

4.3.2 原理

直觉:这就像一个工厂的分工------"重型机械"(2D 矩阵)由 Muon 专线处理,"小件"(1D 参数)由 AdamW 通用线处理,"特殊件"(embedding/router)也走通用线。

分组规则:

python 复制代码
参数分类逻辑:
  if ndim != 2:
    → AdamW(Muon 不适用)
  if name contains "embed_tokens" or "lm_head" or "router":
    → AdamW(语义特殊,不适合正交化)
  if name ends with "bias" or ndim == 1:
    → AdamW(1D,无矩阵结构)
  if name in ("q_proj", "k_proj", "v_proj", "q_up", "k_up", "v_up")
     AND parent is KimiDeltaAttention or GatedMLA:
    → Per-Head Muon(独立正交化每个注意力头)
  otherwise (2D matrix):
    → Muon(标准全矩阵正交化)

4.3.3 工程实现

kimi3-master (kimi3/optim/muon.py:222-261):

python 复制代码
_PER_HEAD_SUFFIXES = ("q_proj", "k_proj", "v_proj", "q_up", "k_up", "v_up")

def muon_param_groups(model, optim_cfg):
    per_head = {}   # {num_heads: [params]}
    matrices = []   # 普通2D矩阵
    others = []     # AdamW 参数

    for name, p in model.named_parameters():
        if not p.requires_grad:
            continue
        is_matrix = p.ndim == 2
        excluded = (
            "embed_tokens" in name or "lm_head" in name or "router" in name
            or name.endswith("bias") or (".weight" in name and p.ndim == 1)
        )
        if not is_matrix or excluded:
            others.append(p)
            continue
        heads = _head_count(model, name) if optim_cfg.per_head else None
        if heads and p.shape[0] % heads == 0:
            per_head.setdefault(heads, []).append(p)
        else:
            matrices.append(p)

    groups = []
    if matrices:
        groups.append({"params": matrices, "use_muon": True, "num_heads": None})
    for heads, params in sorted(per_head.items()):
        groups.append({"params": params, "use_muon": True, "num_heads": heads})
    if others:
        groups.append({"params": others, "use_muon": False, "num_heads": None})
    return groups

kimi-k3-pytorch-main (training/optimizer/parameter_registry.py:169-325):

更结构化的参数注册表系统,支持四种优化器家族:

家族 参数类型 优化器 Weight Decay
per_head_muon Q/K/V 投影矩阵 Per-Head Muon 是
muon 其他2D矩阵 标准 Muon 是
adamw_decay 大型2D矩阵(非 Muon) AdamW 是
adamw_no_decay bias/norm/embedding/lm_head AdamW 否

参数检测机制 (_qkv_role_and_layout()):

python 复制代码
def _qkv_role_and_layout(owner_name, modules):
    # 检查模块是否有 _kimi_head_spec 属性(并行线性层)
    # 检查父模块是否是 KDAProjections → q_proj/k_proj/v_proj
    # 检查父模块是否是 MLAProjections → query
    # 检查父模块是否是 LatentKVProjection → key_up/value_up
    # 返回 (role, HeadMatrixLayout)

4.4 QK-Clip(Q/K 权重重缩放)

4.4.1 要解决的问题

在长序列训练中,Q 和 K 权重可能增长过大,导致 attention scale(\(QK^T / \sqrt{d}\))爆炸,引发数值不稳定。QK-Clip 通过监控 attention scale 并对称缩放 Q/K 权重来预防此问题。

4.4.2 原理

直觉 :QK-Clip 就像一个"安全阀"------当 Q 和 K 的乘积增长过快时,它会同时缩小 Q 和 K(各缩小 \(\sqrt{\text{correction}}\)),使它们的乘积回到安全范围。

数学:

  • 监控 proxy: \(\text{scale} = \|QK^T\|_{\max}\)(或类似度量)
  • 当 \(\text{scale} > \text{threshold}\):
    • \(\text{correction} = \min(1.0, \text{threshold} / \text{scale})\)
    • \(Q \leftarrow Q \cdot \sqrt{\text{correction}}\)
    • \(K \leftarrow K \cdot \sqrt{\text{correction}}\)
    • 乘积缩放: \((Q\sqrt{c})(K\sqrt{c})^T = c \cdot QK^T\)(等效于将 scale 降到 threshold)

4.4.3 工程实现

kimi-k3-pytorch-main (training/optimizer/qk_clip.py:39-162):

python 复制代码
class QKClipController:
    def __init__(self, model, *, threshold, eps=1e-6, every_steps=1, ...):
        # 扫描模型,找到所有有 _kimi_qk_weights 或 GatedMLA/KDA 的模块
        self.layers = []
        for name, module in model.named_modules():
            custom_weights = getattr(module, "_kimi_qk_weights", None)
            if custom_weights is not None:
                self.layers.append((name, module, custom_weights[0], custom_weights[1]))
            elif isinstance(module, GatedMLA):
                self.layers.append((name, module, module.projections.query.weight,
                                   module.projections.latent_kv.key_up.weight))

    @torch.no_grad()
    def apply(self, step):
        for _, module, query_weight, key_weight in self.layers:
            scale = getattr(module, "_last_qk_scale", None)
            if scale is None:
                continue
            # 可选: 分布式 all_reduce 获取全局最大 scale
            value = float(reduced_scale.item())
            if value > self.threshold:
                correction = min(1.0, self.threshold / max(value, self.eps))
                symmetric = correction ** 0.5
                query_weight.mul_(symmetric)   # 对称缩放 Q
                key_weight.mul_(symmetric)     # 对称缩放 K

关键设计:

  • 每 N 步执行一次(every_steps),避免频繁检查
  • 支持分布式 all_reduce 获取跨 rank 的最大 scale
  • 仅缩放 Q 和 K,不缩放 V(V 的缩放不影响 attention scale)

kimi3-master 版本 :使用 _clip() 方法(weight clipping),不区分 Q/K,而是对所有参数统一做 RMS 裁剪。QK-Clip 是更精确的替代方案。


4.5 混合优化器包装器(Hybrid Optimizer)

4.5.1 要解决的问题

将 Muon 和 AdamW 两个独立优化器组合成一个统一接口,支持:

  • 统一的 step() / zero_grad() / state_dict() 接口
  • 事务性更新:如果检测到非有限梯度,跳过整个步骤(不更新任何参数)
  • 独立的 Muon LR 和 AdamW LR 控制
  • QK-Clip 集成

4.5.2 工程实现

kimi-k3-pytorch-main (training/optimizer/hybrid.py:29-153):

python 复制代码
class KimiHybridOptimizer:
    def __init__(self, muon, adamw, report, config, qk_clip):
        self.muon = muon       # KimiMuon 实例
        self.adamw = adamw     # torch.optim.AdamW 实例
        self.report = report   # ParameterAssignmentReport
        self.qk_clip = qk_clip

    @torch.no_grad()
    def step(self, closure=None):
        # 事务性检查: 梯度是否包含 NaN/Inf
        parameters = [p for group in self.param_groups for p in group["params"] if p.grad is not None]
        nonfinite = sum(not bool(torch.isfinite(p.grad).all()) for p in parameters)
        if nonfinite:
            return OptimizerStepReport(executed=False, nonfinite_parameters=nonfinite, ...)
        
        # 正常更新
        update_metrics = self.muon.step() # muon 更新
        self.adamw.step() # adamw 更新
        self.step_number += 1
        
        # QK-Clip
        clip_report = self.qk_clip.apply(self.step_number) if self.qk_clip else None
        return OptimizerStepReport(executed=True, update_metrics=update_metrics, ...)

kimi3-master 版本 (kimi3/optim/muon.py:74-123):

更简单的实现------Muon 类自身同时处理 Muon 和 AdamW 组:

python 复制代码
class Muon(torch.optim.Optimizer):
    def step(self, closure=None):
        for group in self.param_groups:
            if group.get("use_muon", True):
                self._muon_group(group)
            else:
                self._adamw_group(group)

差异 :kimi3-master 将 Muon 和 AdamW 合并在一个 Optimizer 子类中;kimi-k3-pytorch-main 将它们分离为两个独立优化器并用包装器组合。后者更模块化,但前者更简单。

4.7 学习率调度

4.7.1 Cosine with Warmup

kimi3-master (kimi3/optim/schedules.py:17-27):

python 复制代码
def cosine_with_warmup(step, total_steps, *, warmup_ratio=0.01, min_lr_ratio=0.1):
    warmup = max(1, int(total_steps * warmup_ratio))
    if step < warmup:
        return (step + 1) / warmup                    # 线性 warmup
    progress = (step - warmup) / max(1, total_steps - warmup)
    cosine = 0.5 * (1.0 + math.cos(math.pi * progress))
    return min_lr_ratio + (1.0 - min_lr_ratio) * cosine  # 余弦衰减

行为:

  • 步骤 0 ~ warmup: 从 0 线性增长到 1.0
  • 步骤 warmup ~ total: 从 1.0 余弦衰减到 min_lr_ratio(默认0.1)

4.7.2 Warmup-Stable-Decay(消融用)

python 复制代码
def wsd_schedule(step, total_steps, *, warmup_ratio=0.01, decay_ratio=0.1, min_lr_ratio=0.1):
    warmup = max(1, int(total_steps * warmup_ratio))
    decay_start = int(total_steps * (1.0 - decay_ratio))
    if step < warmup:
        return (step + 1) / warmup
    if step < decay_start:
        return 1.0                    # 稳定阶段
    progress = (step - decay_start) / max(1, total_steps - decay_start)
    return min_lr_ratio + (1.0 - min_lr_ratio) * (1.0 - progress)  # 线性衰减

Liu et al. (2025) 结论:在各自独立调参的前提下,Cosine 一致优于 WSD,因此 Cosine 作为默认。

4.7.3 双学习率调度

kimi3-master (kimi3/train/loop.py:84-89):

python 复制代码
def set_lr(self, step):
    scale = self.lr_lambda(step)
    for group, (lr, adamw_lr) in zip(self.optimizer.param_groups, self.base_lrs):
        group["lr"] = lr * scale          # Muon LR
        group["adamw_lr"] = adamw_lr * scale  # AdamW LR

kimi-k3-pytorch-main (training/scheduler.py:144-166):

python 复制代码
def _set_lr_hybrid(self, step):
    muon_min_lr = self.min_lr if self.min_muon_lr is None else self.min_muon_lr
    for i, group in enumerate(self.optimizer.adamw.param_groups):
        group["lr"] = self._compute_lr(base_lr=self.base_adamw_lrs[i], min_lr=self.min_lr, step=step)
    for i, group in enumerate(self.optimizer.muon.param_groups):
        group["lr"] = self._compute_lr(base_lr=self.base_muon_lrs[i], min_lr=muon_min_lr, step=step)

设计要点:Muon 和 AdamW 可以有不同的基础学习率和最小学习率,但共享同一个调度曲线形状。

4.7.4 实现

Reference\kimi3-master\kimi3\optim\schedules.py 的功能,全部在 src/optim/lr_scheduler.py 中实现。逐函数映射:

schedules.py lr_scheduler.py 位置 差异
cosine_with_warmup() cosine_with_warmup() lr_scheduler.py:11-37 逐行一致
wsd_schedule() wsd_schedule() lr_scheduler.py:40-59 逐行一致
lr_lambda_for() CosineWarmupLR 类 lr_scheduler.py:62-143 被类替代,内部 dispatch cosine/wsd

额外功能(schedules.py 没有):

  • CosineWarmupLR 类:直接操作 optimizer.param_groups,支持 Muon/AdamW 双 LR 调度(group["lr"] + group["adamw_lr"] 同步缩放)

4.8 训练循环(Train Loop)

4.8.1 单步训练

kimi3-master (kimi3/train/loop.py:91-134):

python 复制代码
def train_step(self, batches):
    self.model.train()
    self.optimizer.zero_grad(set_to_none=True)

    # 梯度累积
    for batch in batches:
        out = self.model(batch.input_ids, labels=batch.labels, doc_ids=batch.doc_ids)
        loss = out.loss / len(batches)
        loss.backward()

    # 梯度裁剪
    grad_norm = torch.nn.utils.clip_grad_norm_(self.model.parameters(), cfg.optim.grad_clip)

    # 学习率调度
    lr = self.set_lr(self.state.step)

    # 优化器更新
    self.optimizer.step()

    # 延迟 Router Bias 更新(因果性:使用当前步的直方图更新下一步的 bias)
    self.model.model.update_router_biases()

4.8.2 梯度累积 + 梯度裁剪

python 复制代码
总 loss = Σ(loss_i / grad_accum)     # 平均化 micro-batch 的 loss
grad_norm = clip_grad_norm_(params, max_norm=1.0)  # 全局梯度范数裁剪

4.8.3 Router Bias 延迟更新

原因 :MoE 的 router bias 应基于"当前步"的 expert 使用直方图更新,但直方图在 forward 期间累积。如果在同一 update 中应用,会引入因果性问题(使用了"未来"的直方图)。因此将 router bias 更新延迟到 optimizer.step() 之后。

4.8.4 Context Curriculum

训练过程中根据步数切换不同的上下文长度(seq_len),从短到长逐步增加。这允许模型先学习局部模式,再学习长程依赖。


4.9 配置系统

4.9.1 OptimConfig(kimi3-master)

python 复制代码
@dataclass(frozen=True)
class OptimConfig:
    lr: float = 1e-3                    # Muon 学习率
    adamw_lr: float = 3e-4              # AdamW 学习率(通常更小)
    weight_decay: float = 0.1
    betas: tuple = (0.9, 0.95)          # AdamW beta 参数
    eps: float = 1e-8                   # AdamW epsilon
    muon_momentum: float = 0.95         # Muon 动量系数
    muon_nesterov: bool = True          # Nesterov 加速
    newton_schulz_steps: int = 5        # NS 迭代步数
    per_head: bool = True               # Per-Head 正交化
    weight_clip: float = 0.0            # Kimi K2 权重裁剪(0=禁用)
    grad_clip: float = 1.0              # 梯度范数裁剪
    schedule: Literal["cosine", "wsd"] = "cosine"
    warmup_ratio: float = 0.01          # 1% warmup
    min_lr_ratio: float = 0.1           # 最小 LR 为峰值的10%

4.9.2 KimiOptimizerConfig(kimi-k3-pytorch-main)

python 复制代码
@dataclass(frozen=True)
class KimiOptimizerConfig:
    kind: Literal["adamw", "muon_adamw", "per_head_muon_adamw"] = "per_head_muon_adamw"
    adamw_lr: float = 3e-4
    adamw_betas: tuple = (0.9, 0.95)
    adamw_eps: float = 1e-8
    muon_lr: float | None = None        # None 则使用 adamw_lr
    muon_momentum: float = 0.95
    muon_nesterov: bool = True
    muon_ns_steps: int = 5
    muon_ns_eps: float = 1e-7
    muon_update_rms_scaling: bool = True
    weight_decay: float = 0.1
    muon_weight_decay: float | None = None  # None 则使用 weight_decay
    per_head_qkv: bool = True
    qk_clip_enabled: bool = True
    qk_clip_threshold: float = 100.0
    qk_clip_eps: float = 1e-6
    qk_clip_every_steps: int = 1

4.9.3 YAML 配置示例

kimi3-master/k3_nano.yaml:

yaml 复制代码
train:
  optim:
    lr: 0.002
    adamw_lr: 0.0006
    weight_decay: 0.1
    schedule: cosine
    warmup_ratio: 0.01
    per_head: true

kimi-k3-pytorch-main 各配置统一值:

yaml 复制代码
muon_momentum: 0.95
muon_nesterov: true
muon_ns_steps: 5
muon_ns_eps: 1.0e-7
muon_update_rms_scaling: true
weight_decay: 0.1
per_head_qkv: true
qk_clip_enabled: true
qk_clip_threshold: 100.0

附录A. 计算复杂度分析

A.1 FLOPs 对比

对于 \(W \in \mathbb{R}^{m \times n}\) 的单步更新:

操作 AdamW Muon
动量更新 \(2mn\) \(mn\)(一阶动量)
自适应缩放 \(3mn\)(二阶矩 + 偏差校正 + 分母) \(0\)
正交化 \(0\) \(5 \cdot 2 \cdot m \cdot n \cdot \min(m,n)\)(NS 迭代)
RMS 缩放 \(0\) \(mn\)(缩放)
总计 \(5mn\) \(5mn \cdot \min(m,n) + 2mn\)

对于典型的 Transformer 层(\(m = n = 4096\)):

  • AdamW: \(5 \times 4096^2 = 83.9M\) FLOPs
  • Muon: \(5 \times 4096^3 + 2 \times 4096^2 = 343.6G + 33.6M \approx 343.6G\) FLOPs

Muon 单步计算量更大 ,但由于更好的更新方向,通常需要更少的步数达到相同 loss,因此 wall-clock 时间更优(Liu et al. 报告约 2x 加速)。

A.2 内存对比

项目 AdamW Muon
权重副本 (FP32) 4 bytes/param 4 bytes/param
一阶动量 4 bytes/param 4 bytes/param
二阶动量 4 bytes/param 0
总计 12 bytes/param 8 bytes/param

Muon 节省 33% 优化器状态内存。

A.3 参数敏感性

超参数 默认值 调大的效果 调小的效果
muon_lr 1e-3 更新更大,可能不稳定 更新更小,收敛更慢
muon_momentum 0.95 更依赖历史梯度,更平滑 更依赖当前梯度,更灵敏
newton_schulz_steps 5 正交化更精确(收益递减) 正交化不够精确
adamw_lr 3e-4 AdamW 分支更新更大 AdamW 分支更新更小
weight_decay 0.1 权重衰减更快,防止过拟合 权重增长更大
warmup_ratio 0.01 更长的 warmup,更稳定但浪费步数 更短的 warmup,可能不稳定
min_lr_ratio 0.1 训练后期学习率更高 训练后期学习率更低
qk_clip_threshold 100.0 更宽松的 Q/K 缩放 更频繁的 Q/K 缩放

附录B. 交付核对

代码实现 (Model-Viz/src/optim/):

文件 内容 测试
newton_schulz.py NS 正交化 + match_update_rms 13 项 ✅
muon.py Muon 类 + per_head_orthogonalize 11 项 ✅
param_groups.py build_muon_param_groups + _head_count 4 项 ✅
hybrid.py HybridMuonAdamW(NaN检测/事务性step) 5 项 ✅
lr_scheduler.py CosineWarmupLR + cosine/wsd 函数 11 项 ✅
__init__.py 公开 API 导出 ---
muon_p2p.py P2P Muon 正交化器 + OwnershipMap 28 项 ✅

实验 :experiments/optim/demo_muon_e2e.py(Muon vs AdamW 对比,生成 muon_vs_adamw.png)

参考代码文件:

文件 行数 内容
kimi3-master/kimi3/optim/muon.py 276 核心 Muon 优化器
kimi3-master/kimi3/optim/muon_p2p.py 168 分布式 P2P Muon
kimi3-master/kimi3/optim/schedules.py 63 学习率调度
kimi3-master/kimi3/train/loop.py 214 训练循环
kimi3-master/kimi3/config.py:251-272 22 OptimConfig
kimi-k3-pytorch-main/training/optimizer/muon.py 142 KimiMuon
kimi-k3-pytorch-main/training/optimizer/newton_schulz.py 74 NS + RMS 缩放
kimi-k3-pytorch-main/training/optimizer/per_head_muon.py 159 Per-Head 正交化
kimi-k3-pytorch-main/training/optimizer/config.py 77 KimiOptimizerConfig
kimi-k3-pytorch-main/training/optimizer/qk_clip.py 162 QK-Clip
kimi-k3-pytorch-main/training/optimizer/hybrid.py 255 混合优化器包装器
kimi-k3-pytorch-main/training/optimizer/parameter_registry.py 325 参数注册表
kimi-k3-pytorch-main/training/scheduler.py 324 双 LR 调度器

附录C. 端到端的优化器测试demo

loop.py 的功能未在本项目中实现。 对比如下:

loop.py 功能 我们的项目 状态
Trainer 类(统一管理模型/优化器/数据/调度) 无 ❌
train_step() 梯度累积 + 梯度裁剪 + set_lr demo 中有简单版 ⚠️ 不完整
train() 完整训练循环 + curriculum + logging 无 ❌
evaluate() 评估循环 无 ❌
save()/load() checkpoint 无 ❌
set_lr() 双 LR 调度 CosineWarmupLR 已实现 ✅
Router Bias 延迟更新 无(属于模型层) ❌
build_optimizer() 工厂 无(手动构造) ❌

现有的 demo_muon_e2e.py 是一个最小化对比脚本,不是结构化的 Trainer。

下面构建一个完整的端到端 Trainer demo:

C.1 loop.py 功能覆盖状态

loop.py 功能 实现位置 状态
Trainer 类 src/optim/trainer.py ✅ 新增
train_step() 梯度累积 + 裁剪 + set_lr trainer.py:train_step() ✅ 新增
train() 完整训练循环 + 日志 trainer.py:train() ✅ 新增
evaluate() 评估 trainer.py:evaluate() ✅ 新增
save()/load() checkpoint trainer.py:save()/load() ✅ 新增
set_lr() 双 LR 调度 CosineWarmupLR + trainer.py:set_lr() ✅
build_optimizer() 工厂 手动构造(更灵活) ⚠️ 设计选择
Router Bias 延迟更新 模型层,非优化器职责 ❌ 不在范围
Context Curriculum 数据管线层 ❌ 不在范围
MetricLog / RunningMean trainer.py:RunningMean ✅ 简化版

C.2 端到端 Demo 结构

experiments/optim/demo_trainer_e2e.py 演示完整训练流程:

python 复制代码
Part 1: Muon 训练
  ├── Trainer 初始化(模型 + Muon + CosineWarmupLR)
  ├── train(steps=200, grad_accum=2)  ← 梯度累积 + 梯度裁剪 + 日志
  ├── evaluate(eval_data)             ← eval_loss + perplexity
  └── save/load checkpoint            ← 保存 → 加载 → 验证输出一致

Part 2: AdamW 对比训练
  └── 同结构 Trainer,AdamW 优化器

Part 3: 结果对比 + 4 图输出
  ├── 训练 loss 曲线(Muon vs AdamW,raw + smoothed)
  ├── 学习率调度曲线
  ├── 梯度范数曲线
  └── 最终 loss 柱状图(train + eval)


0xFF 参考文献

  1. Jordan, K. et al. (2024). Muon: An optimizer for hidden layers in neural networks. blog
  2. Liu, J. et al. (2025). Muon is Scalable for LLM Training. arXiv:2502.16982.
  3. Bernstein, J. & Newhouse, L. (2024). Old Optimizer, New Norm: An Anthology. arXiv:2409.20325.
  4. Chen, L. et al. (2025). Muon Optimizes Under Spectral Norm Constraints. arXiv:2506.15054.
  5. Kim, G. Y. & Oh, M. H. (2026). Convergence of Muon with Newton-Schulz. ICLR 2026.