GitHub 61.2k ★ · Apache-2.0 · 作者 Jingyao Gong

MiniMind 互动知识平台

从 0 到 1 亲手训练一个 64M 参数的大语言模型:约 3 元钱、2 小时,覆盖 预训练 → SFT → LoRA → DPO → PPO / GRPO / CISPO → Agent RL → 蒸馏 全链路。

「大道至简」—— 所有核心算法均以 PyTorch 原生实现,不依赖 transformers / trl / peft 的高层封装。

61.2kGitHub Stars
64M主线模型参数量
≈2h / ≈¥3单卡 3090 从 0 训练
6400自定义词表大小
1/2700约为 GPT-3 的体积
00

项目总览

先花 3 分钟,建立对 MiniMind 的整体认知。

它是什么 · 一句话读懂

MiniMind 是一个开源的大语言模型全阶段复现项目 + 系统性教程:它把 ChatGPT 背后那套「预训练 → 指令微调 → 偏好对齐 → 强化学习」的完整工业流程,压缩成一个普通人用单张消费级显卡、一顿饭钱就能跑通的极简实现。

它不是调用框架 API 的"套壳"项目——模型结构(RMSNorm / RoPE / GQA / SwiGLU / MoE)、Tokenizer、LoRA、DPO、PPO、GRPO、CISPO、Agent RL、知识蒸馏,全部从 0 用原生 PyTorch 手写,代码总量小到可以逐行读完。

Dense + MoE 双架构对齐 Qwen3 生态Tool Calling自适应思考 <think>YaRN 长文本外推断点续训DDP / DeepSpeed 多卡wandb / SwanLab

为什么值得亲手学一遍

🎯 打开黑盒,而不是停留在"会用"。绝大多数学习路径止步于用 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-364MDense8 层 / 7682026.04当前主线 ✅
minimind-3-moe198M-A64MMoE(4 专家 / top-1)8 层 / 7682026.04当前主线 ✅
minimind2-small26MDense8 层 / 5122025.04历史(体积最小)
minimind2104MDense16 层 / 7682025.04历史
minimind2-moe145MMoE8 层 / 6402025.04历史
minimind-v1 系列26M ~ 108MDense / MoE—2024.08-09已停止维护

💡 198M-A64M 表示总参数 198M、每个 token 激活约 64M(4 专家取 top-1 路由)。

项目大事记

2024.08.27项目首次开源,提出「3 块钱 + 2 小时训练 26M 小模型」。
2024.10.05拓展多模态视觉能力,孪生项目 MiniMind-V 发布。
2025.02.09重大重构:发布 minimind2 系列;统一 jsonl 数据格式;LoRA / DPO / 白盒蒸馏全部改为原生实现;开始具备英文能力。
2025.04.26参数命名对齐 transformers 生态;兼容 llama.cpp / vllm / ollama;词表改用 <|im_start|><|im_end|>。
2025.10.24新增 RLAIF:PPO / GRPO 从 0 实现;断点续训;YaRN 长文本外推;自适应思考;SwanLab 替代 WandB。
2026.03新增 Agentic RL(train_agent.py):多轮 Tool-Use 的 GRPO / CISPO 训练;训推分离 rollout engine。
2026.04.01发布 minimind-3 / minimind-3-moe:结构对齐 Qwen3 生态,GQA 8Q/4KV,Tokenizer 更新为 BPE + ByteLevel,Tool Call 并入主线 SFT 数据。
01

快速上手 · 手把手教程

五步走通全流程:环境 → 推理体验 → 下载数据 → 训练 → 对话测试。所有命令均来自官方 README。

0

克隆仓库并安装依赖

bash · 终端
# 克隆仓库(浅克隆即可)
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

(可选)先下载官方权重,体验推理效果

bash · 下载模型 & CLI 推理
# 方式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/ 目录)。

2

下载训练数据,放入 ./dataset 目录

从 ModelScope 或 HuggingFace 下载。✨ 为快速复现推荐必选项,无需全部下载:

文件体积用途
pretrain_t2t_mini.jsonl ✨1.2GB轻量预训练(推荐 max_seq_len≈768)
sft_t2t_mini.jsonl ✨1.6GB轻量 SFT,已混入 Tool Call 样本
rlaif.jsonl ✨24MBPPO / GRPO / CISPO 强化学习
pretrain_t2t.jsonl10GB主线完整预训练
sft_t2t.jsonl14GB主线完整 SFT(含 Tool Call / 思考)
dpo.jsonl53MBDPO 偏好数据(chosen / rejected)
agent_rl.jsonl / agent_rl_math.jsonl86MB / 18MB多轮 Tool-Use Agentic RL(含 gt 校验)
3

两阶段必训:预训练 + 指令微调

bash · 在 trainer/ 目录执行
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)。

4

测试你的模型

bash · 真实输出示例
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
✅ 门槛总结一块 3090 即可完整复现;8×H100 可把训练压缩到分钟级;LoRA 微调甚至 CPU 也能跑。MoE 版本约比 Dense 慢 50%(原生实现未做 expert 融合 kernel,详见 FAQ)。
02

项目架构全景

整个仓库只有四个核心目录。点击任意文件,右侧查看它的职责说明。

📦 minimind/
├─ 📁 model/ —— 模型定义
│   ├─model_minimind.py (⭐ 核心结构 18.7KB)
│   ├─model_lora.py
│   ├─tokenizer.json / tokenizer_config.json
├─ 📁 dataset/ —— 数据集构建
│   └─lm_dataset.py
├─ 📁 trainer/ —— 全部训练脚本
│   ├─train_pretrain.py (必须)
│   ├─train_full_sft.py (必须)
│   ├─train_lora.py
│   ├─train_dpo.py
│   ├─train_ppo.py
│   ├─train_grpo.py (含CISPO)
│   ├─train_agent.py (🔥 Agentic RL)
│   ├─train_distillation.py
│   ├─train_tokenizer.py
│   ├─rollout_engine.py
│   └─trainer_utils.py
├─ 📁 scripts/ —— 部署与工具
│   ├─serve_openai_api.py
│   ├─web_demo.py
│   ├─convert_model.py
│   └─eval_toolcall.py
└─eval_llm.py (命令行对话入口)
👆 点击左侧任意文件

这里是整个项目的"地图"。MiniMind 的设计哲学是极简:模型一个文件、数据集一个文件、每个训练阶段一个独立脚本,互不纠缠,适合逐个击破。

训练主线流程

一条从"原始文本"到"可用助手"的完整流水线(🔥 为 2026 新增):

📄 文本语料pretrain_t2t(jsonl)
➜
✂️ TokenizerBPE + ByteLevel · 6400 词表
➜
📚 预训练 Pretrain词语接龙 · 吸收知识
➜
💬 SFT对话模板 · Tool Call · 思考
🎯 LoRA垂域/自我认知
➜
⚖️ DPO人类偏好对齐
➜
🤖 RLAIFPPO / GRPO / CISPO
➜
🔧 Agent RL 🔥多轮工具调用 RL
➜
🫀 蒸馏 / 部署API · ollama · vllm
📖 阅读建议前两个阶段(Pretrain + SFT)是必选项,构成一个能对话的 Zero 模型;后面全部是可选的"进阶副本",每个都对应 trainer/ 下一个独立脚本。
03

模型结构精讲

一个标准、现代、教科书级的 Transformer Decoder。点击下方结构图中的每一块,查看它在 MiniMind 里的具体实现。

🈴 Token 序列「秦始皇」→ [123, 88, 4021, …]
▼
🧲 Embedding 查表 + Dropout6400 × 768,与 LM Head 权重共享(tie)
▼
── Transformer Block × 8 层 ──
📐 RMSNorm(Pre-Norm)x · rsqrt(mean(x²)+ε) × weight
▼
👁️ GQA 因果自注意力8 个 Q 头 / 4 个 KV 头 + RoPE + QK-Norm + FlashAttention
▼ ⊕ 残差连接
📐 RMSNorm(第二次 Pre-Norm)注意力结果回接残差后再归一化
▼
🌀 FFN:SwiGLU(Dense)/ MoE(4 专家 top-1)down( SiLU(gate(x)) ⊙ up(x) ),中间维 2432
▼ ⊕ 残差连接
📐 最终 RMSNorm8 层输出后统一归一化
▼
🎯 LM Head → Softmax768 → 6400 logits,权重与 Embedding 共享
▼
🔁 自回归生成预测下一个 token → 拼回输入 → 循环(KV-Cache 加速)
👆 点击上方任意模块

