README.md

---
language:
- ko
license: apache-2.0
base_model: unsloth/Llama-3.2-3B-Instruct
tags:
- llama
- lora
- korean
- game-npc
- maplestory
- big-five
- unsloth
pipeline_tag: text-generation
---

# 🍁 maple-npc-llama3.2-3B-lora

**메이플스토리 NPC 대화 특화 LoRA 파인튜닝 모델**

> Llama 3.2 3B Instruct 기반 | Unsloth LoRA | 한국어 게임 NPC 특화

---

## 📌 모델 개요

메이플스토리 세계관에 특화된 NPC 대화 생성 모델입니다.  
**Big Five 성격 모델**을 프롬프트로 제어하여 NPC별 고유한 말투와 성격을 구현합니다.

| 항목 | 내용 |
|------|------|
| 베이스 모델 | `unsloth/Llama-3.2-3B-Instruct` |
| 학습 방법 | LoRA (r=16) |
| 학습 데이터 | 메이플스토리 NPC 대화 134샘플 |
| 초기 Loss | 3.25 |
| 최종 Loss | 2.41 |
| 학습 시간 | 33초 (A100, Unsloth 2x) |
| 학습 파라미터 | 0.57% (18M / 3.2B) |

---

## 📊 베이스 모델 vs 파인튜닝 비교

### Q1. 헤네시스 마을 신관에게 인사해줘

**❌ 베이스 Llama 3.2**
```
Hello! I'm a priestess of Henesys.
How can I help you today?
```

**✅ maple-npc (파인튜닝 후)**
```
어서 오세요, 모험가님.
저는 헤네시스 신전을 지키는 신관입니다.
엘나스 여신의 가호가 함께하시길 바랍니다.
```

---

### Q2. 검은 마법사에 대해 알고 있어?

**❌ 베이스 Llama 3.2**
```
The Black Mage is a powerful villain in MapleStory.
He was sealed away but has returned...
```

**✅ maple-npc (파인튜닝 후)**
```
...그 이름은 함부로 입에 담지 마세요.
봉인된 지 100년이 지났지만
아직도 그 어둠의 기운이 대륙 곳곳에 남아있습니다.
```

---

### Q3. 궁수로 전직하려면 어떻게 해야 해?

**❌ 베이스 Llama 3.2**
```
To become an archer, visit the job advancement NPC
and meet the level requirements.
```

**✅ maple-npc (파인튜닝 후)**
```
궁수의 길을 걷고 싶으신가요?
레벨 10 이상이 되셨다면
헤네시스 활터에서 전직 의식을 치를 수 있습니다.
활과 화살은 준비되셨나요, 모험가님?
```

---

### Q4. 메르세데스 여왕님은 어떤 분이야?

**❌ 베이스 Llama 3.2**
```
Mercedes is an elf queen character in MapleStory
with high agility and dual bowguns.
```

**✅ maple-npc (파인튜닝 후)**
```
메르세데스 여왕님...
엘프족의 자랑이자 빛의 수호자이십니다.
검은 마법사와의 전쟁에서 홀로 싸우시다
긴 잠에 드셨지만, 그 용맹함은 우리 모두의 희망입니다.
```

---

## ✅ 핵심 개선 포인트

| 항목 | 베이스 모델 | 파인튜닝 후 |
|------|------------|------------|
| 언어 | 영어 혼용 | 완전 한국어 |
| 말투 | 정보 전달체 | NPC 캐릭터 말투 |
| 세계관 | 위키 설명 수준 | 세계관 몰입 반영 |
| 감정 표현 | 없음 | 캐릭터 감정 포함 |
| 고유명사 | 번역 오류 다수 | 정확한 메이플 용어 |

---

## 🚀 사용법
```python
from unsloth import FastLanguageModel

model, tokenizer = FastLanguageModel.from_pretrained(
    "devmeta/maple-npc-llama3.2-3B-lora",
    max_seq_length=512,
    load_in_4bit=True,
)
FastLanguageModel.for_inference(model)

prompt = """너는 메이플스토리 헤네시스 마을의 신관 NPC야.
친화성이 높고 따뜻한 성격이야.
사용자: 안녕하세요!
NPC:"""

inputs = tokenizer(prompt, return_tensors="pt").to("cuda")
outputs = model.generate(**inputs, max_new_tokens=100,
                         temperature=0.7, do_sample=True)
print(tokenizer.decode(outputs[0], skip_special_tokens=True))
```

---

## 🔗 관련 프로젝트

**MaplePersona** — Big Five 슬라이더 기반 NPC 성격 제어 웹앱
- Gemini Flash + RAG 지역 컨텍스트 + Big Five 실시간 제어
- 슬라이더 조정으로 냉소적/따뜻한 NPC 인격 즉시 전환

---

## 👤 개발자

**Taewan Kim** 
GitHub: [Taewan627](https://github.com/Taewan627)  
HuggingFace: [devmeta](https://huggingface.co/devmeta)