# GoClaw LLM 工程手册：教师授课指南

这份指南把静态手册变成一门可以授课、作业、评分和复盘的课程。教师不需要把每个学生带到同一个硬件；应要求每个人提交可复查证据，并允许 CPU、Apple Silicon 和 CUDA 路线在资源层面不同。

## 教学原则

1. 先预测，再运行。学生必须在执行 Notebook 前写出形状、数量级或失败原因。
2. 先最小闭环，再引入优化。不要在学生尚未理解 causal mask 时直接讲 FlashAttention。
3. 每个性能数字必须带硬件、模型、数据、dtype、batch 和计时口径。
4. 先建立 baseline，再使用 LoRA、RAG、Agent 或更大模型。
5. 让学生故意制造错误：去掉 mask、打乱 labels、交换 chosen/rejected、删除 checkpoint 状态。
6. 评价解释质量，不只评价结果。能够定位失败层级比得到一个偶然较低的 loss 更重要。

## 90 分钟课堂模板

| 时间 | 教师活动 | 学生活动 | 产物 |
|---:|---|---|---|
| 0–10 分钟 | 提出一个反例或线上事故 | 写下预测 | 预测卡 |
| 10–25 分钟 | 讲直觉与公式 | 标注符号、形状和假设 | 公式草图 |
| 25–45 分钟 | 演示最小实现 | 跟踪断言和日志 | 可运行 Notebook |
| 45–65 分钟 | 引入一个错误版本 | 解释错误信号 | 故障记录 |
| 65–80 分钟 | 组织单变量对照 | 运行并记录指标 | 实验表 |
| 80–90 分钟 | 口头抽查与总结 | 写结论边界 | 一页复盘 |

## 模块授课重点

| 模块 | 必须让学生真正会做的事 | 不要提前假设学生会什么 |
|---|---|---|
| 导学/全景 | 能解释模型从数据到服务的路径 | 不要假设知道 Base/Chat/Reasoning 区别 |
| 数学/语言模型 | 能从 `[B,T]` 追到 logits 和 loss | 不要只展示公式，不检查形状 |
| Transformer | 能手算三 token causal attention | 不要把 attention head 解释成固定语义模块 |
| TinyGPT | 能保存、加载并解释一次训练 step | 不要以生成流畅度作为唯一成功标准 |
| 训练工程 | 能估算状态内存并设计恢复 | 不要把“权重能装下”当作“训练可行” |
| 推理 | 能区分 prefill、decode、TTFT、TPOT | 不要用一个 token/s 概括全部服务性能 |
| LoRA/SFT | 能做 Base 与 Adapter 的逐题对照 | 不要用几条演示数据宣称能力提升 |
| 对齐 | 能审计偏好数据与 DPO margin | 不要把 DPO 当成没有数据问题的快捷 SFT |
| 评估 | 能保存逐样本输出和错误类型 | 不要允许反复查看 test 后继续调参 |
| RAG/Agent | 能分离检索错、生成错和权限错 | 不要先接 Agent 再讨论状态机和权限 |
| 服务 | 能测试健康、错误、延迟和取消 | 不要把本地教学 API 当成生产服务 |
| 高级主题 | 能提出可证伪架构决策 | 不要用论文单一数字外推到所有硬件 |

## 课堂抽查问题

- 如果 causal mask 去掉，为什么 loss 可能变得更好但模型反而失效？
- 如果 KV Cache 正确但更慢，哪些固定条件需要重新检查？
- 如果 LoRA 让目标格式更好但通用任务下降，哪些指标决定是否接受？
- 如果 RAG 的正确文档已经在 Top-1，为什么回答仍可能错误？
- 如果平均延迟下降但 P99 上升，产品是否一定变好？

## 作业提交格式

学生每次提交：

```text
README.md                 # 环境与运行命令
reports/<experiment>.md   # 问题、对照、结果、边界
artifacts/                # 小型日志、指标、图表；不提交大模型权重
raw/                      # 必要的原始输出或脱敏样本
```

教师先检查命令是否能在干净进程运行，再检查结论是否超出证据。缺少 baseline、数据切分、硬件或随机种子时，最高只能得到“流程运行”分，不能得到“实验结论”分。

## 评分门槛

- 60 分：能运行并说明主流程。
- 70 分：形状、公式和断言正确。
- 80 分：有单变量对照、baseline 和逐样本结果。
- 90 分：能解释失败、统计不确定性、资源边界和安全影响。
- 100 分：能把机制迁移到新问题，并提出可复查的下一步实验。

一票否决：泄漏测试集、提交凭据、跨用户越权、伪造性能数字或把未运行的实验写成已复现。