README.md

---
license: apache-2.0
base_model: Qwen/Qwen2.5-1.5B-Instruct
tags:
- qwen
- qwen2.5
- lora
- unsloth
- korean
- education
- textbook
language:
- ko
datasets:
- maywell/korean_textbooks
library_name: peft
pipeline_tag: text-generation
---

# 한국어 교육 자료 파인튜닝 모델 (Qwen2.5-1.5B + LoRA)

## 모델 소개

**Qwen/Qwen2.5-1.5B-Instruct** 를 기반으로 **maywell/korean_textbooks** 데이터셋, 그리고
**LoRA(저랭크 적응)** 기법을 사용해 파인튜닝한 **어댑터(LoRA 가중치)** 입니다.
베이스 가중치는 포함되지 않으며, **베이스 + 어댑터**로 로드하여 사용합니다.
- 학습 방식: LoRA (QLoRA, 4bit 로딩)
- 주요 목적: 한국어 교육/설명형 응답 품질 향상

> 참고: 학습에는 Unsloth/TRL/PEFT 스택을 사용했고, 추론은 HF Transformers + PEFT만으로 가능합니다.

## 사용 방법

### 1) 모델 로드(4bit + PEFT)
```python
from transformers import AutoTokenizer, AutoModelForCausalLM
from peft import PeftModel
import torch

BASE = "Qwen/Qwen2.5-1.5B-Instruct"
ADAPTER = "Eunma/korean-model"

tokenizer = AutoTokenizer.from_pretrained(BASE)
base = AutoModelForCausalLM.from_pretrained(
    BASE,
    load_in_4bit=True,
    device_map="auto",
    trust_remote_code=True
)

model = PeftModel.from_pretrained(base, ADAPTER)
model.eval()

messages = [
    { "role": "system", "content": "한국어로 정확하고 친절하게 설명하는 교육 도우미입니다." },
    { "role": "user", "content": "2의 거듭제곱에 대해 간단히 설명해줘." },
]

prompt = tokenizer.apply_chat_template(messages, add_generation_prompt=True, tokenize=False)
enc = tokenizer(prompt, return_tensors="pt").to(model.device)
if "attention_mask" not in enc:
    enc["attention_mask"] = torch.ones_like(enc["input_ids"])

with torch.inference_mode():
    out = model.generate(
        **enc,
        max_new_tokens=256,
        do_sample=True, temperature=0.7, top_p=0.9,
        pad_token_id=tokenizer.eos_token_id,
        use_cache=True
    )

print(tokenizer.decode(out[0], skip_special_tokens=True))
```

##  훈련 정보

- **베이스 모델**: Qwen/Qwen2.5-1.5B
- **훈련 스텝**: 30 steps
- **옵티마이저**: adamw_8bit
- **스케줄러**: linear
- **LoRA 설정**: r=8, alpha=16
- **타겟 모듈**: q_proj, k_proj, v_proj, o_proj, gate_proj, up_proj, down_proj
- **데이터셋**: maywell/korean_textbooks


## 시스템 요구사항

- **GPU 메모리**: 최소 6GB (권장 8GB+)
- 학습(QLoRA, 4bit): GPU 12–16GB 권장(T4 16GB에서 확인)
- **Python**: 3.10+
- **주요 라이브러리**: transformers, peft, torch, bitsandbytes, accelerate

## 주의사항
1. 한국어 중심으로 튜닝. 타 언어 응답 품질은 제한적일 수 있음.
2. 베이스 라이선스 및 사용 정책 준수
3. 어댑터만 포함되어 있으므로 베이스 모델과 함께 로드
4. 사실성 검증 필요.

## 관련 링크

- **베이스 모델**: [Qwen2.5-1.5B](https://huggingface.co/Qwen/Qwen2.5-1.5B-Instruct)
- **데이터셋**: [maywell/korean_textbooks](https://huggingface.co/datasets/maywell/korean_textbooks)
- **PEFT(LoRA)**: https://github.com/huggingface/peft
- **Transformers**: https://github.com/huggingface/transformers

## 📜 라이선스

이 모델은 베이스 모델인 Qwen2.5-1.5B의 라이선스를 따릅니다.