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.

Keep a user-set UNSLOTH_RETURN_LOGITS=1 across trainer.train() (#13311)

Daniel Han8ad2b6a19203
diff --git a/tests/test_return_logits_survives_for_training.py b/tests/test_return_logits_survives_for_training.py
new file mode 100644
index 00000000000..04ad27d4143
--- /dev/null
+++ b/tests/test_return_logits_survives_for_training.py
@@ -0,0 +1,217 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved.
+"""A user's UNSLOTH_RETURN_LOGITS=1 must survive trainer.train() (#3071): for_training() may only undo
+for_inference()'s forced "1". Methods are lifted out with ``ast`` so this runs without ``import unsloth``.
+"""
+
+from __future__ import annotations
+
+import ast
+import builtins
+import inspect
+import os
+import sys
+import textwrap
+import types
+from pathlib import Path
+
+import pytest
+
+MODELS = Path(__file__).resolve().parents[1] / "unsloth" / "models"
+FLAG = "UNSLOTH_RETURN_LOGITS"
+MARK = "_UNSLOTH_RETURN_LOGITS_BEFORE_INFERENCE"
+
+
+class _Namespace(dict):
+ def __missing__(self, name):
+ return getattr(builtins, name, None)
+
+
+def _fast_base_model():
+ tree = ast.parse((MODELS / "vision.py").read_text(encoding = "utf-8"))
+ cls = next(n for n in tree.body if isinstance(n, ast.ClassDef) and n.name == "FastBaseModel")
+ wanted = [
+ n for n in tree.body if isinstance(n, ast.FunctionDef) and n.name == "_embeddings_or_none"
+ ]
+ methods = {}
+ for name in ("for_inference", "for_training"):
+ fn = next(n for n in cls.body if isinstance(n, ast.FunctionDef) and n.name == name)
+ fn.decorator_list = []
+ wanted.append(fn)
+ utils = ast.parse((MODELS / "_utils.py").read_text(encoding = "utf-8"))
+ for node in utils.body:
+ if isinstance(node, ast.FunctionDef) and node.name in (
+ "resolve_training_gradient_checkpointing",
+ "_gradient_checkpointing_layer_class",
+ "_forward_reads_checkpoint_function",
+ "_calls_checkpoint_function",
+ "_is_unarmed",
+ "arm_gradient_checkpointing",
+ "set_module_gradient_checkpointing",
+ ):
+ node.decorator_list = []
+ wanted.insert(0, node)
+ namespace = _Namespace(os = os, inspect = inspect)
+ module = ast.fix_missing_locations(ast.Module(body = wanted, type_ignores = []))
+ exec(compile(module, str(MODELS / "vision.py"), "exec"), namespace)
+ for name in ("for_inference", "for_training"):
+ methods[name] = namespace[name]
+ return types.SimpleNamespace(**methods)
+
+
+class _Model:
+ training = True
+ gradient_checkpointing = False
+
+ def parameters(self):
+ return ()
+
+ def modules(self):
+ return ()
+
+ def train(self):
+ self.training = True
+
+ def eval(self):
+ self.training = False
+
+
+def fbm(monkeypatch):
+ zoo = types.ModuleType("unsloth_zoo")
+ utils = types.ModuleType("unsloth_zoo.training_utils")
+ utils.restore_use_cache = lambda model: None
+ utils.disable_use_cache = lambda model: None
+ monkeypatch.setitem(sys.modules, "unsloth_zoo", zoo)
+ monkeypatch.setitem(sys.modules, "unsloth_zoo.training_utils", utils)
+ monkeypatch.delenv(FLAG, raising = False)
+ monkeypatch.delenv(MARK, raising = False)
+ return _fast_base_model()
+
+
+def test_for_training_keeps_a_user_set_flag(fbm, monkeypatch):
+ monkeypatch.setenv(FLAG, "1")
+ fbm.for_training(_Model())
+ assert os.environ[FLAG] == "1"
+ # The trainer's own cycle: for_training in __init__, for_inference, for_training in train().
+ model = _Model()
+ fbm.for_training(model)
+ fbm.for_inference(model)
+ fbm.for_training(model)
+ assert os.environ[FLAG] == "1"
+ assert MARK not in os.environ
+
+
[email protected]("before", [None, "0"])
+def test_for_training_undoes_the_flag_for_inference_forced(fbm, monkeypatch, before):
+ # Default training must go back to the fused CE path after generation / GRPO rollouts.
+ if before is not None:
+ monkeypatch.setenv(FLAG, before)
+ model = _Model()
+ fbm.for_inference(model)
+ assert os.environ[FLAG] == "1"
+ fbm.for_inference(model) # repeated calls (every GRPO step) keep the first saved value
+ fbm.for_training(model)
+ assert os.environ[FLAG] == "0"
+ assert MARK not in os.environ
+ fbm.for_training(model)
+ assert os.environ[FLAG] == "0"
+
+
+def test_for_training_still_defaults_an_unset_flag_to_zero(fbm):
+ fbm.for_training(_Model())
+ assert os.environ[FLAG] == "0"
+
+
+def _trailing_for_inference_block():
+ tree = ast.parse((MODELS / "rl.py").read_text(encoding = "utf-8"))
+ template = next(
+ n.value.value
+ for n in tree.body
+ if isinstance(n, ast.Assign)
+ and any(getattr(t, "id", None) == "RLTrainer_replacement" for t in n.targets)
+ )
+ lines = template.splitlines()
+ start = next(i for i, line in enumerate(lines) if 'hasattr(model, "for_inference")' in line)
+ block = [lines[start]]
+ indent = len(lines[start]) - len(lines[start].lstrip())
+ for line in lines[start + 1 :]:
+ if line.strip() and len(line) - len(line.lstrip()) <= indent:
+ break
+ block.append(line)
+ # The template is filled with str.format: a literal brace in the block breaks every trainer.
+ return textwrap.dedent("\n".join(block)).format()
+
+
+def test_trainer_init_leaves_the_flag_for_train(fbm, monkeypatch):
+ model = _Model()
+ model.for_inference = lambda: fbm.for_inference(model)
+ monkeypatch.setenv(FLAG, "0")
+ exec(_trailing_for_inference_block(), {"os": os, "model": model})
+ assert model.training is False
+ assert os.environ[FLAG] == "0"
+ assert MARK not in os.environ
+ os.environ[FLAG] = "1"
+ fbm.for_training(model)
+ assert os.environ[FLAG] == "1"
+
+
+def _prepare_for_training_mode():
+ tree = ast.parse((MODELS / "rl.py").read_text(encoding = "utf-8"))
+ template = next(
+ n.value.value
+ for n in tree.body
+ if isinstance(n, ast.Assign)
+ and any(getattr(t, "id", None) == "RLTrainer_replacement" for t in n.targets)
+ )
+ lines = template.splitlines()
+ start = lines.index("def prepare_for_training_mode(f):")
+ end = lines.index(" return wrapper", start)
+ namespace = _Namespace(os = os, functools = __import__("functools"))
+ exec("\n".join(lines[start : end + 1]).format(), namespace)
+ return namespace["prepare_for_training_mode"]
+
+
+def test_flag_set_between_two_train_calls_is_kept(fbm):
+ model = _Model()
+ model.for_inference = lambda: fbm.for_inference(model)
+ model.for_training = lambda use_gradient_checkpointing = None: fbm.for_training(model)
+ seen = []
+
+ class _Trainer:
+ args = types.SimpleNamespace(gradient_checkpointing = False)
+
+ def train(self):
+ seen.append(os.environ.get(FLAG))
+
+ trainer = _Trainer()
+ trainer.model = model
+ train = _prepare_for_training_mode()(_Trainer.train)
+ model.eval()
+ train(trainer)
+ assert model.training is False
+ os.environ[FLAG] = "1"
+ train(trainer)
+ assert seen == ["0", "1"]
+
+
+def _logits_check():
+ tree = ast.parse((MODELS / "rl.py").read_text(encoding = "utf-8"))
+ return next(
+ n.value.value
+ for n in ast.walk(tree)
+ if isinstance(n, ast.Assign)
+ and any(getattr(t, "id", None) == "logits_check" for t in n.targets)
+ )
+
+
[email protected]("user_flag", [None, "1"])
+def test_compute_metrics_auto_flag_does_not_outlive_the_trainer_init(fbm, monkeypatch, user_flag):
+ # compute_metrics forces "1" while building the trainer; training (and the next trainer's
+ # padding-free gate) must see the user's value, not a leaked "1".
+ if user_flag is not None:
+ monkeypatch.setenv(FLAG, user_flag)
+ exec(_logits_check(), {"os": os, "compute_metrics": object()})
+ assert os.environ[FLAG] == "1"
+ fbm.for_training(_Model())
+ assert os.environ[FLAG] == (user_flag or "0")
diff --git a/unsloth/models/rl.py b/unsloth/models/rl.py
index 88133f5dae8..5c162c31628 100644
--- a/unsloth/models/rl.py
+++ b/unsloth/models/rl.py
@@ -496,7 +496,12 @@ def prepare_for_training_mode(f):
# Restore previous mode when possible
if hasattr(self, 'model') and hasattr(self.model, "for_inference"):
if _was_training is False:
+ # Mode only: a UNSLOTH_RETURN_LOGITS=1 set before the next train() must survive (#3071).
+ _logits_env = [(_k, os.environ.get(_k)) for _k in ("UNSLOTH_RETURN_LOGITS", "_UNSLOTH_RETURN_LOGITS_BEFORE_INFERENCE")]
self.model.for_inference()
+ for _k, _v in _logits_env:
+ if _v is None: os.environ.pop(_k, None)
+ else: os.environ[_k] = _v
elif _was_training is True and hasattr(self.model, "for_training"):
self.model.for_training(use_gradient_checkpointing=use_gc)
# Reset gradient checkpointing buffers to free memory while staying ready for next run
@@ -603,7 +608,12 @@ class Unsloth{RLTrainer_name}(_Unsloth{RLTrainer_name}):
model.for_training(use_gradient_checkpointing=_use_gc)
super().__init__({RLTrainer_call_args}{RLTrainer_kwargs})
if "model" in locals() and hasattr(model, "for_inference"):
+ # Mode switch only: a UNSLOTH_RETURN_LOGITS=1 set between here and train() must survive (#3071).
+ _unsloth_logits_env = [(_unsloth_k, os.environ.get(_unsloth_k)) for _unsloth_k in ("UNSLOTH_RETURN_LOGITS", "_UNSLOTH_RETURN_LOGITS_BEFORE_INFERENCE")]
model.for_inference()
+ for _unsloth_k, _unsloth_v in _unsloth_logits_env:
+ if _unsloth_v is None: os.environ.pop(_unsloth_k, None)
+ else: os.environ[_unsloth_k] = _unsloth_v
{RLTrainer_post}
pass
'''
@@ -2512,6 +2522,9 @@ def _patch_trl_rl_trainers_impl(trainer_file = "grpo_trainer"):
"if locals().get('compute_metrics', None) is not None: _output_logits = True\n"
"if locals().get('preprocess_logits_for_metrics', None) is not None: _output_logits = True\n"
"if _output_logits:\n"
+ # Recorded like for_inference()'s "1" so for_training() undoes it and only a user's "1" persists (#3071).
+ " _unsloth_rl = os.environ.get('UNSLOTH_RETURN_LOGITS', '0')\n"
+ " if _unsloth_rl != '1': os.environ['_UNSLOTH_RETURN_LOGITS_BEFORE_INFERENCE'] = _unsloth_rl\n"
" os.environ['UNSLOTH_RETURN_LOGITS'] = '1'\n"
)
extra_args += logits_check
diff --git a/unsloth/models/vision.py b/unsloth/models/vision.py
index bf6b2ffba58..99c1b6005b9 100644
--- a/unsloth/models/vision.py
+++ b/unsloth/models/vision.py
@@ -5053,6 +5053,10 @@ class FastBaseModel:
# Returning hidden states must be disabled for GRPO, and returning logits enabled.
os.environ["UNSLOTH_RETURN_HIDDEN_STATES"] = "0"
+ # Remember what the forced "1" replaced, for for_training() to put back (#3071).
+ _return_logits = os.environ.get("UNSLOTH_RETURN_LOGITS", "0")
+ if _return_logits != "1":
+ os.environ["_UNSLOTH_RETURN_LOGITS_BEFORE_INFERENCE"] = _return_logits
os.environ["UNSLOTH_RETURN_LOGITS"] = "1"
if torch_compiler_set_stance is not None:
torch_compiler_set_stance(stance = "default", skip_guard_eval_unsafe = False)
@@ -5111,7 +5115,11 @@ class FastBaseModel:
except ImportError:
pass
- os.environ["UNSLOTH_RETURN_LOGITS"] = "0"
+ # Undo only for_inference()'s "1": forcing "0" here wiped a user's UNSLOTH_RETURN_LOGITS=1 (#3071).
+ _return_logits = os.environ.pop("_UNSLOTH_RETURN_LOGITS_BEFORE_INFERENCE", None)
+ if _return_logits is None:
+ _return_logits = os.environ.get("UNSLOTH_RETURN_LOGITS", "0")
+ os.environ["UNSLOTH_RETURN_LOGITS"] = _return_logits
if torch_compiler_set_stance is not None:
torch_compiler_set_stance(stance = "default", skip_guard_eval_unsafe = False)
return model