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
RMSNorm: keep the final norm's own dX buffer when hidden states are returned to the caller (#14139)
Daniel Han7462b48cd153
diff --git a/tests/test_norm_backward_grad_alias.py b/tests/test_norm_backward_grad_alias.pyindex a209938840c..bb930800e0d 100644--- a/tests/test_norm_backward_grad_alias.py+++ b/tests/test_norm_backward_grad_alias.py@@ -168,15 +168,50 @@ def test_final_norm_reuses_grad_only_under_the_causal_lm_head(monkeypatch):calls.clear()backbone(input_ids = ids, use_cache = False)assert calls and not calls[-1]- # GRPO / DPO style: hidden states come back as logits and feed a chunked lm_head loss.+ # GRPO / DPO style: hidden states come back as logits, so the caller owns their grad.calls.clear()monkeypatch.setenv("UNSLOTH_RETURN_HIDDEN_STATES", "1")embeds = backbone.embed_tokens(ids).detach().requires_grad_()hidden = model(inputs_embeds = embeds, use_cache = False).logits- assert calls and calls[-1], "GRPO-style hidden states should let the final norm reuse its grad"+ assert (+ calls and not calls[-1]+ ), "hidden states returned as logits need the final norm's own buffer"assert hidden.shape[-1] == model.config.hidden_sizelogits = hidden.float() @ model.lm_head.weight.float().t()(grad,) = torch.autograd.grad(logits.logsumexp(-1).mean(), embeds)assert torch.isfinite(grad).all()monkeypatch.delenv("UNSLOTH_RETURN_HIDDEN_STATES")assert not getattr(backbone, "_unsloth_head_reads_final_norm", False)++[email protected](not has_real_cuda(), reason = "CUDA Triton kernels required")+def test_returned_hidden_states_leave_caller_and_shared_grads_alone(monkeypatch):+ # Under UNSLOTH_RETURN_HIDDEN_STATES the final norm's output reaches the caller as .logits; a+ # caller grad_outputs or a second branch reading the same grad (h + x) must stay intact.+ from unsloth import FastLanguageModel++ model, _ = FastLanguageModel.from_pretrained(+ "trl-internal-testing/tiny-Qwen3ForCausalLM",+ max_seq_length = 64,+ load_in_4bit = False,+ dtype = torch.bfloat16,+ )+ model.train()+ torch.manual_seed(19)+ ids = torch.randint(10, model.config.vocab_size, (2, 16), device = "cuda")+ x0 = model.model.embed_tokens(ids).detach()+ incoming = torch.randn_like(x0)+ monkeypatch.setenv("UNSLOTH_RETURN_HIDDEN_STATES", "1")+ grads = []+ for output_hidden_states in (False, True):+ x = x0.clone().requires_grad_()+ h = model(+ inputs_embeds = x, use_cache = False, output_hidden_states = output_hidden_states+ ).logits+ go = incoming.clone()+ (dx,) = torch.autograd.grad(h + x, x, go)+ assert torch.equal(go, incoming), "caller's grad_outputs were overwritten"+ grads.append(dx)+ # output_hidden_states = True always kept the norm's own buffer: the reference.+ assert torch.equal(grads[0], grads[1])diff --git a/unsloth/models/llama.py b/unsloth/models/llama.pyindex 49ce312f5b5..878a78e268d 100644--- a/unsloth/models/llama.py+++ b/unsloth/models/llama.py@@ -1775,12 +1775,15 @@ def apply_logit_transforms(logits, logit_softcapping, logit_scaling):def _run_backbone(self, **kwargs):- # The CausalLM forward feeds the final norm's output to lm_head, the fused CE loss, or (with- # UNSLOTH_RETURN_HIDDEN_STATES, set only by Unsloth's GRPO / DPO / GKD trainers) their chunked- # lm_head loss; all return a fresh grad, so the norm may write dX over it. Returned- # hidden_states would let a caller own that grad, so they keep the norm's own buffer.+ # The CausalLM forward feeds the final norm's output to lm_head or the fused CE loss, which+ # return a fresh grad, so the norm may write dX over it. Hidden states handed back to the+ # caller (output_hidden_states, or as .logits under UNSLOTH_RETURN_HIDDEN_STATES) let the+ # caller own or share that grad, so they keep the norm's own buffer.model = self.model- model._unsloth_head_reads_final_norm = not kwargs.get("output_hidden_states")+ model._unsloth_head_reads_final_norm = (+ not kwargs.get("output_hidden_states")+ and os.environ.get("UNSLOTH_RETURN_HIDDEN_STATES", "0") != "1"+ )try:return model(**kwargs)finally: