创建工程

.gitignore

@@ -0,0 +1,48 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution
+dist/
+build/
+*.egg-info/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Data
+data/
+*.tsv
+*.csv
+
+# Checkpoints & Outputs
+checkpoints/
+outputs/
+logs/
+wandb/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Models
+*.pt
+*.pth
+*.bin
+*.safetensors
+*.onnx
+
+# Tokenizer artifacts
+*.model
+*.vocab
+tokenizer.json

README.md

@@ -1,4 +1,77 @@
 ---
 license: mit
 ---
-EasyTranslate: Transformer-Based Translation Model
+
+# EasyTranslate: 基于 Transformer 的英中翻译系统
+
+> 研究生 NLP 期末项目 — 使用前沿技术实现高质量英文到中文机器翻译
+
+## 亮点
+
+- **Pre-LayerNorm Transformer**: 从零构建，训练更稳定
+- **RoPE 旋转位置编码**: 替代传统正弦编码，更好捕获相对位置信息
+- **Flash Attention 2**: 利用 PyTorch 2.0+ 原生支持，训练显著加速
+- **NLLB 预训练微调**: 基于 Meta NLLB-200 模型，支持 LoRA 参数高效微调
+- **完整评估体系**: SacreBLEU + COMET + chrF++ 多维度评估
+- **6 组消融实验**: 系统验证各前沿组件的效果
+
+## 快速开始
+
+```bash
+# 安装
+conda create -n easytranslate python=3.11 && conda activate easytranslate
+pip install torch --index-url https://download.pytorch.org/whl/cu121
+pip install -r requirements.txt && pip install -e .
+
+# 从头训练 Transformer
+python scripts/train.py --config configs/default_config.yaml
+
+# 微调 NLLB + LoRA
+python scripts/train.py --config configs/default_config.yaml model.type=finetune_nllb
+
+# 评估
+python scripts/evaluate.py --checkpoint checkpoints/best_model.pt
+
+# 交互翻译
+python scripts/translate.py --checkpoint checkpoints/best_model.pt
+```
+
+## 项目结构
+
+```
+src/easytranslate/
+├── data/          # 数据加载、分词、预处理、动态批处理
+├── model/         # Transformer (Encoder-Decoder) + 注意力 + 位置编码 + LoRA
+├── training/      # 训练循环、优化器、损失函数、分布式训练
+├── evaluation/    # BLEU/COMET 指标、Beam Search 解码、评估器
+└── utils/         # 配置管理、日志、随机种子
+```
+
+## 技术架构
+
+```
+英文输入 → BPE Tokenizer → Source Embedding + RoPE
+    → Transformer Encoder (6 layers, Flash Attention, Pre-LN)
+    → Transformer Decoder (6 layers, Causal Mask, Cross-Attention)
+    → Linear Projection → Beam Search → 中文输出
+```
+
+## 团队分工
+
+详见 [TASK_ASSIGNMENT.md](TASK_ASSIGNMENT.md)
+
+| 角色 | 负责模块 | 核心任务 |
+|------|----------|----------|
+| Person A | `data/` | 数据集加载、BPE 分词器、预处理流水线 |
+| Person B | `model/` | Transformer 架构、Flash Attention、RoPE、LoRA |
+| Person C | `training/` | 训练循环、混合精度、梯度累积、早停 |
+| Person D | `evaluation/` | BLEU/COMET 评估、Beam Search、推理服务 |
+| Person E | `utils/` + 实验 | 工具模块、消融实验、可视化、报告 |
+
+## 依赖
+
+- Python >= 3.10
+- PyTorch >= 2.1 (Flash Attention 支持)
+- HuggingFace Transformers / Datasets / Tokenizers
+- PEFT (LoRA)
+- SacreBLEU, COMET (评估)

TASK_ASSIGNMENT.md

