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
"""#1213 — `soup train` and `soup sweep` must build the same trainer wrapper.
Both commands now route through ``soup_cli.trainer.dispatch.build_trainer``.
Before that, sweep carried a second ``if/elif`` chain over ``cfg.task`` that was
last extended in v0.40.0, with no MLX route at all: for ten task values and for
every ``backend: mlx`` config, an arm trained plain next-token SFT while the run
registry recorded the configured task, and the sweep ranked those numbers.
The task list below is read off ``SoupConfig``'s ``task`` Literal instead of
being hand-written, so a task added to the schema without a dispatch entry fails
the first test rather than training the wrong objective under one command.
"""
from __future__ import annotations
import importlib
import typing
from pathlib import Path
from types import SimpleNamespace
from unittest.mock import MagicMock, patch
import pytest
_SRC = Path(__file__).resolve().parents[1] / "src" / "soup_cli"
#: Every wrapper ``build_trainer`` can construct, keyed by the module that
#: defines it. The classes here depend on peft/trl/mlx, so each site is swapped
#: for a recorder and no backend has to be installed for this file to run.
_WRAPPER_SITES = {
"soup_cli.trainer.sft": "SFTTrainerWrapper",
"soup_cli.trainer.dpo": "DPOTrainerWrapper",
"soup_cli.trainer.online_dpo": "OnlineDPOTrainerWrapper",
"soup_cli.trainer.grpo": "GRPOTrainerWrapper",
"soup_cli.trainer.ppo": "PPOTrainerWrapper",
"soup_cli.trainer.kto": "KTOTrainerWrapper",
"soup_cli.trainer.orpo": "ORPOTrainerWrapper",
"soup_cli.trainer.simpo": "SimPOTrainerWrapper",
"soup_cli.trainer.ipo": "IPOTrainerWrapper",
"soup_cli.trainer.bco": "BCOTrainerWrapper",
"soup_cli.trainer.preference": "PreferenceTrainerWrapper",
"soup_cli.trainer.reward_model": "RewardModelTrainerWrapper",
"soup_cli.trainer.pretrain": "PretrainTrainerWrapper",
"soup_cli.trainer.embedding": "EmbeddingTrainerWrapper",
"soup_cli.trainer.distill": "DistillTrainerWrapper",
"soup_cli.trainer.prm": "PRMTrainerWrapper",
"soup_cli.trainer.classifier": "ClassifierTrainerWrapper",
"soup_cli.trainer.unlearn": "UnlearnTrainerWrapper",
"soup_cli.trainer.mole_routing": "MoleRoutingTrainerWrapper",
"soup_cli.trainer.tts": "TTSTrainerWrapper",
"soup_cli.trainer.asr": "AsrTrainerWrapper",
}
#: transformer-backend dispatch: task -> wrapper class name.
_EXPECTED = {
"sft": "SFTTrainerWrapper",
"dpo": "DPOTrainerWrapper",
"online_dpo": "OnlineDPOTrainerWrapper",
"grpo": "GRPOTrainerWrapper",
"ppo": "PPOTrainerWrapper",
"kto": "KTOTrainerWrapper",
"orpo": "ORPOTrainerWrapper",
"simpo": "SimPOTrainerWrapper",
"ipo": "IPOTrainerWrapper",
"bco": "BCOTrainerWrapper",
"preference": "PreferenceTrainerWrapper",
"reward_model": "RewardModelTrainerWrapper",
"pretrain": "PretrainTrainerWrapper",
"embedding": "EmbeddingTrainerWrapper",
"distill": "DistillTrainerWrapper",
"prm": "PRMTrainerWrapper",
"classifier": "ClassifierTrainerWrapper",
"reranker": "ClassifierTrainerWrapper",
"cross_encoder": "ClassifierTrainerWrapper",
"unlearn": "UnlearnTrainerWrapper",
"moe_lora_routing": "MoleRoutingTrainerWrapper",
"tts": "TTSTrainerWrapper",
"asr": "AsrTrainerWrapper",
}
#: MLX rows resolve through ``mlx_routing``. Same five tasks the registry
#: accepts; the name is what ``resolve_trainer`` would have imported.
_MLX_EXPECTED = {
"sft": "MLXSFTTrainerWrapper",
"dpo": "MLXDPOTrainerWrapper",
"orpo": "MLXORPOTrainerWrapper",
"simpo": "MLXSimPOTrainerWrapper",
"kto": "MLXKTOTrainerWrapper",
"grpo": "MLXGRPOTrainerWrapper",
}
#: The minimum each task's own validator asks for on top of base + data.
_TASK_EXTRAS: dict[str, dict] = {
"preference": {"training": {"preference_loss": "simpo"}},
"tts": {"modality": "audio_out", "training": {"tts_family": "orpheus"}},
"classifier": {"training": {"num_labels": 2}},
"reranker": {"training": {"num_labels": 2}},
"cross_encoder": {"training": {"num_labels": 2}},
"distill": {"training": {"teacher_model": "fixtures/teacher"}},
"unlearn": {
"training": {"unlearn_method": "npo"},
"data": {"forget_set": "./forget.jsonl"},
},
"moe_lora_routing": {"training": {"mole_task_adapters": ["adapter-a", "adapter-b"]}},
"online_dpo": {"training": {"online_dpo_judge": "some-judge-model"}},
}
def _schema_tasks() -> tuple[str, ...]:
from soup_cli.config.schema import SoupConfig
annotation = SoupConfig.model_fields["task"].annotation
return typing.get_args(annotation)
def _recorder(name: str, built: list[str]):
"""A stand-in wrapper that records the class name and satisfies the CLI."""
class _Recorder:
def __init__(self, cfg, **kwargs):
built.append(name)
def setup(self, dataset):
pass
def train(self, **kwargs):
return {
"initial_loss": 1.0,
"final_loss": 0.5,
"total_steps": 1,
"duration_secs": 1.0,
"output_dir": "out",
"duration": "1s",
}
_Recorder.__name__ = name
_Recorder.__qualname__ = name
return _Recorder
@pytest.fixture
def built(monkeypatch: pytest.MonkeyPatch) -> list[str]:
"""Swap every wrapper class for a recorder; collects the names that get built.
Every wrapper module is imported *before* the first patch lands. Some of
them subclass a class that lives in another of them (`tts.py` subclasses
`sft.py`'s wrapper), and the base is bound at that module's first import. If
the patch were already in place, the real class would inherit from a
recorder and stay that way for the rest of the session, breaking any later
test that walks the MRO or monkeypatches the real base.
"""
names: list[str] = []
modules = {
module_path: importlib.import_module(module_path)
for module_path in _WRAPPER_SITES
}
for module_path, cls_name in _WRAPPER_SITES.items():
monkeypatch.setattr(modules[module_path], cls_name, _recorder(cls_name, names))
from soup_cli.trainer import mlx_routing
monkeypatch.setattr(
mlx_routing,
"get_mlx_trainer",
lambda task: _recorder(_MLX_EXPECTED[task], names),
)
return names
def _sweep_config(task: str):
from soup_cli.config.schema import SoupConfig
fields: dict = {"base": "some-model", "task": task, "data": {"train": "./d.jsonl"}}
for key, value in _TASK_EXTRAS.get(task, {}).items():
existing = fields.get(key)
fields[key] = {**existing, **value} if isinstance(existing, dict) else value
return SoupConfig(**fields)
def _run_sweep_arm(cfg) -> None:
"""Run one sweep arm with everything outside the dispatch stubbed out."""
from soup_cli.commands.sweep import _run_single
tracker = MagicMock()
tracker.start_run.return_value = "run-1"
with (
patch("soup_cli.data.loader.load_dataset", return_value={"train": [{"text": "x"}]}),
patch("soup_cli.utils.gpu.detect_device", return_value=("cpu", "CPU")),
patch("soup_cli.utils.gpu.get_gpu_info", return_value={}),
patch("soup_cli.experiment.tracker.ExperimentTracker", return_value=tracker),
patch("soup_cli.monitoring.display.TrainingDisplay"),
):
_run_single(cfg, {}, "sweep_1", None)
class TestDispatchParity:
def test_every_schema_task_has_a_dispatch_entry(self, built: list[str]) -> None:
"""Walk the Literal: a task the schema grows without a wrapper fails here."""
from soup_cli.trainer.dispatch import build_trainer
assert set(_schema_tasks()) == set(_EXPECTED), (
"SoupConfig.task and the dispatch table disagree: update "
"soup_cli/trainer/dispatch.py::build_trainer and this file together"
)
for task, expected_name in _EXPECTED.items():
built.clear()
build_trainer(SimpleNamespace(task=task, backend="transformers"), device="cpu")
assert built == [expected_name], f"task={task!r} built {built}"
def test_mlx_backend_goes_through_the_registry(self, built: list[str]) -> None:
from soup_cli.trainer.dispatch import build_trainer
for task, expected_name in _MLX_EXPECTED.items():
built.clear()
build_trainer(SimpleNamespace(task=task, backend="mlx"), device="metal")
assert built == [expected_name], f"backend=mlx task={task!r} built {built}"
def test_sweep_builds_the_wrapper_the_schema_names(self, built: list[str]) -> None:
"""The sweep-side half of the parity claim, over every task value."""
for task, expected_name in _EXPECTED.items():
built.clear()
_run_sweep_arm(_sweep_config(task))
assert built == [expected_name], f"sweep task={task!r} built {built}"
def test_sweep_builds_the_mlx_wrapper_too(self, built: list[str]) -> None:
"""`backend: mlx` used to reach the SFT wrapper in sweep, and only there.
The schema admits MLX for ``sft`` alone (it refuses the other registry
entries before dispatch), so this row is the one end-to-end MLX case the
config layer allows.
"""
cfg = _sweep_config("sft").model_copy(update={"backend": "mlx"})
built.clear()
_run_sweep_arm(cfg)
assert built == ["MLXSFTTrainerWrapper"], built
def test_an_unknown_task_raises_instead_of_falling_back_to_sft(
self, built: list[str]
) -> None:
from soup_cli.trainer.dispatch import build_trainer
with pytest.raises(ValueError) as excinfo:
build_trainer(SimpleNamespace(task="not_a_task", backend="transformers"), device="cpu")
assert "not_a_task" in str(excinfo.value)
assert built == [], "an unknown task must not build an SFT wrapper"
def test_sweeping_the_shrink_heal_config_builds_the_distill_wrapper(
self, built: list[str], tmp_path: Path
) -> None:
"""`soup shrink --heal-steps` writes a `task: distill` config; sweep used to SFT it."""
from soup_cli.commands.shrink import _build_heal_config_yaml
from soup_cli.config.loader import load_config
heal_yaml = _build_heal_config_yaml(
pruned_dir=str(tmp_path / "pruned"),
teacher="fixtures/teacher",
heal_data=str(tmp_path / "heal.jsonl"),
steps=200,
out_dir=str(tmp_path / "healed"),
heal_rows=1000,
)
config_path = tmp_path / "soup.yaml"
config_path.write_text(heal_yaml, encoding="utf-8")
cfg = load_config(config_path)
assert cfg.task == "distill"
built.clear()
_run_sweep_arm(cfg)
assert built == ["DistillTrainerWrapper"], built
class TestNoSecondChain:
"""The regression this file exists for was a chain, not a wrong branch."""
@pytest.mark.parametrize("filename", ["train.py", "sweep.py"])
def test_command_calls_the_shared_dispatch_only(self, filename: str) -> None:
source = (_SRC / "commands" / filename).read_text(encoding="utf-8")
assert "build_trainer(" in source, f"{filename} does not call build_trainer"
assert "elif cfg.task ==" not in source, (
f"{filename} grew a task chain again; route it through "
"soup_cli/trainer/dispatch.py instead"
)
class TestTheKwargsReachTheWrapper:
"""`build_trainer` forwards each command's kwargs unchanged (#1213).
The parity tests above compare which *class* gets built. Without this class,
`build_trainer` could stop forwarding `trust_remote_code`,
`deepspeed_config`, `fsdp_config` or `report_to` and nothing would fail:
`soup train` would silently ignore `--trust-remote-code`, `--deepspeed`,
FSDP and trackers, and a sweep arm could lose `device=` and fall back to the
wrapper's own `"cuda"` default. Both mutations survive the recorder fixtures
because the recorder accepts `**kwargs` and never looks at them.
"""
#: What `soup train` passes (commands/train.py builds exactly these five).
TRAIN_KWARGS = {
"device": "cpu",
"report_to": "none",
"deepspeed_config": "ds_config.json",
"fsdp_config": {"fsdp": "full_shard"},
"trust_remote_code": True,
}
@pytest.fixture
def seen(self, monkeypatch: pytest.MonkeyPatch) -> dict:
received: dict = {}
def recorder(name: str):
class _Recorder:
def __init__(self, cfg, **kwargs):
received[name] = kwargs
def setup(self, dataset):
pass
def train(self, **kwargs):
return {"initial_loss": 1.0, "final_loss": 0.5, "total_steps": 1,
"duration_secs": 1.0, "output_dir": "out", "duration": "1s"}
return _Recorder
modules = {path: importlib.import_module(path) for path in _WRAPPER_SITES}
for path, cls_name in _WRAPPER_SITES.items():
monkeypatch.setattr(modules[path], cls_name, recorder(cls_name))
from soup_cli.trainer import mlx_routing
monkeypatch.setattr(
mlx_routing, "get_mlx_trainer", lambda task: recorder(_MLX_EXPECTED[task])
)
return received
def test_build_trainer_forwards_every_kwarg_unchanged(self, seen: dict) -> None:
from soup_cli.trainer.dispatch import build_trainer
rows = [(task, "transformers", name) for task, name in _EXPECTED.items()]
rows += [(task, "mlx", name) for task, name in _MLX_EXPECTED.items()]
for task, backend, name in rows:
seen.clear()
build_trainer(SimpleNamespace(task=task, backend=backend), **self.TRAIN_KWARGS)
assert seen == {name: self.TRAIN_KWARGS}, f"{backend}/{task}: {seen}"
def test_sweep_passes_the_detected_device(self, seen: dict) -> None:
for task, name in _EXPECTED.items():
seen.clear()
_run_sweep_arm(_sweep_config(task))
assert seen == {name: {"device": "cpu"}}, f"sweep {task}: {seen}"