LLM 파인튜닝 프로젝트

Hugging Face Transformers와 PEFT(LoRA)를 사용한 대규모 언어 모델(LLM) 파인튜닝 프로젝트입니다.

📁 프로젝트 구조

fine_tunning/
├── .env                   # 허깅페이스 토큰 (비공개)
├── .gitignore             # Git 제외 파일
├── config.py              # 설정 클래스 (모델, LoRA, 학습 설정)
├── data_loader.py         # 데이터 로딩 및 전처리
├── data_augmentation.py   # 📊 데이터 증강 모듈
├── model_downloader.py    # 허깅페이스 모델 다운로드
├── model_uploader.py      # 🚀 허깅페이스 모델 업로드
├── monitoring.py          # 📈 학습 모니터링 (TensorBoard/WandB)
├── trainer.py             # 파인튜닝 트레이너 모듈
├── inference.py           # 추론 및 챗봇 모듈
├── evaluation.py          # 📊 모델 평가 도구
├── web_demo.py            # 💬 웹 데모 (Gradio/Streamlit)
├── main.py                # 메인 실행 스크립트
├── sample_data.json       # 샘플 학습 데이터
├── requirements.txt       # 의존성 패키지
└── README.md              # 프로젝트 설명

🚀 시작하기

1. 환경 설정

# 가상환경 생성 (권장)
python -m venv venv
source venv/bin/activate  # Linux/Mac
# 또는
.\venv\Scripts\activate  # Windows

# 의존성 설치
pip install -r requirements.txt

2. 허깅페이스 토큰 설정

.env 파일에 허깅페이스 토큰을 설정하세요:

# .env 파일
HF_TOKEN=your_huggingface_token_here

⚠️ .env 파일은 .gitignore에 포함되어 Git에 커밋되지 않습니다.

3. GPU 요구사항

• VRAM: 최소 16GB 권장 (4bit 양자화 사용 시)
• CUDA: 11.8 이상

---

📖 핵심 기능

1️⃣ 모델 다운로드

# 모델 정보 조회
python model_downloader.py info beomi/llama-2-ko-7b

# 모델 다운로드
python model_downloader.py download beomi/llama-2-ko-7b --output ./models

# 모델 검색
python model_downloader.py search "korean llm" --task text-generation

2️⃣ 파인튜닝 실행

# 기본 실행 (로컬 데이터)
python main.py --train_file "./sample_data.json"

# 모델 다운로드 후 파인튜닝
python main.py --download_model --model_name "beomi/llama-2-ko-7b"

# 전체 옵션
python main.py \
    --model_name "beomi/llama-2-ko-7b" \
    --train_file "./sample_data.json" \
    --output_dir "./outputs" \
    --num_epochs 3 \
    --batch_size 4 \
    --learning_rate 2e-4 \
    --lora_r 16 \
    --lora_alpha 32 \
    --merge_model

3️⃣ 추론 실행

# 대화형 모드
python inference.py --model_path "./outputs/final_model" \
    --base_model "beomi/llama-2-ko-7b" --interactive

# 병합된 모델 사용
python inference.py --model_path "./outputs/merged_model" --interactive

---

📊 추가 기능

1. 학습 모니터링 (TensorBoard/WandB)

# 모니터링 테스트
python monitoring.py --tensorboard --output ./logs

# TensorBoard 실행
tensorboard --logdir ./logs/tensorboard

주요 기능:

• 📈 실시간 손실/학습률 추적
• 📊 퍼플렉시티 모니터링
• 📉 그래디언트 노름 추적
• 💾 메트릭 JSON 저장
• 🖼️ 학습 곡선 자동 시각화

2. 데이터 증강

# 데이터 증강 실행
python data_augmentation.py -i sample_data.json -o augmented_data.json -n 2

# 옵션
python data_augmentation.py \
    --input sample_data.json \
    --output augmented_data.json \
    --num_aug 3 \
    --synonym_prob 0.3 \
    --swap_prob 0.2

지원 기법:

• 🔄 동의어 치환 (한국어/영어)
• ➕ 랜덤 삽입
• 🔀 랜덤 스왑
• ➖ 랜덤 삭제
• 🔤 노이즈 추가 (오타)

