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.

Preserve padding masks in distillation backbone forwards (#15068)

cherry77-cloud98c1fdc8640d
diff --git a/tests/test_distillation_padding_mask.py b/tests/test_distillation_padding_mask.py
new file mode 100644
index 00000000000..e0dc002d198
--- /dev/null
+++ b/tests/test_distillation_padding_mask.py
@@ -0,0 +1,99 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved.
+"""Distillation's direct backbone forward must keep the left-padding mask on the training student."""
+
+from __future__ import annotations
+
+import ast
+import functools
+import inspect
+from pathlib import Path
+
+import pytest
+
+RL_PY = Path(__file__).resolve().parents[1] / "unsloth" / "models" / "rl.py"
+
+
+def _wrap():
+ tree = ast.parse(RL_PY.read_text(encoding = "utf-8"))
+ node = next(
+ n
+ for n in tree.body
+ if isinstance(n, ast.FunctionDef) and n.name == "_wrap_distillation_padding_mask"
+ )
+ namespace = {"functools": functools}
+ exec(compile(ast.Module(body = [node], type_ignores = []), str(RL_PY), "exec"), namespace)
+ return namespace["_wrap_distillation_padding_mask"]
+
+
+class _Module:
+ def __init__(
+ self,
+ *children,
+ base = False,
+ ):
+ self.children = children
+ if base:
+ self.embed_tokens = object()
+
+ def modules(self):
+ yield self
+ for child in self.children:
+ yield from child.modules()
+
+
+def test_flag_set_for_the_call_then_restored():
+ fresh, preset = _Module(base = True), _Module(base = True)
+ preset._unsloth_keep_padding_mask = False
+ wrapper = _Module(_Module(fresh), preset)
+ seen = {}
+
+ class _Trainer:
+ def _get_last_hidden_state(
+ self, unwrapped_model, input_ids, attention_mask, logits_to_keep
+ ):
+ seen["fresh"] = fresh._unsloth_keep_padding_mask
+ seen["preset"] = preset._unsloth_keep_padding_mask
+ seen["wrapper"] = hasattr(wrapper, "_unsloth_keep_padding_mask")
+ return "hidden"
+
+ _wrap()(_Trainer)
+ assert _Trainer()._get_last_hidden_state(wrapper, 1, 2, 3) == "hidden"
+ assert seen == {"fresh": True, "preset": True, "wrapper": False}
+ assert not hasattr(fresh, "_unsloth_keep_padding_mask")
+ assert preset._unsloth_keep_padding_mask is False
+
+
+def test_flag_restored_on_error_and_wrapped_once():
+ base = _Module(base = True)
+
+ class _Trainer:
+ def _get_last_hidden_state(self, unwrapped_model, *args):
+ assert base._unsloth_keep_padding_mask is True
+ raise RuntimeError("oom")
+
+ wrap = _wrap()
+ wrap(_Trainer)
+ first = _Trainer._get_last_hidden_state
+ wrap(_Trainer)
+ assert _Trainer._get_last_hidden_state is first
+ with pytest.raises(RuntimeError):
+ _Trainer()._get_last_hidden_state(_Module(base))
+ assert not hasattr(base, "_unsloth_keep_padding_mask")
+
+
+def test_trainer_without_the_helper_is_left_alone():
+ class _Trainer:
+ pass
+
+ _wrap()(_Trainer)
+ assert not hasattr(_Trainer, "_get_last_hidden_state")
+
+
+def test_trl_helper_takes_the_model_first():
+ distillation = pytest.importorskip("trl.trainer.distillation_trainer")
+ helper = getattr(distillation.DistillationTrainer, "_get_last_hidden_state", None)
+ if helper is None:
+ pytest.skip("TRL DistillationTrainer without _get_last_hidden_state")
+ params = list(inspect.signature(helper).parameters)
+ assert params[:2] == ["self", "unwrapped_model"]
diff --git a/unsloth/models/rl.py b/unsloth/models/rl.py
index 364749fb46e..cff4f03fc33 100644
--- a/unsloth/models/rl.py
+++ b/unsloth/models/rl.py
@@ -879,6 +879,35 @@ def _wrap_ppo_train(trainer_cls):
trainer_cls.train = wrapped
+def _wrap_distillation_padding_mask(trainer_cls):
+ original = getattr(trainer_cls, "_get_last_hidden_state", None)
+ if original is None or getattr(original, "_unsloth_padding_mask_wrapped", False):
+ return
+
+ @functools.wraps(original)
+ def wrapped(self, unwrapped_model, *args, **kwargs):
+ # Distillation calls the backbone directly, bypassing CausalLM's _has_no_labels update.
+ missing = object()
+ states = [
+ (module, getattr(module, "_unsloth_keep_padding_mask", missing))
+ for module in unwrapped_model.modules()
+ if hasattr(module, "embed_tokens")
+ ]
+ for module, _ in states:
+ module._unsloth_keep_padding_mask = True
+ try:
+ return original(self, unwrapped_model, *args, **kwargs)
+ finally:
+ for module, previous in states:
+ if previous is missing:
+ del module._unsloth_keep_padding_mask
+ else:
+ module._unsloth_keep_padding_mask = previous
+
+ wrapped._unsloth_padding_mask_wrapped = True
+ trainer_cls._get_last_hidden_state = wrapped
+
+
def _park_optimizer_enabled(trainer):
if not torch.cuda.is_available():
return False
@@ -4055,6 +4084,8 @@ def _patch_trl_rl_trainers_impl(trainer_file = "grpo_trainer"):
_wrap_ppo_train(getattr(created_module, f"Unsloth{RLTrainer_name}"))
except Exception as e:
logger.info(f"Unsloth: Could not wrap PPO rollouts for {RLTrainer_name}: {e}")
+ if trainer_file in ("distillation_trainer", "server_distillation_trainer"):
+ _wrap_distillation_padding_mask(getattr(created_module, f"Unsloth{RLTrainer_name}"))
if trainer_file == "gkd_trainer" and "_unsloth_trl_compute_loss" in RLTrainer_source:
try:
_wrap_grpo_hidden_states_fallback(