LLM 微调与后训练入门项目

这是一个面向初学者的 LLM 学习仓库，所有核心教学内容都以 Jupyter Notebook（.ipynb）形式组织。

项目采用双路线设计：

基础线：帮助你从环境配置、预训练模型使用、SFT、LoRA、量化、部署一路走通
进阶线：帮助你从奖励建模、偏好数据到 PPO / DPO / ORPO / KTO / GRPO 等后训练对齐算法建立系统理解

每个重点 notebook 都尽量保持同一教学节奏：

背景与目标 -> 手动推导 -> 纯 PyTorch toy 计算 -> 调包小 demo -> 结果对照 -> 常见坑 -> 小结 / 练习

设计目标

默认目标硬件：单卡 RTX 5080，16GB 显存
默认目标：仓库中的 notebook 都可以在这个硬件上以“小规模教学配置”运行
代码资产仍以 .ipynb 为主，不把主教学逻辑迁移成 .py 包结构
对复杂算法先讲“为什么”，再讲“怎么调包跑出来”

适合谁

想系统入门大模型工程实践的同学
希望用 Notebook 边学边跑的同学
已经会一点 Transformers / PEFT，想继续补后训练对齐主线的同学
想把“手动理解原理”和“工程上手 demo”放在一个仓库里对照学习的同学

3 分钟选学指南

如果你是第一次点进这个仓库，不一定需要按 01 -> 15 全部顺序跑。可以先按自己的目标选路径：

你的目标	建议先看	为什么这样安排
第一次系统学 LLM	`01 -> 02 -> 02b -> 03`	先把环境、表示原理、预训练闭环和最基础的下游训练链路建立起来。
只有 `1` 小时，想先建立全局图	`01 -> 02 -> 07`	这样最快能看到“预训练模型怎么用”和“后训练全景图”。
只关心微调实战	`01 -> 03 -> 04 -> 05`	这条线最适合先建立 SFT、LoRA、量化的工程直觉。
只关心 RLHF / 对齐	`01 -> 04 -> 07 -> 08 -> 09 -> 11 -> 12`	先把 LoRA 和偏好数据准备好，再进入奖励建模和在线 / 离线对齐。
只想理解前沿，不急着复现	`07 -> 12 -> 13 -> 14 -> 15` + `docs/frontier_algorithm_tracker.md`	先掌握后训练主线，再看推理蒸馏、多模态、在线 RL 系统化扩展。
只有 CPU 或显存明显小于 `16GB`	`01` 的环境检测与显存估算、`02` 的手动部分、`05` 的手动量化、`07` 的算法地图	先把原理吃透，再择机迁移到有 GPU 的环境跑 demo。

项目结构

llm-finetuning-notebooks/
├── notebooks/
│   ├── 01_environment_setup.ipynb
│   ├── 02_pretrained_model_usage.ipynb
│   ├── 02b_causal_language_model_pretraining.ipynb
│   ├── 03_full_finetuning.ipynb
│   ├── 04_parameter_efficient_finetuning.ipynb
│   ├── 05_quantization_techniques.ipynb
│   ├── 06_deployment_inference.ipynb
│   ├── 07_post_training_overview.ipynb
│   ├── 08_reward_modeling.ipynb
│   ├── 09_dpo_orpo_alignment.ipynb
│   ├── 10_kto_alignment.ipynb
│   ├── 11_ppo_alignment.ipynb
│   ├── 12_grpo_alignment.ipynb
│   ├── 13_reasoning_distillation_and_open_r1.ipynb
│   ├── 14_multimodal_vlm_and_omni_overview.ipynb
│   └── 15_online_rl_variants_and_systems.ipynb
├── data/
│   ├── raw/
│   ├── processed/
│   └── README.md
├── assets/
│   └── figures/
├── requirements.txt
├── environment.yml
├── LICENSE
├── README.md
└── .gitignore

安装环境

仓库现在只维护一套统一环境，覆盖基础微调、LoRA/量化、部署 demo，以及 trl 相关的后训练对齐 notebook。

方式 1：venv + pip

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

方式 2：conda

conda env create -f environment.yml
conda activate llm

学习路径

路线 A：基础线

01_environment_setup.ipynb
02_pretrained_model_usage.ipynb
02b_causal_language_model_pretraining.ipynb
03_full_finetuning.ipynb
04_parameter_efficient_finetuning.ipynb
05_quantization_techniques.ipynb
06_deployment_inference.ipynb

路线 B：从基础微调到后训练对齐

