【轻量化复刻大模型 / KIMI K3】K3 训练模块交互式演示
【轻量化复刻大模型 / 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 实现思路
核心设计原则:复用优先,零重复代码。
- plot 脚本独立可运行:每个
fig_*()函数返回(fig, text)元组,if __name__ == "__main__"保存到assets/ - Gradio 只做 UI 组装:
gradio_train_demo.py直接from plot_train_loop import fig_*,不实现任何绘图逻辑 - demo 脚本可 import:
demo_pretrain_e2e.py提取build_nano_config()/build_nano_dataset()/run_training()三个可复用函数,原有main()的 print 输出保持不变(向后兼容) - 深色主题:与 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 总体公式
# 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
公式:
# 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 负载均衡
公式:
# 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 衰减因子有界性
公式:
# 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 训练步包含:
- 采样一个 batch(PackedDataset)
- 前向传播计算 cross-entropy loss
- 反向传播计算梯度
- 梯度裁剪(防止梯度爆炸)
- 按 LR 调度更新学习率
- 优化器 step 更新参数
- 记录指标并打印
代码位置: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 期。这样设计的好处:
- 短序列计算快,前期大部分预算用短序列 → 经济
- 逐步加长让模型渐进适应长程依赖
- 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 或其他状态依赖导致
为什么会有小差异?
- 数据采样顺序不同(每个 micro-batch 是随机采样的)
- 梯度裁剪的时机不同(在累积后裁剪 vs 在每个 micro-batch 后裁剪)
- 数值精度的微小差异
调节建议
- 想看最接近的结果 → 步数调小(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 应该包含:
- 模型权重(
model.state_dict()) - 优化器状态(
optimizer.state_dict()) - 训练状态(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 是训练日志的核心数据结构,做两件事:
- 内存历史:所有记录存在
history列表里,供实时查询和绘图 - 文件持久化:可选写入 JSONL 文件,供训练后分析
每条记录是一个 dict,至少包含 wall(相对时间戳)和其他自定义指标。
代码位置:train/metrics.py:46 MetricLog 类
设计思路
设计思路: 这个 Tab 演示的是训练日志系统的数据结构设计,回答三个问题:
- 怎么记?——
MetricLog.log(step=..., loss=..., lr=..., grad_norm=...)按 step 追加字典记录,内存中保留完整历史(ml.history)。 - 怎么取?——
series(key)提取任意字段的时间序列,smoothed(key, window)返回滑动均值(内部用RunningMean)。这是把「存储」与「统计」解耦——存的是原始值,平滑是后处理。 - 怎么持久化?——支持可选的 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)保证了训练日志系统的鲁棒性——缺什么模块就不记什么指标,不会因为一个模块被禁用就让整个训练流程崩溃。

浙公网安备 33010602011771号