LLM-Beginner：大模型与智能体入门练习

本系列是 NLP-Beginner 在大模型时代的重构版本，是一份独立的入门教程，面向有 Python 与深度学习基础的学习者。沿用原系列「任务渐进 × 每个 2-4 周」的节奏，按"熟悉 Transformer → 从零实现 mini-GPT → 指令微调与对齐 → RAG → 工具调用 Agent → Mini Coding Agent"六个任务展开。

llm-beginner 可独立完成，无任何前置依赖。如果同时在读《神经网络与深度学习（第二版）》（下文简称 NNDL2）与配套的《神经网络与深度学习案例与实践（第二版）》（下文简称 实践书 v2），每个任务的"延伸阅读"会指向对应章节，配合读会更顺畅。

相关教材

作为本教程的学习材料，同步撰写了《大模型与智能体》，围绕共用基础、大模型、智能体、边界与未来四条主线展开，共 17 章。 完整章节列表。

这本教材可以作为 llm-beginner 的前置知识配合阅读：教材讲清原理，本仓库的 6 个任务负责把原理动手跑通。两者都可独立完成，不强相关。

参考：

1. 《神经网络与深度学习》
2. 《大模型与智能体》（2026 出版）
3. 原始版本：NLP-Beginner（2019 年发布，已归档供对比阅读）
4. 不懂问搜索引擎与大模型

通用说明

• 设备基准：8GB 消费级 GPU（如 RTX 3060/4060）可完成任务一至四；任务五、六推荐 16GB+ 显存，或使用 Q4_K_M 量化在 8GB 上跑。Mac M 系列通过 MPS / llama.cpp 兜底。
• 模型生态：通义千问 Qwen 系列贯穿全程，国内可直接从 Hugging Face / ModelScope 下载。
• 语言：以中文为主，仅在英文数据显著更好时使用英文（如部分小模型预训练语料）。
• 教学路线：每项任务先手写、再对照框架——先吃透原理，再看工程上怎么封装。

环境与自检

六个任务目录结构一致：每个任务下都有 requirements.txt（依赖）、data/download.py（下载数据 / 模型）、eval/run.py（自检脚本）和 eval/tutor_prompt.md（贴给大模型做代码 review 的提示词）。你的实现写在各任务的 src/ 下，按该任务 README「实现约定」表里列出的类 / 函数签名导出——自检脚本正是按这些签名导入并评测你的代码，照着写才能被正确评分。

环境准备

• Python：3.10+（推荐 3.11 / 3.12）。
• 按任务装依赖（各任务相互独立，可共用一个环境，也可每个任务单独建 venv / conda）：

bash pip install -r task-1-transformer/requirements.txt

• 国内下载加速：Hugging Face 访问不稳时先设镜像再下载（download 脚本在缺失时也会提示）：

bash export HF_ENDPOINT=https://hf-mirror.com # Windows PowerShell：$env:HF_ENDPOINT = "https://hf-mirror.com"

完全无法访问 HF 时，多数数据 / 模型可改用 ModelScope（见各 download.py 末尾提示）。

标准流程（以任务一为例）

cd task-1-transformer
python data/download.py        # 1. 下载数据 / 模型（命令见下表，部分任务带参数）
# 2. 在 src/ 下写好你的实现（见本任务 README「实现约定」）
python eval/run.py             # 3. 跑自检，结果写入 eval/result.json

⚠️ 请在仓库内运行 eval/run.py：它依赖仓库根目录的 _eval_harness.py（六个任务共用的运行壳）。把单个任务目录拷到仓库外会导致自检无法 import。

各任务的下载命令

任务	下载命令（在任务目录下执行）	说明
一 Transformer	python data/download.py	ChnSentiCorp 中文情感分类
二 mini-GPT	python data/download.py [--dataset poetry\|tinystories\|skypile]	默认 poetry（唐诗，quick-start）
三 SFT/DPO	python data/download.py	下载 Qwen2.5-0.5B，并提示 MOSS / DPO 数据获取方式
四 RAG	python data/download.py [--skip-models]	BGE 模型 + NNDL PDF + 校验 gold_qa；--skip-models 只下 PDF 并校验
五 工具 Agent	python data/download.py	生成 10 题任务集与检索夹具，并打印模型部署提示
六 Coding Agent	python data/download.py [--with-swebench]	生成本地 toy-repo；--with-swebench 额外下载 SWE-bench Lite 抽样元数据

看懂自检结果

eval/run.py 逐项打印，并把结构化结果写入 eval/result.json（始终 UTF-8，可附在提交里）。每项有三种状态：

• [通过]：该项契约满足。
• [跳过]：前置条件还没就绪（如模型 / ckpt / 数据缺失），不是错误——补齐后重跑即可。
• [失败]：实现与预期不符，结果里带 error 或具体指标，照着修。

自检只验证关键契约（如 attention 数值正确性、召回率、任务成功率），是“能不能跑对”的下限检查，不替代你自己跑各任务 README「实验」里的对比与消融。Windows 控制台中文乱码已由脚本自动处理（sys.stdout.reconfigure），无需额外设置。

找大模型帮你 review

每个任务的 eval/tutor_prompt.md 是一段可直接复制的提示词：连同 src/ 下的代码一起贴给 Claude / Qwen / DeepSeek 等，就能拿到一份按该任务检查项组织的代码审查。

---

任务一：熟悉 Transformer

详细资源、数据下载与自检脚本见 task-1-transformer/

手写 self-attention 与 Transformer block，在小任务上跑通并可视化注意力权重。本任务和实践书 v2《注意力机制》章节有意重叠——为独立读者打下从零起步的 Transformer 基础。

1. 参考
2. Attention Is All You Need
3. The Annotated Transformer
4. The Illustrated Transformer (Jay Alammar)
5. 延伸阅读（配合读可加深理解，非必需）
   • NNDL2 第 8 章《注意力机制与 Transformer》之「注意力机制」「自注意力」「Transformer 模型」三节
   • 实践书 v2《注意力机制》章「基于双向 LSTM 和多头自注意力的文本分类」「基于自注意力模型的文本语义匹配」两节
6. 数据集
7. 文本分类：ChnSentiCorp（中文情感分类，本任务下载脚本与自检以此为准）；文本匹配方向可参考 LCQMC（呼应实践书 v2 的语义匹配任务，需自行改造数据与自检）
8. Toy 任务（可选）：序列 copy / sort，便于打印注意力矩阵观察学习过程
9. 实现要求
10. 手写 scaled dot-product attention（缩放、softmax、mask）
11. 手写 multi-head attention
12. 手写完整 Transformer encoder block（attention + FFN + residual + LayerNorm）
13. 用 padding mask 跑文本分类任务
14. 再用 causal mask 跑一遍 toy 语言模型（为任务二预热）
15. 用 matplotlib 可视化句子内部的注意力热图
16. 知识点
17. Self-attention 的 QKV 计算
18. Padding mask vs causal mask
19. Multi-head 的并行视角
20. Pre-LN vs Post-LN
21. 注意力可视化的解读方法
22. 实验
23. Head 数 / 层数对分类准确率的影响
24. 移除 residual / LayerNorm 后训练是否还能收敛
25. 注意力热图：观察模型是否"看对了关键词"
26. 时间：2 周

---

任务二：从零实现 mini-GPT

详细资源、数据下载与自检脚本见 task-2-mini-gpt/

用 PyTorch 从零搭一个 decoder-only 模型，先在中文小语料上预训练并自回归生成，进阶再切到 TinyStories 或中文故事语料观察小模型叙事能力。本任务扩展实践书 v2「nanoGPT 模型」的带读：加入 BPE、RoPE、KV cache。

1. 参考
2. nanoGPT
3. TinyStories 原论文
4. RoFormer (RoPE)
5. 延伸阅读
   • NNDL2 第 8 章「现代 Transformer 的常见优化」（含 RoPE / FlashAttention / KV 缓存 / GQA / MoE）
   • 实践书 v2《大语言模型与智能体》章「nanoGPT 模型」「预训练循环」「解码 / 采样策略」三节
6. 数据集（三档渐进，按设备与目标选择）
7. Quick-start（~49KB）：poetryFromTang.txt —— 5 分钟跑通 pipeline、验证代码正确性
8. 正式训练（~100MB，CPU 也能跑）：TinyStories 或社区中文版 TinyStoriesChinese ——原论文证明 10M 参数模型就能学会语法和叙事，能直观看到「涌现」
9. 进阶训练（~1GB+，建议 GPU）：SkyPile-150B 子集（昆仑万维开源高质量中文预训练语料）
10. 实现要求
11. 手写简化版 BPE tokenizer（不用 tiktoken / sentencepiece）
12. 手写 decoder-only 模型，集成 RoPE（超出实践书 v2 nanoGPT 使用的绝对位置编码）
13. 实现 KV cache（推理加速，实践书 v2 只讲不实现）
14. 实现采样策略：greedy / top-k / top-p / temperature
15. 知识点
16. BPE 分词与 merge 过程
17. RoPE 旋转矩阵的原理与外推优势
18. KV cache 的内存换计算
19. 困惑度与生成质量的关系
20. 采样策略对生成多样性的影响
21. 实验
22. 参数量扫描（10M / 50M / 100M）对训练损失与困惑度的影响
23. 绝对位置编码 vs RoPE 在长序列外推上的差异
24. KV cache 开 / 关 的推理速度对比
25. TinyStories 上是否能复现 10M 参数模型涌现叙事能力
26. 时间：3 周

---

任务三：指令微调与偏好对齐

详细资源、数据下载与自检脚本见 task-3-sft-dpo/

在小尺寸预训练模型上做 SFT + DPO 两阶段对齐，理解从 base model 到 chat model 的全过程。本任务扩展实践书 v2「监督微调与 LoRA」「偏好对齐：DPO」两节：手写 LoRA、改用 MOSS 中英双语对话数据、做完整的"指令格式 → 偏好"两阶段闭环。

1. 参考
2. LoRA: Low-Rank Adaptation
3. Direct Preference Optimization
4. Hugging Face TRL 文档
5. Hugging Face PEFT 文档
6. 延伸阅读：实践书 v2《大语言模型与智能体》章「监督微调与 LoRA」「偏好对齐：DPO」两节
7. 基座模型：Qwen2.5-0.5B（8GB 显存可全量微调）
8. 数据集
9. SFT：MOSS-003-sft-data（复旦 NLP 组发布的 110 万条中文多轮对话，取 1-5 万子集即可）
10. DPO：自行在 Hugging Face 寻找中文偏好数据（如 UltraFeedback 翻译版），或先用英文数据集走通流程
11. 贯通任务五：同时下载 MOSS-003 with-tools 数据（带工具调用对话的子集），任务三教模型学会工具调用的输出格式，任务五在 Agent 循环里真的去调
12. 实现要求
13. 先手写 LoRA（亲手实现低秩矩阵注入、forward 与梯度），再用 PEFT 对照
14. SFT 与 DPO 都跑一遍，对比输出质量
15. 知识点
16. Chat template 与 Qwen 对话格式
17. Loss masking：只对 assistant turn 计算 loss
18. LoRA 数学：rank、scaling、初始化
19. DPO 损失函数与 reference model 的作用
20. SFT vs RLHF vs DPO 的简化逻辑
21. 实验
22. 全量微调 vs LoRA：显存占用与下游质量
23. LoRA rank 消融（r = 4 / 8 / 16 / 32）
24. 灾难性遗忘评估（在 C-Eval 子集上对比微调前后）
25. SFT-only vs SFT+DPO 在偏好上的差异
26. 时间：2-3 周

---

任务四：RAG 文档问答

详细资源、数据下载与自检脚本见 task-4-rag/

构建端到端中文检索增强生成系统，并量化每个环节的提升。本任务扩展实践书 v2 RAG 节的最小示例：加入 reranker、chunking 策略消融、RAGAS 评测。

1. 参考
2. Retrieval-Augmented Generation 综述
3. BGE Embedding 系列
4. RAGAS 评测框架
5. 延伸阅读：实践书 v2《大语言模型与智能体》章「检索增强生成（RAG）」一节
6. 技术栈
7. Embedding：bge-small-zh-v1.5
8. 向量库：FAISS（本地、轻量）
9. Reranker：bge-reranker-base
10. 生成模型：Qwen2.5-7B-Instruct（Q4_K_M 量化版可在 8GB 跑）
11. 数据
12. 知识库：《神经网络与深度学习（第二版）》PDF（默认下载到 task-4-rag/data/kb.pdf）
13. 评测：基于 ../神经网络与深度学习2/ LaTeX 正文设计的 task-4-rag/data/gold_qa.jsonl
14. 实现要求：手写 RAG 流水线，不使用 LlamaIndex / LangChain 的高层封装
15. 知识点
16. Chunking 策略：固定大小 / 递归切分 / 语义切分
17. 向量检索原理与近似算法（IVF、HNSW）
18. 两阶段检索架构（embedding 召回 + reranker 精排）
19. 评测指标：Recall@k、MRR、faithfulness、answer relevancy
20. Query rewriting 与 HyDE 等增强策略
21. 实验
22. Chunk size 扫描（128 / 256 / 512 / 1024 字符）对检索质量的影响
23. 加 / 不加 reranker 的端到端提升
24. Query rewriting 的有效性
25. 用 RAGAS 打端到端分数
26. 时间：2 周

---

任务五：工具调用 Agent

详细资源、数据下载与自检脚本见 task-5-tool-agent/

实现 ReAct 循环，让 LLM 自主调用工具完成多步任务。本任务扩展实践书 v2 ReAct 节的单工具示例：扩展到 4 类工具、错误恢复、与 Qwen-Agent 框架对照。

1. 参考
2. ReAct: Synergizing Reasoning and Acting
3. Toolformer
4. Qwen-Agent
5. 延伸阅读：实践书 v2《大语言模型与智能体》章「ReAct 智能体」一节
6. 基座模型：Qwen2.5-7B-Instruct（原生支持 function calling）
7. 部署：Ollama / vLLM / llama.cpp 本地推理
8. 工具实现（自己写，不依赖任何 agent 框架）
9. 计算器
10. Python sandbox（受限执行环境）
11. 本地文件检索
12. 维基百科 API
13. 实现要求
14. 第一阶段：手写 ReAct 循环（~200 行，纯 Python + HTTP 调用本地模型）
15. 第二阶段：对照 Qwen-Agent 的实现，理解工程封装与原生 ReAct 的差异
16. 贯通任务三：可选地使用任务三中基于 moss-003-sft-plugin 微调过的模型，对比 zero-shot 与微调后的工具调用成功率
17. 知识点
18. Function calling 协议（OpenAI 兼容格式）
19. ReAct 范式：Thought / Action / Observation 循环
20. Prompt 构造与停止条件设计
21. 错误恢复与重试策略
22. 词元预算与上下文管理
23. 实验
24. 手写 ReAct vs Qwen-Agent 原生 function calling 的成功率对比
25. 不同模型尺寸（1.5B / 7B / 14B）的工具调用准确率
26. 错误注入下的恢复能力
27. 时间：2 周

---

任务六：Mini Coding Agent

详细资源、数据下载与自检脚本见 task-6-coding-agent/

复刻一个极简版 Claude Code，能在本地仓库上理解任务、修改代码、运行测试并迭代。本任务完全超出实践书 v2 的覆盖范围，引入 MCP、Skill、Subagent 三层栈。

1. 参考
2. SWE-bench
3. CodeAct：用代码执行代替 JSON 工具调用
4. Qwen-Agent
5. smolagents（Hugging Face 极简 agent 框架，原生 CodeAct 风格）
6. Model Context Protocol (MCP)
7. Anthropic Skills（Skill 设计参考，源码可读）
8. 延伸阅读：本任务为进阶扩展，教材未覆盖；可阅读 Anthropic 发布的 Claude Code / Skill / Subagent 系列博客作为补充
9. 基座模型：Qwen2.5-Coder-7B-Instruct
10. 能力三层栈

层	概念	角色
底层	Tools / MCP	原子工具，通过 MCP server 接入，无状态、可跨 agent 复用
中层	Skills	组织化的能力包（SKILL.md + scripts + references），按需加载、渐进式披露
顶层	Subagents	独立 context 的子 agent，处理可并行或需隔离的子任务

1. 实现要求
2. 手写一个 MCP server（提供工具，如「读写本地代码 + 运行测试 + 跑 git 命令」）
3. 手写 2-3 个 Skill（如 code-review、pr-description-writer、test-runner），并实现一个约 50 行的 mini-Skill 加载器（description 匹配 + 按需加载文件内容到上下文）
4. 1-2 个 Subagent（如把「代码搜索」与「测试执行」分给独立 subagent，主 agent 只看摘要）
5. 主线 agentic loop：while not done: model -> tool -> observation -> loop
6. 主框架用 Qwen-Agent，对照阅读 smolagents 的 CodeAct 实现
7. 任务范围
8. 输入：本地 Git 仓库 + 一个 issue 描述
9. 输出：能自动定位代码、修改、跑测试、生成 patch 的完整 trace
10. 评测：在 SWE-bench Lite 上抽样跑通几条
11. 知识点
12. Agentic loop 的本质：循环 + 工具 + 模型自主停机
13. MCP 协议规范与 server 实现
14. Skill 设计模式：progressive disclosure、description-based 路由
15. Subagent 与 context 隔离的工程价值
16. 长任务的 context compaction 策略
17. Sandbox 代码执行的安全考虑
18. Trace 评测：步骤数、成功率、词元消耗
19. 实验
20. 同一任务在 Q4_K_M 量化 vs FP16 下的成功率差异
21. 单 agent vs 加 Subagent 的词元消耗与成功率
22. 纯 prompt vs 加 Skill 的成功率提升
23. 时间：5-6 周（全系列最大跳变：子系统最多、且完全超出教材覆盖）

---

整体设计原则

维度	设计选择
定位	独立入门教程，可与 NNDL2、实践书 v2 配合阅读，但可独立完成、无强依赖
教学路线	每项任务「先手写、再对照框架」，理解原理在前
技术栈	本地化优先，依赖 Hugging Face / 阿里 Qwen / 国产开源生态，国内畅通
数据贯通	MOSS 系列从任务三贯通到任务五（教格式 → 真调用）；唐诗数据从原 nlp-beginner 任务五延续到新任务二
模型贯通	Qwen2.5 体系：0.5B（任务 3）→ 7B-Instruct（任务 4-5）→ Coder-7B（任务 6）；任务二从零训练、不属此体系
技术覆盖	RoPE、LoRA、DPO、RAG、ReAct、MCP、Skill、Subagent、CodeAct