Skip to content

Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.

21.4 KB
Raw Blame
"""transformers 5.1 dropped warnings_issued but trl still writes it unguarded; trainer.py wraps it."""

import ast
import dataclasses
import inspect
import os
from functools import wraps
from pathlib import Path

import pytest
import torch

ROOT = Path(__file__).resolve().parents[1]
SRC_PATH = ROOT / "unsloth" / "trainer.py"
SRC = SRC_PATH.read_text(encoding = "utf-8")


def _load(*names):
    """Exec the named top-level functions from trainer.py in a bare namespace."""
    tree = ast.parse(SRC)
    wanted = [n for n in tree.body if isinstance(n, ast.FunctionDef) and n.name in names]
    missing = set(names) - {n.name for n in wanted}
    assert not missing, f"not found in trainer.py: {sorted(missing)}"
    ns = {
        "os": os,
        "torch": torch,
        "inspect": inspect,
        "dataclasses": dataclasses,
        "wraps": wraps,
    }
    try:
        import trl
        from unsloth_zoo.utils import Version
        ns["trl"], ns["Version"] = trl, Version
    except Exception:  # pragma: no cover - only used by the integration tests
        pass
    exec(compile(ast.Module(body = wanted, type_ignores = []), str(SRC_PATH), "exec"), ns)
    return ns


GUARD = _load("_ensure_warnings_issued")["_ensure_warnings_issued"]


class _Bare(torch.nn.Module):
    """A module with no `warnings_issued`, exactly like transformers >= 5.1."""


def test_a_module_without_the_attribute_gets_a_dict():
    m = _Bare()
    with pytest.raises(AttributeError):
        m.warnings_issued
    GUARD(m)
    assert m.warnings_issued == {}


def test_the_dict_is_writable_the_way_trl_writes_it():
    m = _Bare()
    GUARD(m)
    m.warnings_issued["estimate_tokens"] = True
    assert m.warnings_issued == {"estimate_tokens": True}


def test_each_model_gets_its_own_dict():
    """A shared class-level dict would suppress the warning globally, which is
    a behaviour change rather than a compatibility fix."""
    a, b = _Bare(), _Bare()
    GUARD(a)
    GUARD(b)
    a.warnings_issued["estimate_tokens"] = True
    assert b.warnings_issued == {}


def test_an_existing_dict_is_left_exactly_as_it_was():
    """On transformers 4.x and 5.0 the attribute is already a dict, so the guard must be a no-op:
    same object, same contents, nothing rebound."""
    m = _Bare()
    original = {"estimate_tokens": True, "other": 1}
    m.warnings_issued = original
    GUARD(m)
    assert m.warnings_issued is original
    assert m.warnings_issued == {"estimate_tokens": True, "other": 1}


def test_a_non_dict_mapping_is_preserved_not_discarded():
    m = _Bare()
    m.warnings_issued = [("estimate_tokens", True)]
    GUARD(m)
    assert m.warnings_issued == {"estimate_tokens": True}


def test_an_uncoercible_value_becomes_an_empty_dict():
    """Better a usable empty dict than a TypeError from dict(3)."""
    m = _Bare()
    m.warnings_issued = 3
    GUARD(m)
    assert m.warnings_issued == {}


def test_running_twice_is_idempotent():
    m = _Bare()
    GUARD(m)
    m.warnings_issued["estimate_tokens"] = True
    GUARD(m)
    assert m.warnings_issued == {"estimate_tokens": True}


@pytest.mark.parametrize("value", [None, "Qwen/Qwen2.5-1.5B", 7, object()])
def test_non_modules_are_left_alone_without_raising(value):
    """trl accepts a repo id string and builds the model itself, so the guard must leave non-modules
    alone and never be the thing that raises."""
    GUARD(value)
    assert not hasattr(value, "warnings_issued")


def test_a_model_that_refuses_the_assignment_does_not_raise():
    """Whatever that model's problem is, trl should report it, not us."""

    class _Locked(torch.nn.Module):
        def __setattr__(self, name, value):
            if name == "warnings_issued":
                raise RuntimeError("no")
            super().__setattr__(name, value)

    GUARD(_Locked())


@dataclasses.dataclass
class _FakeConfig:
    learning_rate: float = 1e-4


class _FakeTrainer:
    """The first three lines of trl's GRPOTrainer.__init__, in effect."""

    def __init__(
        self,
        model = None,
        args = None,
        **kwargs,
    ):
        model.warnings_issued["estimate_tokens"] = True
        self.model = model
        self.args = args


