README.md

metadata

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 train 데이터셋을 한국어로 번역한 spider-ko 데이터셋을 활용하여 미세조정하였습니다.

📊 주요 성능

Spider 한국어 검증 데이터셋(1,034개) 평가 결과:

• 정확 일치율: 42.65% (441/1034)
• 실행 정확도: 65.47% (677/1034)

💡 실행 정확도가 정확 일치율보다 높은 이유는, SQL 문법이 다르더라도 동일한 결과를 반환하는 경우가 많기 때문입니다.

🚀 바로 시작하기

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 (1-epoch)
• 지원 DB: 166개의 다양한 도메인 데이터베이스 ( spider dataset )
• 학습 방법: LoRA (r=16, alpha=32)

💬 활용 예시

기본 사용법

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()

실제 사용 예시

# 예시 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

하이퍼파라미터

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"]
}

📚 참고 자료

인용

@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 (Yu et al., 2018)

🤝 기여자

@sim-so, @choincnp, @nuatmochoi