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.

Studio: show the real epoch for Mac training runs (#11602)

Nilay8190a1a77267
diff --git a/studio/backend/core/training/trainer.py b/studio/backend/core/training/trainer.py
index fc8247f7017..53902fed94c 100644
--- a/studio/backend/core/training/trainer.py
+++ b/studio/backend/core/training/trainer.py
@@ -362,6 +362,8 @@ class UnslothTrainer:
self.model_load_error = None
self.dataset_loaded_from_exact_snapshot = False
self.dataset_snapshot_path = None
+ # A max_steps bound keeps a uniform sample of the rows, so a pass over it is this share of a dataset pass.
+ self._kept_row_fraction = 1.0
self.training_start_time: Optional[float] = None
self.session_start_step: int = 0
@@ -663,7 +665,9 @@ class UnslothTrainer:
trainer_ref._update_progress(
step = current_step,
- epoch = round(state.epoch, 2) if state.epoch else 0,
+ epoch = round(state.epoch * trainer_ref._kept_row_fraction, 2)
+ if state.epoch
+ else 0,
loss = loss_value,
learning_rate = logs.get("learning_rate", None),
elapsed_seconds = elapsed_seconds,
@@ -677,7 +681,9 @@ class UnslothTrainer:
)
def on_epoch_end(self, args, state, control, **kwargs):
- trainer_ref._update_progress(epoch = state.epoch, step = state.global_step)
+ trainer_ref._update_progress(
+ epoch = state.epoch * trainer_ref._kept_row_fraction, step = state.global_step
+ )
def on_step_end(self, args, state, control, **kwargs):
if trainer_ref.should_stop:
@@ -2705,6 +2711,7 @@ class UnslothTrainer:
try:
self.dataset_loaded_from_exact_snapshot = False
self.dataset_snapshot_path = None
+ self._kept_row_fraction = 1.0
dataset = None
eval_dataset = None
dataset_attestation_source = None
@@ -3127,6 +3134,7 @@ class UnslothTrainer:
):
def _log_bound(kept, total):
+ self._kept_row_fraction = kept / total
logger.info(
f"Bounded dataset to {kept} of {total} rows for a "
f"max_steps run (seed {max_train_rows_seed})\n"
diff --git a/studio/backend/core/training/worker.py b/studio/backend/core/training/worker.py
index 395b40e525d..469c3bb1afa 100644
--- a/studio/backend/core/training/worker.py
+++ b/studio/backend/core/training/worker.py
@@ -2681,6 +2681,12 @@ def _run_mlx_training(event_queue, stop_queue, config):
# A bracketed split names rows the same way the numeric fields do.
mlx_split_names_rows = "[" in (config.get("train_split") or "")
+ # The bound keeps a uniform sample of the rows, so a pass over it is this share of a dataset pass.
+ mlx_kept_row_fraction = [1.0]
+
+ def _on_bound(kept, total):
+ mlx_kept_row_fraction[0] = kept / total
+ _send("status", status_message = f"Using {kept} of {total} rows (max_steps run)")
def _slice(ds):
if slice_start is not None or slice_end is not None:
@@ -2696,10 +2702,7 @@ def _run_mlx_training(event_queue, stop_queue, config):
ds,
mlx_max_train_rows,
mlx_max_train_rows_seed,
- on_bound = lambda kept, total: _send(
- "status",
- status_message = f"Using {kept} of {total} rows (max_steps run)",
- ),
+ on_bound = _on_bound,
)
def _load_local(file_paths):
@@ -2958,6 +2961,7 @@ def _run_mlx_training(event_queue, stop_queue, config):
weight_decay = config.get("weight_decay", 0.001)
weight_decay = 0.001 if weight_decay is None else float(weight_decay)
+ # `streaming` stays off: without a pass length zoo cannot end an epoch on an optimizer step or report a real epoch.
mlx_config_kwargs = dict(
per_device_train_batch_size = batch_size,
gradient_accumulation_steps = grad_accum,
@@ -2975,7 +2979,6 @@ def _run_mlx_training(event_queue, stop_queue, config):
use_cce = True,
compile = True,
gradient_checkpointing = use_grad_checkpoint,
- streaming = is_vlm,
packing = bool(config.get("packing", False)),
output_dir = output_dir,
save_steps = int(config.get("save_steps", 0) or 0),
@@ -3111,7 +3114,11 @@ def _run_mlx_training(event_queue, stop_queue, config):
_send(
"progress",
step = step,
- epoch = round(step / total * num_epochs, 2) if total > 0 else 0,
+ epoch = (
+ round(trainer.state.epoch * mlx_kept_row_fraction[0], 2)
+ if trainer.state.epoch
+ else 0
+ ),
loss = loss,
learning_rate = lr,
total_steps = total,
diff --git a/studio/backend/tests/test_mlx_epoch_report.py b/studio/backend/tests/test_mlx_epoch_report.py
new file mode 100644
index 00000000000..1e61fa3bd43
--- /dev/null
+++ b/studio/backend/tests/test_mlx_epoch_report.py
@@ -0,0 +1,107 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import ast
+import inspect
+import textwrap
+from types import SimpleNamespace
+
+import core.training.worker as _worker
+from datasets import Dataset
+
+_TREE = ast.parse(textwrap.dedent(inspect.getsource(_worker._run_mlx_training)))
+
+
+class _StubMLXTrainer:
+ def __init__(self):
+ self._step_callbacks = []
+ self.state = SimpleNamespace(epoch = None)
+
+ def add_step_callback(self, fn):
+ self._step_callbacks.append(fn)
+
+ def train(self, step, state_epoch):
+ self.state.epoch = state_epoch
+ for cb in self._step_callbacks:
+ cb(step, step, 1.25, 2e-4, 900.0, 3.5, 12.0, 4096, 0.7)
+
+
+def _step_callback_block():
+ body = _TREE.body[0].body
+ bound = [
+ n
+ for n in body
+ if ast.unparse(n) == "mlx_kept_row_fraction = [1.0]"
+ or (isinstance(n, ast.FunctionDef) and n.name in ("_on_bound", "_slice"))
+ ]
+ starts = [i for i, n in enumerate(body) if ast.unparse(n) == "start_step = 0"]
+ ends = [
+ i for i, n in enumerate(body) if ast.unparse(n) == "trainer.add_step_callback(_on_step)"
+ ]
+ assert len(bound) == 3 and len(starts) == 1 and len(ends) == 1 and starts[0] < ends[0]
+ return bound + body[starts[0] : ends[0] + 1]
+
+
+def _run_step_callback(
+ step,
+ state_epoch,
+ rows = 0,
+ max_train_rows = None,
+):
+ block = compile(ast.Module(body = _step_callback_block(), type_ignores = []), "<on_step>", "exec")
+ events = []
+ trainer = _StubMLXTrainer()
+ namespace = dict(vars(_worker))
+ namespace.update(
+ {
+ "trainer": trainer,
+ "resume_from_checkpoint": None,
+ "slice_start": None,
+ "slice_end": None,
+ "mlx_split_names_rows": False,
+ "mlx_max_train_rows": max_train_rows,
+ "mlx_max_train_rows_seed": 3407,
+ "wandb_run": None,
+ "tb_writer": None,
+ "_send": lambda event_type, **kw: events.append((event_type, kw)),
+ }
+ )
+ exec(block, namespace)
+ namespace["_slice"](Dataset.from_dict({"text": ["row"] * rows}))
+ trainer.train(step, state_epoch)
+ return [kw for kind, kw in events if kind == "progress"]
+
+
+def test_mlx_step_callback_reports_the_trainer_epoch():
+ progress = _run_step_callback(60, 15.3333)
+
+ assert len(progress) == 1
+ assert progress[0]["step"] == 60 and progress[0]["total_steps"] == 60
+ assert progress[0]["epoch"] == 15.33
+
+
+def test_mlx_step_callback_reports_zero_before_the_trainer_has_an_epoch():
+ assert _run_step_callback(1, None)[0]["epoch"] == 0
+
+
+def test_mlx_step_callback_counts_a_bounded_run_over_the_whole_dataset():
+ progress = _run_step_callback(60, 2.0, rows = 1000, max_train_rows = 250)
+
+ assert progress[0]["epoch"] == 0.5
+
+
+def test_mlx_training_never_streams():
+ keyword_values = [
+ n.value for n in ast.walk(_TREE) if isinstance(n, ast.keyword) and n.arg == "streaming"
+ ]
+ subscript_values = [
+ n.value
+ for n in ast.walk(_TREE)
+ if isinstance(n, ast.Assign)
+ and any(
+ isinstance(t, ast.Subscript) and ast.unparse(t.slice) == "'streaming'"
+ for t in n.targets
+ )
+ ]
+ for value in keyword_values + subscript_values:
+ assert isinstance(value, ast.Constant) and value.value is False, ast.unparse(value)
diff --git a/studio/backend/tests/test_training_preflight.py b/studio/backend/tests/test_training_preflight.py
index 59d1f7b3450..e0f734f7dcf 100644
--- a/studio/backend/tests/test_training_preflight.py
+++ b/studio/backend/tests/test_training_preflight.py
@@ -540,11 +540,13 @@ def test_max_steps_bound_subsets_before_formatting(monkeypatch):
assert len(bounded) == 1024
# Shuffled: the head of a corpus ordered by source is not a sample of it.
assert bounded.shuffle_seeds == [99]
+ assert trainer._kept_row_fraction == 1024 / 500_000
def test_max_steps_bound_leaves_a_small_dataset_alone(monkeypatch):
train = _SizedDataset(40)
trainer = _cached_only_loader(monkeypatch, train)
+ trainer._kept_row_fraction = 0.5 # left over from an earlier bounded load
result = trainer.load_and_format_dataset(
"org/dataset",
@@ -556,6 +558,7 @@ def test_max_steps_bound_leaves_a_small_dataset_alone(monkeypatch):
assert result is not None
# Untouched: no shuffle cost or reordering for a run that reads it all.
assert result[0]["dataset"] is train
+ assert trainer._kept_row_fraction == 1.0
def test_max_steps_bound_defers_to_an_explicit_slice(monkeypatch):
diff --git a/studio/backend/tests/test_training_progress_callback.py b/studio/backend/tests/test_training_progress_callback.py
index 9b4e271b6e7..4c31092d3b7 100644
--- a/studio/backend/tests/test_training_progress_callback.py
+++ b/studio/backend/tests/test_training_progress_callback.py
@@ -154,6 +154,26 @@ def test_logging_reports_an_empty_status_so_the_active_one_is_sent_once():
assert owner.training_progress.num_tokens == 384
+def test_unbounded_run_reports_the_trainer_epoch():
+ owner = _make_owner()
+
+ _drive(owner._create_progress_callback(), steps = 3)
+
+ assert owner.training_progress.epoch == 1.5
+
+
+def test_bounded_run_reports_epochs_over_the_whole_dataset():
+ owner = _make_owner()
+ owner._kept_row_fraction = 0.1
+ reported: list[float] = []
+ owner.add_progress_callback(lambda progress: reported.append(progress.epoch))
+
+ _drive(owner._create_progress_callback(), steps = 3)
+
+ assert [epoch for epoch in reported if epoch][:3] == [0.05, 0.1, 0.15]
+ assert owner.training_progress.epoch == pytest.approx(0.15)
+
+
def test_parent_status_advances_over_the_whole_chain():
owner = _make_owner()
backend = TrainingBackend()