MiniMind 互动知识平台
从 0 到 1 亲手训练一个 64M 参数的大语言模型:约 3 元钱、2 小时,覆盖 预训练 → SFT → LoRA → DPO → PPO / GRPO / CISPO → Agent RL → 蒸馏 全链路。
「大道至简」—— 所有核心算法均以 PyTorch 原生实现,不依赖 transformers / trl / peft 的高层封装。
项目总览
先花 3 分钟,建立对 MiniMind 的整体认知。
它是什么 · 一句话读懂
MiniMind 是一个开源的大语言模型全阶段复现项目 + 系统性教程:它把 ChatGPT 背后那套「预训练 → 指令微调 → 偏好对齐 → 强化学习」的完整工业流程,压缩成一个普通人用单张消费级显卡、一顿饭钱就能跑通的极简实现。
它不是调用框架 API 的"套壳"项目——模型结构(RMSNorm / RoPE / GQA / SwiGLU / MoE)、Tokenizer、LoRA、DPO、PPO、GRPO、CISPO、Agent RL、知识蒸馏,全部从 0 用原生 PyTorch 手写,代码总量小到可以逐行读完。
为什么值得亲手学一遍
🎯 打开黑盒,而不是停留在"会用"。绝大多数学习路径止步于用 LoRA 给现成大模型做点微调——作者的比喻是"教牛顿用智能手机,有趣但偏离了物理本质"。MiniMind 让你从训练层面(而非推理层面)理解 LLM。
🧩 拒绝高层抽象。transformers / trl / peft 十几行代码就能完成全流程,但也把开发者与底层隔离开。MiniMind 的每个模块都短小、可读、可改。
💸 门槛低到离谱。最小版本只有 26M 参数,单卡 RTX 3090 约 2 小时、3 元钱即可完成 Zero 模型全流程;CPU 也能跑 LoRA 微调。
🌱 生态完整。兼容 transformers / llama.cpp / vllm / ollama / Llama-Factory,还有视觉版 MiniMind-V、全双工 Omni 版、扩散语言模型 dLM、线性注意力版等姊妹实验。
模型家族与版本演进
| 模型 | 参数量 | 结构 | 层数 / 维度 | 发布 | 状态 |
|---|---|---|---|---|---|
| minimind-3 | 64M | Dense | 8 层 / 768 | 2026.04 | 当前主线 ✅ |
| minimind-3-moe | 198M-A64M | MoE(4 专家 / top-1) | 8 层 / 768 | 2026.04 | 当前主线 ✅ |
| minimind2-small | 26M | Dense | 8 层 / 512 | 2025.04 | 历史(体积最小) |
| minimind2 | 104M | Dense | 16 层 / 768 | 2025.04 | 历史 |
| minimind2-moe | 145M | MoE | 8 层 / 640 | 2025.04 | 历史 |
| minimind-v1 系列 | 26M ~ 108M | Dense / MoE | — | 2024.08-09 | 已停止维护 |
💡 198M-A64M 表示总参数 198M、每个 token 激活约 64M(4 专家取 top-1 路由)。
项目大事记
<|im_start|><|im_end|>。快速上手 · 手把手教程
五步走通全流程:环境 → 推理体验 → 下载数据 → 训练 → 对话测试。所有命令均来自官方 README。
克隆仓库并安装依赖
# 克隆仓库(浅克隆即可)
git clone --depth 1 https://github.com/jingyaogong/minimind
cd minimind && pip install -r requirements.txt -i https://mirrors.aliyun.com/pypi/simple
# 训练前务必确认 CUDA 可用(CPU / MPS 也能跑,但速度差异巨大)
python -c "import torch; print(torch.cuda.is_available())"参考环境:Python 3.10 + CUDA 12.2 + PyTorch。多卡用户可通过 torchrun --nproc_per_node N train_xxx.py 启动 DDP。
📦 主要依赖:torch(建议按官网命令单独安装)+ transformers 4.57.6 / datasets / flask / streamlit / swanlab / modelscope 等,requirements.txt 已锁定版本。
(可选)先下载官方权重,体验推理效果
# 方式1:ModelScope 下载(国内快) 方式2:git clone https://huggingface.co/jingyaogong/minimind-3
modelscope download --model gongjy/minimind-3 --local_dir ./minimind-3
# Transformers 格式推理 / 原生 torch 权重推理
python eval_llm.py --load_from ./minimind-3
python eval_llm.py --load_from ./model --weight full_sft
# 开启显式思考(Adaptive Thinking)
python eval_llm.py --load_from ./minimind-3 --open_thinking 1
# 也可以直接白嫖 ollama
ollama run jingyaogong/minimind-3想要 WebUI:cd scripts && streamlit run web_demo.py(需先把模型文件夹复制进 scripts/ 目录)。
下载训练数据,放入 ./dataset 目录
从 ModelScope 或 HuggingFace 下载。✨ 为快速复现推荐必选项,无需全部下载:
| 文件 | 体积 | 用途 |
|---|---|---|
| pretrain_t2t_mini.jsonl ✨ | 1.2GB | 轻量预训练(推荐 max_seq_len≈768) |
| sft_t2t_mini.jsonl ✨ | 1.6GB | 轻量 SFT,已混入 Tool Call 样本 |
| rlaif.jsonl ✨ | 24MB | PPO / GRPO / CISPO 强化学习 |
| pretrain_t2t.jsonl | 10GB | 主线完整预训练 |
| sft_t2t.jsonl | 14GB | 主线完整 SFT(含 Tool Call / 思考) |
| dpo.jsonl | 53MB | DPO 偏好数据(chosen / rejected) |
| agent_rl.jsonl / agent_rl_math.jsonl | 86MB / 18MB | 多轮 Tool-Use Agentic RL(含 gt 校验) |
两阶段必训:预训练 + 指令微调
cd trainer
# ① 预训练:让模型学会"高质量词语接龙"(无监督吸收知识)
python train_pretrain.py # 多卡: torchrun --nproc_per_node N train_pretrain.py
# ② 指令微调 SFT:学会多轮对话模板,成为"助手"
python train_full_sft.py
# 💡 所有脚本支持断点续训:中断后加 --from_resume 1 自动从 ./checkpoints 恢复
# 💡 训练可视化:任意脚本加 --use_wandb(默认对接 SwanLab,接口兼容)产出权重位于 out/:预训练得 pretrain_768.pth,SFT 得 full_sft_768.pth(768 为模型维度,MoE 自动追加 _moe 后缀)。
🔗 权重自动接力:train_full_sft.py 默认 --from_weight pretrain(LoRA 默认接 full_sft),无需手动搬运权重。所谓 Zero 模型,就是只用 mini 数据跑完这两步得到的最小可行对话模型(full_sft_zero_768.pth)。
测试你的模型
python eval_llm.py --weight full_sft🧠: 机器学习是人工智能的核心技术之一,通过算法让计算机从数据中学习规律,并持续改进预测或决策效果……
💬: 推荐一些中国的美食
🧠: 例如北京烤鸭、兰州拉面、四川火锅、广东早茶、小笼包和麻婆豆腐等,这些美食分别代表了不同地区的风味特点……
之后可继续可选阶段:LoRA 垂域微调 → DPO 偏好对齐 → GRPO / CISPO 强化学习 → Agent RL(工具调用)→ 知识蒸馏,详见第 06 章。
硬件要求与训练开销
下表为官方在单卡 RTX 3090(24GB,租价约 ¥1.3/h)上对 minimind-3 的实测估算(1 epoch):
| 阶段 | minimind-3 (64M) | minimind-3-moe (198M-A64M) |
|---|---|---|
| pretrain_t2t_mini | ≈1.21h / ¥1.57 | ≈1.69h / ¥2.20 |
| sft_t2t_mini | ≈1.10h / ¥1.43 | ≈1.54h / ¥2.00 |
| Zero 全流程合计 | ≈2.31h / ≈¥3.0 | ≈3.23h / ≈¥4.2 |
项目架构全景
整个仓库只有四个核心目录。点击任意文件,右侧查看它的职责说明。
这里是整个项目的"地图"。MiniMind 的设计哲学是极简:模型一个文件、数据集一个文件、每个训练阶段一个独立脚本,互不纠缠,适合逐个击破。
训练主线流程
一条从"原始文本"到"可用助手"的完整流水线(🔥 为 2026 新增):
模型结构精讲
一个标准、现代、教科书级的 Transformer Decoder。点击下方结构图中的每一块,查看它在 MiniMind 里的具体实现。
MiniMind-3 是一个 8 层、隐藏维 768 的 Decoder-Only Transformer,整体与 Qwen3 / Llama 系的"现代配方"一致:Pre-Norm + RMSNorm + SwiGLU + RoPE + GQA。点击每个模块看细节。
🔄 互动演示:词语接龙(下一 Token 预测)
预训练教给模型的核心能力就是"词语接龙":每一步模型输出词表中每个 token 的概率分布,采样一个拼回输入,再预测下一个,循环往复直到输出结束符。点击候选词,或点"按概率采样"体验(概率为模拟数据,仅演示机制):
对应源码:MiniMindForCausalLM.generate()——本演示就是它的简化版:logits → 温度/top-k/top-p → 采样 → 拼接 → 循环。
关键配置与设计取舍
class MiniMindConfig(PretrainedConfig):
model_type = "minimind"
def __init__(self, hidden_size=768, num_hidden_layers=8,
use_moe=False, **kwargs):
...
self.vocab_size = 6400
self.num_attention_heads = 8 # Q 头
self.num_key_value_heads = 4 # KV 头(GQA)
self.hidden_act = 'silu' # SwiGLU
self.intermediate_size = ceil(h*π/64)*64 # = 2432
self.max_position_embeddings = 32768
self.rope_theta = 1e6
self.tie_word_embeddings = True # 共享 Embedding
self.num_experts = 4 # MoE:4 专家
self.num_experts_per_tok = 1 # top-1 路由为什么是 768 维 × 8 层?
这来自 MobileLLM 的系统性研究:参数量固定时,"深而窄"优于"矮胖"——30~42 层的狭长结构在常识推理等基准上普遍好于 12 层的矮胖结构。
但"窄"有下限:d_model < 512 时词嵌入维度过窄的劣势会放大,加层也补不回来;而 d_model > 1536 后,继续加深通常比加宽更划算。768 × 8 是训练效率、稳定性与效果之间的工程折中。
参数量计算器 · 亲手验证 Scaling
拖动滑块,实时计算参数量(按 MiniMindConfig 的真实公式:注意力 3h²,FFN 3h×i,i = ⌈h·π/64⌉×64,词表 6400,Q:KV = 8:4):
核心组件源码解读
七大组件全部来自 model_minimind.py / model_lora.py 原文(有删节)。切换标签页逐一攻克。
RMSNorm 是 LayerNorm 的简化版:减均值、除标准差的两步合并成一步"除以均方根",少一次均值计算,快且效果几乎不掉。现代 LLM(Llama / Qwen / MiniMind)全线采用,且放在残差分支之前(Pre-Norm),训练更稳定。
class RMSNorm(torch.nn.Module):
def __init__(self, dim, eps=1e-5):
super().__init__()
self.eps = eps
self.weight = nn.Parameter(torch.ones(dim))
def norm(self, x):
return x * torch.rsqrt(x.pow(2).mean(-1, keepdim=True) + self.eps)
def forward(self, x):
return (self.weight * self.norm(x.float())).type_as(x)细节:内部先转 float32 计算再转回原 dtype,保证低精度(bf16)训练时数值稳定;可学习参数只有一条 weight 向量(无 bias)。
RoPE(旋转位置编码)把"位置"变成对 Q/K 向量的平面旋转:位置越远转角越大,注意力内积只依赖相对位置。MiniMind 额外支持 YaRN 外推——训练时只见过 2048 长度,推理时通过一个线性渐变系数压缩高频旋转,免训练扩展到 32768。
def precompute_freqs_cis(dim, end=32*1024, rope_base=1e6, rope_scaling=None):
# 基频:不同维度通道对应不同旋转速度(theta^(-2i/d))
freqs = 1.0 / (rope_base ** (torch.arange(0, dim, 2)[:dim//2].float() / dim))
if rope_scaling is not None:
# YaRN:f'(i) = f(i)·((1-γ) + γ/s),γ 是随通道线性上升的 ramp
# 低频通道保持不动,高频通道按 1/factor 压缩 → 长文本外推
ramp = torch.clamp((torch.arange(dim//2).float() - low) / max(high-low, .001), 0, 1)
freqs = freqs * (1 - ramp + ramp / factor)
t = torch.arange(end)
freqs = torch.outer(t, freqs).float() # 位置 × 频率 → 角度矩阵
return torch.cos(freqs).cat... , torch.sin(freqs).cat... # cos/sin 各复制拼接
def apply_rotary_pos_emb(q, k, cos, sin, unsqueeze_dim=1):
def rotate_half(x): # [x1,x2,...,xd/2,xd/2+1,...] → 后半取负拼到前面
return torch.cat((-x[..., x.shape[-1]//2:], x[..., :x.shape[-1]//2]), dim=-1)
q_embed = q*cos + rotate_half(q)*sin
k_embed = k*cos + rotate_half(k)*sin
return q_embed, k_embed实测:输入超过训练长度的《西游记》长文本时,开启 --inference_rope_scaling 后 PPL 明显下降(官方提供了 rope_ppl 对比图)。rope_theta=1e6 的大基数也让低频通道更平滑。
GQA(分组查询注意力)让多个 Q 头共享同一组 KV 头:8 个 Q 头只用 4 组 KV,KV-Cache 显存直接减半,是 Llama2-70B / Qwen3 都在用的标准技巧。FlashAttention 则调用 PyTorch 原生 scaled_dot_product_attention 融合算子,避免显式生成 n² 注意力矩阵。
xq, xk, xv = self.q_proj(x), self.k_proj(x), self.v_proj(x)
xq = xq.view(bsz, seq_len, self.n_local_heads, self.head_dim) # 8 头
xk = xk.view(bsz, seq_len, self.n_local_kv_heads, self.head_dim) # 4 头
xv = xv.view(bsz, seq_len, self.n_local_kv_heads, self.head_dim)
xq, xk = self.q_norm(xq), self.k_norm(xk) # QK-Norm:稳定训练
xq, xk = apply_rotary_pos_emb(xq, xk, cos, sin) # 注入位置信息
xq, xk, xv = (xq.transpose(1,2), repeat_kv(xk, self.n_rep).transpose(1,2),
repeat_kv(xv, self.n_rep).transpose(1,2)) # 4 组 KV 复制给 8 个 Q 头
if self.flash: # 条件满足时走融合算子
output = F.scaled_dot_product_attention(xq, xk, xv, is_causal=True)
else: # 手写兜底:score → 因果掩码 → softmax → 加权求和
scores = (xq @ xk.transpose(-2,-1)) / math.sqrt(self.head_dim)
scores[..., -seq_len:] += torch.full((seq_len, seq_len), -inf).triu(1) # 上三角屏蔽
output = F.softmax(scores.float(), dim=-1) @ xv亮点:①QK-Norm——对每个头的 Q/K 再做 RMSNorm(对齐 Qwen3),抑制注意力 logits 爆炸;② 手写兜底分支是绝佳的教学材料,能看清 softmax 之前因果掩码是怎么加上的。
SwiGLU是 FFN 的现代形态:两条支路相乘,一条过 SiLU 激活,一条直通(门控思想),比传统 ReLU FFN 效果更好。注意中间维不是拍脑袋定的:⌈h·π/64⌉×64,对 768 维即 2432——用 π 做缩放是 Llama 系沿用的经验配方,同时保持 64 的倍数利于硬件对齐。
class FeedForward(nn.Module):
def __init__(self, config, intermediate_size=None):
super().__init__()
intermediate_size = intermediate_size or config.intermediate_size
self.gate_proj = nn.Linear(config.hidden_size, intermediate_size, bias=False)
self.down_proj = nn.Linear(intermediate_size, config.hidden_size, bias=False)
self.up_proj = nn.Linear(config.hidden_size, intermediate_size, bias=False)
self.act_fn = ACT2FN[config.hidden_act] # SiLU
def forward(self, x):
return self.down_proj(self.act_fn(self.gate_proj(x)) * self.up_proj(x))MoE(混合专家)把单个 FFN 换成 N 个并行"专家"和一个路由器:每个 token 只被 top-k 个专家处理(MiniMind-3-MoE 为 4 选 1),容量变大而计算量近似不变。两个关键细节:负载均衡辅助损失防止路由塌缩到个别专家;未被选中的专家在训练时也要"挂"到计算图上(用 0×sum 技巧)避免 DDP 报错。
x_flat = x.view(-1, hidden_dim) # 展平到 token 粒度
scores = F.softmax(self.gate(x_flat), dim=-1) # 路由器打分
topk_weight, topk_idx = torch.topk(scores, k=1, dim=-1, sorted=False)
if self.config.norm_topk_prob:
topk_weight = topk_weight / (topk_weight.sum(-1, keepdim=True) + 1e-20)
y = torch.zeros_like(x_flat)
for i, expert in enumerate(self.experts):
mask = (topk_idx == i)
if mask.any(): # 只forward被选中的token(分桶)
token_idx = mask.any(dim=-1).nonzero().flatten()
y.index_add_(0, token_idx, expert(x_flat[token_idx]) * weight)
elif self.training:
y[0, 0] += 0 * sum(p.sum() for p in expert.parameters()) # 空专家挂图
if self.training and self.config.router_aux_loss_coef > 0:
load = F.one_hot(topk_idx, num_experts).float().mean(0)
self.aux_loss = (load * scores.mean(0)).sum() * num_experts * 5e-4 # 均衡损失
return y.view(batch_size, seq_len, hidden_dim)只有当专家 i 既接了很多 token(f 大)又被打了高分(P 大)时 aux 损失才大——这正好惩罚"赢家通吃"的路由塌缩,把 token 均匀推向各个专家(coef=5e-4)。
KV-Cache:自回归生成时,历史 token 的 K/V 不会再变,缓存起来后每步只需前向 1 个新 token,把每步 O(n²) 降到 O(n)。采样策略则决定生成的随机性:temperature 调节分布陡峭度 → top-k 截断 → top-p 核采样 → repetition_penalty 惩罚重复。
minimind-3 @ 2048 上下文 ≈ 2×8×4×96×2048×2B ≈ 24 MB(GQA 已把 KV 头从 8 砍到 4)
for _ in range(max_new_tokens):
past_len = past_key_values[0][0].shape[1] if past_key_values else 0
outputs = self.forward(input_ids[:, past_len:], attention_mask,
past_key_values, use_cache=use_cache) # 只喂新token!
logits = outputs.logits[:, -1, :] / temperature # 温度缩放
if repetition_penalty != 1.0: # 已出现token除以惩罚
seen = torch.unique(input_ids[i])
logits[i, seen] = torch.where(score > 0, score/rp, score*rp)
if top_k > 0: # 只保留前k个logit
logits[logits < torch.topk(logits, top_k)[0][..., -1, None]] = -inf
if top_p < 1.0: # 核采样:累计概率≥p
sorted_logits, idx = torch.sort(logits, descending=True)
mask = torch.cumsum(torch.softmax(sorted_logits, -1), -1) > top_p
logits[mask.scatter(1, idx, mask)] = -inf
next_token = torch.multinomial(torch.softmax(logits, -1), 1) # 按概率抽样
past_key_values = outputs.past_key_values # 更新缓存注:以上是 generate() 方法的默认采样参数;eval_llm.py 命令行入口默认 top_p=0.95,并支持 --historys N 携带 N 轮历史对话(需为偶数)。
LoRA 冻结原权重 W,旁边挂一条低秩支路 BA(A 高斯初始化、B 全零 → 训练起点等价于恒等),只训练 A/B。MiniMind 不用 peft,50 行手写;且只挂到 in_features == out_features 的方阵 Linear 上。
class LoRA(nn.Module):
def __init__(self, in_features, out_features, rank):
super().__init__()
self.rank = rank
self.A = nn.Linear(in_features, rank, bias=False) # 降维
self.B = nn.Linear(rank, out_features, bias=False) # 升维
self.A.weight.data.normal_(mean=0.0, std=0.02) # A:高斯初始化
self.B.weight.data.zero_() # B:全零 → 初始输出为0
def forward(self, x):
return self.B(self.A(x))
def apply_lora(model, rank=16):
for name, module in model.named_modules():
if isinstance(module, nn.Linear) and module.in_features == module.out_features:
lora = LoRA(module.in_features, module.out_features, rank=rank)
setattr(module, "lora", lora)
original_forward = module.forward
def forward_with_lora(x, layer1=original_forward, layer2=lora):
return layer1(x) + layer2(x) # W·x + B(A·x)
module.forward = forward_with_lora
# merge_lora:训练完可把 ΔW = B·A 合并回原权重,得到零开销的新模型
state_dict[f'{name}.weight'] += (module.lora.B.weight @ module.lora.A.weight)应用示例:医学问答 LoRA(lora_medical)与自我认知 LoRA(lora_identity),评测命令 python eval_llm.py --weight full_sft --lora_weight lora_medical。
Tokenizer 与数据
词表决定模型体积的下限,数据决定能力的上限。
6400 词表的取舍智慧
MiniMind 自训了一个 BPE + ByteLevel 分词器,词表只有 6400(支持 <tool_call> / <think> 等模板标记)。对小模型而言,词表大小直接决定 Embedding 层和输出层的参数占比——6400×768 的 Embedding 只有约 490 万参数,这让 26M 的 smallest 版本成为可能。
压缩比参考:中文约 1.5~1.7 字符/token("白日依山尽"5 字 → 4 token),英文约 4~5 字符/token。代价是编解码效率弱于 Qwen/GLM 等中文友好词表——这是体积约束下的主动取舍。作者建议:不要轻易重训 tokenizer,它会同时破坏权重、数据格式与生态兼容性。
<|im_start|>、eos=<|im_end|>、pad/unk=<|endoftext|>,另预留 vision/audio/tts 等多模态占位与 buffer token 供未来扩展。数据集格式规范(jsonl)
纯文本 → 下一 token 预测。训练代码自动加 BOS/EOS、padding,并把 pad 位置 label 置为 -100:
{"text": "如何才能摆脱拖延症?治愈拖延症并不容易,但以下建议可能有所帮助。"}
{"text": "清晨的阳光透过窗帘洒进房间,桌上的书页被风轻轻翻动。"}
{"text": "Transformer 通过自注意力机制建模上下文关系,是现代大语言模型的重要基础结构。"}多轮对话统一走 chat_template 渲染;Tool Call 数据与 OpenAI 格式一致(tools 挂 system、tool_calls 挂 assistant),训练时自动展开为 <tool_call> 片段:
{"conversations": [
{"role": "system", "content": "# Tools ...", "tools": "[...]"},
{"role": "user", "content": "帮我算一下 256 乘以 37 等于多少"},
{"role": "assistant", "content": "",
"tool_calls": "[{\"name\":\"calculate_math\",\"arguments\":{\"expression\":\"256 * 37\"}}]"},
{"role": "tool", "content": "{\"result\":\"9472\"}"},
{"role": "assistant", "content": "256 乘以 37 等于 9472。"}
]}其中约 10 万条 Tool Call 样本由 qwen3-4b 蒸馏合成;只有 assistant 段(含工具标签)参与 loss。
同一个问题配一好一坏两个回答,DPO 从中学习人类偏好(抽样自 DPO-En-Zh-20k,含中文):
{
"chosen": [{"content": "Q", "role": "user"}, {"content": "good answer", "role": "assistant"}],
"rejected": [{"content": "Q", "role": "user"}, {"content": "bad answer", "role": "assistant"}]
}RLAIF 的 assistant 回答留空——完全由当前策略模型在线采样生成后再打分。Agent RL 额外带一个 gt 字段做最终答案校验(RLVR 风格):
{"conversations": [
{"role": "user", "content": "请解释一下什么是光合作用?"},
{"role": "assistant", "content": "无"} // 留空,等 rollout 续写
]}
// agent_rl 额外携带:多轮轨迹 + 工具集 + 校验目标
{"conversations": [ ... 多轮工具调用消息 ... ], "tools": [...], "gt": "9472"}📏 max_seq_len 指 token 数而非字符数:中文 ≈1.5~1.7 字符/token,数据集文件名里的"长度"则按字符算。设大了 padding 浪费算力,设小了截断伤语义——官方推荐 mini 数据 ≈768、主线 pretrain ≈380,在算力与语义完整性之间找平衡。数据来源:匠数 deepctrl、Magpie-Align、R1-Distill-SFT、COIG、Step-3.5-Flash-SFT 等,经清洗、去重、长度控制与格式统一后发布。
模板解剖 · 一条对话是如何变成训练文本的
SFT 数据不是直接喂给模型的:先经 chat_template(Jinja2,与 Qwen3 同款风格)把 messages 渲染成一整条文本,再切片 tokenize。下图就是渲染结果(橙=特殊 token / 蓝=角色名 / 绿=模型要学的内容 / 紫=思考标签):
三个关键机制:① Adaptive Thinking——open_thinking=0 时模板注入空的 <think></think>(如上,模型直接回答);=1 时只注入 <think> 起始标签,让模型自己续写思考再给答案。② Tool Call——tools 列表被渲染进 system 段,assistant 的 tool_calls 渲染成 <tool_call>{...}</tool_call>、工具返回渲染成 <tool_response>{...}</tool_response>。③ 训练时按 thinking_ratio 概率混合空思考/显式思考样本,让模型"该想时想、该直答时直答"。
SFT 的关键技巧:提示词部分不计算损失(label = -100),只有 assistant 回复段参与交叉熵。点击按钮体验 label 的生成逻辑:
实现:SFTDataset 先用 chat_template 渲染整段对话,然后扫描 token 序列定位 <|im_start|>assistant\n … <|im_end|>\n 区间,区间外的 label 全部置 -100(generate_labels 函数)。
训练全流程详解
MiniMind 实现了 2+N 种强化学习算法。先建立一个统一视角,再逐个点开阶段卡片。
PO 算法的统一视角
所有 Policy Optimization 算法,本质都是在优化同一个期望——差别只是三个组件的实例化方式:
如何利用新旧策略的概率比 rt(clip 裁剪?对比 chosen/rejected?)
回答比基线好多少:Critic 估计(PPO)?组内归一化(GRPO)?隐式偏好(DPO)?
约束别偏离参考模型太远:全局 KL?token 级 KL?还是隐含在 β 里?
九大训练阶段卡片(点击展开)
目标:让模型埋头读海量文本,把事实知识与语言规律压进参数——学会"高质量词语接龙"(输入"秦始皇",接出"是中国历史上的第一位皇帝")。本质是最小化下一 token 交叉熵,无监督。
关键配置:AdamW,lr 5e-4 余弦退火(下限 10%),epoch 2,batch 32 × 梯度累积 8,bf16 混合精度,梯度裁剪 1.0。
lr = get_lr(epoch*iters + step, epochs*iters, learning_rate) # 余弦退火
with autocast_ctx: # bf16 自动混合精度
res = model(input_ids, labels=labels)
loss = (res.loss + res.aux_loss) / accumulation_steps # MoE均衡损失一起优化
scaler.scale(loss).backward()
if step % accumulation_steps == 0:
scaler.unscale_(optimizer)
torch.nn.utils.clip_grad_norm_(model.parameters(), grad_clip) # 裁剪防爆
scaler.step(optimizer); scaler.update()
optimizer.zero_grad(set_to_none=True)学习率调度:lr·(0.1 + 0.45·(1+cos(π·t/T)))——从 100% 平滑降到 10%,无 warmup 阶梯,简单有效。
预训练后就能答知识题,但还不会"对话":
🧠: 天空之所以看起来是蓝色的,主要是因为太阳光进入大气层后,短波长的蓝光更容易被空气分子散射,因此人眼从各个方向接收到的蓝光会更多。
此时它只会"续写"而不会角色扮演——让模型学会 user/assistant 角色结构,正是下一步 SFT 的任务。
目标:让模型适应多轮对话模板,理解 user / assistant / system / tool 角色结构,学会指令跟随、工具调用与思考标签。
不只是"教聊天":主线 SFT 数据多达 14GB,本身已带有 mid-training 性质——持续向模型灌入知识、行为模式与回答风格(包括 qwen3-4b 蒸馏的 10w 条 Tool Call 与 reasoning 数据)。Tool Call 能力已并入主线数据,跑完 full_sft 即自带基础工具调用能力。
关键配置:默认从 pretrain 权重自动接力(--from_weight pretrain),epoch 2、batch 16、lr 骤降到 1e-5(预训练的 1/50)、max_seq_len 768——小学习率做"精装修",避免冲掉预训练学到的知识。
Loss Mask:只对 assistant 段计算损失(见第 05 章可视化)。
目标:冻结基模,只训练低秩增量分支,用极小代价完成垂域适配(医学问答、自我认知等),保留通用能力。源码解读见第 04 章标签页⑦。
cd trainer && python train_lora.py # lora_identity / lora_medical 等
python eval_llm.py --weight full_sft --lora_weight lora_medical
# 合并导出:cd scripts && python convert_model.py(merge_base_lora)经验:若垂域数据充足且不怕过拟合,也可直接 full_sft 全参微调,但需混入通用数据防止灾难遗忘。
思路:SFT 后的模型只会"接龙",不知道什么回答好、什么差。DPO 用 chosen / rejected 偏好对直接最大化"好答案优于差答案"的对数几率——无需奖励模型、无需在线采样,off-policy 可以像监督学习一样反复跑 epoch。
x = torch.cat([x_chosen, x_rejected], dim=0) # 好坏拼成一个 batch
policy_log_probs = 策略模型logp(x, y, mask)
ref_log_probs = 冻结参考模型logp(x, y, mask)
pi_logratios = chosen_policy - rejected_policy # 策略模型的好差间距
ref_logratios = chosen_ref - rejected_ref # 参考模型的好差间距
logits = pi_logratios - ref_logratios
loss = -F.logsigmoid(beta * logits).mean()局限:不做在线探索,更多提升"偏好/安全"而非智力;对"能不能做对题"帮助有限。
📄 论文:DPO — Direct Preference Optimization (Rafailov et al., 2023)
思路:Actor(策略)实时采样回答,Critic(价值网络)估计优势,KL 约束防跑偏。需要奖励信号——MiniMind 采用 InternLM2-1.8B-Reward 奖励模型给出的连续分数(约 -2.5 ~ +3.0)。
关键实现:CriticModel 直接继承 MiniMindForCausalLM 外挂价值头;GAE(γ=1.0, λ=0.95)、ε=0.2、kl_coef≈0.02、vf_coef=0.5;Actor / Critic 学习率分别低至 3e-7 / 5e-7,仅训 1 epoch——RL 阶段的学习率比 SFT 又小了几个数量级,这是所有 PO 算法的共同特征。
思路(DeepSeekMath 提出、R1 带火):同一问题采样 N 个回答,用组内平均奖励当基线——高于均值的被鼓励、低于的被抑制,彻底去掉 Critic 网络。单网络训练更稳、收敛上限更高,MiniMind 实验中 reward 平稳上升到 4 左右。
实现中的奖励是"规则分 + 模型分"混合:回答长度适中(20~800 字符)±0.5、思考内容长度适中 ±1.0、</think> 恰好出现一次 +0.25、重复内容扣分,再叠加奖励模型的连续分——这正好呼应了本章末尾"奖励信号怎么选"的混合策略。
advantages = (rewards - mean_r) / (std_r + 1e-4) # 组内归一化
ratio = torch.exp(per_token_logps - old_logps)
clipped = torch.clamp(ratio, 1 - epsilon, 1 + epsilon)
per_token_loss1 = ratio * advantages.unsqueeze(1)
per_token_loss2 = clipped * advantages.unsqueeze(1)
per_token_loss = -(torch.min(per_token_loss1, per_token_loss2) - beta * per_token_kl)注意退化组问题:若 N 个回答奖励几乎相同,学习信号趋近 0——小模型必须把 RL 限制在能力边界内。
思路:PPO/GRPO 里 ratio 被 clip 后梯度流也被硬截断。CISPO 只做一个极小改动:把策略项改写成「裁剪权重 × log 概率」,ratio 截断但梯度路径保住。
实现上只是 train_grpo.py --loss_type cispo(且这是默认值),分组采样、奖励计算、优势构造全部复用 GRPO 逻辑。
思路:不再是"单轮问答即时打分",而是多轮轨迹级 RL:模型生成 tool_call → 执行工具 → observation 拼回上下文 → 继续生成,循环直到任务完成,最后对整条轨迹结算一次延迟奖励。
源码里的奖励明细(train_agent.py):gt 命中给大头 +2.5 × len(verified)/len(gt)(部分命中按比例给分);<tool_call> 标签不闭合按个扣 0.5;工具调用与工具返回数量对齐 ±0.5;回答/思考长度适中、思考标签恰好闭合给小分;再加 Reward Model 连续分;重复内容与未完成轨迹扣分——可验证的 gt 占绝对权重,避免模型只会"讨好 RM"。
训推分离:训练侧只管 policy 更新,rollout 侧(本地 torch 或 sglang server)只管高吞吐采样,中间靠"轨迹 + 权重同步"衔接——麻雀虽小,已是 openrlhf / verl 的雏形(当前为同步模式)。
python train_agent.py
# 或高吞吐版:先起 sglang server,再指定 rollout engine
python -m sglang.launch_server --model-path ./minimind-3 --attention-backend triton --port 8998
python train_agent.py --rollout_engine sglang --sglang_base_url http://localhost:8998 \
--data_path ../dataset/agent_rl_math.jsonl黑盒蒸馏:只学老师的输出文本(硬标签),本质是对 teacher 回答做 SFT。R1 / Qwen3 的回答、tool call、思维链数据都属此类——主线 SFT 数据里已大量混入。
白盒蒸馏:进一步拟合老师在 token 分布层面的偏好(软标签),学生学到"候选词之间的相对倾向":
train_distillation.py 完整展示双模型加载、温度缩放、MoE↔Dense 组合蒸馏与断点续训,适合作为参考实现逐行读。
RL 算法对比总表
先分清两大范式,再看算法:
| 范式 | 裁判是谁 | 优点 | 缺点 |
|---|---|---|---|
| RLHF(如 DPO) | 人类偏好标注 | 贴近真实人类偏好 | 标注贵、效率低、难扩展 |
| RLAIF(PPO / GRPO / CISPO / Agent) | 奖励模型 / 规则 / 环境 | 全自动、可扩展、能在线试错 | 可能偏离人类真实偏好(reward hacking) |
| 算法 | 策略项 f(rt) | 优势项 g(At) | 正则项 h(KL) | 训练模型数 | 范式 |
|---|---|---|---|---|---|
| DPO | log rw − log rl | 无显式优势(偏好隐式) | 隐含在 β 中 | 1(前向参与 2) | off-policy |
| PPO | min(r·A, clip(r,1±ε)·A) | Critic / GAE 估计 | β·𝔼[KL] | 2(Actor+Critic) | on-policy |
| GRPO | min(r·A, clip(r,1±ε)·A) | 组内归一化 (R−μ)/σ | β·KLt(token级) | 1 | on-policy |
| CISPO | clip(r,0,εhigh)·A·log πθ | (R−μ)/σ(沿用GRPO) | β·KLt | 1 | on-policy |
训练工程细节
工程基建(所有脚本共享)
✅ DDP 多卡:torchrun --nproc_per_node N,自动初始化进程组
✅ 断点续训:--from_resume 1,从 checkpoints/ 恢复模型+优化器+scaler+进度,支持跨 GPU 数量恢复
✅ 混合精度:bf16 autocast(fp16 时启用 GradScaler)
✅ 梯度累积:小显存也能凑出大 batch
✅ 可视化:--use_wandb(SwanLab 兼容接口,国内友好)
✅ torch.compile:--use_compile 1 一键加速
奖励信号怎么选?
任何能量化"回答质量"的机制都可以做奖励:
• Model-based:奖励模型 / LLM-as-Judge 打分(MiniMind 主线)
• Rule-based:数学答案比对、代码通过测试、JSON 格式合规、CoT 步骤完整度(DeepSeek R1 路线)
• Environment-based:Agent 场景的环境真实反馈(工具是否执行成功)
可混合:rtotal = α·rmodel + β·rrule
默认超参速查表(来自各脚本 argparse 默认值)
| 阶段 | 学习率 | 批量 / 轮数 | 其他关键默认值 |
|---|---|---|---|
| Pretrain | 5e-4(余弦退火至 10%) | 32 × 累积8 / 2 epoch | seq 340 · bf16 · 裁剪 1.0 |
| Full SFT | 1e-5 | 16 / 2 epoch | seq 768 · 自动接 pretrain 权重 |
| LoRA | 1e-4 | 32 / 10 epoch | rank 16 · 自动接 full_sft · seq 340 |
| DPO | 4e-8(官方注:建议 ≤5e-8 防遗忘) | 4 / 1 epoch | β=0.15 · 双模型前向 · seq 1024 |
| PPO | Actor 3e-7 / Critic 5e-7 | 2 / 1 epoch | ε=0.2 · kl 0.02 · GAE(γ=1.0, λ=0.95) |
| GRPO / CISPO | 3e-7 | 2 × 每题采 6 个回答 / 1 epoch | ε=0.2 · loss_type 默认 cispo |
| Agent RL | 3e-7 | 2 × 每题采 4 条轨迹 / 1 epoch | 多轮 rollout · 延迟奖励 · seq 1024 |
| 蒸馏 | 5e-6 | 32 / 6 epoch | CE+KL 混合 · 温度缩放 · 可 MoE↔Dense |
📌 规律:越靠后的阶段学习率越小(预训练 5e-4 → SFT 1e-5 → RL 3e-7 量级),每个阶段都在"精修"而非"重塑"模型——这是复现训练时最值得记住的一条经验。
实验与评测
用数据说话:RL 到底带来了什么?小模型横评该怎么读?
Agent RL 带来了什么(20 道数学工具题实测)
同一批「先决定是否调工具、再把可验证结果做对」的数学 ToolUse 任务:
错误从 8 道降到 3 道:例如 3**2 从答 8 → 答对 9,10**2 从答 13 → 答对 100。RL 后模型真正学会了"该调工具时调工具、用工具结果答题"。
另一组主观横评(GPT-5.4 当裁判,满分 100):minimind-3-moe 68 分(表达流畅但幻觉多)> chatlm-mini 62 分(知识准但代码差)> minimind-3 61 分 > baby-llama2 21 分。有趣的互补现象:D 赢在知识准确性(25 vs 10),A 赢在代码能力(17 vs 3)——小参数预算下"说得好"与"说得对"很难兼得。
客观横评:先看"分辨率",再看分数
lm-evaluation-harness 测试(选择题按候选概率判定,随机作答就是很强的下界,这个量级的模型长期在附近徘徊):
| 模型 | 参数 | zh: ceval / cmmlu | en: arc / piqa / obqa |
|---|---|---|---|
| minimind-3 | 64M | 24.89 / 25.38 | 28.49 / 50.65 / 23.60 |
| minimind-3-moe | 198M | 25.48 / 24.32 | 27.74 / 50.71 / 26.20 |
| minimind-3-exam(LoRA 格式对齐版) | 64M | 30.98 / 26.12 | 35.61 / 56.26 / 24.20 |
| SmolLM2-135M-Instruct | 135M | 24.44 / 24.71 | 58.50 / 68.17 / 32.80 |
| gpt2-medium | 360M | 23.18 / 25.00 | 43.60 / 66.38 / 30.20 |
| TinyLlama-1.1B-Chat | 1100M | 25.71 / 25.03 | 54.80 / 74.43 / 35.60 |
彩蛋:minimind-3-exam 仅用 LoRA 做了"答题格式对齐"(不注入知识、无数据污染),7 项平均就提升约 2.9 个百分点——说明小模型的瓶颈未必在知识,也可能只是输入格式没对齐。而一旦在有交集的数据上微调,ceval 可以刷到 97%,但毫无参考意义(数据污染)。
长文本:YaRN 外推实测(用不同长度《西游记》文本测 PPL),开启 rope scaling 后长文本 PPL 显著下降。
部署与生态
训练好的模型不止能跑 CLI:一行命令接入 OpenAI 兼容 API,或塞进 ollama / vllm / llama.cpp / 手机。
🖥️ OpenAI 兼容 API 服务
cd scripts && python serve_openai_api.py # 启动服务
python chat_api.py # 测试
# 支持流式 / reasoning_content / tool_calls / open_thinking
curl http://localhost:8998/v1/chat/completions -H "Content-Type: application/json" -d '{
"model": "minimind",
"messages": [{"role": "user", "content": "世界上最高的山是什么?"}],
"stream": true, "open_thinking": true
}'可直接接入 FastGPT / Open-WebUI / Dify 等第三方 Chat UI。
🔄 格式转换
scripts/convert_model.py 在 torch / transformers 两种格式间互转;LoRA 可合并回基模导出成新完整模型。官方发布权重以 Transformers 格式为主。
⚙️ 三方推理引擎一键上
# ollama:一行直接跑(官方已上架)
ollama run jingyaogong/minimind-3
# vllm:高吞吐服务
vllm serve /path/to/model --served-model-name "minimind"
# llama.cpp:先转 GGUF(tokenizer 兼容项用 qwen2),再可选 Q8 量化
python convert_hf_to_gguf.py /path/to/minimind-model
# sglang:RL 训练的高吞吐 rollout 后端
python -m sglang.launch_server --model-path ./minimind-3 --port 8998
# MNN:端侧部署(Mac / 手机),支持 4-bit HQQ 量化学习路线与常见问题
给不同目标读者的路线图,以及最常被问到的问题。
推荐学习路径
高频问题
三个理由:① 词表直接决定 Embedding + 输出层参数占比,6400 词表是 26M 小模型能存在的前提;② 词表一变,权重、数据格式、推理接口、社区生态兼容性全部报废;③ tokenizer 还影响 PPL 这类按 token 统计的指标——跨 tokenizer 比较时 BPB(Bits Per Byte)更公平。官方明确建议:别重训,沿用即可。
"MoE 推理更快"的前提是融合 kernel。原生实现里 token 要先按专家分桶、再逐个专家 forward,kernel 启停与调度开销急剧变重。要提速得靠 Triton 自定义 kernel / DeepSpeed-MoE / Megatron-LM。MiniMind 为保持"纯 PyTorch 普适性"选择了 4 experts / top-1 的甜点折中。
这就是对齐税 / reward hacking:RL 优化的是"当前奖励定义下的分数",模型会越来越擅长迎合奖励,但不等价于整体能力无损提升——agent 权重工具题从 60% 涨到 85% 的同时,通用问答的事实性在下降。业界所有后训练模型都存在,只是程度差异。按用途选权重即可。
奖励稀疏排第一:模型太弱,在超纲任务(如 MATH500 + 二元对错奖励)上所有 rollout 全错、奖励全零、优势归零、梯度消失。解法:用连续分数的奖励模型(-2.5~+3.0 即使全错也能分出高下)、把任务限制在能力边界内、混合规则奖励,并监控 Var(r) 不要趋近 0。其次注意 GRPO 的退化组(组内奖励方差≈0 则无信号)。
官方保留了早期 Zero 样例:能进行基础中文对话(介绍自己、推荐美食、解释概念),但事实知识与泛化有限,英文接近乱码。它的价值在于验证"个人从 0 训练 LLM"路线完全可行——要更强效果,用 14GB 主线数据完整复现 minimind-3 即可。