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
"""Tests for NEFTune (neftune_alpha) and rsLoRA (use_rslora) support."""
import typing
import pytest
from pydantic import ValidationError
from soup_cli.config.schema import (
NEFTUNE_APPLYING_TASKS,
LoraConfig,
SoupConfig,
TrainingConfig,
)
# ---------------------------------------------------------------------------
# NEFTune config tests
# ---------------------------------------------------------------------------
class TestNEFTuneConfig:
"""NEFTune config validation."""
def test_neftune_alpha_default_none(self):
"""neftune_alpha defaults to None."""
tcfg = TrainingConfig()
assert tcfg.neftune_alpha is None
def test_neftune_alpha_valid(self):
"""neftune_alpha accepts valid float."""
tcfg = TrainingConfig(neftune_alpha=5.0)
assert tcfg.neftune_alpha == 5.0
def test_neftune_alpha_zero(self):
"""neftune_alpha accepts 0 (disabled)."""
tcfg = TrainingConfig(neftune_alpha=0.0)
assert tcfg.neftune_alpha == 0.0
def test_neftune_alpha_max(self):
"""neftune_alpha accepts 50.0 (max)."""
tcfg = TrainingConfig(neftune_alpha=50.0)
assert tcfg.neftune_alpha == 50.0
def test_neftune_alpha_negative_rejected(self):
"""neftune_alpha rejects negative values."""
with pytest.raises(Exception):
TrainingConfig(neftune_alpha=-1.0)
def test_neftune_alpha_too_high_rejected(self):
"""neftune_alpha rejects values > 50."""
with pytest.raises(Exception):
TrainingConfig(neftune_alpha=51.0)
def test_neftune_in_full_config(self):
"""neftune_alpha works in full SoupConfig."""
cfg = SoupConfig(
base="test-model",
data={"train": "./data.jsonl"},
training={"neftune_alpha": 5.0},
)
assert cfg.training.neftune_alpha == 5.0
# ---------------------------------------------------------------------------
# NEFTune trainer integration tests
# ---------------------------------------------------------------------------
class TestNEFTuneTrainer:
"""NEFTune trainer argument passing."""
def test_sft_neftune_in_training_kwargs(self):
"""SFT trainer includes neftune_noise_alpha in training kwargs."""
tcfg = TrainingConfig(neftune_alpha=5.0)
assert tcfg.neftune_alpha == 5.0
# Verify the pattern: if neftune_alpha is not None, it should be passed
training_kwargs = {}
if tcfg.neftune_alpha is not None:
training_kwargs["neftune_noise_alpha"] = tcfg.neftune_alpha
assert training_kwargs["neftune_noise_alpha"] == 5.0
def test_neftune_none_not_passed(self):
"""When neftune_alpha is None, neftune_noise_alpha is NOT added."""
tcfg = TrainingConfig()
training_kwargs = {}
if tcfg.neftune_alpha is not None:
training_kwargs["neftune_noise_alpha"] = tcfg.neftune_alpha
assert "neftune_noise_alpha" not in training_kwargs
def test_dpo_neftune_forwarding(self):
"""DPO trainer config includes neftune_noise_alpha when set."""
tcfg = TrainingConfig(neftune_alpha=10.0)
extra = (
{"neftune_noise_alpha": tcfg.neftune_alpha}
if tcfg.neftune_alpha is not None else {}
)
assert extra == {"neftune_noise_alpha": 10.0}
def test_kto_neftune_forwarding(self):
"""KTO trainer config includes neftune_noise_alpha when set."""
tcfg = TrainingConfig(neftune_alpha=7.5)
extra = (
{"neftune_noise_alpha": tcfg.neftune_alpha}
if tcfg.neftune_alpha is not None else {}
)
assert extra == {"neftune_noise_alpha": 7.5}
def test_orpo_neftune_forwarding(self):
"""ORPO trainer config includes neftune_noise_alpha when set."""
tcfg = TrainingConfig(neftune_alpha=3.0)
extra = (
{"neftune_noise_alpha": tcfg.neftune_alpha}
if tcfg.neftune_alpha is not None else {}
)
assert extra == {"neftune_noise_alpha": 3.0}
def test_simpo_neftune_forwarding(self):
"""SimPO trainer config includes neftune_noise_alpha when set."""
tcfg = TrainingConfig(neftune_alpha=15.0)
extra = (
{"neftune_noise_alpha": tcfg.neftune_alpha}
if tcfg.neftune_alpha is not None else {}
)
assert extra == {"neftune_noise_alpha": 15.0}
def test_ipo_neftune_forwarding(self):
"""IPO trainer config includes neftune_noise_alpha when set."""
tcfg = TrainingConfig(neftune_alpha=2.0)
extra = (
{"neftune_noise_alpha": tcfg.neftune_alpha}
if tcfg.neftune_alpha is not None else {}
)
assert extra == {"neftune_noise_alpha": 2.0}
# ---------------------------------------------------------------------------
# NEFTune sweep integration tests
# ---------------------------------------------------------------------------
class TestNEFTuneSweep:
"""NEFTune sweep parameter support."""
def test_neftune_in_sweep_shortcuts(self):
"""neftune_alpha is a valid sweep parameter."""
from soup_cli.commands.sweep import _set_nested_param
config_dict = {
"base": "test",
"task": "sft",
"data": {"train": "./data.jsonl"},
"training": {},
}
_set_nested_param(config_dict, "neftune_alpha", 5.0)
assert config_dict["training"]["neftune_alpha"] == 5.0
# ---------------------------------------------------------------------------
# rsLoRA config tests
# ---------------------------------------------------------------------------
class TestRsLoRAConfig:
"""rsLoRA config validation."""
def test_rslora_default_false(self):
"""use_rslora defaults to False."""
lora = LoraConfig()
assert lora.use_rslora is False
def test_rslora_enable(self):
"""use_rslora can be enabled."""
lora = LoraConfig(use_rslora=True)
assert lora.use_rslora is True
def test_rslora_in_full_config(self):
"""use_rslora works in full SoupConfig."""
cfg = SoupConfig(
base="test-model",
data={"train": "./data.jsonl"},
training={"lora": {"use_rslora": True}},
)
assert cfg.training.lora.use_rslora is True
def test_rslora_with_dora(self):
"""use_rslora can be used alongside use_dora."""
lora = LoraConfig(use_rslora=True, use_dora=True)
assert lora.use_rslora is True
assert lora.use_dora is True
# ---------------------------------------------------------------------------
# rsLoRA sweep integration tests
# ---------------------------------------------------------------------------
class TestRsLoRATrainer:
"""rsLoRA trainer integration — use_rslora flows to LoraConfig."""
def test_rslora_in_lora_config_kwargs(self):
"""use_rslora is passed to peft.LoraConfig constructor."""
lcfg = LoraConfig(use_rslora=True, r=16, alpha=32)
# Verify the value that would be passed to peft.LoraConfig
assert lcfg.use_rslora is True
kwargs = {
"r": lcfg.r,
"lora_alpha": lcfg.alpha,
"lora_dropout": lcfg.dropout,
"use_dora": lcfg.use_dora,
"use_rslora": lcfg.use_rslora,
}
assert kwargs["use_rslora"] is True
assert kwargs["use_dora"] is False
def test_rslora_false_in_lora_config_kwargs(self):
"""use_rslora=False is passed correctly."""
lcfg = LoraConfig(use_rslora=False)
kwargs = {"use_rslora": lcfg.use_rslora}
assert kwargs["use_rslora"] is False
def test_rslora_with_all_tasks(self):
"""use_rslora works in config for every task type."""
for task in [
"sft", "dpo", "grpo", "ppo", "reward_model",
"kto", "orpo", "simpo", "ipo", "pretrain", "embedding",
]:
cfg = SoupConfig(
base="test-model",
task=task,
data={"train": "./data.jsonl"},
training={"lora": {"use_rslora": True}},
)
assert cfg.training.lora.use_rslora is True, f"Failed for task={task}"
# ---------------------------------------------------------------------------
# rsLoRA sweep integration tests
# ---------------------------------------------------------------------------
class TestRsLoRASweep:
"""rsLoRA sweep parameter support."""
def test_rslora_in_sweep_shortcuts(self):
"""use_rslora is a valid sweep parameter."""
from soup_cli.commands.sweep import _set_nested_param
config_dict = {
"base": "test",
"task": "sft",
"data": {"train": "./data.jsonl"},
"training": {"lora": {}},
}
_set_nested_param(config_dict, "use_rslora", True)
assert config_dict["training"]["lora"]["use_rslora"] is True
# ---------------------------------------------------------------------------
# NEFTune task-gate (issue #1820)
# ---------------------------------------------------------------------------
#: All tasks declared in the ``task`` Literal of SoupConfig, derived via
#: ``typing.get_args`` so adding a task to the schema Literal updates this.
ALL_TASKS: frozenset[str] = frozenset(
typing.get_args(SoupConfig.model_fields["task"].annotation),
)
#: NEFTUNE_APPLYING_TASKS must be a subset of ALL_TASKS.
assert NEFTUNE_APPLYING_TASKS.issubset(ALL_TASKS)
class TestNEFTuneTaskGate:
"""#1820: neftune_alpha is refused on tasks whose trainer never reads it."""
def _make_cfg(
self,
task: str,
neftune_alpha: float = 5.0,
**extra_training,
) -> SoupConfig:
"""Build a minimal SoupConfig with a given task and neftune_alpha.
Some tasks need extra fields to pass validation (tts needs modality,
preference needs preference_loss, classifier/reranker/cross_encoder
need num_labels, distill needs teacher_model). Those are passed via
*extra_training* so the caller can satisfy those preconditions.
"""
training_kw = {"neftune_alpha": neftune_alpha}
training_kw.update(extra_training)
modality = "text"
if task == "tts":
modality = "audio_out"
return SoupConfig(
base="test-model",
task=task,
modality=modality,
data={"train": "./data.jsonl"},
training=training_kw,
)
@pytest.mark.parametrize("task", sorted(NEFTUNE_APPLYING_TASKS))
def test_applying_tasks_accept_neftune_alpha(self, task):
"""Tasks in NEFTUNE_APPLYING_TASKS accept neftune_alpha without error."""
# preference needs preference_loss; tts needs audio_out modality
# and a tts_family.
extra: dict = {}
if task == "preference":
extra["preference_loss"] = "dpo"
if task == "tts":
extra["tts_family"] = "orpheus"
cfg = self._make_cfg(task, 5.0, **extra)
assert cfg.training.neftune_alpha == 5.0
@pytest.mark.parametrize("task", sorted(ALL_TASKS - NEFTUNE_APPLYING_TASKS))
def test_non_applying_tasks_reject_neftune_alpha(self, task):
"""Tasks NOT in NEFTUNE_APPLYING_TASKS reject neftune_alpha at load."""
# Some tasks need extra fields to reach the neftune gate.
extra: dict = {}
if task in ("classifier", "reranker", "cross_encoder"):
extra["num_labels"] = 2
if task == "distill":
extra["teacher_model"] = "teacher"
with pytest.raises(
ValidationError, match=rf"training\.neftune_alpha.*task='{task}'"
):
self._make_cfg(task, 5.0, **extra)
def test_mutation_check_drop_one_task(self, monkeypatch):
"""Mutation test: removing a task from NEFTUNE_APPLYING_TASKS fails.
Verifies that the validator uses the NEFTUNE_APPLYING_TASKS constant
(not a hardcoded set) by dropping one task and checking that the
config is then rejected for that task.
"""
import soup_cli.config.schema as schema_module
monkeypatch.setattr(
schema_module,
"NEFTUNE_APPLYING_TASKS",
NEFTUNE_APPLYING_TASKS - {"dpo"},
)
# dpo is no longer in the set, so neftune_alpha=5.0 should be refused.
with pytest.raises(
ValidationError, match=r"training\.neftune_alpha.*task='dpo'"
):
self._make_cfg("dpo", 5.0)
def test_neftune_alpha_zero_is_refused(self):
"""neftune_alpha=0.0 is refused on non-applying tasks (gate checks is not None)."""
with pytest.raises(
ValidationError, match=r"training\.neftune_alpha.*task='grpo'"
):
self._make_cfg("grpo", 0.0)
def test_applying_tasks_pinned(self):
"""NEFTUNE_APPLYING_TASKS is pinned literally — removing any task fails."""
assert NEFTUNE_APPLYING_TASKS == frozenset({
"sft", "tts", "dpo", "ipo", "kto", "orpo", "simpo", "bco", "preference",
})