ri7elyass/qwen2.5-coder-text2sql

Model Card for Qwen2.5-Coder Text-to-SQL (LoRA)

Fine-tuning di Qwen2.5-Coder-1.5B-Instruct per generare query SQL a partire da domande in linguaggio naturale, dato lo schema di un database.

Model Details

Model Description

Questo modello è un adapter LoRA che estende Qwen2.5-Coder-1.5B-Instruct con la capacità di tradurre domande in linguaggio naturale in query SQL eseguibili, dato lo schema del database come contesto nel prompt.

• Developed by: Elyass Rochdi
• Model type: Causal Language Model (decoder-only Transformer) con adapter LoRA
• Language(s) (NLP): Inglese
• License: Apache 2.0
• Finetuned from model: Qwen/Qwen2.5-Coder-1.5B-Instruct

Model Sources

• Repository: https://huggingface.co/ri7elyass/qwen2.5-coder-text2sql

Uses

Direct Use

Generazione di query SQL a partire da una domanda in linguaggio naturale e uno schema di database fornito nel prompt. Pensato per prototipi di interfacce "chiedi al database in linguaggio naturale" e per scopi di portfolio/dimostrativi.

Out-of-Scope Use

Non pensato per essere usato in produzione senza validazione delle query generate (es. controllo sintattico, sandboxing dell'esecuzione). Non gestisce in modo affidabile query SQL molto complesse (subquery annidate multiple, window functions avanzate) o schemi molto diversi da quelli visti nel dataset Spider.

Bias, Risks, and Limitations

Il modello è stato fine-tuned solo su Spider, un dataset generalista in inglese — su schemi di dominio molto specifico o in altre lingue le prestazioni possono degradare. Essendo stato allenato per 1 sola epoca, c'è margine di miglioramento. Come ogni sistema Text-to-SQL, le query generate vanno validate prima dell'esecuzione su dati reali (rischio di query errate o, in contesti non controllati, potenzialmente dannose).

Recommendations

Validare sempre la query generata (sintassi + logica) prima di eseguirla su un database reale, specialmente in contesti con permessi di scrittura.

How to Get Started with the Model

from transformers import AutoModelForCausalLM, AutoTokenizer
from peft import PeftModel
import torch

base_model = "Qwen/Qwen2.5-Coder-1.5B-Instruct"
adapter = "ri7elyass/qwen2.5-coder-text2sql"

tokenizer = AutoTokenizer.from_pretrained(base_model)
model = AutoModelForCausalLM.from_pretrained(base_model, torch_dtype=torch.bfloat16, device_map="auto")
model = PeftModel.from_pretrained(model, adapter)

prompt = """Schema: singer : Singer_ID (number), Name (text), Country (text)
Domanda: How many singers are there?
SQL:"""

inputs = tokenizer(prompt, return_tensors="pt").to(model.device)
outputs = model.generate(**inputs, max_new_tokens=100, do_sample=False, pad_token_id=tokenizer.eos_token_id)
print(tokenizer.decode(outputs[0][inputs["input_ids"].shape[1]:], skip_special_tokens=True))

Training Details

Training Data

Spider — dataset Text-to-SQL con 7.000 esempi domanda→query su 166 database diversi. Schema dei database ottenuto da richardr1126/spider-schema.

Training Procedure

Ogni esempio è stato costruito concatenando schema del DB (formato testuale) + domanda come prompt, con la query SQL come completion target. Loss calcolata solo sui token della completion (loss masking sul prompt).

Preprocessing

Tokenizzazione con il tokenizer nativo di Qwen2.5-Coder, troncamento a 512 token, padding dinamico per batch.

Training Hyperparameters

• Training regime: bf16 mixed precision, base model quantizzato in 4-bit (QLoRA, NF4)
• LoRA config: r=8, lora_alpha=16, target_modules=["q_proj", "v_proj"], lora_dropout=0.05
• Batch size: 4 per device, gradient accumulation 4 (batch effettivo 16)
• Epochs: 1
• Learning rate: 2e-4

Speeds, Sizes, Times

• Hardware: GPU T4 (Google Colab, free tier)
• Training time: ~3h10
• Adapter size: ~4.4MB (solo i pesi LoRA)

Evaluation

Testing Data, Factors & Metrics

Testing Data

Split di validation di Spider (1.034 esempi, database mai visti durante il training).

Metrics

Loss (cross-entropy) e ispezione qualitativa delle query generate (correttezza semantica, non solo match testuale esatto).

Results

• Training loss finale: ~0.18 (partita da ~0.49 al primo logging step)
• Esempio qualitativo — Domanda: "Show all countries and the number of singers in each country." → SQL generato: SELECT count(*), country FROM singer GROUP BY country (semanticamente equivalente al ground truth, con solo l'ordine delle colonne diverso)

Technical Specifications

Model Architecture and Objective

Architettura Transformer decoder-only (Qwen2.5-Coder-1.5B), con adapter LoRA applicati alle proiezioni Query e Value dell'attention, in ogni layer. Obiettivo: causal language modeling, con loss calcolata solo sui token della query SQL target.

Compute Infrastructure

Hardware

1x NVIDIA Tesla T4 (16GB VRAM)

Software

• transformers
• peft
• bitsandbytes (quantizzazione 4-bit)
• datasets

Model Card Authors

Elyass Rochdi

Model Card Contact

huggingface.co/ri7elyass