README.md

metadata

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 (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

---

학습 설정

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로 명시하세요.

---

로컬 실행

# 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)하다면 → 더 학습 필요

---

참고

@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
• 📝 The Annotated Transformer: http://nlp.seas.harvard.edu/annotated-transformer/
• 🎥 The Illustrated Transformer (Jay Alammar): https://jalammar.github.io/illustrated-transformer/