README.md

---
license: mit
title: 한국어 텍스트 비난독화 AI 모델 | Korean Text De-obfuscation Fine-tuning
sdk: streamlit
emoji: 📚
colorFrom: purple
colorTo: indigo
sdk_version: 1.45.1
---
# 🔤 한국어 텍스트 비난독화 AI 모델 | Korean Text De-obfuscation Fine-tuning

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![HuggingFace](https://img.shields.io/badge/🤗-HuggingFace-yellow)](https://huggingface.co/)

**숭실대학교 지능형시스템 과목**의 **91veMe4Plus 팀**에서 설계하고 개발한 **난독화된 한국어 문자열의 원본을 추론하는 언어모델 파인튜닝** 연구 프로젝트입니다.

## 🎯 프로젝트 개요

**난독화된 한국어 텍스트를 원본으로 복원**하는 언어모델 파인튜닝 프로젝트입니다. **Naver HyperCLOVAX-SEED-Text-Instruct-0.5B** 모델을 **LoRA (Low-Rank Adaptation)**로 파인튜닝하여 왜곡되거나 변형된 한국어 문자열에서 원본 텍스트를 정확히 추론할 수 있는 AI 모델을 개발했습니다.

### 🔤 난독화 복원 예시

| 난독화된 텍스트 | 원본 텍스트 |
|----------------|--------------|
| ㅇㅏㄴㄴㅕㅇ하세요 | 안녕하세요     |
| ㅎㅏㅇㅏㄱㅣㅁㅏㄹ | 하늘이 맑음   |
| ㅁㅏㄹㅎㅏㅁㅅㅣㄴㄴㅏ | 말할 수 있는 나 |

### 핵심 성과
- **BLEU 점수**: 7-10배 향상 (0.0029 → 0.0233)
- **ROUGE-1**: 2배 향상 (0.138 → 0.279)
- **문자 정확도**: 2배 향상 (0.151 → 0.332)
- **추론 시간**: 50% 단축 (6.78s → 3.03s)

## 🏫 학술 정보

- **대학교**: 숭실대학교 (Soongsil University)
- **과목**: 지능형시스템 (Intelligent Systems)
- **팀명**: 91veMe4Plus
- **프로젝트**: 한국어 텍스트 비난독화 AI 모델 성능 최적화 연구

## 📊 모델 성능

| 모델 | BLEU | ROUGE-1 | ROUGE-2 | ROUGE-L | 문자 정확도 | 추론 시간 |
|------|------|---------|---------|---------|-------------|-----------|
| 원본 HyperCLOVAX | 0.0029 | 0.138 | 0.064 | 0.138 | 0.151 | 6.78s |
| **파인튜닝 모델** | **0.0233** | **0.276** | **0.148** | **0.279** | **0.332** | **3.03s** |

## 🛠️ 기술 스택

### 모델 아키텍처
- **베이스 모델**: Naver HyperCLOVAX-SEED-Text-Instruct-0.5B
- **파인튜닝 기법**: LoRA (Low-Rank Adaptation)
- **양자화**: 4-bit BitsAndBytes
- **최적화**: AdamW + Linear Warmup

### LoRA 설정
```python
LoraConfig(
    r=16,
    lora_alpha=32,
    target_modules=["q_proj", "k_proj", "v_proj", "o_proj", 
                   "gate_proj", "up_proj", "down_proj"],
    lora_dropout=0.1,
    task_type=TaskType.CAUSAL_LM
)
```

## 📈 실험 결과

### 하이퍼파라미터 최적화
- **Learning Rate**: 1e-4 vs 5e-4 비교
- **Batch Size**: 1, 2, 4 비교  
- **Dataset Size**: 10K vs 30K 샘플 비교

### 최적 설정
- **Learning Rate**: 1e-4
- **Batch Size**: 4
- **Dataset Size**: 10,000 샘플 (효율성 관점)

## 💾 데이터셋

**696,024개** 한국어 텍스트 샘플 (6가지 유형):
- 구어체/대화체 (16,878)
- 뉴스문어체 (281,932)
- 문화문어체 (25,628)
- 전문분야문어체 (306,542)
- 조례문어체 (36,339)
- 지자체웹사이트문어체 (28,705)

## 🚀 빠른 시작

### 설치
```bash
pip install transformers peft torch bitsandbytes
```

### 사용법
```python
from transformers import AutoTokenizer, AutoModelForCausalLM
from peft import PeftModel

# 모델 로드
base_model = AutoModelForCausalLM.from_pretrained(
    "navercorp/HyperCLOVAX-SEED-Text-Instruct-0.5B"
)
model = PeftModel.from_pretrained(base_model, "path/to/lora/adapter")
tokenizer = AutoTokenizer.from_pretrained(
    "navercorp/HyperCLOVAX-SEED-Text-Instruct-0.5B"
)

# 추론
prompt = """### 지시사항:
다음 난독화된 한국어 텍스트를 원래 텍스트로 복원해주세요.

난독화된 텍스트: ㅇㅏㄴㄴㅕㅇ하세요

### 응답:"""

inputs = tokenizer(prompt, return_tensors="pt")
outputs = model.generate(**inputs, max_new_tokens=128, temperature=0.7)
result = tokenizer.decode(outputs[0], skip_special_tokens=True)
```

## 📁 주요 파일

```
FineTuningLLM/
├── 🧪 실험 노트북
│   ├── learning_rate_hyperclova_deobfuscation_finetuning.ipynb
│   ├── batch_size_hyperclova_deobfuscation_finetuning.ipynb
│   └── datasets_hyperclova_deobfuscation_finetuning.ipynb
├── 📊 성능 분석
│   ├── model_performance_analysis_*.ipynb
│   └── team_all_model_performance_analysis_*.ipynb
├── 🤖 훈련된 모델
│   ├── hyperclova-deobfuscation-lora-1e-4-learning-rate/
│   ├── hyperclova-deobfuscation-lora-*-batch-size/
│   └── hyperclova-deobfuscation-lora-*-datasets/
└── 📈 분석 결과 (CSV, PNG)
```

## 🔧 요구사항

- Python 3.8+
- PyTorch 2.0+
- CUDA 지원 GPU (권장)
- 16GB+ RAM

## 📝 라이선스

MIT License - Copyright (c) 2025 91veMe4Plus

## 🤝 기여하기

이슈나 PR은 언제든 환영합니다! 한국어 NLP 연구에 관심이 있으시면 참여해주세요.

## 📞 연락처

- **팀**: 91veMe4Plus
- **프로젝트**: 한국어 텍스트 비난독화 AI 모델 성능 분석

---

*이 프로젝트는 한국어 텍스트 처리 성능 향상을 위한 연구 목적으로 개발되었습니다.*