@@ -0,0 +1,414 @@
+# EasyTranslate 任务分工文档
+
+## 项目概述
+
+**项目名称**: EasyTranslate — 基于 Transformer 的英中翻译系统  
+**课程**: 研究生 NLP 期末作业  
+**团队规模**: 5 人  
+**技术栈**: PyTorch + HuggingFace Transformers + Flash Attention 2 + RoPE + LoRA  
+
+---
+
+## 📂 项目结构
+
+```
+UCAS-EasyTranslate/
+├── configs/
+│   ├── default_config.yaml          # 主配置文件
+│   └── deepspeed_config.json        # DeepSpeed 分布式训练配置
+├── src/easytranslate/
+│   ├── data/                        # [Person A] 数据模块
+│   │   ├── dataset.py               # 数据集加载
+│   │   ├── tokenizer.py             # 分词器
+│   │   ├── preprocessing.py         # 数据预处理
+│   │   └── collator.py              # 数据整理 & 动态批处理
+│   ├── model/                       # [Person B] 模型模块
+│   │   ├── transformer.py           # Transformer 主模型
+│   │   ├── encoder.py               # 编码器
+│   │   ├── decoder.py               # 解码器
+│   │   ├── attention.py             # 注意力机制 (标准 + Flash Attention)
+│   │   ├── positional.py            # 位置编码 (Sinusoidal + RoPE)
+│   │   └── finetune.py              # 预训练模型微调 (NLLB + LoRA)
+│   ├── training/                    # [Person C] 训练模块
+│   │   ├── trainer.py               # 训练器 (完整训练循环)
+│   │   ├── optimizer.py             # 优化器 & 学习率调度
+│   │   └── loss.py                  # 损失函数 (标签平滑)
+│   ├── evaluation/                  # [Person D] 评估模块
+│   │   ├── metrics.py               # 评估指标 (BLEU, COMET, chrF)
+│   │   ├── decoding.py              # 解码策略 (贪心, Beam Search, 采样)
+│   │   └── evaluator.py             # 评估器
+│   └── utils/                       # [Person E] 工具模块
+│       ├── config.py                # 配置管理
+│       ├── seed.py                  # 随机种子
+│       └── logging.py               # 日志管理
+├── scripts/
+│   ├── train.py                     # 训练入口
+│   ├── evaluate.py                  # 评估入口
+│   ├── translate.py                 # 翻译推理 (CLI + Web UI)
+│   ├── run_experiments.py           # [Person E] 实验运行器
+│   └── visualize.py                 # [Person E] 可视化分析
+├── tests/
+│   ├── test_data.py                 # 数据模块测试
+│   ├── test_model.py                # 模型模块测试
+│   ├── test_training.py             # 训练模块测试
+│   └── test_evaluation.py           # 评估模块测试
+├── requirements.txt
+├── setup.py
+└── README.md
+```
+
+---
+
+## 👥 人员分工
+
+### Person A — 数据工程师
+
+**负责文件**: `src/easytranslate/data/` 目录下所有文件  
+**预计工作量**: ~800 行代码  
+**截止日期建议**: 第 1-2 周
+
+#### 核心任务
+
+| 优先级 | 文件 | 任务 | 要点 |
+|--------|------|------|------|
+| P0 | `dataset.py` | `TranslationDataset.__getitem__` | 实现 tokenize + padding + teacher forcing 输入构造 |
+| P0 | `dataset.py` | `load_wmt_dataset` | 使用 HuggingFace datasets 加载 WMT19 zh-en |
+| P0 | `tokenizer.py` | `TokenizerWrapper` | 统一分词器接口 (encode/decode/vocab_size/special_tokens) |
+| P0 | `tokenizer.py` | `train_bpe_tokenizer` | 使用 HuggingFace tokenizers 库训练 BPE |
+| P0 | `tokenizer.py` | `build_tokenizer` | 根据配置构建分词器 |
+| P1 | `preprocessing.py` | `clean_text` | Unicode 标准化 + 控制字符去除 |
+| P1 | `preprocessing.py` | `filter_by_length` | 按长度和长度比过滤 |
+| P1 | `preprocessing.py` | `preprocess_pipeline` | 完整预处理流水线 |
+| P1 | `collator.py` | `TranslationCollator` | batch padding + mask 生成 |
+| P2 | `collator.py` | `DynamicBatchSampler` | 按 token 数动态构建 batch |
+| P2 | `dataset.py` | `load_opus_dataset` | OPUS-100 数据集加载 |
+| P2 | `dataset.py` | `load_custom_dataset` | 自定义语料加载 |
+
+#### 技术参考
+- HuggingFace datasets: https://huggingface.co/docs/datasets
+- HuggingFace tokenizers: https://huggingface.co/docs/tokenizers
+- WMT19 zh-en: `datasets.load_dataset("wmt19", "zh-en")`
+
+#### 验收标准
+- [ ] `pytest tests/test_data.py` 全部通过
+- [ ] 能够成功加载 WMT19 数据集并完成预处理
+- [ ] BPE 分词器训练成功，encode/decode 往返一致
+- [ ] DataLoader 能正常迭代，batch 维度正确
+
+---
+
+### Person B — 模型架构师
+
+**负责文件**: `src/easytranslate/model/` 目录下所有文件  
+**预计工作量**: ~1000 行代码  
+**截止日期建议**: 第 1-2 周
+
+#### 核心任务
+
+| 优先级 | 文件 | 任务 | 要点 |
+|--------|------|------|------|
+| P0 | `attention.py` | `MultiHeadAttention` | 标准多头注意力: QKV 投影 + scaled dot-product + mask |
+| P0 | `attention.py` | `FlashMultiHeadAttention` | 使用 F.scaled_dot_product_attention (PyTorch 2.0+) |
+| P0 | `positional.py` | `SinusoidalPositionalEncoding` | 经典正弦余弦位置编码 |
+| P0 | `positional.py` | `RotaryPositionalEmbedding` | RoPE 旋转位置编码 (前沿技术!) |
+| P0 | `encoder.py` | `TransformerEncoderLayer/Encoder` | Pre-LayerNorm Encoder |
+| P0 | `decoder.py` | `TransformerDecoderLayer/Decoder` | Pre-LayerNorm Decoder (self-attn + cross-attn + FFN) |
+| P0 | `transformer.py` | `TransformerTranslationModel` | 完整 Enc-Dec 模型: embedding + encoder + decoder + projection |
+| P1 | `transformer.py` | `encode / decode_step` | 推理用的编码和单步解码 |
+| P1 | `finetune.py` | `load_pretrained_model` | 加载 NLLB/mBART 预训练模型 |
+| P1 | `finetune.py` | `setup_lora` | 使用 PEFT 库配置 LoRA 微调 |
+
+#### 关键技术点
+
+1. **Pre-LayerNorm** (比 Post-LN 训练更稳定):
+   ```
+   x → LayerNorm → Attention → Add(x) → LayerNorm → FFN → Add
+   ```
+
+2. **RoPE 旋转位置编码** (LLaMA/GPT-NeoX 使用):
+   ```python
+   q' = q * cos(θ) + rotate_half(q) * sin(θ)
+   k' = k * cos(θ) + rotate_half(k) * sin(θ)
+   # attention(q', k') 自动编码相对位置信息
+   ```
+
+3. **Flash Attention 2** (PyTorch 2.0+ 原生支持):
+   ```python
+   F.scaled_dot_product_attention(Q, K, V, attn_mask, dropout_p, is_causal)
+   ```
+
+4. **LoRA 微调** (参数高效):
+   ```python
+   from peft import LoraConfig, get_peft_model, TaskType
+   config = LoraConfig(r=16, lora_alpha=32, target_modules=["q_proj", "v_proj"], task_type=TaskType.SEQ_2_SEQ_LM)
+   model = get_peft_model(model, config)
+   ```
+
+#### 验收标准
+- [ ] `pytest tests/test_model.py` 全部通过
+- [ ] 模型前向传播输出维度正确: `[B, T, vocab_size]`
+- [ ] Flash Attention 和标准 Attention 输出一致
+- [ ] RoPE 编码能正确应用到 Q, K
+- [ ] LoRA 模型可训练参数量远小于全量参数
+
+---
+
+### Person C — 训练工程师
+
+**负责文件**: `src/easytranslate/training/` 目录下所有文件  
+**预计工作量**: ~700 行代码  
+**截止日期建议**: 第 2-3 周 (依赖 Person A, B)
+
+#### 核心任务
+
+| 优先级 | 文件 | 任务 | 要点 |
+|--------|------|------|------|
+| P0 | `loss.py` | `LabelSmoothedCrossEntropyLoss` | 带标签平滑的交叉熵损失 + 忽略 padding |
+| P0 | `optimizer.py` | `build_optimizer` | 构建 AdamW，支持参数分组 |
+| P0 | `optimizer.py` | `build_scheduler` | Cosine with warmup / Inverse sqrt 调度器 |
+| P0 | `trainer.py` | `Trainer.__init__` | 初始化训练环境 (设备, 精度, 分布式) |
+| P0 | `trainer.py` | `_train_one_epoch` | 单 epoch 训练循环 (混合精度 + 梯度累积) |
+| P0 | `trainer.py` | `_validate` | 验证循环 |
+| P1 | `trainer.py` | `train` | 主训练循环 (多 epoch) |
+| P1 | `trainer.py` | `_save/_load_checkpoint` | 检查点保存和加载 |
+| P1 | `trainer.py` | `_should_early_stop` | 早停逻辑 |
+| P2 | `trainer.py` | `_setup_distributed` | DDP/FSDP/DeepSpeed 分布式训练 |
+| P2 | `trainer.py` | `_log_metrics` | TensorBoard/WandB 日志 |
+
+#### 关键技术点
+
+1. **混合精度训练**:
+   ```python
+   scaler = torch.amp.GradScaler('cuda')
+   with torch.amp.autocast('cuda', dtype=torch.float16):
+       logits = model(src, tgt)
+       loss = criterion(logits, labels)
+   scaler.scale(loss).backward()
+   scaler.step(optimizer)
+   scaler.update()
+   ```
+
+2. **梯度累积**:
+   ```python
+   loss = loss / gradient_accumulation_steps
+   loss.backward()
+   if (step + 1) % gradient_accumulation_steps == 0:
+       optimizer.step()
+       optimizer.zero_grad()
+   ```
+
+3. **标签平滑** (smoothing=0.1):
+   ```
+   对于 target token: prob = 1 - smoothing = 0.9
+   对于其他 token: prob = smoothing / (V - 1) ≈ 0.000003
+   ```
+
+#### 验收标准
+- [ ] `pytest tests/test_training.py` 全部通过
+- [ ] 能在小数据集上完成完整训练流程
+- [ ] Loss 能正常下降
+- [ ] 检查点能正确保存和加载
+- [ ] 早停机制正常工作
+
+---
+
+### Person D — 评估与推理工程师
+
+**负责文件**: `src/easytranslate/evaluation/` + `scripts/evaluate.py` + `scripts/translate.py`  
+**预计工作量**: ~800 行代码  
+**截止日期建议**: 第 2-3 周 (依赖 Person B)
+
+#### 核心任务
+
+| 优先级 | 文件 | 任务 | 要点 |
+|--------|------|------|------|
+| P0 | `metrics.py` | `compute_bleu` | SacreBLEU (tokenize="zh" 对中文分词) |
+| P0 | `metrics.py` | `compute_comet` | COMET 神经网络评估指标 |
+| P0 | `metrics.py` | `compute_chrf` / `compute_ter` | chrF++ 和 TER 指标 |
+| P0 | `decoding.py` | `greedy_decode` | 贪心解码 (逐 token argmax) |
+| P0 | `decoding.py` | `beam_search_decode` | 束搜索 (最关键的解码算法!) |
+| P1 | `decoding.py` | `sample_decode` | 采样解码 (temperature + top-k + top-p) |
+| P1 | `evaluator.py` | `Evaluator` | 统一评估接口 |
+| P1 | `scripts/evaluate.py` | 评估入口脚本 | 加载模型 → 评估 → 输出结果 |
+| P2 | `scripts/translate.py` | 交互翻译 | CLI 交互 + 文件翻译 |
+| P2 | `scripts/translate.py` | `launch_web_ui` | Gradio Web 界面 |
+
+#### 关键技术点
+
+1. **Beam Search** (翻译最核心的算法):
+   ```
+   维护 beam_size 个候选序列
+   每步扩展所有候选 → 选 top-k → 继续
+   完成后按 score / length^penalty 排序
+   ```
+
+2. **SacreBLEU** (标准化评估):
+   ```python
+   import sacrebleu
+   bleu = sacrebleu.corpus_bleu(hypotheses, [references], tokenize="zh")
+   ```
+
+3. **COMET** (最准确的评估指标):
+   ```python
+   from comet import download_model, load_from_checkpoint
+   model = load_from_checkpoint(download_model("Unbabel/wmt22-comet-da"))
+   data = [{"src": s, "mt": h, "ref": r} for s, h, r in zip(sources, hyps, refs)]
+   output = model.predict(data)
+   ```
+
+#### 验收标准
+- [ ] `pytest tests/test_evaluation.py` 全部通过
+- [ ] BLEU 计算结果与 sacrebleu CLI 一致
+- [ ] Beam search 翻译质量 ≥ Greedy
+- [ ] 能完成端到端评估流程
+- [ ] 交互翻译模式正常工作
+
+---
+
+### Person E — 实验与报告
+
+**负责文件**: `src/easytranslate/utils/` + `scripts/run_experiments.py` + `scripts/visualize.py` + 实验报告  
+**预计工作量**: ~600 行代码 + 实验报告  
+**截止日期建议**: 第 1 周 (utils) + 第 3-4 周 (实验)
+
+#### 核心任务
+
+| 优先级 | 文件 | 任务 | 要点 |
+|--------|------|------|------|
+| P0 | `utils/config.py` | 配置管理 | OmegaConf 加载 + CLI 覆盖 |
+| P0 | `utils/seed.py` | 随机种子 | 全局种子设置 (可复现) |
+| P0 | `utils/logging.py` | 日志系统 | Rich 美化 + 文件日志 |
+| P1 | `scripts/run_experiments.py` | 实验运行器 | 自动化运行 6 组消融实验 |
+| P1 | `scripts/visualize.py` | 训练曲线 | Loss/BLEU/LR 曲线绘制 |
+| P1 | `scripts/visualize.py` | 实验对比 | 柱状图 + 表格对比 |
+| P2 | `scripts/visualize.py` | 注意力可视化 | Cross-attention 热力图 |
+| P2 | `scripts/visualize.py` | 翻译样例 | 好坏案例展示 |
+| P0 | — | 实验报告 | 撰写完整实验报告 |
+
+#### 实验设计 (6 组消融实验)
+
+| 实验编号 | 实验名称 | 关键变量 | 目的 |
+|----------|----------|----------|------|
+| Exp1 | Baseline Transformer | 标准 6 层, d=512, 正弦位置编码 | 基线 |
+| Exp2 | + RoPE | 替换正弦编码为 RoPE | 验证旋转位置编码效果 |
+| Exp3 | + Flash Attention | 使用 Flash Attention 2 | 验证训练加速效果 |
+| Exp4 | Full (RoPE + Flash) | RoPE + Flash Attention | 完整前沿方案 |
+| Exp5 | NLLB + LoRA | 预训练 NLLB-600M + LoRA r=16 | 预训练微调效果 |
+| Exp6 | NLLB Full FT | 预训练 NLLB-600M 全量微调 | 微调上界 |
+
+#### 报告结构建议
+1. **摘要**: 项目目标、方法、主要结果
+2. **引言**: 机器翻译背景、Transformer 发展、研究动机
+3. **相关工作**: Transformer、NLLB、LoRA、Flash Attention、RoPE
+4. **方法**:
+   - 模型架构 (附架构图)
+   - 训练策略 (混合精度、标签平滑、调度器)
+   - 预训练微调方案 (NLLB + LoRA)
+5. **实验**:
+   - 数据集 (WMT19 zh-en)
+   - 实验设置 (超参数表)
+   - 实验结果 (BLEU/COMET/chrF 表格)
+   - 消融分析 (各组件贡献)
+   - 训练效率对比 (Flash Attention 加速比)
+6. **分析**:
+   - 注意力可视化
+   - 翻译案例分析
+   - 错误分析
+7. **结论与展望**
+
+#### 验收标准
+- [ ] utils 模块功能正常
+- [ ] 6 组实验能自动化运行
+- [ ] 生成完整的可视化图表
+- [ ] 实验报告完整，图表清晰
+
+---
+
+## 🗓️ 时间线
+
+```
+第 1 周: Person A (数据) + Person B (模型) + Person E (utils) 并行开发
+         ↓
+第 2 周: Person C (训练, 依赖 A+B) + Person D (评估, 依赖 B) 开始
+         Person A, B 完善和联调
+         ↓
+第 3 周: 全体联调 → scripts/train.py 整合
+         Person E 开始跑实验
+         ↓
+第 4 周: Person E 完成实验 + 报告
+         全体 Review + 优化
+```
+
+## 🔌 模块接口约定
+
+### 分词器接口 (Person A 定义, Person B/C/D 使用)
+```python
+tokenizer.encode(text: str) -> list[int]
+tokenizer.decode(ids: list[int]) -> str
+tokenizer.vocab_size -> int
+tokenizer.pad_id -> int
+tokenizer.bos_id -> int
+tokenizer.eos_id -> int
+```
+
+### 模型接口 (Person B 定义, Person C/D 使用)
+```python
+# 训练
+logits = model(src_ids, tgt_input_ids, src_padding_mask, tgt_padding_mask)
+# logits: [B, T, vocab_size]
+
+# 推理
+encoder_output = model.encode(src_ids, src_padding_mask)
+next_logits = model.decode_step(tgt_input_ids, encoder_output, src_padding_mask)
+```
+
+### 数据 Batch 格式 (Person A 定义, Person C 使用)
+```python
+batch = {
+    "src_ids": Tensor[B, S],
+    "tgt_input_ids": Tensor[B, T],
+    "labels": Tensor[B, T],
+    "src_padding_mask": BoolTensor[B, S],
+    "tgt_padding_mask": BoolTensor[B, T],
+}
+```
+
+### 评估接口 (Person D 定义, Person C/E 使用)
+```python
+evaluator = Evaluator(model, tokenizer, config)
+results = evaluator.evaluate(dataloader)
+# results: {"bleu": 25.6, "comet": 0.82, "chrf": 45.3, "ter": 55.2}
+```
+
+---
+
+## ⚙️ 开发环境
+
+```bash
+# 1. 创建虚拟环境
+conda create -n easytranslate python=3.11
+conda activate easytranslate
+
+# 2. 安装 PyTorch (CUDA 12.1)
+pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121
+
+# 3. 安装项目依赖
+pip install -r requirements.txt
+
+# 4. 安装项目 (开发模式)
+pip install -e .
+
+# 5. 运行测试
+pytest tests/ -v
+```
+
+---
+
+## ✅ 最终交付清单
+
+- [ ] 代码: 所有 `TODO: Person X` 均已实现
+- [ ] 测试: `pytest tests/` 全部通过
+- [ ] 训练: 至少完成 Exp1 (基线) 和 Exp5 (NLLB+LoRA) 两组实验
+- [ ] 评估: 在 WMT19 测试集上报告 BLEU / COMET 分数
+- [ ] 报告: 完整实验报告 (含图表)
+- [ ] 演示: 交互翻译 Demo 可运行

configs/deepspeed_config.json

@@ -0,0 +1,28 @@
+{
+    "fp16": {
+        "enabled": true,
+        "loss_scale": 0,
+        "loss_scale_window": 1000,
+        "initial_scale_power": 16,
+        "hysteresis": 2,
+        "min_loss_scale": 1
+    },
+    "zero_optimization": {
+        "stage": 2,
+        "offload_optimizer": {
+            "device": "cpu",
+            "pin_memory": true
+        },
+        "allgather_partitions": true,
+        "allgather_bucket_size": 2e8,
+        "overlap_comm": true,
+        "reduce_scatter": true,
+        "reduce_bucket_size": 2e8,
+        "contiguous_gradients": true
+    },
+    "gradient_accumulation_steps": 4,
+    "gradient_clipping": 1.0,
+    "train_batch_size": "auto",
+    "train_micro_batch_size_per_gpu": "auto",
+    "wall_clock_breakdown": false
+}

configs/default_config.yaml

