README.md

# 🎮 KoELECTRA Multi-Label Review Classifier (AI 기반 리뷰 인사이트 시스템)

이 모델은 한국어 게임 리뷰(예: Steam 리뷰)를 기반으로 학습된 **다중 라벨 분류 모델**입니다.  
사용자는 하나의 리뷰 문장에서 **15개 항목(성능, 버그, 스토리, 번역, 밸런스 등)** 을 동시에 예측할 수 있습니다.

---

## 🧠 Model Overview
- **Base Model:** monologg/koelectra-base-v3-discriminator  
- **Framework:** Hugging Face Transformers + PyTorch  
- **Task:** Multi-label Text Classification  
- **Loss:** BCEWithLogitsLoss (pos_weight 보정 적용)  
- **Epochs:** 8  
- **Optimizer:** AdamW (lr=2e-5)  
- **Hardware:** NVIDIA A100 / T4 GPU  
- **Metrics:** Micro-F1, Macro-F1, Accuracy  

---

## 🏷️ Labels (15 categories)
| Index | Label | 설명 |
|:--:|:--|:--|
| 0 | y_OPTIMIZATION | 최적화 / 프레임 |
| 1 | y_BUG_CRASH | 버그, 크래시 |
| 2 | y_GRAPHICS | 그래픽 품질 |
| 3 | y_SOUND | 사운드 품질 |
| 4 | y_CONTROL | 조작감 |
| 5 | y_MATCHMAKING_SERVER | 매칭, 서버 품질 |
| 6 | y_BALANCE | 밸런스 |
| 7 | y_STORY | 스토리 완성도 |
| 8 | y_TRANSLATION_LOCALIZATION | 번역, 현지화 |
| 9 | y_PRICE_VALUE | 가격 대비 가치 |
| 10 | y_TUTORIAL_GUIDE | 튜토리얼, 가이드 |
| 11 | y_UI_UX | UI/UX 편의성 |
| 12 | y_CONTENT_UPDATE | 콘텐츠 업데이트 |
| 13 | y_GAMEPLAY_MECHANICS | 게임 플레이 메커닉 |
| 14 | y_ENGAGEMENT | 몰입감 |

---

## 📊 Example Usage
```python
from transformers import AutoTokenizer, AutoModelForSequenceClassification
import torch

model_id = "Wing4/results"
tok = AutoTokenizer.from_pretrained(model_id)
model = AutoModelForSequenceClassification.from_pretrained(model_id)

text = "스토리가 흥미롭고 그래픽이 뛰어나요. 하지만 서버가 자주 끊깁니다."
inputs = tok(text, return_tensors="pt", truncation=True, padding=True)

with torch.no_grad():
    logits = model(**inputs).logits
    probs = torch.sigmoid(logits).squeeze().tolist()
print(probs)

## 📈 Performance (Validation)

| Epoch | Train Loss | Val Loss | Micro-F1 | Macro-F1 | Accuracy |
|:--:|:--:|:--:|:--:|:--:|:--:|
| 1 | 1.1288 | 0.3854 | 0.4887 | 0.3474 | 0.7239 |
| 2 | 0.6371 | 0.3293 | 0.6716 | 0.4794 | 0.8410 |
| 3 | 0.4236 | 0.2891 | 0.7467 | 0.5399 | 0.8854 |
| 4 | 0.3349 | 0.2389 | 0.7599 | 0.5450 | 0.9045 |
| 5 | 0.2788 | 0.2339 | 0.8100 | 0.5882 | 0.9320 |
| 6 | 0.2539 | 0.2617 | 0.8416 | 0.6263 | 0.9365 |
| 7 | 0.1976 | 0.2573 | 0.8590 | 0.6471 | 0.9433 |

**📊 최종 성능 (Epoch 8)**  
- **Micro-F1:** 0.86  
- **Macro-F1:** 0.65  
- **Accuracy:** 0.94  
- **Validation Loss:** 0.257  

> pos_weight 보정(`√`)을 적용한 모델로, 이전 버전 대비 확률 스케일 안정화 및 F1 향상(+0.13p)을 달성했습니다.


📜 License & Author
Author: Wing4

Created: 2025-10