本仓库用于《大模型基础与应用》期中作业，目标是手工搭建一个可训练的小规模 Transformer，并在小数据集上完成验证、实验分析与文档撰写。当前版本默认使用 Tiny Shakespeare（Hugging Face: tiny_shakespeare）作为示例数据集，并在本地缓存拆分后的文本、训练流程与元数据日志，后续可在此基础上扩展实验与报告。

• 安装 uv（已安装可跳过）：参考 https://docs.astral.sh/uv/
• 创建并激活虚拟环境：

  uv venv
  source .venv/bin/activate

• 安装依赖：

  uv pip install -r requirements.txt

• 下载 Tiny Shakespeare 并拆分为 train / validation / test（首次必跑，需联网，脚本会从 Karpathy 的 char-rnn 仓库拉取原始文本）：

  uv run python scripts/prepare_tiny_shakespeare.py

• 运行示例训练（使用 Tiny Shakespeare 子集，默认配置适合笔记本）：

  ./scripts/run.sh configs/base.yaml

训练完成后，会在 results/tiny_shakespeare_encoder/ 生成：

• metadata.json：记录实验、数据、模型、优化器与 tokenizer 配置。
• metrics.json：逐 epoch 的训练 / 验证 loss。
• loss_curve.png：收敛曲线，可直接引用到报告。
• model.pt：包含模型、优化器与调度器权重，便于后续继续训练。
• tokenizer.json：与当前语料对应的词表。

• configs/：实验配置文件（默认 base.yaml 对应 Tiny Shakespeare 轻量设置）。
• data/tiny_shakespeare/：运行 prepare_tiny_shakespeare.py 后生成的本地数据（脚本会自动导出 tiny_shakespeare.zip，推荐在提交前将其加入仓库）。
• docs/：作业说明与架构文档。
• results/：训练曲线、模型权重与实验指标的输出目录。
• scripts/run.sh：统一的训练入口脚本，封装了环境变量与命令行参数。
• src/fundamentals_large_models/：核心源码，包含配置解析、数据流水线、模型组件与训练流程。
• main.py：简易入口，等价于执行 python -m fundamentals_large_models.train。

• 支持 Tiny Shakespeare 快速迭代，默认 batch_size=16、seq_len=128 适配常见笔记本。
• AdamW + 梯度裁剪 + warmup + cosine decay，可根据配置快速切换。
• 每轮自动在 validation split 评估，并把 loss 曲线保存至 loss_curve.png。
• 自动写入 metadata.json、metrics.json、model.pt、tokenizer.json 等复现实验所需资产。
• Tokenizer 词表支持缓存 / 加载，保证多次运行的一致性。

为满足作业“手工 Transformer + 消融实验”要求，仓库提供以下配置（结果目录位于 results/ 对应子文件夹）：

• ./scripts/run.sh configs/base.yaml：基线模型（2 层 Encoder、4 头注意力、含位置编码）。
• ./scripts/run.sh configs/ablation_no_positional_encoding.yaml：移除正弦位置编码，观察性能下降幅度。
• ./scripts/run.sh configs/ablation_reduced_capacity.yaml：保持位置编码但将注意力头数减半、FFN 缩小，模拟容量不足。

运行完成后，可比较各自的 metrics.json / loss_curve.png，在报告中整理表格或折线图，并描述差异原因。 三组实验的验证 loss 摘要已记录于 docs/experiment_summary.md。