MiniMind-3 是一个 8 层、隐藏维 768 的 Decoder-Only Transformer,整体与 Qwen3 / Llama 系的"现代配方"一致:Pre-Norm + RMSNorm + SwiGLU + RoPE + GQA。点击每个模块看细节。

🔄 互动演示:词语接龙(下一 Token 预测)

预训练教给模型的核心能力就是"词语接龙":每一步模型输出词表中每个 token 的概率分布,采样一个拼回输入,再预测下一个,循环往复直到输出结束符。点击候选词,或点"按概率采样"体验(概率为模拟数据,仅演示机制):

秦始皇是▌

对应源码:MiniMindForCausalLM.generate()——本演示就是它的简化版:logits → 温度/top-k/top-p → 采样 → 拼接 → 循环。

关键配置与设计取舍

python · model/model_minimind.py(默认值)
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 是训练效率、稳定性与效果之间的工程折中。

⚠️ 经验法则想加深先保底:d_model 别低于 512;预算允许时优先加层数而非宽度。

参数量计算器 · 亲手验证 Scaling

拖动滑块,实时计算参数量(按 MiniMindConfig 的真实公式:注意力 3h²,FFN 3h×i,i = ⌈h·π/64⌉×64,词表 6400,Q:KV = 8:4):

✅ 与官方 minimind-3 配置一致Embedding 与 LM Head 权重共享,只计一份。
63.9M
总参数量 | fp16 权重约 128 MB |
Embedding(共享)
注意力(3h² × 层)
FFN(3h·i × 层)
04

核心组件源码解读

七大组件全部来自 model_minimind.py / model_lora.py 原文(有删节)。切换标签页逐一攻克。

RMSNorm 是 LayerNorm 的简化版:减均值、除标准差的两步合并成一步"除以均方根",少一次均值计算,快且效果几乎不掉。现代 LLM(Llama / Qwen / MiniMind)全线采用,且放在残差分支之前(Pre-Norm),训练更稳定。

python · model_minimind.py
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。

python · 预计算旋转表 + YaRN(删节)
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² 注意力矩阵。

Attention(Q, K, V) = softmax( Q·KT / √dk ) · V  dk = head_dim = 96
python · Attention.forward(删节)
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 的倍数利于硬件对齐。

python · 全部代码,就这么短
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 报错。

python · MOEFeedForward.forward(删节)
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)
𝓛aux = Nexperts · coef · Σi fi · P̄i (fi=落到专家 i 的 token 占比,P̄i=路由器给 i 的平均概率)

只有当专家 i 既接了很多 token(f 大)又被打了高分(P 大)时 aux 损失才大——这正好惩罚"赢家通吃"的路由塌缩,把 token 均匀推向各个专家(coef=5e-4)。

⚠️ 反直觉事实这套原生实现里 MoE 反而比同规模 Dense 慢约 50%:token 按专家分桶后逐个 forward,kernel 启停调度开销巨大。工业级提速要靠 Triton 融合 kernel / DeepSpeed-MoE / Megatron。4 专家 top-1 是"甜点配置"。

KV-Cache:自回归生成时,历史 token 的 K/V 不会再变,缓存起来后每步只需前向 1 个新 token,把每步 O(n²) 降到 O(n)。采样策略则决定生成的随机性:temperature 调节分布陡峭度 → top-k 截断 → top-p 核采样 → repetition_penalty 惩罚重复。