@@ -0,0 +1,182 @@
+# ============================================================================
+# EasyTranslate 默认配置文件
+# 基于 Transformer 架构的英中翻译模型
+# ============================================================================
+
+# ---------- 模型配置 ----------
+model:
+  # 模型类型: "transformer_scratch" | "finetune_nllb" | "finetune_mbart"
+  type: "transformer_scratch"
+
+  # === Transformer from scratch 配置 ===
+  transformer:
+    d_model: 512               # 模型维度
+    nhead: 8                   # 多头注意力头数
+    num_encoder_layers: 6      # 编码器层数
+    num_decoder_layers: 6      # 解码器层数
+    dim_feedforward: 2048      # FFN 中间维度
+    dropout: 0.1               # Dropout 概率
+    activation: "gelu"         # 激活函数: "relu" | "gelu"
+    max_seq_len: 512           # 最大序列长度
+    use_flash_attention: true  # 是否使用 Flash Attention 2
+    use_rotary_embedding: true # 是否使用旋转位置编码 (RoPE)
+    pre_norm: true             # Pre-LayerNorm (更稳定)
+
+  # === 预训练模型微调配置 ===
+  pretrained:
+    model_name: "facebook/nllb-200-distilled-600M"  # HuggingFace 模型名
+    src_lang: "eng_Latn"       # 源语言代码
+    tgt_lang: "zho_Hans"       # 目标语言代码
+    use_lora: true             # 是否使用 LoRA 微调
+    lora:
+      r: 16                    # LoRA 秩
+      alpha: 32                # LoRA alpha
+      dropout: 0.05            # LoRA dropout
+      target_modules:          # LoRA 目标模块
+        - "q_proj"
+        - "v_proj"
+        - "k_proj"
+        - "o_proj"
+
+# ---------- 分词器配置 ----------
+tokenizer:
+  # 分词器类型: "bpe" | "sentencepiece" | "pretrained"
+  type: "bpe"
+  vocab_size: 32000            # 词汇表大小
+  min_frequency: 2             # 最小词频
+  special_tokens:
+    pad: "<pad>"
+    unk: "<unk>"
+    bos: "<s>"
+    eos: "</s>"
+  max_length: 512              # 最大 token 长度
+
+# ---------- 数据配置 ----------
+data:
+  # 数据集: "wmt" | "opus" | "custom"
+  dataset_name: "wmt"
+  wmt:
+    year: "19"                 # WMT 年份
+    language_pair: "zh-en"     # 语言对
+  opus:
+    subset: "UNPC"             # OPUS 子集名
+  custom:
+    train_src: "data/train.en" # 自定义训练集源语言
+    train_tgt: "data/train.zh"
+    val_src: "data/val.en"
+    val_tgt: "data/val.zh"
+    test_src: "data/test.en"
+    test_tgt: "data/test.zh"
+
+  # 数据处理
+  preprocessing:
+    lowercase_src: false       # 源语言是否小写化
+    remove_punctuation: false  # 是否去除标点
+    max_src_len: 256           # 源语言最大长度
+    max_tgt_len: 256           # 目标语言最大长度
+    filter_by_length: true     # 是否按长度过滤
+    length_ratio_threshold: 3.0 # 长度比阈值
+
+  # DataLoader
+  dataloader:
+    batch_size: 32
+    num_workers: 4
+    pin_memory: true
+    dynamic_batching: true     # 动态 batch (按 token 数)
+    max_tokens_per_batch: 8192 # 动态 batch 最大 token 数
+
+# ---------- 训练配置 ----------
+training:
+  # 基础训练参数
+  epochs: 30
+  max_steps: -1                # -1 表示按 epoch 训练
+  gradient_accumulation_steps: 4
+  fp16: true                   # 混合精度训练
+  bf16: false                  # BF16 (A100+)
+  gradient_checkpointing: false
+
+  # 优化器
+  optimizer:
+    type: "adamw"              # "adam" | "adamw" | "adafactor"
+    lr: 3.0e-4
+    weight_decay: 0.01
+    betas: [0.9, 0.98]
+    eps: 1.0e-8
+
+  # 学习率调度
+  scheduler:
+    type: "cosine_with_warmup" # "cosine_with_warmup" | "inverse_sqrt" | "linear"
+    warmup_steps: 4000
+    min_lr: 1.0e-6
+
+  # 正则化
+  regularization:
+    label_smoothing: 0.1       # 标签平滑
+    dropout: 0.1
+
+  # 检查点
+  checkpoint:
+    save_dir: "checkpoints/"
+    save_every_n_steps: 5000
+    save_best: true            # 保存最佳模型
+    metric_for_best: "bleu"    # 选择最佳模型的指标
+    max_checkpoints: 5         # 最大保存检查点数
+
+  # 早停
+  early_stopping:
+    enabled: true
+    patience: 5
+    min_delta: 0.1
+
+  # 分布式训练
+  distributed:
+    strategy: "ddp"            # "ddp" | "fsdp" | "deepspeed"
+    deepspeed_config: "configs/deepspeed_config.json"
+
+# ---------- 评估配置 ----------
+evaluation:
+  # 评估指标
+  metrics:
+    - "bleu"                   # SacreBLEU
+    - "comet"                  # COMET (神经网络指标)
+    - "chrf"                   # chrF++
+    - "ter"                    # TER
+
+  # 解码策略
+  decoding:
+    strategy: "beam_search"    # "greedy" | "beam_search" | "sampling"
+    beam_size: 5
+    length_penalty: 1.0
+    no_repeat_ngram_size: 3
+    max_decode_len: 256
+
+    # Sampling 参数
+    sampling:
+      temperature: 0.7
+      top_k: 50
+      top_p: 0.9
+
+  # 评估频率
+  eval_every_n_steps: 1000
+  eval_on_epoch_end: true
+
+# ---------- 日志配置 ----------
+logging:
+  # 日志工具: "wandb" | "tensorboard" | "both"
+  backend: "tensorboard"
+  project_name: "EasyTranslate"
+  log_every_n_steps: 100
+  log_dir: "logs/"
+
+# ---------- 推理/部署配置 ----------
+inference:
+  model_path: "checkpoints/best_model"
+  device: "cuda"
+  batch_size: 16
+  quantization: null           # null | "int8" | "int4"
+
+# ---------- 实验配置 ----------
+experiment:
+  seed: 42
+  name: "baseline"
+  output_dir: "outputs/"

pytest.ini

@@ -0,0 +1,6 @@
+[pytest]
+testpaths = tests
+python_files = test_*.py
+python_functions = test_*
+python_classes = Test*
+addopts = -v --tb=short

requirements.txt

@@ -0,0 +1,35 @@
+# Core
+torch>=2.1.0
+transformers>=4.36.0
+datasets>=2.16.0
+tokenizers>=0.15.0
+sentencepiece>=0.1.99
+accelerate>=0.25.0
+
+# Training
+deepspeed>=0.12.0
+bitsandbytes>=0.41.0
+peft>=0.7.0
+wandb>=0.16.0
+tensorboard>=2.15.0
+
+# Evaluation
+sacrebleu>=2.4.0
+unbabel-comet>=2.2.0
+rouge-score>=0.1.2
+nltk>=3.8.0
+
+# Utilities
+numpy>=1.24.0
+pandas>=2.0.0
+tqdm>=4.66.0
+pyyaml>=6.0.0
+omegaconf>=2.3.0
+rich>=13.0.0
+matplotlib>=3.8.0
+seaborn>=0.13.0
+
+# Serving (optional)
+fastapi>=0.108.0
+uvicorn>=0.25.0
+gradio>=4.10.0

scripts/evaluate.py

@@ -0,0 +1,50 @@
+"""
+评估入口脚本
+
+使用方式:
+    # 在测试集上评估
+    python scripts/evaluate.py --config configs/default_config.yaml --checkpoint checkpoints/best_model.pt
+
+    # 指定解码策略
+    python scripts/evaluate.py --checkpoint checkpoints/best_model.pt evaluation.decoding.strategy=beam_search evaluation.decoding.beam_size=10
+"""
+
+import argparse
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent / "src"))
+
+
+def parse_args():
+    parser = argparse.ArgumentParser(description="EasyTranslate Evaluation")
+    parser.add_argument("--config", type=str, default="configs/default_config.yaml")
+    parser.add_argument("--checkpoint", type=str, required=True, help="模型检查点路径")
+    parser.add_argument("--output", type=str, default="outputs/evaluation_results.json", help="结果保存路径")
+    args, unknown = parser.parse_known_args()
+    return args, unknown
+
+
+def main():
+    """
+    评估主流程。
+
+    TODO [Person D]:
+    1. 加载配置和检查点
+    2. 重建模型并加载权重
+    3. 加载测试数据
+    4. 构建 Evaluator
+    5. 运行评估
+    6. 打印和保存结果
+    """
+    args, cli_overrides = parse_args()
+
+    print("=" * 60)
+    print("  EasyTranslate - Evaluation")
+    print("=" * 60)
+
+    raise NotImplementedError("TODO: Person D 实现评估主流程")
+
+
+if __name__ == "__main__":
+    main()

scripts/run_experiments.py

@@ -0,0 +1,113 @@
+"""
+实验运行脚本 — Person E 负责
+
+自动化运行消融实验，比较不同配置的效果。
+
+使用方式:
+    python scripts/run_experiments.py
+"""
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent / "src"))
+
+
+# 实验配置列表
+EXPERIMENTS = [
+    {
+        "name": "exp1_baseline_transformer",
+        "description": "基线: 从头训练标准 Transformer (6层, d=512)",
+        "overrides": {
+            "model.type": "transformer_scratch",
+            "model.transformer.num_encoder_layers": 6,
+            "model.transformer.num_decoder_layers": 6,
+            "model.transformer.d_model": 512,
+            "model.transformer.use_flash_attention": False,
+            "model.transformer.use_rotary_embedding": False,
+        },
+    },
+    {
+        "name": "exp2_transformer_rope",
+        "description": "消融: Transformer + RoPE 位置编码",
+        "overrides": {
+            "model.type": "transformer_scratch",
+            "model.transformer.use_rotary_embedding": True,
+        },
+    },
+    {
+        "name": "exp3_transformer_flash_attn",
+        "description": "消融: Transformer + Flash Attention 2",
+        "overrides": {
+            "model.type": "transformer_scratch",
+            "model.transformer.use_flash_attention": True,
+        },
+    },
+    {
+        "name": "exp4_transformer_full",
+        "description": "完整: Transformer + RoPE + Flash Attention",
+        "overrides": {
+            "model.type": "transformer_scratch",
+            "model.transformer.use_flash_attention": True,
+            "model.transformer.use_rotary_embedding": True,
+        },
+    },
+    {
+        "name": "exp5_nllb_lora",
+        "description": "预训练微调: NLLB-600M + LoRA",
+        "overrides": {
+            "model.type": "finetune_nllb",
+            "model.pretrained.use_lora": True,
+            "model.pretrained.lora.r": 16,
+        },
+    },
+    {
+        "name": "exp6_nllb_full_finetune",
+        "description": "预训练全量微调: NLLB-600M",
+        "overrides": {
+            "model.type": "finetune_nllb",
+            "model.pretrained.use_lora": False,
+        },
+    },
+]
+
+
+def run_single_experiment(exp_config: dict):
+    """
+    运行单个实验。
+
+    TODO [Person E]:
+    1. 从 base config 创建实验配置
+    2. 应用 overrides
+    3. 设置 experiment.name 和 output_dir
+    4. 调用训练流程
+    5. 在测试集上评估
+    6. 保存实验结果
+    """
+    raise NotImplementedError("TODO: Person E 实现 run_single_experiment")
+
+
+def main():
+    """
+    运行所有实验。
+
+    TODO [Person E]:
+    1. 遍历 EXPERIMENTS 列表
+    2. 对每个实验调用 run_single_experiment
+    3. 收集所有实验结果
+    4. 生成对比表格
+    5. 保存汇总报告
+    """
+    print("=" * 60)
+    print("  EasyTranslate - Experiment Runner")
+    print("=" * 60)
+
+    for exp in EXPERIMENTS:
+        print(f"\n>>> Running: {exp['name']} - {exp['description']}")
+        # run_single_experiment(exp)
+
+    raise NotImplementedError("TODO: Person E 实现实验运行主流程")
+
+
+if __name__ == "__main__":
+    main()

scripts/train.py

@@ -0,0 +1,76 @@
+"""
+训练入口脚本
+
+使用方式:
+    # 从头训练 Transformer
+    python scripts/train.py --config configs/default_config.yaml
+
+    # 微调 NLLB
+    python scripts/train.py --config configs/default_config.yaml model.type=finetune_nllb
+
+    # 命令行覆盖参数
+    python scripts/train.py --config configs/default_config.yaml training.optimizer.lr=1e-4
+
+    # 分布式训练
+    torchrun --nproc_per_node=4 scripts/train.py --config configs/default_config.yaml
+"""
+
+import argparse
+import sys
+from pathlib import Path
+
+# 将 src 目录加入 Python path
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent / "src"))
+
+
+def parse_args():
+    parser = argparse.ArgumentParser(description="EasyTranslate Training")
+    parser.add_argument("--config", type=str, default="configs/default_config.yaml", help="配置文件路径")
+    parser.add_argument("--resume", type=str, default=None, help="检查点路径 (断点续训)")
+    args, unknown = parser.parse_known_args()
+    return args, unknown
+
+
+def main():
+    """
+    训练主流程。
+
+    TODO [整合阶段 - 所有人协作]:
+    1. 解析命令行参数
+    2. 加载配置 (config_from_cli)
+    3. set_seed
+    4. setup_logging
+    5. 根据 model.type 选择训练模式:
+
+       A) model.type == "transformer_scratch":
+          a. 加载数据集 (load_wmt_dataset / load_opus_dataset)
+          b. 预处理 (preprocess_pipeline)
+          c. 训练分词器 (train_bpe_tokenizer) 或加载已有分词器
+          d. 构建 TranslationDataset + DataLoader
+          e. 构建 TransformerTranslationModel
+          f. 构建 Trainer 并开始训练
+
+       B) model.type == "finetune_nllb" / "finetune_mbart":
+          a. 加载预训练模型和分词器 (load_pretrained_model)
+          b. 配置 LoRA (setup_lora)
+          c. 加载数据集，使用预训练分词器处理
+          d. 构建 Trainer 并开始训练
+
+    6. 训练完成后保存最终模型
+    7. 在测试集上评估
+    """
+    args, cli_overrides = parse_args()
+
+    print("=" * 60)
+    print("  EasyTranslate - English to Chinese Translation")
+    print("=" * 60)
+
+    # TODO: 实现训练主流程
+    raise NotImplementedError(
+        "TODO: 整合阶段实现训练主流程\n"
+        "请在所有模块完成后，协作完成此脚本"
+    )
+
+
+if __name__ == "__main__":
+    main()