01_environment_setup.ipynb
02_pretrained_model_usage.ipynb
03_full_finetuning.ipynb
04_parameter_efficient_finetuning.ipynb
07_post_training_overview.ipynb
08_reward_modeling.ipynb
09_dpo_orpo_alignment.ipynb
10_kto_alignment.ipynb
11_ppo_alignment.ipynb
12_grpo_alignment.ipynb

如果您已经理解了 SFT / PEFT，可以直接从 07_post_training_overview.ipynb 开始看。

每个 Notebook 在讲什么

建议先至少完成基础线中的 01 到 04，再进入进阶线。

07_post_training_overview.ipynb
08_reward_modeling.ipynb
09_dpo_orpo_alignment.ipynb
10_kto_alignment.ipynb
11_ppo_alignment.ipynb
12_grpo_alignment.ipynb

路线 C：可选前沿扩展

如果你已经理解了 07-12 的后训练主线，可以继续看这本可选扩展 notebook：

13_reasoning_distillation_and_open_r1.ipynb
14_multimodal_vlm_and_omni_overview.ipynb
15_online_rl_variants_and_systems.ipynb

一眼看全路线

如果你更喜欢先看一张静态图，再决定从哪里开始，可以先看上面的路线图。它主要帮助你快速区分：

哪些 notebook 属于基础工程主线
哪些 notebook 属于后训练对齐主线
哪些内容更适合作为前沿趋势扩展阅读

flowchart LR
    A["01 环境配置"] --> B["02 预训练模型使用"]
    B --> C["03 全参数微调"]
    C --> D["04 LoRA / PEFT"]
    B --> E["05 量化"]
    B --> F["06 部署与推理"]
    D --> G["07 后训练全景"]
    G --> H["08 奖励建模"]
    H --> I["09 DPO / ORPO"]
    H --> J["10 KTO"]
    H --> K["11 PPO"]
    H --> L["12 GRPO"]
    L --> M["13 推理蒸馏与 open-r1"]
    M --> N["14 多模态 VLM 与 Omni"]
    L --> O["15 在线 RL 变体与系统工程"]

可以把它粗略理解成三层：

01-06：先把“模型怎么加载、怎么微调、怎么压缩、怎么部署”走通
07-12：再把“人类偏好如何变成训练目标”建立成一条完整后训练主线
13-15：最后再把视野扩到推理蒸馏、多模态和更前沿的在线 RL 系统工程

学完后你会真正看到什么

这个仓库刻意不把目标写成“直接复现 SOTA”，而是让你在单卡 RTX 5080 16GB 上看到一批足够直观、足够有教学价值的结果。

学习路线	你能亲手看到的结果	为什么这很重要
`01-02` 基础入门	环境检测报告、tokenization 结果、embedding 形状变化、toy attention 权重	这会让你不再只把模型当黑盒，而是真的知道输入是怎么变成隐藏表示的。
`03` 全参数微调	IMDb 小子集上的 loss 变化、logits 与预测类别变化	这是“训练真的在发生”的第一现场，能帮你把交叉熵、梯度更新和模型行为连起来。
`04` LoRA / PEFT	可训练参数比例显著下降、LoRA 与全参微调的资源差异对照	这会让你直观看到“为什么大家都在用 PEFT”，而不只是背一个缩写。
`05` 量化	量化前后显存占用差异、输出质量与误差的基本对照	你会开始理解“为什么小显存也能跑模型”，以及这背后的代价是什么。
`06` 推理部署	greedy / top-k / top-p / temperature 输出差异、本地 API / Gradio demo	这一步会把“训练完的模型”真正变成一个能交互的应用原型。
`08-10` 离线对齐	chosen / rejected 分数差、Reward loss 变化、DPO / ORPO / KTO 不同监督方式带来的输出偏好变化	你会看到“人类偏好”怎样一步步变成模型可以学习的训练信号。
`11-12` 在线对齐	reward、advantage、ratio、KL、group reward 的 toy 计算与短训练反馈	这会帮你建立 PPO / GRPO 不是神秘黑魔法，而是可拆开的优化过程的直觉。
`13-15` 前沿扩展	open-r1 工作流地图、CLIP 图文匹配结果、在线 RL 变体与系统框架地图	这能帮你把“眼前的小 demo”连接到今天开源社区真正还在继续演化的方向。

如果你准备把这个仓库分享给别人，最值得展示的通常不是“跑了多少步”，而是这些肉眼可见的结果：

从 token 到 attention 的中间张量变化
微调前后预测或生成风格的变化
LoRA / 量化带来的资源节省
偏好对齐后 reward 或输出倾向的变化
多模态或在线 RL 扩展给出的新视角

这些结果都故意设计成“小规模也能看出趋势”，这是这个仓库和重型 benchmark 复现仓库最不一样的地方。