def _wrapped():
    ns = _load(
        "_ensure_warnings_issued",
        "_resolve_trainer_params",
        "_route_unknown_trainer_kwargs",
        "_backwards_compatible_trainer",
    )
    if "trl" not in ns:
        pytest.skip("trl not installed")
    for name in (
        "classify_config_kwarg",
        "rename_source",
        "removal_source",
        "rename_value_is_unset",
    ):
        ns[name] = getattr(_rl_config_compat(), name)

    class T(_FakeTrainer):
        pass

    T.__init__ = ns["_backwards_compatible_trainer"](T, _FakeConfig)
    return T


def test_the_unwrapped_trainer_reproduces_the_reported_failure():
    """Without this, the tests below could pass against a bug that no longer
    exists and nobody would notice."""
    with pytest.raises(AttributeError, match = "warnings_issued"):
        _FakeTrainer(_Bare())


def test_the_wrapper_fixes_it_for_a_positional_model():
    t = _wrapped()(_Bare())
    assert t.model.warnings_issued == {"estimate_tokens": True}


def test_the_wrapper_fixes_it_for_a_keyword_model():
    t = _wrapped()(model = _Bare())
    assert t.model.warnings_issued == {"estimate_tokens": True}


def test_the_wrapper_fixes_it_on_the_args_rebuilding_path():
    """`new_init` has a second branch that rebuilds the config when `args` is
    passed. The guard must be reached from both, not just the short one."""
    t = _wrapped()(_Bare(), args = _FakeConfig())
    assert t.model.warnings_issued == {"estimate_tokens": True}


def test_no_model_at_all_still_reaches_the_wrapped_init():
    """The guard must not swallow, or pre-empt, trl's own argument errors."""
    with pytest.raises(AttributeError):
        _wrapped()()


def _new_init_body():
    tree = ast.parse(SRC)
    for node in ast.walk(tree):
        if (
            isinstance(node, ast.FunctionDef)
            and node.name == "new_init"
            and any(
                isinstance(p, ast.FunctionDef) and p.name == "_backwards_compatible_trainer"
                for p in ast.walk(tree)
            )
        ):
            src = ast.get_source_segment(SRC, node)
            if src and "original_init(self" in src:
                return src
    raise AssertionError("new_init not found")


def test_the_guard_runs_before_the_wrapped_init():
    """After it, the AttributeError has already been raised."""
    body = _new_init_body()
    assert body.index("_ensure_warnings_issued(") < body.index("original_init(self")


def test_the_guard_is_outside_the_version_branch():
    """`new_init` only rebuilds the config when `args` is in kwargs. A guard
    nested in that branch would miss every positional-args call."""
    ns = ast.parse(SRC)
    found = []
    for node in ast.walk(ns):
        if isinstance(node, ast.FunctionDef) and node.name == "new_init":
            for stmt in node.body:
                for sub in ast.walk(stmt):
                    if (
                        isinstance(sub, ast.Call)
                        and getattr(sub.func, "id", None) == "_ensure_warnings_issued"
                    ):
                        found.append(type(stmt).__name__)
    assert "Expr" in found, f"guard is nested, not a top-level statement: {found}"


def test_the_generated_compiled_guard_is_still_there():
    """This change adds a second guard on the eager path. It must not have been
    made by moving the compiled one, which would regress the default path."""
    rl = (ROOT / "unsloth" / "models" / "rl.py").read_text(encoding = "utf-8")
    assert "warnings_issued_check" in rl
    assert "model.warnings_issued = {}" in rl


def test_trl_still_writes_the_attribute_unconditionally():
    """A signal, not a requirement: asserting trl still writes it would fail the file on trl >= 1.0."""
    trl = pytest.importorskip("trl")
    grpo = Path(trl.__file__).parent / "trainer" / "grpo_trainer.py"
    if not grpo.exists():
        pytest.skip("trl layout changed")
    text = grpo.read_text(encoding = "utf-8")
    if 'model.warnings_issued["estimate_tokens"] = True' not in text:
        pytest.skip(f"trl {trl.__version__} no longer writes warnings_issued unguarded")


