# 게임·방송 용어 추가학습

## 결론부터

**가능합니다.** 다만 대부분의 경우 **추가학습보다 용어집이 먼저입니다.**

| 방법 | 준비 | 효과가 나타나는 시점 | 무엇에 좋은가 |
|---|---|---|---|
| **1. 용어집** (구현 완료) | 단어 목록만 | **즉시** | 고유명사, 스킬명, 아이템명, 캐릭터명 |
| **2. LoRA 추가학습** | 문장 쌍 1,000~3,000개 | 30분~3시간 학습 | 말투, 문장 구조, 도메인 어조 |
| **3. 풀 파인튜닝** | 문장 쌍 10,000개 이상 | 수 시간~하루 | 번역 스타일 전면 교체 |

용어집과 추가학습은 **경쟁 관계가 아니라 보완 관계**입니다. 둘 다 켜는 게 가장 좋습니다.

---

## 1. 용어집 — 먼저 이것부터

`용어집` 화면에서 "원문 → 각 언어 역어"를 등록하면 끝입니다. 학습 없이 바로 적용됩니다.

동작 방식은 번역 모델에 따라 다릅니다.

- **1~4티어 (NLLB, Seed-X)** — 등록 단어를 `⟦0⟧` 같은 토큰으로 바꿔치기해 모델이 아예
  건드리지 못하게 한 뒤, 번역이 끝나면 지정한 역어로 되돌립니다.
- **5티어 (Qwen3)** — 그 문장에 실제로 나온 용어만 골라 프롬프트에
  "이 용어는 이렇게 옮겨라"로 넣어줍니다. 조사·어미까지 문맥에 맞게 붙어 더 자연스럽습니다.

4티어 Seed-X가 LLM인데도 프롬프트 방식을 못 쓰는 이유는, 이 모델이 chat template 없는
**번역 전용 completion 모델**이기 때문입니다. 지시문을 이해하지 못할뿐더러 모델 카드가
정한 고정 프롬프트 형식(끝의 `<ko>` 같은 언어 태그 포함)을 벗어나면 품질이 무너집니다.
용어집을 문맥까지 자연스럽게 반영하고 싶다면 5티어를 쓰세요.

CSV로 한 번에 가져올 수 있습니다.

```csv
원문 용어,한국어 역어,English 역어,日本語 역어,中文 역어,메모
Nexus,넥서스,Nexus,ネクサス,基地,LoL
baron,바론,Baron,バロン,男爵,LoL
ult,궁,ultimate,アルティメット,大招,궁극기
gg,잘 싸웠다,gg,gg,打得好,
```

**게임 하나당 200~500개만 등록해도 체감 품질이 크게 올라갑니다.** 추가학습으로
같은 효과를 내려면 훨씬 많은 데이터가 필요합니다. 용어집을 먼저 채우세요.

---

## 2. LoRA 추가학습 — 용어집으로 안 되는 것

용어집은 "이 단어를 저 단어로"만 고칩니다. 아래는 못 잡습니다.

- 말투 — "You're getting rolled" → "탈탈 털리고 있네" (직역 아닌 게임 말투)
- 생략된 주어·목적어 복원 — 게임 음성에는 생략이 많습니다
- 방송 특유의 감탄·리액션 어조

이건 문장 쌍으로 학습시켜야 합니다.

### 필요한 데이터 양

공개 연구 기준으로,

- 언어쌍당 **약 650~1,000 문장**만으로도 LoRA 도메인 적응이 동작합니다.
- 언어쌍당 **2,000 문장 / 15~20 epoch** 수준에서 chrF++ 평균 **+6.1점** 개선이 보고됩니다.

즉 **언어쌍당 1,000~3,000 문장이 현실적인 목표**입니다. 4개 언어 전부가 아니라,
실제로 많이 쓰는 방향(예: 영어→한국어) 하나만 먼저 하는 게 효율적입니다.

### 데이터 만드는 법

