01-环境搭建与项目导览

阶段 1：环境搭建与项目导览

教学目标

完成 MiniMind 项目的本地环境搭建
理解项目的整体目录结构和模块划分
成功运行预训练模型的推理，体验完整交互
建立 LLM 训练全流程的全局认知

课时安排

理论讲解：1 课时（项目背景 + 全流程概览）
上机实践：1 课时（环境搭建 + 推理体验）

1.1 项目背景与技术选型

什么是 MiniMind？

MiniMind 是一个从零开始训练的超小型语言模型项目，由开发者 jingyaogong 开源维护。其核心设计理念是"大道至简"------用最少的代码、最低的成本，覆盖大语言模型训练的完整技术栈。

核心技术特性

特性	说明
纯 PyTorch 实现	无黑盒封装，无第三方训练框架依赖（如 DeepSpeed、Megatron），每一行代码都可阅读理解
完整训练链路	Tokenizer → Pretrain → SFT → LoRA → DPO → PPO/GRPO/CISPO → Agentic RL，全流程覆盖
极低成本	单卡 RTX 3090，约 2 小时完成快速复现，成本约 3 元人民币
多模型变体	Dense（64M）和 MoE（198M-A64M）两种架构
多框架兼容	支持 vLLM、ollama、llama.cpp、SGLang、transformers 推理
OpenAI API 兼容	可直接接入 FastGPT、Open-WebUI、Dify 等 RAG 应用
Apache 2.0 开源	无许可证限制，可自由修改和分发

模型演进历史

版本	参数量	发布时间	主要更新
minimind-v1	108M	2024.09.01	初始版本，基础训练链路
minimind-v1-small	26M	2024.08.28	最小模型，CPU 可推理
minimind-v1-moe	4×26M	2024.09.17	首个 MoE 变体
minimind2	104M	2025.04.26	架构优化，增加 RL 算法
minimind2-small	26M	2025.04.26	v2 最小版本
minimind2-moe	145M	2025.04.26	v2 MoE 变体
minimind-3	64M	2026.04.01	对齐 Qwen3，GQA + RoPE + SwiGLU
minimind-3-moe	198M-A64M	2026.04.01	对齐 Qwen3-MoE，Agentic RL

与其他小型 LLM 项目对比

项目	参数量	纯 PyTorch	训练链路完整度	教学适合度
MiniMind	64M	是	完整（8 个阶段）	极高
nanoGPT	~10M	是	仅预训练	低（仅覆盖预训练）
lit-llama	varies	是	仅预训练+微调	中
SmolLM2	135M	部分	仅预训练	中

1.2 环境搭建

1.2.1 系统要求

组件	推荐配置	最低配置
操作系统	Ubuntu 20.04+ / Windows 10+	Ubuntu 18.04+
Python	3.10.x	3.9+
CUDA	12.2+	11.8+
GPU 显存	24GB（RTX 3090/4090）	12GB（RTX 3060）
系统内存	32GB	16GB
硬盘空间	50GB	30GB

注意：如果仅做推理（不训练），RTX 3060（12GB）即可满足。完整训练流程推荐 24GB 显存。

1.2.2 安装步骤

第一步：创建虚拟环境

bash 复制代码

# 使用 conda 创建环境（推荐）
conda create -n minimind python=3.10 -y
conda activate minimind

# 或使用 venv
python -m venv minimind_env
source minimind_env/bin/activate  # Linux/Mac
# Windows:
# minimind_env\Scripts\activate

第二步：安装 PyTorch（CUDA 版本）

bash 复制代码

# CUDA 12.2 版本（推荐）
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu122

# 验证 GPU 可用
python -c "import torch; print(f'CUDA available: {torch.cuda.is_available()}'); print(f'GPU: {torch.cuda.get_device_name(0)}')"

预期输出：

plain 复制代码

CUDA available: True
GPU: NVIDIA GeForce RTX 3090

第三步：克隆项目并安装依赖

bash 复制代码

git clone --depth 1 https://github.com/jingyaogong/minimind
cd minimind
pip install -r requirements.txt -i https://mirrors.aliyun.com/pypi/simple

--depth 1** 说明**：浅克隆仅下载最新版本，不包含完整 git 历史，下载更快。如需完整历史，去掉该参数。