def test_the_installed_transformers_tells_us_which_side_of_5_1_we_are_on():
    """Checks both possible worlds behave as claimed rather than which version is installed: 4.x/5.0
    ship warnings_issued and 5.1+ do not, where the guard makes trl work."""
    transformers = pytest.importorskip("transformers")
    import transformers.modeling_utils as mu

    ships_it = "self.warnings_issued = {}" in Path(mu.__file__).read_text(encoding = "utf-8")
    version = tuple(int(x) for x in transformers.__version__.split(".")[:2])
    if version >= (5, 1):
        assert not ships_it, "5.1+ reinstated it; re-check whether this is needed"
    elif version < (5, 0) or version == (5, 0):
        assert ships_it, f"transformers {transformers.__version__} dropped it early"


def test_every_trl_trainer_that_writes_it_goes_through_the_wrapper():
    """Wrapper rule is XTrainer and XConfig in trl.trainer; a writer without a Config would slip through."""
    trl = pytest.importorskip("trl")
    import trl.trainer

    names = dir(trl.trainer)
    wrapped = {x[: -len("Trainer")] for x in names if x.endswith("Trainer")} & {
        x[: -len("Config")] for x in names if x.endswith("Config")
    }

    root = Path(trl.__file__).parent
    writers = set()
    for path in root.rglob("*_trainer.py"):
        if "experimental" in path.relative_to(root).parts:
            continue  # not exported from trl.trainer, so never wrapped by design
        try:
            text = path.read_text(encoding = "utf-8")
        except OSError:
            continue
        if 'model.warnings_issued["estimate_tokens"] = True' in text:
            if 'hasattr(model, "warnings_issued")' in text:
                continue  # trl guards it itself here
            writers.add(path.stem[: -len("_trainer")])

    if not writers:
        pytest.skip("no trl trainer writes the attribute any more")

    # trl file stems are snake_case; the wrapped names are CamelCase.
    normalized = {w.replace("_", "").lower() for w in wrapped}
    unwrapped = sorted(w for w in writers if w.replace("_", "") not in normalized)
    assert unwrapped == [], f"trl trainers writing warnings_issued but unwrapped: {unwrapped}"


if __name__ == "__main__":
    raise SystemExit(pytest.main([__file__, "-q"]))


# A real trl config: new_init branches on isinstance(TrainingArguments).
def _sft_config():
    pytest.importorskip("trl")
    # Not `trl.SFTConfig`: on Apple Silicon `import unsloth` rebinds it to the MLX config.
    from trl.trainer.sft_config import SFTConfig
    return SFTConfig


class _RecordingTrainer:
    """trl.SFTTrainer's signature, enough of it to see what arrives."""

    def __init__(
        self,
        model = None,
        args = None,
        train_dataset = None,
        processing_class = None,
    ):
        self.args = args
        self.train_dataset = train_dataset


def _rl_config_compat():
    """Load by file spec: importing via the package drags in torch and unsloth_zoo."""
    import importlib.util

    path = ROOT / "unsloth" / "models" / "rl_config_compat.py"
    spec = importlib.util.spec_from_file_location("_rl_config_compat_for_guard", path)
    module = importlib.util.module_from_spec(spec)
    spec.loader.exec_module(module)
    return module


def _wrapped_recording(trainer_base = None, config_class = None):
    config_class = config_class or _sft_config()
    ns = _load(
        "_ensure_warnings_issued",
        "_resolve_trainer_params",
        "_route_unknown_trainer_kwargs",
        "_config_family",
        "_backwards_compatible_trainer",
    )
    if "trl" not in ns:
        pytest.skip("trl not installed")
    # The relative import in the routed function cannot work in a bare namespace.
    for name in (
        "classify_config_kwarg",
        "rename_source",
        "removal_source",
        "rename_value_is_unset",
    ):
        ns[name] = getattr(_rl_config_compat(), name)

    class T(trainer_base or _RecordingTrainer):
        pass

    T.__init__ = ns["_backwards_compatible_trainer"](T, config_class)
    return T, config_class


def test_config_kwargs_reach_the_config_the_caller_passed(tmp_path):
    """Settings that used to be trainer kwargs have to end up on the config.
    They were computed and then dropped whenever `args` was given."""
    Trainer, config_class = _wrapped_recording()
    config = config_class(output_dir = str(tmp_path), report_to = [])
    assert config.packing is False and config.max_length != 2048

    trainer = Trainer(
        model = _Bare(),
        args = config,
        train_dataset = "DS",
        packing = True,
        max_length = 2048,
        dataset_num_proc = 4,
    )

    assert trainer.args.packing is True
    assert trainer.args.max_length == 2048
    assert trainer.args.dataset_num_proc == 4


def test_the_callers_own_config_object_is_the_one_used(tmp_path):
    """Reinitialising re-triggers trl's mutually exclusive checks, so the values
    have to be set rather than a new config built."""
    Trainer, config_class = _wrapped_recording()
    config = config_class(output_dir = str(tmp_path), report_to = [])

    trainer = Trainer(model = _Bare(), args = config, packing = True)

    assert trainer.args is config


def test_untouched_config_values_keep_what_the_caller_set(tmp_path):
    Trainer, config_class = _wrapped_recording()
    config = config_class(output_dir = str(tmp_path), report_to = [], max_length = 777)

    trainer = Trainer(model = _Bare(), args = config, packing = True)

    assert trainer.args.max_length == 777


def test_a_kwarg_neither_side_takes_is_reported_not_swallowed(tmp_path):
    """Not `max_seq_length` as the sentinel: the generated SFT config restores it."""
    Trainer, config_class = _wrapped_recording()
    config = config_class(output_dir = str(tmp_path), report_to = [])
    unexpected = "definitely_not_a_trainer_or_config_kwarg"
    assert unexpected not in {f.name for f in dataclasses.fields(config_class)}

    with pytest.raises(TypeError, match = unexpected):
        Trainer(model = _Bare(), args = config, **{unexpected: 2048})


def test_a_field_trl_retired_is_reported_and_dropped_not_raised(tmp_path, capsys):
    """Must warn, not raise: scripts pinned to an older TRL still pass these."""
    Trainer, config_class = _wrapped_recording()
    config = config_class(output_dir = str(tmp_path), report_to = [])
    retired = "rpo_alpha"  # DPOConfig, removed in TRL 0.29.0
    assert retired not in {f.name for f in dataclasses.fields(config_class)}

    trainer = Trainer(model = _Bare(), args = config, **{retired: 1.0})

    assert trainer.args is config
    assert not hasattr(config, retired)
    assert retired in capsys.readouterr().out


def test_a_field_trl_renamed_is_carried_across_to_the_new_name(tmp_path, capsys):
    Trainer, config_class = _wrapped_recording()
    fields = {f.name for f in dataclasses.fields(config_class)}
    if "use_liger_kernel" not in fields or "use_liger_loss" in fields:
        pytest.skip("installed trl does not show this rename on SFTConfig")
    config = config_class(output_dir = str(tmp_path), report_to = [])

    trainer = Trainer(model = _Bare(), args = config, use_liger_loss = True)

    assert trainer.args.use_liger_kernel is True
    assert "use_liger_kernel" in capsys.readouterr().out


def test_the_explicitly_supplied_new_name_beats_the_renamed_old_one(tmp_path, capsys):
    """Migrating over an explicit new name would silently train with the opposite
    setting. Covers both branches: the caller's config, and the rebuilt one."""
    Trainer, config_class = _wrapped_recording()
    fields = {f.name for f in dataclasses.fields(config_class)}
    if "use_liger_kernel" not in fields or "use_liger_loss" in fields:
        pytest.skip("installed trl does not show this rename on SFTConfig")

    config = config_class(output_dir = str(tmp_path), report_to = [])
    trainer = Trainer(model = _Bare(), args = config, use_liger_loss = False, use_liger_kernel = True)
    assert trainer.args.use_liger_kernel is True
    assert "is ignored" in capsys.readouterr().out

    Rebuilt, _ = _wrapped_recording()
    rebuilt = Rebuilt(
        model = _Bare(),
        args = None,
        output_dir = str(tmp_path),
        report_to = [],
        use_liger_loss = False,
        use_liger_kernel = True,
    )
    assert rebuilt.args.use_liger_kernel is True


def test_a_name_trl_never_had_still_raises(tmp_path):
    """The retirement table must not become a way to swallow typos."""
    Trainer, config_class = _wrapped_recording()
    config = config_class(output_dir = str(tmp_path), report_to = [])

    with pytest.raises(TypeError, match = "learnign_rate"):
        Trainer(model = _Bare(), args = config, learnign_rate = 3e-4)


def test_a_variadic_trainer_receives_a_name_the_table_does_not_know(tmp_path):
    """A trainer declaring `**kwargs` opted into arbitrary names, so deliver."""

    class _Variadic(_RecordingTrainer):
        def __init__(
            self,
            model = None,
            args = None,
            train_dataset = None,
            processing_class = None,
            **kwargs,
        ):
            super().__init__(model, args, train_dataset, processing_class)
            self.extra = dict(kwargs)

    Trainer, config_class = _wrapped_recording(trainer_base = _Variadic)
    config = config_class(output_dir = str(tmp_path), report_to = [])

    trainer = Trainer(model = _Bare(), args = config, some_extension_kwarg = 5)

    assert trainer.extra == {"some_extension_kwarg": 5}


