Practical LLM Fine-Tuning — Unsloth, LoRA & the Modern Stack

# ═══════════════════════════════════════════════════════════
# Complete SFT (Supervised Fine-Tuning) workflow with Unsloth
# Based on patterns from the Granite/Qwen/Llama notebooks
# Runs on free Google Colab T4 (16GB VRAM)
# ═══════════════════════════════════════════════════════════

# Step 0: Install
# pip install unsloth trl transformers datasets bitsandbytes

from unsloth import FastLanguageModel
from trl import SFTTrainer, SFTConfig
from datasets import load_dataset, Dataset
import torch

# ── Step 1: Load model with automatic optimisations ──
model, tokenizer = FastLanguageModel.from_pretrained(
    model_name     = "unsloth/Llama-3.2-1B-Instruct",  # or Qwen3, Granite4 etc.
    max_seq_length = 2048,        # Max tokens per example
    dtype          = None,        # Auto-detect: BF16 on Ampere+, FP16 on older
    load_in_4bit   = True,        # 4-bit quantisation: 7B uses ~4GB VRAM instead of 14GB
)

# ── Step 2: Add LoRA adapters ──
model = FastLanguageModel.get_peft_model(
    model,
    r=16,               # LoRA rank. 8-64 common. Higher = more params = more capacity
    lora_alpha=16,      # Scaling factor = lora_alpha/r. Often set equal to r.
    lora_dropout=0.0,   # 0 works well for LoRA (unlike vanilla dropout)
    bias="none",        # Recommended: no bias in LoRA layers
    target_modules=[    # Which attention/MLP matrices to add LoRA to
        "q_proj", "k_proj", "v_proj", "o_proj",   # Attention matrices
        "gate_proj", "up_proj", "down_proj",       # MLP matrices
    ],
    use_gradient_checkpointing="unsloth",  # Saves VRAM at cost of slight speed
)

# Show trainable parameter count
model.print_trainable_parameters()
# trainable params: 27,262,976 / 1,235,814,400 = 2.21% (for 1B model)

# ── Step 3: Prepare dataset with chat template ──
# Use standard chat format that matches the model's instruction template
train_data = [
    {
        "messages": [
            {"role": "system",    "content": "You are a helpful SQL expert."},
            {"role": "user",      "content": "How do I get the top 10 customers by revenue?"},
            {"role": "assistant", "content": "Use ORDER BY with LIMIT:

SELECT customer_id, SUM(amount) AS revenue
FROM orders
GROUP BY customer_id
ORDER BY revenue DESC
LIMIT 10;"},
        ]
    },
    # Add thousands more examples...
]
dataset = Dataset.from_list(train_data)

# Apply chat template to format as model expects
def format_chat(example):
    text = tokenizer.apply_chat_template(
        example["messages"],
        tokenize=False,
        add_generation_prompt=False
    )
    return {"text": text}

dataset = dataset.map(format_chat)

# ── Step 4: Configure and run SFT trainer ──
sft_config = SFTConfig(
    output_dir             = "./sft_output",
    dataset_text_field     = "text",
    max_seq_length         = 2048,
    num_train_epochs       = 3,
    per_device_train_batch_size = 2,
    gradient_accumulation_steps = 4,   # Effective batch = 2 × 4 = 8
    warmup_steps           = 10,
    learning_rate          = 2e-4,     # Higher LR for LoRA vs full FT
    weight_decay           = 0.01,
    lr_scheduler_type      = "cosine",
    bf16                   = True,     # BF16 compute (auto on Ampere+)
    fp16                   = False,
    logging_steps          = 10,
    save_steps             = 100,
    report_to              = "none",   # "tensorboard" or "wandb" for tracking
)

trainer = SFTTrainer(
    model         = model,
    tokenizer     = tokenizer,
    train_dataset = dataset,
    args          = sft_config,
)

# ── Step 5: Train ──
trainer.train()

# ── Step 6: Save and use the fine-tuned model ──
# Save LoRA adapters only (tiny: ~50MB for 7B model)
model.save_pretrained("./lora_adapters")
tokenizer.save_pretrained("./lora_adapters")

# For GGUF/Ollama deployment (quantise for local inference)
model.save_pretrained_gguf("./gguf_model", tokenizer,
    quantization_method="q4_k_m")   # 4-bit quantisation for CPU inference

# ── Step 7: Inference with the fine-tuned model ──
FastLanguageModel.for_inference(model)   # Enable 2× faster inference mode
inputs = tokenizer([
    tokenizer.apply_chat_template([
        {"role": "user", "content": "How do I join two tables in SQL?"}
    ], tokenize=False, add_generation_prompt=True)
], return_tensors="pt").to("cuda")

outputs = model.generate(**inputs, max_new_tokens=200, temperature=0.7)
print(tokenizer.decode(outputs[0], skip_special_tokens=True))

# Based on Qwen3_5__2B__Vision.ipynb and Qwen3_5__4B__Vision.ipynb notebooks
# Fine-tuning a vision-language model (VLM) on image+text tasks

from unsloth import FastVisionModel   # Vision-specific fast loading

model, tokenizer = FastVisionModel.from_pretrained(
    model_name   = "unsloth/Qwen2-VL-2B-Instruct",  # 2B vision-language model
    max_seq_length = 2048,
    dtype          = None,
    load_in_4bit   = True,
)

# Enable only text weights for faster fine-tuning (keep vision encoder frozen)
model = FastVisionModel.get_peft_model(
    model,
    finetune_vision_layers = True,    # Train vision encoder too?
    finetune_language_layers = True,  # Train language decoder
    finetune_attention_modules = True,
    finetune_mlp_modules = True,
    r=16, lora_alpha=16,
)

# Vision training dataset format
vision_data = [
    {
        "messages": [
            {
                "role": "user",
                "content": [
                    {"type": "image", "image": "path/to/invoice.jpg"},
                    {"type": "text",  "text": "Extract all line items and totals from this invoice."}
                ]
            },
            {
                "role": "assistant",
                "content": "Line Items:
1. Product A: $50.00
2. Service B: $120.00
Total: $170.00"
            }
        ]
    }
]
# Use cases: document OCR, chart understanding, medical imaging, receipt extraction