text2sql-7b-v3-16

Model Details

text2sql-7b-v3-16 is an 8B-parameter causal language model fine-tuned for text-to-SQL generation. It accepts a natural-language question plus schema context and returns SQL inside the notebook's required answer format.

• Model type: causal language model, text generation
• Primary task: text-to-SQL
• Base model family: Arctic-Text2SQL-R1-7B
• Output format: <think>...</think><answer>SQL</answer>
• Tensor format: Safetensors
• Precision: BF16
• Fine-tuning method: PEFT LoRA adapters merged into the final model artifact
• Final artifact path used locally: outputs/text2sql-7b-v3-16/merged-text2sql-7b-v3-16

Intended Technical Use

Use this model to generate PostgreSQL-style SQL from a natural-language question and schema description. The fine-tuning set contains both plain SQL examples and pgvector retrieval examples using embed_query() with vector-distance operators.

This model is not a SQL execution engine. Generated SQL should be parsed, reviewed, and run in a controlled environment before use.

How to Use

import torch
from transformers import AutoModelForCausalLM, AutoTokenizer

model_id = "ihebaker10/text2sql-7b-v3-16"

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

messages = [
    {
        "role": "system",
        "content": "Generate SQL. Return the final SQL inside <answer>...</answer>.",
    },
    {
        "role": "user",
        "content": "Schema:\n...\n\nQuestion:\nList the latest 10 records.",
    },
]

prompt = tokenizer.apply_chat_template(
    messages,
    tokenize=False,
    add_generation_prompt=True,
)
inputs = tokenizer(prompt, return_tensors="pt").to(model.device)

with torch.no_grad():
    outputs = model.generate(
        **inputs,
        max_new_tokens=768,
        temperature=0.2,
        top_p=0.95,
        do_sample=False,
    )

print(tokenizer.decode(outputs[0], skip_special_tokens=True))

Training Data

The training data contains 10,000 text-to-SQL examples loaded from a MongoDB collection and split into 9,001 training examples and 999 validation examples.

Each record contains an identifier, is_sql_only, natural-language question, reference SQL query, reasoning hint, schema text, table list, and version.

Training Procedure

Training used a three-stage PEFT workflow:

The LoRA adapter was merged into the base weights before publishing the final Safetensors artifact.

Hyperparameters

LoRA configuration:

Reward Functions

Stage 2 used the following reward checks:

• format_reward: validates the <think> and <answer> response structure.
• sql_syntax_reward: rewards SQL that parses successfully.
• pgvector_usage_reward: checks whether embed_query() is used only when expected.
• execution_reward: optionally compares generated SQL results with reference SQL when DB_URL is configured.

Evaluation

Positive class for precision, recall, and F1 is pgvector usage, meaning the generated SQL contains embed_query().

Stage eval losses:

Detailed pgvector decision metrics from the saved final merged-model evaluation:

Detailed saved stage metrics:

Limitations

• SQL should be validated before execution.
• Exact-match SQL is strict and may undercount semantically equivalent queries.
• pgvector recall on the validation split is lower than precision, so some retrieval-style prompts may be answered as plain SQL.
• Execution-based reward depends on DB_URL; without it, training optimizes formatting, SQL syntax, and pgvector usage only.

Technical Environment

• Frameworks: transformers, peft, trl, datasets, torch
• Attention implementation: sdpa
• Gradient checkpointing: enabled
• CUDA memory fraction in notebook: 0.98
• TF32 matmul: enabled
• TensorBoard logging: enabled for all training stages

Environmental Impact

Carbon emissions were not measured. Recorded training runtimes were approximately:

Total recorded training runtime was approximately 14.3 hours on a local CUDA GPU.