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
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.pyindex 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_cachefrom utils.models import is_vision_model, get_base_model_from_lorafrom 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 = processorelse:diff --git a/studio/backend/core/inference/mlx_inference.py b/studio/backend/core/inference/mlx_inference.pyindex 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_deadfrom 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 = modelself._processor = processorself._tokenizer = getattr(processor, "tokenizer", processor)diff --git a/studio/backend/core/training/worker.py b/studio/backend/core/training/worker.pyindex 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.pyindex 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: Noneutils_model_config.load_mlx_adapter_tokenizer = lambda tokenizer, *args, **kwargs: tokenizer+ utils_model_config.load_mlx_adapter_processor = lambda processor, *args, **kwargs: processorutils_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.pyindex 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, adapterassert ok, messageassert 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.pynew file mode 100644index 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 == CHATMLdiff --git a/studio/backend/utils/models/model_config.py b/studio/backend/utils/models/model_config.pyindex 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]: