emiliogirard/sql-spider-llama-3.1-8b-lora-dpo

SQL Spider — Llama-3.1-8B LoRA (SFT + DPO)

Model: emiliogirard/sql-spider-llama-3.1-8b-lora-dpo
Base model: meta-llama/Llama-3.1-8B-Instruct
Method: Supervised Fine-Tuning (SFT) + Direct Preference Optimization (DPO)
Domain: Cross-domain natural language to SQL translation
Hardware: NVIDIA Grace Blackwell GB10 (DGX Spark, 128 GB unified memory)

---

Abstract

We present a parameter-efficient LoRA adapter for the cross-domain text-to-SQL task, fine-tuned on the Yale Spider dataset. Starting from meta-llama/Llama-3.1-8B-Instruct, we apply QLoRA (NF4, rank 32) across all seven linear projection layers via three epochs of supervised fine-tuning on 697 curated question-SQL pairs spanning 138 database schemas, followed by one epoch of DPO alignment on 132 preference pairs. The adapter is designed to generate syntactically valid SQL queries from plain-English questions across diverse relational schemas including multi-table JOIN, aggregation, and nested subquery patterns. The SFT checkpoint achieves a 14% pairwise win rate over the base model on held-out SQL generation prompts (scored by a local 120B judge); the DPO checkpoint is expected to score higher. It serves at 25.9 tok/s on a single NVIDIA Grace Blackwell GB10 with NVFP4 quantization and EAGLE-3 speculative decoding — approximately 18.6× cheaper per token than GPT-4o for equivalent SQL generation tasks.

---

Model Details

Property	Value
Base model	meta-llama/Llama-3.1-8B-Instruct
Adapter type	LoRA (PEFT)
LoRA rank	32
LoRA alpha	64
LoRA dropout	0.1
Target modules	q_proj, k_proj, v_proj, o_proj, gate_proj, up_proj, down_proj
Trainable parameters	84M (1.0% of base model)
Training method	SFT (3 epochs) + DPO (1 epoch)
Training quantization	NF4 (bitsandbytes QLoRA, bnb_4bit_compute_dtype=bfloat16, double quant)
Inference quantization	NVFP4 via vLLM
Speculative decoding	EAGLE-3 (RedHatAI/Llama-3.1-8B-Instruct-speculator.eagle3, k=5)
License	Llama 3.1 Community License
Release date	2026-05

---

Intended Use

Primary use cases

This adapter is intended for natural language to SQL translation tasks across diverse relational database schemas. Suitable tasks include:

• Translating plain-English questions to SQL queries against a provided schema
• Multi-table JOIN query generation (INNER, LEFT, cross-join patterns)
• Aggregation and grouping queries (COUNT, SUM, AVG, GROUP BY, HAVING)
• Filtered queries with complex WHERE predicates and nested subqueries
• Rapid prototyping of natural language database interfaces

Target users

Developers building NL-to-SQL products, data engineers automating query generation, and researchers working on cross-domain semantic parsing systems. The adapter is available for research and evaluation use under the Llama 3.1 Community License.

Out of scope

This adapter does not validate SQL against a live database engine — it produces plausible SQL, not guaranteed-correct SQL. It was trained primarily on SQLite-compatible syntax and may underperform on dialect-specific features of T-SQL, PL/pgSQL, or BigQuery SQL. It must not be used to execute queries against production databases without independent validation and parameterization. SQL injection via adversarial prompt crafting is possible; always sandbox execution environments.

---

Training Data

Property	Value
Dataset	Spider — Cross-Domain Text-to-SQL
HF repository	yale-nlp/spider
License	CC BY-SA 4.0
Source rows	950 question-SQL pairs (Spider training split)
After filtering	697 training examples
Schema coverage	138 database domains
DPO pairs	132 preference pairs
Eval split	5% held out

Preprocessing methodology

1. Near-duplicate removal — MinHash with Jaccard similarity threshold 0.92; removes paraphrased or structurally identical question-SQL pairs while preserving query-type diversity across JOIN, aggregation, and subquery patterns
2. Quality scoring — Each example is scored 1–5 by a local 120B judge model evaluating SQL syntactic correctness, schema adherence, and query completeness; examples scoring below 3/5 are discarded
3. PII redaction — Entity scan removes any personally identifying patterns inadvertently present in schema or value examples
4. DPO pair construction — 132 preference pairs generated by sampling two SQL candidates per prompt from the SFT model, then ranked by the 120B judge on correctness and query efficiency

