MiniMind 项目详细说明文档

项目概述

1.1 项目简介

MiniMind 是一个开源的超轻量级大语言模型（LLM）训练项目，旨在让所有人都能用极低成本从零开始训练一个功能完整的语言模型。项目完全开源，涵盖了从数据准备、Tokenizer 训练到预训练（Pretrain）、监督微调（SFT）、强化学习对齐（RLHF/RLAIF）、知识蒸馏、推理模型训练的全流程。

1.2 项目目标

• 降低 LLM 学习门槛，让初学者也能理解大模型的完整训练流程
• 提供可运行、可复现的最小完整实现
• 作为 LLM 技术的教学和研究平台

1.3 模型变体

模型架构

2.1 整体架构

MiniMind 基于 Transformer Decoder-Only 架构，参考 Llama3.1 的设计，是一个标准的自回归语言模型。

2.2 模型配置

hidden_size: 512 / 768          # 隐藏层维度
num_hidden_layers: 8 / 16       # Transformer 层数
num_attention_heads: 8          # 注意力头数
num_key_value_heads: 2          # KV头数（GQA）
vocab_size: 6400                # 词表大小
max_position_embeddings: 32768  # 最大位置长度
rope_theta: 1000000.0           # RoPE 基频

2.3 核心组件详解

• RMSNorm（均方根归一化）：替代传统 LayerNorm，去除均值中心化步骤，仅保留缩放操作，计算更高效。
• RoPE（旋转位置编码）：使用旋转矩阵对 Query 和 Key 进行位置编码。支持通过 YaRN 算法进行长度外推（scale=32, alpha=1, beta=32, mscale=0.707）。
• GQA（分组查询注意力）：使用 8 个 Query 头但只有 2 个 KV 头，每 4 个 Query 头共享 1 组 KV，减少 KV Cache 内存占用，推理速度提升。
• SwiGLU 前馈网络：采用 SwiGLU 门控机制 FFN(x) = W2 * (SiLU(W1 * x) * W3 * x)。
• MoE（混合专家）架构：基于 DeepSeek-V2/V3 设计，4 个路由专家 + 1 个共享专家，每个 token 选择 Top-2 路由专家。

训练流程

MiniMind 提供完整的训练 pipeline，从数据准备到最终模型部署：

3.1 Tokenizer 训练

文件：trainer/train_tokenizer.py

使用 HuggingFace tokenizers 库训练 BPE（Byte-Pair Encoding）分词器：

• 词表大小：6400
• 特殊 token：<unk>, <s>, </s>
• 训练数据：tokenizer_train.jsonl
• 设计理念：极小词表保持模型轻量，同时覆盖常用中英文字符

3.2 预训练（Pretrain）

文件：trainer/train_pretrain.py

在大规模无标注文本上进行自回归语言建模：

关键技术：支持 DDP 多卡训练、混合精度训练（AMP + bf16）、Cosine 学习率调度（含 warmup）、断点续训、梯度裁剪。

3.3 监督微调（SFT）

文件：trainer/train_full_sft.py

使用指令-回答对数据进行全参数微调：

数据格式为多轮对话，包含 system / user / assistant 角色。

3.4 LoRA 微调

文件：trainer/train_lora.py + model/model_lora.py

使用低秩适配器进行参数高效微调，完全自定义实现（非 peft 库）：

• 仅对方形 Linear 层添加 LoRA 适配器
• 冻结所有非 LoRA 参数
• LoRA rank = 16
• 训练参数量极少，适合低资源场景

3.5 DPO（直接偏好优化）

文件：trainer/train_dpo.py

无需奖励模型的偏好对齐方法，使用 chosen/rejected 数据对，通过对比学习优化策略模型。默认参数：batch_size=4, lr=4e-8, beta=0.1。

3.6 RLAIF（AI反馈强化学习）

项目从零实现了三种 RLAIF 算法：

• PPO（近端策略优化）：经典 RLHF 算法，包含 Actor、Critic、Old Actor、Reference Model 四个模型，使用 GAE 计算优势函数，奖励模型使用 InternLM2-1.8B-Reward。（381行）
• GRPO（组相对策略优化）：来自 DeepSeek 的创新算法，无需 Critic 网络，对同一 prompt 采样多个回答（group_size=4），使用组内相对排名计算优势值。（304行）
• SPO（单流策略优化）：来自腾讯（2025.09）的实验性算法，使用 AutoAdaptiveValueTracker，Beta 分布建模基线值，单流架构。（354行）

3.7 知识蒸馏

文件：trainer/train_distillation.py

白盒知识蒸馏：Loss = α × CE_Loss + (1-α) × KL_Loss。温度参数 T=2.0，权重 α=0.3。

3.8 推理模型训练

文件：trainer/train_reason.py

训练具有思维链能力的推理模型，使用 <think> 和 <answer> 特殊标记，对特殊标记施加 10倍 loss 权重强化格式遵循。

