Transformer From Scratch (Assignment)

按作业要求实现 Transformer 编码器（可扩展到编码器-解码器），提供可复现实验脚本与结果可视化。

项目概述

本项目完整实现了 Transformer 架构，包括：

• Encoder-only Transformer：用于语言建模任务
• Encoder-Decoder Transformer：用于序列到序列任务（机器翻译、文本摘要）
• 完整的评估指标：Loss、Perplexity、Accuracy
• 消融实验框架：系统对比不同配置的效果
• 相对位置编码：支持绝对和相对位置编码

项目结构

├── src/
│   ├── models/              # Transformer 模型实现
│   │   ├── layers.py        # 核心组件：MHA、FFN、LayerNorm、位置编码、相对位置编码
│   │   ├── encoder.py       # Encoder 实现
│   │   ├── decoder.py       # Decoder 实现
│   │   └── seq2seq.py       # Encoder-Decoder 组合模型
│   ├── configs/             # 配置文件
│   │   ├── base.yaml        # 统一配置文件（支持 LM 和 Seq2Seq）
│   │   ├── ablation.yaml    # 消融实验配置
│   │   └── relative_pos.yaml # 相对位置编码配置
│   ├── data.py              # 数据加载与预处理
│   ├── train.py             # 训练主程序
│   ├── run_ablation.py      # 消融实验脚本
│   ├── inference.py         # 模型推理脚本
│   └── utils.py             # 工具函数
├── scripts/
│   ├── run.sh               # Linux/Mac 运行脚本
│   ├── run.ps1              # Windows PowerShell 脚本
│   ├── run_ablation.sh      # 消融实验脚本（Linux/Mac）
│   └── run_ablation.ps1     # 消融实验脚本（Windows）
├── results/                 # 实验结果
│   ├── seq2seq/             # seq2seq结果
│   ├── ablation/            # 消融实验结果
│   │   ├── baseline/        # 基准实验
│   │   ├── comparison.png  # 所有实验对比图
│   │   └── summary.json    # 结果汇总
│   └── logs/               # 训练日志
├── data/                    # 本地数据集（可选）
├── requirements.txt        # Python 依赖
└── README.md               # 项目说明

依赖安装

# 创建虚拟环境
conda create --name trans python=3.10 
conda activate trans

# 安装依赖
pip install -r requirements.txt

2. 运行实验

Windows (PowerShell)

# 直接运行
.\scripts\run.ps1

Linux/Mac (Bash)

bash scripts/run.sh 

Python 命令

python -m src.train --config src/configs/base.yaml --task seq2seq --arch encdec --dataset iwslt2017 --seed 3407 --device cpu

数据集说明

语言建模任务（LM）

数据集	任务类型	大小	用途	Hugging Face ID
Tiny Shakespeare	字符级语言建模	~1MB	快速测试，收敛快	tiny_shakespeare
WikiText-2	词级语言建模	~2M tokens	标准基准测试	wikitext

序列到序列任务（Seq2Seq）

数据集	任务类型	大小	用途	Hugging Face ID
IWSLT2017	机器翻译 (EN↔DE)	~200K pairs	小规模翻译基准	iwslt2017

运行所有消融实验

# Windows PowerShell
.\scripts\run_ablation.ps1

# Linux/Mac
bash scripts/run_ablation.sh

运行特定实验

# Windows PowerShell
.\scripts\run_ablation.ps1 -Exps @("baseline", "no_pos_encoding", "no_residual")

# Linux/Mac
bash scripts/run_ablation.sh src/configs/ablation.yaml cpu "baseline no_pos_encoding no_residual"