第四步：下载预训练模型

bash 复制代码

# 使用 ModelScope 下载（国内推荐）
pip install modelscope
modelscope download --model gongjy/minimind-3 --local_dir ./minimind-3

# 或使用 HuggingFace 下载
pip install huggingface_hub
huggingface-cli download jingyaogong/minimind-3 --local-dir ./minimind-3

第五步：下载小规模数据集（用于快速复现训练）

bash 复制代码

# 创建数据集目录
mkdir -p dataset

# 从 ModelScope 下载 mini 数据集
modelscope download --model gongjy/minimind_dataset \
  --include "pretrain_t2t_mini.jsonl" \
  --include "sft_t2t_mini.jsonl" \
  --local_dir ./dataset

# 如需完整数据集（后续阶段使用）
modelscope download --model gongjy/minimind_dataset --local_dir ./dataset

数据集文件说明：

文件名	大小	用途
`pretrain_t2t_mini.jsonl`	1.2GB	预训练（推荐快速复现）
`pretrain_t2t.jsonl`	10GB	预训练（完整训练）
`sft_t2t_mini.jsonl`	1.6GB	监督微调（推荐快速复现）
`sft_t2t.jsonl`	14GB	监督微调（完整训练）
`dpo.jsonl`	53MB	DPO 偏好对齐训练
`rlaif.jsonl`	24MB	RLAIF 强化学习训练
`agent_rl.jsonl`	86MB	Agentic RL 训练

1.2.3 环境验证

运行以下脚本验证安装是否成功：

bash 复制代码

python -c "
import torch
from model.model import MiniMindModel, ModelArgs

# 检查 PyTorch 和 CUDA
print(f'PyTorch version: {torch.__version__}')
print(f'CUDA available: {torch.cuda.is_available()}')

# 尝试创建模型
args = ModelArgs()
model = MiniMindModel(args).to('cuda')
total_params = sum(p.numel() for p in model.parameters())
print(f'Model params: {total_params / 1e6:.1f}M')
print('Environment setup OK!')
"

1.3 项目结构导览

1.3.1 目录结构

克隆完成后，项目根目录结构如下：

plain 复制代码

minimind/
├── model/                      # 模型定义（核心代码）
│   ├── model.py               # 主模型类 MiniMindModel + ModelArgs
│   ├── transformer.py         # Transformer 层实现（Attention, MLP, Block 等）
│   ├── moe.py                 # MoE 混合专家模型实现
│   └── generation.py         # 生成策略（Greedy, Top-K, Top-P, Beam Search）
│
├── trainer/                    # 训练脚本
│   ├── train_pretrain.py      # 预训练脚本
│   ├── train_full_sft.py      # 全量 SFT 微调脚本
│   ├── train_lora.py          # LoRA 微调脚本
│   ├── train_distillation.py  # 知识蒸馏脚本
│   ├── train_dpo.py            # DPO 偏好对齐脚本
│   ├── train_ppo.py            # PPO 强化学习脚本
│   ├── train_grpo.py           # GRPO/CISPO 强化学习脚本
│   └── train_agent.py          # Agentic RL 训练脚本
│
├── dataset/                    # 数据集目录（需单独下载）
│   ├── pretrain_t2t_mini.jsonl
│   ├── sft_t2t_mini.jsonl
│   ├── dpo.jsonl
│   └── ...
│
├── scripts/                    # 工具脚本
│   ├── web_demo.py            # Streamlit Web 演示界面
│   ├── serve_openai_api.py    # OpenAI 兼容 API 服务
│   ├── convert_model.py       # 模型格式转换（LoRA 合并 / torch→transformers）
│   └── ...
│
├── out/                        # 训练输出目录（自动生成）
│   ├── pretrain_768.pth       # 预训练 checkpoint
│   ├── full_sft_768.pth       # SFT checkpoint
│   └── ...
│
├── eval_llm.py                 # CLI 推理评估脚本
├── eval_toolcall.py            # Tool Call 测试脚本
├── eval_clip.py                 # CLIP 评测脚本
├── requirements.txt             # Python 依赖
├── project.config              # 项目配置文件
└── README.md                   # 项目说明文档

1.3.2 核心模块关系图

