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 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.py
index 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_mem
if _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.py
index 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[str
continue
role = 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
index 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, the
Windows 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 wheels
that set props.name="Radeon 8060S Graphics" but no gcnArchName, applying the
wrong 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 re
from pathlib import Path
from types import SimpleNamespace
@@ -286,7 +290,8 @@ class TestMemFractionSelection:
the guard calls the helper, sizes against the allocator's own total, and tags the
log 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 no
denominator 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 source
assert "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 source
diff --git a/studio/backend/utils/datasets/format_conversion.py b/studio/backend/utils/datasets/format_conversion.py
index 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.py
new file mode 100644
index 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.py
index 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_MAPPING
from transformers import set_seed as transformers_set_seed
from peft import LoraConfig, TaskType, get_peft_model as _get_peft_model
from 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, sys
import types
diff --git a/unsloth/models/sentence_transformer.py b/unsloth/models/sentence_transformer.py
index 3c14c681940..1460f39843c 100644
--- a/unsloth/models/sentence_transformer.py
+++ b/unsloth/models/sentence_transformer.py
@@ -42,7 +42,27 @@ import re
from transformers import AutoModel, AutoConfig
import tempfile
from 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 contextlib
import shutil
diff --git a/unsloth/models/vision.py b/unsloth/models/vision.py
index 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_distributed
from unsloth_zoo.gradient_checkpointing import (
unpatch_unsloth_gradient_checkpointing,
diff --git a/unsloth/save.py b/unsloth/save.py
index 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])