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: add early stopping patience on eval loss (#13626)

Daniel Han2a8ecf6ad27e
diff --git a/studio/backend/core/training/early_stopping.py b/studio/backend/core/training/early_stopping.py
new file mode 100644
index 00000000000..2c2d68fa5ff
--- /dev/null
+++ b/studio/backend/core/training/early_stopping.py
@@ -0,0 +1,170 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Stop a run once eval loss stops improving, and keep the weights from the best evaluation."""
+
+from __future__ import annotations
+
+import math
+from typing import Any, Optional
+
+from loggers import get_logger
+
+logger = get_logger(__name__)
+
+MAX_EARLY_STOPPING_PATIENCE = 1000
+# Past this the CPU copy of the best weights costs more host RAM than it is worth (a full finetune of a 1B model).
+MAX_BEST_WEIGHTS_BYTES = 2 << 30
+
+
+def early_stopping_patience(value: Any) -> int:
+ """Patience in evaluations; anything unusable is 0, meaning off."""
+ if isinstance(value, bool) or value is None:
+ return 0
+ try:
+ patience = float(value)
+ except (TypeError, ValueError, OverflowError):
+ return 0
+ if not math.isfinite(patience) or patience < 1:
+ return 0
+ return min(int(patience), MAX_EARLY_STOPPING_PATIENCE)
+
+
+def create_early_stopping_callback(patience: int, user_stopped = None):
+ """HF TrainerCallback: counts evaluations whose eval_loss is not below the best so far, stops the run after
+ ``patience`` of them in a row, and, like load_best_model_at_end (and zoo's MLX trainer), copies the best
+ evaluation's trainable weights back when the run finishes, so the final save holds them.
+ Its own bookkeeping, not EarlyStoppingCallback, which needs metric_for_best_model and restores nothing without
+ load_best_model_at_end, and that needs checkpoints Studio does not write by default."""
+ from transformers import TrainerCallback
+
+ class EvalLossEarlyStopping(TrainerCallback):
+ def __init__(self):
+ self.patience = patience
+ self.best_loss: Optional[float] = None
+ self.best_step: Optional[int] = None
+ self.bad_evals = 0
+ self.stopped_at: Optional[int] = None
+ self.restored = False
+ self._best_weights: Optional[dict] = None
+ self._too_large = False
+
+ def on_evaluate(
+ self,
+ args,
+ state,
+ control,
+ metrics = None,
+ model = None,
+ **kwargs,
+ ):
+ loss = (metrics or {}).get("eval_loss")
+ if loss is None:
+ return
+ loss = float(loss)
+ # A diverged (NaN / inf) eval counts against patience and never becomes the best.
+ if math.isfinite(loss) and (self.best_loss is None or loss < self.best_loss):
+ self.best_loss = loss
+ self.best_step = state.global_step
+ self.bad_evals = 0
+ self._keep_best_weights(model)
+ return
+ self.bad_evals += 1
+ # At the last step the run ends anyway; calling that an early stop would misreport it.
+ max_steps = getattr(state, "max_steps", 0)
+ steps_left = not max_steps or state.global_step < max_steps
+ if self.bad_evals >= self.patience and self.stopped_at is None and steps_left:
+ self.stopped_at = state.global_step
+ control.should_training_stop = True
+ logger.info(
+ f"Early stopping at step {state.global_step}: eval loss has not improved for "
+ f"{self.bad_evals} evaluations (best {self.best_loss} at step {self.best_step})\n"
+ )
+
+ def on_train_end(
+ self,
+ args,
+ state,
+ control,
+ model = None,
+ **kwargs,
+ ):
+ # A user stop never restores, even on the step patience ran out: stop-and-save writes a resume
+ # checkpoint whose optimizer state is the current step's.
+ best, self._best_weights = self._best_weights, None
+ finished = self.stopped_at is not None or state.global_step >= state.max_steps
+ if user_stopped is not None and user_stopped():
+ finished = False
+ if not finished or self.best_step == state.global_step or best is None or model is None:
+ return
+ try:
+ import torch
+
+ # Check every shape before touching the model, so a mismatch leaves the final weights whole. copy_
+ # casts and moves one tensor at a time, so nothing is staged on the GPU.
+ pairs = [
+ (param, best[name]) for name, param in model.named_parameters() if name in best
+ ]
+ if any(param.shape != saved.shape for param, saved in pairs):
+ raise ValueError("a saved tensor no longer matches its parameter's shape")
+ with torch.no_grad():
+ for param, saved in pairs:
+ param.copy_(saved)
+ self.restored = True
+ logger.info(
+ f"Restored the weights from step {self.best_step} (eval loss {self.best_loss:.4f})\n"
+ )
+ except Exception as exc:
+ logger.warning(f"Could not restore the best weights, keeping the final ones: {exc}")
+
+ def _keep_best_weights(self, model):
+ if model is None or self._too_large:
+ return
+ try:
+ trainable = [(n, p) for n, p in model.named_parameters() if p.requires_grad]
+ size = sum(p.numel() * p.element_size() for _, p in trainable)
+ if size > MAX_BEST_WEIGHTS_BYTES:
+ self._too_large = True
+ self._best_weights = None
+ logger.info(
+ f"Early stopping keeps the final weights: {size / 2**30:.1f} GB of trainable "
+ "weights is too much to hold a copy of the best ones\n"
+ )
+ return
+ # Refill the previous copy in place: building a new dict first would hold two copies at once.
+ if self._best_weights is not None and self._best_weights.keys() == {
+ n for n, _ in trainable
+ }:
+ for n, p in trainable:
+ self._best_weights[n].copy_(p.detach())
+ else:
+ self._best_weights = None
+ self._best_weights = {n: p.detach().to("cpu", copy = True) for n, p in trainable}
+ except Exception as exc:
+ self._too_large = True
+ self._best_weights = None
+ logger.warning(f"Could not keep a copy of the best weights: {exc}")
+
+ return EvalLossEarlyStopping()
+
+
+def attach_early_stopping(
+ trainer,
+ value: Any,
+ user_stopped = None,
+):
+ """Add the callback to an HF trainer that evaluates; returns it, or None when off or there is nothing to watch."""
+ patience = early_stopping_patience(value)
+ if patience == 0:
+ return None
+ strategy = getattr(getattr(trainer, "args", None), "eval_strategy", "no")
+ if (
+ getattr(trainer, "eval_dataset", None) is None
+ or str(getattr(strategy, "value", strategy)) == "no"
+ ):
+ logger.info("Early stopping is off: this run has no evaluation to watch\n")
+ return None
+ callback = create_early_stopping_callback(patience, user_stopped = user_stopped)
+ trainer.add_callback(callback)
+ logger.info(f"Early stopping on: patience of {patience} evaluations\n")
+ return callback
diff --git a/studio/backend/core/training/trainer.py b/studio/backend/core/training/trainer.py
index 29830d06308..d85b591cae7 100644
--- a/studio/backend/core/training/trainer.py
+++ b/studio/backend/core/training/trainer.py
@@ -546,6 +546,7 @@ class UnslothTrainer:
self.is_training = False
self.should_stop = False
self.save_on_stop = True
+ self._early_stopping = None
self.load_in_4bit = True
self.is_cpt = False
@@ -1045,6 +1046,23 @@ class UnslothTrainer:
return _ProgressCallback()
+ def _attach_early_stopping(self, training_args):
+ from core.training.early_stopping import attach_early_stopping
+ self._early_stopping = attach_early_stopping(
+ self.trainer,
+ training_args.get("early_stopping_patience"),
+ user_stopped = lambda: self.should_stop,
+ )
+
+ def _early_stopping_summary(self) -> str:
+ es = self._early_stopping
+ if es is None:
+ return ""
+ summary = f"Stopped early at step {es.stopped_at}. " if es.stopped_at is not None else ""
+ if es.restored:
+ summary += f"Kept the weights from step {es.best_step} (eval loss {es.best_loss:.4f}). "
+ return summary
+
def _calculate_total_steps(self, num_samples, batch_size, grad_accum, num_epochs, max_steps):
"""Calculate total training steps from dataset size and training params."""
if max_steps and max_steps > 0:
@@ -1124,7 +1142,9 @@ class UnslothTrainer:
logger.info(f"\n{msg}. Model saved to {output_dir}\n")
self._update_progress(
is_training = False,
- status_message = f"Training stopped. Model saved to {output_dir}",
+ status_message = (
+ f"Training stopped. {self._early_stopping_summary()}Model saved to {output_dir}"
+ ),
)
elif self.should_stop:
msg = f"{label} training cancelled" if label else "Training cancelled"
@@ -1139,7 +1159,9 @@ class UnslothTrainer:
self._update_progress(
is_training = False,
is_completed = True,
- status_message = f"Training completed! Model saved to {output_dir}",
+ status_message = (
+ f"Training completed! {self._early_stopping_summary()}Model saved to {output_dir}"
+ ),
)
def _cleanup_audio_artifacts(self):
@@ -4427,6 +4449,7 @@ class UnslothTrainer:
trainer_kwargs["eval_dataset"] = eval_dataset
self.trainer = HFTrainer(**trainer_kwargs)
self.trainer.add_callback(self._create_progress_callback())
+ self._attach_early_stopping(training_args)
# Unsloth publishes progress itself, so HF's stdout callbacks are pure duplication in a log that has
# no terminal; --verbose keeps them.
_drop_hf_stdout_callbacks(self.trainer)
@@ -4473,6 +4496,7 @@ class UnslothTrainer:
trainer_kwargs["eval_dataset"] = eval_dataset
self.trainer = HFTrainer(**trainer_kwargs)
self.trainer.add_callback(self._create_progress_callback())
+ self._attach_early_stopping(training_args)
_drop_hf_stdout_callbacks(self.trainer)
batch_size = training_args.get("batch_size", 2)
@@ -4525,6 +4549,7 @@ class UnslothTrainer:
self.trainer = Seq2SeqTrainer(**trainer_kwargs)
self.trainer.add_callback(self._create_progress_callback())
+ self._attach_early_stopping(training_args)
_drop_hf_stdout_callbacks(self.trainer)
batch_size = training_args.get("batch_size", 2)
@@ -5105,6 +5130,7 @@ class UnslothTrainer:
logger.info("Training on full sequences (including prompts)\n")
self.trainer.add_callback(self._create_progress_callback())
+ self._attach_early_stopping(training_args)
# Unsloth publishes progress itself, so HF's stdout callbacks are pure duplication in a log that has no
# terminal; --verbose keeps them.
_drop_hf_stdout_callbacks(self.trainer)
diff --git a/studio/backend/core/training/training.py b/studio/backend/core/training/training.py
index 7aca6654f4c..dcab5fc7cef 100644
--- a/studio/backend/core/training/training.py
+++ b/studio/backend/core/training/training.py
@@ -261,6 +261,7 @@ def _build_training_worker_config(values: dict[str, Any]) -> dict[str, Any]:
"train_split": values.get("train_split", "train"),
"eval_split": values.get("eval_split"),
"eval_steps": values.get("eval_steps", 0.00),
+ "early_stopping_patience": values.get("early_stopping_patience", 0),
"dataset_streaming": values.get("dataset_streaming", False),
"dataset_slice_start": values.get("dataset_slice_start"),
"dataset_slice_end": values.get("dataset_slice_end"),
diff --git a/studio/backend/core/training/worker.py b/studio/backend/core/training/worker.py
index db99f8571cf..01ea659d1bb 100644
--- a/studio/backend/core/training/worker.py
+++ b/studio/backend/core/training/worker.py
@@ -2522,6 +2522,11 @@ def _start_mlx_stop_poller(stop_queue):
trainer = trainer_ref[0]
if trainer is not None:
trainer.stop_requested = True
+ # Early stopping set load_best_model_at_end; a manual stop keeps the current adapters instead, since the
+ # stop checkpoint stores this step's optimizer state next to them.
+ args = getattr(trainer, "args", None)
+ if getattr(args, "load_best_model_at_end", False):
+ args.load_best_model_at_end = False
stop_thread = _start_worker_stop_poller(
stop_queue,
@@ -2768,6 +2773,9 @@ def _finalize_mlx_training(
resume_blocked = True,
)
return
+ if not stopped_after_save and getattr(trainer, "_early_stopped", False):
+ # Zoo ends an early-stopped run without stop_requested, so it reads as a plain completion otherwise.
+ completion_message = "Training completed (stopped early: eval loss stopped improving)"
send(
"complete",
output_dir = output_dir if bool(trainer.is_main_process) else None,
@@ -3386,6 +3394,17 @@ def _run_mlx_training(event_queue, stop_queue, config):
# Refills the gradient-norm chart. MLX returns a norm for free only under global-norm clipping; asking for it
# beats switching clip modes, which would alter the loss trajectory and cost VLM runs mx.compile.
mlx_config_kwargs["report_grad_norm"] = True
+ if (
+ "early_stopping_patience" in _supported_fields
+ and "load_best_model_at_end" in _supported_fields
+ ):
+ from core.training.early_stopping import early_stopping_patience
+
+ # Zoo counts patience in evaluations and restores the best adapters itself, the CUDA path's contract.
+ patience = early_stopping_patience(config.get("early_stopping_patience"))
+ if patience and eval_dataset is not None and eval_steps_value > 0:
+ mlx_config_kwargs["early_stopping_patience"] = patience
+ mlx_config_kwargs["load_best_model_at_end"] = True
if "append_eos" in _supported_fields:
# Unsloth SFT formatting owns rendered examples; raw/CPT text still needs MLX to append EOS.
mlx_config_kwargs["append_eos"] = bool(raw_text_mode)
@@ -5058,6 +5077,7 @@ def run_training_process(*, event_queue: Any, stop_queue: Any, config: dict) ->
tensorboard_dir = tensorboard_dir,
eval_dataset = eval_dataset,
eval_steps = eval_steps,
+ early_stopping_patience = config.get("early_stopping_patience", 0),
max_seq_length = config.get("max_seq_length", 2048),
vision_image_size = config.get("vision_image_size"),
optim = config.get("optim", "adamw_8bit"),
diff --git a/studio/backend/models/training.py b/studio/backend/models/training.py
index 36f83e60fd0..ecdb7d2187c 100644
--- a/studio/backend/models/training.py
+++ b/studio/backend/models/training.py
@@ -205,6 +205,12 @@ class TrainingStartRequest(BaseModel):
description = "Whether to load the Hugging Face dataset in streaming mode",
)
eval_steps: float = Field(0.00, description = "Fraction of total steps between evals (0-1)")
+ early_stopping_patience: int = Field(
+ 0,
+ ge = 0,
+ le = 1000,
+ description = "Stop after this many evaluations without a lower eval loss and keep the best weights. 0 = off",
+ )
dataset_slice_start: Optional[int] = Field(
None,
ge = 0,
@@ -231,6 +237,13 @@ class TrainingStartRequest(BaseModel):
def _normalize_project_name(cls, value: Optional[str]) -> Optional[str]:
return normalize_project_name(value)
+ @field_validator("early_stopping_patience", mode = "before")
+ @classmethod
+ def _reject_boolean_patience(cls, value: Any) -> Any:
+ if isinstance(value, bool):
+ raise ValueError("early_stopping_patience must be a number, not a boolean")
+ return value
+
@field_validator("eval_steps", mode = "before")
@classmethod
def _normalize_eval_steps(cls, value: Any) -> Any:
diff --git a/studio/backend/routes/training.py b/studio/backend/routes/training.py
index e62f34083a1..a54c2faea94 100644
--- a/studio/backend/routes/training.py
+++ b/studio/backend/routes/training.py
@@ -2118,6 +2118,7 @@ async def start_training(
"dataset_streaming": request.dataset_streaming,
"eval_split": request.eval_split,
"eval_steps": request.eval_steps,
+ "early_stopping_patience": request.early_stopping_patience,
"dataset_slice_start": request.dataset_slice_start,
"dataset_slice_end": request.dataset_slice_end,
"custom_format_mapping": request.custom_format_mapping,
diff --git a/studio/backend/tests/test_early_stopping.py b/studio/backend/tests/test_early_stopping.py
new file mode 100644
index 00000000000..ae23797b8b0
--- /dev/null
+++ b/studio/backend/tests/test_early_stopping.py
@@ -0,0 +1,392 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Early stopping on eval loss, driven through a real transformers Trainer on CPU."""
+
+import math
+
+import pytest
+import torch
+from torch import nn
+from transformers import Trainer, TrainingArguments
+
+from core.training import early_stopping as es
+from core.training.early_stopping import attach_early_stopping, early_stopping_patience
+
+
+class _Line(nn.Module):
+ """y = w, so loss is (w - target)^2 and the step direction is fully determined by the data."""
+
+ def __init__(self):
+ super().__init__()
+ self.w = nn.Parameter(torch.zeros(1))
+
+ def forward(
+ self,
+ x,
+ labels = None,
+ ):
+ pred = self.w.expand_as(x)
+ return {"loss": ((pred - labels) ** 2).mean(), "logits": pred}
+
+
+class _Rows(torch.utils.data.Dataset):
+ def __init__(
+ self,
+ target,
+ n = 8,
+ ):
+ self.target, self.n = target, n
+
+ def __len__(self):
+ return self.n
+
+ def __getitem__(self, i):
+ return {"x": torch.ones(1), "labels": torch.full((1,), float(self.target))}
+
+
+def _trainer(
+ tmp_path,
+ *,
+ eval_target = -1.0,
+ max_steps = 20,
+ eval_dataset = True,
+ **args,
+):
+ # Training pulls w toward +1 and evaluation scores it against eval_target, so with -1 every step makes
+ # eval loss worse and with +1 every step makes it better.
+ config = dict(
+ output_dir = str(tmp_path),
+ per_device_train_batch_size = 2,
+ learning_rate = 0.05,
+ max_steps = max_steps,
+ eval_strategy = "steps",
+ eval_steps = 1,
+ save_strategy = "no",
+ logging_steps = 1,
+ report_to = "none",
+ use_cpu = True,
+ lr_scheduler_type = "constant",
+ optim = "sgd",
+ disable_tqdm = True,
+ )
+ config.update(args)
+ return Trainer(
+ model = _Line(),
+ args = TrainingArguments(**config),
+ train_dataset = _Rows(1.0),
+ eval_dataset = _Rows(eval_target) if eval_dataset else None,
+ )
+
+
+def _w_after_steps(tmp_path, steps):
+ trainer = _trainer(tmp_path / f"ref{steps}", max_steps = steps, eval_strategy = "no")
+ trainer.train()
+ return trainer.model.w.item()
+
+
+ "value,expected",
+ [
+ (None, 0),
+ (0, 0),
+ (3, 3),
+ ("4", 4),
+ (2.9, 2),
+ (True, 0),
+ (-1, 0),
+ (float("nan"), 0),
+ (float("inf"), 0),
+ ("abc", 0),
+ (10**9, es.MAX_EARLY_STOPPING_PATIENCE),
+ ],
+)
+def test_patience_coercion(value, expected):
+ assert early_stopping_patience(value) == expected
+
+
+def test_stops_after_patience_and_keeps_the_best_weights(tmp_path):
+ trainer = _trainer(tmp_path)
+ callback = attach_early_stopping(trainer, 2)
+ trainer.train()
+
+ # Step 1 is the first evaluation and so the best; steps 2 and 3 are worse, which is patience 2.
+ assert trainer.state.global_step == 3
+ assert callback.stopped_at == 3 and callback.best_step == 1 and callback.restored
+ assert trainer.model.w.item() == pytest.approx(_w_after_steps(tmp_path, 1))
+ assert trainer.model.w.item() != pytest.approx(_w_after_steps(tmp_path, 3))
+
+
+def test_improving_run_is_untouched(tmp_path):
+ trainer = _trainer(tmp_path, eval_target = 1.0, max_steps = 6)
+ callback = attach_early_stopping(trainer, 2)
+ trainer.train()
+
+ assert trainer.state.global_step == 6
+ assert callback.stopped_at is None and not callback.restored and callback.best_step == 6
+ assert trainer.model.w.item() == pytest.approx(_w_after_steps(tmp_path, 6))
+
+
+def test_run_ending_on_worse_evals_still_saves_the_best(tmp_path):
+ trainer = _trainer(tmp_path, max_steps = 3)
+ callback = attach_early_stopping(trainer, 5)
+ trainer.train()
+
+ assert trainer.state.global_step == 3 and callback.stopped_at is None
+ assert callback.restored and callback.best_step == 1
+ assert trainer.model.w.item() == pytest.approx(_w_after_steps(tmp_path, 1))
+
+
+def test_off_or_without_evaluation_adds_nothing(tmp_path):
+ for trainer, value in [
+ (_trainer(tmp_path / "a"), 0),
+ (_trainer(tmp_path / "b"), None),
+ (_trainer(tmp_path / "c", eval_dataset = False, eval_strategy = "no"), 3),
+ (_trainer(tmp_path / "d", eval_strategy = "no"), 3),
+ ]:
+ before = list(trainer.callback_handler.callbacks)
+ assert attach_early_stopping(trainer, value) is None
+ assert trainer.callback_handler.callbacks == before
+
+
+def _feed(callback, losses):
+ class _State:
+ global_step = 0
+
+ class _Control:
+ should_training_stop = False
+
+ state, control = _State(), _Control()
+ for step, loss in enumerate(losses, start = 1):
+ state.global_step = step
+ callback.on_evaluate(None, state, control, metrics = {"eval_loss": loss})
+ return control
+
+
+def test_nan_eval_loss_counts_against_patience():
+ callback = es.create_early_stopping_callback(2)
+ control = _feed(callback, [1.0, float("nan"), float("nan")])
+ assert control.should_training_stop and callback.best_loss == 1.0 and callback.stopped_at == 3
+
+
+def test_a_nan_first_eval_never_becomes_the_best():
+ callback = es.create_early_stopping_callback(2)
+ control = _feed(callback, [float("nan"), 0.9, 0.8])
+ assert not control.should_training_stop
+ assert callback.best_loss == 0.8 and callback.best_step == 3 and callback.bad_evals == 0
+ assert not math.isnan(callback.best_loss)
+
+
+def test_a_user_stop_keeps_the_current_weights(tmp_path):
+ # Stop-and-save writes a resume checkpoint with this step's optimizer state, so the weights must match it.
+ from transformers import TrainerCallback
+
+ class _UserStop(TrainerCallback):
+ def on_evaluate(self, args, state, control, **kwargs):
+ if state.global_step == 2:
+ control.should_training_stop = True
+
+ trainer = _trainer(tmp_path)
+ callback = attach_early_stopping(trainer, 5)
+ trainer.add_callback(_UserStop())
+ trainer.train()
+
+ assert (
+ trainer.state.global_step == 2 and callback.bad_evals == 1 and callback.stopped_at is None
+ )
+ assert not callback.restored
+ assert trainer.model.w.item() == pytest.approx(_w_after_steps(tmp_path, 2))
+
+
+def test_too_large_to_copy_still_stops_with_the_final_weights(tmp_path, monkeypatch):
+ monkeypatch.setattr(es, "MAX_BEST_WEIGHTS_BYTES", 0)
+ trainer = _trainer(tmp_path)
+ callback = attach_early_stopping(trainer, 2)
+ trainer.train()
+
+ assert trainer.state.global_step == 3 and callback.stopped_at == 3 and not callback.restored
+ assert trainer.model.w.item() == pytest.approx(_w_after_steps(tmp_path, 3))
+
+
+def test_request_model_accepts_and_validates_patience():
+ from pydantic import ValidationError
+
+ from models.training import TrainingStartRequest
+
+ base = dict(model_name = "x", format_type = "auto", hf_dataset = "a/b", training_type = "LoRA/QLoRA")
+ assert TrainingStartRequest(**base).early_stopping_patience == 0
+ assert TrainingStartRequest(**base, early_stopping_patience = 3).early_stopping_patience == 3
+ for bad in (True, -1, 2.5, 1001):
+ with pytest.raises(ValidationError):
+ TrainingStartRequest(**base, early_stopping_patience = bad)
+
+
+def test_worker_config_carries_patience():
+ from core.training.training import _build_training_worker_config
+
+ assert _build_training_worker_config({"model_name": "m"})["early_stopping_patience"] == 0
+ config = _build_training_worker_config({"model_name": "m", "early_stopping_patience": 4})
+ assert config["early_stopping_patience"] == 4
+
+
+def test_mlx_worker_hands_patience_to_zoo_only_when_it_can_take_it():
+ # MLXTrainingConfig implements patience and best-adapter restore itself; the worker only forwards the
+ # setting, gated on the fields so an older unsloth-zoo still constructs its config.
+ from pathlib import Path
+
+ source = (Path(__file__).resolve().parents[1] / "core" / "training" / "worker.py").read_text(
+ encoding = "utf-8"
+ )
+ gate = source.index('"early_stopping_patience" in _supported_fields')
+ block = source[gate : source.index('if "append_eos" in _supported_fields:', gate)]
+ assert '"load_best_model_at_end" in _supported_fields' in block
+ assert "if patience and eval_dataset is not None and eval_steps_value > 0:" in block
+ assert 'mlx_config_kwargs["early_stopping_patience"] = patience' in block
+ assert 'mlx_config_kwargs["load_best_model_at_end"] = True' in block
+ assert source.index("mlx_config_kwargs = dict(") < gate < source.index("trainer = MLXTrainer(")
+
+
+def test_mlx_manual_stop_turns_off_the_best_adapter_restore():
+ # Zoo restores the best adapters before the stop checkpoint is written; a manual stop must keep the current ones.
+ import queue
+ import time
+ import types
+
+ from core.training import worker
+
+ stop_queue = queue.Queue()
+ _, _, trainer_ref, _, stop_thread = worker._start_mlx_stop_poller(stop_queue)
+ trainer = types.SimpleNamespace(
+ stop_requested = False, args = types.SimpleNamespace(load_best_model_at_end = True)
+ )
+ trainer_ref[0] = trainer
+ stop_queue.put({"type": "stop", "save": True})
+ deadline = time.time() + 5
+ while not trainer.stop_requested and time.time() < deadline:
+ time.sleep(0.05)
+ assert trainer.stop_requested and trainer.args.load_best_model_at_end is False
+ stop_queue.put({"type": "stop", "save": False})
+ stop_thread.join(timeout = 5)
+
+
+def test_status_reports_an_early_stop_even_without_a_restore(tmp_path, monkeypatch):
+ import types
+
+ from core.training.trainer import UnslothTrainer
+
+ monkeypatch.setattr(es, "MAX_BEST_WEIGHTS_BYTES", 0)
+ trainer = _trainer(tmp_path)
+ callback = attach_early_stopping(trainer, 2)
+ trainer.train()
+ summary = UnslothTrainer._early_stopping_summary(
+ types.SimpleNamespace(_early_stopping = callback)
+ )
+ assert summary == "Stopped early at step 3. "
+ assert callback._best_weights is None
+
+
+def test_the_best_weight_copy_is_released_when_not_needed(tmp_path):
+ trainer = _trainer(tmp_path, eval_target = 1.0, max_steps = 4)
+ callback = attach_early_stopping(trainer, 2)
+ trainer.train()
+ assert not callback.restored and callback._best_weights is None
+
+
+def test_a_new_best_refills_the_copy_in_place():
+ # Building a fresh dict per improvement would hold two full copies of the trainable weights at once.
+ callback = es.create_early_stopping_callback(3)
+ model = _Line()
+
+ class _State:
+ global_step = 1
+
+ callback.on_evaluate(None, _State(), None, metrics = {"eval_loss": 2.0}, model = model)
+ first = callback._best_weights["w"]
+ with torch.no_grad():
+ model.w.fill_(5.0)
+ _State.global_step = 2
+ callback.on_evaluate(None, _State(), None, metrics = {"eval_loss": 1.0}, model = model)
+ assert callback._best_weights["w"] is first and first.item() == 5.0
+
+
+def test_mlx_early_stop_is_named_in_the_final_status():
+ import types
+
+ from core.training import worker
+
+ def finish(early_stopped):
+ events = []
+ trainer = types.SimpleNamespace(
+ distributed_world_size = 1,
+ is_main_process = True,
+ stop_requested = False,
+ _early_stopped = early_stopped,
+ save_model = lambda path: None,
+ )
+ worker._finalize_mlx_training(
+ trainer,
+ lambda: (False, True),
+ "/out",
+ lambda: None,
+ lambda kind, **payload: events.append((kind, payload)),
+ lambda: True,
+ )
+ return events[-1]
+
+ assert finish(False) == (
+ "complete",
+ {"output_dir": "/out", "status_message": "Training completed"},
+ )
+ assert finish(True)[1]["status_message"] == (
+ "Training completed (stopped early: eval loss stopped improving)"
+ )
+
+
+def test_steps_after_the_best_evaluation_roll_back_like_load_best_model_at_end(tmp_path):
+ # Zoo's MLX trainer restores the best adapters whenever the run finishes; the CUDA path keeps the same contract.
+ trainer = _trainer(tmp_path, eval_target = 1.0, max_steps = 5, eval_steps = 2)
+ callback = attach_early_stopping(trainer, 3)
+ trainer.train()
+
+ # transformers 5 also evaluates the final step, leaving no tail; older releases stop evaluating at step 4.
+ assert trainer.state.global_step == 5 and callback.best_step in (4, 5)
+ assert callback.restored == (callback.best_step == 4)
+ assert trainer.model.w.item() == pytest.approx(_w_after_steps(tmp_path, callback.best_step))
+
+
+def test_a_user_stop_on_the_step_patience_runs_out_still_keeps_the_current_weights(tmp_path):
+ trainer = _trainer(tmp_path)
+ callback = attach_early_stopping(trainer, 2, user_stopped = lambda: True)
+ trainer.train()
+
+ assert trainer.state.global_step == 3 and callback.stopped_at == 3 and not callback.restored
+ assert trainer.model.w.item() == pytest.approx(_w_after_steps(tmp_path, 3))
+
+
+def test_a_finished_run_rolls_back_unevaluated_steps():
+ callback = es.create_early_stopping_callback(3)
+ model = _Line()
+
+ class _State:
+ global_step = 4
+ max_steps = 5
+
+ callback.on_evaluate(None, _State(), None, metrics = {"eval_loss": 1.0}, model = model)
+ with torch.no_grad():
+ model.w.fill_(7.0)
+ _State.global_step = 5
+ callback.on_train_end(None, _State(), None, model = model)
+ assert callback.restored and model.w.item() == 0.0 and callback._best_weights is None
+
+
+def test_running_out_of_patience_on_the_last_step_is_not_an_early_stop(tmp_path):
+ trainer = _trainer(tmp_path, max_steps = 3)
+ callback = attach_early_stopping(trainer, 2)
+ trainer.train()
+
+ assert (
+ trainer.state.global_step == 3 and callback.bad_evals == 2 and callback.stopped_at is None
+ )
+ assert callback.restored and trainer.model.w.item() == pytest.approx(
+ _w_after_steps(tmp_path, 1)
+ )
diff --git a/studio/frontend/src/config/training.ts b/studio/frontend/src/config/training.ts
index a01d39e345f..f86d415a46e 100644
--- a/studio/frontend/src/config/training.ts
+++ b/studio/frontend/src/config/training.ts
@@ -168,6 +168,7 @@ export const DEFAULT_HYPERPARAMS = {
maxSteps: 60,
saveSteps: 0,
evalSteps: 0.0,
+ earlyStoppingPatience: 0,
packing: false,
trainOnCompletions: false,
gradientCheckpointing: "unsloth" as const,
diff --git a/studio/frontend/src/features/studio/sections/training-hyperparameters-section.tsx b/studio/frontend/src/features/studio/sections/training-hyperparameters-section.tsx
index 4184767e69a..4cf5df55e55 100644
--- a/studio/frontend/src/features/studio/sections/training-hyperparameters-section.tsx
+++ b/studio/frontend/src/features/studio/sections/training-hyperparameters-section.tsx
@@ -85,6 +85,7 @@ export function TrainingHyperparametersSection({
useShallow((state) => ({
epochs: state.epochs,
isDecision: state.modelType === "decision",
+ isEmbedding: state.isEmbeddingModel || state.modelType === "embeddings",
optimizerType: state.optimizerType,
lrSchedulerType: state.lrSchedulerType,
batchSize: state.batchSize,
@@ -93,6 +94,7 @@ export function TrainingHyperparametersSection({
warmupSteps: state.warmupSteps,
saveSteps: state.saveSteps,
evalSteps: state.evalSteps,
+ earlyStoppingPatience: state.earlyStoppingPatience,
randomSeed: state.randomSeed,
setOptimizerType: state.setOptimizerType,
setLrSchedulerType: state.setLrSchedulerType,
@@ -103,6 +105,7 @@ export function TrainingHyperparametersSection({
setEpochs: state.setEpochs,
setSaveSteps: state.setSaveSteps,
setEvalSteps: state.setEvalSteps,
+ setEarlyStoppingPatience: state.setEarlyStoppingPatience,
setRandomSeed: state.setRandomSeed,
})),
);
@@ -378,6 +381,25 @@ export function TrainingHyperparametersSection({
className="w-28 font-mono"
/>
</ParamsRow>
+ {!store.isDecision && !store.isEmbedding && (
+ <ParamsRow
+ label={t("studio.params.earlyStoppingPatience")}
+ tooltip={t("studio.params.earlyStoppingPatienceTooltip")}
+ >
+ <Input
+ type="number"
+ step="1"
+ min="0"
+ max="1000"
+ disabled={store.evalSteps <= 0}
+ value={store.earlyStoppingPatience}
+ onChange={(event) =>
+ store.setEarlyStoppingPatience(Number(event.target.value))
+ }
+ className="w-28 font-mono"
+ />
+ </ParamsRow>
+ )}
<ParamsRow
label={t("studio.params.seed")}
tooltip={t("studio.params.seedTooltip")}
diff --git a/studio/frontend/src/features/training/api/mappers.ts b/studio/frontend/src/features/training/api/mappers.ts
index b3bdbbf9310..3e4318dd732 100644
--- a/studio/frontend/src/features/training/api/mappers.ts
+++ b/studio/frontend/src/features/training/api/mappers.ts
@@ -18,6 +18,12 @@ function parseSliceValue(value: string | null): number | null {
return num;
}
+// The backend takes a whole number in [0, 1000]; a half-typed or out-of-range field must not 422 the Start.
+function normalizeEarlyStoppingPatience(value: number): number {
+ if (!Number.isFinite(value) || value < 1) return 0;
+ return Math.min(Math.floor(value), 1000);
+}
+
function buildS3PayloadConfig(config: TrainingConfigState) {
const s3 = config.datasetSource === "s3" ? config.s3Config : null;
if (!s3) {
@@ -261,6 +267,10 @@ export function buildTrainingStartPayload(
max_steps: config.maxSteps,
save_steps: config.saveSteps,
eval_steps: config.evalSteps,
+ early_stopping_patience:
+ config.evalSteps > 0 && !isDecision && !isEmbedding
+ ? normalizeEarlyStoppingPatience(config.earlyStoppingPatience)
+ : 0,
weight_decay: config.weightDecay,
// max_grad_norm omitted on purpose: the backend now honors an explicit value,
// so hardcoding 0 here would pin every UI run to "clipping off" and override
diff --git a/studio/frontend/src/features/training/api/models-api.ts b/studio/frontend/src/features/training/api/models-api.ts
index 12a41059e99..5d382dbd4d7 100644
--- a/studio/frontend/src/features/training/api/models-api.ts
+++ b/studio/frontend/src/features/training/api/models-api.ts
@@ -28,6 +28,7 @@ interface BackendTrainingDefaults {
max_steps?: number;
save_steps?: number;
eval_steps?: number;
+ early_stopping_patience?: number;
weight_decay?: number;
random_seed?: number;
offload_layers?: number | "auto";
diff --git a/studio/frontend/src/features/training/lib/yaml-config.ts b/studio/frontend/src/features/training/lib/yaml-config.ts
index 834d8537d19..b67888c72c7 100644
--- a/studio/frontend/src/features/training/lib/yaml-config.ts
+++ b/studio/frontend/src/features/training/lib/yaml-config.ts
@@ -89,6 +89,7 @@ export function serializeConfigToYaml(
max_steps: state.maxSteps,
save_steps: state.saveSteps,
eval_steps: state.evalSteps,
+ early_stopping_patience: state.earlyStoppingPatience,
weight_decay: state.weightDecay,
random_seed: state.randomSeed,
packing: state.packing,
diff --git a/studio/frontend/src/features/training/stores/training-config-store.ts b/studio/frontend/src/features/training/stores/training-config-store.ts
index b58ac6d1279..feb4dc14c0a 100644
--- a/studio/frontend/src/features/training/stores/training-config-store.ts
+++ b/studio/frontend/src/features/training/stores/training-config-store.ts
@@ -116,6 +116,12 @@ function canReapplyModelDefaults(modelName: string): boolean {
const DEFAULT_DECISION_CHECKPOINT = "laya-multilingual";
+// Saved runs and YAML files carry it, but it is not a model default: switching models keeps it.
+function earlyStoppingPatienceFrom(value: unknown): number {
+ const patience = Number(value);
+ return Number.isFinite(patience) && patience > 0 ? Math.floor(patience) : 0;
+}
+
// evalSteps is left alone: it follows the chosen eval split, not the model.
const GENERIC_MODEL_DEFAULTS = Object.fromEntries(
MODEL_DEFAULT_STATE_KEYS.filter((key) => key !== "evalSteps").map((key) => [
@@ -1602,6 +1608,8 @@ export const useTrainingConfigStore = create<TrainingConfigStore>()(
});
notifyStreamingCompat(streamingPatch);
},
+ setEarlyStoppingPatience: (earlyStoppingPatience) =>
+ setUserEdit({ earlyStoppingPatience }),
setPacking: (packing) => setUserEdit({ packing }),
setTrainOnCompletions: (trainOnCompletions) => {
_trainOnCompletionsManuallySet = true;
@@ -1657,7 +1665,13 @@ export const useTrainingConfigStore = create<TrainingConfigStore>()(
_trainingMethodEditGeneration += 1;
_trainOnCompletionsManuallySet = true;
_trainOnCompletionsExplicitModel = selections.selectedModel;
- setUserEdit({ ...hyperparameters, ...selections });
+ setUserEdit({
+ ...hyperparameters,
+ ...selections,
+ earlyStoppingPatience: earlyStoppingPatienceFrom(
+ config.early_stopping_patience,
+ ),
+ });
// Fetch capabilities without replacing the saved recipe.
loadAndApplyModelDefaults(selections.selectedModel, {
applyTrainingDefaults: false,
@@ -1699,12 +1713,23 @@ export const useTrainingConfigStore = create<TrainingConfigStore>()(
if (patch.trainOnCompletions !== undefined) {
_trainOnCompletionsExplicitModel = get().selectedModel;
}
+ const importsPatience = Object.hasOwn(
+ config.training ?? {},
+ "early_stopping_patience",
+ );
setUserEdit((state) => {
const importsCompletionsInCpt =
state.trainingMethod === "cpt" &&
patch.trainOnCompletions !== undefined;
return {
...patch,
+ ...(importsPatience
+ ? {
+ earlyStoppingPatience: earlyStoppingPatienceFrom(
+ config.training?.early_stopping_patience,
+ ),
+ }
+ : {}),
...(patch.trainOnCompletions !== undefined
? { trainOnCompletionsDefaultPendingFor: null }
: {}),
diff --git a/studio/frontend/src/features/training/types/api.ts b/studio/frontend/src/features/training/types/api.ts
index 3b1d2717c58..12939a25398 100644
--- a/studio/frontend/src/features/training/types/api.ts
+++ b/studio/frontend/src/features/training/types/api.ts
@@ -48,6 +48,7 @@ export interface TrainingStartRequest {
max_steps: number | null;
save_steps: number;
eval_steps: number;
+ early_stopping_patience?: number;
weight_decay: number;
max_grad_norm?: number | null;
max_grad_value?: number | null;
diff --git a/studio/frontend/src/features/training/types/config.ts b/studio/frontend/src/features/training/types/config.ts
index 13fb0b28a03..cf66950dbe8 100644
--- a/studio/frontend/src/features/training/types/config.ts
+++ b/studio/frontend/src/features/training/types/config.ts
@@ -123,6 +123,8 @@ export interface TrainingConfigState {
maxSteps: number;
saveSteps: number;
evalSteps: number;
+ /** Evaluations without a lower eval loss before the run stops; 0 = off. */
+ earlyStoppingPatience: number;
packing: boolean;
trainOnCompletions: boolean;
gradientCheckpointing: GradientCheckpointing;
@@ -264,6 +266,7 @@ export interface TrainingConfigActions {
setMaxSteps: (value: number) => void;
setSaveSteps: (value: number) => void;
setEvalSteps: (value: number) => void;
+ setEarlyStoppingPatience: (value: number) => void;
setPacking: (value: boolean) => void;
setTrainOnCompletions: (value: boolean) => void;
setGradientCheckpointing: (value: GradientCheckpointing) => void;
diff --git a/studio/frontend/src/i18n/locales/ar.ts b/studio/frontend/src/i18n/locales/ar.ts
index f20742f1014..12681edde8f 100644
--- a/studio/frontend/src/i18n/locales/ar.ts
+++ b/studio/frontend/src/i18n/locales/ar.ts
@@ -3623,6 +3623,9 @@ export const ar = {
evalSteps: "خطوات التقييم",
evalStepsTooltip:
"نسبة إجمالي خطوات التدريب بين عمليات التقييم (0-1). اضبطها على 0 لتعطيل التقييم. مثال: 0.01 = تقييم كل 1% من الخطوات.",
+ earlyStoppingPatience: "صبر الإيقاف المبكر",
+ earlyStoppingPatienceTooltip:
+ "يوقف التدريب بعد هذا العدد من التقييمات المتتالية دون انخفاض في خسارة التقييم، ويحتفظ بأوزان أفضل تقييم. يتطلب تفعيل التقييم (خطوات التقييم أكبر من 0). اضبطه على 0 للتعطيل.",
seed: "البذرة (Seed)",
seedTooltip: "بذرة عشوائية لإمكانية إعادة الإنتاج.",
offloadLayers: "تفريغ الطبقات",
diff --git a/studio/frontend/src/i18n/locales/de.ts b/studio/frontend/src/i18n/locales/de.ts
index c4cb6610376..c421bb55715 100644
--- a/studio/frontend/src/i18n/locales/de.ts
+++ b/studio/frontend/src/i18n/locales/de.ts
@@ -3682,6 +3682,9 @@ export const de = {
evalSteps: "Eval-Schritte",
evalStepsTooltip:
"Anteil der gesamten Trainingsschritte zwischen Auswertungen (0-1). Auf 0 setzen, um die Auswertung zu deaktivieren. Z. B. 0.01 = alle 1 % der Schritte auswerten.",
+ earlyStoppingPatience: "Early-Stopping-Geduld",
+ earlyStoppingPatienceTooltip:
+ "Beendet das Training nach so vielen Evaluierungen in Folge ohne niedrigeren Eval-Loss und behält die Gewichte der besten Evaluierung. Erfordert Evaluierung (Eval-Schritte über 0). 0 deaktiviert es.",
seed: "Seed",
seedTooltip: "Zufalls-Seed für Reproduzierbarkeit.",
offloadLayers: "Schichten auslagern",
diff --git a/studio/frontend/src/i18n/locales/en.ts b/studio/frontend/src/i18n/locales/en.ts
index 4fec7084394..4b4f57378b7 100644
--- a/studio/frontend/src/i18n/locales/en.ts
+++ b/studio/frontend/src/i18n/locales/en.ts
@@ -3660,6 +3660,9 @@ export const en = {
evalSteps: "Eval Steps",
evalStepsTooltip:
"Fraction of total training steps between evaluations (0-1). Set to 0 to disable evaluation. E.g. 0.01 = evaluate every 1% of steps.",
+ earlyStoppingPatience: "Early Stopping Patience",
+ earlyStoppingPatienceTooltip:
+ "Stop training after this many evaluations in a row without a lower eval loss, and keep the weights from the best evaluation. Needs evaluation (Eval Steps above 0). 0 to disable.",
seed: "Seed",
seedTooltip: "Random seed for reproducibility.",
offloadLayers: "Offload layers",
diff --git a/studio/frontend/src/i18n/locales/es.ts b/studio/frontend/src/i18n/locales/es.ts
index 4568c843f49..581ab7510ba 100644
--- a/studio/frontend/src/i18n/locales/es.ts
+++ b/studio/frontend/src/i18n/locales/es.ts
@@ -3677,6 +3677,9 @@ export const es = {
evalSteps: "Pasos entre evaluaciones",
evalStepsTooltip:
"Fracción del total de pasos de entrenamiento entre evaluaciones (0-1). Pon 0 para desactivar la evaluación. P. ej. 0.01 = evaluar cada 1 % de los pasos.",
+ earlyStoppingPatience: "Paciencia de parada temprana",
+ earlyStoppingPatienceTooltip:
+ "Detiene el entrenamiento tras este número de evaluaciones seguidas sin una pérdida de evaluación menor y conserva los pesos de la mejor evaluación. Requiere evaluación (pasos entre evaluaciones mayor que 0). 0 para desactivar.",
seed: "Semilla",
seedTooltip: "Semilla aleatoria para reproducibilidad.",
offloadLayers: "Descargar capas",
diff --git a/studio/frontend/src/i18n/locales/fr.ts b/studio/frontend/src/i18n/locales/fr.ts
index 1d65f105079..5578a36e8d0 100644
--- a/studio/frontend/src/i18n/locales/fr.ts
+++ b/studio/frontend/src/i18n/locales/fr.ts
@@ -3692,6 +3692,9 @@ export const fr = {
evalSteps: "Étapes d'évaluation",
evalStepsTooltip:
"Fraction du nombre total d'étapes d'entraînement entre les évaluations (0-1). Définissez 0 pour désactiver l'évaluation. Ex. 0,01 = évaluer tous les 1 % d'étapes.",
+ earlyStoppingPatience: "Patience d'arrêt anticipé",
+ earlyStoppingPatienceTooltip:
+ "Arrête l'entraînement après ce nombre d'évaluations consécutives sans perte d'évaluation plus basse, et conserve les poids de la meilleure évaluation. Nécessite l'évaluation (étapes d'évaluation supérieures à 0). 0 pour désactiver.",
seed: "Graine",
seedTooltip: "Graine aléatoire pour la reproductibilité.",
offloadLayers: "Décharger des couches",
diff --git a/studio/frontend/src/i18n/locales/he.ts b/studio/frontend/src/i18n/locales/he.ts
index 7eec259f2d6..17db8540388 100644
--- a/studio/frontend/src/i18n/locales/he.ts
+++ b/studio/frontend/src/i18n/locales/he.ts
@@ -3729,6 +3729,9 @@ export const he = {
evalSteps: "צעדי הערכה (Eval Steps)",
evalStepsTooltip:
"חלק מסך כל צעדי האימון בין הערכות (0-1). הגדר 0 כדי להשבית הערכה. לדוגמה 0.01 = הערכה בכל 1% מהצעדים.",
+ earlyStoppingPatience: "סבלנות לעצירה מוקדמת (Early Stopping)",
+ earlyStoppingPatienceTooltip:
+ "עוצר את האימון אחרי מספר כזה של הערכות ברצף בלי ירידה ב-eval loss, ושומר את המשקלים מההערכה הטובה ביותר. דורש הערכה (צעדי הערכה מעל 0). 0 לביטול.",
seed: "גרעין אקראיות (Seed)",
seedTooltip: "גרעין אקראי לשחזור מדויק של תוצאות.",
offloadLayers: "העברת שכבות לזיכרון המערכת",
diff --git a/studio/frontend/src/i18n/locales/hi.ts b/studio/frontend/src/i18n/locales/hi.ts
index b5152617e13..bbbbe172d64 100644
--- a/studio/frontend/src/i18n/locales/hi.ts
+++ b/studio/frontend/src/i18n/locales/hi.ts
@@ -3631,6 +3631,9 @@ export const hi = {
evalSteps: "Eval स्टेप्स",
evalStepsTooltip:
"मूल्यांकनों के बीच कुल ट्रेनिंग स्टेप्स का अंश (0-1)। मूल्यांकन अक्षम करने के लिए 0 सेट करें। उदा. 0.01 = हर 1% स्टेप्स पर मूल्यांकन करें।",
+ earlyStoppingPatience: "Early stopping धैर्य",
+ earlyStoppingPatienceTooltip:
+ "लगातार इतने मूल्यांकनों में eval loss कम न होने पर ट्रेनिंग रोक देता है और सबसे अच्छे मूल्यांकन के वेट रखता है। मूल्यांकन ज़रूरी है (Eval स्टेप्स 0 से ज़्यादा)। बंद करने के लिए 0 रखें।",
seed: "सीड",
seedTooltip: "पुनरुत्पादन के लिए रैंडम seed।",
offloadLayers: "परतें ऑफ़लोड करें",
diff --git a/studio/frontend/src/i18n/locales/it.ts b/studio/frontend/src/i18n/locales/it.ts
index f4cf81d97bb..7c43931248d 100644
--- a/studio/frontend/src/i18n/locales/it.ts
+++ b/studio/frontend/src/i18n/locales/it.ts
@@ -3685,6 +3685,9 @@ export const it = {
evalSteps: "Step fra le valutazioni",
evalStepsTooltip:
"Frazione degli step totali fra due valutazioni (0-1). Imposta 0 per disattivare la valutazione. Per esempio 0,01 = valuta ogni 1% degli step.",
+ earlyStoppingPatience: "Pazienza early stopping",
+ earlyStoppingPatienceTooltip:
+ "Interrompe l'addestramento dopo questo numero di valutazioni consecutive senza una loss di valutazione più bassa e mantiene i pesi della valutazione migliore. Richiede la valutazione (step fra le valutazioni maggiore di 0). 0 per disattivare.",
seed: "Seed",
seedTooltip: "Seed casuale per la riproducibilità.",
offloadLayers: "Scarica livelli",
diff --git a/studio/frontend/src/i18n/locales/ja.ts b/studio/frontend/src/i18n/locales/ja.ts
index 462306c051e..b98623c40df 100644
--- a/studio/frontend/src/i18n/locales/ja.ts
+++ b/studio/frontend/src/i18n/locales/ja.ts
@@ -3575,6 +3575,9 @@ export const ja = {
saveStepsTooltip: "N ステップごとにチェックポイントを保存します。0 で無効化します。",
evalSteps: "評価ステップ間隔",
evalStepsTooltip: "評価を行う間隔を、総トレーニングステップに対する割合 (0-1) で指定します。0 に設定すると評価が無効になります。例: 0.01 = ステップの 1% ごとに評価を実行。",
+ earlyStoppingPatience: "早期終了の猶予回数",
+ earlyStoppingPatienceTooltip:
+ "評価ロスが下がらない評価がこの回数続いたらトレーニングを停止し、最良の評価時の重みを保持します。評価が必要です (評価ステップ間隔を 0 より大きく設定)。0 で無効になります。",
seed: "シード値",
seedTooltip: "再現性のための乱数シード。",
offloadLayers: "レイヤーのオフロード",
diff --git a/studio/frontend/src/i18n/locales/ko.ts b/studio/frontend/src/i18n/locales/ko.ts
index cb3056e4428..e43a8d27c5c 100644
--- a/studio/frontend/src/i18n/locales/ko.ts
+++ b/studio/frontend/src/i18n/locales/ko.ts
@@ -3614,6 +3614,9 @@ export const ko = {
evalSteps: "평가 스텝",
evalStepsTooltip:
"평가 사이의 간격을 전체 학습 스텝 수의 비율로 나타냅니다(0-1). 0으로 설정하면 평가가 비활성화됩니다. 예: 0.01 = 스텝의 1%마다 평가.",
+ earlyStoppingPatience: "조기 종료 인내 횟수",
+ earlyStoppingPatienceTooltip:
+ "평가 손실이 낮아지지 않는 평가가 이 횟수만큼 연속되면 학습을 중단하고 가장 좋았던 평가 시점의 가중치를 유지합니다. 평가가 필요합니다 (평가 스텝이 0보다 커야 함). 0이면 비활성화됩니다.",
seed: "시드",
seedTooltip: "재현성을 위한 랜덤 시드입니다.",
offloadLayers: "레이어 오프로드",
diff --git a/studio/frontend/src/i18n/locales/pt-br.ts b/studio/frontend/src/i18n/locales/pt-br.ts
index 65aaf6677de..a79759fc4f1 100644
--- a/studio/frontend/src/i18n/locales/pt-br.ts
+++ b/studio/frontend/src/i18n/locales/pt-br.ts
@@ -3648,6 +3648,9 @@ export const ptBR = {
evalSteps: "Passos de Validação",
evalStepsTooltip:
"Fração dos passos totais de treino entre as validações (0-1). Defina como 0 para desativar. Ex: 0.01 = valida a cada 1% dos passos.",
+ earlyStoppingPatience: "Paciência de parada antecipada",
+ earlyStoppingPatienceTooltip:
+ "Interrompe o treinamento após este número de validações seguidas sem uma perda de validação menor e mantém os pesos da melhor validação. Requer validação (Passos de Validação acima de 0). 0 para desativar.",
seed: "Seed",
seedTooltip: "Semente aleatória para reprodutibilidade.",
offloadLayers: "Descarregar camadas",
diff --git a/studio/frontend/src/i18n/locales/ru.ts b/studio/frontend/src/i18n/locales/ru.ts
index 807de97c1f1..d75cd61dfae 100644
--- a/studio/frontend/src/i18n/locales/ru.ts
+++ b/studio/frontend/src/i18n/locales/ru.ts
@@ -3647,6 +3647,9 @@ export const ru = {
evalSteps: "Шаги оценки",
evalStepsTooltip:
"Доля от общего числа шагов обучения между оценками (0-1). Задайте 0, чтобы отключить оценку. Например, 0.01 = оценка каждый 1% шагов.",
+ earlyStoppingPatience: "Терпение ранней остановки",
+ earlyStoppingPatienceTooltip:
+ "Останавливает обучение после указанного числа оценок подряд без снижения eval loss и сохраняет веса лучшей оценки. Требуется оценка (шаги оценки больше 0). 0 отключает.",
seed: "Seed",
seedTooltip: "Случайный seed для воспроизводимости.",
offloadLayers: "Выгрузка слоёв",
diff --git a/studio/frontend/src/i18n/locales/sv.ts b/studio/frontend/src/i18n/locales/sv.ts
index 0454cc2950e..e95283cb12a 100644
--- a/studio/frontend/src/i18n/locales/sv.ts
+++ b/studio/frontend/src/i18n/locales/sv.ts
@@ -3851,6 +3851,9 @@ export const sv = {
evalSteps: "Utvärderingssteg",
evalStepsTooltip:
"Andel av totala träningssteg mellan utvärderingar (0–1). Ange 0 för att inaktivera utvärdering. Exempel: 0,01 = utvärdera var 1 % av stegen.",
+ earlyStoppingPatience: "Tålamod för early stopping",
+ earlyStoppingPatienceTooltip:
+ "Stoppar träningen efter så här många utvärderingar i rad utan lägre utvärderingsförlust och behåller vikterna från den bästa utvärderingen. Kräver utvärdering (utvärderingssteg över 0). 0 för att stänga av.",
seed: "Slumptalets startvärde",
seedTooltip: "Slumptalets startvärde för reproducerbarhet.",
offloadLayers: "Avlasta lager",
diff --git a/studio/frontend/src/i18n/locales/zh-CN.ts b/studio/frontend/src/i18n/locales/zh-CN.ts
index 6731d82bae6..ce97033c712 100644
--- a/studio/frontend/src/i18n/locales/zh-CN.ts
+++ b/studio/frontend/src/i18n/locales/zh-CN.ts
@@ -3540,6 +3540,9 @@ export const zhCN = {
evalSteps: "评估步数",
evalStepsTooltip:
"评估之间间隔占总训练步数的比例(0-1)。设为 0 则禁用评估。例如 0.01 = 每 1% 步评估一次。",
+ earlyStoppingPatience: "早停耐心值",
+ earlyStoppingPatienceTooltip:
+ "连续这么多次评估的评估损失都没有降低时停止训练,并保留最佳评估时的权重。需要开启评估(评估步数大于 0)。设为 0 则禁用。",
seed: "随机种子",
seedTooltip: "用于复现的随机种子。",
offloadLayers: "卸载层",
diff --git a/studio/frontend/tests/training-config-roundtrip.test.ts b/studio/frontend/tests/training-config-roundtrip.test.ts
index cff83c84d89..1c40356c162 100644
--- a/studio/frontend/tests/training-config-roundtrip.test.ts
+++ b/studio/frontend/tests/training-config-roundtrip.test.ts
@@ -252,3 +252,18 @@ test("a file with no embedding learning rate leaves the current one alone", () =
importConfig("training:\n max_seq_length: 4096\n");
assert.equal(useTrainingConfigStore.getState().embeddingLearningRate, 4e-5);
});
+
+test("saving and reloading a config keeps the early stopping patience", () => {
+ seedTunedModelDefaults();
+ useTrainingConfigStore.setState({ evalSteps: 0.1, earlyStoppingPatience: 4 });
+
+ const saved = serializeConfigToYaml(useTrainingConfigStore.getState(), false);
+
+ useTrainingConfigStore.setState({ earlyStoppingPatience: 0 });
+ importConfig(saved);
+ assert.equal(useTrainingConfigStore.getState().earlyStoppingPatience, 4);
+
+ // A file from before the setting existed leaves the current value alone.
+ importConfig("training:\n eval_steps: 0.1\n");
+ assert.equal(useTrainingConfigStore.getState().earlyStoppingPatience, 4);
+});
diff --git a/studio/frontend/tests/training-duplicate-run.test.ts b/studio/frontend/tests/training-duplicate-run.test.ts
index 12ef1547797..445dc0d707e 100644
--- a/studio/frontend/tests/training-duplicate-run.test.ts
+++ b/studio/frontend/tests/training-duplicate-run.test.ts
@@ -215,3 +215,27 @@ test("late model details preserve settings captured by a new CPT transition", as
assert.deepEqual(store.getState().targetModules, ["v_proj"]);
assert.equal(store.getState().trainOnCompletions, true);
});
+
+test("duplicate keeps a run's early stopping patience", async () => {
+ setAuthFetchHandler(() => modelResponse());
+ store.getState().restoreRunConfig({
+ model_name: "org/model",
+ hf_dataset: "org/data",
+ eval_steps: 0.1,
+ early_stopping_patience: 3,
+ });
+ await settle();
+ assert.equal(store.getState().earlyStoppingPatience, 3);
+ assert.equal(
+ buildTrainingStartPayload(store.getState(), null).early_stopping_patience,
+ 3,
+ );
+
+ store.getState().restoreRunConfig({
+ model_name: "org/model",
+ hf_dataset: "org/data",
+ eval_steps: 0.1,
+ });
+ await settle();
+ assert.equal(store.getState().earlyStoppingPatience, 0);
+});
diff --git a/studio/frontend/tests/training-start-payload-early-stopping.test.ts b/studio/frontend/tests/training-start-payload-early-stopping.test.ts
new file mode 100644
index 00000000000..3113696c127
--- /dev/null
+++ b/studio/frontend/tests/training-start-payload-early-stopping.test.ts
@@ -0,0 +1,74 @@
+// 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 assert from "node:assert/strict";
+import test from "node:test";
+
+import { registerBundlerResolver } from "./helpers/kit.ts";
+
+import type { TrainingConfigState } from "../src/features/training/types/config.ts";
+
+registerBundlerResolver();
+const { buildTrainingStartPayload } =
+ await import("../src/features/training/api/mappers.ts");
+const { initialTrainingConfigState } =
+ await import("../src/features/training/stores/training-config-policy.ts");
+
+function payloadFor(patch: Partial<TrainingConfigState>) {
+ const config: TrainingConfigState = {
+ ...initialTrainingConfigState,
+ modelType: "text",
+ selectedModel: "unsloth/gemma-3-270m-it",
+ datasetSource: "huggingface",
+ dataset: "unsloth/test",
+ ...patch,
+ };
+ return buildTrainingStartPayload(config, null);
+}
+
+test("early stopping is off by default", () => {
+ assert.equal(initialTrainingConfigState.earlyStoppingPatience, 0);
+ assert.equal(payloadFor({ evalSteps: 0.1 }).early_stopping_patience, 0);
+});
+
+test("patience is sent only while evaluation is on", () => {
+ assert.equal(
+ payloadFor({ evalSteps: 0.1, earlyStoppingPatience: 3 })
+ .early_stopping_patience,
+ 3,
+ );
+ assert.equal(
+ payloadFor({ evalSteps: 0, earlyStoppingPatience: 3 })
+ .early_stopping_patience,
+ 0,
+ );
+});
+
+test("a fractional, negative or huge field becomes a whole number the backend accepts", () => {
+ const sent = (value: number) =>
+ payloadFor({ evalSteps: 0.1, earlyStoppingPatience: value })
+ .early_stopping_patience;
+ assert.equal(sent(2.7), 2);
+ assert.equal(sent(-4), 0);
+ assert.equal(sent(Number.NaN), 0);
+ assert.equal(sent(50000), 1000);
+});
+
+test("decision and embedding models never send it", () => {
+ assert.equal(
+ payloadFor({
+ modelType: "decision",
+ evalSteps: 0.1,
+ earlyStoppingPatience: 3,
+ }).early_stopping_patience,
+ 0,
+ );
+ assert.equal(
+ payloadFor({
+ modelType: "embeddings",
+ evalSteps: 0.1,
+ earlyStoppingPatience: 3,
+ }).early_stopping_patience,
+ 0,
+ );
+});