如果你准备把这个仓库公开给别人看，或者后面想把它整理成更好看的 GitHub 首页，可以继续看：

docs/showcase_capture_guide.md

这个小指南会帮你快速决定：

哪几本 notebook 最值得截图
哪几类结果最适合放首页
如果 README 里只能放 4 张图，应该优先选哪 4 张

如果你已经准备真的开始整理首页图位，而不只是想法层面规划，还可以继续看：

docs/homepage_gallery_template.md

这里面已经补好了：

推荐截图文件名
推荐图注文案
可以直接贴回 README 的 Markdown 模板

第一批示例图预览

下面这 4 张图已经作为第一批真实展示卡片落地，全部来自 notebook 里最轻量、最适合公开展示的手动部分。

原理拆解	单卡友好训练

`02` 用 toy tokenization 和 attention 把输入如何变成中间表示拆开来看。	`04` 用 LoRA 参数对比说明为什么 PEFT 对单卡实验这么重要。

对齐直觉	多模态扩展

`08` 把 chosen / rejected 分数差和 pairwise loss 变成肉眼可见的训练信号。	`14` 先用 patch / embedding / similarity 建立多模态直觉，再连接到 VLM / Omni。

这组图的定位不是“benchmark 结果截图”，而是“帮助第一次访问者一眼看懂这个仓库到底教什么、能跑出什么、为什么适合单卡 16GB 环境”。

展示导航

如果你现在不是想完整读 README，而是想先挑一组结果快速看，这里可以直接按目的进入：

想看首页最小精华：先看上面的 4 张核心预览图。
想看“训练与资源”：看 imdb_finetune_loss.png 和 quantization_memory_compare.png。
想看“后训练对齐”：看 offline_alignment_family_map.png、online_rl_ppo_grpo_compare.png、reasoning_distillation_open_r1_map.png。
想看“前沿扩展”：看 multimodal_evolution_map.png 和 online_rl_systems_map.png。
想看完整整理规则：看 docs/showcase_capture_guide.md 和 docs/homepage_gallery_template.md。

如果你还想补“训练变化”或“量化资源变化”这类更工程向的展示卡片，当前展示目录里也已经补上了。为了不让首页变成一长串文件名，这里按“训练 / 对齐 / 扩展”分成三组来看会更清楚：

展示分组	适合先看什么	对应卡片	它主要回答什么问题
训练与资源	想先确认“模型真的在学”，以及“单卡为什么还能跑”	`imdb_finetune_loss.png`、`quantization_memory_compare.png`	微调有没有真的发生、量化到底省了什么资源。
后训练对齐	想先把 `08-12` 的主线关系看懂	`offline_alignment_family_map.png`、`online_rl_ppo_grpo_compare.png`、`reasoning_distillation_open_r1_map.png`	离线对齐怎么分家、`PPO -> GRPO` 直觉上怎么变、推理蒸馏为什么会自然接在后训练后面。
前沿扩展	想先建立“多模态”和“系统工程”方向的全局图	`multimodal_evolution_map.png`、`online_rl_systems_map.png`	`CLIP -> VLM -> Omni` 为什么是一条连续路线，以及 `TRL / OpenRLHF / verl / open-r1` 分别更适合拿来理解什么。

如果你后面要发帖、做项目首页，或者单独向别人介绍这个仓库，最省事的做法通常不是把这 7 张图全部平铺出来，而是先选你这次最想强调的一组：

想强调“单卡也能学到真实训练直觉”，优先选“训练与资源”
想强调“这个仓库把 RLHF / 对齐讲成了完整主线”，优先选“后训练对齐”
想强调“这个仓库不只停在基础，还连到了今天的多模态和系统工程”，优先选“前沿扩展”

按时间预算开始

如果你只是第一次来到这个仓库，不一定要立刻按 01 -> 15 全部跑完。更省力的做法通常是先按时间预算选入口：

你现在有多少时间	最推荐的入口	你会先建立什么直觉
`10` 分钟	看上面的路线图、`4` 张核心预览图，再看“训练与资源”两张卡	先知道这个仓库教什么、为什么不是纯调包、为什么能围绕单卡 `16GB` 展开。
`30` 分钟	在上一步基础上，再看“后训练对齐”三张卡，并翻一下 docs/frontier_algorithm_tracker.md 里的“经典算法时间线”	快速建立 `SFT -> Reward Modeling -> DPO / PPO / GRPO` 这条后训练主线的大图。
`2` 小时	轻跑 `02` 的手动部分、`03` 的 IMDb 小子集关键单元、`08` 的 pairwise loss、`11` 的 PPO toy 计算、`14` 的 CLIP demo	不只是看展示图，而是真的亲手走一遍“预训练使用 -> 微调 -> 对齐 -> 多模态扩展”的小闭环。