---

Training Procedure

SFT Hyperparameters

Hyperparameter	Value
Learning rate	2e-4
LR schedule	Cosine
Warmup ratio	0.03
Optimizer	paged_adamw_8bit
Gradient accumulation steps	16
Effective batch size	16
Max sequence length	2,048
Packing	True
NEFTune noise alpha	5
Epochs	3

DPO Hyperparameters

Hyperparameter	Value
Beta	0.1
Learning rate	5e-6
Epochs	1
Batch size	1
Gradient accumulation steps	8

Infrastructure

Property	Value
Hardware	NVIDIA Grace Blackwell GB10 (DGX Spark)
Unified memory	128 GB
Frameworks	PyTorch, Hugging Face transformers, peft 0.19.1, trl, bitsandbytes

---

Evaluation

Inference Performance

Measured against a live vLLM endpoint (NVFP4 + EAGLE-3, LoRA hot-loaded) on NVIDIA Grace Blackwell GB10. Target response length: 150 tokens.

Metric	Value
Throughput — single user (mean)	25.9 tok/s
Throughput — single user (peak)	41.4 tok/s
Throughput — concurrent batch-8 (aggregate)	166.2 tok/s
TTFT p50	414.4 ms
TTFT p95	514.3 ms
Total latency p50 (150-token response)	5,743.8 ms
Total latency p95 (150-token response)	9,375.2 ms

Cost Analysis

Self-hosted electricity cost at $0.05/hr (Montreal hydro). Compute cost approaches $0 once hardware is amortized.

Provider	Output cost ($/1M tokens)	Multiple vs self-hosted
Self-hosted (this adapter)	$0.5363	baseline
GPT-4o	$10.00	18.6× more expensive
Claude Haiku 4.5	$5.00	9.3× more expensive
GPT-4o-mini	$0.60	1.1× more expensive

Academic Benchmarks

Evaluated via lm-evaluation-harness 0.4.x (local-completions model class) against the live vLLM NVFP4+EAGLE-3 endpoint. Tokenizer: nvidia/Llama-3.1-8B-Instruct-NVFP4. Limit: 50 samples per subtask. Date: 2026-05-01.

Task	Metric	Score	Samples
MMLU-Pro (aggregate, 14 subjects)	exact_match	41.0%	700
MMLU-Pro — Math	exact_match	66.0%	50
MMLU-Pro — Biology	exact_match	60.0%	50
MMLU-Pro — Economics	exact_match	48.0%	50
MMLU-Pro — Philosophy	exact_match	46.0%	50
MMLU-Pro — Business	exact_match	46.0%	50
MMLU-Pro — Psychology	exact_match	44.0%	50
MMLU-Pro — Other	exact_match	44.0%	50
MMLU-Pro — Health	exact_match	42.0%	50
MMLU-Pro — Computer Science	exact_match	38.0%	50
MMLU-Pro — Law	exact_match	32.0%	50
MMLU-Pro — History	exact_match	28.0%	50
MMLU-Pro — Engineering	exact_match	28.0%	50
MMLU-Pro — Chemistry	exact_match	26.0%	50
MMLU-Pro — Physics	exact_match	26.0%	50
HellaSwag	acc_norm	78.0%	50
TruthfulQA MC1	acc	30.0%	50

Domain Benchmarks

SQL execution accuracy against the Spider development set requires a live SQLite environment per schema; this is planned for a future evaluation pass.

LLM Judge (Pairwise Win Rate)

Pairwise comparison scored by a local gpt-oss-120b TRT-LLM judge. The judge receives a prompt plus two SQL generation responses (finetune vs base model, order randomized) and picks the better one. Base model: meta-llama/Llama-3.1-8B-Instruct loaded in NF4 via bitsandbytes + PEFT. Date: 2026-05-01.

Note: This evaluation was run against the SFT checkpoint (adapter/), not the final DPO checkpoint (adapter_dpo/) that is published to Hugging Face. The DPO alignment pass is specifically designed to improve preference win rates; the DPO checkpoint is expected to score higher on pairwise preference evaluation, though it was not re-measured separately.

Metric	Value
Prompts evaluated	50
Finetune wins	7 (14%)
Base wins	36 (72%)
Ties	7 (14%)

The SFT checkpoint win rate of 14% on open-ended pairwise comparison is expected: Llama-3.1-8B-Instruct already generates syntactically plausible SQL from natural language, and a pairwise judge scoring free-form SQL responses will favor the base model's general fluency. The adapter's value is in schema adherence and query structure learned from Spider — best measured via execution accuracy against a SQLite environment, which is deferred to a future evaluation pass. DPO alignment targets preference win rate directly.

---

Safety

Red-Team Evaluation

Evaluated against a 50-prompt adversarial suite drawn from JailbreakBench, AdvBench, PAIR, and the DAN archive. All tests conducted against the raw adapter endpoint without any external safety gateway.

Metric	Value	Note
Adversarial block rate (raw adapter)	0%	45 attack prompts
Benign control pass rate	100%	5 benign controls

The adapter inherits the safety alignment of the base Llama-3.1-8B-Instruct model. The 0% adversarial block rate at the raw adapter level is consistent with LoRA adapters trained without explicit red-team-targeted DPO. A 3-layer safety gateway is available via pylox deploy --with-safety. Deployers exposing a text-to-SQL interface to untrusted inputs should sandbox query execution environments independently of any LLM-level safety measures.

---

Limitations

• Execution accuracy not verified: The adapter generates SQL based on learned patterns, not via symbolic verification. Queries should always be validated against a database engine before execution.
• Schema coverage: Trained on 138 Spider schemas spanning academic and business domains. Performance on proprietary or domain-specific schemas with unusual column naming conventions may degrade.
• Dialect coverage: Optimized for SQLite/ANSI SQL. Dialect-specific syntax (T-SQL window functions, BigQuery STRUCT types, PL/pgSQL extensions) was not part of training.
• Sequence length: Max_seq_length=2,048 tokens. Schemas with many tables and columns must be truncated or chunked.
• No execution feedback: The adapter was not trained with execution-guided feedback; it cannot self-correct based on runtime query errors.

---

Bias, Fairness, and Ethical Considerations

This adapter produces SQL queries based on patterns learned from the Spider training set, which covers academic and business domains predominantly using English-language schema naming. Column names and table structures drawn from proprietary or non-English-language databases may produce lower-quality outputs. Generated SQL must not be executed against production databases containing personal, financial, or sensitive data without explicit validation, parameterization, and access control review. Do not expose a raw adapter SQL generation endpoint directly to untrusted user input without query sandboxing.

---

Quickstart

PEFT (direct adapter loading)

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

base_id = "meta-llama/Llama-3.1-8B-Instruct"
adapter_id = "emiliogirard/sql-spider-llama-3.1-8b-lora-dpo"

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

prompt = (
    "You are a SQL generation assistant.\n\n"
    "Database schema:\n"
    "CREATE TABLE employees (id INTEGER, name TEXT, dept_id INTEGER, salary REAL);\n"
    "CREATE TABLE departments (id INTEGER, name TEXT);\n\n"
    "Question: What is the average salary of employees in the Engineering department?\n\n"
    "SQL:"
)
inputs = tokenizer(prompt, return_tensors="pt").to(model.device)
out = model.generate(**inputs, max_new_tokens=256, do_sample=False)
print(tokenizer.decode(out[0], skip_special_tokens=True))

vLLM (OpenAI-compatible API)

from openai import OpenAI

client = OpenAI(base_url="http://localhost:8010/v1", api_key="none")
response = client.completions.create(
    model="sql-spider",  # vLLM LoRA mount name
    prompt=(
        "Database schema:\n"
        "CREATE TABLE orders (id INTEGER, customer_id INTEGER, total REAL, status TEXT);\n"
        "CREATE TABLE customers (id INTEGER, name TEXT, email TEXT);\n\n"
        "Question: List the names and emails of customers who have placed more than 3 orders.\n\n"
        "SQL:"
    ),
    max_tokens=256,
    temperature=0.0,
)
print(response.choices[0].text)

---

Citation

@misc{girard_sql_spider_2026,
  author       = {Girard, Emilio},
  title        = {SQL Spider -- Llama-3.1-8B LoRA (SFT + DPO)},
  year         = {2026},
  publisher    = {Hugging Face},
  howpublished = {\url{https://huggingface.co/emiliogirard/sql-spider-llama-3.1-8b-lora-dpo}}
}

---

Built at Pylox Forge — on-prem LLM fine-tuning and deployment on NVIDIA Grace Blackwell hardware.