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
Fix Voxtral processor saving and Voxtral Realtime training (#12647)
Yashwanth Nomula453499b6cd60
diff --git a/tests/test_voxtral_training_fixes.py b/tests/test_voxtral_training_fixes.pynew file mode 100644index 00000000000..2c3f653f262--- /dev/null+++ b/tests/test_voxtral_training_fixes.py@@ -0,0 +1,153 @@+# SPDX-License-Identifier: AGPL-3.0-only+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved.++"""Voxtral fine-tuning (#3013): saving its MistralCommonBackend processor, and training Voxtral+Realtime with input gradients on."""++import pytest++transformers = pytest.importorskip("transformers")++import unsloth # noqa: E402,F401 applies patch_enable_input_require_grads+import torch # noqa: E402++from unsloth.import_fixes import fix_transformers_voxtral_realtime_inplace_audio_add # noqa: E402+from unsloth.save import patch_saving_functions, unsloth_tokenizer_save_pretrained # noqa: E402++TINY_VOXTRAL = "trl-internal-testing/tiny-VoxtralForConditionalGeneration"+++class _StrictSave:+ """MistralCommonBackend.save_pretrained's contract: any extra kwarg raises, even None."""++ def __init__(self):+ self.calls = []++ def original_save_pretrained(+ self,+ save_directory,+ push_to_hub = False,+ token = None,+ **kwargs,+ ):+ if kwargs:+ raise ValueError(f"Kwargs {list(kwargs)} are not supported")+ self.calls.append(save_directory)+ return (save_directory,)+++def test_unset_legacy_format_and_prefix_are_not_forwarded(tmp_path):+ tok = _StrictSave()+ unsloth_tokenizer_save_pretrained(tok, str(tmp_path))+ unsloth_tokenizer_save_pretrained(tok, str(tmp_path), legacy_format = None, filename_prefix = None)+ assert tok.calls == [str(tmp_path)] * 2+++def test_set_legacy_format_and_prefix_still_reach_the_tokenizer(tmp_path):+ seen = {}++ class _Recording:+ def original_save_pretrained(self, save_directory, **kwargs):+ seen.update(kwargs)++ unsloth_tokenizer_save_pretrained(+ _Recording(), str(tmp_path), legacy_format = False, filename_prefix = "p"+ )+ assert seen["legacy_format"] is False and seen["filename_prefix"] == "p"+++def test_save_only_options_stay_out_of_push_to_hub(tmp_path):+ pushed = {}++ class _Pushing:+ def original_save_pretrained(self, save_directory, **kwargs):+ pass++ def push_to_hub(self, repo_id, **kwargs):+ pushed.update(kwargs, repo_id = repo_id)++ unsloth_tokenizer_save_pretrained(+ _Pushing(), str(tmp_path), legacy_format = False, push_to_hub = True, token = "t"+ )+ assert pushed == {"repo_id": str(tmp_path), "token": "t"}+++def test_patched_voxtral_processor_saves(tmp_path):+ pytest.importorskip("mistral_common")+ try:+ processor = transformers.AutoProcessor.from_pretrained(TINY_VOXTRAL)+ except Exception as e:+ pytest.skip(f"cannot load {TINY_VOXTRAL}: {e}")+ if not isinstance(processor.tokenizer, transformers.PreTrainedTokenizerBase):+ pytest.skip("transformers 4.x MistralCommonTokenizer; FastModel cannot load Voxtral there")+ patch_saving_functions(processor)+ patch_saving_functions(processor.tokenizer)+ processor.save_pretrained(str(tmp_path / "processor"))+ processor.tokenizer.save_pretrained(+ save_directory = str(tmp_path / "tokenizer"), legacy_format = None, filename_prefix = None+ )+ assert (tmp_path / "processor" / "tekken.json").is_file()+ assert (tmp_path / "tokenizer" / "tekken.json").is_file()+++def _realtime_model():+ cls = getattr(transformers, "VoxtralRealtimeForConditionalGeneration", None)+ if cls is None:+ pytest.skip("this transformers has no VoxtralRealtimeForConditionalGeneration")+ config = transformers.VoxtralRealtimeConfig(+ audio_config = dict(+ hidden_size = 32,+ intermediate_size = 64,+ num_hidden_layers = 1,+ num_attention_heads = 2,+ head_dim = 16,+ num_mel_bins = 16,+ ),+ text_config = dict(+ hidden_size = 32,+ intermediate_size = 64,+ num_hidden_layers = 1,+ num_attention_heads = 2,+ num_key_value_heads = 2,+ head_dim = 16,+ vocab_size = 64,+ ),+ )+ torch.manual_seed(0)+ model = cls(config).float().train()+ model.requires_grad_(False)+ trainable = [p for n, p in model.named_parameters() if "q_proj" in n and "audio" not in n][0]+ trainable.requires_grad_(True)+ return model, trainable+++def _step(model, trainable):+ torch.manual_seed(0)+ features = torch.randn(1, 16, 64) # 64 frames -> 8 audio tokens+ ids = torch.randint(0, 64, (1, 8))+ trainable.grad = None+ loss = model(input_ids = ids, input_features = features, labels = ids).loss+ loss.backward()+ return loss.detach(), trainable.grad.clone()+++def test_voxtral_realtime_trains_with_input_require_grads():+ model, trainable = _realtime_model()+ ref_loss, ref_grad = _step(model, trainable) # no input-grad hook: upstream's own path++ fix_transformers_voxtral_realtime_inplace_audio_add()+ model.enable_input_require_grads()+ loss, grad = _step(model, trainable)+ assert torch.isfinite(loss)+ torch.testing.assert_close(loss, ref_loss)+ torch.testing.assert_close(grad, ref_grad)+++def test_voxtral_realtime_fix_is_idempotent():+ _realtime_model()+ fix_transformers_voxtral_realtime_inplace_audio_add()+ cls = transformers.models.voxtral_realtime.modeling_voxtral_realtime.VoxtralRealtimeModel+ patched = cls.forward+ fix_transformers_voxtral_realtime_inplace_audio_add()+ assert cls.forward is patched+ assert "inputs_embeds +=" in __import__("inspect").getsource(patched.__wrapped__)diff --git a/unsloth/import_fixes.py b/unsloth/import_fixes.pyindex fa4e7ee91b4..f4c5354d77e 100644--- a/unsloth/import_fixes.py+++ b/unsloth/import_fixes.py@@ -5082,6 +5082,52 @@ def patch_enable_input_require_grads():logger.info("Unsloth: Patched enable_input_require_grads for vision model compatibility")+_VOXTRAL_REALTIME_MODULE = "transformers.models.voxtral_realtime.modeling_voxtral_realtime"+++def fix_transformers_voxtral_realtime_inplace_audio_add():+ """VoxtralRealtimeModel.forward does `inputs_embeds += audio_embeds`; with input gradients on that is a+ leaf requiring grad, so step 1 raises (#3013, transformers <= 5.19). Hand it a non-leaf copy. Lazy: only+ once transformers imported the module."""+ cls = getattr(sys.modules.get(_VOXTRAL_REALTIME_MODULE), "VoxtralRealtimeModel", None)+ if cls is None or getattr(cls.forward, "_unsloth_inplace_audio_fix", False):+ return+ try:+ if "inputs_embeds +=" not in inspect.getsource(cls.forward):+ return+ except Exception:+ return+ import torch++ original = cls.forward++ @functools.wraps(original)+ def forward(+ self,+ input_ids = None,+ *args,+ **kwargs,+ ):+ if args or not torch.is_grad_enabled():+ return original(self, input_ids, *args, **kwargs)+ inputs_embeds = kwargs.get("inputs_embeds")+ # input_ids is read only for this lookup, so passing the embeddings instead is equivalent.+ if inputs_embeds is None and input_ids is not None:+ inputs_embeds, input_ids = self.get_input_embeddings()(input_ids), None+ if (+ isinstance(inputs_embeds, torch.Tensor)+ and inputs_embeds.is_leaf+ and inputs_embeds.requires_grad+ ):+ inputs_embeds = inputs_embeds.clone()+ if inputs_embeds is not None:+ kwargs["inputs_embeds"] = inputs_embeds+ return original(self, input_ids, **kwargs)++ forward._unsloth_inplace_audio_fix = True+ cls.forward = forward++def patch_unsafe_trainer_rng_load():"""Harden Trainer._load_rng_state against CVE-2026-1839 (RCE from a maliciousrng_state.pth on resume). Hardens only the rng torch.load, via a thread-localdiff --git a/unsloth/models/vision.py b/unsloth/models/vision.pyindex 524c29f690e..f669b1703f4 100644--- a/unsloth/models/vision.py+++ b/unsloth/models/vision.py@@ -4897,6 +4897,9 @@ class FastBaseModel:float32_mixed_precision = None,):reject_alora(model)+ from ..import_fixes import fix_transformers_voxtral_realtime_inplace_audio_add++ fix_transformers_voxtral_realtime_inplace_audio_add()full_finetuning = os.environ.get("UNSLOTH_ENABLE_FULL_FINETUNING", "0") == "1"if type(float32_mixed_precision) is bool:diff --git a/unsloth/save.py b/unsloth/save.pyindex 4c837b9cf8a..3a4daf34e87 100644--- a/unsloth/save.py+++ b/unsloth/save.py@@ -7436,12 +7436,16 @@ def unsloth_tokenizer_save_pretrained(push_to_hub = False,**kwargs,):+ # Forward only what the caller set: MistralCommonBackend (Voxtral, tekken checkpoints) rejects these even as None.+ save_kwargs = dict(kwargs)+ if legacy_format is not None:+ save_kwargs["legacy_format"] = legacy_format+ if filename_prefix is not None:+ save_kwargs["filename_prefix"] = filename_prefixresult = self.original_save_pretrained(save_directory,- legacy_format = legacy_format,- filename_prefix = filename_prefix,push_to_hub = False,- **kwargs,+ **save_kwargs,)_preserve_sentencepiece_tokenizer_assets(self,@@ -7573,14 +7577,13 @@ def patch_saving_functions(model, vision = False):return original(*bound.args, **bound.kwargs)return original(*args, **kwargs)- if (- isinstance(model, PreTrainedTokenizerBase)- and model.save_pretrained.__name__ != "unsloth_tokenizer_save_pretrained"- ):- model.original_save_pretrained = model.save_pretrained- model.save_pretrained = _bind_saving_method(- unsloth_tokenizer_save_pretrained, model, "save_pretrained"- )+ if isinstance(model, PreTrainedTokenizerBase):+ if model.save_pretrained.__name__ != "unsloth_tokenizer_save_pretrained":+ model.original_save_pretrained = model.save_pretrained+ model.save_pretrained = _bind_saving_method(+ unsloth_tokenizer_save_pretrained, model, "save_pretrained"+ )+ # Never into a tokenizer's own .tokenizer: MistralCommonBackend's is a raw mistral_common object.elif getattr(model, "tokenizer", None) is not None:patch_saving_functions(model.tokenizer)