Skip to content
Projects

FRS2003/hands-on-llm has 124 GitHub stars and 12 forks. GitHot measured 0 stars in 24 hours. Last checked 2026-11-15 15:42 UTC. Last push 2026-09-16.

How these counts are measured

Measured star growth

in 24h
0
in 7 days
Update delayed
in 15 days
Update delayed
in 1 month
Update delayed

Net star changes over overlapping periods, not daily totals. Missing measurements are left blank. Stars measure attention, not software quality.

About

动手学大模型全栈:CS336 中文精讲 · PyTorch 手搓 Transformer · 单卡复现 Pretrain/SFT/LoRA/DPO/GRPO/RLVR · PEFT/Agent/RAG 落地(含真实实验、曲线与复现脚本)

AI

README.md

Original

Hands-on LLM · 动手学大模型:从手搓原理到落地应用

License Language Created Modules

一条由理论到落地的大模型自学与实战路径:先读透原理,再用原生 PyTorch 手搓并完整跑通 预训练 → SFT → LoRA → DPO → GRPO → 可验证奖励 RLVR,然后读懂工业级微调框架、动手做 Agent,最后用 RAG 把模型落到真实场景。 所有训练实验都在**单张消费级显卡(RTX 3080 Ti 12GB)**上真实跑过,数字、曲线、生成样例与踩坑全部留档,不做"截图式学习"。

🧭 学习路线(建议按编号顺序)

① 理论基础        ② 手搓 + 训练全链路      ③ 工业框架           ④ Agent 工程        ⑤ RAG 落地
CS336 中文精讲 → 原生 PyTorch 实现 →    LLaMA-Factory  →   编程智能体     →  文献问答系统
Transformer/      Pretrain·SFT·LoRA·     对齐/PEFT/分布式/   ReAct·记忆·多智能体  混合检索·重排
MoE/Scaling/对齐   DPO·GRPO + 对照实验     量化推理 选型                        带引文生成
模块 目录 你会看到什么
① 理论基础 01-foundations Stanford CS336(L1–L17)5 篇中文精讲:分词、Transformer、注意力变体、MoE、GPU/并行、Scaling Law、推理优化、对齐与 GRPO
② 手搓与训练 02-train-from-scratch 原生 PyTorch + Triton 手写字节级 BPE 分词器、RMSNorm/RoPE/GQA/SwiGLU(含融合 RMSNorm Kernel)并配数值自检;单卡跑通五阶段训练 + 可验证奖励 RLVR,并做规模/资源/偏好/架构对照实验
③ 工业框架 03-peft-framework 源码级走读 LLaMA-Factory 四层链路;对齐/PEFT/量化选型笔记 + 双卡 DDP/ZeRO 分布式实测 + 带注释 yaml 模板与工程化封装 + 垂直领域微调方案(csv 为自测记录表)
④ Agent 工程 04-agent 终端编程 Agent:ReAct + Harness、Skill 路由、记忆闭环、分层上下文压缩、主从多智能体、分层安全
⑤ RAG 落地 05-rag-application 医学文献混合检索问答:BM25+稠密双路、加权融合、Rerank、HyDE/QE、带引文生成、ReAct 编排、Streamlit

🎯 适合谁 / 你能收获什么

  • 想系统补齐大模型训练与落地、从理论走向动手实践的同学;
  • 会调包但说不清"Transformer 内部 / 为什么 SFT 学习率要更小 / DPO loss 为何从 0.693 起步"的人;
  • 想在单卡上把预训练→对齐全链路亲手跑一遍、并留下可复现实验记录的人。

收获:一套"原理 → 手写 → 训练 → 框架 → Agent → 应用"可运行、可复现、带真实数据的完整作品,而不是一堆零散 demo。

🧩 能力矩阵(想掌握的能力 → 对应模块)

想掌握的能力点 在哪里练到
Transformer / 自注意力 / 位置编码 / GQA / MoE ① + ②
继续预训练、SFT、LoRA、DPO、GRPO/强化学习对齐 ②
数据清洗/抽样、Scaling Law、模型评估 ① + ②
模型/数据/管道并行、DeepSpeed ZeRO、混合精度 ① + ③
PEFT 方法选型、量化(GPTQ/AWQ)、vLLM 推理 ③
Agent / ReAct / 工具调用 / 记忆 / 多智能体 ④ + ⑤
RAG / 混合检索 / 向量库 / Rerank / 查询改写 / 检索评测 ⑤
PyTorch 原生实现与数值正确性验证 ②

🔬 部分真实实验结果(均有日志/曲线支撑,详见各模块)

  • 从零训练 63.91M 小模型(hidden 768 / 8 层 / GQA KV 头 4 / bf16):预训练数据量 ×2.5 后,最终 loss 3.35→2.53,验证数据规模效应;
  • LoRA 只训 0.61% 参数(0.393M/63.91M),适配器权重 132MB→0.78MB,显存 7.36GB→4.60GB;
  • DPO 用 17,166 对偏好数据,loss 从理论值 -ln2≈0.693 起步并缓慢下降,学习率刻意取 4e-8 防止灾难性遗忘;
  • GRPO 免 1.8B 奖励模型改纯规则奖励,单卡真实训练 300 步(21.7 min):组内优势均值严格为 0、平均 |KL|≈0.005 未漂移,同 prompt/种子前后对比规则分 0.109→0.290;100 条未训练 held-out 题上 +0.084、3-gram 重复度下降,并做五阶段(pretrain→GRPO)同种子生成横评;另配 14 项纯 tensor 自检;
  • 可验证奖励 RLVR(答案对错自动判分):一位加法先 SFT 冷启动到「采样能偶尔答对」的甜区(greedy 0.633),再用对错判分的 GRPO(B8×G4、lr 4e-6、β-KL 0.08、300 步)把独立 120 题 greedy 0.633→0.792、采样三种子均值 0.503→0.603;对照证明 RL 只放大已有能力、不注入知识,并复现了 lr 过大 / KL 过弱导致的策略崩溃;
  • 架构/精度消融:同骨架实测 MHA/GQA/MQA——训练侧 MQA 比 MHA 省约 12% 显存、快约 16%,而推理 KV cache@4096 为 100.7/50.3/12.6MB(随 KV 头数 8:4:1,长上下文这才是 GQA/MQA 主价值);bf16 较 fp32 省 35–49% 显存、约 1.8× 吞吐;
  • 分布式对照(2×RTX 3080 Ti,详见 ③ 模块):0.5B 双卡 DDP 接近线性加速、每卡显存与单卡持平(DDP 只扩吞吐、不省单卡显存);1.5B 全参 DDP/ZeRO-1/2 先后显存不足,仅参数也分片的 ZeRO-3 跑通,验证“分片越彻底越省显存、通信开销越大”;
  • 全程显存峰值 4.6–7.4GB、GPU 利用率 96–99%,证明单卡可完整走通主链路。

🗺 怎么开始

  • 第一次看:从 LEARNING_PATH.md 按顺序学,每个模块都有自己的 README 导览;
  • 想直接看代码:进 02-train-from-scratch/from_scratch 看手写组件,python test_model.py、python test_grpo_logic.py、python test_tokenizer_bpe.py 跑数值自检;
  • 自测回查:appendix/ 里有名词词典、论文清单,以及结合本仓库真实数字的核心知识自测;
  • 离线/批注:各模块的教学笔记基本都附了排版好的 Word 版(与同名 .md 同目录的 .docx),导航大纲齐全,可直接下载打印或批注。

📂 仓库结构

hands-on-llm/
├── 01-foundations/          # CS336 中文精讲(理论)
├── 02-train-from-scratch/   # 手写组件 + 五阶段训练 + 对照实验
├── 03-peft-framework/       # LLaMA-Factory 源码走读、选型笔记、配置模板与二次开发示例
├── 04-agent/                # 编程智能体:ReAct/记忆/多智能体/安全
├── 05-rag-application/      # 医学文献混合检索问答 RAG(双路召回/重排/评测)
├── appendix/                # 名词词典 / 论文清单 / 核心知识自测
├── tools/                   # 辅助工具:Markdown→Word 转换器 md2docx.py
├── LEARNING_PATH.md         # 学习路径与使用指南
└── LICENSE                  # MIT

🛠 环境

  • Python 3.10、PyTorch(训练/手写组件)、Transformers;Agent/RAG 通过 OpenAI 兼容接口接入模型,Key 一律走环境变量(.env.example),仓库不含任何密钥。
  • 训练默认 bf16 混合精度;单卡 12GB 即可复现②,纯 CPU 也能跑手写组件的数值自检。

📌 进度与规划

  • 理论笔记、手写组件、Pretrain/SFT/LoRA/DPO、框架对照、Agent、RAG
  • GRPO 纯规则奖励改造与数值自检
  • GRPO 纯规则奖励 300 步全量训练,补 Reward/KL/Loss 曲线与前后生成对比
  • GRPO 100 条 held-out 定量评测 + 五阶段同种子生成横评(能力演进证据链)
  • MHA/GQA/MQA × 混合精度 × batch 架构消融(训练显存/吞吐 + 推理 KV cache 实测)
  • 可验证奖励 RLVR(对错判分):SFT 甜区冷启动 + GRPO,greedy 0.633→0.792,含能力边界 / 策略崩溃对照
  • DeepSpeed 分布式实测:双卡 DDP vs ZeRO-1/2/3 对照(显存/通信/吞吐,见 03 模块 dist_lab)
  • Triton 融合 RMSNorm Kernel(前向+反向,GPU 数值对齐,访存受限大张量约 2.7×)
  • 手写分块 Flash Attention(尚未实现,列后续规划)
  • 持续补充论文精读与自测题

🙏 致谢与说明

本仓库为一套面向学习者的动手学习资料,训练部分复现自 jingyaogong/minimind(MIT)、 框架实验参考 hiyouga/LLaMA-Factory(Apache-2.0)、 理论笔记对应 Stanford CS336(笔记为学习理解,不含其受版权保护的讲义/作业),各模块 README 内有更详细出处。如有疏漏欢迎 Issue 指正。

License

MIT