def test_a_trainer_whose_config_parameter_is_not_called_args_does_not_KeyError(tmp_path):
    """`discard`, not `remove`: this used to raise KeyError."""

    class _OddlyNamed:
        def __init__(
            self,
            model = None,
            config = None,
            **kwargs,
        ):
            self.model, self.config, self.extra = model, config, dict(kwargs)

    Trainer, config_class = _wrapped_recording(trainer_base = _OddlyNamed)
    config = config_class(output_dir = str(tmp_path), report_to = [])

    trainer = Trainer(model = _Bare(), args = config)

    assert trainer.extra["args"] is config


def test_trainer_kwargs_still_go_to_the_trainer(tmp_path):
    Trainer, config_class = _wrapped_recording()
    config = config_class(output_dir = str(tmp_path), report_to = [])

    trainer = Trainer(model = _Bare(), args = config, train_dataset = "DS", packing = True)

    assert trainer.train_dataset == "DS"


def test_auto_packing_wraps_inside_the_backwards_compatible_wrapper():
    """Auto-packing reads packing off the config to block VLMs, collators and the blocklist, so it
    must wrap first to see the moved value; wrapped last, the block is undone right after."""
    for node in ast.walk(ast.parse(SRC)):
        if isinstance(node, ast.FunctionDef) and node.name == "_patch_trl_trainer":
            body = ast.get_source_segment(SRC, node)
            break
    else:
        raise AssertionError("_patch_trl_trainer not found")

    assert body.index("_patch_sft_trainer_auto_packing(trl)") < body.index(
        "_backwards_compatible_trainer(trl."
    )


def test_auto_packing_failure_still_leaves_the_wrapper_installed():
    """Going first, a raise here would skip the wrapping loop and drop pre-0.13
    compatibility, so the call has to be guarded."""
    for node in ast.walk(ast.parse(SRC)):
        if isinstance(node, ast.FunctionDef) and node.name == "_patch_trl_trainer":
            guarded = any(
                "_patch_sft_trainer_auto_packing" in ast.dump(stmt)
                for stmt in node.body
                if isinstance(stmt, ast.Try)
            )
            assert guarded, "_patch_sft_trainer_auto_packing must be wrapped in try/except"
            return
    raise AssertionError("_patch_trl_trainer not found")


def test_a_plain_training_arguments_keeps_the_moved_kwargs(tmp_path):
    """Plain TrainingArguments plus SFT kwargs: trl rebuilds via SFTConfig(**args.to_dict()), which
    drops attributes set on args, so packing, text field and length must survive."""
    from transformers import TrainingArguments

    Trainer, config_class = _wrapped_recording()
    args = TrainingArguments(output_dir = str(tmp_path), report_to = [], hub_token = "hf_FAKE")

    trainer = Trainer(
        model = _Bare(),
        args = args,
        packing = True,
        max_length = 4096,
        dataset_text_field = "body",
    )

    seen = trainer.args
    if not isinstance(seen, config_class):
        # What trl's SFTTrainer does with a plain TrainingArguments.
        rebuilt = seen.to_dict()
        rebuilt["hub_token"] = seen.hub_token
        seen = config_class(**rebuilt)
    assert (seen.packing, seen.max_length, seen.dataset_text_field) == (True, 4096, "body")
    assert seen.hub_token == "hf_FAKE"
    assert seen.output_dir == str(tmp_path)


def test_an_instance_of_the_displaced_trl_config_is_not_rebuilt(tmp_path):
    """Unsloth swaps each trl config for a subclass; a config built from the pristine class before
    that swap must keep the identity path. Rebuilding a GRPOConfig re-raises its post-init checks."""
    pristine = _sft_config()

    class Patched(pristine):
        _unsloth_patched_rl_config = True

    Patched.__name__ = pristine.__name__
    Trainer, _ = _wrapped_recording(config_class = Patched)
    config = pristine(output_dir = str(tmp_path), report_to = [], bf16 = False)

    trainer = Trainer(model = _Bare(), args = config, packing = True)

    assert trainer.args is config
    assert trainer.args.packing is True