scripts/translate.py

@@ -0,0 +1,82 @@
+"""
+交互式翻译推理脚本
+
+使用方式:
+    # 命令行交互翻译
+    python scripts/translate.py --checkpoint checkpoints/best_model.pt
+
+    # 翻译文件
+    python scripts/translate.py --checkpoint checkpoints/best_model.pt --input input.txt --output output.txt
+
+    # 启动 Gradio Web UI
+    python scripts/translate.py --checkpoint checkpoints/best_model.pt --web
+"""
+
+import argparse
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent / "src"))
+
+
+def parse_args():
+    parser = argparse.ArgumentParser(description="EasyTranslate Inference")
+    parser.add_argument("--config", type=str, default="configs/default_config.yaml")
+    parser.add_argument("--checkpoint", type=str, required=True)
+    parser.add_argument("--input", type=str, default=None, help="输入文件路径")
+    parser.add_argument("--output", type=str, default=None, help="输出文件路径")
+    parser.add_argument("--web", action="store_true", help="启动 Gradio Web UI")
+    return parser.parse_args()
+
+
+def interactive_translate(evaluator):
+    """
+    命令行交互翻译。
+
+    TODO [Person D]:
+    1. 循环读取用户输入
+    2. 调用 evaluator.translate_single()
+    3. 打印翻译结果
+    4. 输入 'quit' 退出
+    """
+    raise NotImplementedError("TODO: Person D 实现 interactive_translate")
+
+
+def translate_file(evaluator, input_path: str, output_path: str):
+    """
+    文件翻译。
+
+    TODO [Person D]:
+    1. 读取输入文件 (一行一句)
+    2. 批量翻译
+    3. 将结果写入输出文件
+    """
+    raise NotImplementedError("TODO: Person D 实现 translate_file")
+
+
+def launch_web_ui(evaluator):
+    """
+    启动 Gradio Web UI。
+
+    TODO [Person D]:
+    1. 创建 Gradio Interface
+    2. 输入: 英文文本框
+    3. 输出: 中文翻译结果
+    4. 调用 evaluator.translate_single()
+    """
+    raise NotImplementedError("TODO: Person D 实现 launch_web_ui")
+
+
+def main():
+    args = parse_args()
+
+    print("=" * 60)
+    print("  EasyTranslate - Translation")
+    print("=" * 60)
+
+    # TODO: 加载模型、构建 evaluator，然后根据参数选择模式
+    raise NotImplementedError("TODO: 实现推理主流程")
+
+
+if __name__ == "__main__":
+    main()

scripts/visualize.py

@@ -0,0 +1,86 @@
+"""
+可视化与分析脚本 — Person E 负责
+
+功能:
+1. 训练曲线绘制 (loss, BLEU, learning rate)
+2. 实验结果对比图
+3. 注意力权重可视化
+4. 翻译样例展示
+"""
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent / "src"))
+
+
+def plot_training_curves(log_dir: str, output_path: str = "outputs/training_curves.png"):
+    """
+    绘制训练曲线。
+
+    TODO [Person E]:
+    1. 从 TensorBoard 日志或 CSV 读取训练数据
+    2. 绘制子图:
+       - Train Loss vs Steps
+       - Val Loss vs Steps
+       - BLEU vs Epochs
+       - Learning Rate vs Steps
+    3. 保存图片
+    """
+    raise NotImplementedError("TODO: Person E 实现 plot_training_curves")
+
+
+def plot_experiment_comparison(results_dir: str, output_path: str = "outputs/experiment_comparison.png"):
+    """
+    绘制实验对比图。
+
+    TODO [Person E]:
+    1. 读取所有实验的评估结果
+    2. 绘制柱状图: BLEU / COMET / chrF 对比
+    3. 绘制表格: 所有指标汇总
+    4. 保存图片
+    """
+    raise NotImplementedError("TODO: Person E 实现 plot_experiment_comparison")
+
+
+def visualize_attention(
+    model,
+    src_text: str,
+    tgt_text: str,
+    tokenizer,
+    output_path: str = "outputs/attention_map.png",
+):
+    """
+    注意力权重可视化。
+
+    TODO [Person E]:
+    1. 获取模型的 encoder self-attention 和 cross-attention 权重
+    2. 绘制热力图 (matplotlib / seaborn)
+    3. x 轴: 源语言 tokens, y 轴: 目标语言 tokens
+    4. 支持多头注意力的分别可视化和平均可视化
+    """
+    raise NotImplementedError("TODO: Person E 实现 visualize_attention")
+
+
+def generate_translation_examples(
+    evaluator,
+    test_pairs: list[tuple[str, str]],
+    output_path: str = "outputs/translation_examples.md",
+):
+    """
+    生成翻译样例展示。
+
+    TODO [Person E]:
+    1. 翻译测试样例
+    2. 生成 Markdown 格式的对比表格:
+       | 源文 (英) | 参考翻译 (中) | 模型翻译 (中) | BLEU |
+    3. 包含好的和差的翻译案例
+    4. 保存为 Markdown 文件
+    """
+    raise NotImplementedError("TODO: Person E 实现 generate_translation_examples")
+
+
+if __name__ == "__main__":
+    print("请指定要运行的可视化任务")
+    print("  python scripts/visualize.py --task training_curves --log_dir logs/")
+    print("  python scripts/visualize.py --task comparison --results_dir outputs/")

setup.py

@@ -0,0 +1,21 @@
+from setuptools import setup, find_packages
+
+setup(
+    name="easytranslate",
+    version="0.1.0",
+    description="Transformer-based English-to-Chinese Translation Model",
+    packages=find_packages(where="src"),
+    package_dir={"": "src"},
+    python_requires=">=3.10",
+    install_requires=[
+        "torch>=2.1.0",
+        "transformers>=4.36.0",
+        "datasets>=2.16.0",
+        "sentencepiece>=0.1.99",
+        "accelerate>=0.25.0",
+        "sacrebleu>=2.4.0",
+        "omegaconf>=2.3.0",
+        "rich>=13.0.0",
+        "tqdm>=4.66.0",
+    ],
+)

src/easytranslate/__init__.py

@@ -0,0 +1,3 @@
+"""EasyTranslate: Transformer-based English-to-Chinese Translation."""
+
+__version__ = "0.1.0"

src/easytranslate/evaluation/__init__.py

@@ -0,0 +1,16 @@
+"""评估与推理模块 (Person D 负责)"""
+
+from easytranslate.evaluation.metrics import compute_bleu, compute_comet, compute_chrf, compute_all_metrics
+from easytranslate.evaluation.decoding import greedy_decode, beam_search_decode, sample_decode
+from easytranslate.evaluation.evaluator import Evaluator
+
+__all__ = [
+    "compute_bleu",
+    "compute_comet",
+    "compute_chrf",
+    "compute_all_metrics",
+    "greedy_decode",
+    "beam_search_decode",
+    "sample_decode",
+    "Evaluator",
+]

src/easytranslate/evaluation/decoding.py

@@ -0,0 +1,129 @@
+"""
+解码策略模块 — Person D 负责实现
+
+功能要求:
+1. greedy_decode: 贪心解码
+2. beam_search_decode: 束搜索解码
+3. sample_decode: 采样解码 (temperature, top-k, top-p)
+
+技术要点:
+- Beam Search 是翻译任务最常用的解码策略
+- 需要高效处理批量解码
+- 支持长度惩罚 (length penalty) 和重复惩罚 (no_repeat_ngram)
+- 对于预训练模型，可以直接使用 model.generate()
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Optional
+
+import torch
+import torch.nn as nn
+import torch.nn.functional as F
+
+logger = logging.getLogger(__name__)
+
+
+@torch.no_grad()
+def greedy_decode(
+    model: nn.Module,
+    src_ids: torch.Tensor,          # [B, S]
+    src_padding_mask: torch.BoolTensor,  # [B, S]
+    bos_id: int,
+    eos_id: int,
+    max_len: int = 256,
+) -> torch.Tensor:
+    """
+    贪心解码。
+
+    TODO [Person D]: 实现以下逻辑:
+    1. encoder_output = model.encode(src_ids, src_padding_mask)
+    2. 初始化 decoder input: [B, 1] 全为 bos_id
+    3. for step in range(max_len):
+       a. logits = model.decode_step(decoder_input, encoder_output, src_padding_mask)
+       b. next_token = logits.argmax(dim=-1)
+       c. decoder_input = concat(decoder_input, next_token)
+       d. 如果所有序列都生成了 eos_id，则提前终止
+    4. 返回生成的 token ids [B, T]
+    """
+    raise NotImplementedError("TODO: Person D 实现 greedy_decode")
+
+
+@torch.no_grad()
+def beam_search_decode(
+    model: nn.Module,
+    src_ids: torch.Tensor,          # [B, S]
+    src_padding_mask: torch.BoolTensor,
+    bos_id: int,
+    eos_id: int,
+    beam_size: int = 5,
+    max_len: int = 256,
+    length_penalty: float = 1.0,
+    no_repeat_ngram_size: int = 0,
+) -> torch.Tensor:
+    """
+    束搜索解码。
+
+    TODO [Person D]: 实现以下逻辑:
+    1. encoder_output = model.encode(src_ids, src_padding_mask)
+    2. 将 encoder_output 扩展为 beam_size 份: [B*beam, S, D]
+    3. 初始化 beam:
+       - beam_scores: [B, beam_size] 初始为 0
+       - beam_tokens: [B, beam_size, 1] 初始为 bos_id
+    4. for step in range(max_len):
+       a. 对每个 beam 计算 logits
+       b. log_probs = log_softmax(logits)
+       c. (可选) 应用 no_repeat_ngram 约束
+       d. scores = beam_scores + log_probs
+       e. 选择 top-k candidates (k = beam_size)
+       f. 更新 beam_tokens 和 beam_scores
+       g. 将已完成的 beam 移到 finished pool
+    5. 对 finished beams 应用 length_penalty:
+       score = score / (length ^ length_penalty)
+    6. 选择得分最高的序列
+    7. 返回最佳翻译 [B, T]
+
+    这是翻译任务最关键的解码算法，请仔细实现。
+    """
+    raise NotImplementedError("TODO: Person D 实现 beam_search_decode")
+
+
+@torch.no_grad()
+def sample_decode(
+    model: nn.Module,
+    src_ids: torch.Tensor,
+    src_padding_mask: torch.BoolTensor,
+    bos_id: int,
+    eos_id: int,
+    max_len: int = 256,
+    temperature: float = 1.0,
+    top_k: int = 0,
+    top_p: float = 1.0,
+) -> torch.Tensor:
+    """
+    采样解码 (支持 temperature, top-k, top-p/nucleus sampling)。
+
+    TODO [Person D]: 实现以下逻辑:
+    1. 与贪心解码类似，但每步采样而非取 argmax
+    2. 应用 temperature: logits = logits / temperature
+    3. 应用 top-k: 只保留概率最高的 k 个 token
+    4. 应用 top-p (nucleus): 只保留累积概率达到 p 的 token
+    5. 从过滤后的分布中采样: torch.multinomial
+    """
+    raise NotImplementedError("TODO: Person D 实现 sample_decode")
+
+
+def _apply_no_repeat_ngram(
+    logits: torch.Tensor,
+    generated_tokens: torch.Tensor,
+    ngram_size: int,
+) -> torch.Tensor:
+    """
+    防止生成重复的 n-gram。
+
+    TODO [Person D]:
+    1. 从 generated_tokens 中提取所有已出现的 (ngram_size-1)-gram
+    2. 对于每个可能导致重复 ngram 的 next token，将其 logits 设为 -inf
+    """
+    raise NotImplementedError("TODO: Person D 实现 _apply_no_repeat_ngram")

src/easytranslate/evaluation/evaluator.py

@@ -0,0 +1,76 @@
+"""
+评估器模块 — Person D 负责实现
+
+功能要求:
+将解码和评估指标整合为统一的评估接口。
+
+使用方法:
+    evaluator = Evaluator(model, tokenizer, config)
+    results = evaluator.evaluate(test_loader)
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Optional
+
+import torch
+import torch.nn as nn
+from torch.utils.data import DataLoader
+from tqdm import tqdm
+
+from easytranslate.evaluation.metrics import compute_all_metrics
+from easytranslate.evaluation.decoding import greedy_decode, beam_search_decode, sample_decode
+
+logger = logging.getLogger(__name__)
+
+
+class Evaluator:
+    """
+    翻译模型评估器。
+
+    TODO [Person D]: 实现以下方法。
+    """
+
+    def __init__(self, model: nn.Module, tokenizer, config: dict):
+        """
+        TODO [Person D]:
+        1. 保存 model, tokenizer, config
+        2. 从 config 读取解码策略和评估指标配置
+        3. 根据策略选择解码函数
+        """
+        raise NotImplementedError("TODO: Person D 实现 Evaluator.__init__")
+
+    def evaluate(
+        self,
+        dataloader: DataLoader,
+        src_texts: Optional[list[str]] = None,
+        ref_texts: Optional[list[str]] = None,
+    ) -> dict:
+        """
+        在给定数据上进行评估。
+
+        TODO [Person D]: 实现以下逻辑:
+        1. model.eval()
+        2. 遍历 dataloader，使用选定的解码策略生成翻译
+        3. 将生成的 token ids 解码为文本
+        4. 调用 compute_all_metrics 计算指标
+        5. 返回评估结果 dict
+        """
+        raise NotImplementedError("TODO: Person D 实现 evaluate")
+
+    def translate(self, texts: list[str]) -> list[str]:
+        """
+        翻译一批文本。
+
+        TODO [Person D]:
+        1. tokenize 输入文本
+        2. 调用解码函数生成翻译
+        3. 解码为文本
+        4. 返回翻译结果列表
+        """
+        raise NotImplementedError("TODO: Person D 实现 translate")
+
+    def translate_single(self, text: str) -> str:
+        """翻译单条文本。"""
+        return self.translate([text])[0]

src/easytranslate/evaluation/metrics.py

@@ -0,0 +1,109 @@
+"""
+评估指标模块 — Person D 负责实现
+
+功能要求:
+1. compute_bleu: 计算 SacreBLEU 分数
+2. compute_comet: 计算 COMET 分数 (神经网络评估指标)
+3. compute_chrf: 计算 chrF++ 分数
+4. compute_ter: 计算 TER (Translation Edit Rate)
+5. compute_all_metrics: 计算所有指标
+
+技术要点:
+- SacreBLEU: 标准化的 BLEU 实现，结果可复现
+- COMET: 基于预训练语言模型的评估指标，与人类评价相关性最高
+- chrF++: 基于字符 n-gram 的 F-score，对中文尤其有用
+- TER: 编辑距离，衡量翻译后编辑量
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Optional
+
+logger = logging.getLogger(__name__)
+
+
+def compute_bleu(
+    hypotheses: list[str],
+    references: list[str],
+    tokenize: str = "zh",
+) -> dict:
+    """
+    计算 SacreBLEU 分数。
+
+    TODO [Person D]: 实现以下逻辑:
+    1. 使用 sacrebleu.corpus_bleu(hypotheses, [references], tokenize=tokenize)
+    2. tokenize="zh" 对中文进行字符级别分词
+    3. 返回 {"bleu": score, "bleu_1": ..., "bleu_2": ..., "bleu_3": ..., "bleu_4": ..., "bp": ...}
+
+    注意: references 需要包装为 list of list (支持多参考)
+    """
+    raise NotImplementedError("TODO: Person D 实现 compute_bleu")
+
+
+def compute_comet(
+    sources: list[str],
+    hypotheses: list[str],
+    references: list[str],
+    model_name: str = "Unbabel/wmt22-comet-da",
+    batch_size: int = 16,
+    gpus: int = 1,
+) -> dict:
+    """
+    计算 COMET 分数。
+
+    TODO [Person D]: 实现以下逻辑:
+    1. 加载 COMET 模型: comet.download_model(model_name)
+    2. 构建输入数据: [{"src": s, "mt": h, "ref": r} for s, h, r in zip(...)]
+    3. 调用 model.predict(data, batch_size, gpus)
+    4. 返回 {"comet": system_score, "comet_scores": segment_scores}
+
+    COMET 需要源语言、翻译结果和参考翻译三者。
+    """
+    raise NotImplementedError("TODO: Person D 实现 compute_comet")
+
+
+def compute_chrf(
+    hypotheses: list[str],
+    references: list[str],
+) -> dict:
+    """
+    计算 chrF++ 分数。
+
+    TODO [Person D]:
+    1. 使用 sacrebleu.corpus_chrf(hypotheses, [references])
+    2. 返回 {"chrf": score}
+    """
+    raise NotImplementedError("TODO: Person D 实现 compute_chrf")
+
+
+def compute_ter(
+    hypotheses: list[str],
+    references: list[str],
+) -> dict:
+    """
+    计算 TER 分数。
+
+    TODO [Person D]:
+    1. 使用 sacrebleu.corpus_ter(hypotheses, [references])
+    2. 返回 {"ter": score}
+    """
+    raise NotImplementedError("TODO: Person D 实现 compute_ter")
+
+
+def compute_all_metrics(
+    sources: list[str],
+    hypotheses: list[str],
+    references: list[str],
+    metrics: list[str] = ["bleu", "comet", "chrf", "ter"],
+) -> dict:
+    """
+    计算所有指定的评估指标。
+
+    TODO [Person D]:
+    1. 遍历 metrics 列表
+    2. 调用对应的计算函数
+    3. 合并结果并返回
+    4. 记录每个指标的计算时间
+    """
+    raise NotImplementedError("TODO: Person D 实现 compute_all_metrics")

src/easytranslate/model/__init__.py

@@ -0,0 +1,20 @@
+"""模型架构模块 (Person B 负责)"""
+
+from easytranslate.model.transformer import TransformerTranslationModel
+from easytranslate.model.encoder import TransformerEncoder
+from easytranslate.model.decoder import TransformerDecoder
+from easytranslate.model.attention import MultiHeadAttention, FlashMultiHeadAttention
+from easytranslate.model.positional import SinusoidalPositionalEncoding, RotaryPositionalEmbedding
+from easytranslate.model.finetune import load_pretrained_model, setup_lora
+
+__all__ = [
+    "TransformerTranslationModel",
+    "TransformerEncoder",
+    "TransformerDecoder",
+    "MultiHeadAttention",
+    "FlashMultiHeadAttention",
+    "SinusoidalPositionalEncoding",
+    "RotaryPositionalEmbedding",
+    "load_pretrained_model",
+    "setup_lora",
+]

src/easytranslate/model/attention.py

@@ -0,0 +1,106 @@
+"""
+注意力机制模块 — Person B 负责实现
+
+包含:
+1. MultiHeadAttention: 标准多头注意力 (支持 RoPE)
+2. FlashMultiHeadAttention: Flash Attention 2 加速版本
+
+技术要点:
+- Scaled Dot-Product Attention
+- 支持 key_padding_mask 和 attn_mask
+- Flash Attention 2 使用 torch.nn.functional.scaled_dot_product_attention
+- RoPE 旋转位置编码集成
+"""
+
+from __future__ import annotations
+
+import math
+from typing import Optional
+
+import torch
+import torch.nn as nn
+import torch.nn.functional as F
+
+
+class MultiHeadAttention(nn.Module):
+    """
+    标准多头注意力机制。
+
+    TODO [Person B]: 实现以下内容:
+
+    __init__:
+    1. Q, K, V 线性投影: nn.Linear(d_model, d_model)
+    2. 输出投影: nn.Linear(d_model, d_model)
+    3. Dropout
+
+    forward(query, key, value, key_padding_mask=None, attn_mask=None):
+    1. 线性投影 Q, K, V
+    2. reshape 为 [B, nhead, L, d_k]
+    3. (可选) 应用 RoPE 旋转位置编码
+    4. 计算 attention scores: QK^T / sqrt(d_k)
+    5. 应用 masks (padding mask + causal mask)
+    6. Softmax + Dropout
+    7. 加权求和 V
+    8. reshape 回 [B, L, d_model]
+    9. 输出投影
+    """
+
+    def __init__(
+        self,
+        d_model: int = 512,
+        nhead: int = 8,
+        dropout: float = 0.1,
+        use_rotary_embedding: bool = False,
+    ):
+        super().__init__()
+        assert d_model % nhead == 0, "d_model 必须能被 nhead 整除"
+        self.d_model = d_model
+        self.nhead = nhead
+        self.d_k = d_model // nhead
+
+        raise NotImplementedError("TODO: Person B 实现 MultiHeadAttention.__init__")
+
+    def forward(
+        self,
+        query: torch.Tensor,   # [B, L_q, D]
+        key: torch.Tensor,     # [B, L_k, D]
+        value: torch.Tensor,   # [B, L_v, D]
+        key_padding_mask: Optional[torch.BoolTensor] = None,  # [B, L_k]
+        attn_mask: Optional[torch.Tensor] = None,             # [L_q, L_k]
+    ) -> torch.Tensor:
+        raise NotImplementedError("TODO: Person B 实现 MultiHeadAttention.forward")
+
+
+class FlashMultiHeadAttention(nn.Module):
+    """
+    Flash Attention 2 加速的多头注意力。
+
+    TODO [Person B]: 使用 PyTorch 2.0+ 的 F.scaled_dot_product_attention 实现:
+    1. 与 MultiHeadAttention 结构相同
+    2. 在 forward 中使用 F.scaled_dot_product_attention(Q, K, V, attn_mask, dropout, is_causal)
+    3. 会自动选择最优的 attention kernel (Flash Attention / Memory-Efficient Attention)
+
+    注意:
+    - 需要 PyTorch >= 2.0
+    - is_causal=True 时自动生成因果掩码，不需要手动传入 attn_mask
+    """
+
+    def __init__(
+        self,
+        d_model: int = 512,
+        nhead: int = 8,
+        dropout: float = 0.1,
+        use_rotary_embedding: bool = False,
+    ):
+        super().__init__()
+        raise NotImplementedError("TODO: Person B 实现 FlashMultiHeadAttention.__init__")
+
+    def forward(
+        self,
+        query: torch.Tensor,
+        key: torch.Tensor,
+        value: torch.Tensor,
+        key_padding_mask: Optional[torch.BoolTensor] = None,
+        is_causal: bool = False,
+    ) -> torch.Tensor:
+        raise NotImplementedError("TODO: Person B 实现 FlashMultiHeadAttention.forward")

src/easytranslate/model/decoder.py

@@ -0,0 +1,86 @@
+"""
+Transformer Decoder 模块 — Person B 负责实现
+
+包含:
+- TransformerDecoderLayer: 单层解码器
+- TransformerDecoder: 多层解码器堆叠
+
+架构 (Pre-LayerNorm):
+    x → LN → Masked Self-Attention → Residual
+      → LN → Cross-Attention → Residual
+      → LN → FFN → Residual
+"""
+
+from __future__ import annotations
+
+import torch
+import torch.nn as nn
+from typing import Optional
+
+
+class TransformerDecoderLayer(nn.Module):
+    """
+    单层 Transformer Decoder。
+
+    TODO [Person B]: 实现以下组件:
+    1. Masked Self-Attention (因果掩码，防止看到未来)
+    2. Cross-Attention (decoder 查询 encoder 输出)
+    3. Feed-Forward Network
+    4. 三个 LayerNorm
+    5. Residual connections + Dropout
+    """
+
+    def __init__(
+        self,
+        d_model: int = 512,
+        nhead: int = 8,
+        dim_feedforward: int = 2048,
+        dropout: float = 0.1,
+        activation: str = "gelu",
+        use_flash_attention: bool = True,
+        use_rotary_embedding: bool = True,
+        pre_norm: bool = True,
+    ):
+        super().__init__()
+        raise NotImplementedError("TODO: Person B 实现 TransformerDecoderLayer.__init__")
+
+    def forward(
+        self,
+        tgt: torch.Tensor,                               # [B, T, D]
+        memory: torch.Tensor,                             # [B, S, D] (encoder output)
+        tgt_mask: Optional[torch.Tensor] = None,          # [T, T] causal mask
+        memory_key_padding_mask: Optional[torch.BoolTensor] = None,  # [B, S]
+        tgt_key_padding_mask: Optional[torch.BoolTensor] = None,     # [B, T]
+    ) -> torch.Tensor:
+        """
+        TODO [Person B]: Pre-LayerNorm 前向传播:
+        1. Masked Self-Attention with causal mask
+        2. Cross-Attention with encoder output
+        3. FFN
+        每步都有 residual connection 和 dropout
+        """
+        raise NotImplementedError("TODO: Person B 实现 TransformerDecoderLayer.forward")
+
+
+class TransformerDecoder(nn.Module):
+    """
+    多层 Transformer Decoder。
+
+    TODO [Person B]:
+    1. 堆叠 N 个 TransformerDecoderLayer
+    2. 最终加一个 LayerNorm
+    """
+
+    def __init__(self, decoder_layer: TransformerDecoderLayer, num_layers: int):
+        super().__init__()
+        raise NotImplementedError("TODO: Person B 实现 TransformerDecoder.__init__")
+
+    def forward(
+        self,
+        tgt: torch.Tensor,
+        memory: torch.Tensor,
+        tgt_mask: Optional[torch.Tensor] = None,
+        memory_key_padding_mask: Optional[torch.BoolTensor] = None,
+        tgt_key_padding_mask: Optional[torch.BoolTensor] = None,
+    ) -> torch.Tensor:
+        raise NotImplementedError("TODO: Person B 实现 TransformerDecoder.forward")

src/easytranslate/model/encoder.py

@@ -0,0 +1,84 @@
+"""
+Transformer Encoder 模块 — Person B 负责实现
+
+包含:
+- TransformerEncoderLayer: 单层编码器
+- TransformerEncoder: 多层编码器堆叠
+
+架构 (Pre-LayerNorm):
+    x → LayerNorm → MultiHeadAttention → Residual → LayerNorm → FFN → Residual
+"""
+
+from __future__ import annotations
+
+import torch
+import torch.nn as nn
+from typing import Optional
+
+
+class TransformerEncoderLayer(nn.Module):
+    """
+    单层 Transformer Encoder。
+
+    TODO [Person B]: 实现以下组件:
+    1. Self-Attention: MultiHeadAttention (支持 Flash Attention)
+    2. Feed-Forward Network: Linear → Activation → Dropout → Linear
+    3. 两个 LayerNorm
+    4. Residual connections
+    5. Dropout
+
+    注意: 使用 Pre-LayerNorm 架构 (先 norm 再 attention/ffn)
+    """
+
+    def __init__(
+        self,
+        d_model: int = 512,
+        nhead: int = 8,
+        dim_feedforward: int = 2048,
+        dropout: float = 0.1,
+        activation: str = "gelu",
+        use_flash_attention: bool = True,
+        use_rotary_embedding: bool = True,
+        pre_norm: bool = True,
+    ):
+        super().__init__()
+        raise NotImplementedError("TODO: Person B 实现 TransformerEncoderLayer.__init__")
+
+    def forward(
+        self,
+        src: torch.Tensor,                             # [B, S, D]
+        src_key_padding_mask: Optional[torch.BoolTensor] = None,  # [B, S]
+    ) -> torch.Tensor:
+        """
+        TODO [Person B]: Pre-LayerNorm 前向传播:
+        1. residual = src
+        2. src = layer_norm_1(src)
+        3. src = self_attention(src, src, src, key_padding_mask=src_key_padding_mask)
+        4. src = residual + dropout(src)
+        5. residual = src
+        6. src = layer_norm_2(src)
+        7. src = ffn(src)
+        8. src = residual + dropout(src)
+        """
+        raise NotImplementedError("TODO: Person B 实现 TransformerEncoderLayer.forward")
+
+
+class TransformerEncoder(nn.Module):
+    """
+    多层 Transformer Encoder。
+
+    TODO [Person B]:
+    1. 堆叠 N 个 TransformerEncoderLayer
+    2. 最终加一个 LayerNorm (Pre-Norm 架构需要)
+    """
+
+    def __init__(self, encoder_layer: TransformerEncoderLayer, num_layers: int):
+        super().__init__()
+        raise NotImplementedError("TODO: Person B 实现 TransformerEncoder.__init__")
+
+    def forward(
+        self,
+        src: torch.Tensor,
+        src_key_padding_mask: Optional[torch.BoolTensor] = None,
+    ) -> torch.Tensor:
+        raise NotImplementedError("TODO: Person B 实现 TransformerEncoder.forward")

src/easytranslate/model/finetune.py

@@ -0,0 +1,95 @@
+"""
+预训练模型微调模块 — Person B 负责实现
+
+功能要求:
+1. load_pretrained_model: 加载 NLLB / mBART 等预训练翻译模型
+2. setup_lora: 配置 LoRA 参数高效微调
+
+技术要点:
+- 使用 HuggingFace transformers 加载预训练模型
+- 使用 PEFT (Parameter-Efficient Fine-Tuning) 库配置 LoRA
+- 支持 NLLB-200 (Meta, 200种语言) 和 mBART-50 (Meta, 50种语言)
+- 冻结预训练参数，只训练 LoRA adapter
+
+这是实验对比的关键部分:
+- 从头训练 vs 预训练微调
+- Full fine-tuning vs LoRA
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Optional
+
+import torch
+import torch.nn as nn
+
+logger = logging.getLogger(__name__)
+
+
+def load_pretrained_model(
+    model_name: str = "facebook/nllb-200-distilled-600M",
+    src_lang: str = "eng_Latn",
+    tgt_lang: str = "zho_Hans",
+    device: str = "cuda",
+) -> tuple:
+    """
+    加载预训练翻译模型和分词器。
+
+    TODO [Person B]: 实现以下逻辑:
+    1. 使用 AutoModelForSeq2SeqLM.from_pretrained(model_name) 加载模型
+    2. 使用 AutoTokenizer.from_pretrained(model_name) 加载分词器
+    3. 设置源语言和目标语言
+    4. 将模型移到指定设备
+
+    支持的模型:
+    - facebook/nllb-200-distilled-600M (推荐，轻量级)
+    - facebook/nllb-200-1.3B (中等规模)
+    - facebook/mbart-large-50-many-to-many-mmt
+
+    Returns:
+        (model, tokenizer)
+    """
+    raise NotImplementedError("TODO: Person B 实现 load_pretrained_model")
+
+
+def setup_lora(
+    model: nn.Module,
+    r: int = 16,
+    alpha: int = 32,
+    dropout: float = 0.05,
+    target_modules: Optional[list[str]] = None,
+) -> nn.Module:
+    """
+    为模型配置 LoRA 微调。
+
+    TODO [Person B]: 实现以下逻辑:
+    1. 定义 LoraConfig:
+       - r: LoRA 秩 (低秩分解维度)
+       - lora_alpha: 缩放因子
+       - lora_dropout: LoRA dropout
+       - target_modules: 需要加 LoRA 的模块 (如 q_proj, v_proj)
+       - task_type: SEQ_2_SEQ_LM
+    2. 使用 get_peft_model(model, config) 包装模型
+    3. 打印可训练参数数量和比例
+    4. 返回 LoRA 模型
+
+    参考: https://huggingface.co/docs/peft
+
+    Returns:
+        peft_model: LoRA 包装后的模型
+    """
+    if target_modules is None:
+        target_modules = ["q_proj", "v_proj"]
+
+    raise NotImplementedError("TODO: Person B 实现 setup_lora")
+
+
+def freeze_model_except_lora(model: nn.Module):
+    """
+    冻结模型所有参数，只保留 LoRA 参数可训练。
+
+    TODO [Person B]: 遍历 model.named_parameters()，
+    如果参数名中不包含 "lora"，则设置 requires_grad = False。
+    """
+    raise NotImplementedError("TODO: Person B 实现 freeze_model_except_lora")

src/easytranslate/model/positional.py

@@ -0,0 +1,97 @@
+"""
+位置编码模块 — Person B 负责实现
+
+包含:
+1. SinusoidalPositionalEncoding: 经典正弦余弦位置编码
+2. RotaryPositionalEmbedding (RoPE): 旋转位置编码
+
+RoPE 是当前最前沿的位置编码方案，被 LLaMA, GPT-NeoX 等大模型广泛采用。
+优势: 更好地捕获相对位置信息，支持长度外推。
+"""
+
+from __future__ import annotations
+
+import math
+
+import torch
+import torch.nn as nn
+
+
+class SinusoidalPositionalEncoding(nn.Module):
+    """
+    经典正弦余弦位置编码 (Vaswani et al., 2017)。
+
+    PE(pos, 2i)   = sin(pos / 10000^(2i/d_model))
+    PE(pos, 2i+1) = cos(pos / 10000^(2i/d_model))
+
+    TODO [Person B]: 实现以下内容:
+    1. 在 __init__ 中预计算位置编码矩阵 [max_seq_len, d_model]
+    2. 注册为 buffer (不参与梯度更新)
+    3. forward(x): 返回 x + pe[:, :x.size(1), :]
+    """
+
+    def __init__(self, d_model: int, max_seq_len: int = 5000, dropout: float = 0.1):
+        super().__init__()
+        raise NotImplementedError("TODO: Person B 实现 SinusoidalPositionalEncoding.__init__")
+
+    def forward(self, x: torch.Tensor) -> torch.Tensor:
+        """
+        Args:
+            x: [B, L, D]
+        Returns:
+            x + positional_encoding: [B, L, D]
+        """
+        raise NotImplementedError("TODO: Person B 实现 SinusoidalPositionalEncoding.forward")
+
+
+class RotaryPositionalEmbedding(nn.Module):
+    """
+    旋转位置编码 (RoPE) — Su et al., 2021
+
+    核心思想: 通过旋转变换将位置信息编码到 Q, K 向量中。
+    q' = q * cos(θ) + rotate_half(q) * sin(θ)
+    k' = k * cos(θ) + rotate_half(k) * sin(θ)
+
+    TODO [Person B]: 实现以下内容:
+
+    __init__:
+    1. 计算频率: inv_freq = 1.0 / (base ** (torch.arange(0, dim, 2) / dim))
+    2. 注册为 buffer
+
+    _compute_rope(seq_len):
+    1. 计算 position indices: t = [0, 1, ..., seq_len-1]
+    2. 计算 freqs = torch.outer(t, inv_freq)
+    3. 构建 cos_cached, sin_cached
+
+    apply_rotary_pos_emb(q, k):
+    1. 对 q 和 k 应用旋转变换
+    2. 返回旋转后的 q', k'
+
+    参考: https://arxiv.org/abs/2104.09864
+    """
+
+    def __init__(self, dim: int, max_seq_len: int = 2048, base: float = 10000.0):
+        super().__init__()
+        raise NotImplementedError("TODO: Person B 实现 RotaryPositionalEmbedding.__init__")
+
+    def _compute_rope(self, seq_len: int, device: torch.device):
+        raise NotImplementedError("TODO: Person B 实现 _compute_rope")
+
+    @staticmethod
+    def _rotate_half(x: torch.Tensor) -> torch.Tensor:
+        """将 x 的后半部分取反并与前半部分交换。"""
+        x1, x2 = x.chunk(2, dim=-1)
+        return torch.cat((-x2, x1), dim=-1)
+
+    def apply_rotary_pos_emb(
+        self,
+        q: torch.Tensor,  # [B, nhead, L, d_k]
+        k: torch.Tensor,  # [B, nhead, L, d_k]
+    ) -> tuple[torch.Tensor, torch.Tensor]:
+        """
+        对 Q, K 应用 RoPE。
+
+        Returns:
+            (q_rotated, k_rotated)
+        """
+        raise NotImplementedError("TODO: Person B 实现 apply_rotary_pos_emb")

src/easytranslate/model/transformer.py

@@ -0,0 +1,157 @@
+"""
+Transformer 翻译模型主体 — Person B 负责实现
+
+这是整个模型的核心文件，定义 Encoder-Decoder 架构。
+
+架构设计:
+- Pre-LayerNorm Transformer (训练更稳定)
+- 可选 Flash Attention 2 (加速注意力计算)
+- 可选 RoPE 旋转位置编码 (替代传统正弦位置编码)
+- 共享 Embedding 权重 (可选)
+"""
+
+from __future__ import annotations
+
+import logging
+import math
+from typing import Optional
+
+import torch
+import torch.nn as nn
+import torch.nn.functional as F
+
+from easytranslate.model.encoder import TransformerEncoder
+from easytranslate.model.decoder import TransformerDecoder
+from easytranslate.model.positional import SinusoidalPositionalEncoding, RotaryPositionalEmbedding
+
+logger = logging.getLogger(__name__)
+
+
+class TransformerTranslationModel(nn.Module):
+    """
+    完整的 Transformer 英中翻译模型。
+
+    架构:
+        Source Embedding + Positional Encoding
+        → Transformer Encoder (N layers)
+        → Transformer Decoder (N layers)
+        → Linear Projection → Softmax
+
+    TODO [Person B]: 实现以下内容:
+
+    __init__:
+    1. 源语言 Embedding: nn.Embedding(src_vocab_size, d_model)
+    2. 目标语言 Embedding: nn.Embedding(tgt_vocab_size, d_model)
+    3. 位置编码: SinusoidalPositionalEncoding 或 RotaryPositionalEmbedding
+    4. Transformer Encoder
+    5. Transformer Decoder
+    6. 输出投影层: nn.Linear(d_model, tgt_vocab_size)
+    7. (可选) 共享 target embedding 和 output projection 的权重
+    8. 调用 _init_weights() 初始化参数
+
+    forward:
+    1. 源语言 embedding + 位置编码 → encoder_input
+    2. 目标语言 embedding + 位置编码 → decoder_input
+    3. 生成 masks (src_key_padding_mask, tgt_key_padding_mask, tgt_mask)
+    4. encoder_output = encoder(encoder_input, src_key_padding_mask)
+    5. decoder_output = decoder(decoder_input, encoder_output, masks...)
+    6. logits = output_projection(decoder_output)
+    7. 返回 logits [B, T, tgt_vocab_size]
+    """
+
+    def __init__(
+        self,
+        src_vocab_size: int,
+        tgt_vocab_size: int,
+        d_model: int = 512,
+        nhead: int = 8,
+        num_encoder_layers: int = 6,
+        num_decoder_layers: int = 6,
+        dim_feedforward: int = 2048,
+        dropout: float = 0.1,
+        activation: str = "gelu",
+        max_seq_len: int = 512,
+        use_flash_attention: bool = True,
+        use_rotary_embedding: bool = True,
+        pre_norm: bool = True,
+        pad_id: int = 0,
+        share_embedding: bool = False,
+    ):
+        super().__init__()
+        # TODO [Person B]: 实现模型初始化
+        # 保存超参数
+        self.d_model = d_model
+        self.pad_id = pad_id
+
+        raise NotImplementedError("TODO: Person B 实现 TransformerTranslationModel.__init__")
+
+    def _init_weights(self):
+        """
+        参数初始化。
+
+        TODO [Person B]: 实现 Xavier/Kaiming 初始化:
+        - Embedding: normal_(0, d_model^-0.5)
+        - Linear: xavier_uniform_
+        - LayerNorm: ones_ / zeros_
+        """
+        raise NotImplementedError("TODO: Person B 实现 _init_weights")
+
+    def _generate_square_subsequent_mask(self, sz: int, device: torch.device) -> torch.Tensor:
+        """
+        生成因果注意力掩码 (causal mask)。
+
+        TODO [Person B]:
+        返回上三角矩阵 mask，shape [sz, sz]，
+        mask[i][j] = -inf if j > i else 0
+        """
+        raise NotImplementedError("TODO: Person B 实现 _generate_square_subsequent_mask")
+
+    def forward(
+        self,
+        src_ids: torch.Tensor,           # [B, S]
+        tgt_input_ids: torch.Tensor,     # [B, T]
+        src_padding_mask: Optional[torch.BoolTensor] = None,  # [B, S]
+        tgt_padding_mask: Optional[torch.BoolTensor] = None,  # [B, T]
+    ) -> torch.Tensor:
+        """
+        前向传播。
+
+        Returns:
+            logits: [B, T, tgt_vocab_size]
+        """
+        raise NotImplementedError("TODO: Person B 实现 forward")
+
+    @torch.no_grad()
+    def encode(self, src_ids: torch.Tensor, src_padding_mask: Optional[torch.BoolTensor] = None) -> torch.Tensor:
+        """
+        仅编码（用于推理时复用 encoder 输出）。
+
+        TODO [Person B]:
+        1. src embedding + positional encoding
+        2. encoder forward
+        3. 返回 encoder_output
+        """
+        raise NotImplementedError("TODO: Person B 实现 encode")
+
+    @torch.no_grad()
+    def decode_step(
+        self,
+        tgt_input_ids: torch.Tensor,
+        encoder_output: torch.Tensor,
+        src_padding_mask: Optional[torch.BoolTensor] = None,
+    ) -> torch.Tensor:
+        """
+        解码一步（用于自回归推理）。
+
+        TODO [Person B]:
+        1. tgt embedding + positional encoding
+        2. 生成 causal mask
+        3. decoder forward
+        4. 取最后一个 token 的 logits
+        5. 返回 logits [B, vocab_size]
+        """
+        raise NotImplementedError("TODO: Person B 实现 decode_step")
+
+    def count_parameters(self) -> int:
+        """返回可训练参数数量。"""
+        return sum(p.numel() for p in self.parameters() if p.requires_grad)

src/easytranslate/training/__init__.py

@@ -0,0 +1,12 @@
+"""训练模块 (Person C 负责)"""
+
+from easytranslate.training.trainer import Trainer
+from easytranslate.training.optimizer import build_optimizer, build_scheduler
+from easytranslate.training.loss import LabelSmoothedCrossEntropyLoss
+
+__all__ = [
+    "Trainer",
+    "build_optimizer",
+    "build_scheduler",
+    "LabelSmoothedCrossEntropyLoss",
+]

src/easytranslate/training/loss.py

@@ -0,0 +1,57 @@
+"""
+损失函数模块 — Person C 负责实现
+
+功能要求:
+1. LabelSmoothedCrossEntropyLoss: 带标签平滑的交叉熵损失
+
+技术要点:
+- 标签平滑 (Label Smoothing) 是 Transformer 训练的标准技巧
+- smoothing=0.1 意味着将 10% 的概率均匀分配给非目标类
+- 需要忽略 padding token 的损失
+"""
+
+from __future__ import annotations
+
+import torch
+import torch.nn as nn
+import torch.nn.functional as F
+
+
+class LabelSmoothedCrossEntropyLoss(nn.Module):
+    """
+    带标签平滑的交叉熵损失。
+
+    TODO [Person C]: 实现以下逻辑:
+
+    __init__:
+    1. 保存 smoothing 系数和 pad_id
+
+    forward(logits, targets):
+    1. logits: [B, T, V] — 模型输出
+    2. targets: [B, T] — 目标 token ids
+    3. 展平为 [B*T, V] 和 [B*T]
+    4. 创建 smooth label distribution:
+       - target token 概率 = 1 - smoothing
+       - 其他 token 概率 = smoothing / (V - 1)
+    5. 计算 KL 散度作为损失
+    6. 忽略 pad_id 位置的损失
+    7. 返回平均损失
+
+    参考: "Rethinking the Inception Architecture for Computer Vision" (Szegedy et al.)
+    """
+
+    def __init__(self, smoothing: float = 0.1, pad_id: int = 0):
+        super().__init__()
+        self.smoothing = smoothing
+        self.pad_id = pad_id
+        raise NotImplementedError("TODO: Person C 实现 LabelSmoothedCrossEntropyLoss.__init__")
+
+    def forward(self, logits: torch.Tensor, targets: torch.Tensor) -> torch.Tensor:
+        """
+        Args:
+            logits: [B, T, V]
+            targets: [B, T]
+        Returns:
+            loss: scalar
+        """
+        raise NotImplementedError("TODO: Person C 实现 LabelSmoothedCrossEntropyLoss.forward")

src/easytranslate/training/optimizer.py

@@ -0,0 +1,76 @@
+"""
+优化器与学习率调度器 — Person C 负责实现
+
+功能要求:
+1. build_optimizer: 根据配置创建优化器
+2. build_scheduler: 根据配置创建学习率调度器
+3. InverseSqrtScheduler: 自定义 inverse square root 调度器
+
+技术要点:
+- AdamW 是 Transformer 训练的标准优化器
+- Cosine with warmup 是目前最流行的调度策略
+- Inverse sqrt 是经典 Transformer 论文使用的调度策略
+"""
+
+from __future__ import annotations
+
+import math
+from typing import Optional
+
+import torch
+from torch.optim import Adam, AdamW
+from torch.optim.lr_scheduler import LambdaLR
+
+
+def build_optimizer(model, config: dict) -> torch.optim.Optimizer:
+    """
+    根据配置创建优化器。
+
+    TODO [Person C]: 实现以下逻辑:
+    1. 从 config 中读取 optimizer type, lr, weight_decay, betas, eps
+    2. 根据 type 创建 Adam / AdamW / Adafactor
+    3. (可选) 对不同参数组设置不同学习率:
+       - embedding 层可以用较小的 lr
+       - LayerNorm 的 bias 不加 weight_decay
+    """
+    raise NotImplementedError("TODO: Person C 实现 build_optimizer")
+
+
+def build_scheduler(
+    optimizer: torch.optim.Optimizer,
+    config: dict,
+    num_training_steps: Optional[int] = None,
+) -> torch.optim.lr_scheduler._LRScheduler:
+    """
+    根据配置创建学习率调度器。
+
+    TODO [Person C]: 实现以下逻辑:
+    1. 从 config 中读取 scheduler type, warmup_steps, min_lr
+    2. type == "cosine_with_warmup":
+       使用 get_cosine_schedule_with_warmup (transformers 库)
+    3. type == "inverse_sqrt":
+       实现经典的 lr = d_model^(-0.5) * min(step^(-0.5), step * warmup^(-1.5))
+    4. type == "linear":
+       使用 get_linear_schedule_with_warmup
+
+    参考: Attention Is All You Need, Section 5.3
+    """
+    raise NotImplementedError("TODO: Person C 实现 build_scheduler")
+
+
+class InverseSqrtScheduler(LambdaLR):
+    """
+    Inverse Square Root 学习率调度器。
+
+    lr = base_lr * min(step^{-0.5}, step * warmup_steps^{-1.5})
+
+    这是原始 Transformer 论文使用的调度策略。
+
+    TODO [Person C]:
+    1. 实现 lr_lambda 函数
+    2. warmup 阶段线性增长
+    3. warmup 后按 step^{-0.5} 衰减
+    """
+
+    def __init__(self, optimizer, warmup_steps: int = 4000):
+        raise NotImplementedError("TODO: Person C 实现 InverseSqrtScheduler.__init__")

src/easytranslate/training/trainer.py