KV-Cache 显存 ≈ 2(K,V) × 层数 × kv_heads × head_dim × 序列长 × batch × 2B
minimind-3 @ 2048 上下文 ≈ 2×8×4×96×2048×2B ≈ 24 MB(GQA 已把 KV 头从 8 砍到 4)
python · generate(删节,默认 T=0.85, top_p=0.85, top_k=50)
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 上。

python · model/model_lora.py(完整核心)
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。

05

Tokenizer 与数据

词表决定模型体积的下限,数据决定能力的上限。

6400 词表的取舍智慧

MiniMind 自训了一个 BPE + ByteLevel 分词器,词表只有 6400(支持 <tool_call> / <think> 等模板标记)。对小模型而言,词表大小直接决定 Embedding 层和输出层的参数占比——6400×768 的 Embedding 只有约 490 万参数,这让 26M 的 smallest 版本成为可能。

Qwen2
0
ChatGLM
0
Llama 3
0
Yi
0
Mistral
0
MiniMind
0

压缩比参考:中文约 1.5~1.7 字符/token("白日依山尽"5 字 → 4 token),英文约 4~5 字符/token。代价是编解码效率弱于 Qwen/GLM 等中文友好词表——这是体积约束下的主动取舍。作者建议:不要轻易重训 tokenizer,它会同时破坏权重、数据格式与生态兼容性。

🔤 30 秒看懂 BPE + ByteLevelBPE(字节对编码)从字符/字节级词表出发,反复把语料中出现最频繁的相邻符号对合并成新词,直到凑满 6400 个——高频词整词入库,低频词自然拆碎。ByteLevel 预分词则先把文本按 UTF-8 字节切开,保证任何文本(含 emoji、生僻字)都能编码,不存在 OOV。特殊 token:bos=<|im_start|>、eos=<|im_end|>、pad/unk=<|endoftext|>,另预留 vision/audio/tts 等多模态占位与 buffer token 供未来扩展。

数据集格式规范(jsonl)

纯文本 → 下一 token 预测。训练代码自动加 BOS/EOS、padding,并把 pad 位置 label 置为 -100:

jsonl · pretrain_t2t(_mini).jsonl
{"text": "如何才能摆脱拖延症?治愈拖延症并不容易,但以下建议可能有所帮助。"}
{"text": "清晨的阳光透过窗帘洒进房间,桌上的书页被风轻轻翻动。"}
{"text": "Transformer 通过自注意力机制建模上下文关系,是现代大语言模型的重要基础结构。"}

多轮对话统一走 chat_template 渲染;Tool Call 数据与 OpenAI 格式一致(tools 挂 system、tool_calls 挂 assistant),训练时自动展开为 <tool_call> 片段:

jsonl · sft_t2t(_mini).jsonl
{"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,含中文):

jsonl · dpo.jsonl
{
  "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 风格):

jsonl · rlaif.jsonl / agent_rl(_math).jsonl
{"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 / 蓝=角色名 / 绿=模型要学的内容 / 紫=思考标签):

<|im_start|>system You are minimind, a helpful assistant.<|im_end|> <|im_start|>user 你好,介绍一下机器学习<|im_end|> <|im_start|>assistant <think> </think> 机器学习是人工智能的核心分支,它让计算机从数据中学习规律。<|im_end|>

三个关键机制:① 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 的生成逻辑:

模式② 说明绿色 = 参与 loss 的 token(assistant 内容 + 收尾的 <|im_end|>);灰色 = 提示词与模板骨架(label 置为 -100,被交叉熵忽略)。这样模型专注于"如何回答",而不是背提示词。

实现:SFTDataset 先用 chat_template 渲染整段对话,然后扫描 token 序列定位 <|im_start|>assistant\n … <|im_end|>\n 区间,区间外的 label 全部置 -100(generate_labels 函数)。

06

训练全流程详解

MiniMind 实现了 2+N 种强化学习算法。先建立一个统一视角,再逐个点开阶段卡片。

PO 算法的统一视角

所有 Policy Optimization 算法,本质都是在优化同一个期望——差别只是三个组件的实例化方式:

𝒥PO = 𝔼q∼P(Q), o∼πθ(·|q) [ Φ(rt, At) 策略目标 − h(KLt) 正则项 ]
① 策略项 f(rt)

如何利用新旧策略的概率比 rt(clip 裁剪?对比 chosen/rejected?)

② 优势项 g(At)

回答比基线好多少:Critic 估计(PPO)?组内归一化(GRPO)?隐式偏好(DPO)?

③ 正则项 h(KL)

约束别偏离参考模型太远:全局 KL?token 级 KL?还是隐含在 β 里?

九大训练阶段卡片(点击展开)

📚1 · 预训练 Pretrain必须 · ~1.2h / ¥1.6▶

目标:让模型埋头读海量文本,把事实知识与语言规律压进参数——学会"高质量词语接龙"(输入"秦始皇",接出"是中国历史上的第一位皇帝")。本质是最小化下一 token 交叉熵,无监督。

𝓛 = CrossEntropy( logits[..., :-1], labels[..., 1:] ),ignore_index = -100

关键配置:AdamW,lr 5e-4 余弦退火(下限 10%),epoch 2,batch 32 × 梯度累积 8,bf16 混合精度,梯度裁剪 1.0。

python · train_pretrain.py 训练循环(删节)
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 的任务。

💬2 · 监督微调 SFT必须 · ~1.1h / ¥1.4▶

目标:让模型适应多轮对话模板,理解 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 章可视化)。

🎯3 · LoRA 参数高效微调可选 · CPU 也能跑▶

目标:冻结基模,只训练低秩增量分支,用极小代价完成垂域适配(医学问答、自我认知等),保留通用能力。源码解读见第 04 章标签页⑦。

bash
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 全参微调,但需混入通用数据防止灾难遗忘。

⚖️4 · DPO 直接偏好优化(RLHF)可选 · off-policy▶

思路:SFT 后的模型只会"接龙",不知道什么回答好、什么差。DPO 用 chosen / rejected 偏好对直接最大化"好答案优于差答案"的对数几率——无需奖励模型、无需在线采样,off-policy 可以像监督学习一样反复跑 epoch。

𝓛DPO = −𝔼[ log σ( β·[ log(πθ(yw|x)/πref(yw|x)) − log(πθ(yl|x)/πref(yl|x)) ] ) ]
python · train_dpo.py(β 默认 0.15)
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)

🏗️5 · PPO 近端策略优化(RLAIF)可选 · on-policy · 双网络▶

思路:Actor(策略)实时采样回答,Critic(价值网络)估计优势,KL 约束防跑偏。需要奖励信号——MiniMind 采用 InternLM2-1.8B-Reward 奖励模型给出的连续分数(约 -2.5 ~ +3.0)。

𝓛PPO = −𝔼[ min(rt·At, clip(rt, 1−ε, 1+ε)·At) ] + β·𝔼[KL]

关键实现: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 算法的共同特征。

⚠️ 两个坑① 小模型在 R1 风格数学题上会遇到奖励稀疏:回答全错 → 奖励全零 → 梯度消失(如同让小学生做高考题)。连续奖励模型即使全错也能区分"-3.0 和 -2.8",保住非零梯度。② PPO 双网络联合优化收敛慢、显存约为单网络方法的 1.5–2 倍,训练曲线上 reward 提升缓慢。

📄 论文:PPO (Schulman et al., 2017)

👥6 · GRPO 组相对策略优化可选 · 单网络 · 推荐▶

思路(DeepSeekMath 提出、R1 带火):同一问题采样 N 个回答,用组内平均奖励当基线——高于均值的被鼓励、低于的被抑制,彻底去掉 Critic 网络。单网络训练更稳、收敛上限更高,MiniMind 实验中 reward 平稳上升到 4 左右。

Ai,j = (Ri,j − μi) / (σi + ε) (组内归一化优势)

实现中的奖励是"规则分 + 模型分"混合:回答长度适中(20~800 字符)±0.5、思考内容长度适中 ±1.0、</think> 恰好出现一次 +0.25、重复内容扣分,再叠加奖励模型的连续分——这正好呼应了本章末尾"奖励信号怎么选"的混合策略。

python · train_grpo.py(ε=0.2)
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 限制在能力边界内。

📄 论文:GRPO / DeepSeekMath (Shao et al., 2024)

✂️7 · CISPO 裁剪重要性采样可选 · GRPO 的 loss 变体▶

思路:PPO/GRPO 里 ratio 被 clip 后梯度流也被硬截断。CISPO 只做一个极小改动:把策略项改写成「裁剪权重 × log 概率」,ratio 截断但梯度路径保住。

𝓛CISPO = −𝔼[ min(rt, εhigh) · At · log πθ(at|s) − β·KLt ]

实现上只是 train_grpo.py --loss_type cispo(且这是默认值),分组采样、奖励计算、优势构造全部复用 GRPO 逻辑。

📄 论文:CISPO — MiniMax-M1 (2025)

🔧8 · Agentic RL 多轮工具调用强化学习🔥 2026 新增 · train_agent.py▶

思路:不再是"单轮问答即时打分",而是多轮轨迹级 RL:模型生成 tool_call → 执行工具 → observation 拼回上下文 → 继续生成,循环直到任务完成,最后对整条轨迹结算一次延迟奖励。

R(τ) = Ranswer + Rtool + Rformat + Rrm − Runfinished

源码里的奖励明细(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 的雏形(当前为同步模式)。

bash · torch 或 sglang 两种 rollout
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
🫀9 · 知识蒸馏(黑盒 / 白盒)可选 · train_distillation.py▶

黑盒蒸馏:只学老师的输出文本(硬标签),本质是对 teacher 回答做 SFT。R1 / Qwen3 的回答、tool call、思维链数据都属此类——主线 SFT 数据里已大量混入。

白盒蒸馏:进一步拟合老师在 token 分布层面的偏好(软标签),学生学到"候选词之间的相对倾向":

𝓛whitebox = α·𝓛CE + (1−α)·T²·KL( ptT ∥ psT )

train_distillation.py 完整展示双模型加载、温度缩放、MoE↔Dense 组合蒸馏与断点续训,适合作为参考实现逐行读。

RL 算法对比总表

先分清两大范式,再看算法:

范式裁判是谁优点缺点
RLHF(如 DPO)人类偏好标注贴近真实人类偏好标注贵、效率低、难扩展
RLAIF(PPO / GRPO / CISPO / Agent)奖励模型 / 规则 / 环境全自动、可扩展、能在线试错可能偏离人类真实偏好(reward hacking)
算法策略项 f(rt)优势项 g(At)正则项 h(KL)训练模型数范式
DPOlog rw − log rl无显式优势(偏好隐式)隐含在 β 中1(前向参与 2)off-policy
PPOmin(r·A, clip(r,1±ε)·A)Critic / GAE 估计β·𝔼[KL]2(Actor+Critic)on-policy
GRPOmin(r·A, clip(r,1±ε)·A)组内归一化 (R−μ)/σβ·KLt(token级)1on-policy
CISPOclip(r,0,εhigh)·A·log πθ(R−μ)/σ(沿用GRPO)β·KLt1on-policy
💡 记忆口诀DPO 是"off-policy 的偏好对比",PPO 是"双网络 + 裁剪",GRPO 是"去掉 Critic 的组内竞赛",CISPO 是"GRPO 修了个 clip 截梯度的 bug"——全是统一框架的实例化。

训练工程细节

工程基建(所有脚本共享)

✅ 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

⚠️ 监控指标盯住奖励方差 Var(r):若持续接近 0,说明奖励稀疏,需换数据或奖励机制。

默认超参速查表(来自各脚本 argparse 默认值)

阶段学习率批量 / 轮数其他关键默认值
Pretrain5e-4(余弦退火至 10%)32 × 累积8 / 2 epochseq 340 · bf16 · 裁剪 1.0
Full SFT1e-516 / 2 epochseq 768 · 自动接 pretrain 权重
LoRA1e-432 / 10 epochrank 16 · 自动接 full_sft · seq 340
DPO4e-8(官方注:建议 ≤5e-8 防遗忘)4 / 1 epochβ=0.15 · 双模型前向 · seq 1024
PPOActor 3e-7 / Critic 5e-72 / 1 epochε=0.2 · kl 0.02 · GAE(γ=1.0, λ=0.95)
GRPO / CISPO3e-72 × 每题采 6 个回答 / 1 epochε=0.2 · loss_type 默认 cispo
Agent RL3e-72 × 每题采 4 条轨迹 / 1 epoch多轮 rollout · 延迟奖励 · seq 1024
蒸馏5e-632 / 6 epochCE+KL 混合 · 温度缩放 · 可 MoE↔Dense

📌 规律:越靠后的阶段学习率越小(预训练 5e-4 → SFT 1e-5 → RL 3e-7 量级),每个阶段都在"精修"而非"重塑"模型——这是复现训练时最值得记住的一条经验。

07

实验与评测

用数据说话:RL 到底带来了什么?小模型横评该怎么读?

Agent RL 带来了什么(20 道数学工具题实测)

同一批「先决定是否调工具、再把可验证结果做对」的数学 ToolUse 任务:

full_sft(SFT 后)
12/20
agent(CISPO 训练后)
17/20

错误从 8 道降到 3 道:例如 3**2 从答 8 → 答对 9,10**2 从答 13 → 答对 100。RL 后模型真正学会了"该调工具时调工具、用工具结果答题"。

⚠️ 但有代价:对齐税(Alignment Tax)agent 权重在通用问答上的事实性反而下降、幻觉更多——"工具任务做得更好,但开放问答更敢编"。后训练把某条能力线拉高时,几乎必然牺牲部分通用性,这是优化目标变窄的必然结果。做 ToolUse 选 agent 权重,做日常聊天选 full_sft。

另一组主观横评(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 / cmmluen: arc / piqa / obqa
minimind-364M24.89 / 25.3828.49 / 50.65 / 23.60
minimind-3-moe198M25.48 / 24.3227.74 / 50.71 / 26.20
minimind-3-exam(LoRA 格式对齐版)64M30.98 / 26.1235.61 / 56.26 / 24.20
SmolLM2-135M-Instruct135M24.44 / 24.7158.50 / 68.17 / 32.80
gpt2-medium360M23.18 / 25.0043.60 / 66.38 / 30.20
TinyLlama-1.1B-Chat1100M25.71 / 25.0354.80 / 74.43 / 35.60
📊 官方提醒:注意标准误obqa(500 题)单项标准误 ±1.9,两点以内差异分不出模型高下;ceval/piqa/siqa ±1.2 左右。这张表更大的价值是让你理解"评测的分辨率",而非排名本身。
📈 顺带搞懂 PPL 与 BPBPPL(困惑度)= exp(平均交叉熵),可以理解为"模型对下一个词的平均犹豫程度",越低越好;但它按 token 统计——tokenizer 不同,PPL 就不可直接比较,此时改用 BPB(Bits Per Byte,每字节比特数)才公平。下面 YaRN 外推实验测的正是不同文本长度下的 PPL。

彩蛋:minimind-3-exam 仅用 LoRA 做了"答题格式对齐"(不注入知识、无数据污染),7 项平均就提升约 2.9 个百分点——说明小模型的瓶颈未必在知识,也可能只是输入格式没对齐。而一旦在有交集的数据上微调,ceval 可以刷到 97%,但毫无参考意义(数据污染)。

长文本:YaRN 外推实测(用不同长度《西游记》文本测 PPL),开启 rope scaling 后长文本 PPL 显著下降。

08

部署与生态

训练好的模型不止能跑 CLI:一行命令接入 OpenAI 兼容 API,或塞进 ollama / vllm / llama.cpp / 手机。

🖥️ OpenAI 兼容 API 服务

bash
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 格式为主。

⚙️ 三方推理引擎一键上

bash
# 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 量化
🌍 姊妹项目宇宙MiniMind-V(视觉多模态)· MiniMind-O(全双工 Omni)· MiniMind-dLM(离散扩散语言模型)· MiniMind-Linear(线性注意力)——后两者可在主线 AR 模型上续训(见仓库 Discussions #618 / #704)。
09

学习路线与常见问题

给不同目标读者的路线图,以及最常被问到的问题。

推荐学习路径

第 1 步跑通 Zero 模型:pretrain_t2t_mini + sft_t2t_mini,单卡约 2.3h,亲眼看到 loss 下降和第一次对话。
第 2 步逐行读 model_minimind.py:只有约 290 行。按本平台第 03/04 章顺序:Config → RMSNorm → RoPE → Attention → FFN → MoE → Block → ForCausalLM → generate。
第 3 步读数据集与 SFT:理解 lm_dataset.py 里 label = -100 的掩码逻辑与 chat_template 展开(第 05 章可视化)。
第 4 步玩垂域微调:改 100 条自我认知数据跑 LoRA,再 convert_model 合并导出,体验"自己的模型"。
第 5 步攻克 RL:从 DPO(最简单)→ GRPO → CISPO → train_agent,对照第 06 章统一框架逐个击破。
第 6 步向外延伸:部署 API 接入自己的 UI;读 Discussions 里的 dLM / 线性注意力实验;读 MobileLLM / DeepSeekMath / CISPO 原论文。

高频问题

❓Q1 · 为什么不重新训练一个更大的 tokenizer?▶

三个理由:① 词表直接决定 Embedding + 输出层参数占比,6400 词表是 26M 小模型能存在的前提;② 词表一变,权重、数据格式、推理接口、社区生态兼容性全部报废;③ tokenizer 还影响 PPL 这类按 token 统计的指标——跨 tokenizer 比较时 BPB(Bits Per Byte)更公平。官方明确建议:别重训,沿用即可。

❓Q2 · MoE 不是应该更快吗,为什么这里反而慢 50%?▶

"MoE 推理更快"的前提是融合 kernel。原生实现里 token 要先按专家分桶、再逐个专家 forward,kernel 启停与调度开销急剧变重。要提速得靠 Triton 自定义 kernel / DeepSpeed-MoE / Megatron-LM。MiniMind 为保持"纯 PyTorch 普适性"选择了 4 experts / top-1 的甜点折中。

❓Q3 · 强化学习训完,模型为什么有时"变笨"了?▶

这就是对齐税 / reward hacking:RL 优化的是"当前奖励定义下的分数",模型会越来越擅长迎合奖励,但不等价于整体能力无损提升——agent 权重工具题从 60% 涨到 85% 的同时,通用问答的事实性在下降。业界所有后训练模型都存在,只是程度差异。按用途选权重即可。

❓Q4 · 小模型做 RL 最容易踩什么坑?▶

奖励稀疏排第一:模型太弱,在超纲任务(如 MATH500 + 二元对错奖励)上所有 rollout 全错、奖励全零、优势归零、梯度消失。解法:用连续分数的奖励模型(-2.5~+3.0 即使全错也能分出高下)、把任务限制在能力边界内、混合规则奖励,并监控 Var(r) 不要趋近 0。其次注意 GRPO 的退化组(组内奖励方差≈0 则无信号)。

❓Q5 · Zero 模型到底能达到什么水平?▶

官方保留了早期 Zero 样例:能进行基础中文对话(介绍自己、推荐美食、解释概念),但事实知识与泛化有限,英文接近乱码。它的价值在于验证"个人从 0 训练 LLM"路线完全可行——要更强效果,用 14GB 主线数据完整复现 minimind-3 即可。

随堂小测验 · 检验学习成果

MiniMind 互动知识平台 · 基于开源项目 jingyaogong/minimind(Apache-2.0)整理制作 · 数据截至 2026-09

引用格式:@misc{minimind, title={MiniMind: Train a Tiny LLM from Scratch}, author={Jingyao Gong}, year={2024}}

本页面为独立学习笔记,所有代码摘录版权归原作者;命令与数据以官方仓库最新 README 为准。