如果你对在线 RL 的系统工程更好奇，可以在这条 2 小时路径最后补看 15_online_rl_variants_and_systems.ipynb 的系统地图部分。

如果你准备完整执行 notebook，而不是只做第一次浏览，再回到下面的索引表，按前置要求逐步走会更稳。

第一次真正动手：优先跑哪 3 本

如果你已经不只是想“看看这个仓库讲什么”，而是准备真正开始跑，最省力的做法通常不是从 01 一口气跑到 15，而是先完成一个最小闭环。

你的目标	最推荐先跑的 `3` 本	为什么这样更适合第一次动手
第一次完成一个最基础的训练闭环	`01 -> 02 -> 03`	这组会把“环境可用、模型会吃输入、训练真的发生”三件最关键的事先建立起来。
已经懂一点微调，想第一次碰对齐	`07 -> 08 -> 09`	先看全景图，再亲手算 reward / pairwise loss，最后再看 DPO / ORPO 怎样把偏好数据变成训练目标。
已经理解基础与对齐，想快速建立前沿感	`13 -> 14 -> 15`	这组能把你从推理蒸馏、轻量多模态 demo，一路带到在线 RL 系统工程地图。

如果你拿不准自己现在属于哪一类，一个很稳的默认选择是：

先跑 01 -> 02 -> 03
跑通以后再补 07 -> 08 -> 09
最后按兴趣进入 13 -> 14 -> 15

这样安排的好处是，你几乎每一阶段都会看到肉眼可见的结果变化，而不是在很长一段时间里只看到环境配置或一堆抽象名词。

跑完以后，怎样算真的跑通

第一次动手时，最容易卡住的不是“有没有按钮可以点”，而是不知道“现在这样到底算没算成功”。你可以先用下面这张表做最小自检：

路径	最小跑通信号	如果没看到，先优先检查什么
`01 -> 02 -> 03`	`01` 能正常输出环境检测结果；`02` 能看到 token / embedding / attention 的中间结果；`03` 的 IMDb 小子集 loss 或预测结果出现变化	先检查 kernel 是否切到正确环境、`transformers` 是否装对、训练部分是否把 batch size 设得过大。
`07 -> 08 -> 09`	`07` 能说清 `prompt / chosen / rejected` 的数据形式；`08` 能算出 pairwise loss 或看到 reward 分数差；`09` 的 `DPOTrainer` / `ORPOTrainer` 至少能完成一次前向或极短训练	先检查 advanced 环境是否启用、偏好数据字段名是否对应、LoRA 与 tokenizer 设置是否一致。
`13 -> 14 -> 15`	`13` 能看到 teacher / student 分布差异或 KL toy 结果；`14` 的 CLIP demo 能把更匹配的文本排到前面；`15` 的 trainer 能力检查或系统地图部分能顺利跑完	先检查模型下载是否完整、图像依赖是否安装、是否误把重型训练部分当成默认必须跑完的内容。

如果你当前机器状态一般，或者你只是第一次验证环境，建议先遵守两个顺序：

先跑每本 notebook 的“手动推导 / toy 计算”部分，再决定要不要继续跑调包 demo。
一旦遇到显存吃紧，优先先降 batch size、max_length、max_steps，不要第一时间怀疑整条路线有问题。

单卡 `RTX 5080 16GB` 首次运行建议

这个仓库默认就是围绕单卡 16GB 设计的，但“能跑通”和“第一次就把每个重型单元全跑完”不是一回事。第一次上手时，更稳的做法是先按下面这个顺序来：

路径	第一次建议先跑什么	第一次建议先跳过什么	更稳的默认做法
`01 -> 02 -> 03`	`01` 全部环境检测、`02` 全部手动部分、`03` 的 IMDb 小子集与极短训练	`03` 里任何会明显拉长训练时间的完整对照实验	先确认 loss 会动、预测会变，再决定要不要加步数。
`07 -> 08 -> 09`	`07` 的数据格式和算法地图、`08` 的 pairwise loss、`09` 的单样本目标函数与最短 trainer smoke demo	`08-09` 里所有“想看更明显生成变化”而额外加长的训练轮数	先把 chosen / rejected、reward、DPO / ORPO 关系跑通，不要一上来追输出质量。
`13 -> 14 -> 15`	`13` 的 KL toy 计算、`14` 的 CLIP demo、`15` 的系统地图和 trainer 能力检查	任何默认不是“最小 smoke demo”的扩展训练或长输出比较	先把“蒸馏 / 多模态 / 在线 RL 系统图”理解清楚，再决定是否继续加实验量。

如果你想把第一次运行的失败概率再降一点，可以直接把这几个参数当成默认优先级：

先减 batch size
再减 max_length 或生成长度
再减 max_steps
最后才考虑换更小模型或暂时只跑手动部分

对这个仓库来说，这个顺序很重要，因为我们优先想保住的是“教学闭环还在”，而不是第一轮就把每个包封装 demo 跑到最完整。

默认参数起点：第一次不要比这更激进

如果你准备自己手动改 notebook 参数，而不是完全照当前默认值运行，第一次建议不要一上来就把配置放大。更稳的起点可以直接参考下面这张表：

路径	当前 notebook 里的保守量级	第一次建议先别超过什么	为什么这样更稳
`01 -> 02 -> 03`	`03` 里 tokenizer `max_length=128`、`max_steps=30`、`per_device_train_batch_size=8`	如果你是第一次跑，先不要把 `max_length` 提到 `256+`，也不要把步数翻倍	这条线的目标是先确认 loss 会动、预测会变，而不是追第一轮就更高精度。
`07 -> 08 -> 09`	`08` 是 `max_steps=5`、`batch_size=2`；`09` 的 `DPO/ORPO` 是 `max_steps=3`、`batch_size=1`	第一次先不要加长训练步数，也不要把 batch 往上提	这条线最重要的是把偏好数据、reward、DPO / ORPO 关系跑通，不是先追生成质量。
`11 -> 12`	`11` 的 `PPOTrainer` 默认只构建、不直接训练；`12` 的 `GRPO` 是 `max_steps=3`、`batch_size=1`、`num_generations=4`、`max_prompt_length=128`、`max_completion_length=32`	第一次先不要直接打开更长 PPO 训练，也不要把 `num_generations` 和 completion length 一起放大	在线 RL 很容易同时吃掉 rollout、reward、生成长度三部分资源，第一轮先保住 smoke demo 最重要。
`13 -> 14 -> 15`	`13` 先用 `2` 条 prompt 做 teacher / student 蒸馏；`14` 用合成图片 + 轻量 `CLIP`；`15` 主要是系统地图和 trainer 能力检查	第一次先不要自己扩成更多 prompt、更长文本或更重的多模态模型	这一组的目标是先建立前沿直觉，不是把大模型工作流完整搬到单卡上。

如果你真的需要手动改参数，可以优先按这个顺序调：

先把 batch size 往下调
再把 max_steps 压短
再把 max_length / max_completion_length 压短
只有前面还不够时，才换更小模型或先只跑手动部分

这和很多人直觉不一样，但对这个仓库更合适，因为我们优先想保住的是“这条教学链能不能完整跑通”，而不是“第一轮能不能把所有资源都吃满”。

第一次跑完后，最值得保留什么结果

如果你已经成功跑通一条路径，下一步最值得做的通常不是立刻加大训练量，而是先把最能说明“我真的学到了什么”的结果保留下来。

路径	第一次最值得保留的结果	为什么优先留这个
`01 -> 02 -> 03`	`01` 的 GPU / CUDA 检测、`02` 的 token / attention 中间结果、`03` 的 loss 或预测变化	这三类结果能把“环境可用 -> 模型会吃输入 -> 训练真的发生”完整串起来。
`07 -> 08 -> 09`	`08` 的 chosen / rejected 分数差、`09` 的 DPO / ORPO 极短训练日志或生成倾向变化	这最能体现“偏好数据真的变成了训练信号”，也是进阶线最容易讲明白的一组证据。
`11 -> 12`	reward、advantage、ratio、group reward 的 toy 表格或关键打印结果	在线 RL 的价值不一定先体现在长训练结果上，先把这些中间量留住反而更有教学价值。
`13 -> 14 -> 15`	`13` 的 KL distillation 数值、`14` 的 CLIP 匹配排序、`15` 的系统地图或框架分工表	这组结果最适合证明“仓库不只停在基础，还继续连到了蒸馏、多模态和在线 RL 系统工程”。

如果你后面准备发 GitHub 首页、项目介绍页或分享帖，这一节保留下来的结果，基本就是最自然的第一批素材。

第一次公开分享：最小 `4` 图套餐

如果你第一次想把这个仓库发给别人看，不需要一上来就把所有结果都摊开。更稳也更清楚的做法，通常是先用 4 张图讲完最核心的四件事：

