|
|
--- |
|
|
language: |
|
|
- ko |
|
|
license: apache-2.0 |
|
|
tags: |
|
|
- text2sql |
|
|
- spider |
|
|
- korean |
|
|
- llama |
|
|
- text-generation |
|
|
- table-question-answering |
|
|
datasets: |
|
|
- spider |
|
|
- huggingface-KREW/spider-ko |
|
|
base_model: unsloth/Meta-Llama-3.1-8B-Instruct |
|
|
model-index: |
|
|
- name: Llama-3.1-8B-Spider-SQL-Ko |
|
|
results: |
|
|
- task: |
|
|
type: text2sql |
|
|
name: Text to SQL |
|
|
dataset: |
|
|
name: Spider (Korean) |
|
|
type: text2sql |
|
|
metrics: |
|
|
- type: exact_match |
|
|
value: 42.65 |
|
|
- type: execution_accuracy |
|
|
value: 65.47 |
|
|
--- |
|
|
|
|
|
# Llama-3.1-8B-Spider-SQL-Ko |
|
|
|
|
|
한국어 질문을 SQL 쿼리로 변환하는 Text-to-SQL 모델입니다. |
|
|
[Spider](https://yale-lily.github.io/spider) train 데이터셋을 한국어로 번역한 [spider-ko](https://huggingface.co/datasets/huggingface-KREW/spider-ko) 데이터셋을 활용하여 미세조정하였습니다. |
|
|
|
|
|
## 📊 주요 성능 |
|
|
|
|
|
Spider 한국어 검증 데이터셋(1,034개) 평가 결과: |
|
|
- **정확 일치율**: 42.65% (441/1034) |
|
|
- **실행 정확도**: 65.47% (677/1034) |
|
|
|
|
|
> 💡 실행 정확도가 정확 일치율보다 높은 이유는, SQL 문법이 다르더라도 동일한 결과를 반환하는 경우가 많기 때문입니다. |
|
|
|
|
|
## 🚀 바로 시작하기 |
|
|
|
|
|
```python |
|
|
from unsloth import FastLanguageModel |
|
|
|
|
|
# 모델 불러오기 |
|
|
model, tokenizer = FastLanguageModel.from_pretrained( |
|
|
model_name="huggingface-KREW/Llama-3.1-8B-Spider-SQL-Ko", |
|
|
max_seq_length=2048, |
|
|
dtype=None, |
|
|
load_in_4bit=True, |
|
|
) |
|
|
|
|
|
# 한국어 질문 → SQL 변환 |
|
|
question = "가수는 몇 명이 있나요?" |
|
|
schema = """테이블: singer |
|
|
컬럼: singer_id, name, country, age""" |
|
|
|
|
|
prompt = f"""데이터베이스 스키마: |
|
|
{schema} |
|
|
|
|
|
질문: {question} |
|
|
SQL:""" |
|
|
|
|
|
# 결과: SELECT count(*) FROM singer |
|
|
``` |
|
|
|
|
|
## 📝 모델 소개 |
|
|
|
|
|
- **기반 모델**: Llama 3.1 8B Instruct (4bit 양자화) |
|
|
- **학습 데이터**: [spider-ko](https://huggingface.co/datasets/huggingface-KREW/spider-ko) (1-epoch) |
|
|
- **지원 DB**: 166개의 다양한 도메인 데이터베이스 ( [spider dataset](https://yale-lily.github.io/spider) ) |
|
|
- **학습 방법**: LoRA (r=16, alpha=32) |
|
|
|
|
|
## 💬 활용 예시 |
|
|
|
|
|
### 기본 사용법 |
|
|
|
|
|
```python |
|
|
def generate_sql(question, schema_info): |
|
|
"""한국어 질문을 SQL로 변환""" |
|
|
prompt = f"""다음 데이터베이스 스키마를 참고하여 질문에 대한 SQL 쿼리를 생성하세요. |
|
|
|
|
|
### 데이터베이스 스키마: |
|
|
{schema_info} |
|
|
|
|
|
### 질문: {question} |
|
|
|
|
|
### SQL 쿼리:""" |
|
|
|
|
|
messages = [{"role": "user", "content": prompt}] |
|
|
inputs = tokenizer.apply_chat_template(messages, tokenize=True, add_generation_prompt=True, return_tensors="pt") |
|
|
|
|
|
outputs = model.generate(inputs, max_new_tokens=150, temperature=0.1) |
|
|
response = tokenizer.decode(outputs[0], skip_special_tokens=True) |
|
|
|
|
|
return response.split("### SQL 쿼리:")[-1].strip() |
|
|
``` |
|
|
|
|
|
### 실제 사용 예시 |
|
|
|
|
|
```python |
|
|
# 예시 1: 집계 함수 |
|
|
question = "부서장들 중 56세보다 나이가 많은 사람이 몇 명입니까?" |
|
|
# 결과: SELECT count(*) FROM head WHERE age > 56 |
|
|
|
|
|
# 예시 2: 조인 |
|
|
question = "가장 많은 대회를 개최한 도시의 상태는 무엇인가요?" |
|
|
# 결과: SELECT T1.Status FROM city AS T1 JOIN farm_competition AS T2 ON T1.City_ID = T2.Host_city_ID GROUP BY T2.Host_city_ID ORDER BY COUNT(*) DESC LIMIT 1 |
|
|
|
|
|
# 예시 3: 서브쿼리 |
|
|
question = "기업가가 아닌 사람들의 이름은 무엇입니까?" |
|
|
# 결과: SELECT Name FROM people WHERE People_ID NOT IN (SELECT People_ID FROM entrepreneur) |
|
|
``` |
|
|
|
|
|
## ⚠️ 사용 시 주의사항 |
|
|
|
|
|
### 제한사항 |
|
|
- ✅ 영어 테이블/컬럼명 사용 (한국어 질문 → 영어 SQL) |
|
|
- ✅ Spider 데이터셋 도메인에 최적화 |
|
|
- ❌ NoSQL, 그래프 DB 미지원 |
|
|
- ❌ 매우 복잡한 중첩 쿼리는 정확도 하락 |
|
|
|
|
|
## 🔧 기술 사양 |
|
|
|
|
|
### 학습 환경 |
|
|
- **GPU**: NVIDIA Tesla T4 (16GB) |
|
|
- **학습 시간**: 약 4시간 |
|
|
- **메모리 사용**: 최대 7.6GB VRAM |
|
|
|
|
|
### 하이퍼파라미터 |
|
|
```python |
|
|
training_args = { |
|
|
"per_device_train_batch_size": 2, |
|
|
"gradient_accumulation_steps": 4, |
|
|
"learning_rate": 5e-4, |
|
|
"num_train_epochs": 1, |
|
|
"optimizer": "adamw_8bit", |
|
|
"lr_scheduler_type": "cosine", |
|
|
"warmup_ratio": 0.05 |
|
|
} |
|
|
|
|
|
lora_config = { |
|
|
"r": 16, |
|
|
"lora_alpha": 32, |
|
|
"lora_dropout": 0, |
|
|
"target_modules": ["q_proj", "k_proj", "v_proj", "o_proj", |
|
|
"gate_proj", "up_proj", "down_proj"] |
|
|
} |
|
|
``` |
|
|
|
|
|
## 📚 참고 자료 |
|
|
|
|
|
### 인용 |
|
|
```bibtex |
|
|
@misc{llama31_spider_sql_ko_2025, |
|
|
title={Llama-3.1-8B-Spider-SQL-Ko: Korean Text-to-SQL Model}, |
|
|
author={[Sohyun Sim, Youngjun Cho, Seongwoo Choi]}, |
|
|
year={2025}, |
|
|
publisher={Hugging Face KREW}, |
|
|
url={https://huggingface.co/huggingface-KREW/Llama-3.1-8B-Spider-SQL-Ko} |
|
|
} |
|
|
``` |
|
|
|
|
|
### 관련 논문 |
|
|
- [Spider: A Large-Scale Human-Labeled Dataset](https://arxiv.org/abs/1809.08887) (Yu et al., 2018) |
|
|
|
|
|
## 🤝 기여자 |
|
|
|
|
|
[@sim-so](https://huggingface.co/sim-so), [@choincnp](https://huggingface.co/choincnp), [@nuatmochoi](https://huggingface.co/nuatmochoi) |
|
|
|
