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
"""#798 — the MoE flags only ever worked on SFT.
``moe_lora`` picks LoRA targets that cover the expert FFNs. Only ``sft`` and
``pretrain`` (and ``tts`` through ``super()``) read it, yet 8 DPO and 7 GRPO
shipped recipes set it, so those recipes trained attention-only LoRA while
saying otherwise. ``moe_expert_quant`` and ``train_router_only`` are read by
the SFT path only, and ``moe_aux_loss_coeff`` by SFT and pretrain.
The ruling on the issue was (b): fix the recipes rather than document that they
do not work. So the five preference/RL trainers wire ``moe_lora``, and the
flags no trainer outside a named list reads are refused at config load.
The wiring tests drive each trainer's real ``_setup_transformers`` over a real
tiny ``Qwen3MoeForCausalLM`` with real peft. Only the loaders are stubbed.
"""
from __future__ import annotations
import pathlib
from types import SimpleNamespace
import pytest
from soup_cli.config.loader import load_config_from_string
torch = pytest.importorskip("torch")
pytest.importorskip("peft")
transformers = pytest.importorskip("transformers")
_MOE_TASKS = ("dpo", "kto", "orpo", "simpo", "grpo")
#: The per-task minimum a config needs, beyond base/data.
_TASK_YAML = {
"dpo": ("dpo", ""),
"kto": ("kto", ""),
"orpo": ("dpo", ""),
"simpo": ("dpo", ""),
"grpo": ("alpaca", " reward_fn: length\n"),
# sft is not in _MOE_TASKS (it always read the flag); it is here so the
# dropout refusal can be driven through the path #798 assumed worked.
"sft": ("alpaca", ""),
}
def _tiny_moe():
"""A real Qwen3-MoE, ~10k parameters. Experts are fused 3-D weights here
(``mlp.experts.gate_up_proj``), which is what peft adapts."""
from transformers import Qwen3MoeConfig, Qwen3MoeForCausalLM
return Qwen3MoeForCausalLM(
Qwen3MoeConfig(
vocab_size=64,
hidden_size=16,
intermediate_size=32,
moe_intermediate_size=16,
num_hidden_layers=1,
num_attention_heads=2,
num_key_value_heads=1,
num_experts=4,
num_experts_per_tok=2,
decoder_sparse_step=1,
max_position_embeddings=64,
)
)
def _config(task: str, *, moe_lora: bool, extra: str = "", dropout: float = 0.0) -> object:
data_format, training_extra = _TASK_YAML[task]
return load_config_from_string(
f"base: org/tiny-moe\n"
f"task: {task}\n"
f"backend: transformers\n"
f"data:\n train: x.jsonl\n format: {data_format}\n"
f"training:\n"
f" quantization: none\n"
f" moe_lora: {'true' if moe_lora else 'false'}\n"
f" lora:\n r: 4\n alpha: 8\n dropout: {dropout}\n"
f"{training_extra}{extra}"
)
_WRAPPERS = {
"dpo": ("soup_cli.trainer.dpo", "DPOTrainerWrapper"),
"kto": ("soup_cli.trainer.kto", "KTOTrainerWrapper"),
"orpo": ("soup_cli.trainer.orpo", "ORPOTrainerWrapper"),
"simpo": ("soup_cli.trainer.simpo", "SimPOTrainerWrapper"),
"grpo": ("soup_cli.trainer.grpo", "GRPOTrainerWrapper"),
"sft": ("soup_cli.trainer.sft", "SFTTrainerWrapper"),
}
_SMALL = dict(
vocab_size=64,
hidden_size=16,
num_hidden_layers=1,
num_attention_heads=2,
num_key_value_heads=1,
)
def _stand_in(arch):
"""A tiny real model per MoE family, for the per-architecture evidence.
Only families with a config class in the installed transformers can be built;
`mistral-large-3` and `kimi-k2.x` have none here, and the PR names them as
untested rather than implying coverage.
"""
import transformers as tf
if arch == "qwen3_moe":
return _tiny_moe()
if arch == "mixtral":
return tf.MixtralForCausalLM(tf.MixtralConfig(
**_SMALL, intermediate_size=32, num_local_experts=4, num_experts_per_tok=2))
if arch == "minimax":
return tf.MiniMaxForCausalLM(tf.MiniMaxConfig(
**_SMALL, intermediate_size=32, num_local_experts=4, num_experts_per_tok=2))
if arch == "deepseek_v3":
return tf.DeepseekV3ForCausalLM(tf.DeepseekV3Config(
**_SMALL, intermediate_size=32, moe_intermediate_size=16, n_routed_experts=4,
num_experts_per_tok=2, n_shared_experts=1, first_k_dense_replace=0,
n_group=1, topk_group=1))
if arch == "glm4_moe":
return tf.Glm4MoeForCausalLM(tf.Glm4MoeConfig(
**_SMALL, intermediate_size=32, moe_intermediate_size=16, n_routed_experts=4,
num_experts_per_tok=2, n_shared_experts=1, first_k_dense_replace=0,
n_group=1, topk_group=1))
raise KeyError(arch)
_MOE_STAND_INS = {
arch: (lambda a=arch: _stand_in(a))
for arch in ("qwen3_moe", "deepseek_v3", "glm4_moe", "mixtral", "minimax")
}
def _tiny_dense():
"""A dense Qwen3 of the same size: the control for "MoE only"."""
from transformers import Qwen3Config, Qwen3ForCausalLM
return Qwen3ForCausalLM(
Qwen3Config(
vocab_size=64,
hidden_size=16,
intermediate_size=32,
num_hidden_layers=1,
num_attention_heads=2,
num_key_value_heads=1,
max_position_embeddings=64,
)
)
def _attach_lora(
task: str, monkeypatch, *, moe_lora: bool, dense=False, expect_failure=False,
dropout: float = 0.0,
):
"""Run the trainer's own ``_setup_transformers`` far enough to attach LoRA.
The model loader and tokenizer are stubbed; ``get_peft_model`` and the
target-module resolution are the real ones, which is the point.
"""
import importlib
module = importlib.import_module(_WRAPPERS[task][0])
wrapper_cls = getattr(module, _WRAPPERS[task][1])
tokenizer = SimpleNamespace(pad_token=None, eos_token="</s>", pad_token_id=0)
monkeypatch.setattr(
transformers.AutoTokenizer, "from_pretrained", lambda *_a, **_k: tokenizer
)
build = _tiny_dense if dense else _tiny_moe
monkeypatch.setattr(
transformers.AutoModelForCausalLM, "from_pretrained", lambda *_a, **_k: build()
)
cfg = _config(task, moe_lora=moe_lora, dropout=dropout)
wrapper = object.__new__(wrapper_cls)
wrapper.config = cfg
wrapper.device = "cpu"
wrapper._trust_remote_code = False
wrapper.model = None
wrapper.tokenizer = None
try:
wrapper._setup_transformers(cfg, cfg.training)
except ValueError:
# peft's "no target_modules" refusal: the control asserts it.
if expect_failure:
raise
raise
except Exception as exc: # noqa: BLE001 — setup continues past the LoRA attach
if not _adapted(wrapper.model or object()):
raise AssertionError(f"{task}: setup failed before LoRA attach: {exc!r}") from exc
return wrapper.model
def _adapted(model) -> list[str]:
if not hasattr(model, "named_modules"):
return []
return sorted(
name.rsplit(".lora_A", 1)[0]
for name, _ in model.named_modules()
if name.endswith("lora_A")
)
class TestMoeLoraReachesTheExpertFfns:
@pytest.mark.parametrize("task", _MOE_TASKS)
def test_moe_lora_true_adapts_the_experts(self, task, monkeypatch):
"""The 15 shipped DPO/GRPO recipes say moe_lora: true and trained
attention-only LoRA."""
adapted = _adapted(_attach_lora(task, monkeypatch, moe_lora=True))
experts = [name for name in adapted if "experts" in name]
assert experts, f"{task}: no expert module carries an adapter: {adapted}"
@pytest.mark.parametrize("task", _MOE_TASKS)
def test_without_the_flag_no_expert_is_adapted(self, task, monkeypatch):
"""The control the ruling asked for: ``moe_lora`` is what reaches the experts.
Until #1070 this asserted the attach FAILED -- on a fused-expert Qwen3-MoE,
``target_modules: auto`` resolved to None and peft refused. #1102 maps
``qwen3_moe``'s attention projections, so ``auto`` now attaches, and it
attaches attention-only. That keeps the control's point rather than
dropping it: the experts are adapted only when ``moe_lora`` asks for them,
and the companion test above proves it does."""
adapted = _adapted(_attach_lora(task, monkeypatch, moe_lora=False))
assert adapted, f"{task}: target_modules: auto attached nothing"
assert not [n for n in adapted if "experts" in n], (
f"{task}: experts adapted without moe_lora: {adapted}"
)
@pytest.mark.parametrize("task", _MOE_TASKS)
def test_a_non_moe_base_is_untouched_by_the_flag(self, task, monkeypatch):
"""The other control: the wiring must not change a dense model's targets,
whatever the flag says."""
adapted_off = _adapted(_attach_lora(task, monkeypatch, moe_lora=False, dense=True))
adapted_on = _adapted(_attach_lora(task, monkeypatch, moe_lora=True, dense=True))
assert adapted_off == adapted_on, (adapted_off, adapted_on)
assert adapted_on, "the dense control adapted nothing"
#: The tasks whose trainers read the expert knobs / the aux-loss coefficient.
#: Written out rather than imported so a member silently leaving the schema's
#: frozenset fails ``test_the_allowlists_are_the_ones_these_tests_cover``
#: instead of quietly shrinking the parametrisations below.
_EXPECTED_EXPERT_KNOB_TASKS = {"sft", "tts"}
_EXPECTED_AUX_LOSS_TASKS = {"sft", "tts", "pretrain"}
#: What each of those tasks needs on top of a bare config to load at all.
_TASK_PREAMBLE = {
"sft": "data:\n train: x.jsonl\n",
"pretrain": "data:\n train: x.jsonl\n",
"tts": "modality: audio_out\ndata:\n train: x.jsonl\n",
}
_TASK_TRAINING = {
"sft": "",
"pretrain": "",
"tts": " tts_family: orpheus\n",
}
class TestTheFlagsNoTrainerReadsAreRefused:
@pytest.mark.parametrize("task", ["dpo", "grpo", "kto", "pretrain"])
@pytest.mark.parametrize(
"knob", [" moe_expert_quant: nf4\n", " train_router_only: true\n"]
)
def test_sft_only_knobs_are_refused_off_sft(self, task, knob):
with pytest.raises(ValueError) as excinfo:
load_config_from_string(
f"base: org/m\ntask: {task}\n"
f"data:\n train: x.jsonl\n format: {_TASK_YAML.get(task, ('alpaca', ''))[0]}\n"
# dropout 0 so the #798 dropout refusal does not answer first:
# this test is about the task, not about the dropout.
f"training:\n moe_lora: true\n lora:\n dropout: 0.0\n{knob}"
+ (" reward_fn: length\n" if task == "grpo" else "")
)
message = str(excinfo.value)
assert task in message
assert "sft" in message
@pytest.mark.parametrize("knob", ["moe_expert_quant: nf4", "train_router_only: true"])
@pytest.mark.parametrize("task", sorted(_EXPECTED_EXPERT_KNOB_TASKS))
def test_the_tasks_that_read_them_still_accept_them(self, task, knob):
"""Every member of the allowlist, not just ``sft``. Dropping ``tts`` from
``_MOE_EXPERT_KNOB_TASKS`` survived when this covered ``sft`` alone: the
refusal above only proves the tasks that are NOT on the list."""
cfg = load_config_from_string(
f"base: org/m\ntask: {task}\n{_TASK_PREAMBLE[task]}"
f"training:\n moe_lora: true\n lora:\n dropout: 0.0\n"
f"{_TASK_TRAINING[task]} {knob}\n"
)
assert cfg.task == task
@pytest.mark.parametrize("task", ["dpo", "grpo"])
def test_a_non_default_aux_loss_coeff_is_refused(self, task):
with pytest.raises(ValueError, match="moe_aux_loss_coeff"):
load_config_from_string(
f"base: org/m\ntask: {task}\n"
f"data:\n train: x.jsonl\n format: {_TASK_YAML[task][0]}\n"
"training:\n moe_aux_loss_coeff: 0.05\n"
+ (" reward_fn: length\n" if task == "grpo" else "")
)
@pytest.mark.parametrize("task", ["dpo", "grpo"])
def test_the_default_aux_loss_coeff_still_loads(self, task):
"""Every shipped DPO/GRPO MoE recipe writes the default 0.01 explicitly,
and a dumped config writes it too: refusing that would break them."""
cfg = load_config_from_string(
f"base: org/m\ntask: {task}\n"
f"data:\n train: x.jsonl\n format: {_TASK_YAML[task][0]}\n"
"training:\n moe_aux_loss_coeff: 0.01\n"
+ (" reward_fn: length\n" if task == "grpo" else "")
)
assert cfg.training.moe_aux_loss_coeff == 0.01
@pytest.mark.parametrize("task", sorted(_EXPECTED_AUX_LOSS_TASKS))
def test_a_non_default_aux_loss_coeff_is_accepted_where_it_is_read(self, task):
"""Every member of the allowlist. ``tts`` was unpinned here too -- removing
it from ``_MOE_AUX_LOSS_TASKS`` survived while this covered sft and
pretrain only."""
cfg = load_config_from_string(
f"base: org/m\ntask: {task}\n{_TASK_PREAMBLE[task]}"
f"training:\n{_TASK_TRAINING[task]} moe_aux_loss_coeff: 0.05\n"
)
assert cfg.training.moe_aux_loss_coeff == 0.05
def test_the_allowlists_are_the_ones_these_tests_cover(self):
"""The parametrisations above read the schema's own frozensets, so they
would follow a member being removed instead of failing. These pin the
membership itself, in both directions."""
from soup_cli.config.schema import _MOE_AUX_LOSS_TASKS, _MOE_EXPERT_KNOB_TASKS
assert set(_MOE_EXPERT_KNOB_TASKS) == _EXPECTED_EXPERT_KNOB_TASKS
assert set(_MOE_AUX_LOSS_TASKS) == _EXPECTED_AUX_LOSS_TASKS
class TestShippedConfigs:
def test_every_recipe_still_loads(self):
from soup_cli.recipes.catalog import RECIPES
from tests.recipe_contracts import load_catalog_config
for name, recipe in RECIPES.items():
load_catalog_config(recipe), name
def test_the_moe_recipes_are_the_ones_this_issue_names(self):
"""17: 9 dpo + 8 grpo (including deepseek-v4-pro-dpo and deepseek-v4-pro-grpo)."""
import yaml
from soup_cli.recipes.catalog import RECIPES
tasks = []
for recipe in RECIPES.values():
cfg = yaml.safe_load(recipe.yaml_str)
training = cfg.get("training") or {}
if training.get("moe_lora") and cfg.get("task") in _MOE_TASKS:
tasks.append(cfg["task"])
# #1145 removed mistral-large-3-dpo (its repo has no config.json) and
# minimax-m3-dpo (DPO cannot build its VL wrapper): 9 -> 7 dpo.
assert sorted(tasks) == ["dpo"] * 7 + ["grpo"] * 8, sorted(tasks)
class TestTheDropoutConstraint:
"""peft's ParamWrapper refuses dropout on FUSED MoE experts.
Checked against the model, not at config load. The first version of this
branch refused ``moe_lora`` + non-zero dropout in the schema, which is wrong
in two directions: it fired for a dense base, where the flag is a documented
no-op and nothing would have broken, and it fired ahead of more specific
validators, so ``stream_layers`` conflicts started reporting a dropout
problem instead (tests/test_v07200.py::TestStreamMutualExclusions). At load
time the model is a string; whether its experts are fused is not knowable.
"""
def _tcfg(self, dropout):
return SimpleNamespace(moe_lora=True, lora=SimpleNamespace(dropout=dropout))
def test_fused_experts_plus_dropout_is_refused(self):
from soup_cli.utils.moe import resolve_moe_lora_targets
with pytest.raises(ValueError) as excinfo:
resolve_moe_lora_targets(_tiny_moe(), self._tcfg(0.05), ["q_proj"])
message = str(excinfo.value)
assert "lora.dropout: 0.0" in message
# peft's own words, or the rule reads as arbitrary and the first thing a
# user does is set the dropout back (#798 ruling).
assert "lora.ParamWrapper does not work with lora_dropout != 0" in message
def test_the_same_model_with_dropout_zero_gets_the_expert_targets(self):
from soup_cli.utils.moe import resolve_moe_lora_targets
targets = resolve_moe_lora_targets(_tiny_moe(), self._tcfg(0.0), ["q_proj"])
assert any("proj" in t for t in targets) and targets != ["q_proj"]
def test_a_dense_model_with_dropout_is_not_refused(self):
"""The control: a dense base has no fused experts, peft is happy, and
refusing it was the bug in the first version of this branch."""
from soup_cli.utils.moe import resolve_moe_lora_targets
assert resolve_moe_lora_targets(
_tiny_dense(), self._tcfg(0.05), ["q_proj"]
) == ["q_proj"]
def test_the_predicate_follows_peft_not_the_parameter_shapes(self):
"""Mixtral and MiniMax have the SAME fused 3-D expert parameters and the
same module structure as Qwen3-MoE, and peft attaches to them happily at
dropout 0.05. A model-wide "are there fused expert params" scan -- the
first version of this check, and what #1074's review caught -- refuses
those two for a reason that does not apply to them.
What actually differs is inside peft: its v4->v5 checkpoint conversion
rewrites target_modules into target_parameters only for model types that
have a conversion mapping, and only that rewrite produces the
ParamWrapper which refuses dropout.
"""
from soup_cli.utils.moe import (
get_moe_target_modules,
peft_routes_lora_to_fused_params,
)
routed, fused_params = {}, {}
for name, build in _MOE_STAND_INS.items():
model = build()
targets = get_moe_target_modules(model)
routed[name] = peft_routes_lora_to_fused_params(model, targets)
fused_params[name] = sorted({
param_name.rsplit(".", 1)[-1]
for param_name, param in model.named_parameters()
if "expert" in param_name.lower() and param.ndim == 3
})
assert routed == {
"qwen3_moe": True,
"deepseek_v3": True,
"glm4_moe": True,
"mixtral": False,
"minimax": False,
}, routed
# The control that makes the point: every one of them HAS fused 3-D
# expert parameters, under the same names.
assert all(names == ["down_proj", "gate_up_proj"] for names in fused_params.values()), (
fused_params
)
@pytest.mark.parametrize("arch", ["mixtral", "minimax"])
def test_an_architecture_peft_does_not_route_is_refused_since_1421(self, arch):
"""Until #1421 these two were NOT refused: peft's conversion never routed
their targets onto the fused experts, so the attach at dropout 0.05
succeeded -- and adapted no experts. Now ``moe_lora`` names the fused
parameters itself, so the experts are reached on these families too, and
peft's ``ParamWrapper`` refuses dropout there exactly as on Qwen3-MoE.
``test_peft_really_accepts_those_two_at_dropout`` below still holds for a
module-only attach, which is what it measures."""
from soup_cli.utils.moe import resolve_moe_lora_targets
model = _MOE_STAND_INS[arch]()
with pytest.raises(ValueError, match="ParamWrapper"):
resolve_moe_lora_targets(model, self._tcfg(0.05), ["q_proj"])
@pytest.mark.parametrize("arch", ["mixtral", "minimax"])
def test_peft_really_accepts_those_two_at_dropout(self, arch):
"""Not taken from the review on trust: the attach Soup now allows."""
from peft import LoraConfig, TaskType, get_peft_model
from soup_cli.utils.moe import get_moe_target_modules
model = _MOE_STAND_INS[arch]()
get_peft_model(model, LoraConfig(
r=4, lora_dropout=0.05, target_modules=get_moe_target_modules(model),
task_type=TaskType.CAUSAL_LM,
))
def test_a_stub_model_with_peft_patched_out_is_never_refused(self, monkeypatch):
"""The shape `tests/test_pretrain.py` actually uses, which caught this.
That suite stubs the model AND patches `peft.LoraConfig`, so the probe
built a MagicMock config whose `target_parameters` is truthy for any
model -- and a stub with no experts got refused. Patching LoraConfig is
the load-bearing half: with the real class a bare MagicMock returns None
and the bug hides, which is how my first version of this test passed
while proving nothing.
"""
from unittest.mock import MagicMock
import peft
from soup_cli.utils.moe import peft_routes_lora_to_fused_params
monkeypatch.setattr(peft, "LoraConfig", MagicMock())
assert peft_routes_lora_to_fused_params(MagicMock(), ["down_proj"]) is False
@pytest.mark.parametrize("arch", ["qwen3_moe", "deepseek_v3", "glm4_moe"])
def test_the_routed_architectures_are_refused(self, arch):
from soup_cli.utils.moe import resolve_moe_lora_targets
with pytest.raises(ValueError, match="ParamWrapper"):
resolve_moe_lora_targets(_MOE_STAND_INS[arch](), self._tcfg(0.05), ["q_proj"])
@pytest.mark.parametrize("task", ["dpo", "sft"] )
def test_the_refusal_reaches_a_real_trainer_setup(self, task, monkeypatch):
"""End to end through the trainer's own setup, not just the helper.
Asserts SOUP's wording, not peft's: with the helper's refusal removed,
peft raises its own ParamWrapper error from the same line, so matching
on "ParamWrapper" alone passes whether or not the wiring is there.
Found by mutation N2.
"""
if task == "sft":
pytest.importorskip("trl")
with pytest.raises(ValueError) as excinfo:
_attach_lora(task, monkeypatch, moe_lora=True, dropout=0.05,
expect_failure=True)
message = str(excinfo.value)
assert "training.moe_lora=true needs training.lora.dropout: 0.0" in message
assert "lora.ParamWrapper does not work with lora_dropout != 0" in message
def test_the_config_itself_still_loads(self):
"""Deliberate: no load-time refusal. If someone re-adds one, this fails
and the trade-off above gets read again rather than rediscovered."""
cfg = load_config_from_string(
"base: org/m\ntask: sft\ndata: {train: x.jsonl}\n"
"training: {moe_lora: true, lora: {dropout: 0.05}}\n"
)
assert cfg.training.lora.dropout == 0.05
def test_dropout_is_untouched_without_moe_lora(self):
"""The rule is about moe_lora, not about dropout."""
cfg = load_config_from_string(
"base: org/m\ntask: sft\ndata: {train: x.jsonl}\n"
"training: {lora: {dropout: 0.05}}\n"
)
assert cfg.training.lora.dropout == 0.05
def test_peft_really_refuses_it(self):
"""Not taken on trust: the constraint this rule exists for, reproduced.
A dropout LoRA over the fused experts raises inside peft; the same attach
with dropout 0 succeeds and adapts the expert module."""
from peft import LoraConfig, TaskType, get_peft_model
targets = ["q_proj", "k_proj", "v_proj", "o_proj", "gate_proj", "up_proj", "down_proj"]
with pytest.raises(ValueError, match="ParamWrapper"):
get_peft_model(
_tiny_moe(),
LoraConfig(r=4, lora_dropout=0.05, target_modules=targets,
task_type=TaskType.CAUSAL_LM),
)
model = get_peft_model(
_tiny_moe(),
LoraConfig(r=4, lora_dropout=0.0, target_modules=targets,
task_type=TaskType.CAUSAL_LM),
)
assert [n for n in _adapted(model) if "experts" in n]
def _stream_tcfg(dropout):
"""A training config as the streamed setup path holds it."""
return SimpleNamespace(
moe_lora=True, lora=SimpleNamespace(dropout=dropout, target_modules="auto")
)
class TestTheStreamedPathUsesTheSameHelper:
"""``trainer/stream_setup.py`` kept its own copy of the moe_lora block, so the
streamed path was the one path with no dropout refusal -- "one helper for
every trainer" was not quite true. Flagged by the maintainer on #1074.
It builds a meta skeleton it then deletes, so the helper is called while that
probe is alive rather than at the attach; these pin that it is called at all,
with the probe, and that its answer is what reaches the LoRA config.
"""
def test_the_source_has_no_second_copy_of_the_block(self):
"""The mutation this guards is re-inlining ``get_moe_target_modules``
here, which reintroduces exactly the gap that was reported."""
import pathlib
source = (
pathlib.Path(__file__).resolve().parents[1]
/ "src" / "soup_cli" / "trainer" / "stream_setup.py"
).read_text(encoding="utf-8")
assert "resolve_moe_lora_targets" in source
assert "get_moe_target_modules" not in source, (
"the streamed path is resolving targets itself again"
)
def test_the_helper_refuses_the_streamed_config_too(self):
"""The behaviour behind it: the helper the streamed path now calls is the
one that refuses a non-zero dropout on fused experts, so the streamed path
inherits the refusal rather than reaching peft's message."""
from soup_cli.utils.moe import resolve_moe_lora_targets
with pytest.raises(ValueError, match="lora.dropout"):
resolve_moe_lora_targets(_tiny_moe(), _stream_tcfg(0.05), None)
def test_and_still_resolves_targets_at_zero_dropout(self):
from soup_cli.utils.moe import resolve_moe_lora_targets
targets = resolve_moe_lora_targets(_tiny_moe(), _stream_tcfg(0.0), None)
assert targets, "the streamed path would get no MoE targets at all"
class TestTheSweepInteraction:
"""`soup sweep` can generate the combination this PR refuses (#1074 ask 4).
`commands/sweep.py`'s parameter map exposes `moe_aux_loss_coeff`, so a grid
over it on `dpo` or `grpo` now hard-fails at config load for every non-
default point. The values are user-typed rather than Soup-generated, so the
warn-then-refuse staging for generated values does not cover it -- but the
interaction should be a known fact rather than a surprise.
"""
def test_the_sweep_shortcut_writes_the_refused_knob(self):
"""Driven through the function rather than reading its dict: the map is
a local in `_set_nested_param`, and what matters is where a sweep point
lands, not how the table is spelled."""
from soup_cli.commands.sweep import _set_nested_param
written = _set_nested_param({}, "moe_aux_loss_coeff", 0.05)
assert written["training"]["moe_aux_loss_coeff"] == 0.05
def test_a_non_default_point_on_dpo_is_refused_and_the_default_is_not(self):
yaml_ = ("base: org/m\ntask: dpo\n"
"data:\n train: x.jsonl\n format: dpo\n"
"training:\n moe_aux_loss_coeff: {}\n")
assert load_config_from_string(yaml_.format("0.01")).training.moe_aux_loss_coeff == 0.01
with pytest.raises(ValueError, match="moe_aux_loss_coeff"):
load_config_from_string(yaml_.format("0.05"))
class TestPerArchitectureCoverage:
"""Which families the wiring actually reaches, measured (#1074 review ask 3).
The wiring is not uniform across MoE families, and saying so is the point:
a recipe that looks fixed and is not is worse than one that visibly fails.
"""
#: What the module names alone (`get_moe_target_modules` + a real peft
#: attach) reach per family, on tiny stand-ins: peft's own name conversion
#: decides it. Since #1421 the trainer path below adds the fused parameters
#: as `target_parameters`, and every family here gets its expert adapters.
MODULE_NAMES_ALONE = {
"qwen3_moe": True,
"deepseek_v3": True,
"glm4_moe": True,
"mixtral": False,
"minimax": False,
}
@pytest.mark.parametrize("arch", sorted(MODULE_NAMES_ALONE))
def test_expert_coverage_by_module_names_alone(self, arch):
from peft import LoraConfig, TaskType, get_peft_model
from soup_cli.utils.moe import get_moe_target_modules
model = _MOE_STAND_INS[arch]()
attached = get_peft_model(model, LoraConfig(
r=4, lora_dropout=0.0, target_modules=list(get_moe_target_modules(model)),
task_type=TaskType.CAUSAL_LM,
))
experts = [name for name in _adapted(attached) if "expert" in name.lower()]
assert bool(experts) is self.MODULE_NAMES_ALONE[arch], (arch, experts)
@pytest.mark.parametrize("arch", sorted(MODULE_NAMES_ALONE))
def test_the_trainer_path_reaches_the_experts_on_every_family(self, arch):
"""#1421: the two calls every MoE-wired trainer makes, then peft's attach.
The fused parameters travel on the resolved targets into the LoraConfig,
so Mixtral and MiniMax are no longer attention-only."""
from peft import get_peft_model
from soup_cli.utils.moe import resolve_moe_lora_targets
from soup_cli.utils.peft_wiring import build_lora_config
model = _MOE_STAND_INS[arch]()
tcfg = SimpleNamespace(moe_lora=True, lora=SimpleNamespace(
r=4, alpha=8, dropout=0.0, use_dora=False, use_rslora=False, use_vera=False,
rank_pattern=None, alpha_pattern=None, init_strategy="random",
))
targets = resolve_moe_lora_targets(model, tcfg, ["q_proj"], None)
attached = get_peft_model(
model, build_lora_config(tcfg.lora, target_modules=targets, task_type="CAUSAL_LM")
)
experts = [name for name in _adapted(attached) if "expert" in name.lower()]
assert experts, (arch, _adapted(attached))
def test_the_uncovered_families_are_named_in_the_docs(self):
"""`minimax-m3-sft` sets no `moe_lora` (it loads through SFT's vision
path, which never runs the MoE step), so it trains attention-only. That
has to be written down where a user looks, not only in a test.
(`minimax-m3-dpo` was removed in #1145: DPO cannot build the
`minimax_m3_vl` wrapper.)"""
from pathlib import Path
docs = (Path(__file__).resolve().parents[1]
/ "docs" / "performance-and-quantization.md").read_text(encoding="utf-8")
lowered = docs.lower()
assert "minimax-m3-sft" in lowered, (
"the recipe the wiring does not reach must be named in the docs"
)
assert "attention-only" in lowered, "and what they do instead"
class TestEveryMoeRecipeCanAttach:
"""Recipe 32 must not arrive broken on the day it ships (#798 ruling)."""
def test_every_recipe_that_sets_moe_lora_pins_dropout_zero(self):
import yaml
from soup_cli.recipes.catalog import RECIPES
offenders = []
for name, recipe in RECIPES.items():
training = yaml.safe_load(recipe.yaml_str).get("training") or {}
if not training.get("moe_lora"):
continue
dropout = (training.get("lora") or {}).get("dropout")
if dropout != 0.0:
offenders.append(f"{name}: lora.dropout={dropout!r}")
assert offenders == [], (
"a recipe with moe_lora: true and a non-zero lora.dropout cannot "
"attach LoRA at all (peft ParamWrapper): " + "; ".join(offenders)
)
def test_every_shipped_template_and_example_pins_dropout_zero(self):
"""``RECIPES`` is not everything Soup ships. ``src/soup_cli/templates``
feeds ``soup init --template`` and ``examples/configs`` is copy-paste
material, so a MoE config there fails at attach exactly as a recipe would
-- found by the maintainer on ``templates/moe.yaml``, which set
``moe_lora: true`` and inherited the 0.05 default."""
import yaml
root = pathlib.Path(__file__).resolve().parents[1]
roots = [
root / "src" / "soup_cli" / "templates",
root / "examples",
]
checked, offenders = [], []
for base in roots:
for path in sorted(base.rglob("*.yaml")):
try:
loaded = yaml.safe_load(path.read_text(encoding="utf-8"))
except yaml.YAMLError:
continue
if not isinstance(loaded, dict):
continue
training = loaded.get("training") or {}
if not isinstance(training, dict) or not training.get("moe_lora"):
continue
checked.append(path.relative_to(root).as_posix())
dropout = (training.get("lora") or {}).get("dropout")
if dropout != 0.0:
offenders.append(
f"{path.relative_to(root).as_posix()}: lora.dropout={dropout!r}"
)
assert checked, "no shipped template or example sets moe_lora -- the sweep broke"
assert offenders == [], (
"a shipped config with moe_lora: true and a non-zero lora.dropout "
"cannot attach LoRA at all (peft ParamWrapper): " + "; ".join(offenders)
)
def test_the_guard_sees_the_recipes_it_is_guarding(self):
"""A control: the loop above passes vacuously if nothing sets moe_lora."""
import yaml
from soup_cli.recipes.catalog import RECIPES
counted = sum(
1 for r in RECIPES.values()
if (yaml.safe_load(r.yaml_str).get("training") or {}).get("moe_lora")
)
# 33 until #1145 removed mistral-large-3-sft/-dpo and minimax-m3-dpo, and took
# moe_lora off minimax-m3-sft (SFT's vision path never reads it).
assert counted >= 29, counted