← research lab

Mac-local specialist field guide

MLX LoRA fine-tuning on Apple Silicon

Fine-tune an MLX model on Apple Silicon with checked chat data, bounded LoRA/QLoRA commands, and paired base/adapter evaluation. Includes failure checks and limits.

MLX LoRA adapts a pretrained language model on Apple Silicon while keeping its base weights frozen. Start with a model that fits your Mac, check the dataset before loading weights, and compare the unchanged base with the adapter on the same held-out task. This guide supplies the commands and an exact-duplicate preflight; it does not promise a quality or memory result.

1. Prepare a local environment and pin the inputs

Use an Apple Silicon Mac and a compatible MLX model. Put a downloaded, revision-pinned base in ./models/base; that directory is a placeholder for your own model, not a bundled download. Save its model-card URL, license, revision, tokenizer and chat template alongside your run. A quantized base selects QLoRA in MLX LM; a non-quantized base uses LoRA. Neither path guarantees that a particular model fits your available memory.

uv venv --python 3.12
MLX_LM_REVISION=56230fa02b8ff8330daf26dc95c28480423ed5fe
uv pip install "mlx-lm[train] @ git+https://github.com/ml-explore/mlx-lm.git@$MLX_LM_REVISION"
.venv/bin/mlx_lm.lora --help
uv pip freeze > mlx-environment.txt

The commands below follow the official MLX LM LoRA guide and CLI source, checked on 14 November 2026. The install command selects that checked source revision. Keep the resolved environment file with your result to record its dependencies. Installing packages downloads software; the examples use local model and data paths and do not enable a remote experiment tracker.

2. Validate the chat data before using the GPU

Prepare data/train.jsonl, data/valid.jsonl and data/test.jsonl with distinct examples from the task you want to teach. Each line is one JSON object. For this example, use text-only chat messages and end each conversation with the desired assistant answer. Tool calls and other dataset formats need their own schema checks.

{"messages":[{"role":"user","content":"Classify this request: list the files in a folder."},{"role":"assistant","content":"file-listing"}]}

That single row illustrates the format, not a useful training set. Save the following as check_data.py and run .venv/bin/python check_data.py. It rejects empty splits, malformed JSON, invalid text-chat messages and exact duplicate conversations, including duplicates across splits. It does not detect paraphrases or prove that the data matches the model’s chat template. Review those separately.

import json
from pathlib import Path

seen = {}
for split in ("train", "valid", "test"):
    path = Path("data") / f"{split}.jsonl"
    lines = path.read_text().splitlines()
    assert lines, f"{path}: empty split"
    for number, line in enumerate(lines, 1):
        row = json.loads(line)
        messages = row.get("messages")
        assert isinstance(messages, list) and messages, (path, number)
        for message in messages:
            assert message.get("role") in {"system", "user", "assistant"}, (path, number)
            assert isinstance(message.get("content"), str), (path, number)
            assert message["content"].strip(), (path, number)
        assert messages[-1]["role"] == "assistant", (path, number)
        key = json.dumps(messages, sort_keys=True, ensure_ascii=False)
        assert key not in seen, f"duplicate example: {seen.get(key)} and {path}:{number}"
        seen[key] = f"{path}:{number}"
    print(f"{path}: {len(lines)} chat examples")

3. Record the unchanged base, then smoke-test training

Measure the unchanged base on your held-out task before training. The first command below also records base-model test perplexity. The empty adapter path explicitly selects the base in the linked CLI version. Keep the same model, test split, batch size and sequence settings for the paired adapter check.

.venv/bin/mlx_lm.lora \
  --model ./models/base --data ./data \
  --test --test-batches -1 --batch-size 1 --adapter-path ""

.venv/bin/mlx_lm.lora \
  --model ./models/base --data ./data --train \
  --iters 10 --batch-size 1 --num-layers 4 --seed 0 \
  --adapter-path ./adapters/smoke

Training is opt-in. Ten iterations and four adapted layers are a small wiring check, not a recommended recipe or a quality result. Stop if the run does not fit the machine. Preserve the resolved configuration and adapter output before choosing a larger run. If prompt masking is required, check the selected model’s template and MLX LM’s --mask-prompt behavior rather than assuming the loss covers only assistant tokens.

4. Evaluate the saved adapter on the same holdout

.venv/bin/mlx_lm.lora \
  --model ./models/base --data ./data \
  --test --test-batches -1 --batch-size 1 \
  --adapter-path ./adapters/smoke

Perplexity is a training diagnostic. It does not establish correct tool arguments, executable SQL, faithful edits or a useful assistant. Run base and adapter through the same task scorer and decoding settings. Keep an out-of-domain regression slice, preserve raw failures, and distinguish a timeout or missing measurement from zero. The local LLM evaluation guide walks through a retained report card and its limits.

5. Decide before fusing or publishing

Keep the model identity, data manifest, configuration, adapter, evaluation outputs and decision together. Fuse or export only after the target gate and protected regression gates pass. Check the fused artifact through its intended runtime separately; an adapter result does not prove export parity. Record latency, RAM and throughput only when measured on the named machine.

The retained ReST specialist shows the tradeoff. Its September paired run improved file-operations depth from 9/12 to 12/12 while breadth fell from 30/45 to 25/45. Those are historical measurements supporting a narrow routing decision, not results from this tutorial or a general model upgrade.

What was checked for this guide

The command flags and empty-adapter baseline behavior were checked against the linked MLX LM source. The data preflight was exercised on valid synthetic splits and duplicate, malformed, empty and invalid-message fixtures without loading a model. No MLX training, model download, quality benchmark or memory measurement was run for this refresh. Use the Mac fine-tuning overview to choose a workflow and the factory run schema to retain a reproducible decision record.