数据集

4.1 数据类型

4.2 数据格式

# 预训练数据
{"text": "这是一段无标注的训练文本..."}

# SFT数据
{"conversations": [
  {"role": "user", "content": "问题"},
  {"role": "assistant", "content": "回答"}
]}

# DPO数据
{"prompt": "问题", "chosen": "好的回答", "rejected": "差的回答"}

4.3 Dataset 类实现

文件：dataset/lm_dataset.py

提供四个数据集类：

• PretrainDataset：预训练数据加载，支持随机截断
• SFTDataset：SFT 数据加载，支持多轮对话和随机系统提示词
• DPODataset：DPO 数据加载，同时返回 chosen 和 rejected
• RLAIFDataset：RLAIF 数据加载，仅返回 prompt

推理与部署

5.1 命令行推理

文件：eval_llm.py

支持 PyTorch 原生格式（.pth）和 Transformers 格式两种推理方式，具备流式输出、多轮对话、LoRA 加载等功能。

5.2 OpenAI 兼容 API 服务

文件：scripts/serve_openai_api.py

基于 FastAPI 的 API 服务器，完全兼容 OpenAI Chat Completion API，支持流式（SSE）和非流式响应，端点 POST /v1/chat/completions，默认端口 8998。

5.3 Streamlit Web UI

文件：scripts/web_demo.py

基于 Streamlit 的聊天界面，支持本地模型直接加载和 API 模式连接，多轮对话，参数调节。

5.4 模型格式转换

文件：scripts/convert_model.py

支持 PyTorch 与 Transformers 格式互转，兼容 MiniMind 和 Llama 两种格式映射。

5.5 第三方生态兼容

工程细节

6.1 训练工具函数

文件：trainer/trainer_utils.py

提供共用工具：学习率调度器（Cosine Annealing with Warmup）、DDP 初始化、随机种子设置、Xavier 均匀初始化 + Embedding 正态初始化、Checkpoint 管理、SkipBatchSampler（断点续训跳过已训练批次）。

6.2 Chat Template

文件：MiniMind2/chat_template.jinja

支持 system / user / assistant / tool 四种角色、工具调用（Tool Calling）、思考模式。

6.3 核心依赖

torch==2.6.0
transformers==4.57.1
streamlit==1.50.0
swanlab==0.6.8          # 实验追踪
fastapi + uvicorn       # API服务

快速开始

环境准备

git clone https://github.com/jingyaogong/minimind.git
cd minimind
pip install -r requirements.txt

命令行对话

python eval_llm.py

启动 API 服务

python scripts/serve_openai_api.py

启动 Web UI

streamlit run scripts/web_demo.py

从零训练完整流程

# 1. 训练 Tokenizer
python trainer/train_tokenizer.py

# 2. 预训练
python trainer/train_pretrain.py

# 3. 监督微调
python trainer/train_full_sft.py

# 4. LoRA 微调（可选）
python trainer/train_lora.py

# 5. DPO 对齐（可选）
python trainer/train_dpo.py

# 6. RLAIF（可选）
python trainer/train_ppo.py    # 或 train_grpo.py / train_spo.py

# 7. 知识蒸馏（可选）
python trainer/train_distillation.py

# 8. 推理模型训练（可选）
python trainer/train_reason.py

项目结构

minimind/
├── model/
│   ├── model_minimind.py     # 核心模型定义
│   └── model_lora.py         # LoRA 实现
├── trainer/
│   ├── train_tokenizer.py    # Tokenizer 训练
│   ├── train_pretrain.py     # 预训练
│   ├── train_full_sft.py     # 全参数SFT
│   ├── train_lora.py         # LoRA微调
│   ├── train_dpo.py          # DPO对齐
│   ├── train_ppo.py          # PPO算法
│   ├── train_grpo.py         # GRPO算法
│   ├── train_spo.py          # SPO算法
│   ├── train_distillation.py # 知识蒸馏
│   ├── train_reason.py       # 推理模型训练
│   └── trainer_utils.py      # 训练工具函数
├── dataset/
│   └── lm_dataset.py         # 数据集类定义
├── scripts/
│   ├── serve_openai_api.py   # OpenAI API服务
│   ├── web_demo.py           # Streamlit WebUI
│   ├── convert_model.py      # 模型格式转换
│   └── chat_openai_api.py    # API客户端
├── eval_llm.py               # 推理/对话脚本
├── requirements.txt           # 依赖列表
└── README.md                  # 项目说明

总结

MiniMind 是目前最完整、最轻量的开源 LLM 教学项目之一。它用极简的代码和极低的成本，完整复现了大语言模型从数据到部署的全流程。无论你是 AI 初学者还是研究者，都能从中获得深刻的理解和实践经验。

项目地址：https://github.com/jingyaogong/minimind

本文档基于 MiniMind 项目源码深度分析生成，涵盖全部核心模块和训练流程。