1. **게임 공식 현지화 자산** — 한국어판이 있는 게임의 자막/UI 텍스트. 품질이 가장 좋습니다.
2. **자막 파일 쌍** — 같은 영상의 영어 자막 + 한국어 자막(.srt)을 시간축으로 정렬.
3. **이 프로그램의 기록** — `설정 > 번역 기록을 파일로 남기기`를 켜두면
   `%APPDATA%/Hearo/transcripts/` 에 "원문 / 번역" 쌍이 쌓입니다.
   **틀린 번역만 손으로 고쳐서** 학습 데이터로 쓰는 게 가장 현실적인 경로입니다.
4. 위키·커뮤니티 용어 사전 — 용어집으로 쓰는 게 더 낫습니다. 문장이 아니므로.

형식은 JSONL 한 줄에 한 쌍입니다.

```jsonl
{"source": "Enemy missing from mid", "target": "미드 실종", "source_lang": "en", "target_lang": "ko"}
{"source": "I'll take baron", "target": "바론 내가 먹을게", "source_lang": "en", "target_lang": "ko"}
```

### 학습 실행

```bash
pip install -e ".[finetune]"

python scripts/finetune_mt.py \
  --data data/game_terms.jsonl \
  --tier ultimate \
  --output ./adapters/game-ko \
  --epochs 3
```

끝나면 `모델` 화면의 **추가학습 어댑터** 칸에 `./adapters/game-ko` 를 넣으면 적용됩니다.

### 티어별 난이도

| 티어 | 번역 모델 | 방식 | 학습에 필요한 VRAM | 난이도 |
|---|---|---|---|---|
| 1~2 | NLLB-600M | 풀 파인튜닝 가능 | ~8GB | ★ 쉬움 |
| 3 | NLLB-1.3B | LoRA | ~10GB | ★★ |
| 4 | Seed-X-PPO-7B | LoRA (권장 안 함) | ~16GB | ★★★ 까다로움 |
| 5 | **Qwen3-8B** | **LoRA** | **~16GB** | **★ 쉬움 (권장)** |

**4티어 Seed-X는 추가학습 대상으로 권하지 않습니다.** 이미 PPO(강화학습)까지 마친
모델이라 그 위에 SFT를 얹으면 기존 번역 품질이 무너지기 쉽습니다 (catastrophic forgetting).
Int4 양자화 가중치라 학습 자체도 번거롭습니다.

**추가학습을 할 거라면 5티어(Qwen3-8B)**, **VRAM이 부족하면 1~2티어(NLLB-600M 풀 파인튜닝)**
로 가는 게 맞습니다.

### 권장 하이퍼파라미터

연구에서 널리 쓰이는 설정입니다. `scripts/finetune_mt.py` 의 기본값이기도 합니다.

```
LoRA rank r = 16, alpha = 32, dropout = 0.05
대상 모듈: attention 의 q_proj, v_proj
learning rate = 2e-4 (LoRA) / 5e-5 (풀 파인튜닝)
epochs = 3 (데이터 2,000개 이상) / 10~20 (수백 개)
```

---

## 3. 어느 것부터 할지

```
1주차  용어집 300개 등록  →  이것만으로 충분한지 확인
2주차  번역 기록 켜고 실사용, 틀린 문장 수집
3주차  고친 문장 1,000개 모이면 LoRA 학습
```

**용어집만으로 만족스러우면 추가학습은 안 해도 됩니다.** 실제로 고유명사 오역이
체감 불만의 대부분입니다.

## 참고

- [Fine-Tuning NLLB-200 with LoRA on a 650-Sentence Corpus](https://medium.com/@meinnps/fine-tuning-nllb-200-with-lora-on-a-650-sentence-turkmen-english-corpus-082f68bdec71)
- [SemiAdapt / SemiLoRA: Efficient Domain Adaptation for Low-Resource MT (arXiv)](https://arxiv.org/pdf/2510.18725)
- [How to fine-tune a NLLB-200 model](https://cointegrated.medium.com/how-to-fine-tune-a-nllb-200-model-for-translating-a-new-language-a37fc706b865)