3. 모델 평가

# 평가 실행
python evaluation.py \
    --model_path "./outputs/final_model" \
    --base_model "beomi/llama-2-ko-7b" \
    --test_file "./sample_data.json" \
    --output_dir "./eval_results"

평가 지표:

• 📊 Perplexity
• 📈 BLEU Score
• 📉 ROUGE-1/2/L
• ✨ 생성 품질 (길이, 반복률, 일관성)
• 📝 마크다운 리포트 자동 생성

4. 모델 업로드 (Hugging Face Hub)

# 모델 업로드
python model_uploader.py upload \
    --model_path "./outputs/final_model" \
    --repo_name "your-username/my-finetuned-model" \
    --base_model "beomi/llama-2-ko-7b" \
    --dataset "custom" \
    --description "한국어 파인튜닝 모델"

# 내 모델 목록
python model_uploader.py list

# 저장소 삭제
python model_uploader.py delete your-username/my-model

자동 생성:

• 📝 모델 카드 (README.md)
• ⚙️ 학습 설정 저장
• 📊 평가 결과 포함

5. 웹 데모 (Gradio/Streamlit)

# Gradio 데모 실행
python web_demo.py \
    --model_path "./outputs/final_model" \
    --base_model "beomi/llama-2-ko-7b" \
    --type gradio \
    --port 7860

# 공유 링크 생성
python web_demo.py --model_path "./outputs/final_model" --share

# Streamlit 스크립트 생성
python web_demo.py --model_path "./outputs/final_model" --type streamlit
# 그 후: streamlit run streamlit_demo.py

기능:

• 💬 실시간 채팅 인터페이스
• ⚙️ 파라미터 조절 (Temperature, Top-P, Top-K)
• 🔄 대화 히스토리 관리
• 📱 반응형 UI

---

🔧 설정 옵션

모델 설정 (ModelConfig)

파라미터	기본값	설명
model_name	beomi/llama-2-ko-7b	베이스 모델 이름
use_4bit	True	4bit 양자화 사용
use_8bit	False	8bit 양자화 사용

LoRA 설정 (LoraConfig)

파라미터	기본값	설명
r	16	LoRA rank
lora_alpha	32	LoRA alpha
lora_dropout	0.05	Dropout 비율

학습 설정 (TrainingConfig)

파라미터	기본값	설명
num_train_epochs	3	학습 에포크 수
per_device_train_batch_size	4	배치 사이즈
learning_rate	2e-4	학습률
gradient_accumulation_steps	4	그래디언트 누적

---

📊 지원 데이터 형식

1. Instruction 형식 (권장)

[
    {
        "instruction": "질문 또는 지시사항",
        "input": "추가 입력 (선택)",
        "output": "원하는 출력"
    }
]

2. Chat 형식

[
    {
        "messages": [
            {"role": "user", "content": "안녕하세요"},
            {"role": "assistant", "content": "안녕하세요! 무엇을 도와드릴까요?"}
        ]
    }
]

3. 일반 텍스트

[
    {"text": "학습할 텍스트 내용..."}
]

---

🔄 추천 모델

모델	크기	설명
beomi/llama-2-ko-7b	7B	한국어 Llama 2
beomi/Llama-3-Open-Ko-8B	8B	한국어 Llama 3
google/gemma-2b	2B	Gemma 2B
google/gemma-7b	7B	Gemma 7B
Qwen/Qwen2-7B	7B	Qwen2 7B
mistralai/Mistral-7B-v0.1	7B	Mistral 7B

---

⚠️ 주의사항

1. Python 3.14 호환성: Python 3.14에서는 datasets 라이브러리 호환성 이슈가 있을 수 있습니다. 로컬 데이터 파일 사용을 권장합니다.
2. GPU 메모리: 7B 모델 기준 4bit 양자화 시 약 10-12GB VRAM 필요
3. 학습 시간: 데이터 크기와 에포크 수에 따라 수 시간에서 수일 소요
4. 저장 공간: 모델 체크포인트로 수 GB 필요

---

📚 참고 자료

• Hugging Face PEFT
• TRL - Transformer Reinforcement Learning
• BitsAndBytes
• Gradio

라이선스

MIT License