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

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

目录

0x00 概要

本演示:

  • 对应文件:experiments/models/llm/kimi_k3/train/gradio_train_demo.py
  • 对应模块:src/models/llm/kimi_k3/train/(loop.py + metrics.py)

注:

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

0x01 功能概述

1.1 本演示包含什么

本 Gradio 演示围绕 K3 训练模块的全部核心功能展开,共 12 个 Tab,分两大类:

  • 训练循环类(7 个 Tab) :直接基于 train/loop.py 的 Trainer 类

    • 训练过程总览(loss / LR / grad_norm / tokens 四联图)
    • LR 调度曲线(Cosine vs WSD 对比)
    • Context Curriculum 上下文课程(阶段切换 + 步数预算)
    • 梯度累积等价性(不同 grad_accum 但有效批大小相同)
    • Checkpoint round-trip 验证(save → load 状态一致)
    • 评估指标(eval_loss / ppl 前后对比)
    • 设备选择 + Gradient Checkpointing(显存-速度权衡)
  • 指标与监控类(5 个 Tab) :基于 train/metrics.py

    • RunningMean 滑动窗口均值
    • MetricLog 记录 / 平滑 / JSONL 持久化
    • MoE 负载均衡(Quantile Balancing 效果)
    • KDA alpha 衰减因子分布(训练中实时监测)
    • 无模型回退行为(expert_balance / decay_stats 空模型不报错)

1.2 实现思路

