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.

Studio: keep the chat template of Mac LoRAs trained on multimodal base models (#13826)

Daniel Han98aa8fb3e129
diff --git a/studio/backend/core/export/export.py b/studio/backend/core/export/export.py
index 7a4169efa72..6598241061a 100644
--- a/studio/backend/core/export/export.py
+++ b/studio/backend/core/export/export.py
@@ -32,7 +32,11 @@ from utils.hardware import clear_gpu_cache
from utils.models import is_vision_model, get_base_model_from_lora
from utils.models.model_identity import restore_hf_cache_repo_identity
-from utils.models.model_config import detect_audio_type, load_mlx_adapter_tokenizer
+from utils.models.model_config import (
+ detect_audio_type,
+ load_mlx_adapter_processor,
+ load_mlx_adapter_tokenizer,
+)
from utils.paths import (
ensure_dir,
outputs_root,
@@ -990,6 +994,8 @@ class ExportBackend:
**_device_map_kw,
**_offload_kw,
)
+ if _IS_MLX and adapter_config.exists():
+ processor = load_mlx_adapter_processor(processor, checkpoint_path)
tokenizer = processor
else:
diff --git a/studio/backend/core/inference/mlx_inference.py b/studio/backend/core/inference/mlx_inference.py
index bec90fb116f..2c60049151d 100644
--- a/studio/backend/core/inference/mlx_inference.py
+++ b/studio/backend/core/inference/mlx_inference.py
@@ -56,7 +56,11 @@ from core.inference.mcp_images import (
top_up_image_markers,
trim_image_turns,
)
-from utils.models.model_config import is_audio_input_type, load_mlx_adapter_tokenizer
+from utils.models.model_config import (
+ is_audio_input_type,
+ load_mlx_adapter_processor,
+ load_mlx_adapter_tokenizer,
+)
from utils.utils import is_metal_queue_dead
from loggers import get_logger
@@ -4839,6 +4843,8 @@ class MLXInferenceBackend:
self._reads_vision = bool(is_vision)
if use_vlm:
processor = tokenizer_or_processor
+ if is_lora:
+ processor = load_mlx_adapter_processor(processor, model_name, hf_token)
self._model = model
self._processor = processor
self._tokenizer = getattr(processor, "tokenizer", processor)
diff --git a/studio/backend/core/training/worker.py b/studio/backend/core/training/worker.py
index 9e45d19225a..8ca0fab5560 100644
--- a/studio/backend/core/training/worker.py
+++ b/studio/backend/core/training/worker.py
@@ -2186,6 +2186,28 @@ def _activate_transformers_version_or_warn(model_name: str, hf_token: str | None
)
+def _carry_mlx_chat_template_to_processor(model, tokenizer) -> bool:
+ """MLXTrainer saves the loader's processor when it has one, so a text run on a multimodal base checkpoint (Qwen3.5
+ Base) saved no template and Chat failed with "chat_template is not set". Give it the template the rows used."""
+ processor = getattr(model, "_processor", None)
+ if processor is None or processor is tokenizer:
+ return False
+ trained = tokenizer
+ if type(tokenizer).__name__ == "TokenizerWrapper":
+ trained = getattr(tokenizer, "_tokenizer", tokenizer)
+ template = getattr(trained, "chat_template", None)
+ if not template or getattr(processor, "chat_template", None):
+ return False
+ own = getattr(processor, "tokenizer", None)
+ if own is not None and own is not trained and getattr(own, "chat_template", None):
+ return False
+ processor.chat_template = template
+ if own is not None and own is not trained:
+ # Also carries get_chat_template's end-token remap.
+ processor.tokenizer = trained
+ return True
+
+
def _mlx_vlm_max_resized_size(width: int, height: int, target: int) -> tuple[int, int]:
if width <= 0 or height <= 0 or target <= 0:
return width, height
@@ -3279,6 +3301,14 @@ def _run_mlx_training(event_queue, stop_queue, config):
except ImportError:
_send("status", status_message = "Format helper unavailable, using raw dataset")
+ if not is_vlm and dataset_final_format:
+ # get_chat_template returns a new tokenizer unless it is an mlx-lm wrapper, so the rows' template stayed in
+ # the formatter; mirror the CUDA trainer and re-apply it here (no-op for models with a template).
+ from utils.datasets.chat_templates import get_training_chat_template
+ tokenizer = get_training_chat_template(tokenizer, model_name, dataset_final_format)
+ if _carry_mlx_chat_template_to_processor(model, tokenizer):
+ logger.info("Saving the training chat template with the processor")
+
if eval_enabled and eval_dataset is None:
from core.training.eval_dataset import (
MIN_TOTAL_ROWS_FOR_EVAL,
diff --git a/studio/backend/tests/test_export_absolute_paths.py b/studio/backend/tests/test_export_absolute_paths.py
index bde1c78c938..456cc0deb15 100644
--- a/studio/backend/tests/test_export_absolute_paths.py
+++ b/studio/backend/tests/test_export_absolute_paths.py
@@ -301,6 +301,7 @@ def _install_export_backend_stubs(monkeypatch):
utils_model_config = sys.modules["utils.models.model_config"]
utils_model_config.detect_audio_type = lambda *args, **kwargs: None
utils_model_config.load_mlx_adapter_tokenizer = lambda tokenizer, *args, **kwargs: tokenizer
+ utils_model_config.load_mlx_adapter_processor = lambda processor, *args, **kwargs: processor
utils_paths = sys.modules["utils.paths"]
utils_paths.ensure_dir = lambda path: Path(path).mkdir(parents = True, exist_ok = True)
diff --git a/studio/backend/tests/test_mlx_lora_adapter_tokenizer.py b/studio/backend/tests/test_mlx_lora_adapter_tokenizer.py
index beac5551b3e..49e44e848de 100644
--- a/studio/backend/tests/test_mlx_lora_adapter_tokenizer.py
+++ b/studio/backend/tests/test_mlx_lora_adapter_tokenizer.py
@@ -164,3 +164,70 @@ def test_mlx_lora_on_a_model_with_its_own_template_keeps_it(monkeypatch, adapter
assert ok, message
assert backend.current_tokenizer is own
+
+
+class TokenizerWrapper:
+ def __init__(self, tokenizer):
+ self._tokenizer = tokenizer
+
+ @property
+ def chat_template(self):
+ return self._tokenizer.chat_template
+
+
+def _base_processor(base_tokenizer):
+ base_tokenizer._unsloth_modality_model_type = "qwen3_5"
+ base_tokenizer.stopping_criteria = "mlx-vlm criteria"
+ return SimpleNamespace(tokenizer = base_tokenizer, chat_template = None)
+
+
[email protected]("wrapped", [False, True])
+def test_mlx_processor_of_a_multimodal_base_gets_the_trained_tokenizer(
+ monkeypatch, adapter_dir, base_tokenizer, wrapped
+):
+ if wrapped:
+ load = sys.modules["mlx_lm.utils"].load_tokenizer
+ monkeypatch.setattr(
+ sys.modules["mlx_lm.utils"],
+ "load_tokenizer",
+ lambda path, eos_token_ids = None: TokenizerWrapper(load(path)),
+ )
+ processor = _base_processor(base_tokenizer)
+
+ assert model_config.load_mlx_adapter_processor(processor, str(adapter_dir)) is processor
+
+ _assert_trained_tokenizer(processor.tokenizer)
+ assert processor.chat_template == CHATML
+ assert processor.tokenizer._unsloth_modality_model_type == "qwen3_5"
+ assert processor.tokenizer.stopping_criteria == "mlx-vlm criteria"
+
+
+def test_mlx_processor_with_its_own_template_is_left_alone(adapter_dir, base_tokenizer):
+ processor = _base_processor(base_tokenizer)
+ processor.chat_template = "{{ messages[0]['content'] }}"
+
+ model_config.load_mlx_adapter_processor(processor, str(adapter_dir))
+
+ assert processor.tokenizer is base_tokenizer
+
+
+def test_mlx_vision_export_saves_the_template_a_base_model_lora_was_trained_with(
+ monkeypatch, adapter_dir, base_tokenizer
+):
+ _install_export_backend_stubs(monkeypatch)
+ backend = _export_backend(monkeypatch, base_tokenizer)
+ mod = sys.modules[type(backend).__module__]
+ processor = _base_processor(base_tokenizer)
+ monkeypatch.setattr(mod, "is_vision_model", lambda *a, **k: True)
+ monkeypatch.setattr(
+ mod,
+ "FastVisionModel",
+ SimpleNamespace(from_pretrained = lambda **k: (SimpleNamespace(), processor)),
+ )
+
+ ok, message = backend.load_checkpoint(str(adapter_dir))
+ assert ok, message
+
+ assert backend.current_tokenizer is processor
+ assert processor.chat_template == CHATML
+ _assert_trained_tokenizer(processor.tokenizer)
diff --git a/studio/backend/tests/test_mlx_processor_chat_template.py b/studio/backend/tests/test_mlx_processor_chat_template.py
new file mode 100644
index 00000000000..62c753347c5
--- /dev/null
+++ b/studio/backend/tests/test_mlx_processor_chat_template.py
@@ -0,0 +1,81 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import sys
+from pathlib import Path
+from types import SimpleNamespace
+
+import pytest
+
+_TESTS_DIR = Path(__file__).resolve().parent
+if str(_TESTS_DIR) not in sys.path:
+ sys.path.insert(0, str(_TESTS_DIR))
+
+from test_mlx_training_worker_config import _load_worker_module # noqa: E402
+
+CHATML = "{% for m in messages %}<|im_start|>{{ m['role'] }}{% endfor %}"
+
+
+class TokenizerWrapper:
+ def __init__(self, inner):
+ self._tokenizer = inner
+
+
[email protected](scope = "module")
+def carry():
+ return _load_worker_module()._carry_mlx_chat_template_to_processor
+
+
+def _base_processor():
+ return SimpleNamespace(chat_template = None, tokenizer = SimpleNamespace(chat_template = None))
+
+
+def test_base_checkpoint_processor_gets_the_training_template(carry):
+ processor = _base_processor()
+ trained = SimpleNamespace(chat_template = CHATML)
+ assert carry(SimpleNamespace(_processor = processor), trained)
+ assert processor.chat_template == CHATML
+ assert processor.tokenizer is trained
+
+
+def test_mlx_lm_wrapper_is_unwrapped(carry):
+ processor = _base_processor()
+ trained = SimpleNamespace(chat_template = CHATML)
+ assert carry(SimpleNamespace(_processor = processor), TokenizerWrapper(trained))
+ assert processor.tokenizer is trained
+
+
+def test_hf_fast_tokenizer_backend_is_not_unwrapped(carry):
+ # PreTrainedTokenizerFast keeps its Rust backend on _tokenizer too.
+ processor = _base_processor()
+ trained = SimpleNamespace(chat_template = CHATML, _tokenizer = object())
+ assert carry(SimpleNamespace(_processor = processor), trained)
+ assert processor.tokenizer is trained
+
+
[email protected]("owner", ["processor", "tokenizer"])
+def test_checkpoints_with_a_template_are_left_alone(carry, owner):
+ processor = _base_processor()
+ own_tokenizer = processor.tokenizer
+ if owner == "processor":
+ processor.chat_template = "native"
+ else:
+ own_tokenizer.chat_template = "native"
+ assert not carry(SimpleNamespace(_processor = processor), SimpleNamespace(chat_template = CHATML))
+ assert processor.tokenizer is own_tokenizer
+ assert processor.chat_template == ("native" if owner == "processor" else None)
+
+
+def test_no_processor_or_no_template_is_a_no_op(carry):
+ trained = SimpleNamespace(chat_template = CHATML)
+ assert not carry(SimpleNamespace(), trained)
+ processor = _base_processor()
+ assert not carry(SimpleNamespace(_processor = processor), SimpleNamespace(chat_template = None))
+ assert processor.chat_template is None
+
+
+def test_template_set_in_place_on_the_processor_tokenizer_still_reaches_the_processor(carry):
+ processor = _base_processor()
+ processor.tokenizer.chat_template = CHATML
+ assert carry(SimpleNamespace(_processor = processor), processor.tokenizer)
+ assert processor.chat_template == CHATML
diff --git a/studio/backend/utils/models/model_config.py b/studio/backend/utils/models/model_config.py
index acb8ca401b7..948926e2302 100644
--- a/studio/backend/utils/models/model_config.py
+++ b/studio/backend/utils/models/model_config.py
@@ -4218,6 +4218,37 @@ def load_mlx_adapter_tokenizer(
return adapter_tokenizer if adapter_tokenizer.chat_template else tokenizer
+def load_mlx_adapter_processor(
+ processor,
+ lora_path: str,
+ hf_token: HfTokenArg = None,
+):
+ """The processor counterpart of load_mlx_adapter_tokenizer, for multimodal bases such as Qwen3.5 Base."""
+ own = getattr(processor, "tokenizer", None)
+ if (
+ own is None
+ or getattr(processor, "chat_template", None)
+ or getattr(own, "chat_template", None)
+ ):
+ return processor
+ adapter = load_mlx_adapter_tokenizer(own, lora_path, hf_token)
+ trained = (
+ getattr(adapter, "_tokenizer", adapter)
+ if type(adapter).__name__ == "TokenizerWrapper"
+ else adapter
+ )
+ template = getattr(trained, "chat_template", None)
+ if adapter is own or not template:
+ return processor
+ # mlx-vlm (stopping_criteria) and the MLX loader (_unsloth_* tags) hang state off the processor's tokenizer.
+ for name, value in vars(own).items():
+ if not hasattr(trained, name):
+ setattr(trained, name, value)
+ processor.tokenizer = trained
+ processor.chat_template = template
+ return processor
+
+
def get_base_model_from_lora_identifier(
identifier: str, hf_token: Optional[str] = None
) -> Optional[str]: