# Transformer 记忆模型（可落地版）

## 目标

用轻量 Transformer 读取「词项 CLS + 练习事件序列」，预测**当前回忆成功率**与未来遗忘曲线，并与艾宾浩斯公式融合，保证冷启动可用。

## 架构

```
[CLS 词项特征] + [事件1] + [事件2] + …  →  Linear → 2×(MHA+FFN)  →  CLS  →  sigmoid → P(回忆成功)
```

| 组件 | 说明 |
|------|------|
| **CLS（词项 token）** | 掌握率、连对、对错次数、词长、状态 one-hot |
| **事件 token** | 对错、距上次间隔(log)、耗时、题型 one-hot |
| **注意力** | 解释哪些历史尝试影响当前预测（`attention_hint`） |
| **融合** | `blend = min(1, 事件数/5)`；`recall = blend×模型 + (1-blend)×公式` |

## 目录

- `services/memory_transformer/encoding.py` — 序列特征
- `services/memory_transformer/network.py` — NumPy 推理
- `services/memory_transformer/service.py` — 预测与曲线
- `scripts/train_memory_transformer.py` — PyTorch 训练并导出 JSON
- `data/memory_transformer/default_weights.json` — 默认权重（未训练时回退）

## API

`GET /api/words/{word_id}/memory-model`

返回：`recall_now_percent`、`curve[]`、`recommended_review_days`、`attention_hint[]` 等。

## 训练

```bash
cd backend
source venv/bin/activate
pip install numpy torch
python -m scripts.train_memory_transformer --epochs 30          # 合成数据
python -m scripts.train_memory_transformer --epochs 30 --from-db  # 真实 quiz_records
```

导出：`backend/data/memory_transformer/weights.json`（存在则优先于 default）。

生产 API **仅需 NumPy**，无需安装 PyTorch。

## 与复习调度对接（下一步）

可将 `recommended_review_days` 写回 `words.review_due_date`，与 `quiz_service.review_interval_days` 二选一或加权融合。