Hugging Face's logo

huggingface-KREW
/
Llama-3.1-8B-Spider-SQL-Ko

Table Question Answering
Safetensors
Korean
text2sql
spider
korean
llama
text-generation
Eval Results
Model card Files
xet
Community
Llama-3.1-8B-Spider-SQL-Ko
File size: 4,991 Bytes 
4efa655
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
a15a665
 
4efa655
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
2b5dfe5
4efa655
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
 
---
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)