第 `1` 张	第 `2` 张	第 `3` 张	第 `4` 张
路线图：`assets/figures/course_roadmap.svg`	原理拆解：`pretrained_attention_toy.png`	单卡训练 / 对齐：`lora_parameter_ratio.png` 或 `alignment_score_or_reward.png`	前沿扩展：`clip_zero_shot_match.png`

这样选的好处是：

第 1 张先回答“这个仓库整体教什么”
第 2 张回答“这不是纯调包教程”
第 3 张回答“单卡训练和对齐到底能看到什么变化”
第 4 张回答“这个仓库还会继续把你带到多模态与前沿方向”

如果你这次更想强调某一条线，也可以这样替换：

想强调“训练真的发生了”：把第 3 张换成 imdb_finetune_loss.png
想强调“资源友好”：把第 3 张换成 quantization_memory_compare.png
想强调“后训练对齐是主角”：把第 3 张换成 offline_alignment_family_map.png 或 online_rl_ppo_grpo_compare.png

如果你这次是发给不同背景的人看，一个很省事的做法是：前后两张尽量不动，只按受众换第 3 张。

你主要发给谁看	第 `3` 张更推荐换成什么	这样更容易让对方立刻看懂什么
工程 / 训练同学	`imdb_finetune_loss.png` 或 `quantization_memory_compare.png`	训练确实发生了，而且资源约束是可见、可控的。
后训练 / 对齐方向同学	`offline_alignment_family_map.png` 或 `online_rl_ppo_grpo_compare.png`	这个仓库不只讲基础微调，还把离线对齐和在线 RL 主线串起来了。
只学过基础 LLM 的同学	`lora_parameter_ratio.png`	LoRA 最容易建立“单卡也能训，而且不是纯理论”的第一直觉。

对大多数第一次公开分享来说，更稳的默认骨架仍然是：

第 1 张讲结构：course_roadmap.svg
第 2 张讲原理：pretrained_attention_toy.png
第 3 张按受众切换
第 4 张保留 clip_zero_shot_match.png，把故事自然延伸到多模态与前沿方向

如果你第一次发帖时还不想自己想图注，可以直接用这四句：

course_roadmap.svg：这张图先把仓库的基础线、进阶线和前沿扩展入口一次讲清楚。
pretrained_attention_toy.png：这个仓库不只调包，也会手动拆开 token、embedding 和 attention 给你看。
lora_parameter_ratio.png 或 alignment_score_or_reward.png：单卡环境下，你能直观看到训练资源差异，或者看到偏好信号怎样变成训练目标。
clip_zero_shot_match.png：学到后面，这个仓库还会自然把你带到多模态与更前沿的方向。

第一次公开分享时，优先把故事讲清楚，比一次塞进更多图更重要。

想继续跟进前沿？

如果你已经跑完基础线或进阶线，想知道“这些算法在真实开源世界里又往哪里发展了”，可以继续看：

docs/frontier_algorithm_tracker.md

这个文档会持续区分两类内容：

经典算法主线：哪些方法是你应该先真正吃透的基础
当前前沿增量：哪些新算法、新框架值得继续跟进，但未必适合立刻塞进单卡教学主线

Notebook 索引表

编号	主题	手动部分	调包部分	预计运行时间	显存目标	前置要求
01	环境配置	手动估算参数、dtype、activation 的显存占用	安装并验证 `torch` / `transformers` / `peft`	10-15 分钟	CPU / 单卡 16GB	无
02	预训练模型使用	手动 tokenization、embedding lookup、toy self-attention	`AutoTokenizer` / `AutoModel` / `pipeline`	15-25 分钟	单卡 16GB	01
02b	Causal LM 预训练	shifted cross-entropy、perplexity、单步优化	`Trainer` + Wikitext-2 小子集 + tiny GPT-style model	30-50 分钟	单卡 16GB	01-02
03	全参数微调	手动 cross-entropy、logits、梯度更新一步	`Trainer` + IMDb 小子集	25-45 分钟	单卡 16GB	01-02
04	LoRA / PEFT	手动推导 `W + ΔW`、`ΔW = BA`	`peft` + LoRA 分类微调	25-45 分钟	单卡 16GB	01-03
05	量化	手动 8-bit 量化、zero-point、scale、误差	`bitsandbytes` 8-bit / 4-bit demo	20-35 分钟	单卡 16GB	01-02
06	部署与推理	手动比较 greedy / top-k / top-p / temperature	`FastAPI` + `Gradio` + `distilgpt2`	20-30 分钟	单卡 16GB	01-02
07	后训练全景	手动梳理偏好数据格式与算法关系	TRL trainer 映射表	15-25 分钟	CPU / 单卡 16GB	01-04
08	奖励建模	手动计算 Bradley-Terry / pairwise ranking loss	`RewardTrainer` 小型 smoke demo	25-40 分钟	单卡 16GB	07
09	DPO / ORPO	手动拆解单样本目标函数	`DPOTrainer` / `ORPOTrainer` 小型 demo	30-50 分钟	单卡 16GB	07-08
10	KTO	手动理解 desirable / undesirable 监督	`KTOTrainer` 小型 demo	25-40 分钟	单卡 16GB	07-08
11	PPO	手动计算 reward、advantage、ratio、clip、KL	`PPOTrainer` 小型 demo	35-60 分钟	单卡 16GB	07-08
12	GRPO	手动计算 group reward 和 group-normalized advantage	`GRPOTrainer` 小型 demo	35-60 分钟	单卡 16GB	07-08
13	推理蒸馏与 open-r1	手动理解 KL distillation、teacher/student 分布迁移	小 teacher / student 蒸馏 smoke demo	25-45 分钟	单卡 16GB	07-12
14	多模态 VLM 与 Omni	手动理解图像 patch、embedding、图文相似度	轻量 `CLIP` zero-shot 图文匹配 demo	20-40 分钟	单卡 16GB	02, 07, 13
15	在线 RL 变体与系统工程	手动理解 PPO / RLOO / GRPO / GSPO-token 的 baseline 与 ratio 直觉	`TRL` trainer 能力检查 + `OpenRLHF / verl / open-r1` 系统地图	25-45 分钟	单卡 16GB	11-14

