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.
Python agentaichatgptdeepseekfine-tuninggemmaimage-generationllamallmllmsopenaipythonqwenreinforcement-learningself-hostedstable-diffusiontext-to-speechttsuiunsloth
# SPDX-License-Identifier: AGPL-3.0-only
# Copyright 2026-present the Unsloth AI Inc. team.
"""Three components must agree on token-count loss normalisation, or grads silently scale by 1/GA."""
from __future__ import annotations
import ast
import importlib.util
import inspect
import os
import sys
import textwrap
from pathlib import Path
os.environ.setdefault("UNSLOTH_COMPILE_DISABLE", "1")
os.environ.setdefault("TORCHDYNAMO_DISABLE", "1")
os.environ.setdefault("TORCH_COMPILE_DISABLE", "1")
import pytest
# daily-fresh-fetch collects this directory with only pytest installed.
if importlib.util.find_spec("torch") is None:
pytest.skip("torch not installed", allow_module_level = True)
# Unsloth needs a torch accelerator, so spoof at module scope before any unsloth import.
_SPOOF_DIR = Path(__file__).resolve().parents[1]
sys.path.insert(0, str(_SPOOF_DIR))
import _zoo_aggressive_cuda_spoof as _spoof # noqa: E402
_spoof.apply()
def test_sft_loss_type_default_is_nll_after_unsloth_patch():
"""chunked_nll bypasses the forward (fused CE never runs) and double-divides."""
import unsloth # noqa: F401 must precede trl
import trl
if not hasattr(trl.SFTConfig, "loss_type"):
pytest.skip("this TRL has no SFTConfig.loss_type")
cfg = trl.SFTConfig(output_dir = "unused")
assert cfg.loss_type == "nll", (
f"SFTConfig.loss_type resolved to {cfg.loss_type!r}, expected 'nll'. "
"If TRL changed its default again, update the sft_trainer replacement in "
"unsloth/models/rl.py -- do NOT add loss_type to the global replacements "
"dict, it is an unrelated field in DPO/KTO/GRPO."
)
def _loss_type_field(cfg_cls):
"""Reads the dataclass field; hasattr misses default_factory fields, which leave no class attribute."""
import dataclasses
return next((f for f in dataclasses.fields(cfg_cls) if f.name == "loss_type"), None)
def _pristine_config_cls(cfg_cls):
"""TRL's own config class, walking past the subclass patching rebinds over it."""
while "_unsloth_patched_rl_config" in cfg_cls.__dict__ or cfg_cls.__name__.startswith(
"Unsloth"
):
cfg_cls = cfg_cls.__mro__[1]
return cfg_cls
def test_loss_type_replacement_did_not_leak_to_other_trainers():
"""DPO and KTO loss_type are checked against pristine TRL, whose default changes between releases."""
import unsloth # noqa: F401
import trl
from packaging.version import Version
checked = []
for name in ("DPOConfig", "KTOConfig"):
cfg_cls = getattr(trl, name, None)
if cfg_cls is None or _loss_type_field(cfg_cls) is None:
continue
pristine = _pristine_config_cls(cfg_cls)
assert "_unsloth_patched_rl_config" not in pristine.__dict__, (
f"the pristine walk for {name} landed on a patched class, so comparing against "
f"it would compare the patch with itself"
)
want = pristine(output_dir = "unused").loss_type
got = cfg_cls(output_dir = "unused").loss_type
assert got == want, (
f"{name}.loss_type is {got!r} and pristine TRL {trl.__version__} says {want!r}. "
"A loss_type replacement leaked out of the sft_trainer branch in rl.py."
)
checked.append(name)
grpo = getattr(trl, "GRPOConfig", None)
grpo_refused = Version(trl.__version__) < Version("0.20.0")
if grpo is not None and not grpo_refused and _loss_type_field(grpo) is not None:
got = grpo(output_dir = "unused").loss_type
# Unsloth follows TRL's GRPO default from 0.22, the first TRL with 'dapo'.
want = "dapo" if Version(trl.__version__) >= Version("0.22.0") else "bnpo"
assert got == want, (
f"GRPOConfig.loss_type is {got!r}, expected {want!r}. That default is unsloth's own "
"(rl.py), so this is either a lost override or a leak."
)
checked.append("GRPOConfig")
assert len(checked) >= 2, (
f"only {checked} carried a loss_type field on trl {trl.__version__}, so this test "
f"checked almost nothing. Retarget it rather than letting it pass empty."
)
def test_explicit_loss_type_still_wins():
"""Pinning a default must not take the choice away from the user."""
import unsloth # noqa: F401
import trl
if not hasattr(trl.SFTConfig, "loss_type"):
pytest.skip("this TRL has no SFTConfig.loss_type")
for wanted in ("chunked_nll", "dft"):
cfg = trl.SFTConfig(output_dir = "unused", loss_type = wanted)
assert cfg.loss_type == _trl_resolves(wanted), "explicit loss_type was clobbered"
def _trl_resolves(wanted):
"""Reads the chunked_nll to nll alias from TRL's FutureWarning, not from a version number."""
import warnings
pristine = _pristine_sft_config_cls()
with warnings.catch_warnings(record = True) as caught:
warnings.simplefilter("always")
got = pristine(output_dir = "unused", loss_type = wanted).loss_type
aliased = any(
issubclass(w.category, FutureWarning)
and repr(wanted) in str(w.message)
and "deprecated" in str(w.message)
for w in caught
)
return got if aliased else wanted
def _skip_if_unsloth_refuses_grpo():
# Unsloth refuses GRPO below trl 0.20.0; the floor lane runs below it.
import trl
from packaging.version import Version
if Version(trl.__version__) < Version("0.20.0"):
pytest.skip(f"unsloth refuses GRPO on trl {trl.__version__} (< 0.20.0)")
def test_dr_grpo_turns_off_reward_scaling_by_default():
"""TRL >= 0.22 defaults scale_rewards to "group" (= True), so dr_grpo must override both."""
import unsloth # noqa: F401
import trl
_skip_if_unsloth_refuses_grpo()
def scale(**kwargs):
return trl.GRPOConfig(output_dir = "unused", loss_type = "dr_grpo", **kwargs).scale_rewards
for kwargs in ({}, {"scale_rewards": True}, {"scale_rewards": "group"}):
assert scale(**kwargs) in (False, "none"), f"dr_grpo with {kwargs} still scales rewards"
assert scale(scale_rewards = None) in (True, "group"), "None should keep group scaling"
assert scale(scale_rewards = "batch") == "batch", "an explicit batch scaling was clobbered"
def _pristine_sft_config_cls():
"""TRL's own SFTConfig, not the generated subclass patching rebinds over it."""
import trl
# Check the marker, not the name: the generated subclass is renamed to TRL's name for pickling.
cls = trl.SFTConfig
while "_unsloth_patched_rl_config" in cls.__dict__ or cls.__name__.startswith("Unsloth"):
cls = cls.__mro__[1]
return cls
def test_pristine_trl_sft_config_default_is_nll_too():
"""Importing SFTConfig before unsloth keeps TRL's own class, whose default must also be nll."""
import unsloth # noqa: F401 must precede trl
pristine = _pristine_sft_config_cls()
if not hasattr(pristine, "loss_type"):
pytest.skip("this TRL has no SFTConfig.loss_type")
got = pristine(output_dir = "unused").loss_type
assert got == "nll", (
f"pristine {pristine.__name__}.loss_type resolved to {got!r}, expected "
"'nll'. _pin_pristine_sft_loss_type in unsloth/models/rl.py stopped "
"reaching TRL's own class, so a pre-unsloth `from trl import SFTConfig` "
"still double-normalises the loss by 1/GA."
)
def test_pristine_trl_sft_config_keeps_an_explicit_loss_type():
"""Pinning the pristine default must not take the choice away either."""
import unsloth # noqa: F401
pristine = _pristine_sft_config_cls()
if not hasattr(pristine, "loss_type"):
pytest.skip("this TRL has no SFTConfig.loss_type")
for wanted in ("chunked_nll", "dft"):
got = pristine(output_dir = "unused", loss_type = wanted).loss_type
assert got == _trl_resolves(
wanted
), f"explicit loss_type {wanted!r} was clobbered to {got!r}"
# "dft" is not an alias on any TRL, so it must always come back unchanged.
assert _trl_resolves("dft") == "dft"
def test_dataclass_field_default_is_nll_for_hfargumentparser():
"""HfArgumentParser passes the field value through, so the dataclass field default must be nll."""
import dataclasses
import unsloth # noqa: F401
pristine = _pristine_sft_config_cls()
if not hasattr(pristine, "loss_type"):
pytest.skip("this TRL has no SFTConfig.loss_type")
import trl
for cls in (pristine, trl.SFTConfig):
field = {f.name: f for f in dataclasses.fields(cls)}["loss_type"]
assert field.default == "nll", (
f"{cls.__name__}.loss_type field default is {field.default!r}, "
"expected 'nll'. HfArgumentParser and any other dataclass-driven "
"entry point would pass that default through and land on chunked_nll."
)
def _divides_by_num_items(fn) -> bool:
"""True when the source contains a division by num_items_in_batch/n_items."""
try:
source = textwrap.dedent(inspect.getsource(fn))
except (OSError, TypeError):
return False
try:
tree = ast.parse(source)
except SyntaxError:
return False
names = {"num_items_in_batch", "n_items"}
for node in ast.walk(tree):
if isinstance(node, ast.BinOp) and isinstance(node.op, ast.Div):
for sub in ast.walk(node.right):
if isinstance(sub, ast.Name) and sub.id in names:
return True
return False
def test_transformers_training_step_still_keys_off_model_accepts_loss_kwargs():
"""If upstream changes this predicate, our whole reconciliation is stale."""
from transformers import Trainer
try:
source = inspect.getsource(Trainer.training_step)
except (OSError, TypeError):
pytest.skip("Trainer.training_step source unavailable")
assert "model_accepts_loss_kwargs" in source, (
"transformers' training_step no longer references model_accepts_loss_kwargs. "
"The grad-accum normalisation contract changed upstream; re-check "
"unsloth_zoo's _unsloth_get_batch_samples against the new predicate."
)
assert (
"num_items_in_batch" in source
), "transformers' training_step no longer references num_items_in_batch."
def test_trl_chunked_ce_divides_by_num_items_without_consulting_the_flag():
"""Fires if TRL starts gating this, at which point the pin can be dropped."""
trl_sft = pytest.importorskip("trl.trainer.sft_trainer")
fn = getattr(trl_sft, "_chunked_cross_entropy_loss", None)
if fn is None:
pytest.skip("this TRL has no _chunked_cross_entropy_loss")
assert _divides_by_num_items(fn), (
"TRL's _chunked_cross_entropy_loss no longer divides by num_items_in_batch. "
"If TRL now gates this on model_accepts_loss_kwargs, the loss_type pin in "
"unsloth/models/rl.py may no longer be needed -- re-measure before removing."
)
try:
source = inspect.getsource(fn)
except (OSError, TypeError):
return
assert "model_accepts_loss_kwargs" not in source, (
"TRL's chunked CE now consults model_accepts_loss_kwargs. Good news: "
"re-evaluate whether unsloth still needs to pin loss_type='nll'."
)
def test_unsloth_fused_ce_has_the_same_num_items_contract():
"""Ours divides by n_items too, which is why the compiled-path flag matters."""
ce = pytest.importorskip("unsloth_zoo.fused_losses.cross_entropy_loss")
fn = getattr(ce, "unsloth_fused_ce_loss", None)
if fn is None:
pytest.skip("unsloth_fused_ce_loss not present")
source = inspect.getsource(fn)
assert "n_items" in source, (
"unsloth_fused_ce_loss no longer takes n_items; the normalisation "
"contract changed on our side and rl.py's loss_type pin should be re-checked."
)
def test_unsloth_get_batch_samples_is_installed_and_shaped_as_expected():
"""_utils.py raises NotImplementedError on this shape; catch it before train()."""
from transformers import Trainer
fn = getattr(Trainer, "get_batch_samples", None)
if fn is None:
pytest.skip("Trainer has no get_batch_samples")
try:
source = inspect.getsource(fn).strip()
except (OSError, TypeError):
pytest.skip("get_batch_samples source unavailable")
assert source.endswith("return batch_samples, num_items_in_batch"), (
"get_batch_samples no longer ends in the expected 2-tuple return. "
"unsloth/models/_utils.py raises NotImplementedError on this exact check."
)
def test_rl_py_scopes_loss_type_to_sft_trainer():
"""AST guard: no loss_type replacement outside an `if trainer_file ==` branch."""
from unsloth.models import rl
source = inspect.getsource(rl)
tree = ast.parse(source)
offenders = []
for node in ast.walk(tree):
if not isinstance(node, ast.Assign):
continue
if not any(isinstance(t, ast.Name) and t.id == "replacements" for t in node.targets):
continue
if not isinstance(node.value, ast.Dict):
continue
keys = [k.value for k in node.value.keys if isinstance(k, ast.Constant)]
if "loss_type" not in keys:
continue
guarded = False
for parent in ast.walk(tree):
if not isinstance(parent, ast.If):
continue
if node not in [
n
for b in (parent.body, parent.orelse)
for n in ast.walk(ast.Module(body = b, type_ignores = []))
]:
continue
if "trainer_file" in ast.dump(parent.test):
guarded = True
break
if not guarded:
offenders.append(keys)
assert not offenders, (
f"found an unguarded `loss_type` replacement: {offenders}. It must live "
'inside an `if trainer_file == "...":` branch -- the global replacements '
"dict is applied by regex to every generated config, and loss_type is a "
"real field in DPOConfig, KTOConfig and GRPOConfig."
)