plain 复制代码

                    ┌──────────────────┐
                    │   ModelArgs      │
                    │ (超参数配置)      │
                    └────────┬─────────┘
                             │
                    ┌────────▼─────────┐
                    │ MiniMindModel    │
                    │ (主模型入口)      │
                    └────────┬─────────┘
                             │
              ┌──────────────┼──────────────┐
              │              │              │
     ┌────────▼──────┐ ┌────▼─────┐ ┌──────▼────────┐
     │ RMSNorm       │ │ Token    │ │ Transformer   │
     │ (归一化层)     │ │ Embedding│ │ Blocks × N    │
     └──────────────┘ └──────────┘ └──────┬─────────┘
                                        │
                              ┌─────────▼──────────┐
                              │  TransformerBlock   │
                              └─────────┬──────────┘
                                        │
                     ┌──────────────────┼──────────────────┐
                     │                  │                  │
            ┌────────▼──────┐  ┌───────▼──────┐  ┌───────▼──────┐
            │  Attention    │  │    MLP       │  │  RMSNorm     │
            │  (GQA+RoPE)   │  │  (SwiGLU)    │  │  (Pre-Norm)   │
            └───────────────┘  └──────────────┘  └──────────────┘

1.3.3 训练脚本调用关系

plain 复制代码

train_pretrain.py ──────────> model/model.py (MiniMindModel)
       │                            │
       │ 读取 dataset/              │ 前向计算 loss
       ▼                            ▼
pretrain_t2t_mini.jsonl     CrossEntropyLoss (next-token)
       │
       │ 保存
       ▼
out/pretrain_768.pth
       │
       ▼ 加载
train_full_sft.py ──────────> model/model.py
       │
       │ 读取
       ▼
sft_t2t_mini.jsonl
       │
       │ 保存
       ▼
out/full_sft_768.pth
       │
       ├──> train_lora.py (LoRA 微调)
       ├──> train_dpo.py   (DPO 对齐)
       ├──> train_ppo.py   (PPO 强化学习)
       ├──> train_grpo.py   (GRPO/CISPO)
       └──> train_agent.py (Agentic RL)

1.4 LLM 训练全流程概览

1.4.1 一张图理解全流程

plain 复制代码

原始文本数据
     │
     ▼
┌─────────────────┐
│  Tokenizer 训练  │   使用 BPE 算法，从语料中学习子词切分规则
│  (词汇表构建)     │   输出：minimind_tokenizer（6400 词表）
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│   预训练          │   目标：next-token prediction（下一个词预测）
│  (Pretrain)      │   输入：大规模无标注文本
│                  │   输出：pretrain_768.pth（学会语言规律）
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  监督微调        │   目标：学会听指令、回答问题
│  (SFT)           │   输入：问答对话数据（conversations 格式）
│                  │   输出：full_sft_768.pth（具备对话能力）
└────────┬────────┘
         │
         ├──> LoRA 微调（低成本适配特定任务）
         │
         ├──> 知识蒸馏（从大模型迁移知识）
         │
         ▼
┌─────────────────┐
│  强化学习对齐    │   目标：对齐人类偏好，提升回答质量
│  (RLHF/RLAIF)   │   算法：DPO / PPO / GRPO / CISPO
│                  │   输出：dpo/ppo/grpo_768.pth
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Agentic RL     │   目标：学会使用工具、多轮交互
│  (Agent 训练)    │   算法：CISPO + 多轮 Tool-Use
│                  │   输出：agent_768.pth
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  部署推理        │   方式：OpenAI API / vLLM / ollama / llama.cpp
│  (Deployment)   │   用途：集成到 RAG、Agent 等应用
└─────────────────┘

1.4.2 各阶段核心区别

阶段	训练目标	数据类型	损失函数	训练时长
Pretrain	预测下一个词	无标注文本	Cross-Entropy	~1.2 小时
SFT	生成正确回答	问答对话	Cross-Entropy	~1.1 小时
LoRA	适配特定任务	任务相关数据	Cross-Entropy	~0.5 小时
DPO	区分好坏回答	偏好对（chosen/rejected）	DPO Loss	~0.3 小时
PPO	最大化奖励	奖励模型打分	PPO Loss	~0.5 小时
GRPO	最大化奖励（组归一化）	规则奖励	GRPO Loss	~0.5 小时

