Model Card: Llama-3.2-3B-Korean-NL2SQL (Merged)

본 모델은 Meta의 Llama-3.2-3B-Instruct 모델을 베이스로 하여, 실무용 PostgreSQL 환경에서 한국어 질의를 고정밀 SQL 쿼리로 변환(NL2SQL)할 수 있도록 파인튜닝 및 가중치 병합(Weight Merge)을 완료한 경량 특화 모델입니다.

3B라는 소형 체급임에도 불구하고, 에러 피드백을 기반으로 한 재귀적 자가 수정 에이전트 환경에서 22.73%라는 높은 복구 성공률을 기록하며 뛰어난 유연성과 비용 효율성(Cost-Efficiency)을 증명한 모델입니다.

🌟 주요 특징 (Key Features)

• 초경량·고효율 엔지니어링: 3B 파라미터 사이즈로 VRAM 소모를 최소화하여, 사양이 제한된 엣지 서버나 로컬 환경에서도 대규모 인프라 부담 없이 고속 추론 및 서빙이 가능합니다.
• 높은 회복 탄력성 (High Resilience): 최초 생성에서 문법적 실수가 발생하더라도, 데이터베이스 에러 로그를 주입했을 때 문맥을 파악하여 올바른 쿼리로 고쳐 쓰는 디버깅 능력이 체급 대비 매우 탁월합니다.
• 실무형 PostgreSQL 매핑: 소형 모델이 흔히 범하기 쉬운 문법적 비약을 억제하고, PostgreSQL 규격에 맞는 안정적인 쿼리 패턴을 구사하도록 튜닝되었습니다.

📊 성능 평가 요약 (Evaluation Results)

실무용 ERP 데이터베이스 스키마와 난이도별(Level 1 ~ 5) 평가 데이터셋 400문항을 바탕으로 엄밀하게 측정한 벤치마크 결과입니다.

Difficulty	Pure Acc	Final Acc	Errors	Repaired	Repair Rate
Level 1	92.50%	92.50%	1	0	0.00%
Level 2	85.00%	87.50%	5	2	40.00%
Level 3	76.25%	78.75%	3	2	66.67%
Level 4	60.00%	61.25%	6	1	16.67%
Level 5	53.75%	53.75%	7	0	0.00%
TOTAL	73.50%	74.75%	22	5	22.73%

• Pure Accuracy: 최초 1회 생성 시의 SQL 실행 결과 정답률은 **73.50%**입니다.
• 에이전트 자가 수정 기여도: 1차 생성에서 에러가 발생한 22건 중 5건을 스스로 완벽히 수리(Repair Success Rate: 22.73%)해내며, 최종 정답률을 **74.75%**까지 끌어올렸습니다. 특히 중간 난이도(Level 2, 3)에서 최대 66.67%의 고효율 복구 성능을 입증했습니다.

💻 사용 방법 (How to Use)

Llama-3.2의 공식 Chat Template 규격을 준수하여 로컬 환경에서 추론하는 예시 코드입니다.

import torch
from transformers import AutoTokenizer, AutoModelForCausalLM

model_id = "yeongseok11/Llama-3.2-3B-korean-nl2sql"

tokenizer = AutoTokenizer.from_pretrained(model_id)
model = AutoModelForCausalLM.from_pretrained(
    model_id,
    torch_dtype=torch.bfloat16,
    device_map="auto"
)
model.eval()

# Prompt Template (Llama-3.2 전용 템플릿 준수)
prompt = """<|begin_of_text|><|start_header_id|>system<|end_header_id|>

당신은 실무용 PostgreSQL 전문가입니다. 오직 SQL 쿼리만 답변하세요.<|eot_id|><|start_header_id|>user<|end_header_id|>

### 스키마:
CREATE TABLE emp (
    emp_id INT PRIMARY KEY,
    emp_name VARCHAR(50),
    dept_id INT,
    salary INT
);

### 질문:
기획팀(dept_id = 10) 직원들의 평균 급여를 구하는 쿼리를 짜줘.<|eot_id|><|start_header_id|>assistant<|end_header_id|>

### SQL:
"""

inputs = tokenizer(prompt, return_tensors="pt").to("cuda")
with torch.no_grad():
    outputs = model.generate(
        **inputs,
        max_new_tokens=256,
        temperature=0.0,
        do_sample=False,
        pad_token_id=tokenizer.eos_token_id
    )

print(tokenizer.decode(outputs[0], skip_special_tokens=True).split("### SQL:\n")[-1])

📝 연구 및 한계점 (Limitations & Future Work)
본 모델은 경량화 모델로서 뛰어난 유연성을 갖추고 있으나, 초고난도(Level 5)의 복잡한 다중 조인 제약 조건 환경에서는 모델 체급 한계로 인한 의미론적 한계를 일부 보입니다.
 이를 보완하기 위해 향후 연구는 기저 인프라 단에서 스키마 정보를 LLM 지향적으로 가공해 주는 AI 친화적 메타데이터 자동 관리 파이프라인(AI-Friendly Metadata Enrichment) 체계와의 결합을 목표로 하고 있습니다.