基础线说明

`01_environment_setup.ipynb`

检查 CPU、内存、GPU、CUDA
验证基础依赖是否安装成功
手动估算参数量与显存占用的关系

`02_pretrained_model_usage.ipynb`

用最小例子理解 token、embedding、attention
再用 Hugging Face 包直接加载真实模型看结果
如果你想把“表示原理”继续连到“预训练目标、loss 与训练循环”，请继续看 02b_causal_language_model_pretraining.ipynb

`02b_causal_language_model_pretraining.ipynb`

用 openai-community/gpt2 tokenizer + wikitext-2-raw-v1 理解 Causal LM 训练样本如何形成
手动拆解 shifted cross-entropy、ignore_index=-100、perplexity 和单步 optimizer update
再用 Trainer 跑一个 tiny GPT-2 style from-scratch 小规模 smoke pretraining

`03_full_finetuning.ipynb`

保留 IMDb 作为分类任务
先手动理解 cross-entropy 和一次梯度更新
再用 Trainer 做小规模全参数微调

`04_parameter_efficient_finetuning.ipynb`

先手动理解 LoRA 为什么能减少可训练参数
再用 peft 跑一个小型 LoRA 微调 demo
结尾补 “AdaLoRA / DoRA / IA3” 的前沿 PEFT 卡片

`05_quantization_techniques.ipynb`

手动理解量化、反量化、误差来源
再用 bitsandbytes 跑 8-bit / 4-bit 加载和简单生成

`06_deployment_inference.ipynb`

先手动比较几种常见 decoding 策略
再用 FastAPI 和 Gradio 组织一个轻量推理服务

进阶线说明

`07_post_training_overview.ipynb`

建立 SFT、Reward Modeling、DPO、ORPO、KTO、PPO、GRPO 的整体地图
用极小样本解释三类常见训练数据格式：
- prompt / chosen / rejected
- prompt / completion / desirable
- prompt / completion / reward

`08_reward_modeling.ipynb`

手动计算偏好概率和 Bradley-Terry 风格损失
再用 RewardTrainer 跑一个最小奖励建模 demo

`09_dpo_orpo_alignment.ipynb`

对照解释 DPO 和 ORPO 的目标函数差异
使用相同的小型偏好数据集做调包对比

`10_kto_alignment.ipynb`

解释 KTO 和 pairwise preference 的不同监督形式
展示 KTOTrainer 的最小可运行形式

`11_ppo_alignment.ipynb`

先在离散 toy policy 上手动算 reward、advantage、clip、KL
再用小型模型和简单 reward function 展示 PPOTrainer

`12_grpo_alignment.ipynb`

解释组内相对奖励、为什么不需要 value head
对比 GRPOTrainer 和 PPO 的直观差异

`13_reasoning_distillation_and_open_r1.ipynb`

手动拆解 teacher / student 的分布蒸馏直觉
用 gpt2 -> distilgpt2 做极小蒸馏 smoke demo
把 open-r1 看成“数据 + 蒸馏 + RL + 评测”的公开工作流

`14_multimodal_vlm_and_omni_overview.ipynb`

