术语、排错与参考资料

阅读顺序与随用随查

有编程经验但第一次训练模型，可以按 1—26 课顺序学习。第 4—7 课是数字与学习机制，第 8—15 课是 GPT 结构。若在第 11 课的矩阵尺寸上卡住，回到第 5 课手算一行，再继续。无需在开始前先修完整的高等数学课程，但要愿意追踪少量数字。

每个页面末尾有独立实验代码，可在项目根目录执行 .venv/bin/python lessons/课号/experiment.py。练习修改前可以先复制为 my_experiment.py，避免后续重新构建课程时覆盖自己改过的示例。全套正式源码在 poetry_gpt/。

术语对应表

代码里常见的词	这里怎样理解	相关课
corpus / 语料	提供给模型学习的文字材料	2—3
token	模型处理的一个编号单位；本项目通常是汉字或特殊标记	4
vocabulary	编号与文字之间的固定对照表	4、8
tensor	带有明确形状的一组数字	5
batch	一次更新同时处理的多条题目	5、17
logits	尚未变成概率的原始候选分数	6
softmax	把分数转换为总和为 1 的非负权重	6、10
loss	衡量本次预测有多差的数字	6
gradient	误差对各参数变化的敏感方向	7
backward	沿计算关系求梯度	7
optimizer	根据梯度调整参数的程序	7、16
learning rate	控制每次调整的大致幅度	17
embedding	按编号取出一行可学习数字	8
context	本次计算直接能够利用的前文范围	9
attention	根据权重汇总不同位置的信息	10
Q / K / V	用于比较、被比较、被汇总的三组表示	11
causal mask	阻止当前位置看到尚未出现的信息	12
head	一组独立的注意力汇总计算	13
feedforward	对每个位置独立进行的共享加工	14
residual	原输入与加工结果相加的通路	14
LayerNorm	沿每个位置的表示宽度控制数值尺度	14
dropout	训练时随机丢弃部分数值的办法	14
checkpoint	保存某阶段模型及配套状态的文件	18
overfitting	学习材料表现变好，但新材料表现恶化的现象	19
inference	读取已学参数执行预测或生成	20
temperature	改变最终候选分布尖锐程度的控制量	20
top-k	只在当前最高分的 K 个候选中选择	20
weak label	用规则自动得到、可能有误差的标签	22

Python 读代码小抄

a[:-1] 取除最后一项之外的内容；a[1:] 从第二项开始取。enumerate(items) 同时给出位置和元素。with 用于管理文件等资源，结束后自动关闭。Path 处理文件路径。dict.get(name, default) 允许字段缺失时使用默认值。

nn.Module 是 PyTorch 管理模型部件的基类。写在构造函数并注册的层会参与参数统计、保存、移动设备。forward 定义输入如何变成输出。调用 model(x) 会进入它的前向过程。.train() 与 .eval() 改变 Dropout 等部件的行为；它们本身不会启动训练，也不会自动更新参数。

torch.no_grad() 暂停记录求导关系，适合评估和生成。loss.backward() 求梯度，optimizer.step() 才更新参数。.item() 把单个张量数值取成普通 Python 数，适合打印；不要拿它替代用于求导的 loss。

数学符号小抄

点乘：对应项相乘再相加，例如 [1,2]·[3,4]=11。矩阵乘法：一行与一列反复点乘。转置：交换行和列。平方根：平方后等于原数的非负值，例如 sqrt(4)=2。指数 exp(x)：softmax 用它把任意分数变为正数。自然对数 ln(x)：指数的反运算，本项目用 -ln(正确字概率) 评分。

梯度可以先从斜率理解。误差 L=(w-3)² 的斜率是 2(w-3)；当前斜率为负时，稍增大 w 会降低误差。多层模型靠链式法则把变化影响逐步传回。课程第 7 课先手算，再用自动求导对照。

报错时从哪里开始

现象	先检查什么	可执行动作
没有学习环境	项目 .venv 是否存在	`sh scripts/setup.sh`
找不到 torch	是否使用项目的 Python	用 `./poet` 或 `.venv/bin/python`
mps 不可用	当前进程是否能访问 Mac 加速	普通终端运行 doctor，或先用 CPU 实验
显示找不到原诗	当前材料源路径是否正确	`prepare --source` 指向仓库
材料目录已存在	是否误覆盖旧实验	为练习指定新的 output
输入字不在字表	是否生僻字或模型字表不匹配	换已收录字；扩表需要配套训练
矩阵尺寸不匹配	最后两维和头数	打印 shape，对照第 5、13 课
误差不下降	目标错位、梯度、更新是否接通	先运行第 16 课小题
误差变为 NaN	学习率、遮挡和数值范围	停止，回到小配置检查
内存不足	批数量和模型宽度	降低 batch-size 或使用 tiny
恢复提示材料不一致	是否换了数据或字表	选回同一份材料
诗有四行但意思不自然	训练阶段、采样和条件覆盖	保留样例，比较验证与固定生成题
关键词不出现	标签稀疏或模型控制较弱	检查标签，比较多候选，人工审阅
浏览器无法保存进度	本地存储是否被禁用	正文仍可读，另行记下课号
课程地址打不开	课程后台服务是否运行	先用 `./poet course --status` 查询，再用 `./poet course --start` 启动
预览端口占用	已有其他程序使用该端口	`./poet course --start --port 8767`，随后打开显示的新地址

文件与复现范围

课程不读取网络字体、远程脚本或远程模型接口。首次安装依赖需要网络，之后使用现成模型在本机生成。双击 course/dist/index.html 可以离线阅读。需要 HTTP 阅读时运行 ./poet course --start，默认地址为 http://127.0.0.1:8766/，只绑定本机。启动命令返回后服务仍在后台运行；电脑重启后需再次启动。--status 查看状态，--stop 停止服务。--serve 用于前台调试，关闭该进程后网页地址会停止响应。

随机种子帮助同一环境重现。跨 CPU、MPS、CUDA、软件版本或并行实现，浮点计算和随机轨迹可能不同，不能保证字节级相同输出。记录配置、材料摘要、环境版本和实际结果比只记录 seed 更完整。

一手参考资料

本课程主线实现为便于学习而编写，并非直接运行上述项目的训练脚本。minGPT 的维护状态与当前工具版本需要分别核对；我们使用本项目固定依赖和实际验证结果。原始数据来自仓库，自动繁简转换和材料筛选不等于权威古籍校勘。