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 the cold unsloth.save import, the preview role map and the GPU memory cap (#11077)
Daniel Hane15a75ee6f6e
diff --git a/studio/backend/core/training/worker.py b/studio/backend/core/training/worker.pyindex 7aceed273f8..44d6c3bb61d 100644--- a/studio/backend/core/training/worker.py+++ b/studio/backend/core/training/worker.py@@ -1600,7 +1600,10 @@ def _rocm_classify_unified_memory(props: Any) -> tuple[str, bool]:_UNIFIED_OS_RESERVE_BYTES = 16 * 1024**3_UNIFIED_MAX_RESERVE_FRACTION = 0.20_DISCRETE_MEM_FRACTION = 0.90+# The name this guard shipped with; still wins on a ROCm host, since setups export it._MEM_FRACTION_ENV = "UNSLOTH_ROCM_MEM_FRACTION"+# Backend neutral, so NVIDIA has a cap too (unsloth#8178).+_GPU_MEM_FRACTION_ENV = "UNSLOTH_GPU_MEM_FRACTION"def _parse_mem_fraction_env(env_value: str | None) -> float | None:@@ -1691,6 +1694,47 @@ def _rocm_memory_fraction(return min(fraction, _DISCRETE_MEM_FRACTION)+def _mem_fraction_env_names(backend: str) -> tuple[str, ...]:+ """Most specific first, so a host already exporting the ROCm name keeps its cap."""+ if backend == "rocm":+ return (_MEM_FRACTION_ENV, _GPU_MEM_FRACTION_ENV)+ return (_GPU_MEM_FRACTION_ENV,)+++def _mem_fraction_env_value(backend: str, environ: Any = None) -> tuple[str | None, str | None]:+ """``(raw, name)``, else the first one SET so a warning names what the user exported."""+ if environ is None:+ environ = os.environ+ first_set: tuple[str | None, str | None] = (None, None)+ for name in _mem_fraction_env_names(backend):+ raw = environ.get(name)+ if raw is None:+ continue+ if _parse_mem_fraction_env(raw) is not None:+ return raw, name+ if first_set == (None, None):+ first_set = (raw, name)+ return first_set+++def _gpu_memory_fraction(+ total_bytes: int,+ is_unified: bool,+ platform: str,+ backend: str,+ env_value: str | None = None,+ denominator_bytes: int | None = None,+) -> float:+ """An override in ``(0.0, 1.0]`` wins; else ROCm delegates unchanged and the rest+ answer ``1.0``, torch's uncapped default, so setting nothing changes nothing."""+ override = _parse_mem_fraction_env(env_value)+ if override is not None:+ return override+ if backend != "rocm":+ return 1.0+ return _rocm_memory_fraction(total_bytes, is_unified, platform, None, denominator_bytes)++# ── Fast-path hooks ──# Wrap transformers' is_causal_conv1d_available so the first call (at modeling import)# drives the install; models that never query the gate pay nothing.@@ -3666,90 +3710,96 @@ def run_training_process(*, event_queue: Any, stop_queue: Any, config: dict) ->try:import torch as _torch_memif _torch_mem.cuda.is_available():- # Classify unified vs discrete (see _rocm_classify_unified_memory's docstring).- _props = _torch_mem.cuda.get_device_properties(0)- _dev_name = _props.name- _gcn_arch, _is_unified = _rocm_classify_unified_memory(_props)- if _is_unified and not _gcn_arch:- logger.debug(- "ROCm OOM guard: gcnArchName absent -- inferred "- "unified memory from device name %r; applying unified cap",- _dev_name,- )- # Unified hosts on native Windows: mem_get_info's total is the WDDM budget the driver grants HIP (BIOS- # carve + ~half of remaining RAM). The OS share is already outside it, so any sub-1.0- # starve-protection double-taxes (48.49 GiB budget -> 38.79 allowed) and blocks loads that fit in free- # memory. Current AMD Windows wheels only enforce sub-1.0 fractions (gfx1151: 0.5 caps, 1.0- # overcommits via WDDM), so 1.0 behaves like torch's uncapped default. On Linux the total spans nearly- # all RAM, so keep a bounded headroom. props.total_memory is the pool the reserve comes out of, and- # from torch 2.10 also what the allocator scales; through 2.9 it scales hipMemGetInfo's total, a- # different number on a unified APU, so hand that to the helper on those wheels and the reserve is the- # same bytes either way.- _total_bytes = int(getattr(_props, "total_memory", 0) or 0)- _driver_total = 0- if not _allocator_divides_by_props_total(getattr(_torch_mem, "__version__", "")):- try:- _driver_total = int(_torch_mem.cuda.mem_get_info(0)[1])- except Exception:- _driver_total = 0- _env_raw = os.environ.get(_MEM_FRACTION_ENV)- _env_fraction = _parse_mem_fraction_env(_env_raw)- if _env_raw and _env_fraction is None:- logger.warning(- "ROCm OOM guard: ignoring %s=%r (needs a float in (0.0, 1.0]); "- "using the computed cap instead",- _MEM_FRACTION_ENV,+ # torch keeps the fraction PER DEVICE: a sharded run left the rest uncapped.+ _unified_seen = False+ for _mem_index in range(_torch_mem.cuda.device_count()):+ # Classify unified vs discrete (see _rocm_classify_unified_memory's docstring).+ _props = _torch_mem.cuda.get_device_properties(_mem_index)+ _dev_name = _props.name+ _gcn_arch, _is_unified = _rocm_classify_unified_memory(_props)+ if _is_unified and not _gcn_arch:+ logger.debug(+ "ROCm OOM guard: gcnArchName absent -- inferred "+ "unified memory from device name %r; applying unified cap",+ _dev_name,+ )+ # On native Windows mem_get_info's total is the WDDM budget, which already+ # excludes the OS share, so any sub-1.0 double-taxes; Linux totals span+ # nearly all RAM, so keep headroom. The allocator scales props.total_memory+ # from torch 2.10 and hipMemGetInfo's total through 2.9, so hand the driver+ # total to the helper there and the reserve is the same bytes either way.+ _total_bytes = int(getattr(_props, "total_memory", 0) or 0)+ _driver_total = 0+ if not _allocator_divides_by_props_total(+ getattr(_torch_mem, "__version__", "")+ ):+ try:+ _driver_total = int(_torch_mem.cuda.mem_get_info(_mem_index)[1])+ except Exception:+ _driver_total = 0+ # ROCm name first, so an existing export keeps the cap it had.+ _env_raw, _env_name = _mem_fraction_env_value("rocm")+ _env_fraction = _parse_mem_fraction_env(_env_raw)+ if _env_raw and _env_fraction is None:+ logger.warning(+ "ROCm OOM guard: ignoring %s=%r (needs a float in (0.0, 1.0]); "+ "using the computed cap instead",+ _env_name,+ _env_raw,+ )+ _mem_fraction = _gpu_memory_fraction(+ _total_bytes,+ _is_unified,+ sys.platform,+ "rocm",_env_raw,+ _driver_total or None,)- _mem_fraction = _rocm_memory_fraction(- _total_bytes, _is_unified, sys.platform, _env_raw, _driver_total or None- )- # A wheel that reports no total still gets a cap; say so rather than printing "0.0 of 0.0 GiB allowed"- # on the one host whose props are suspect.- _allowed = (- f"{_total_bytes * _mem_fraction / 1024**3:.1f} of "- f"{_total_bytes / 1024**3:.1f} GiB allowed"- if _total_bytes > 0- else "device total unreported by this wheel"- )- _torch_mem.cuda.set_per_process_memory_fraction(_mem_fraction)- logger.info(- "ROCm OOM guard: set_per_process_memory_fraction(%.4f) — "- "%s memory host (%s, %s), %s, %s",- _mem_fraction,- "unified" if _is_unified else "discrete",- _dev_name,- _gcn_arch or "unknown arch",- _allowed,- f"from {_MEM_FRACTION_ENV}"- if _env_fraction is not None- else f"computed; override with {_MEM_FRACTION_ENV}",- )- # When the totals differ the cap was solved against the driver's, so the budget printed above is not- # the one enforced. Give both, and the headroom that results, which the floor can leave under the- # intended reserve.- if (- _is_unified- and sys.platform != "win32"- and _env_fraction is None- and _total_bytes > 0- and _driver_total > 0- and abs(_driver_total - _total_bytes) > _total_bytes // 100- ):+ _allowed = (+ f"{_total_bytes * _mem_fraction / 1024**3:.1f} of "+ f"{_total_bytes / 1024**3:.1f} GiB allowed"+ if _total_bytes > 0+ else "device total unreported by this wheel"+ )+ _torch_mem.cuda.set_per_process_memory_fraction(_mem_fraction, _mem_index)logger.info(- "ROCm OOM guard: props.total_memory is %.1f GiB but this torch caps "- "against the driver's %.1f GiB, so the fraction is solved for that "- "total and %.1f GiB stays free against the intended %.1f GiB. Adjust "- "with %s.",- _total_bytes / 1024**3,- _driver_total / 1024**3,- (_total_bytes - _mem_fraction * _driver_total) / 1024**3,- _UNIFIED_OS_RESERVE_BYTES / 1024**3,- _MEM_FRACTION_ENV,+ "ROCm OOM guard: set_per_process_memory_fraction(%.4f, cuda:%d) — "+ "%s memory host (%s, %s), %s, %s",+ _mem_fraction,+ _mem_index,+ "unified" if _is_unified else "discrete",+ _dev_name,+ _gcn_arch or "unknown arch",+ _allowed,+ f"from {_env_name}"+ if _env_fraction is not None+ else f"computed; override with {_MEM_FRACTION_ENV} or {_GPU_MEM_FRACTION_ENV}",)+ # Differing totals: the budget printed above is not the one enforced.+ if (+ _is_unified+ and sys.platform != "win32"+ and _env_fraction is None+ and _total_bytes > 0+ and _driver_total > 0+ and abs(_driver_total - _total_bytes) > _total_bytes // 100+ ):+ logger.info(+ "ROCm OOM guard: props.total_memory is %.1f GiB but this torch caps "+ "against the driver's %.1f GiB, so the fraction is solved for that "+ "total and %.1f GiB stays free against the intended %.1f GiB. Adjust "+ "with %s.",+ _total_bytes / 1024**3,+ _driver_total / 1024**3,+ (_total_bytes - _mem_fraction * _driver_total) / 1024**3,+ _UNIFIED_OS_RESERVE_BYTES / 1024**3,+ _MEM_FRACTION_ENV,+ )+ _unified_seen = _unified_seen or _is_unified+# Unified Windows APUs: the WDDM budget is user-raisable, but nothing on the box says so -- users see# "48 GB VRAM" on a 96 GB machine. Say where the limit comes from.- if _is_unified and sys.platform == "win32":+ if _unified_seen and sys.platform == "win32":try:import psutil as _psutil@@ -3770,6 +3820,46 @@ def run_training_process(*, event_queue: Any, stop_queue: Any, config: dict) ->except Exception as _oom_guard_err:logger.debug("Could not set GPU memory fraction: %s", _oom_guard_err)+ # A user preference, unlike the driver-forced ROCm arm; XPU and MPS are not wired yet.+ # ── 1h. Explicit GPU memory cap ──+ if not _hw.IS_ROCM:+ _cap_raw, _cap_name = _mem_fraction_env_value("cuda")+ _cap_fraction = _parse_mem_fraction_env(_cap_raw)+ if _cap_raw and _cap_fraction is None:+ logger.warning(+ "Ignoring %s=%r (needs a float in (0.0, 1.0]); leaving GPU memory uncapped",+ _cap_name,+ _cap_raw,+ )+ elif _cap_fraction is not None:+ try:+ import torch as _torch_cap+ if _torch_cap.cuda.is_available():+ _cap = _gpu_memory_fraction(0, False, sys.platform, "cuda", _cap_raw)+ # Named explicitly: the fraction is PER DEVICE, so `get_device_map` jobs+ # left cuda:1 and up uncapped.+ for _cap_index in range(_torch_cap.cuda.device_count()):+ _torch_cap.cuda.set_per_process_memory_fraction(_cap, _cap_index)+ _cap_props = _torch_cap.cuda.get_device_properties(_cap_index)+ _cap_total = int(getattr(_cap_props, "total_memory", 0) or 0)+ logger.info(+ "GPU memory cap: set_per_process_memory_fraction(%.4f, cuda:%d) from %s — %s, %s",+ _cap,+ _cap_index,+ _cap_name,+ getattr(_cap_props, "name", "unknown device"),+ f"{_cap_total * _cap / 1024**3:.1f} of {_cap_total / 1024**3:.1f} GiB allowed"+ if _cap_total > 0+ else "device total unreported by this wheel",+ )+ else:+ logger.debug(+ "%s is set but no torch CUDA device is available; nothing to cap",+ _cap_name,+ )+ except Exception as _cap_err:+ logger.debug("Could not set GPU memory fraction: %s", _cap_err)+# ── 2. Now import ML libraries (fresh in this clean process) ──try:_send_status(event_queue, "Importing Unsloth...")diff --git a/studio/backend/hub/utils/dataset_format.py b/studio/backend/hub/utils/dataset_format.pyindex 310367f4ed8..2c8756aa95f 100644--- a/studio/backend/hub/utils/dataset_format.py+++ b/studio/backend/hub/utils/dataset_format.py@@ -709,6 +709,8 @@ def check_dataset_format(dataset, is_vlm: bool = False) -> dict:}+# The aliases `standardize_data_formats` accepts. Keys are normalised: look them up+# through `_normalize_role_alias`._ROLE_MAP = {"human": "user","user": "user",@@ -720,6 +722,14 @@ _ROLE_MAP = {}+def _normalize_role_alias(role: Any) -> str:+ """Match aliases the way the trainer does: `role.strip().lower()`, as+ `standardize_data_formats` compares them (unslothai/unsloth-zoo#1225)."""+ if role is None:+ return ""+ return str(role).strip().lower()++def _standardize_sharegpt_row(row: dict[str, Any], chat_column: str) -> dict[str, Any]:chat_data = row.get(chat_column)if not isinstance(chat_data, list):@@ -730,9 +740,11 @@ def _standardize_sharegpt_row(row: dict[str, Any], chat_column: str) -> dict[strcontinuerole = message.get("role") or message.get("from")content = message.get("content") if "content" in message else message.get("value")+ normalized = _normalize_role_alias(role)messages.append({- "role": _ROLE_MAP.get(str(role), str(role or "user")),+ # Unknown alias shown as written; blank falls back to "user", as before.+ "role": _ROLE_MAP.get(normalized, str(role)) if normalized else "user","content": "" if content is None else content,})diff --git a/studio/backend/tests/test_dataset_preview_role_aliases.py b/studio/backend/tests/test_dataset_preview_role_aliases.pynew file mode 100644index 00000000000..519c4e5396d--- /dev/null+++ b/studio/backend/tests/test_dataset_preview_role_aliases.py@@ -0,0 +1,274 @@+# SPDX-License-Identifier: AGPL-3.0-only+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0++"""The preview's copy of the alias map matched the RAW role, while the zoo matches+`role.strip().lower()` (unslothai/unsloth-zoo#1225), so "Human"/"GPT" trained differently."""++import json+import sys+from pathlib import Path++import pytest++_BACKEND_ROOT = Path(__file__).resolve().parents[1]+if str(_BACKEND_ROOT) not in sys.path:+ sys.path.insert(0, str(_BACKEND_ROOT))++from hub.utils.dataset_format import ( # noqa: E402+ _ROLE_MAP,+ _normalize_role_alias,+ _standardize_sharegpt_row,+)++# Left previews as right, matching what standardize_data_formats writes for the trainer.+_SPELLINGS = [+ ("human", "user"),+ ("Human", "user"),+ ("HUMAN", "user"),+ ("hUmAn", "user"),+ (" human", "user"),+ ("human ", "user"),+ ("\thuman\n", "user"),+ (" Human ", "user"),+ ("user", "user"),+ ("User", "user"),+ ("USER", "user"),+ (" user ", "user"),+ ("input", "user"),+ ("Input", "user"),+ ("INPUT", "user"),+ ("gpt", "assistant"),+ ("GPT", "assistant"),+ ("Gpt", "assistant"),+ (" gpt\t", "assistant"),+ ("assistant", "assistant"),+ ("Assistant", "assistant"),+ ("ASSISTANT", "assistant"),+ ("output", "assistant"),+ ("Output", "assistant"),+ ("OUTPUT", "assistant"),+ ("system", "system"),+ ("System", "system"),+ ("SYSTEM", "system"),+ ("\tSystem\n", "system"),+]++[email protected]("spelling, expected", _SPELLINGS)+def test_every_spelling_of_a_known_alias_normalises(spelling, expected):+ assert _ROLE_MAP.get(_normalize_role_alias(spelling)) == expected++[email protected]("spelling, expected", _SPELLINGS)+def test_the_preview_row_standardiser_maps_every_spelling(spelling, expected):+ row = {"conversations": [{"from": spelling, "value": "hello"}]}+ result = _standardize_sharegpt_row(row, "conversations")+ assert result["conversations"][0]["role"] == expected+ assert result["conversations"][0]["content"] == "hello"+++def test_the_role_key_is_read_before_the_from_key():+ row = {"conversations": [{"role": "GPT", "from": "Human", "value": "x"}]}+ assert (+ _standardize_sharegpt_row(row, "conversations")["conversations"][0]["role"] == "assistant"+ )+++def test_the_content_key_is_read_before_the_value_key():+ row = {"conversations": [{"from": "Human", "content": "c", "value": "v"}]}+ message = _standardize_sharegpt_row(row, "conversations")["conversations"][0]+ assert message["content"] == "c"+++def test_the_map_keys_are_all_already_normalised():+ for key in _ROLE_MAP:+ assert key == _normalize_role_alias(key), f"{key!r} is not in normalised form"+++def test_the_alias_set_is_the_one_the_trainer_accepts():+ """Cross-repo pin: an alias the zoo grows has to reach the preview too."""+ # Not importorskip: unsloth_zoo raises NotImplementedError, not ImportError, on a host+ # with no recognised accelerator, which is every GitHub macOS and Windows runner.+ try:+ import unsloth_zoo.dataset_utils as dataset_utils+ except Exception as error:+ pytest.skip(f"unsloth_zoo is not importable here: {type(error).__name__}: {error}")+ import inspect++ defaults = inspect.signature(dataset_utils.standardize_data_formats).parameters+ expected = {}+ for parameter, role in (+ ("aliases_for_system", "system"),+ ("aliases_for_user", "user"),+ ("aliases_for_assistant", "assistant"),+ ):+ for alias in defaults[parameter].default:+ expected[_normalize_role_alias(alias)] = role+ assert _ROLE_MAP == expected+++def test_an_unknown_role_is_still_shown_as_written():+ row = {"conversations": [{"from": "Narrator", "value": "x"}]}+ assert _standardize_sharegpt_row(row, "conversations")["conversations"][0]["role"] == "Narrator"++[email protected]("role", [None, "", " ", "\t"])+def test_a_missing_or_blank_role_still_defaults_to_user(role):+ row = {"conversations": [{"from": role, "value": "x"}]}+ assert _standardize_sharegpt_row(row, "conversations")["conversations"][0]["role"] == "user"+++def test_a_non_string_role_does_not_raise():+ row = {"conversations": [{"from": 7, "value": "x"}]}+ assert _standardize_sharegpt_row(row, "conversations")["conversations"][0]["role"] == "7"+++def test_a_none_content_becomes_an_empty_string():+ row = {"conversations": [{"from": "Human", "value": None}]}+ assert _standardize_sharegpt_row(row, "conversations")["conversations"][0]["content"] == ""+++def test_a_non_list_chat_column_is_returned_untouched():+ row = {"conversations": "not a list", "other": 1}+ assert _standardize_sharegpt_row(row, "conversations") == row+++def test_non_dict_messages_are_skipped():+ row = {"conversations": ["plain", {"from": "GPT", "value": "y"}]}+ messages = _standardize_sharegpt_row(row, "conversations")["conversations"]+ assert messages == [{"role": "assistant", "content": "y"}]+++def isolated_studio_home(tmp_path, monkeypatch):+ monkeypatch.setenv("UNSLOTH_STUDIO_HOME", str(tmp_path))+ return tmp_path+++def test_the_check_format_route_previews_a_mixed_case_sharegpt_upload(isolated_studio_home):+ pytest.importorskip("datasets")+ from routes import datasets as datasets_route+ from utils.paths import dataset_uploads_root++ conversation = [+ {"from": " System ", "value": "be brief"},+ {"from": "Human", "value": "hello"},+ {"from": "GPT", "value": "hi"},+ {"from": "Input", "value": "again"},+ {"from": "OUTPUT", "value": "sure"},+ ]+ uploads = dataset_uploads_root()+ uploads.mkdir(parents = True, exist_ok = True)+ path = uploads / "mixed_case_sharegpt.jsonl"+ path.write_text(+ "\n".join(json.dumps({"conversations": conversation}) for _ in range(3)) + "\n",+ encoding = "utf-8",+ )++ request = datasets_route.CheckFormatRequest(dataset_name = str(path))+ response = datasets_route.check_format(request, hf_token = None, current_subject = "test")++ assert response.detected_format == "sharegpt"+ assert response.preview_samples, "the route returned no preview rows"+ for sample in response.preview_samples:+ messages = sample["conversations"]+ if isinstance(messages, str):+ messages = json.loads(messages)+ assert [message["role"] for message in messages] == [+ "system",+ "user",+ "assistant",+ "user",+ "assistant",+ ]+++def test_the_training_standardiser_normalises_the_same_way():+ """Studio training reaches the local `standardize_chat_format`, not the zoo helper."""+ from utils.datasets.format_conversion import _normalize_role_alias as training_normalize+ for spelling, expected in _SPELLINGS:+ assert _ROLE_MAP[training_normalize(spelling)] == expected++[email protected]("spelling, expected", _SPELLINGS)+def test_standardize_chat_format_maps_every_spelling(spelling, expected):+ datasets = pytest.importorskip("datasets")+ from utils.datasets.format_conversion import standardize_chat_format++ dataset = datasets.Dataset.from_list(+ [{"conversations": [{"from": spelling, "value": "hello"}]}] * 4+ )+ result = standardize_chat_format(dataset, num_proc = 1)+ message = result[0]["conversations"][0]+ assert message["role"] == expected+ assert message["content"] == "hello"+++def test_standardize_chat_format_leaves_an_unknown_role_as_written():+ datasets = pytest.importorskip("datasets")+ from utils.datasets.format_conversion import standardize_chat_format++ dataset = datasets.Dataset.from_list(+ [{"conversations": [{"from": "Narrator", "value": "x"}]}] * 4+ )+ assert standardize_chat_format(dataset, num_proc = 1)[0]["conversations"][0]["role"] == "Narrator"+++def test_the_preview_and_the_training_path_agree_on_every_spelling():+ datasets = pytest.importorskip("datasets")+ from utils.datasets.format_conversion import standardize_chat_format++ conversation = [{"from": spelling, "value": "x"} for spelling, _ in _SPELLINGS]+ trained = standardize_chat_format(+ datasets.Dataset.from_list([{"conversations": conversation}] * 4), num_proc = 1+ )[0]["conversations"]+ previewed = _standardize_sharegpt_row({"conversations": conversation}, "conversations")[+ "conversations"+ ]+ assert [m["role"] for m in trained] == [m["role"] for m in previewed]++[email protected]("role", [None, "", " ", "\t"])+def test_the_training_path_defaults_a_blank_role_like_the_preview(role):+ """The training path preserved a blank role and most chat templates reject one."""+ datasets = pytest.importorskip("datasets")+ from utils.datasets.format_conversion import standardize_chat_format++ dataset = datasets.Dataset.from_list(+ [{"conversations": [{"from": role, "value": "x"}, {"from": "gpt", "value": "y"}]}] * 4+ )+ trained = standardize_chat_format(dataset, num_proc = 1)[0]["conversations"]+ previewed = _standardize_sharegpt_row(+ {"conversations": [{"from": role, "value": "x"}, {"from": "gpt", "value": "y"}]},+ "conversations",+ )["conversations"]++ assert trained[0]["role"] == "user"+ assert [m["role"] for m in trained] == [m["role"] for m in previewed]+++ "message, expected",+ [+ # Blank inferred role, usable fallback in the same message: training's `is None`+ # check skipped it and labelled an assistant turn as user.+ ({"role": "", "from": "gpt", "content": "answer"}, "assistant"),+ ({"role": " ", "from": "Human", "content": "q"}, "user"),+ ({"role": None, "from": "gpt", "content": "answer"}, "assistant"),+ # NEGATIVE CONTROLS: no fallback stays "user"; a present role wins over one.+ ({"role": "", "content": "answer"}, "user"),+ ({"role": "gpt", "from": "human", "content": "answer"}, "assistant"),+ ],+)+def test_a_blank_inferred_role_consults_the_same_fallback_the_preview_does(message, expected):+ datasets = pytest.importorskip("datasets")+ from utils.datasets.format_conversion import standardize_chat_format++ rows = [{"conversations": [dict(message), {"role": "user", "content": "x"}]}] * 4+ trained = standardize_chat_format(datasets.Dataset.from_list(rows), num_proc = 1)+ assert trained[0]["conversations"][0]["role"] == expected++ previewed = _standardize_sharegpt_row({"conversations": [dict(message)]}, "conversations")+ assert (+ previewed["conversations"][0]["role"] == expected+ ), "the preview and the training path disagree on this message"diff --git a/studio/backend/tests/test_gpu_mem_fraction_env.py b/studio/backend/tests/test_gpu_mem_fraction_env.pynew file mode 100644index 00000000000..86d0a06675f--- /dev/null+++ b/studio/backend/tests/test_gpu_mem_fraction_env.py@@ -0,0 +1,511 @@+# SPDX-License-Identifier: AGPL-3.0-only+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0++"""A backend-neutral GPU memory cap for the training worker (unsloth#8178). Section 1h+cannot be called directly, so the block is sliced out of worker.py by its banner+comments, which are therefore load-bearing, and executed against fakes."""++from __future__ import annotations++import textwrap+from pathlib import Path+from types import SimpleNamespace++import pytest++from core.training.worker import (+ _DISCRETE_MEM_FRACTION,+ _GPU_MEM_FRACTION_ENV,+ _MEM_FRACTION_ENV,+ _gpu_memory_fraction,+ _mem_fraction_env_names,+ _mem_fraction_env_value,+ _rocm_memory_fraction,+)++GIB = 1024**3++_WORKER_PY = Path(__file__).resolve().parents[1] / "core" / "training" / "worker.py"++# "cuda" is the one wired; the rest guard a later backend inheriting an unmeasured cap.+_OTHER_BACKENDS = ["cuda", "xpu", "mps", "cpu"]+_PLATFORMS = ["linux", "win32", "darwin"]++[email protected]("backend", _OTHER_BACKENDS)[email protected]("platform", _PLATFORMS)[email protected]("total", [0, 8 * GIB, 24 * GIB, 128 * GIB])[email protected]("is_unified", [False, True])+def test_every_non_rocm_backend_is_uncapped_without_an_override(+ backend: str, platform: str, total: int, is_unified: bool+) -> None:+ assert _gpu_memory_fraction(total, is_unified, platform, backend) == 1.0++[email protected]("platform", _PLATFORMS)[email protected]("total", [0, 8 * GIB, 24 * GIB, 80 * GIB, 128 * GIB, 512 * GIB])[email protected]("is_unified", [False, True])[email protected]("denominator", [None, 220 * GIB])+def test_the_rocm_arm_is_byte_identical_to_the_helper_it_delegates_to(+ platform: str, total: int, is_unified: bool, denominator: int | None+) -> None:+ assert _gpu_memory_fraction(+ total, is_unified, platform, "rocm", None, denominator+ ) == _rocm_memory_fraction(total, is_unified, platform, None, denominator)+++def test_a_known_rocm_answer_is_unchanged():+ # Spot values, so a refactor of both sides at once still fails here.+ assert _gpu_memory_fraction(24 * GIB, False, "linux", "rocm") == _DISCRETE_MEM_FRACTION+ assert _gpu_memory_fraction(128 * GIB, True, "win32", "rocm") == 1.0+ assert _gpu_memory_fraction(24 * GIB, True, "linux", "rocm") == pytest.approx(0.80)++[email protected]("backend", _OTHER_BACKENDS + ["rocm"])+ "raw, expected", [("0.5", 0.5), ("0.95", 0.95), ("1.0", 1.0), (" 0.25 ", 0.25)]+)+def test_a_usable_override_wins_on_every_backend(backend: str, raw: str, expected: float) -> None:+ assert _gpu_memory_fraction(128 * GIB, False, "linux", backend, raw) == pytest.approx(expected)++[email protected]("backend", _OTHER_BACKENDS)[email protected]("bad", ["", " ", "abc", "0", "0.0", "-0.5", "1.5", "nan", "inf"])+def test_an_unusable_override_leaves_a_non_rocm_backend_uncapped(backend: str, bad: str) -> None:+ assert _gpu_memory_fraction(128 * GIB, False, "linux", backend, bad) == 1.0++[email protected]("bad", ["", " ", "abc", "0", "0.0", "-0.5", "1.5", "nan", "inf"])+def test_an_unusable_override_leaves_rocm_on_its_computed_cap(bad: str) -> None:+ assert _gpu_memory_fraction(128 * GIB, True, "linux", "rocm", bad) == _rocm_memory_fraction(+ 128 * GIB, True, "linux", None+ )+++def test_rocm_reads_its_own_name_first():+ assert _mem_fraction_env_names("rocm") == (_MEM_FRACTION_ENV, _GPU_MEM_FRACTION_ENV)++[email protected]("backend", _OTHER_BACKENDS)+def test_other_backends_read_only_the_neutral_name(backend: str) -> None:+ assert _mem_fraction_env_names(backend) == (_GPU_MEM_FRACTION_ENV,)+++def test_the_rocm_name_still_wins_on_a_rocm_host():+ environ = {_MEM_FRACTION_ENV: "0.7", _GPU_MEM_FRACTION_ENV: "0.3"}+ assert _mem_fraction_env_value("rocm", environ) == ("0.7", _MEM_FRACTION_ENV)+ assert _gpu_memory_fraction(128 * GIB, True, "linux", "rocm", "0.7") == 0.7+++def test_the_neutral_name_serves_a_rocm_host_that_only_sets_it():+ environ = {_GPU_MEM_FRACTION_ENV: "0.6"}+ assert _mem_fraction_env_value("rocm", environ) == ("0.6", _GPU_MEM_FRACTION_ENV)+++def test_an_unusable_rocm_value_falls_through_to_the_neutral_one():+ environ = {_MEM_FRACTION_ENV: "abc", _GPU_MEM_FRACTION_ENV: "0.5"}+ assert _mem_fraction_env_value("rocm", environ) == ("0.5", _GPU_MEM_FRACTION_ENV)+++def test_when_nothing_parses_the_first_variable_that_was_set_is_named():+ environ = {_MEM_FRACTION_ENV: "abc", _GPU_MEM_FRACTION_ENV: "2.0"}+ assert _mem_fraction_env_value("rocm", environ) == ("abc", _MEM_FRACTION_ENV)+++def test_nothing_set_resolves_to_nothing():+ assert _mem_fraction_env_value("rocm", {}) == (None, None)+ assert _mem_fraction_env_value("cuda", {}) == (None, None)+++def test_a_cuda_host_ignores_the_rocm_only_name():+ # UNSLOTH_ROCM_MEM_FRACTION names a ROCm reserve policy, not a user's cap.+ environ = {_MEM_FRACTION_ENV: "0.5"}+ assert _mem_fraction_env_value("cuda", environ) == (None, None)+++def test_an_empty_string_is_treated_as_unset():+ assert _mem_fraction_env_value("cuda", {_GPU_MEM_FRACTION_ENV: ""}) == (+ "",+ _GPU_MEM_FRACTION_ENV,+ )+ assert _gpu_memory_fraction(0, False, "linux", "cuda", "") == 1.0+++def _section_1h_source() -> str:+ source = _WORKER_PY.read_text(encoding = "utf-8")+ start = source.index(" # ── 1h. Explicit GPU memory cap ──")+ end = source.index(" # ── 2. Now import ML libraries")+ return textwrap.dedent(source[start:end])+++def _make_logger():+ recorded = SimpleNamespace(info = [], warning = [], debug = [])++ def make(level):+ def log(message, *args):+ getattr(recorded, level).append(message % args if args else message)++ return log++ logger = SimpleNamespace(info = make("info"), warning = make("warning"), debug = make("debug"))+ return logger, recorded+++class _FakeCuda:+ """The fraction is stored against ONE device, so a scalar could not tell a cap on+ every GPU from a cap on cuda:0."""++ def __init__(+ self,+ available = True,+ total = 24 * GIB,+ name = "NVIDIA GeForce RTX 4090",+ count = 1,+ current = 0,+ ):+ self._available = available+ self._total = total+ self._name = name+ self._count = count+ self._current = current+ self.fraction = None+ self.fractions = {}++ def is_available(self):+ return self._available++ def device_count(self):+ return self._count if self._available else 0++ def current_device(self):+ return self._current++ def set_per_process_memory_fraction(+ self,+ fraction,+ device = None,+ ):+ index = self._current if device is None else device+ self.fractions[index] = fraction+ self.fraction = fraction++ def get_device_properties(self, index):+ return SimpleNamespace(total_memory = self._total, name = f"{self._name} #{index}")+++def _run_section_1h(+ *,+ is_rocm,+ environ,+ cuda = None,+ platform = "linux",+):+ import sys as _real_sys++ cuda = cuda if cuda is not None else _FakeCuda()+ logger, recorded = _make_logger()+ fake_torch = SimpleNamespace(cuda = cuda)++ from core.training import worker as worker_module++ def resolve_env(backend, environ_ = None):+ # The shipped line passes one argument, so the fake environ cannot arrive via os.+ return worker_module._mem_fraction_env_value(+ backend, environ if environ_ is None else environ_+ )++ namespace = {+ "_hw": SimpleNamespace(IS_ROCM = is_rocm),+ "os": SimpleNamespace(environ = environ),+ "sys": SimpleNamespace(+ platform = platform, modules = dict(_real_sys.modules, torch = fake_torch)+ ),+ "logger": logger,+ "_mem_fraction_env_value": resolve_env,+ "_parse_mem_fraction_env": worker_module._parse_mem_fraction_env,+ "_gpu_memory_fraction": worker_module._gpu_memory_fraction,+ "torch": fake_torch,+ }+ # `import torch` inside the block must reach the fake, not the real wheel.+ real_import = __import__++ def fake_import(name, *args, **kwargs):+ if name == "torch":+ return fake_torch+ return real_import(name, *args, **kwargs)++ builtins_map = __builtins__ if isinstance(__builtins__, dict) else vars(__builtins__)+ namespace["__builtins__"] = dict(builtins_map, __import__ = fake_import)++ exec(compile(_section_1h_source(), str(_WORKER_PY), "exec"), namespace)+ return cuda, recorded+++def test_the_block_does_nothing_when_no_variable_is_set():+ cuda, log = _run_section_1h(is_rocm = False, environ = {})+ assert cuda.fraction is None+ assert log.info == [] and log.warning == []+++def test_the_block_does_nothing_on_a_rocm_host():+ cuda, log = _run_section_1h(+ is_rocm = True,+ environ = {_GPU_MEM_FRACTION_ENV: "0.5"},+ )+ assert cuda.fraction is None+ assert log.info == []+++def test_the_block_caps_an_nvidia_device():+ cuda, log = _run_section_1h(is_rocm = False, environ = {_GPU_MEM_FRACTION_ENV: "0.75"})+ assert cuda.fraction == pytest.approx(0.75)+ assert len(log.info) == 1+ assert _GPU_MEM_FRACTION_ENV in log.info[0]+ assert "18.0 of 24.0 GiB allowed" in log.info[0]+++def test_the_block_ignores_the_rocm_only_variable_on_nvidia():+ cuda, log = _run_section_1h(is_rocm = False, environ = {_MEM_FRACTION_ENV: "0.5"})+ assert cuda.fraction is None+ assert log.info == [] and log.warning == []++[email protected]("bad", ["abc", "0", "1.5", "-1", "nan"])+def test_an_unusable_value_warns_and_leaves_the_device_uncapped(bad: str):+ cuda, log = _run_section_1h(is_rocm = False, environ = {_GPU_MEM_FRACTION_ENV: bad})+ assert cuda.fraction is None+ assert len(log.warning) == 1+ assert _GPU_MEM_FRACTION_ENV in log.warning[0]+ assert "uncapped" in log.warning[0]+++def test_a_host_with_no_cuda_device_is_a_debug_line_not_a_crash():+ cuda, log = _run_section_1h(+ is_rocm = False,+ environ = {_GPU_MEM_FRACTION_ENV: "0.5"},+ cuda = _FakeCuda(available = False),+ )+ assert cuda.fraction is None+ assert log.info == [] and log.warning == []+ assert len(log.debug) == 1+++def test_a_wheel_that_reports_no_total_still_caps():+ cuda, log = _run_section_1h(+ is_rocm = False,+ environ = {_GPU_MEM_FRACTION_ENV: "0.5"},+ cuda = _FakeCuda(total = 0),+ )+ assert cuda.fraction == pytest.approx(0.5)+ assert "device total unreported" in log.info[0]+++class _ExplodingCuda(_FakeCuda):+ def set_per_process_memory_fraction(self, fraction):+ raise RuntimeError("no CUDA-capable device is detected")+++def test_a_failure_inside_the_block_never_takes_the_run_down():+ cuda, log = _run_section_1h(+ is_rocm = False,+ environ = {_GPU_MEM_FRACTION_ENV: "0.5"},+ cuda = _ExplodingCuda(),+ )+ assert log.debug and "Could not set GPU memory fraction" in log.debug[0]++[email protected]("platform", _PLATFORMS)+def test_the_cap_is_the_same_on_every_platform(platform: str):+ cuda, _ = _run_section_1h(+ is_rocm = False,+ environ = {_GPU_MEM_FRACTION_ENV: "0.6"},+ platform = platform,+ )+ assert cuda.fraction == pytest.approx(0.6)+++def test_the_block_is_still_gated_on_the_rocm_flag():+ assert "if not _hw.IS_ROCM:" in _section_1h_source()+++def test_no_settings_route_reads_the_new_variable():+ """A Settings control is a follow-up; when added it must share this policy path."""+ backend_root = Path(__file__).resolve().parents[1]+ offenders = []+ for path in (backend_root / "routes").rglob("*.py"):+ if _GPU_MEM_FRACTION_ENV in path.read_text(encoding = "utf-8"):+ offenders.append(str(path.relative_to(backend_root)))+ assert offenders == [], offenders+++def test_every_visible_gpu_is_capped_not_just_the_current_one():+ """torch keeps the fraction per device and defaults to `current_device()`, so a+ sharded run left cuda:1 and up allocating freely (unsloth#8178)."""+ cuda, log = _run_section_1h(+ is_rocm = False,+ environ = {_GPU_MEM_FRACTION_ENV: "0.75"},+ cuda = _FakeCuda(count = 4),+ )+ assert cuda.fractions == {+ 0: pytest.approx(0.75),+ 1: pytest.approx(0.75),+ 2: pytest.approx(0.75),+ 3: pytest.approx(0.75),+ }+ assert len(log.info) == 4, log.info+ for index, line in enumerate(log.info):+ assert f"cuda:{index}" in line, line+ assert "18.0 of 24.0 GiB allowed" in line+++def test_the_cap_names_a_device_explicitly_rather_than_relying_on_the_current_one():+ """Control: with no `device` argument this records only cuda:3."""+ cuda, _log = _run_section_1h(+ is_rocm = False,+ environ = {_GPU_MEM_FRACTION_ENV: "0.5"},+ cuda = _FakeCuda(count = 4, current = 3),+ )+ assert sorted(cuda.fractions) == [0, 1, 2, 3]+++def test_a_single_gpu_host_is_unchanged():+ cuda, log = _run_section_1h(+ is_rocm = False,+ environ = {_GPU_MEM_FRACTION_ENV: "0.9"},+ cuda = _FakeCuda(count = 1),+ )+ assert cuda.fractions == {0: pytest.approx(0.9)}+ assert len(log.info) == 1+++def _section_1g_source() -> str:+ source = _WORKER_PY.read_text(encoding = "utf-8")+ start = source.index(" # ── 1g. ROCm OOM guard ──")+ end = source.index(" # ── 1h. Explicit GPU memory cap ──")+ return textwrap.dedent(source[start:end])+++class _FakeRocmCuda(_FakeCuda):+ def __init__(+ self,+ *,+ driver_total = None,+ gcn_arch = "gfx1100",+ **kwargs,+ ):+ kwargs.setdefault("name", "AMD Radeon PRO W7900")+ super().__init__(**kwargs)+ self._driver_total = self._total if driver_total is None else driver_total+ self._gcn_arch = gcn_arch++ def mem_get_info(self, index = None):+ return (self._driver_total // 2, self._driver_total)++ def get_device_properties(self, index):+ return SimpleNamespace(+ total_memory = self._total,+ name = f"{self._name} #{index}",+ gcnArchName = self._gcn_arch,+ )+++def _run_section_1g(+ *,+ environ,+ cuda = None,+ platform = "linux",+):+ import sys as _real_sys++ from core.training import worker as worker_module++ cuda = cuda if cuda is not None else _FakeRocmCuda()+ logger, recorded = _make_logger()+ fake_torch = SimpleNamespace(cuda = cuda, __version__ = "2.9.0+rocm6.4")++ def resolve_env(backend, environ_ = None):+ return worker_module._mem_fraction_env_value(+ backend, environ if environ_ is None else environ_+ )++ namespace = {+ "_hw": SimpleNamespace(IS_ROCM = True),+ "sys": SimpleNamespace(+ platform = platform, modules = dict(_real_sys.modules, torch = fake_torch)+ ),+ "logger": logger,+ "_mem_fraction_env_value": resolve_env,+ "_parse_mem_fraction_env": worker_module._parse_mem_fraction_env,+ "_gpu_memory_fraction": worker_module._gpu_memory_fraction,+ "_rocm_classify_unified_memory": worker_module._rocm_classify_unified_memory,+ "_allocator_divides_by_props_total": worker_module._allocator_divides_by_props_total,+ "_UNIFIED_OS_RESERVE_BYTES": worker_module._UNIFIED_OS_RESERVE_BYTES,+ "_MEM_FRACTION_ENV": _MEM_FRACTION_ENV,+ "_GPU_MEM_FRACTION_ENV": _GPU_MEM_FRACTION_ENV,+ "torch": fake_torch,+ }+ real_import = __import__++ def fake_import(name, *args, **kwargs):+ if name == "torch":+ return fake_torch+ return real_import(name, *args, **kwargs)++ builtins_map = __builtins__ if isinstance(__builtins__, dict) else vars(__builtins__)+ namespace["__builtins__"] = dict(builtins_map, __import__ = fake_import)++ exec(compile(_section_1g_source(), str(_WORKER_PY), "exec"), namespace)+ return cuda, recorded+++def test_the_rocm_guard_caps_every_visible_device():+ """A sharded ROCm run capped cuda:0 and logged success while cuda:1 and up ran free."""+ cuda, log = _run_section_1g(+ environ = {_GPU_MEM_FRACTION_ENV: "0.75"},+ cuda = _FakeRocmCuda(count = 4),+ )+ assert cuda.fractions == {index: pytest.approx(0.75) for index in range(4)}+ assert len(log.info) == 4, log.info+ for index, line in enumerate(log.info):+ assert f"cuda:{index}" in line, line+++def test_the_rocm_guard_names_the_device_rather_than_the_current_one():+ cuda, _log = _run_section_1g(+ environ = {_MEM_FRACTION_ENV: "0.5"},+ cuda = _FakeRocmCuda(count = 4, current = 2),+ )+ assert sorted(cuda.fractions) == [0, 1, 2, 3]+++def test_a_single_rocm_gpu_is_unchanged():+ cuda, log = _run_section_1g(+ environ = {_MEM_FRACTION_ENV: "0.9"},+ cuda = _FakeRocmCuda(count = 1),+ )+ assert cuda.fractions == {0: pytest.approx(0.9)}+ assert len(log.info) == 1+++def test_each_rocm_device_is_solved_from_its_own_properties():+ """A mixed APU + discrete host must not cap both from cuda:0: only the APU needs headroom."""++ class _MixedCuda(_FakeRocmCuda):+ def get_device_properties(self, index):+ unified = index == 0+ return SimpleNamespace(+ total_memory = 128 * GIB if unified else 48 * GIB,+ name = "AMD Radeon 8060S" if unified else "AMD Radeon PRO W7900",+ gcnArchName = "gfx1151" if unified else "gfx1100",+ )++ def mem_get_info(self, index = None):+ # Same pool both ways, so the cap is the one the properties alone imply.+ total = self.get_device_properties(index).total_memory+ return (total // 2, total)++ cuda, log = _run_section_1g(environ = {}, cuda = _MixedCuda(count = 2))+ assert cuda.fractions[1] == pytest.approx(_DISCRETE_MEM_FRACTION)+ assert cuda.fractions[0] == pytest.approx(_rocm_memory_fraction(128 * GIB, True, "linux"))+ assert cuda.fractions[0] != cuda.fractions[1]+ assert "unified" in log.info[0] and "discrete" in log.info[1]diff --git a/studio/backend/tests/test_rocm_oom_guard.py b/studio/backend/tests/test_rocm_oom_guard.pyindex 6d8cebd1560..8519d65a543 100644--- a/studio/backend/tests/test_rocm_oom_guard.py+++ b/studio/backend/tests/test_rocm_oom_guard.py@@ -9,6 +9,9 @@ Classification paths: (1) canonical gcnArchName, (2) alternate-spelling attr,Fraction selection: the unified-Linux reserve crossover, the discrete cap, theWindows budget-exact 1.0, and the UNSLOTH_ROCM_MEM_FRACTION override.+The guard reaches the policy through _gpu_memory_fraction; its ROCm arm is what this+file pins, and the backend-neutral half lives in test_gpu_mem_fraction_env.py.+Regression: Strix Halo (gfx1151) was misclassified as discrete on Radeon wheelsthat set props.name="Radeon 8060S Graphics" but no gcnArchName, applying thewrong headroom factor on a 128 GiB unified-memory pool.@@ -16,6 +19,7 @@ wrong headroom factor on a 128 GiB unified-memory pool.from __future__ import annotations+import refrom pathlib import Pathfrom types import SimpleNamespace@@ -286,7 +290,8 @@ class TestMemFractionSelection:the guard calls the helper, sizes against the allocator's own total, and tags thelog off the parsed override rather than the raw string."""source = _WORKER_PY.read_text(encoding = "utf-8")- assert "_mem_fraction = _rocm_memory_fraction(" in source+ # The one policy entry point; its "rocm" arm delegates to _rocm_memory_fraction.+ assert "_mem_fraction = _gpu_memory_fraction(" in source# totalGlobalMem is what the allocator multiplies the fraction by from torch# 2.10 on, so the reserve is only the intended size when the guard divides by# the same number. Before 2.10 the allocator divides by the driver's total.@@ -301,9 +306,11 @@ class TestMemFractionSelection:Scoped to the byte arm: discrete and win32 take a flat fraction, which nodenominator gap can distort."""source = _WORKER_PY.read_text(encoding = "utf-8")- assert "_driver_total = int(_torch_mem.cuda.mem_get_info(0)[1])" in source+ assert "mem_get_info(_mem_index)[1]" in sourceassert "if not _allocator_divides_by_props_total(" in source- assert "sys.platform, _env_raw, _driver_total or None" in source+ # Whitespace-insensitive because the formatter wraps this call; what is pinned is+ # that the cap is still solved against the driver's total, not the layout.+ assert re.search(r'sys\.platform,\s*"rocm",\s*_env_raw,\s*_driver_total or None', source)assert "but this torch caps" in sourcediff --git a/studio/backend/utils/datasets/format_conversion.py b/studio/backend/utils/datasets/format_conversion.pyindex 44cadc3b504..b0b165d3195 100644--- a/studio/backend/utils/datasets/format_conversion.py+++ b/studio/backend/utils/datasets/format_conversion.py@@ -21,6 +21,13 @@ def _quiet_bar_kwargs() -> dict:return {}+def _normalize_role_alias(role) -> str:+ """Stripped and lowercased, as `standardize_data_formats` and the preview do it."""+ if role is None:+ return ""+ return str(role).strip().lower()++def standardize_chat_format(dataset,tokenizer = None,@@ -107,13 +114,14 @@ def standardize_chat_format(else:raise ValueError(f"Could not infer role/content keys for chat column '{chat_column}'")+ # Keyed on the normalised alias: "Human" / " user " would reach the template raw.aliases_mapping = {}for x in aliases_for_system:- aliases_mapping[x] = "system"+ aliases_mapping[_normalize_role_alias(x)] = "system"for x in aliases_for_user:- aliases_mapping[x] = "user"+ aliases_mapping[_normalize_role_alias(x)] = "user"for x in aliases_for_assistant:- aliases_mapping[x] = "assistant"+ aliases_mapping[_normalize_role_alias(x)] = "assistant"def _standardize_dataset(examples):convos = examples[chat_column]@@ -131,12 +139,21 @@ def standardize_chat_format(# Use the inferred keys first, falling back per-message so mixed ShareGPT/ChatML rows keep valid turns.original_role = message.get(role_key)original_content = message.get(content_key)- if original_role is None:+ # Blank counts as absent for the ROLE, matching the preview: `is None` here+ # trained {"role": "", "from": "gpt"} as a user turn. Content is not blank-+ # checked, because an empty message is a legitimate value.+ if not _normalize_role_alias(original_role):original_role = message.get("role") or message.get("from") or ""if original_content is None:original_content = message.get("content") or message.get("value") or ""- standard_role = aliases_mapping.get(original_role, original_role)+ # Unknown alias left as written; blank is "user", as most templates reject one.+ normalized_role = _normalize_role_alias(original_role)+ standard_role = (+ aliases_mapping.get(normalized_role, original_role)+ if normalized_role+ else "user"+ )if is_vlm:original_content = [{"type": "text", "text": original_content}]diff --git a/tests/test_cold_import_order.py b/tests/test_cold_import_order.pynew file mode 100644index 00000000000..1b4c603b8ec--- /dev/null+++ b/tests/test_cold_import_order.py@@ -0,0 +1,363 @@+# SPDX-License-Identifier: AGPL-3.0-only+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved.++"""A cold `import unsloth.save` has to work, whatever imported first.++save.py -> .models.loader_utils -> models/__init__ -> llama -> vision, whose module-scope+`from ..save import ...` landed back in the half-built save.py. `_gpu_init.py` hid that by+importing `.models` first, but the MLX branch never reaches it.+"""++import ast+import os+import pathlib+import subprocess+import sys+import textwrap++import pytest++_ROOT = pathlib.Path(__file__).resolve().parents[1]+_MODELS_DIR = _ROOT / "unsloth" / "models"++# The names that used to be bound at module scope, and the modules that bound them.+_DEFERRED_NAMES = (+ "patch_saving_functions",+ "unsloth_save_pretrained_torchao",+ "unsloth_save_pretrained_gguf",+)+++def _model_sources():+ for path in sorted(_MODELS_DIR.rglob("*.py")):+ yield path, ast.parse(path.read_text(encoding = "utf-8"), filename = str(path))+++def _is_save_module(node, package_depth):+ """Absolute or relative: `from ..save` is level 2 one directory below the root."""+ if node.module == "unsloth.save":+ return True+ return node.level == package_depth and node.module == "save"+++def _module_scope_imports(tree):+ # Only the `import`s the interpreter runs while the module object is built.+ for node in tree.body:+ if isinstance(node, (ast.Import, ast.ImportFrom)):+ yield node+ # `try: from x import y` / `if TYPE_CHECKING:` at module scope still runs.+ for child in ast.iter_child_nodes(node):+ if isinstance(child, (ast.Import, ast.ImportFrom)) and not isinstance(+ node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)+ ):+ yield child+++def test_no_module_under_models_imports_unsloth_save_at_module_scope():+ offenders = []+ for path, tree in _model_sources():+ depth = len(path.relative_to(_ROOT / "unsloth").parts)+ for node in _module_scope_imports(tree):+ if isinstance(node, ast.ImportFrom) and _is_save_module(node, depth):+ offenders.append(+ f"{path.relative_to(_ROOT)}:{node.lineno} "+ f"imports {', '.join(a.name for a in node.names)}"+ )+ elif isinstance(node, ast.Import):+ for alias in node.names:+ if alias.name == "unsloth.save":+ offenders.append(+ f"{path.relative_to(_ROOT)}:{node.lineno} imports unsloth.save"+ )+ assert offenders == [], (+ "a module-scope import of unsloth.save from unsloth/models/ closes the cycle that "+ "breaks a cold `import unsloth.save`; move it into the function that needs it, the "+ "way unsloth/chat_templates.py does:\n " + "\n ".join(offenders)+ )+++def _module_level_functions(tree):+ return {node.name: node for node in tree.body if isinstance(node, ast.FunctionDef)}+++def test_every_module_that_calls_a_deferred_name_defines_the_shim_for_it():+ problems = []+ for path, tree in _model_sources():+ depth = len(path.relative_to(_ROOT / "unsloth").parts)+ module_functions = _module_level_functions(tree)+ called = {+ node.func.id+ for node in ast.walk(tree)+ if isinstance(node, ast.Call) and isinstance(node.func, ast.Name)+ }+ for name in _DEFERRED_NAMES:+ if name not in called:+ continue+ shim = module_functions.get(name)+ if shim is None:+ problems.append(+ f"{path.relative_to(_ROOT)} calls {name} and defines no shim for it"+ )+ continue+ imports = {+ alias.name+ for node in ast.walk(shim)+ if isinstance(node, ast.ImportFrom) and _is_save_module(node, depth)+ for alias in node.names+ }+ if name not in imports:+ problems.append(+ f"{path.relative_to(_ROOT)}:{shim.lineno} {name}() does not import "+ f"{name} from unsloth.save"+ )+ assert problems == [], "\n ".join([""] + problems)+++def test_the_deferred_names_are_still_exported_by_unsloth_save():+ """The gate above also passes on a tree where the names simply went away."""+ source = (_ROOT / "unsloth" / "save.py").read_text(encoding = "utf-8")+ tree = ast.parse(source)+ defined = {+ node.name for node in tree.body if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef))+ }+ for name in _DEFERRED_NAMES:+ assert name in defined, f"unsloth.save no longer defines {name}"+ exported = next(+ node.value+ for node in tree.body+ if isinstance(node, ast.Assign)+ and any(getattr(t, "id", None) == "__all__" for t in node.targets)+ )+ listed = {elt.value for elt in exported.elts if isinstance(elt, ast.Constant)}+ # Only this one is in `__all__`; the save_pretrained helpers are reached by name.+ assert "patch_saving_functions" in listed+++def _run(code):+ path = [str(_ROOT)]+ if os.environ.get("PYTHONPATH"):+ path.append(os.environ["PYTHONPATH"])+ return subprocess.run(+ [sys.executable, "-c", textwrap.dedent(code)],+ capture_output = True,+ text = True,+ env = dict(os.environ, PYTHONPATH = os.pathsep.join(path)),+ timeout = 900,+ )+++def _models_importable():+ """Not `find_spec("torch")`: a GitHub macOS runner has torch and still cannot import+ this, because `unsloth_zoo.device_type` raises NotImplementedError with no accelerator."""+ result = _run(+ """+ import unsloth.models # noqa: F401+ print("MODELS_OK")+ """+ )+ return "MODELS_OK" in result.stdout+++_needs_torch = pytest.mark.skipif(+ not _models_importable(),+ reason = (+ "importing unsloth.models does not complete in this environment (no torch, or no "+ "accelerator unsloth_zoo recognises)"+ ),+)+++# The MLX ordering without MLX: faking the branch needs mlx, mlx_lm and an Apple uname.+_COLD_SAVE_FIRST = """+ import importlib+ import importlib.machinery+ import os+ import sys+ import types++ root = os.path.dirname(os.path.dirname(os.path.abspath(%r)))+ pkg_path = os.path.join(root, "unsloth")+ pkg = types.ModuleType("unsloth")+ pkg.__path__ = [pkg_path]+ pkg.__package__ = "unsloth"+ pkg.__file__ = os.path.join(pkg_path, "__init__.py")+ pkg.__spec__ = importlib.machinery.ModuleSpec(+ "unsloth", loader = None, origin = pkg.__file__, is_package = True,+ )+ pkg.__spec__.submodule_search_locations = [pkg_path]+ sys.modules["unsloth"] = pkg++ import unsloth.save as save++ assert callable(save.patch_saving_functions)+ for name in ("vision", "llama", "sentence_transformer"):+ assert "unsloth.models." + name in sys.modules, name+ vision = importlib.import_module("unsloth.models.vision")+ sentence = importlib.import_module("unsloth.models.sentence_transformer")+ # The shims are still module attributes, and they reach the real functions.+ assert callable(vision.patch_saving_functions)+ assert callable(sentence.unsloth_save_pretrained_gguf)+ assert callable(sentence.unsloth_save_pretrained_torchao)+ exec("from ..save import patch_saving_functions as _direct", vars(vision))+ assert vision._direct is save.patch_saving_functions+ print("COLD_SAVE_FIRST_OK")+ """+++@_needs_torch+def test_a_cold_import_of_unsloth_save_does_not_hit_the_cycle():+ result = _run(_COLD_SAVE_FIRST % (str(__file__),))+ assert "COLD_SAVE_FIRST_OK" in result.stdout, (+ "a cold `import unsloth.save` with unsloth.models not yet loaded failed; this is the "+ f"Apple Silicon ordering.\nstdout:\n{result.stdout}\nstderr:\n{result.stderr}"+ )+ assert "partially initialized module" not in result.stderr+++@_needs_torch+ "first, second",+ [+ ("unsloth.save", "unsloth.models"),+ ("unsloth.models", "unsloth.save"),+ ("unsloth.models.sentence_transformer", "unsloth.save"),+ ("unsloth.save", "unsloth.models.sentence_transformer"),+ ],+)+def test_either_import_order_works_through_the_real_package_init(first, second):+ """Passes on the unfixed tree too, so the fix cannot be mistaken for changing it."""+ result = _run(+ f"""+ import {first}+ import {second}+ import unsloth.save+ assert callable(unsloth.save.patch_saving_functions)+ print("ORDER_OK")+ """+ )+ assert "ORDER_OK" in result.stdout, f"stdout:\n{result.stdout}\nstderr:\n{result.stderr}"+++@_needs_torch+def test_the_star_export_from_gpu_init_still_carries_the_names():+ """`from unsloth import patch_saving_functions` has to keep working for old scripts."""+ result = _run(+ """+ import unsloth+ from unsloth import patch_saving_functions+ from unsloth.save import patch_saving_functions as direct+ assert patch_saving_functions is direct+ print("STAR_OK")+ """+ )+ assert "STAR_OK" in result.stdout, f"stdout:\n{result.stdout}\nstderr:\n{result.stderr}"+++def test_save_publishes_the_deferred_names_back_over_its_own_shims():+ """Without the publish-back, `inspect.signature` would read `(*args, **kwargs)`."""+ source = (_ROOT / "unsloth" / "save.py").read_text(encoding = "utf-8")+ assert "_unsloth_deferred_shim" in source, (+ "unsloth/save.py no longer publishes the deferred names back to unsloth.models, so "+ "the shims stay visible after import"+ )+ for module_name in (+ "unsloth.models.vision",+ "unsloth.models.llama",+ "unsloth.models.sentence_transformer",+ ):+ assert module_name in source, f"save.py does not publish back to {module_name}"++ for path, tree in _model_sources():+ module_functions = _module_level_functions(tree)+ marked = {+ node.targets[0].value.id+ for node in tree.body+ if isinstance(node, ast.Assign)+ and isinstance(node.targets[0], ast.Attribute)+ and node.targets[0].attr == "_unsloth_deferred_shim"+ and isinstance(node.targets[0].value, ast.Name)+ }+ for name in _DEFERRED_NAMES:+ if name not in module_functions:+ continue+ assert name in marked, (+ f"{path.relative_to(_ROOT)} defines the {name} shim but never sets "+ f"{name}._unsloth_deferred_shim, so save.py will not replace it"+ )+++@_needs_torch+def test_the_module_attributes_are_the_real_functions_once_save_is_imported():+ result = _run(+ """+ import importlib+ import inspect+ import unsloth+ import unsloth.save as save++ for module_name, names in (+ ("unsloth.models.vision", ("patch_saving_functions",)),+ ("unsloth.models.llama", ("patch_saving_functions",)),+ (+ "unsloth.models.sentence_transformer",+ ("unsloth_save_pretrained_torchao", "unsloth_save_pretrained_gguf"),+ ),+ ):+ module = importlib.import_module(module_name)+ for name in names:+ attribute = getattr(module, name)+ implementation = getattr(save, name)+ assert attribute is implementation, (module_name, name)+ assert not getattr(attribute, "_unsloth_deferred_shim", False), (+ module_name, name,+ )+ assert inspect.signature(attribute) == inspect.signature(implementation)+ print("PUBLISHED_OK")+ """+ )+ assert "PUBLISHED_OK" in result.stdout, f"stdout:\n{result.stdout}\nstderr:\n{result.stderr}"+++_SHIM_ONLY = """+ import importlib+ import importlib.machinery+ import os+ import sys+ import types++ root = os.path.dirname(os.path.dirname(os.path.abspath(%r)))+ pkg_path = os.path.join(root, "unsloth")+ pkg = types.ModuleType("unsloth")+ pkg.__path__ = [pkg_path]+ pkg.__package__ = "unsloth"+ pkg.__file__ = os.path.join(pkg_path, "__init__.py")+ pkg.__spec__ = importlib.machinery.ModuleSpec(+ "unsloth", loader = None, origin = pkg.__file__, is_package = True,+ )+ pkg.__spec__.submodule_search_locations = [pkg_path]+ sys.modules["unsloth"] = pkg++ import unsloth.models.vision as vision++ shim = vision.patch_saving_functions+ assert callable(shim)+ assert getattr(shim, "_unsloth_deferred_shim", False), (+ "unsloth.save has not been imported, so this attribute should still be the shim"+ )++ import unsloth.save as save++ # The shim captured before save.py published over it still reaches unsloth.save, with+ # the arguments untouched.+ seen = []+ save.patch_saving_functions = lambda *a, **k: seen.append((a, k))+ shim("model", vision = True)+ assert seen == [(("model",), {"vision": True})], seen+ print("SHIM_OK")+ """+++@_needs_torch+def test_a_module_that_never_imports_save_still_gets_a_working_name():+ result = _run(_SHIM_ONLY % (str(__file__),))+ assert "SHIM_OK" in result.stdout, f"stdout:\n{result.stdout}\nstderr:\n{result.stderr}"diff --git a/unsloth/models/llama.py b/unsloth/models/llama.pyindex 62cc0093f9b..462e7af45fa 100644--- a/unsloth/models/llama.py+++ b/unsloth/models/llama.py@@ -134,7 +134,20 @@ from transformers.models.auto.modeling_auto import MODEL_FOR_CAUSAL_LM_MAPPINGfrom transformers import set_seed as transformers_set_seedfrom peft import LoraConfig, TaskType, get_peft_model as _get_peft_modelfrom peft import PeftModelForCausalLM, PeftModelForSequenceClassification-from ..save import patch_saving_functions+# Deferred to first call: a module-scope bind out of `unsloth.save` closes an import cycle.+# See the note in unsloth/models/vision.py and tests/test_cold_import_order.py.+++def patch_saving_functions(*args, **kwargs):+ """Hand off to ``unsloth.save.patch_saving_functions``, imported on first call."""+ from ..save import patch_saving_functions as _impl+ return _impl(*args, **kwargs)+++# How unsloth/save.py tells its own shim from a function someone else put here.+patch_saving_functions._unsloth_deferred_shim = True++import re, os, inspect, math, sysimport typesdiff --git a/unsloth/models/sentence_transformer.py b/unsloth/models/sentence_transformer.pyindex 3c14c681940..1460f39843c 100644--- a/unsloth/models/sentence_transformer.py+++ b/unsloth/models/sentence_transformer.py@@ -42,7 +42,27 @@ import refrom transformers import AutoModel, AutoConfigimport tempfilefrom huggingface_hub import HfApi, get_token-from ..save import unsloth_save_pretrained_torchao, unsloth_save_pretrained_gguf+# Deferred to first call: a module-scope bind out of `unsloth.save` closes an import cycle.+# See the note in unsloth/models/vision.py and tests/test_cold_import_order.py.+++def unsloth_save_pretrained_torchao(*args, **kwargs):+ """Hand off to ``unsloth.save.unsloth_save_pretrained_torchao``, imported on first call."""+ from ..save import unsloth_save_pretrained_torchao as _impl+ return _impl(*args, **kwargs)+++def unsloth_save_pretrained_gguf(*args, **kwargs):+ """Hand off to ``unsloth.save.unsloth_save_pretrained_gguf``, imported on first call."""+ from ..save import unsloth_save_pretrained_gguf as _impl+ return _impl(*args, **kwargs)+++# How unsloth/save.py tells its own shims from functions someone else put here.+unsloth_save_pretrained_torchao._unsloth_deferred_shim = True+unsloth_save_pretrained_gguf._unsloth_deferred_shim = True++import contextlibimport shutildiff --git a/unsloth/models/vision.py b/unsloth/models/vision.pyindex 1f6c1fbeb7d..1668084f452 100644--- a/unsloth/models/vision.py+++ b/unsloth/models/vision.py@@ -56,7 +56,23 @@ from .loader_utils import (requested_device_map,resolve_unsloth_device_map,)-from ..save import patch_saving_functions+# `unsloth.save` imports `.models.loader_utils`, so binding a name out of it here at module+# scope closes a cycle and a cold `import unsloth.save` fails on the half-built module.+# `_gpu_init` hid that by importing `.models` first; the MLX branch never reaches it. So the+# hand-off is deferred to first call, and save.py replaces this shim with the real function on+# the last line of its own body. Pinned by tests/test_cold_import_order.py.+++def patch_saving_functions(*args, **kwargs):+ """Hand off to ``unsloth.save.patch_saving_functions``, imported on first call."""+ from ..save import patch_saving_functions as _impl+ return _impl(*args, **kwargs)+++# How unsloth/save.py tells its own shim from a function someone else put here.+patch_saving_functions._unsloth_deferred_shim = True++from ..models.loader_utils import is_distributedfrom unsloth_zoo.gradient_checkpointing import (unpatch_unsloth_gradient_checkpointing,diff --git a/unsloth/save.py b/unsloth/save.pyindex 2db97ba5ef0..3c248de789b 100644--- a/unsloth/save.py+++ b/unsloth/save.py@@ -7107,3 +7107,25 @@ def patch_saving_functions(model, vision = False):model.save_pretrained_gguf = types.MethodType(unsloth_save_pretrained_gguf, model)model.save_pretrained_torchao = types.MethodType(unsloth_save_pretrained_torchao, model)return model+++# Publish the deferred names back to unsloth.models. Those modules bind shims instead of+# these names to avoid an import cycle (see unsloth/models/vision.py); this module and+# `.models` are both complete by the time this runs, so hand the real objects over and the+# attributes regain their identity, signature and docstring.+_DEFERRED_INTO_MODELS = {+ "unsloth.models.vision": ("patch_saving_functions",),+ "unsloth.models.llama": ("patch_saving_functions",),+ "unsloth.models.sentence_transformer": (+ "unsloth_save_pretrained_torchao",+ "unsloth_save_pretrained_gguf",+ ),+}+for _module_name, _deferred_names in _DEFERRED_INTO_MODELS.items():+ _module = sys.modules.get(_module_name)+ if _module is None:+ continue+ for _deferred_name in _deferred_names:+ # Only ever replace our own shim; anything else is left exactly as it is.+ if getattr(getattr(_module, _deferred_name, None), "_unsloth_deferred_shim", False):+ setattr(_module, _deferred_name, globals()[_deferred_name])