@@ -0,0 +1,186 @@
+"""
+训练器模块 — Person C 负责实现
+
+这是训练的核心控制器，负责:
+1. 训练循环 (training loop)
+2. 验证循环 (validation loop)
+3. 检查点保存/加载
+4. 日志记录
+5. 分布式训练支持
+6. 混合精度训练
+7. 梯度累积
+8. 早停
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import time
+from pathlib import Path
+from typing import Optional
+
+import torch
+import torch.nn as nn
+from torch.utils.data import DataLoader
+from tqdm import tqdm
+
+logger = logging.getLogger(__name__)
+
+
+class Trainer:
+    """
+    翻译模型训练器。
+
+    TODO [Person C]: 实现以下所有方法。
+
+    使用方法:
+        trainer = Trainer(model, train_loader, val_loader, config)
+        trainer.train()
+    """
+
+    def __init__(
+        self,
+        model: nn.Module,
+        train_loader: DataLoader,
+        val_loader: DataLoader,
+        config: dict,
+        optimizer=None,
+        scheduler=None,
+        criterion=None,
+        evaluator=None,
+    ):
+        """
+        TODO [Person C]: 初始化训练器:
+        1. 保存模型、数据加载器、配置
+        2. 如果 optimizer 为 None，调用 build_optimizer 创建
+        3. 如果 scheduler 为 None，调用 build_scheduler 创建
+        4. 如果 criterion 为 None，创建 LabelSmoothedCrossEntropyLoss
+        5. 设置混合精度: torch.amp.GradScaler (如果配置了 fp16/bf16)
+        6. 设置分布式训练: 根据配置初始化 DDP/FSDP/DeepSpeed
+        7. 初始化日志记录器 (TensorBoard / WandB)
+        8. 初始化训练状态 (epoch, step, best_metric)
+        """
+        self.model = model
+        self.train_loader = train_loader
+        self.val_loader = val_loader
+        self.config = config
+        raise NotImplementedError("TODO: Person C 实现 Trainer.__init__")
+
+    def train(self):
+        """
+        主训练循环。
+
+        TODO [Person C]: 实现以下逻辑:
+        1. for epoch in range(start_epoch, num_epochs):
+        2.   train_loss = self._train_one_epoch(epoch)
+        3.   val_metrics = self._validate(epoch)
+        4.   self._log_metrics(epoch, train_loss, val_metrics)
+        5.   self._save_checkpoint(epoch, val_metrics)
+        6.   if self._should_early_stop(val_metrics): break
+        7. self._log_final_results()
+        """
+        raise NotImplementedError("TODO: Person C 实现 train")
+
+    def _train_one_epoch(self, epoch: int) -> float:
+        """
+        训练一个 epoch。
+
+        TODO [Person C]: 实现以下逻辑:
+        1. model.train()
+        2. 遍历 train_loader:
+           a. 将 batch 移到设备
+           b. 混合精度上下文: with torch.amp.autocast('cuda'):
+           c. logits = model(src_ids, tgt_input_ids, masks...)
+           d. loss = criterion(logits, labels)
+           e. loss = loss / gradient_accumulation_steps
+           f. scaler.scale(loss).backward()
+           g. 每 gradient_accumulation_steps 步:
+              - scaler.unscale_(optimizer)
+              - torch.nn.utils.clip_grad_norm_(model.parameters(), max_norm=1.0)
+              - scaler.step(optimizer)
+              - scaler.update()
+              - scheduler.step()
+              - optimizer.zero_grad()
+           h. 记录 loss, lr 等指标
+        3. 返回平均训练 loss
+        """
+        raise NotImplementedError("TODO: Person C 实现 _train_one_epoch")
+
+    def _validate(self, epoch: int) -> dict:
+        """
+        验证。
+
+        TODO [Person C]: 实现以下逻辑:
+        1. model.eval()
+        2. with torch.no_grad():
+        3.   遍历 val_loader，计算 loss
+        4.   每 N 步调用 evaluator 计算 BLEU 等指标
+        5. 返回 {"val_loss": ..., "bleu": ..., "comet": ...}
+        """
+        raise NotImplementedError("TODO: Person C 实现 _validate")
+
+    def _save_checkpoint(self, epoch: int, metrics: dict):
+        """
+        保存检查点。
+
+        TODO [Person C]: 实现以下逻辑:
+        1. 构建 checkpoint dict:
+           {
+               "epoch": epoch,
+               "step": self.global_step,
+               "model_state_dict": model.state_dict(),
+               "optimizer_state_dict": optimizer.state_dict(),
+               "scheduler_state_dict": scheduler.state_dict(),
+               "metrics": metrics,
+               "config": config,
+           }
+        2. 保存到 checkpoint_dir/checkpoint_epoch_{epoch}.pt
+        3. 如果是最佳模型，额外保存为 best_model.pt
+        4. 清理旧的检查点 (保留最近 max_checkpoints 个)
+        """
+        raise NotImplementedError("TODO: Person C 实现 _save_checkpoint")
+
+    def _load_checkpoint(self, checkpoint_path: str):
+        """
+        加载检查点继续训练。
+
+        TODO [Person C]:
+        1. torch.load(checkpoint_path)
+        2. 恢复 model, optimizer, scheduler 状态
+        3. 恢复 epoch, step 计数器
+        """
+        raise NotImplementedError("TODO: Person C ��现 _load_checkpoint")
+
+    def _should_early_stop(self, metrics: dict) -> bool:
+        """
+        判断是否应该早停。
+
+        TODO [Person C]:
+        1. 比较当前指标与最佳指标
+        2. 如果连续 patience 个 epoch 没有改善，返回 True
+        """
+        raise NotImplementedError("TODO: Person C 实现 _should_early_stop")
+
+    def _log_metrics(self, epoch: int, train_loss: float, val_metrics: dict):
+        """
+        记录训练指标到 TensorBoard / WandB。
+
+        TODO [Person C]:
+        1. 使用 self.logger 记录 train_loss, val_loss, bleu, lr 等
+        2. 打印到控制台 (使用 rich 库的 table 格式)
+        """
+        raise NotImplementedError("TODO: Person C 实现 _log_metrics")
+
+    def _setup_distributed(self):
+        """
+        设置分布式训练。
+
+        TODO [Person C]: 根据 config["training"]["distributed"]["strategy"]:
+        1. "ddp": 使用 torch.nn.parallel.DistributedDataParallel
+        2. "fsdp": 使用 torch.distributed.fsdp.FullyShardedDataParallel
+        3. "deepspeed": 使用 deepspeed.initialize()
+
+        也可以使用 HuggingFace Accelerate 统一处理。
+        """
+        raise NotImplementedError("TODO: Person C 实现 _setup_distributed")

src/easytranslate/utils/__init__.py

@@ -0,0 +1,7 @@
+"""工具模块"""
+
+from easytranslate.utils.config import load_config, merge_configs
+from easytranslate.utils.seed import set_seed
+from easytranslate.utils.logging import setup_logging
+
+__all__ = ["load_config", "merge_configs", "set_seed", "setup_logging"]

src/easytranslate/utils/config.py

@@ -0,0 +1,51 @@
+"""
+配置管理模块 — 公共模块 (Person E 可以先完成)
+
+功能: 加载 YAML 配置，支持命令行覆盖和多配置合并。
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import Any, Optional
+
+from omegaconf import OmegaConf, DictConfig
+
+logger = logging.getLogger(__name__)
+
+
+def load_config(config_path: str | Path) -> DictConfig:
+    """
+    加载 YAML 配置文件。
+
+    TODO [Person E]: 实现以下逻辑:
+    1. 使用 OmegaConf.load(config_path) 加载配置
+    2. 验证配置完整性
+    3. 返回 DictConfig 对象
+    """
+    raise NotImplementedError("TODO: Person E 实现 load_config")
+
+
+def merge_configs(base_config: DictConfig, override_config: DictConfig) -> DictConfig:
+    """
+    合并配置 (override 覆盖 base)。
+
+    TODO [Person E]:
+    使用 OmegaConf.merge(base_config, override_config)
+    """
+    raise NotImplementedError("TODO: Person E 实现 merge_configs")
+
+
+def config_from_cli(config_path: str, cli_args: list[str]) -> DictConfig:
+    """
+    从配置文件 + 命令行参数构建最终配置。
+
+    TODO [Person E]:
+    1. 加载 config_path
+    2. 使用 OmegaConf.from_cli(cli_args) 解析命令行参数
+    3. 合并并返回
+
+    使用方式: python train.py --config configs/default.yaml training.lr=1e-4 model.nhead=16
+    """
+    raise NotImplementedError("TODO: Person E 实现 config_from_cli")

src/easytranslate/utils/logging.py

@@ -0,0 +1,26 @@
+"""
+日志管理模块 — 公共模块
+"""
+
+import logging
+import sys
+from pathlib import Path
+from typing import Optional
+
+
+def setup_logging(
+    log_dir: Optional[str] = None,
+    level: int = logging.INFO,
+    log_file: Optional[str] = None,
+):
+    """
+    配置日志系统。
+
+    TODO [Person E]: 实现以下逻辑:
+    1. 创建 root logger
+    2. 设置 StreamHandler (控制台输出)
+    3. (可选) 设置 FileHandler (文件输出)
+    4. 使用 rich.logging.RichHandler 美化控制台输出
+    5. 设置日志格式: [时间] [级别] [模块名] 消息
+    """
+    raise NotImplementedError("TODO: Person E 实现 setup_logging")

src/easytranslate/utils/seed.py

@@ -0,0 +1,23 @@
+"""
+随机种子管理模块 — 公共模块
+"""
+
+import random
+
+import numpy as np
+import torch
+
+
+def set_seed(seed: int = 42):
+    """
+    设置全局随机种子以确保实验可复现。
+
+    TODO [Person E]:
+    1. random.seed(seed)
+    2. np.random.seed(seed)
+    3. torch.manual_seed(seed)
+    4. torch.cuda.manual_seed_all(seed)
+    5. torch.backends.cudnn.deterministic = True
+    6. torch.backends.cudnn.benchmark = False
+    """
+    raise NotImplementedError("TODO: Person E 实现 set_seed")

tests/test_data.py

@@ -0,0 +1,72 @@
+"""
+单元测试 — 数据模块 (Person A 实现后需通过)
+"""
+
+import pytest
+import torch
+
+
+class TestTranslationDataset:
+    """测试 TranslationDataset 类。"""
+
+    def test_dataset_length(self):
+        """测试数据集长度。"""
+        # TODO: 创建 mock tokenizer，构建小型数据集，验证 len() 正确
+        pass
+
+    def test_getitem_returns_correct_keys(self):
+        """测试 __getitem__ 返回正确的字段。"""
+        # TODO: 验证返回 dict 包含 src_ids, tgt_input_ids, labels, src_len, tgt_len
+        pass
+
+    def test_getitem_tensor_types(self):
+        """测试返回的 tensor 类型正确。"""
+        pass
+
+    def test_src_tgt_mismatch_raises(self):
+        """测试源目标数量不匹配时抛出异常。"""
+        pass
+
+
+class TestTokenizer:
+    """测试分词器。"""
+
+    def test_bpe_train_and_encode(self):
+        """测试 BPE 训练和编码。"""
+        pass
+
+    def test_encode_decode_roundtrip(self):
+        """测试编码-解码往返一致性。"""
+        pass
+
+    def test_special_tokens(self):
+        """测试特殊 token 正确。"""
+        pass
+
+
+class TestPreprocessing:
+    """测试预处理。"""
+
+    def test_clean_text_unicode(self):
+        """测试 Unicode 标准化。"""
+        pass
+
+    def test_filter_by_length(self):
+        """测试按长度过滤。"""
+        pass
+
+    def test_deduplicate(self):
+        """测试去重。"""
+        pass
+
+
+class TestCollator:
+    """测试数据整理器。"""
+
+    def test_padding(self):
+        """测试 padding 正确。"""
+        pass
+
+    def test_attention_mask(self):
+        """测试 attention mask 正确。"""
+        pass

tests/test_evaluation.py

@@ -0,0 +1,54 @@
+"""
+单元测试 — 评估模块 (Person D 实现后需通过)
+"""
+
+import pytest
+import torch
+
+
+class TestMetrics:
+    """测试评估指标。"""
+
+    def test_bleu_perfect(self):
+        """完美翻译的 BLEU 应接近 100。"""
+        pass
+
+    def test_bleu_zero(self):
+        """完全不相关的翻译 BLEU 应接近 0。"""
+        pass
+
+    def test_chrf_score(self):
+        """测试 chrF 分数范围合理。"""
+        pass
+
+
+class TestDecoding:
+    """测试解码策略。"""
+
+    def test_greedy_decode_shape(self):
+        """测试贪心解码输出维度。"""
+        pass
+
+    def test_greedy_produces_eos(self):
+        """测试贪心解码能生成 EOS。"""
+        pass
+
+    def test_beam_search_better_than_greedy(self):
+        """束搜索质量应不低于贪心。"""
+        pass
+
+    def test_no_repeat_ngram(self):
+        """测试 n-gram 不重复约束。"""
+        pass
+
+
+class TestEvaluator:
+    """测试评估器。"""
+
+    def test_translate_single(self):
+        """测试单句翻译。"""
+        pass
+
+    def test_translate_batch(self):
+        """测试批量翻译。"""
+        pass

tests/test_model.py

@@ -0,0 +1,60 @@
+"""
+单元测试 — 模型模块 (Person B 实现后需通过)
+"""
+
+import pytest
+import torch
+
+
+class TestMultiHeadAttention:
+    """测试多头注意力。"""
+
+    def test_output_shape(self):
+        """测试输出维度正确。"""
+        # TODO: 创建 MHA，输入 [2, 10, 512]，验证输出 [2, 10, 512]
+        pass
+
+    def test_padding_mask(self):
+        """测试 padding mask 效果。"""
+        pass
+
+
+class TestPositionalEncoding:
+    """测试位置编码。"""
+
+    def test_sinusoidal_shape(self):
+        """测试正弦位置编码输出维度。"""
+        pass
+
+    def test_rope_shape(self):
+        """测试 RoPE 输出维度。"""
+        pass
+
+    def test_rope_relative_distance(self):
+        """测试 RoPE 捕获相对距离。"""
+        pass
+
+
+class TestTransformerModel:
+    """测试完整 Transformer 模型。"""
+
+    def test_forward_shape(self):
+        """测试前向传播输出维度。"""
+        # TODO: 构建小模型，输入 mock 数据，验证 logits shape [B, T, V]
+        pass
+
+    def test_encode_shape(self):
+        """测试 encode 输出维度。"""
+        pass
+
+    def test_decode_step_shape(self):
+        """测试 decode_step 输出维度。"""
+        pass
+
+    def test_parameter_count(self):
+        """测试参数数量计算。"""
+        pass
+
+    def test_causal_mask(self):
+        """测试因果掩码生成。"""
+        pass

tests/test_training.py

@@ -0,0 +1,46 @@
+"""
+单元测试 — 训练模块 (Person C 实现后需通过)
+"""
+
+import pytest
+import torch
+
+
+class TestLabelSmoothedLoss:
+    """测试标签平滑损失。"""
+
+    def test_no_smoothing_equals_ce(self):
+        """smoothing=0 时应等于标准交叉熵。"""
+        pass
+
+    def test_smoothing_reduces_confidence(self):
+        """标签平滑应降低损失对正确预测的自信度。"""
+        pass
+
+    def test_ignore_padding(self):
+        """应忽略 padding 位置的损失。"""
+        pass
+
+
+class TestOptimizer:
+    """测试优化器构建。"""
+
+    def test_build_adamw(self):
+        """测试构建 AdamW。"""
+        pass
+
+    def test_weight_decay_groups(self):
+        """测试权重衰减参数组正确。"""
+        pass
+
+
+class TestScheduler:
+    """测试学习率调度器。"""
+
+    def test_warmup_phase(self):
+        """测试 warmup 阶段 lr 线性增长。"""
+        pass
+
+    def test_decay_phase(self):
+        """测试衰减阶段 lr 下降。"""
+        pass