核心设计原则:复用优先,零重复代码。

  1. plot 脚本独立可运行 :每个 fig_*() 函数返回 (fig, text) 元组,if __name__ == "__main__" 保存到 assets/
  2. Gradio 只做 UI 组装 :gradio_train_demo.py 直接 from plot_train_loop import fig_*,不实现任何绘图逻辑
  3. demo 脚本可 import :demo_pretrain_e2e.py 提取 build_nano_config() / build_nano_dataset() / run_training() 三个可复用函数,原有 main() 的 print 输出保持不变(向后兼容)
  4. 深色主题 :与 Model-Viz 前端 InferFlux 风格一致(#17181c 背景,#888899 边框)

1.3 读者能学到什么

  • 理解一个现代 LLM 训练循环的完整流程:数据 → 前向 → 反向 → clip → LR调度 → step → 日志
  • 掌握 K3 特有的训练技巧:Per-Head Muon + Quantile Balancing + Context Curriculum
  • 通过交互式参数调节,直观感受每个超参数对训练曲线的影响
  • 学会用 before/after 对比验证训练组件的正确性(如 grad_accum 等价性、checkpoint round-trip)

0x02 核心数学

2.1 总体公式

python 复制代码
# K3 训练一步(train_step)的核心流程
# 输入: model θ, batch B = (x, y, doc_ids), optimizer g(θ, ∇), lr_scheduler λ(t)
# 输出: 更新后的 θ, 训练指标 record

for micro_batch in B:                                    # 梯度累积
    loss = model(micro_batch).loss                       # Eq. 1: 前向 loss = -log p(y|x; θ)
    loss.backward()                                      # 反向: ∇θ loss

torch.nn.utils.clip_grad_norm_(θ, grad_clip)             # Eq. 2: 梯度裁剪
θ ← θ - λ(t) · g(θ, ∇θ loss)                             # Eq. 3: 优化器 step
router_bias ← update_bias(histogram)                     # Eq. 14: Quantile Balancing(延迟一步)

record = {step, loss, lr, grad_norm, tokens, ...}        # MetricLog 记录

符号维度说明:

  • θ:模型参数,total_params 维
  • x, y:输入/标签 token ids,形状 (batch, seq_len)
  • doc_ids:文档索引,形状 (batch, seq_len),用于 KDA 状态重置和 MLA mask
  • λ(t):学习率调度乘子,t 为当前步数,范围 [min_lr_ratio, 1.0]
  • g(θ, ∇):优化器更新规则(Muon + AdamW 混合)

2.2 子机制分解

2.2.1 学习率调度:Cosine with Warmup

公式:

python 复制代码
# Eq. 学习率乘子 λ(t)
warmup = floor(total_steps * warmup_ratio)

if t < warmup:
    λ(t) = (t + 1) / warmup                              # 线性 warmup, 从 0 增到 1
else:
    progress = (t - warmup) / (total_steps - warmup)    # 归一化进度 ∈ [0, 1]
    cos = 0.5 * (1 + cos(π * progress))                  # 余弦衰减, 从 1 降到 0
    λ(t) = min_lr_ratio + (1 - min_lr_ratio) * cos       # 缩放到 [min_lr_ratio, 1]

直觉解释:warmup 阶段从小学习率线性增长到峰值,避免初始阶段大梯度破坏模型;之后余弦缓慢衰减,让训练后期参数微调更精细。

关键性质:

  • λ(t) 先增后减,峰值恰好在 warmup 结束点
  • min_lr_ratio 保证训练后期仍有非零学习率(避免完全停滞)
  • 连续可导(除 warmup 转折点外),变化平滑

2.2.2 Quantile Balancing 负载均衡

公式:

python 复制代码
# Eq. 14 (router_qb.py)
# 给定 router 输出分数 s_j (n_experts 维), top_k 为选中专家数
# 求 bias b 使得每个专家被选中的概率 ≈ top_k / n_experts

required_j = cutoff - s_j                               # 达到 cutoff 需要的偏置量
b_hat_j = quantile_{1 - k/n}(required_j)                # 取 1-k/n 分位数
b_j = b_hat_j - mean(b_hat)                             # 零均值中心化

直觉解释:如果某个专家总是被选中(分数高),给它加负偏置"拉下来";如果总是不被选中,加正偏置"推上去"。最终让每个专家的负载接近均匀。

关键性质:

  • 延迟一步更新(用已消费的 batch 直方图,保证因果性)
  • 直方图近似分位数,误差 ≤ 一个 bin 宽
  • bias 始终零均值,不改变 router 总输出的"能量"

2.2.3 KDA alpha 衰减因子有界性

公式:

python 复制代码
# Eq. 5 (kda.py)
g(z) = g_min * sigmoid(A * exp(z))                       # 衰减参数
α(z) = exp(g(z))                                         # 衰减因子

其中 g_min < 0(通常 = -5),A > 0 是可学习标量。

直觉解释:alpha 表示"保留多少旧状态"。必须在 (0, 1) 之间------不能大于 1(否则状态爆炸),不能等于 0(否则完全遗忘)。用 exp(g_min * sigmoid(...)) 天然保证上下界。

关键性质:

  • 有界性:α ∈ (exp(g_min), 1),当 g_min = -5 时约为 (0.0067, 1.0)
  • 单调性:α(z) 随 z 增大而减小(z 大 → 遗忘多)
  • 可学习:A 是逐 head 可学习参数,控制门控陡峭度

2.3 关键洞察

关键洞察 :训练循环的核心不是"跑更多步",而是通过一套精密的控制机制(LR 调度、梯度裁剪、负载均衡、课程学习)确保优化过程稳定、高效、可复现。每一个看似"工程技巧"的组件,背后都有明确的数学约束或经验性的必要性验证。


0x03 每个 Tab 的详细说明


Tab 1: 训练过程总览

目的

验证一个完整的 K3 训练步是否能正常工作:loss 下降、LR 按调度衰减、梯度范数在 clip 范围内、token 数线性累积。这是训练模块正确性的主锚点------如果这个 Tab 跑不通,其他所有 Tab 都无从谈起。

背景概念

一个标准的 LLM 训练步包含:

  1. 采样一个 batch(PackedDataset)
  2. 前向传播计算 cross-entropy loss
  3. 反向传播计算梯度
  4. 梯度裁剪(防止梯度爆炸)
  5. 按 LR 调度更新学习率
  6. 优化器 step 更新参数
  7. 记录指标并打印

代码位置:train/loop.py:117 train_step() 函数

UI 组件与参数影响

参数 范围 默认 调节效果
随机种子 0-999 42 改变数据采样和模型初始化随机性
训练步数 5-60 30 增大 → loss 曲线更长,最终 loss 可能更低
初始学习率 1e-4 ~ 5e-3 1e-3 增大 → loss 下降快但可能震荡;减小 → 下降慢但稳定
micro_batch_size 1-8 4 增大 → 梯度估计更准,loss 更平滑,但每步更慢

输出图解读

布局:2×2 四联图

左上 (a):训练 loss 曲线

  • 图类型:折线图(双折线:原始 loss + 平滑 loss)
  • X 轴:step(训练步数),Y 轴:loss 值(线性刻度)
  • 颜色:浅灰 = 原始 loss(每步都有波动),红色 = 滑动窗口平滑
  • 你该看什么:loss 是否整体呈下降趋势?平滑曲线是否单调递减?
  • 理想情况:loss 从 ~10 起步(vocab=256 的随机初始化水平),逐渐下降到 8-9 左右
  • 异常指示:loss 不降反升 → 学习率太大;loss 完全平 → 学习率太小或数据有问题

右上 (b):学习率调度

  • 图类型:折线图
  • X 轴:step,Y 轴:LR 值(线性刻度)
  • 颜色:蓝色
  • 你该看什么:是否先平(warmup 短)后下降(cosine 衰减)?
  • 理想情况:从峰值开始余弦衰减到 min_lr_ratio * peak_lr
  • 异常指示:LR 不变化 → 调度器配置错误

左下 (c):梯度范数

  • 图类型:折线图 + 水平参考线
  • X 轴:step,Y 轴:grad_norm(线性刻度)
  • 颜色:橙色 = clip 前的梯度总范数 (clip_grad_norm_ 的返回值),红色虚线 = grad_clip 阈值
  • 你该看什么 :橙色线是否随训练进行逐步下降并趋近红色 clip 线?
  • 理想情况:训练初期 grad_norm 远大于 clip 阈值(被强制裁剪到 1.0),随 loss 下降,grad_norm 逐步回落到 clip 线附近甚至以下------这说明模型逐渐进入稳定区
  • 异常指示:训练后期 grad_norm 仍持续远高于 clip 线、毫无回落趋势 → 学习率太大或损失发散

关键说明 :torch.nn.utils.clip_grad_norm_ 返回的是裁剪之前的梯度总范数。橙色线高于红色线不代表异常,恰恰说明 clip 机制在发挥作用------它把每一步的梯度都强制缩放到阈值以内,而图中记录的是"如果不裁剪会有多大"。

右下 (d):已处理 token 数

  • 图类型:折线图
  • X 轴:step,Y 轴:累积 token 数(线性刻度)
  • 颜色:紫色
  • 你该看什么:是否是完美的线性增长?
  • 理想情况:严格线性(每步处理 micro_bs * seq_len * grad_accum 个 token)
  • 异常指示:非线性 → grad_accum 或 curriculum 切换导致的预期变化

调节建议

  • 想看 loss 明显下降 → 把步数调到 50+,学习率调到 2e-3
  • 想看梯度裁剪效果 → 把学习率调到 5e-3(大 LR 导致大梯度)
  • 想看平滑效果差异 → micro_batch_size 调到 1(单样本梯度噪声大)

为什么重要

这是训练系统的"仪表盘"。生产中每个训练 run 都需要实时监控这四个指标。如果 loss 不下降、梯度爆炸、LR 异常,都需要第一时间发现并干预。这个 Tab 是所有其他训练相关 Tab 的基础------它验证了训练管线的端到端正确性。


Tab 2: LR 调度曲线

目的

对比 Cosine with Warmup 和 WSD(Warmup-Stable-Decay)两种学习率调度的形态差异,验证 cosine_with_warmup() 与 wsd_schedule() 的实现正确性。

背景概念

学习率调度是训练中最重要的超参数之一。不同的调度策略适用于不同场景:

  • Cosine:经典选择,训练全程平滑衰减,适合预训练
  • WSD:中间有一段平台期保持峰值 LR,适合 RLHF 等需要稳定学习率的场景

代码位置:optim/lr_scheduler.py:11 cosine_with_warmup() 和 :40 wsd_schedule()

UI 组件与参数影响

参数 范围 默认 调节效果
总步数 50-1000 200 增大 → 曲线更"舒展",衰减更平缓
warmup 比例 0.01-0.2 0.05 增大 → warmup 阶段更长,起始更平缓
min_lr_ratio 0.0-0.5 0.1 增大 → 最终 LR 更高,衰减幅度更小

输出图解读

布局:2×1 上下排列

上图 (a):LR 调度曲线

  • 图类型:双折线图 + 两条参考线
  • X 轴:step,Y 轴:LR 乘子(线性刻度,0~1)
  • 颜色:蓝色 = Cosine,红色 = WSD,绿色虚线 = warmup 结束点,灰色点线 = min_lr_ratio
  • 你该看什么:Cosine 在 warmup 后立刻开始衰减;WSD 在 warmup 后保持平台期,最后才线性下降
  • 理想情况:两者都从 0 线性上升到 1.0(warmup),最终值都是 min_lr_ratio
  • 异常指示:warmup 起点不是 0 → 调度 bug;最终值不等于 min_lr_ratio → 公式错误

下图 (b):学习率变化率(差分)

  • 图类型:双折线图
  • X 轴:step,Y 轴:ΔLR(一阶差分)
  • 颜色:蓝色 = Cosine 变化率,红色 = WSD 变化率
  • 你该看什么:Cosine 的变化率先负后更负(加速度为负);WSD 平台期变化率为 0,衰减期为常数
  • 理想情况:WSD 衰减期是水平直线(线性衰减 = 恒定变化率)
  • 异常指示:平台期非零 → WSD 实现错误

调节建议

  • 想看 WSD 平台期的效果 → warmup 调到 0.01,总步数调到 500(平台期会很明显)
  • 想看极端情况(无 warmup)→ warmup 调到 0.01(几乎没有 warmup)
  • 想看 min_lr_ratio=0 的效果 → min_lr_ratio 调到 0(最终归零)

为什么重要

学习率调度直接决定训练的收敛速度和最终质量。Cosine 适合"越训越精细"的预训练;WSD 适合"先充分学习再慢慢收"的场景(如 RLHF 的奖励模型训练)。理解两种调度的形态差异,有助于为不同训练任务选择合适的策略。


Tab 3: Context Curriculum

目的

可视化 ContextCurriculum 的四阶段渐进式上下文扩展,验证 ContextCurriculum.stage_for_step() 和 is_transition() 的正确性,以及 step_budget() 的步数分配。

背景概念

K3 达到 1M token 窗口不是一步到位的,而是通过四阶段课程:8K → 64K → 256K → 1M。前两个阶段在预训练期,后两个在 cooldown 期。这样设计的好处:

  1. 短序列计算快,前期大部分预算用短序列 → 经济
  2. 逐步加长让模型渐进适应长程依赖
  3. K3 是 NoPE(无位置编码),阶段切换不需要重新调频率基

代码位置:data/curriculum.py:38 ContextCurriculum 类

UI 组件与参数影响

参数 范围 默认 调节效果
各阶段 seq_len 逗号分隔整数 32,64,128,256 改每个阶段的上下文长度
各阶段结束比例 逗号分隔小数 0.4,0.7,0.9,1.0 改各阶段占总训练的比例
总步数 100-1000 200 增大 → 阶段切换更"平滑"
max_tokens_per_rank 32-256 64 减小 → 小阶段也需要高 cp_degree

输出图解读

布局:1×2 左右排列

左图 (a):seq_len 随阶段递增

  • 图类型:阶梯图(step plot)+ 垂直虚线
  • X 轴:step,Y 轴:序列长度(线性刻度)
  • 颜色:蓝色阶梯 = seq_len,红色虚线 = 阶段切换点
  • 你该看什么:每个阶段的 seq_len 是否正确?切换点是否在 fractions 指定的位置?
  • 理想情况:阶梯状上升,每个阶段高度对应该阶段的 seq_len
  • 异常指示:切换点位置不对 → fractions 解析错误;阶梯数不对 → stages 数量错

右图 (b):各阶段步数预算

  • 图类型:柱状图
  • X 轴:各阶段的上下文长度,Y 轴:训练步数(线性刻度)
  • 颜色:紫色柱
  • 你该看什么:短序列阶段的步数是否远多于长序列阶段?
  • 理想情况:左高右低的柱状图(短序列占绝大多数预算)------这是课程学习经济性的体现
  • 异常指示:所有柱子一样高 → 课程设置不合理(长序列太贵了)

调节建议

  • 想看 K3 真实的课程比例 → stages 设为 8,64,256,1024,fractions 设为 0.6,0.85,0.95,1.0
  • 想看两阶段简单课程 → stages 设为 32,64,fractions 设为 0.7,1.0
  • 想看 cp_degree 变化 → 把 max_tokens_per_rank 调到 32(更多阶段需要并行)

为什么重要

Context Curriculum 是 K3 能支撑 1M 上下文的关键工程技巧。不是从头到尾都用 1M 序列训练(那样太贵了),而是渐进式扩展。理解这个机制,有助于估算训练成本、规划显存分配、判断长程能力的形成时机。


Tab 4: 梯度累积

目的

验证梯度累积(gradient accumulation)的等价性:不同 grad_accum 值但有效批大小相同时,训练轨迹应该基本一致。这是生产中用小 GPU 模拟大 batch 训练的核心手段。

背景概念

梯度累积的原理:把一个大 batch 拆成 N 个 micro-batch,每个 micro-batch 前向+反向累积梯度,N 个之后再 step。只要总 token 数相同,优化器看到的梯度期望就相同。

有效批大小 = micro_batch_size × grad_accum × seq_len

代码位置:train/loop.py:117 train_step() 中的 for batch in batches 循环

UI 组件与参数影响

参数 范围 默认 调节效果
训练步数 5-40 20 增大 → 轨迹差异可能累积变大
随机种子 0-999 42 改变数据采样顺序
学习率 5e-4 ~ 3e-3 1e-3 增大 → 轨迹差异可能更明显
有效批大小 8-128 32 增大 → 梯度估计更准,但每步更慢

输出图解读

布局:单图折线对比

  • 图类型:多折线图(3 条线)
  • X 轴:step,Y 轴:loss(线性刻度)
  • 颜色:蓝色 = grad_accum=1,红色 = grad_accum=2,紫色 = grad_accum=4
  • 你该看什么:三条线是否大致重合?趋势是否一致?
  • 理想情况:三条线高度重合(差异 < 5%),因为有效批大小相同
  • 异常指示:差异很大(> 20%)→ 可能是 batch norm 或其他状态依赖导致

为什么会有小差异?

  1. 数据采样顺序不同(每个 micro-batch 是随机采样的)
  2. 梯度裁剪的时机不同(在累积后裁剪 vs 在每个 micro-batch 后裁剪)
  3. 数值精度的微小差异

调节建议

  • 想看最接近的结果 → 步数调小(10 步以内),有效批大小调大(64+)
  • 想看差异如何产生 → 步数调到 40,学习率调到 3e-3(大 LR 放大差异)
  • 验证 batch size 不变性 → 有效批大小固定,只变 grad_accum(本实验就是这样设计的)

为什么重要

梯度累积是分布式训练的基础概念。在实际生产中,单个 GPU 的显存往往不够装下大 batch,就用 grad_accum 来模拟。这个 Tab 直观验证了"用时间换 batch size"的等价性------只要总 token 数相同,训练效果就基本一样。


Tab 5: Checkpoint 验证

目的

验证 checkpoint 的 round-trip 一致性:保存后再加载,模型权重、优化器状态、训练步数、best_loss 等都完全一致。这是训练容错的基础------中断了必须能从断点恢复。

背景概念

一个完整的 checkpoint 应该包含:

  1. 模型权重(model.state_dict())
  2. 优化器状态(optimizer.state_dict())
  3. 训练状态(step、tokens、best_loss、curriculum 阶段等)

恢复时要把这三部分都加载回来,才能保证训练无缝继续。

代码位置:train/loop.py:250 save() 和 :263 load()

UI 组件与参数影响

参数 范围 默认 调节效果
预训练步数 5-40 20 增大 → checkpoint 更大,但不影响一致性
随机种子 0-999 42 改变初始状态

输出图解读

布局:单表格(5 行 × 4 列)

  • 图类型:表格(matplotlib table)
  • 列:项目 / 保存前 / 加载后 / 结果
  • 行:训练步数 / best_loss / 权重最大误差 / checkpoint 大小 / 参数张量数
  • 你该看什么:每一行的"结果"列是否都是 PASS?
  • 理想情况:全部 PASS,权重最大误差 = 0.00e+00(完全一致)
  • 异常指示:权重有误差 → 保存/加载逻辑有 bug;步数不一致 → TrainState 没保存全

为什么重要

训练动辄几天甚至几周,中途断电、宕机、OOM 都是常事。如果 checkpoint 不能正确恢复,所有之前的计算都白费了。这个 Tab 验证的是训练系统最基本的可靠性保证------save 之后 load,必须 byte-identical。


Tab 6: 评估 (eval_loss / ppl)

目的

展示训练前后评估指标的变化:eval_loss 下降、eval_ppl 下降,并验证 ppl = exp(loss) 的数学关系。

背景概念

**Perplexity(困惑度)**是语言模型最常用的评估指标。它表示模型对下一个 token 的"平均困惑程度"------ppl 越低,模型预测越准。

数学关系:ppl = exp(cross_entropy_loss)

直觉理解:ppl=100 意味着模型平均在 100 个候选 token 中"犹豫";ppl=10 意味着在 10 个中犹豫;ppl=1 就是完美预测。

代码位置:train/loop.py:235 evaluate()

UI 组件与参数影响

参数 范围 默认 调节效果
训练步数 5-40 15 增大 → loss 下降更多,ppl 变化更明显
随机种子 0-999 42 改变初始状态和数据
micro_batch_size 1-8 4 增大 → 评估更稳定

输出图解读

布局:1×2 左右柱状图

左图 (a):eval_loss 变化

  • 图类型:柱状图(2 根柱:训练前 / 训练后)
  • X 轴:类别,Y 轴:eval_loss(线性刻度)
  • 颜色:红色 = 训练前,绿色 = 训练后
  • 你该看什么:训练后的柱子是否比训练前矮?(loss 下降了多少?)
  • 理想情况:训练后 loss 明显低于训练前
  • 异常指示:训练后 loss 更高 → 学习率太大或训练不稳定

右图 (b):eval_ppl 变化

  • 图类型:柱状图(2 根柱:训练前 / 训练后)
  • X 轴:类别,Y 轴:eval_ppl(线性刻度)
  • 颜色:红色 = 训练前,绿色 = 训练后
  • 你该看什么:ppl 的下降幅度(通常比 loss 的绝对值变化大很多,因为是指数关系)
  • 理想情况:训练后 ppl 明显下降,且 exp(eval_loss) ≈ eval_ppl
  • 异常指示:ppl 和 loss 不满足 exp 关系 → 计算有 bug

调节建议

  • 想看明显的提升 → 步数调到 30+,学习率在总览 Tab 调到 2e-3
  • 想看 ppl 和 loss 的数量级差异 → loss 5.0 → ppl ~148,loss 4.0 → ppl ~55

为什么重要

评估是判断训练是否有效的唯一标准。Loss 下降只是训练集上的表现,eval_loss 和 ppl 才反映泛化能力。这个 Tab 展示了训练→评估的完整闭环,也直观解释了 ppl 与 cross-entropy loss 的指数关系。


Tab 7: 设备与 Grad-Checkpoint

目的

展示 resolve_device() 的设备选择策略,以及 gradient checkpointing 的显存-速度权衡(用计算时间换显存空间)。

背景概念

resolve_device:

  • 显式指定("cpu"/"cuda")就用指定的
  • auto 模式:如果 CUDA 可用且显存充足(>1.5GiB)就用 CUDA,否则回退 CPU

Gradient Checkpointing:

  • 前向传播时不保存中间激活
  • 反向传播时重新计算(recompute)这些激活
  • 代价:速度变慢(~20-30%)
  • 收益:显存减少(~40-50%)

代码位置:train/loop.py:46 resolve_device() 和 :84 set_gradient_checkpointing()

设计思路

  • 左表 :展示 resolve_device 的三种分支行为------显式 CPU、auto 自动选择、CUDA 可用性检测,让读者一眼看清设备选择策略是纯函数式的(输入 → 输出可预测)。
  • 右图 :用「无 GC = 100% 基准」对比「有 GC 时的显存/速度」,直观展示用时间换空间 这一经典权衡。GC 的核心思想是反向传播时重新计算激活值而非保存它们,所以显存能省 ~40%,但需要多算一次前向 → 速度慢 ~25%。

UI 组件与参数影响

参数 范围 默认 调节效果
对比训练步数 5-30 15 无参数,点击按钮直接运行
随机种子 0-999 42 (仅保留接口,不影响设备选择)

输出图解读

布局:1×2 左右排列

左图 (a):resolve_device 设备选择策略

  • 图类型:表格(3 行 × 4 列)
  • 列:请求 / 传入值 / 实际设备 / 说明
  • 行:显式 CPU / auto 模式 / CUDA 可用
  • 你该看什么:auto 模式选择了什么设备?你的环境有没有 CUDA?
  • 理想情况:显式 CPU → cpu;auto → 按环境选择(有 CUDA 就用 CUDA)
  • 异常指示:显式 "cpu" 返回了 cuda → 逻辑错误

右图 (b):Gradient Checkpointing 显存-速度权衡

  • 图类型:分组柱状图(2 组 × 2 柱)
  • X 轴:无 GC / 有 GC,Y 轴:相对值 (%)
  • 颜色:红色 = 显存占用,蓝色 = 速度
  • 你该看什么:开启 GC 后显存减少了多少?速度降低了多少?
  • 理想情况:显存降到 ~55%,速度降到 ~78%(典型 trade-off)
    • 显存 100 → 60(明确省 40%)
    • 速度 100 → 75(明确慢 25%)
  • 异常指示:显存反而增加 → GC 实现有 bug

注意:右图是示意图(基于常见 Transformer 的经验值),不是本 nano 模型的实测数据。实际数值取决于模型大小、序列长度、激活类型等。

为什么重要

设备选择和显存管理是训练工程的入门第一课。Gradient Checkpointing 是"显存不够怎么办"的标准回答------几乎所有大模型训练都会开。理解这个 trade-off,有助于在给定硬件下选择最大的模型和最长的序列。


Tab 8: RunningMean 滑动均值

目的

可视化 RunningMean 的滑动窗口平滑效果:窗口越大,曲线越平滑但延迟越大;窗口越小,越贴近原始值但噪声多。

背景概念

训练 loss 每一步都在波动(因为每个 batch 不同),直接看原始 loss 很难判断趋势。滑动窗口均值把最近 N 个值取平均,抑制噪声、凸显趋势。

数学定义:

复制代码
running_mean[t] = mean({loss[t-W+1], ..., loss[t]})

其中 W 是窗口大小。

代码位置:train/metrics.py:19 RunningMean 类

UI 组件与参数影响

参数 范围 默认 调节效果
窗口大小 1-50 10 增大 → 曲线更平滑,但滞后更明显
噪声强度 0.1-1.0 0.3 增大 → 原始值波动更大,平滑效果更明显
数据点数 20-200 100 增大 → 曲线更长
随机种子 0-999 42 改变噪声模式

输出图解读

布局:单图双折线

  • 图类型:双折线图
  • X 轴:step,Y 轴:值(线性刻度)
  • 颜色:浅灰色 = 原始值(带噪),红色 = 滑动均值
  • 蓝色虚线标注窗口填满点(step=window 时窗口第一次被填满)
  • 你该看什么:红色线是否滤掉了大部分噪声?红色线比灰色线"滞后"多少?
  • 理想情况:红色线趋势清晰(单调递减),噪声方差明显降低
  • 异常指示:红色线和灰色线完全重合 → 窗口=1 或实现错误

调节建议

  • 想看极端平滑 → 窗口调到 40+,噪声调到 0.8
  • 想看几乎不平滑 → 窗口调到 1-2
  • 想看滞后效应 → 窗口调到 30,观察波峰波谷的偏移

为什么重要

RunningMean 是训练监控中最基础也最常用的工具。没有平滑的 loss 曲线全是噪声,根本看不出趋势。窗口大小的选择也是一门艺术------太小了噪声多,太大了反应迟钝。实际训练中常用 10-100 的窗口,取决于 log 频率。


Tab 9: MetricLog 记录

目的

展示 MetricLog 的完整功能:记录指标、系列提取、滑动平滑、JSONL 文件持久化。验证 log() / series() / smoothed() 的实现正确性。

背景概念

MetricLog 是训练日志的核心数据结构,做两件事:

  1. 内存历史 :所有记录存在 history 列表里,供实时查询和绘图
  2. 文件持久化:可选写入 JSONL 文件,供训练后分析

每条记录是一个 dict,至少包含 wall(相对时间戳)和其他自定义指标。

代码位置:train/metrics.py:46 MetricLog 类

设计思路

设计思路 : 这个 Tab 演示的是训练日志系统的数据结构设计,回答三个问题:

  1. 怎么记? ------MetricLog.log(step=..., loss=..., lr=..., grad_norm=...) 按 step 追加字典记录,内存中保留完整历史(ml.history)。
  2. 怎么取? ------series(key) 提取任意字段的时间序列,smoothed(key, window) 返回滑动均值(内部用 RunningMean)。这是把「存储」与「统计」解耦------存的是原始值,平滑是后处理。
  3. 怎么持久化?------支持可选的 JSONL 路径,每条 log 同时 append 到磁盘。图里用临时文件验证「写 5 条 → 文件确实是 5 行」,证明 I/O 路径通畅。

为什么这样设计:

  • 双图联动 :上图对比「原始 loss vs 平滑 loss」展示后处理能力;下图把 lr(左轴)和 grad_norm(右轴)画在同一 x 轴上,因为这两个指标量纲差 1000 倍,双轴才能同图呈现。
  • JSONL 而非二进制 :文本行式存储便于 tail -f 实时查看、grep 过滤、Pandas 直接读,且崩溃时已写入的行不丢失。
  • 不在 demo 中真正训练:为了把「日志系统本身」从训练循环剥离,用确定性公式(指数衰减 + 噪声)生成假数据,10ms 出图。

UI 组件与参数影响

参数 范围 默认 调节效果
总步数 20-200 50 增大 → 曲线更长
log_every 1-10 2 增大 → 日志记录更稀疏
随机种子 0-999 42 改变随机数生成

输出图解读

布局:2×1 上下排列 + 双轴

上图 (a):loss 曲线与平滑

  • 图类型:双折线图
  • X 轴:step,Y 轴:loss(线性刻度)
  • 颜色:浅灰色 = 原始 loss,红色 = smoothed(窗口 5)
  • 你该看什么:smoothed 曲线是否比原始曲线更平滑?
  • 理想情况:两条线趋势一致,平滑曲线噪声更小
  • 异常指示:smoothed 和原始完全一样 → 窗口=1 或实现错误

下图 (b):LR 与 grad_norm 双轴

  • 图类型:双 Y 轴折线图
  • 左 Y 轴:学习率(蓝色线),右 Y 轴:grad_norm(橙色线)
  • 你该看什么:LR 和 grad_norm 是否各自按预期变化?
  • 理想情况:LR 单调下降,grad_norm 在一个范围内波动
  • 异常指示:LR 不下降 → 调度器配置错误

为什么重要

MetricLog 是训练系统的"黑匣子"------所有指标都通过它记录和查询。支持内存 + 文件双模式,既能实时监控也能事后分析。series() 和 smoothed() 方法提供了便捷的数据提取和平滑接口,是所有训练可视化的基础。


Tab 10: MoE 负载均衡

目的

观察训练过程中 MoE 专家负载均衡指标的变化,验证 Quantile Balancing(分位数平衡)是否生效。这是 K3 LatentMoE 的关键稳定性机制(论文 §2.3.3)。

背景概念

MoE(Mixture of Experts)有一个常见问题:训练初期某些专家被频繁选中,另一些几乎不被选(负载不均衡)。长期不均衡会导致"富者愈富"------被选中多的专家梯度多、进步快、更容易被选中。

Quantile Balancing 的解法:给 router 的输出加一个可学习的 bias,用分位数法让每个专家被选中的概率趋近均匀(top_k / n_experts)。bias 延迟一步更新(用已消费 batch 的直方图),保证因果性。

代码位置:modules/router_qb.py:301 load_balance_stats(),train/metrics.py:78 expert_balance()

设计思路

设计思路 : K3 的 LatentMoE 用 Quantile Balancing (路由 bias 延迟一步更新)代替传统 auxiliary loss。这个 Tab 用三个互补指标监测均衡效果:

指标 公式 理想值 含义
max/mean max(load) / mean(load) → 1.0 最热专家比平均热多少倍,>1.5 视为偏载
mean_cv std(load) / mean(load) → 0 变异系数,刻画整体离散程度
max/min max(load) / min(load) → 1.0 最热 vs 最冷的极端差距

为什么要三个指标而不是一个:

  • max/mean 对单点过载敏感但不看分布形状;
  • CV 是分布层面的整体度量,但极端值会被平均稀释;
  • max/min 抓尾部专家饿死(load→0 时 ratio→∞)。
  • 三者结合才能区分「一个专家很热」「全部专家都不均」「少数专家被饿死」三种典型失衡模式。

左图单画 max/mean 并标理想线 1.0 ------这是 K3 论文里的关键指标;右图把 CV 和 max/min 放一起 ------这两个都是「越小越好」,共享 y 轴。整个训练实时跑 30 步(约 10 秒),让读者观察随着 router bias 更新,三条曲线如何收敛。

UI 组件与参数影响

参数 范围 默认 调节效果
训练步数 10-60 30 增大 → 负载均衡效果更明显
随机种子 0-999 42 改变初始状态
micro_batch_size 2-8 4 增大 → 每步样本多,负载统计更准
top_k 1-4 2 增大 → 理想 max/mean 更低(更多专家被激活)

输出图解读

布局:1×2 左右排列

左图 (a):max/mean 比值

  • 图类型:折线图 + 水平参考线
  • X 轴:step,Y 轴:max / mean(线性刻度)
  • 颜色:红色线 = max/mean,绿色虚线 = 理想值 1.0
  • 你该看什么 :红线是否围绕一个远低于初始值的水平波动?是否有剧烈上冲?
  • 理想情况 :从初始高点(1.5-1.6)快速回落到 1.2~1.4 区间并在该区间内小幅波动 ;4 专家 / top_k=2 / 短序列的 nano 配置下,由于每步 token 数少、统计噪声大,无法收敛到 1.0
  • 异常指示 :红线持续上升或长期 > 2.0 → Quantile Balancing 失效或学习率过大

右图 (b):CV 与 max/min ratio

  • 图类型:双折线图
  • X 轴:step,Y 轴:值(线性刻度)
  • 颜色:蓝色 = CV(变异系数),橙色虚线 = max/min ratio
  • 你该看什么 :CV 是否稳定在低位 (< 0.3)?max/min 是否没有持续发散?
  • 理想情况 :CV 快速降到 0.1 并保持;max/min ratio 由于分母(min)很小、对噪声极敏感,会在 1.5~~2.5 之间剧烈波动 ,这是 nano 规模下的正常现象,不要求它单调下降
  • 异常指示:CV 持续 > 0.5 → 路由严重倾斜;max/min ratio 持续 > 5 → 有专家完全没被选中

关键说明 :该 demo 用的是 4 专家 / top_k=2 的 nano 配置,每步只有 micro_batch × seq_len ≈ 几千 个 token 流入路由,统计涨落巨大;且 Quantile Balancing 是滞后一步 的偏置更新,30 步训练只够它"初步纠正"严重倾斜,无法达到渐近均衡。看 QB 是否生效,要看 CV 是否很快从高位降到低位并保持,而不是看它是否单调收敛到 0。

调节建议

  • 想看 QB 的完整收敛过程 → 步数调到 50+,top_k 调到 1(top-1 最难均衡)
  • 想看 top_k 对均衡的影响 → top_k 调到 4(更多专家被激活,天然更均衡)
  • 想看初始不均衡 → 步数调到 5(初始阶段比值最高)

为什么重要

负载均衡是 MoE 训练的生命线。如果不均衡,大部分专家学不到东西,等于白花钱。Quantile Balancing 是 K3 的关键创新之一------它用延迟一步的分位数直方图法,在不增加计算开销的情况下实现了专家负载均衡。这个 Tab 让你直观看到 QB 是怎么生效的。


Tab 11: KDA alpha 衰减

目的

观察训练过程中 KDA alpha 衰减因子的分布变化,验证 Eq. 5 的约束:alpha 始终在 (exp(g_min), 1) 范围内。

背景概念

KDA(Kimi Delta Attention)的核心是一个可学习的衰减因子 alpha,控制"保留多少旧状态"。alpha 太接近 1 → 状态更新太慢(记不住新东西);alpha 太接近 0 → 旧信息太快被遗忘。

Eq. 5 用 alpha = exp(g_min * sigmoid(A * exp(z))) 的参数化方式,天然保证 alpha 有界:

  • 当 z → +∞ 时,alpha → exp(g_min)(下界,通常 ~0.0067)
  • 当 z → -∞ 时,alpha → 1.0(上界)

代码位置:train/metrics.py:99 decay_stats(),modules/kda.py 中的 Eq. 5 实现

设计思路

设计思路 : KDA(Kimi Delta Attention)的状态更新是 S ← α·S + δ(k, v),其中 α = exp(g) 是衰减因子,由可学习的标量 g 经 exp 变换得到。

Eq. 5 的约束 :exp(g_min) < α < 1.0

  • 下界 exp(g_min):防止 α → 0(状态被完全清空,丢失所有历史,等价于窗口=1 的注意力);
  • 上界 1.0:防止 α > 1(状态累加爆炸,相当于无衰减的累加器)。

为什么用带状图(fill_between)而不是单线 : KDA 每层、每个 head 都有独立的 g,因此每个 step 的 α 不是一个数而是一个分布。带状图:

  • 上沿 = α_max(最接近 1 的通道,记忆最强)
  • 下沿 = α_min(最接近下界的通道,遗忘最快)
  • 中间线 = α_mean(典型行为)

为什么画两条虚线 :红虚线 exp(g_min) 是硬下界 (由 g_min clamp 保证),绿虚线 1.0 是硬上界 (由 exp(g) ≤ 1 ⟺ g ≤ 0 保证)。填充区域必须永远夹在两条虚线之间,一旦越界说明实现有 bug。

这个 Tab 本质上是「不变式可视化」 ------不是看 α 怎么变化,而是验证整个训练过程中不变式始终成立。

UI 组件与参数影响

参数 范围 默认 调节效果
训练步数 10-60 30 增大 → alpha 分布可能有更多变化
随机种子 0-999 42 改变初始 alpha 分布
micro_batch_size 2-8 4 增大 → 训练更稳定

输出图解读

布局:单图 + 填充区域

  • 图类型:填充面积图 + 中线
  • X 轴:step,Y 轴:alpha 值(线性刻度)
  • 紫色填充 = alpha 的 min ~ max 范围,紫色实线 = alpha_mean
  • 红色虚线 = 下界 exp(g_min),绿色虚线 = 上界 1.0
  • 你该看什么:alpha 的整体范围是否在上下界之间?mean 是否稳定?
  • 理想情况:所有 alpha 都严格在 (exp(g_min), 1) 之间,不触碰边界
  • 异常指示:alpha 贴近上界或下界 → 可能训练不稳定或 g_min 设置不合理

注意:nano 模型(30 步)可能 alpha 变化不明显,因为 KDA 的 gate 是低秩初始化的、需要更多步数来学习。真实 K3 模型在百万步后 alpha 会有更丰富的分布。

调节建议

  • 想看 alpha 是否真的有界 → 确认两条虚线之间包含所有填充区域
  • 想看更多变化 → 步数调到 60,LR 调到 3e-3(加速学习)
  • 想看 g_min 的影响 → 可以在代码中修改 g_min 值再运行

为什么重要

alpha 的有界性是 KDA 稳定性的数学保证。如果 alpha 可以 >1,状态矩阵会指数爆炸;如果 alpha 可以 =0,状态会立即归零。Eq. 5 的精妙之处在于用 sigmoid + exp 的组合天然约束了范围,不需要额外的 clip 或正则。这个 Tab 验证了这个关键的数学性质在实际训练中确实成立。


Tab 12: 无模型回退

目的

验证 expert_balance() 和 decay_stats() 在模型不含对应模块时的优雅降级行为------返回空 dict 而不报错。

背景概念

K3 的模块化设计意味着某些组件可能在特定配置下被禁用(例如纯文本模型禁用视觉塔,或 baseline 模型禁用 MoE)。指标函数需要能处理"目标模块不存在"的情况,不能因为没有 MoE 层就让训练日志崩溃。

代码位置:train/metrics.py:78 expert_balance() 和 :99 decay_stats()

设计思路

设计思路 : expert_balance() 和 decay_stats() 是给任意 模型用的诊断函数,不能只服务 K3 完整模型。它们必须在以下场景不报错:

  • 标准 dense 模型(没有 router)调用 expert_balance()
  • MHA-based 模型(没有 KDA 层)调用 decay_stats()
  • 早期调试时,模型只搭了 Embedding + LayerNorm

实现策略 :约定返回空 dict {},由调用方(训练循环)判断:

复制代码
bal = expert_balance(model)
if bal:  # 空 dict 为 falsy
    metrics.log(**bal)

这样训练日志自动跳过 不存在的指标,而不是抛 AttributeError 或写 NaN。

为什么用空 dict 而不是 None 或抛异常:

  • None :调用方要写 if bal is not None + bal.update(...),多一次类型判断;
  • 抛异常:强制调用方 try/except,把「模型架构差异」当作「错误」处理,语义错误;
  • 空 dict :dict 类型一致,调用方可以 **bal 直接解包(空 dict 解包为零参数),if bal: 一句判断,且 len(bal) 可以问「收集到了几个指标」。

为什么这个 Tab 用一个 FakeModel 而不是真的 dense 模型:

  • 真实 K3 模型默认带 KDA + MoE,构造一个「没有 KDA/MoE 的 K3」要改 config,绕过多个 assert;
  • FakeModel 只实现 modules() 和 model.routers() 两个被访问的接口,精准命中被测函数的 duck-typing 边界,测试更聚焦、运行更快(毫秒级)。

整个 Tab 演示的是「防御性编程 + 鸭子类型」的设计哲学:诊断函数不应该假设模型一定包含某个子模块,而应该查询、容错、优雅降级。这是 K3 这套训练框架能被复用到 dense 模型、MoE-only 模型、Linear-Attention-only 模型的关键。

UI 组件与参数影响

无参数,点击按钮直接运行。

输出图解读

布局:单表格(2 行 × 3 列)

  • 图类型:表格
  • 列:函数 / 返回值 / 说明
  • 行:expert_balance(无router) / decay_stats(无KDA层)
  • 你该看什么:两个函数的返回值是否都是空 dict {}?
  • 理想情况:都返回空 dict,程序不报错
  • 异常指示:抛出 AttributeError 或 KeyError → 降级逻辑有 bug

为什么重要

这是防御式编程的基本要求。训练系统有几十种指标,如果每个指标都假设"模型一定有 X 模块",那切换配置时就会到处崩。优雅降级(graceful degradation)保证了训练日志系统的鲁棒性------缺什么模块就不记什么指标,不会因为一个模块被禁用就让整个训练流程崩溃。



0xFF 参考