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.

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.py
new file mode 100644
index 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.py
index 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 malicious
rng_state.pth on resume). Hardens only the rng torch.load, via a thread-local
diff --git a/unsloth/models/vision.py b/unsloth/models/vision.py
index 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.py
index 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_prefix
result = 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)