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
Token budget: weight split-chunk TRL metrics by token count (#13978)
Daniel Hanf04666370840
diff --git a/tests/test_token_budget_metrics.py b/tests/test_token_budget_metrics.pynew file mode 100644index 00000000000..eab2b9c3bef--- /dev/null+++ b/tests/test_token_budget_metrics.py@@ -0,0 +1,223 @@+# SPDX-License-Identifier: AGPL-3.0-only+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved.++"""UNSLOTH_TOKEN_BUDGET keeps TRL's per-forward ratio metrics (token accuracy, entropy) equal to an+unsplit step when a micro-batch is split into unequal chunks. CPU only."""++from __future__ import annotations++import contextlib+import importlib.util+import sys+from collections import defaultdict+from pathlib import Path++import pytest++torch = pytest.importorskip("torch")++_PATH = Path(__file__).resolve().parents[1] / "unsloth" / "utils" / "token_budget.py"+_spec = importlib.util.spec_from_file_location("_unsloth_token_budget_metrics", _PATH)+tb = importlib.util.module_from_spec(_spec)+sys.modules[_spec.name] = tb+_spec.loader.exec_module(tb)+++class _Accelerator:+ distributed_type = "NO"+ num_processes = 1++ @contextlib.contextmanager+ def no_sync(self, model):+ yield+++def _token_stats(input_ids):+ # Stand-ins for the model: a token is "predicted correctly" when even, its entropy is its id.+ return (input_ids % 2 == 0).double(), input_ids.double()+++class _TRL022Trainer:+ """TRL 0.22.2 SFTTrainer.compute_loss metrics: accuracy over shifted labels != -100, entropy over+ the attention mask."""++ num_virtual_tokens = 0++ def __init__(self):+ self._metrics = {"train": defaultdict(list), "eval": defaultdict(list)}+ self.accelerator = _Accelerator()+ self.args = type("Args", (), {"gradient_accumulation_steps": 1})()+ self.model_accepts_loss_kwargs = True+ self.label_smoother = None++ def compute_loss(self, inputs):+ correct, entropy = _token_stats(inputs["input_ids"])+ mask = inputs["attention_mask"].double()+ self._metrics["train"]["entropy"].append(float((entropy * mask).sum() / mask.sum()))+ self._metrics["train"]["num_tokens"] = [0]+ shift_labels = inputs["labels"][..., 1:]+ valid = shift_labels != -100+ hits = (correct[..., 1:].bool() & valid).sum()+ self._metrics["train"]["mean_token_accuracy"].append(float(hits / valid.sum()))++ def training_step(+ self,+ model,+ inputs,+ num_items_in_batch = None,+ ):+ self.compute_loss(inputs)+ return torch.tensor(1.0)+++class _TRL1Trainer(_TRL022Trainer):+ """TRL 1.x SFTTrainer.compute_loss metrics: both ratios over the fused head's label_mask."""++ def compute_loss(self, inputs):+ correct, entropy = _token_stats(inputs["input_ids"])+ label_mask = inputs["labels"][..., 1:] != -100+ num_valid = label_mask.sum()+ entropy_sum = (entropy[..., 1:] * label_mask).sum()+ num_correct = (correct[..., 1:] * label_mask).sum()+ self._metrics["train"]["entropy"].append(float(entropy_sum / num_valid))+ self._metrics["train"]["mean_token_accuracy"].append(float(num_correct / num_valid))+++def _padded_batch():+ lengths = [2, 3, 3, 12]+ width = max(lengths)+ gen = torch.Generator().manual_seed(0)+ input_ids = torch.randint(1, 50, (len(lengths), width), generator = gen)+ attention_mask = torch.zeros(len(lengths), width, dtype = torch.long)+ for row, n in enumerate(lengths):+ attention_mask[row, :n] = 1+ labels = input_ids.masked_fill(attention_mask == 0, -100)+ labels[:, 0] = -100+ return {"input_ids": input_ids, "attention_mask": attention_mask, "labels": labels}+++def _logged(trainer):+ return {k: sum(v) / len(v) for k, v in trainer._metrics["train"].items()}++[email protected]("trainer_cls", [_TRL022Trainer, _TRL1Trainer])+def test_split_metrics_match_unsplit_step(monkeypatch, trainer_cls):+ monkeypatch.delenv("UNSLOTH_TOKEN_BALANCE", raising = False)+ batch = _padded_batch()++ monkeypatch.delenv("UNSLOTH_TOKEN_BUDGET", raising = False)+ reference = trainer_cls()+ tb.install_token_budget(reference)+ reference.training_step(None, dict(batch), 10)+ expected = _logged(reference)++ monkeypatch.setenv("UNSLOTH_TOKEN_BUDGET", "36")+ trainer = trainer_cls()+ tb.install_token_budget(trainer)+ chunks = tb.split_batch_by_token_budget(dict(batch), 36)+ assert len(chunks) > 1 and len({c["input_ids"].shape[0] for c in chunks}) > 1+ # Two steps: one entry per micro-batch, each weighted like the unsplit forward.+ trainer.training_step(None, dict(batch), 10)+ trainer.training_step(None, dict(batch), 10)+ assert trainer._unsloth_token_budget_splits == 2+ for key in ("entropy", "mean_token_accuracy"):+ assert len(trainer._metrics["train"][key]) == 2+ logged = _logged(trainer)+ for key in ("entropy", "mean_token_accuracy"):+ assert logged[key] == pytest.approx(expected[key], rel = 1e-6)+ assert logged.get("num_tokens") == expected.get("num_tokens")+++def test_unsplit_steps_leave_metrics_untouched(monkeypatch):+ monkeypatch.delenv("UNSLOTH_TOKEN_BALANCE", raising = False)+ monkeypatch.setenv("UNSLOTH_TOKEN_BUDGET", "100000")+ trainer = _TRL1Trainer()+ tb.install_token_budget(trainer)+ trainer.training_step(None, _padded_batch(), 10)+ assert trainer._unsloth_token_budget_splits == 0+ assert len(trainer._metrics["train"]["entropy"]) == 1+++def test_trainers_without_metrics_still_split(monkeypatch):+ monkeypatch.delenv("UNSLOTH_TOKEN_BALANCE", raising = False)+ monkeypatch.setenv("UNSLOTH_TOKEN_BUDGET", "36")+ trainer = _TRL1Trainer()+ del trainer._metrics+ seen = []+ trainer.training_step = lambda model, inputs, n = None: seen.append(inputs) or torch.tensor(1.0)+ tb.install_token_budget(trainer)+ loss = trainer.training_step(None, _padded_batch(), 10)+ assert len(seen) > 1 and float(loss) == len(seen)+++class _DelegatingTRL1Trainer(_TRL1Trainer):+ """A user subclass of a TRL 1.x trainer whose compute_loss only delegates to super()."""++ def compute_loss(self, inputs):+ return super().compute_loss(inputs)+++def test_delegating_subclass_uses_parent_metric_code(monkeypatch):+ monkeypatch.delenv("UNSLOTH_TOKEN_BALANCE", raising = False)+ batch = _padded_batch()+ monkeypatch.delenv("UNSLOTH_TOKEN_BUDGET", raising = False)+ reference = _DelegatingTRL1Trainer()+ tb.install_token_budget(reference)+ reference.training_step(None, dict(batch), 10)+ expected = _logged(reference)++ monkeypatch.setenv("UNSLOTH_TOKEN_BUDGET", "36")+ trainer = _DelegatingTRL1Trainer()+ tb.install_token_budget(trainer)+ trainer.training_step(None, dict(batch), 10)+ assert trainer._unsloth_token_budget_splits == 1+ logged = _logged(trainer)+ for key in ("entropy", "mean_token_accuracy"):+ assert len(trainer._metrics["train"][key]) == 1+ assert logged[key] == pytest.approx(expected[key], rel = 1e-6)+++def _per_chunk_entries(trainer_cls, batch, **attrs):+ # What TRL logs with no folding: one entry per chunk.+ trainer = trainer_cls()+ for name, value in attrs.items():+ setattr(trainer, name, value)+ for chunk in tb.split_batch_by_token_budget(dict(batch), 36):+ trainer.compute_loss(chunk)+ return {k: list(trainer._metrics["train"][k]) for k in ("entropy", "mean_token_accuracy")}+++def _split_once(monkeypatch, trainer_cls, batch, **attrs):+ monkeypatch.delenv("UNSLOTH_TOKEN_BALANCE", raising = False)+ monkeypatch.setenv("UNSLOTH_TOKEN_BUDGET", "36")+ trainer = trainer_cls()+ for name, value in attrs.items():+ setattr(trainer, name, value)+ tb.install_token_budget(trainer)+ trainer.training_step(None, dict(batch), 10)+ assert trainer._unsloth_token_budget_splits == 1+ return {k: list(trainer._metrics["train"][k]) for k in ("entropy", "mean_token_accuracy")}+++def test_prompt_learning_leaves_entries_unfolded(monkeypatch):+ batch = _padded_batch()+ expected = _per_chunk_entries(_TRL022Trainer, batch, num_virtual_tokens = 2)+ assert len(expected["entropy"]) > 1+ assert _split_once(monkeypatch, _TRL022Trainer, batch, num_virtual_tokens = 2) == expected+++def test_ambiguous_label_source_leaves_entries_unfolded(monkeypatch):+ batch = _padded_batch()+ batch["shift_labels"] = batch["labels"][..., 1:].contiguous()+ batch["shift_labels"] = torch.nn.functional.pad(batch["shift_labels"], (0, 1), value = -100)+ expected = _per_chunk_entries(_TRL1Trainer, batch)+ assert len(expected["entropy"]) > 1+ assert _split_once(monkeypatch, _TRL1Trainer, batch) == expected+++def test_multi_process_leaves_entries_unfolded(monkeypatch):+ batch = _padded_batch()+ expected = _per_chunk_entries(_TRL022Trainer, batch)+ accelerator = _Accelerator()+ accelerator.num_processes = 2+ assert _split_once(monkeypatch, _TRL022Trainer, batch, accelerator = accelerator) == expecteddiff --git a/unsloth/utils/token_budget.py b/unsloth/utils/token_budget.pyindex 2a2a50b8999..3d6a6e89003 100644--- a/unsloth/utils/token_budget.py+++ b/unsloth/utils/token_budget.py@@ -490,6 +490,109 @@ def _same_count_on_every_rank(count, accelerator):return int(bounds[0]) == -int(bounds[1])+def _label_count(chunk):+ """Tokens TRL scores for token accuracy: shifted labels that are not -100."""+ labels = chunk.get("shift_labels")+ if labels is None:+ labels = chunk.get("labels")+ if labels is None:+ return 0+ labels = labels[..., 1:]+ return int((labels != -100).sum())+++def _metric_style(trainer):+ """How the trainer's TRL compute_loss averages entropy: "labels" (fused-head TRL, label mask) or+ "attention" (older TRL, attention mask). None when no class in the MRO computes TRL's metrics."""+ style = getattr(trainer, "_unsloth_token_budget_metric_style", False)+ if style is not False:+ return style+ style = None+ # Subclasses that only delegate to super() do not hold the metric code: use the class that does.+ for cls in type(trainer).__mro__:+ function = cls.__dict__.get("compute_loss")+ if function is None:+ continue+ try:+ source = inspect.getsource(function)+ except Exception:+ break+ if "mean_token_accuracy" in source:+ style = "labels" if "label_mask" in source else "attention"+ break+ trainer._unsloth_token_budget_metric_style = style+ return style+++def _entropy_count(trainer, chunk):+ """Tokens TRL averages entropy over: the label mask on fused-head TRL, else the attention mask or+ every position when padding-free."""+ if _metric_style(trainer) == "labels":+ return _label_count(chunk)+ if "attention_mask" in chunk:+ return int(chunk["attention_mask"].sum())+ if "position_ids" in chunk:+ return int(chunk["position_ids"].numel())+ return 0+++# Per-forward ratio metrics TRL appends once per compute_loss call and later averages per entry.+_RATIO_METRICS = {+ "mean_token_accuracy": lambda trainer, chunk: _label_count(chunk),+ "entropy": _entropy_count,+}+++def _is_prompt_learning(trainer, model):+ if int(getattr(trainer, "num_virtual_tokens", 0) or 0) > 0:+ return True+ for candidate in (model, getattr(trainer, "model", None)):+ config = getattr(candidate, "active_peft_config", None)+ if getattr(config, "is_prompt_learning", False):+ return True+ return False+++def _can_merge_metrics(trainer, model, chunks, accelerator):+ """Fold per-chunk entries only when token weighting provably reproduces TRL's unsplit value:+ one process (TRL's cross-rank reductions differ per version), no prompt-learning PEFT (virtual+ token logits are counted differently per version), one label source, and known TRL metric code."""+ if accelerator is not None and int(getattr(accelerator, "num_processes", 1) or 1) > 1:+ return False+ if _is_prompt_learning(trainer, model):+ return False+ if any("shift_labels" in chunk and "labels" in chunk for chunk in chunks):+ return False+ return _metric_style(trainer) is not None+++def _metric_lengths(trainer):+ metrics = getattr(trainer, "_metrics", None)+ metrics = metrics.get("train") if isinstance(metrics, Mapping) else None+ if not isinstance(metrics, Mapping):+ return None, None+ lengths = {+ key: len(metrics[key])+ for key in _RATIO_METRICS+ if key in metrics and isinstance(metrics[key], list)+ }+ return metrics, lengths+++def _merge_chunk_metrics(trainer, metrics, lengths, chunks):+ """Fold the per-chunk ratio entries back into one entry for the micro-batch, weighting each chunk by+ the tokens TRL divided by, so the logged value matches an unsplit step."""+ keys = [key for key in _RATIO_METRICS if key in metrics and isinstance(metrics[key], list)]+ keys = [key for key in keys if len(metrics[key]) - lengths.get(key, 0) == len(chunks)]+ for key in keys:+ row = [_RATIO_METRICS[key](trainer, chunk) for chunk in chunks]+ start = lengths.get(key, 0)+ values = metrics[key][start:]+ total = sum(row)+ merged = sum(v * w for v, w in zip(values, row)) / total if total > 0 else 0.0+ metrics[key][start:] = [merged]++def install_token_budget(trainer):"""Install whichever of UNSLOTH_TOKEN_BALANCE / UNSLOTH_TOKEN_BUDGET is set on `trainer`."""balance = os.environ.get(_TOKEN_BALANCE_ENV, "0").lower() in ("1", "true", "yes", "on")@@ -548,6 +651,11 @@ def install_token_budget(trainer):if len(chunks) == 1:return original_training_step(model, inputs, num_items_in_batch, *args, **kwargs)trainer._unsloth_token_budget_splits += 1+ metrics, lengths = (+ _metric_lengths(trainer)+ if _can_merge_metrics(trainer, model, chunks, accelerator)+ else (None, None)+ )total = Nonefor i, chunk in enumerate(chunks):context = (@@ -558,6 +666,8 @@ def install_token_budget(trainer):with context:loss = original_training_step(model, chunk, num_items_in_batch, *args, **kwargs)total = loss if total is None else total + loss+ if metrics is not None:+ _merge_chunk_metrics(trainer, metrics, lengths, chunks)return totaltrainer.training_step = training_step