docs: 1차 문서

README.md

@@ -1,10 +1,157 @@
----
-title: README
-emoji: 📈
-colorFrom: pink
-colorTo: purple
-sdk: static
-pinned: false
+# 🔤 한국어 텍스트 비난독화 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 모델 성능 분석
+
 ---
 
-Edit this `README.md` markdown file to author your organization card.
+*이 프로젝트는 한국어 텍스트 처리 성능 향상을 위한 연구 목적으로 개발되었습니다.*