Here's a complete, step-by-step fine-tuning workflow for a SQL generation task.

Step 1: Install Dependencies

pip install mlx-lm datasets huggingface_hub

Step 2: Prepare Training Data

# prepare_data.py
import json, os
from datasets import load_dataset

os.makedirs("./data", exist_ok=True)

system_msg = """You are a text-to-SQL translator. Generate a SQL query
based on the provided SCHEMA.
SCHEMA: {schema}"""

def create_conversation(sample):
    return {"messages": [
        {"role": "system", "content": system_msg.format(schema=sample["context"])},
        {"role": "user", "content": sample["question"]},
        {"role": "assistant", "content": sample["answer"]}
    ]}

dataset = load_dataset("b-mc2/sql-create-context", split="train")
dataset = dataset.shuffle(seed=42).select(range(1000))
dataset = dataset.map(create_conversation, remove_columns=dataset.column_names)

split1 = dataset.train_test_split(test_size=0.2, seed=42)
split2 = split1["test"].train_test_split(test_size=0.5, seed=42)

split1["train"].to_json("./data/train.jsonl", orient="records", lines=True)
split2["train"].to_json("./data/valid.jsonl", orient="records", lines=True)
split2["test"].to_json("./data/test.jsonl", orient="records", lines=True)

Step 3: Configure and Train

# sql_lora_config.yaml
model: mlx-community/Mistral-7B-Instruct-v0.3-4bit
train: true
data: ./data
batch_size: 4
iters: 600
learning_rate: 1e-5
optimizer: adamw
lora_parameters:
  rank: 8
  scale: 20.0
num_layers: 16
mask_prompt: true
steps_per_report: 10
steps_per_eval: 100
save_every: 100
adapter_path: ./sql-adapters

mlx_lm.lora --config sql_lora_config.yaml

Step 4: Test

# Test on holdout set
mlx_lm.lora --config sql_lora_config.yaml --test

# Try a prompt
mlx_lm.generate \
    --model mlx-community/Mistral-7B-Instruct-v0.3-4bit \
    --adapter-path ./sql-adapters \
    --prompt "SCHEMA: CREATE TABLE users (id INT, name TEXT, age INT)
Question: Find all users older than 30"

Step 5: Fuse and Deploy

# Merge adapters into base model
mlx_lm.fuse \
    --model mlx-community/Mistral-7B-Instruct-v0.3-4bit \
    --adapter-path ./sql-adapters \
    --save-path ./sql-mistral-fused

# Serve the fine-tuned model
mlx_lm.server --model ./sql-mistral-fused

Training Speed Reference

Hardware	RAM	Model	Speed
M1 Max 32GB	32 GB	Mistral-7B (LoRA)	~250 tok/s
M3 Max 64GB	64 GB	Mistral-7B (LoRA)	~600 iters in 12 min
M3 Ultra 192GB	192 GB	70B (QLoRA)	~62 tok/s prefill
A100 (cloud)	40 GB	Mistral-7B (LoRA)	~2,000-4,000 tok/s (10-20x faster)

MLX fine-tuning is practical for: small datasets (<10K samples), rapid iteration, privacy-sensitive data, and personal projects where cost matters more than speed.