Fine-tune LLMs from one YAML. Layer streaming trains an 8B model on a 4 GB laptop GPU.
Python cliconsumer-gpudpofine-tuningggufhuggingfacellmllmopslocal-ailocal-llmloralow-vrammachine-learningollamapeftpythonpytorchqlorasfttransformers
"""#685: MLX SFT ignores gradient_checkpointing.
MLXSFTTrainerWrapper.train() builds mlx-lm's TrainingArgs without a
grad_checkpoint kwarg, so mlx-lm's own dataclass default of False always
applies regardless of the validated schema field
training.gradient_checkpointing (bool or tier literal, config/schema.py).
The written adapter_config.json also hardcoded grad_checkpoint: false
rather than reading back the effective value, so the drift could not even
be detected from the output afterwards.
Sibling of test_issue684_mlx_grad_accumulation.py (#684), same file, same
harness: real train() control flow against minimal fake mlx / mlx_lm
modules registered in sys.modules, not source-text inspection.
Tier-string resolution: gradient_checkpointing accepts a plain bool OR one
of "selective"/"medium"/"full"/"auto" (a granularity mlx-lm has no concept
of: TrainingArgs.grad_checkpoint is a single bool). This mirrors the
repo's own established convention for the same field on every other
backend: commands/train.py's hardware-fit predictor
(`gc = bool(getattr(tcfg, "gradient_checkpointing", False))`) and
layer_stream.should_enable_hf_gradient_checkpointing
(`bool(gradient_checkpointing) and not stream_layers`, used by the
DPO/KTO/ORPO/SimPO wrappers) both resolve the same tiered field with a
plain bool() coercion rather than branching per tier. Any non-empty tier
string is truthy, so "selective"/"medium"/"full"/"auto" all resolve to
True (checkpointing enabled) and False/absent resolves to False, exactly
as those two call sites already treat it.
Caveat that still matters: MLX only runs on Apple Silicon. These tests
exercise the real function body via the fake-module harness, not a
substitute for an end-to-end run on real Metal hardware, and this PR does
not attempt to distinguish mlx-lm's checkpointing granularity (there is
none to distinguish; it wraps only the first decoder layer type,
uniformly).
"""
from __future__ import annotations
import json
import sys
import types
import pytest
def _install_fake_mlx(monkeypatch):
"""Register minimal fake ``mlx`` / ``mlx_lm`` modules in ``sys.modules``
so ``MLXSFTTrainerWrapper.train()`` runs for real, without Apple
Silicon or the real packages installed. Same harness as
test_issue634_mlx_resume.py's helper of the same name.
"""
mlx = types.ModuleType("mlx")
mlx_core = types.ModuleType("mlx.core")
# #1850: MLX SFT's train() seeds mx.random before attaching LoRA.
mlx_core.random = types.SimpleNamespace(seed=lambda _seed: None)
mlx_optimizers = types.ModuleType("mlx.optimizers")
mlx_optimizers.AdamW = lambda **kwargs: object()
# #686 builds a real LR schedule, so the MLX path reaches these three
# builders on the default config (scheduler="cosine"). A fake defining only
# AdamW raises AttributeError from `mlx_optim.build_lr_schedule`. Recording
# stubs; the real curve is asserted against the real library in
# tests/test_issue686_mlx_optimizer_schedule.py.
mlx_optimizers.linear_schedule = lambda init, end, steps: (lambda step: end)
mlx_optimizers.cosine_decay = lambda init, steps: (lambda step: init)
mlx_optimizers.join_schedules = lambda scheds, boundaries: (
lambda step: scheds[-1](step)
)
mlx_lm = types.ModuleType("mlx_lm")
mlx_lm_tuner = types.ModuleType("mlx_lm.tuner")
mlx_lm_tuner_callbacks = types.ModuleType("mlx_lm.tuner.callbacks")
class _FakeTrainingCallback:
pass
mlx_lm_tuner_callbacks.TrainingCallback = _FakeTrainingCallback
mlx_lm_tuner_datasets = types.ModuleType("mlx_lm.tuner.datasets")
mlx_lm_tuner_datasets.CacheDataset = lambda rows: rows
mlx_lm_tuner_datasets.create_dataset = lambda rows, tokenizer, args: rows
mlx_lm_tuner_trainer = types.ModuleType("mlx_lm.tuner.trainer")
class _FakeTrainingArgs:
def __init__(self, **kwargs):
self.__dict__.update(kwargs)
mlx_lm_tuner_trainer.TrainingArgs = _FakeTrainingArgs
captured_calls = []
def _fake_train(**kwargs):
captured_calls.append(kwargs)
callback = kwargs.get("training_callback")
if callback is not None:
callback.on_train_loss_report({"train_loss": 0.5})
mlx_lm_tuner_trainer.train = _fake_train
mlx_lm_tuner_utils = types.ModuleType("mlx_lm.tuner.utils")
mlx_lm_tuner_utils.linear_to_lora_layers = lambda model, num_layers, config: None
fake_modules = {
"mlx": mlx,
"mlx.core": mlx_core,
"mlx.optimizers": mlx_optimizers,
"mlx_lm": mlx_lm,
"mlx_lm.tuner": mlx_lm_tuner,
"mlx_lm.tuner.callbacks": mlx_lm_tuner_callbacks,
"mlx_lm.tuner.datasets": mlx_lm_tuner_datasets,
"mlx_lm.tuner.trainer": mlx_lm_tuner_trainer,
"mlx_lm.tuner.utils": mlx_lm_tuner_utils,
}
for name, module in fake_modules.items():
monkeypatch.setitem(sys.modules, name, module)
return captured_calls
class _FakeMlxModel:
def __init__(self):
self.layers = [object()]
def freeze(self):
pass
def load_weights(self, path, strict=True):
pass
def _mlx_wrapper(tmp_path, **training):
from soup_cli.config.schema import DataConfig, SoupConfig, TrainingConfig
from soup_cli.trainer.mlx_sft import MLXSFTTrainerWrapper
cfg = SoupConfig(
base="mlx-community/Llama-3.1-8B-Instruct-4bit",
task="sft",
backend="mlx",
data=DataConfig(train="./data/train.jsonl", format="chatml"),
training=TrainingConfig(**training),
output=str(tmp_path),
)
wrapper = MLXSFTTrainerWrapper(cfg)
wrapper.model = _FakeMlxModel()
wrapper.tokenizer = object()
wrapper._dataset = {"train": [{"text": "hi"}], "val": []}
return wrapper
@pytest.mark.parametrize(
"requested,expected",
[
(True, True),
(False, False),
("selective", True),
("medium", True),
("full", True),
("auto", True),
],
)
def test_grad_checkpoint_reaches_training_args(
tmp_path, monkeypatch, requested, expected
):
"""The value mlx-lm's TrainingArgs actually receives, for every value the
schema accepts. Before the fix this kwarg was never passed at all, so
mlx-lm's own dataclass default (False) applied every time, and a test
that only inspects adapter_config.json cannot see that, since the
written metadata comes from the same local variable regardless of
whether it is threaded into the TrainingArgs(...) call. Deleting
grad_checkpoint=grad_checkpoint from that call must fail here even
though it changes nothing about the JSON write."""
captured_calls = _install_fake_mlx(monkeypatch)
wrapper = _mlx_wrapper(
tmp_path, epochs=1, lr=1e-4, batch_size=1, gradient_checkpointing=requested
)
wrapper.train()
args = captured_calls[0]["args"]
assert args.grad_checkpoint is expected, (
f"gradient_checkpointing={requested!r} must resolve to "
f"grad_checkpoint={expected} on the TrainingArgs mlx-lm receives"
)
@pytest.mark.parametrize(
"requested,expected",
[
(True, True),
(False, False),
("selective", True),
("medium", True),
("full", True),
("auto", True),
],
)
def test_grad_checkpoint_is_recorded_in_adapter_config(
tmp_path, monkeypatch, requested, expected
):
"""The value recorded in adapter_config.json, for every value the schema
accepts. Kept separate from the TrainingArgs assertion above so the two
halves have distinct kill-sets: reverting only the metadata write while
keeping the TrainingArgs kwarg fails only this test, and deleting the
TrainingArgs kwarg while keeping the metadata write fails only the
other one."""
_install_fake_mlx(monkeypatch)
wrapper = _mlx_wrapper(
tmp_path, epochs=1, lr=1e-4, batch_size=1, gradient_checkpointing=requested
)
wrapper.train()
written = json.loads((tmp_path / "adapter_config.json").read_text())
assert written["grad_checkpoint"] is expected, (
f"gradient_checkpointing={requested!r} must resolve to "
f"grad_checkpoint={expected} in the written adapter_config.json"
)
def test_default_is_unchanged(tmp_path, monkeypatch):
"""No explicit setting keeps the schema default (False) end to end,
on both the TrainingArgs kwarg and the written metadata."""
captured_calls = _install_fake_mlx(monkeypatch)
wrapper = _mlx_wrapper(tmp_path, epochs=1, lr=1e-4, batch_size=1)
wrapper.train()
assert captured_calls[0]["args"].grad_checkpoint is False
written = json.loads((tmp_path / "adapter_config.json").read_text())
assert written["grad_checkpoint"] is False
class TestTierFlatteningIsAnnounced:
"""The bool()-flattening from a tier string to a single on/off switch is
silent otherwise: a user asking for 'selective' gets 'full' with no
indication anything was collapsed. Same warning mechanism and same
_warnings_for-style harness as test_issue353_mlx_seed_warning.py."""
@staticmethod
def _warnings_for(monkeypatch, **training):
from io import StringIO
from rich.console import Console
from soup_cli.config.schema import DataConfig, SoupConfig, TrainingConfig
from soup_cli.trainer import mlx_sft
buffer = StringIO()
monkeypatch.setattr(mlx_sft, "console", Console(file=buffer, width=200))
cfg = SoupConfig(
base="mlx-community/Llama-3.1-8B-Instruct-4bit",
task="sft",
backend="mlx",
data=DataConfig(train="./data/train.jsonl", format="chatml"),
training=TrainingConfig(**training),
output="./out",
)
mlx_sft.MLXSFTTrainerWrapper(cfg)._check_unsupported()
return buffer.getvalue()
def test_a_tier_string_is_named(self, monkeypatch):
out = self._warnings_for(
monkeypatch, epochs=1, lr=1e-4, batch_size=1, gradient_checkpointing="selective"
)
assert "gradient_checkpointing" in out
assert "selective" in out
def test_a_plain_bool_says_nothing(self, monkeypatch):
"""CONTROL. A bool is not a tier; flattening a bool to itself has
nothing to announce."""
out = self._warnings_for(
monkeypatch, epochs=1, lr=1e-4, batch_size=1, gradient_checkpointing=True
)
assert "gradient_checkpointing" not in out