README.md

---
title: Transformer Demo
emoji: 🤖
colorFrom: blue
colorTo: indigo
sdk: gradio
sdk_version: 5.29.0
python_version: "3.10"
app_file: app.py
pinned: false
license: mit
---

# Transformer — 논문 재현 데모

**논문**: [Attention Is All You Need](https://arxiv.org/abs/1706.03762) (Vaswani et al., NIPS 2017)

> RNN과 CNN을 모두 버리고 **오직 attention만으로** 인코더-디코더를 구성한
> Transformer 논문을 처음부터 재현하고, 학습된 모델을 직접 체험할 수 있는 Space입니다.

---

## 무엇을 할 수 있나요?

숫자 시퀀스를 입력하면 **Transformer가 뒤집어** 줍니다.

```
입력 :  1 2 3 4 5
출력 :  5 4 3 2 1
```

그리고 더 흥미로운 건 — 디코더의 **cross-attention 가중치**를 시각화해서
모델이 "출력 i번째 위치를 만들 때 입력 어디를 봤는지"를 직접 볼 수 있다는 거예요.
뒤집기 태스크에서는 **반대각선(anti-diagonal) 패턴**이 또렷이 나타납니다.

---

## 왜 번역이 아니라 숫자 뒤집기인가요?

논문은 영어→독일어 번역으로 검증했지만, 그건 8× P100 GPU로 12시간 학습이 필요해요.
무료 Space에서 그게 안 되니까, **부팅 시 30초 안에 학습 끝나는 toy task**를 골랐습니다.

숫자 뒤집기의 장점:

- 어휘가 작음 (0~9 + 특수 토큰 = 13개)
- 입출력 길이가 같고 정답이 명확
- **장거리 의존성**을 강제 — 출력 1번째는 입력 마지막을 봐야 함
- 시각화가 극적 (반대각선 패턴)

---

## 프로젝트 구조

```
├── app.py             # Gradio 데모 (학습 + 추론 + 시각화)
├── transformer.py     # 논문을 그대로 재현한 Transformer 본체
├── requirements.txt   # 패키지 목록
└── README.md          # 이 파일
```

---

## 모델 구성

이 데모는 논문 base 모델의 **1/8 크기**입니다. 구조는 완전히 동일하고 크기만 줄였어요.

| 항목 | 논문 base | 이 데모 |
|------|-----------|---------|
| d_model | 512 | **64** |
| 층 수 N | 6 | **2** |
| 헤드 수 h | 8 | **4** |
| d_ff | 2048 | **128** |
| 어휘 크기 | 37K (BPE) | **13** |
| 파라미터 | 65M | **~80K** |

---

## 학습 설정

```python
optimizer = Adam(lr=5e-4, betas=(0.9, 0.98), eps=1e-9)   # 논문 §5.3
loss     = CrossEntropy(ignore_index=PAD, label_smoothing=0.1)
steps    = 2000
batch    = 128
```

- 매 step마다 길이 3~10의 무작위 숫자열을 새로 생성 (메모리 절약)
- Gradient clipping = 1.0
- Greedy decoding으로 추론

학습은 부팅할 때 자동으로 진행되며, 끝난 모델은 `model.pt`로 캐싱됩니다.

---

## 논문 핵심 부분 코드 매핑

| 논문 위치 | 코드 위치 |
|-----------|-----------|
| 식 (1) `softmax(QKᵀ/√d_k)V` | `transformer.py :: scaled_dot_product_attention` |
| §3.2.2 Multi-Head | `MultiHeadAttention` |
| §3.5 Positional Encoding | `PositionalEncoding` |
| 식 (2) FFN | `FeedForward` |
| §3.1 인코더 1층 | `EncoderLayer` (Post-LN) |
| §3.1 디코더 1층 | `DecoderLayer` (Post-LN) |
| §3.4 임베딩 × √d_model | `Transformer.encode` 내부 |

---

## 어떻게 봐야 하나요? (시각화 해석)

**Cross-Attention 히트맵**:

- 가로축: 인코더 위치 (입력 토큰들, 왼쪽이 시퀀스 앞쪽)
- 세로축: 디코더 위치 (출력 토큰들, 위쪽이 먼저 생성)
- 색이 밝을수록 강한 attention

뒤집기 태스크에서 잘 학습된 모델은:

```
출력 위치 0 (BOS 다음, 첫 출력 토큰) → 입력 마지막 토큰을 봄
출력 위치 1                          → 입력 끝에서 두 번째를 봄
...
```

따라서 **왼쪽 위 → 오른쪽 아래 대각선**의 반대 방향, 즉
**오른쪽 위 → 왼쪽 아래로 흐르는 anti-diagonal**이 보이면 성공입니다.

---

## Hugging Face Spaces 배포 시 주의사항

ResNet 데모를 배포할 때 겪었던 문제들이 여기서도 동일하게 발생할 수 있어요:

### 1. YAML 프론트매터 필수

이 README.md 최상단의 `--- ... ---` 블록이 없으면 Space가 빌드되지 않습니다.

### 2. `colorFrom`/`colorTo`는 정해진 8색만

허용되는 색: `red, yellow, green, blue, indigo, purple, pink, gray`

### 3. Python 3.13 회피

`audioop` 표준 라이브러리가 3.13에서 제거되어 일부 패키지 빌드 실패. **3.10** 권장.

### 4. PyTorch CPU 빌드

기본적으로 무료 Space는 CPU만 제공됩니다. `torch` 설치 시 CUDA 버전이 들어가면
디스크 용량을 초과할 수 있으니 필요시 `torch --index-url https://download.pytorch.org/whl/cpu`로
명시하세요.

---

## 로컬 실행

```bash
# 1) 의존성 설치
pip install -r requirements.txt

# 2) 데모 실행 (첫 실행 시 자동 학습)
python app.py
```

기본적으로 `http://127.0.0.1:7860` 에서 열립니다.

---

## 학습이 잘 안 되면

체크리스트:

- [ ] PyTorch 버전이 2.0 이상인가
- [ ] 학습 step이 2000번 이상 도는가 (콘솔에 step 200, 400, ... 로그 확인)
- [ ] step 1000쯤 되면 `token_acc`가 0.95 이상인가
- [ ] 출력이 항상 같은 토큰만 반복한다면 → 학습이 거의 안 된 것. step 늘리거나 lr 조정
- [ ] cross-attention이 균일(uniform)하다면 → 더 학습 필요

---

## 참고

```bibtex
@inproceedings{vaswani2017attention,
  title     = {Attention Is All You Need},
  author    = {Vaswani, Ashish and Shazeer, Noam and Parmar, Niki
               and Uszkoreit, Jakob and Jones, Llion and Gomez, Aidan N
               and Kaiser, {\L}ukasz and Polosukhin, Illia},
  booktitle = {Advances in Neural Information Processing Systems},
  year      = {2017}
}
```

- 📄 논문: [arXiv:1706.03762](https://arxiv.org/abs/1706.03762)
- 📝 The Annotated Transformer: <http://nlp.seas.harvard.edu/annotated-transformer/>
- 🎥 The Illustrated Transformer (Jay Alammar): <https://jalammar.github.io/illustrated-transformer/>