Skip to content

armgit / Soup

Public Imported from GitHub
0

Fine-tune LLMs from one YAML. Layer streaming trains an 8B model on a 4 GB laptop GPU.

fix(config): refuse lora rank_pattern/alpha_pattern with backend: mlx (they were ignored) (#2150)

Alpamys Makazhane05b6f6db42f
diff --git a/changelog.d/0.76.0/2150.fixed.md b/changelog.d/0.76.0/2150.fixed.md
new file mode 100644
index 00000000..1032b380
--- /dev/null
+++ b/changelog.d/0.76.0/2150.fixed.md
@@ -0,0 +1 @@
+- **`training.lora.rank_pattern` and `alpha_pattern` are refused with `backend: mlx` instead of being silently ignored (#1996).** The MLX trainer builds every adapter, for SFT, DPO, ORPO and SimPO alike, from the one scalar `lora.r` and `lora.alpha`, so a config that asked for a per-module rank or alpha loaded, passed `soup train --dry-run` and trained a uniform adapter, and `soup doctor --config` listed nothing for it. Now refused at config load, naming each field the config set, `backend: mlx`, and the two ways out: remove the pattern, or use `backend: transformers`, which applies it. A task MLX cannot run, `lora.r: 0` and MLX DoRA keep their own, earlier refusals. An empty `{}` or `null` sets nothing and still loads, and `transformers` and `unsloth` configs are unchanged. This is a stop-gap: it goes away when the MLX trainer honours the patterns. (#2150)
diff --git a/docs/backends-and-ops.md b/docs/backends-and-ops.md
index a5e9f61e..96d86401 100644
--- a/docs/backends-and-ops.md
+++ b/docs/backends-and-ops.md
@@ -138,6 +138,8 @@ training:
MLX backend supports SFT, DPO, ORPO and SimPO. Any other task with `backend: mlx` (`grpo`, `ipo`, `kto`, `preference`, ...) is refused when the config is loaded, with an error naming the task. Requires `mlx-lm >= 0.31.3`. Use `soup recipes search mlx` for ready-made Apple Silicon configs.
+`training.lora.rank_pattern` and `training.lora.alpha_pattern` are refused on `backend: mlx` for SFT, DPO, ORPO and SimPO ([#1996](https://github.com/MakazhanAlpamys/Soup/issues/1996)): the MLX trainer builds every adapter from the one scalar `lora.r` and `lora.alpha`, so per-module ranks and alphas would be dropped without a word. Remove them, or use `backend: transformers`, which applies them. An empty `{}` sets nothing and still loads.
+
#### DPO on MLX
`task: dpo` with `backend: mlx` runs Soup's own training loop (`mlx-lm` ships no DPO helper), with the sigmoid loss TRL uses by default and `training.dpo_beta`.
diff --git a/src/soup_cli/config/schema.py b/src/soup_cli/config/schema.py
index 16e5e4a3..90b8b519 100644
--- a/src/soup_cli/config/schema.py
+++ b/src/soup_cli/config/schema.py
@@ -8370,6 +8370,42 @@ class SoupConfig(BaseModel):
)
return self
+ @model_validator(mode="after")
+ def _validate_mlx_lora_patterns(self) -> "SoupConfig":
+ """#1996 - ``lora.rank_pattern`` / ``alpha_pattern`` are not applied on
+ ``backend: mlx``. Stop-gap: delete this validator (and
+ ``tests/test_mlx_lora_pattern_refusal.py``) when the MLX trainer honours them.
+
+ SFT, DPO, ORPO and SimPO all build the adapter in ``MLXSFTTrainerWrapper._apply_lora``
+ from one scalar ``lora.r`` and ``lora.alpha``, so a config that set a pattern
+ trained a uniform-rank adapter without a word. Not part of
+ :meth:`_validate_peft_variant_backend_and_quantization`, which returns early
+ for plain LoRA; defined after :meth:`_validate_mlx_task_support` (and the
+ ``lora.r=0`` check) on purpose, so a task MLX cannot run, or a config with no
+ adapter at all, is refused for that reason first and "use backend:
+ transformers" below always leads to a config that loads. MLX DoRA already
+ refuses both fields in its own words, earlier. An empty ``{}`` sets nothing
+ (``peft_wiring`` reads ``if rank_pattern:``) and still loads.
+ """
+ if self.backend != "mlx":
+ return self
+ lcfg = self.training.lora
+ set_fields = [
+ f"training.lora.{name}"
+ for name in ("rank_pattern", "alpha_pattern")
+ if getattr(lcfg, name)
+ ]
+ if not set_fields:
+ return self
+ names = " and ".join(set_fields)
+ verb = "are" if len(set_fields) > 1 else "is"
+ raise ValueError(
+ f"{names} {verb} not applied by backend: mlx — the MLX trainer builds every "
+ "adapter from one scalar training.lora.r and training.lora.alpha, so "
+ f"per-module ranks and alphas would be dropped. Remove {names}, or use "
+ "backend: transformers."
+ )
+
@model_validator(mode="after")
def _validate_uld_compat(self) -> "SoupConfig":
"""v0.70.0 Part B — Universal Logit Distillation gate.
diff --git a/tests/test_mlx_lora_pattern_refusal.py b/tests/test_mlx_lora_pattern_refusal.py
new file mode 100644
index 00000000..929ba26c
--- /dev/null
+++ b/tests/test_mlx_lora_pattern_refusal.py
@@ -0,0 +1,246 @@
+"""#1996 - ``training.lora.rank_pattern`` / ``alpha_pattern`` are refused on ``backend: mlx``.
+
+Both fields are real on the transformers backend (peft's per-module rank and alpha
+overrides), but every MLX trainer builds its adapter from ONE scalar
+``training.lora.r`` and ``training.lora.alpha``: SFT's ``_apply_lora`` calls
+``linear_to_lora_layers`` with ``int(lora_cfg.r)``, and the DPO, ORPO and SimPO loops
+reuse that method. The only MLX refusal was for the DoRA variant, and the fields are not
+in the doctor's ``_MLX_SFT`` table, so a plain-LoRA config that set them loaded,
+passed ``soup train --dry-run`` and trained a uniform-rank adapter with no warning.
+
+This is the stop-gap until the MLX trainer honours the patterns (PR #2133). When that
+lands, delete this file together with ``SoupConfig._validate_mlx_lora_patterns``.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+from pydantic import ValidationError
+from typer.testing import CliRunner
+
+from soup_cli.cli import app
+from soup_cli.config.backend_support import REGISTRY
+from soup_cli.config.loader import load_config_from_string
+from soup_cli.config.schema import SoupConfig
+from tests.conftest import strip_ansi
+
+_MLX_TASKS = ["sft", "dpo", "orpo", "simpo"]
+_REMOVE_OR_SWITCH = "or use backend: transformers."
+
+_YAML = """
+base: mlx-community/Qwen2.5-0.5B-Instruct-4bit
+task: sft
+backend: mlx
+data:
+ train: ./data/train.jsonl
+ format: alpaca
+training:
+ epochs: 1
+ lora:
+ r: 8
+ alpha: 16
+ rank_pattern:
+ q_proj: 4
+output: ./output
+"""
+
+
+def _plain(text: str) -> str:
+ """Strip ANSI escapes and collapse whitespace (Rich colours and wraps on CI)."""
+ return " ".join(strip_ansi(text).split())
+
+
+def _config(task: str = "sft", backend: str = "mlx", **lora: object) -> SoupConfig:
+ return SoupConfig(
+ base="test/model",
+ task=task,
+ backend=backend,
+ data={"train": "d.jsonl"},
+ training={"epochs": 1, "lora": lora},
+ )
+
+
+def _refusal(task: str = "sft", backend: str = "mlx", **lora: object) -> str:
+ """The message of the refusal, without pydantic's echo of the input dict."""
+ with pytest.raises(ValidationError) as excinfo:
+ _config(task, backend, **lora)
+ errors = excinfo.value.errors()
+ assert len(errors) == 1, errors
+ return " ".join(str(errors[0]["msg"]).split())
+
+
+class TestRefusedOnMlx:
+ @pytest.mark.parametrize("task", _MLX_TASKS)
+ def test_rank_pattern_is_refused(self, task: str) -> None:
+ msg = _refusal(task, rank_pattern={"q_proj": 4})
+ assert "training.lora.rank_pattern is not applied by backend: mlx" in msg
+ assert "one scalar training.lora.r and training.lora.alpha" in msg
+ assert f"Remove training.lora.rank_pattern, {_REMOVE_OR_SWITCH}" in msg
+ assert "alpha_pattern" not in msg # names only what the config set
+
+ @pytest.mark.parametrize("task", _MLX_TASKS)
+ def test_alpha_pattern_is_refused(self, task: str) -> None:
+ msg = _refusal(task, alpha_pattern={"q_proj": 32})
+ assert "training.lora.alpha_pattern is not applied by backend: mlx" in msg
+ assert f"Remove training.lora.alpha_pattern, {_REMOVE_OR_SWITCH}" in msg
+ assert "rank_pattern" not in msg
+
+ @pytest.mark.parametrize("task", _MLX_TASKS)
+ def test_both_patterns_are_named_in_one_refusal(self, task: str) -> None:
+ msg = _refusal(task, rank_pattern={"q_proj": 4}, alpha_pattern={"q_proj": 32})
+ assert (
+ "training.lora.rank_pattern and training.lora.alpha_pattern "
+ "are not applied by backend: mlx"
+ ) in msg
+ assert (
+ "Remove training.lora.rank_pattern and training.lora.alpha_pattern, "
+ + _REMOVE_OR_SWITCH
+ ) in msg
+
+ @pytest.mark.parametrize("value", [{"q_proj": 1}, {"q_proj": 4, "v_proj": 8}, {".*proj": 2}])
+ def test_every_non_empty_pattern_is_refused(self, value: dict) -> None:
+ # The refusal is about the backend, not about what the pattern says.
+ assert "is not applied by backend: mlx" in _refusal(rank_pattern=value)
+ assert "is not applied by backend: mlx" in _refusal(alpha_pattern=value)
+
+ def test_a_yaml_config_is_refused_at_load(self) -> None:
+ with pytest.raises(ValueError) as excinfo:
+ load_config_from_string(_YAML)
+ msg = _plain(str(excinfo.value))
+ assert "training.lora.rank_pattern is not applied by backend: mlx" in msg
+ assert f"Remove training.lora.rank_pattern, {_REMOVE_OR_SWITCH}" in msg
+
+ def test_soup_train_dry_run_stops_with_the_message(self, tmp_path) -> None:
+ config = tmp_path / "soup.yaml"
+ config.write_text(_YAML, encoding="utf-8")
+ result = CliRunner().invoke(app, ["train", "--config", str(config), "--dry-run"])
+ assert result.exit_code == 1, (result.output, repr(result.exception))
+ assert "training.lora.rank_pattern is not applied by backend: mlx" in _plain(
+ result.output
+ )
+
+
+class TestStillLoads:
+ @pytest.mark.parametrize("task", _MLX_TASKS)
+ @pytest.mark.parametrize("field", ["rank_pattern", "alpha_pattern"])
+ def test_an_empty_pattern_is_not_an_override(self, task: str, field: str) -> None:
+ # peft_wiring reads ``if rank_pattern:``, so {} sets nothing on any backend.
+ cfg = _config(task, **{field: {}})
+ assert getattr(cfg.training.lora, field) == {}
+
+ @pytest.mark.parametrize("task", _MLX_TASKS)
+ def test_unset_and_null_patterns_load(self, task: str) -> None:
+ cfg = _config(task, rank_pattern=None, alpha_pattern=None)
+ assert cfg.backend == "mlx"
+ assert cfg.training.lora.rank_pattern is None
+ assert cfg.training.lora.alpha_pattern is None
+ assert _config(task).training.lora.rank_pattern is None
+
+ @pytest.mark.parametrize("task", _MLX_TASKS)
+ def test_scalar_lora_settings_still_load_on_mlx(self, task: str) -> None:
+ cfg = _config(task, r=8, alpha=16, use_rslora=True)
+ assert (cfg.training.lora.r, cfg.training.lora.alpha) == (8, 16)
+
+ @pytest.mark.parametrize("backend", ["transformers", "unsloth"])
+ def test_other_backends_keep_the_patterns(self, backend: str) -> None:
+ cfg = _config("sft", backend, rank_pattern={"q_proj": 4}, alpha_pattern={"q_proj": 32})
+ assert cfg.training.lora.rank_pattern == {"q_proj": 4}
+ assert cfg.training.lora.alpha_pattern == {"q_proj": 32}
+
+ @pytest.mark.parametrize("task", ["dpo", "orpo"])
+ def test_transformers_preference_tasks_keep_the_patterns(self, task: str) -> None:
+ # "use backend: transformers" must lead to a config that loads.
+ cfg = _config(task, "transformers", rank_pattern={"q_proj": 4})
+ assert cfg.training.lora.rank_pattern == {"q_proj": 4}
+
+ def test_the_yaml_config_loads_once_the_backend_is_switched(self) -> None:
+ cfg = load_config_from_string(
+ _YAML.replace("backend: mlx", "backend: transformers").replace(
+ "mlx-community/Qwen2.5-0.5B-Instruct-4bit", "Qwen/Qwen2.5-0.5B-Instruct"
+ )
+ )
+ assert cfg.training.lora.rank_pattern == {"q_proj": 4}
+
+
+class TestOtherRefusalsKeepTheirOwnWords:
+ """Each of these configs names a problem that "use backend: transformers" would not
+ fix, or that has a more basic answer, so that refusal has to come first."""
+
+ @pytest.mark.parametrize("task", ["grpo", "kto", "ipo", "pretrain"])
+ def test_a_task_mlx_cannot_run_is_refused_for_that_first(self, task: str) -> None:
+ with pytest.raises(ValidationError) as excinfo:
+ _config(task, rank_pattern={"q_proj": 4})
+ msg = " ".join(str(excinfo.value).split())
+ assert "MLX backend only ships SFT" in msg
+ assert "is not applied by backend: mlx" not in msg
+
+ @pytest.mark.parametrize("field", ["rank_pattern", "alpha_pattern"])
+ def test_mlx_dora_keeps_its_own_message(self, field: str) -> None:
+ with pytest.raises(ValidationError) as excinfo:
+ _config(use_dora=True, **{field: {"q_proj": 4}})
+ msg = " ".join(str(excinfo.value).split())
+ assert "MLX DoRA does not support" in msg
+ assert "is not applied by backend: mlx" not in msg
+
+ def test_full_fine_tuning_keeps_its_own_message(self) -> None:
+ # lora.r=0 builds no adapter, so there is nothing for a pattern to override
+ # on any backend; MLX is refused for r=0 itself before this check runs.
+ with pytest.raises(ValidationError) as excinfo:
+ _config("sft", r=0, rank_pattern={"q_proj": 4})
+ msg = " ".join(str(excinfo.value).split())
+ assert "training.lora.r=0 (full fine-tuning) requires backend='transformers'" in msg
+ assert "is not applied by backend: mlx" not in msg
+
+
+class TestOtherEntryPoints:
+ def test_direct_construction_is_refused(self) -> None:
+ """``soup sweep``, ``soup rewind`` and autopilot build ``SoupConfig`` directly."""
+ with pytest.raises(ValidationError) as excinfo:
+ SoupConfig(
+ base="mlx-community/Qwen2.5-0.5B-Instruct-4bit",
+ backend="mlx",
+ data={"train": "t.jsonl"},
+ training={"lora": {"alpha_pattern": {"q_proj": 32}}},
+ )
+ assert "training.lora.alpha_pattern is not applied by backend: mlx" in _plain(
+ str(excinfo.value)
+ )
+
+ def test_a_sweep_arm_that_switches_to_mlx_is_refused(self) -> None:
+ """``soup sweep --param backend=mlx`` rebuilds the config from a dump of the
+ base config, so patterns on a transformers base must not ride into an mlx arm."""
+ from soup_cli.commands.sweep import _set_nested_param
+
+ base = _config("sft", "transformers", rank_pattern={"q_proj": 4})
+ arm = base.model_dump()
+ _set_nested_param(arm, "backend", "mlx")
+ with pytest.raises(ValidationError) as excinfo:
+ SoupConfig(**arm)
+ assert "training.lora.rank_pattern is not applied by backend: mlx" in _plain(
+ str(excinfo.value)
+ )
+
+ def test_the_mcp_config_loader_refuses_it(self, tmp_path, monkeypatch) -> None:
+ """The MCP profile/plan tools read the YAML through ``load_config_from_string``."""
+ from soup_cli.mcp_server.registry import McpToolError, _load_config_under_cwd
+
+ monkeypatch.chdir(tmp_path)
+ (tmp_path / "soup.yaml").write_text(_YAML, encoding="utf-8")
+ with pytest.raises(McpToolError, match="invalid config"):
+ _load_config_under_cwd("soup.yaml")
+
+ def test_the_mlx_docs_state_the_refusal(self) -> None:
+ root = Path(__file__).resolve().parents[1]
+ text = (root / "docs" / "backends-and-ops.md").read_text(encoding="utf-8")
+ flat = " ".join(text.split())
+ assert (
+ "`training.lora.rank_pattern` and `training.lora.alpha_pattern` are refused "
+ "on `backend: mlx` for SFT, DPO, ORPO and SimPO"
+ ) in flat
+
+ def test_the_doctor_table_has_no_pattern_rows(self) -> None:
+ # A field refused at load must not also be a doctor row (#958, #1330).
+ fields = {entry.field for entries in REGISTRY.values() for entry in entries}
+ assert not {"training.lora.rank_pattern", "training.lora.alpha_pattern"} & fields