1.5 快速推理体验

1.5.1 CLI 推理

bash 复制代码

# 使用下载的预训练模型进行推理
python eval_llm.py --load_from ./minimind-3

# 交互式对话（输入问题，模型生成回答）
# 示例：
# >>> 请介绍一下 Transformer 架构
# >>> 1+1等于几？
# >>> 用 Python 写一个快速排序

1.5.2 自适应思考模式（Open Thinking）

bash 复制代码

# 开启思考模式，模型会先输出思考过程再给出答案
python eval_llm.py --load_from ./minimind-3 --open_thinking 1

开启思考模式后，模型输出格式示例：

plain 复制代码

<think{
"step": "分析用户问题，这是一个关于...的问题",
"reasoning": "我需要从以下几个角度来回答...",
"conclusion": "因此，答案是..."
}>

根据以上分析，具体回答如下：...

1.5.3 Web Demo

bash 复制代码

cd scripts
streamlit run web_demo.py

浏览器中访问 http://localhost:8501，可以体验：

多轮对话
思考过程展示
工具调用功能
参数调节（temperature、top_p 等）

1.5.4 使用 Ollama 部署（可选）

bash 复制代码

# 安装 ollama 后，直接拉取模型
ollama run jingyaogong/minimind-3

1.5.5 使用 vLLM 高性能推理（可选）

bash 复制代码

pip install vllm
vllm serve ./minimind-3 --served-model-name "minimind"

然后通过 OpenAI 兼容接口调用：

bash 复制代码

curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimind",
    "messages": [{"role": "user", "content": "你好"}],
    "max_tokens": 512
  }'

1.6 配置文件说明

MiniMind 使用 project.config 进行统一配置管理。关键配置项：

properties 复制代码

[model]
dim = 768                 # 模型隐藏维度
n_layers = 8              # Transformer 层数
n_heads = 8               # 注意力头数（Q）
n_kv_heads = 4            # KV 头数（GQA）
vocab_size = 6400          # 词表大小
max_seq_len = 32768        # 最大序列长度
rope_base = 1000000        # RoPE 基数

[training]
batch_size = 64            # 批次大小
learning_rate = 3e-4       # 学习率
warmup_steps = 200         # 学习率预热步数
max_epochs = 10            # 最大训练轮数

[data]
pretrain_data = dataset/pretrain_t2t_mini.jsonl
sft_data = dataset/sft_t2t_mini.jsonl

教学提示：后续各阶段的训练脚本会引用该配置文件。修改配置时注意保持一致。

实践任务

任务 1.1：环境搭建验证（必做）

完成以下操作并截图记录：

成功创建并激活 Python 虚拟环境
验证 CUDA 可用（运行 PyTorch GPU 检测脚本）
克隆 MiniMind 项目并安装依赖
下载 minimind-3 预训练模型
运行模型创建验证脚本，确认输出 Environment setup OK!

任务 1.2：推理体验（必做）

使用至少 2 种方式与模型交互：

CLI 推理：使用 eval_llm.py 与模型进行 3 轮以上对话
Web Demo：启动 Streamlit 界面，体验多轮对话
（可选）Ollama 或 vLLM 推理

思考题：

模型的回答质量如何？哪些类型的问题回答得较好？
对比开启 --open_thinking 前后的输出差异，思考过程对回答质量有什么影响？

任务 1.3：项目结构梳理（必做）

打开 model/model.py，找到 MiniMindModel 类和 ModelArgs 类
理解 ModelArgs 中每个参数的含义（对照本阶段的配置文件说明）
在 model/transformer.py 中找到 Attention、FeedForward、TransformerBlock 类
画出你认为的模型架构图，标注每个组件的输入输出

挑战任务（选做）

修改 project.config 中的模型参数（如 n_layers、dim），观察对模型大小和推理速度的影响
尝试用 modelscope 或 huggingface-cli 下载完整数据集

下一阶段预告

在阶段 2 中，我们将深入学习 Tokenizer 的原理与实现，理解文本如何变成模型能处理的数字序列，并亲手用 MiniMind 的 Tokenizer 对文本进行编码和解码实验。