手动理解图像 patch、patch embedding 和图文相似度
用轻量 CLIP demo 看 zero-shot 图文匹配
把 CLIP (2021) 继续连接到 InternVL-U、Qwen3-Omni 这类统一多模态 / omni 路线

`15_online_rl_variants_and_systems.ipynb`

手动比较 PPO / RLOO / GRPO / GSPO-token 在 baseline、advantage、ratio 上的直觉差异
用最小 API 检查 TRL 里的相关 trainer 能力边界
把 OpenRLHF、verl、open-r1 放进一张“算法 + 系统工程”地图

运行约束

项目默认目标硬件是单卡 RTX 5080，16GB 显存
所有调包 demo 都以“小规模教学配置”为默认设计目标
进阶对齐部分优先使用小模型、LoRA、短输出、极小数据集或极少训练步数
如果你的显存小于 16GB：
- 优先只跑手动推导部分
- 适当减小 batch size
- 缩短 max_new_tokens、训练步数和样本数

数据与输出目录

data/raw/、data/processed/ 用于缓存和中间结果
训练输出、量化输出和对齐实验结果默认不上传 GitHub
你可以把 notebook 里生成的结果目录视为实验产物，而不是仓库源码的一部分

如何参与贡献

如果你想一起把这个仓库做得更清楚、更系统、更适合初学者公开学习，可以先看：

CONTRIBUTING.md

如果你是第一次参与这个项目，不用一上来就改大块 notebook。更稳的起步方式通常是先选下面三类“小而值”的改动：

你想帮什么忙	最适合的第一步	建议先用哪个模板	为什么适合第一次参与
让讲解更清楚	挑一个 notebook 或 README 段落，补一句更容易懂的解释，或调整一小段章节顺序	`Notebook improvement`	风险小，而且最容易直接帮助初学者。
让默认配置更稳	报告或建议某个 demo 的 `batch size`、`max_steps`、`max_length` 更保守的起点	`Notebook improvement` 或 `Bug report`	很贴合单卡 `RTX 5080 16GB` 目标，也最容易验证。
帮仓库继续跟上前沿	补一条官方文档、官方仓库或论文链接，并说明它更适合“教学实践”还是“阅读跟进”	`Frontier update`	不会打乱主线，但能持续提升仓库完整度。

第一次贡献时，通常不建议直接从下面这些开始：

一次性新增多本 notebook
重写基础线 01-06 或进阶线 07-12 的整体结构
把默认环境改得更重，或默认要求多卡 / 更大显存
只补很多新名词，但没有说明它为什么值得初学者学

里面写清楚了：

这个仓库最欢迎哪几类贡献
notebook 改动时要遵守哪些 16GB 单卡约束
提交前怎样检查 .ipynb 的 JSON / AST 结构

如果你是在 GitHub 上参与，也可以直接使用仓库内置的：

issue templates
PR template
notebook structure check workflow

如果你是第一次提 issue，也不用写得很长。最短先写清这 4 件事，通常就已经很有帮助：

你在哪个文件或哪本 notebook 遇到了问题
你做到哪一步、哪一格、或用了什么默认参数
你实际看到了什么现象或报错
你原本以为应该看到什么

如果问题和单卡 RTX 5080 16GB 运行边界有关，最好再顺手补一句：

batch size
max_steps
max_length 或 max_completion_length
是否量化 / 是否 LoRA / 是否只跑手动部分

这样别人通常不用先来回追问很多轮，就能更快帮你判断：这是环境问题、配置太激进、文档不清楚，还是 notebook 本身需要改。

如果你不想自己组织措辞，也可以直接去 CONTRIBUTING.md 里复制“第一次提 issue”的最小示例，再按自己的情况改几行。

如果你已经准备提 PR，也可以先用同一个文档里的“第一次提 PR 最短怎么写”和可复制示例。对这个仓库来说，第一次 PR 最重要的通常不是写得长，而是先说清：改了什么、为什么改、怎么验证。

常见问题

为什么要同时保留“手动推导”和“调包结果”？

因为很多初学者的问题不是“不会写代码”，而是“不知道这个 loss 到底在优化什么”。先手动拆开，再看 trainer 接口，会更容易形成稳定直觉。

为什么进阶线单独拆依赖？

因为 trl、较新的 transformers、peft、accelerate 组合变化更快。如果把它们直接塞回基础线，反而容易让 01 到 06 的轻量体验变脆弱。

为什么有些 demo 只跑极小步数？

因为项目目标是“帮助理解”，不是“在仓库里直接做大规模训练”。只要能看到 loss 变化、偏好概率变化或输出风格变化，教学目的就达到了。

许可证

本项目使用 MIT License，详见 LICENSE。

FilesExpand file tree

README.md

Latest commit

History