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
MLX: build trl.__all__ on first read instead of importing every TRL export at import (#15561)
Daniel Han80fcd255606c
diff --git a/tests/test_mlx_trl_lazy_all.py b/tests/test_mlx_trl_lazy_all.pynew file mode 100644index 00000000000..8609bc8128f--- /dev/null+++ b/tests/test_mlx_trl_lazy_all.py@@ -0,0 +1,223 @@+# SPDX-License-Identifier: AGPL-3.0-only+# Copyright 2023-present Daniel Han-Chen & the Unsloth team. All rights reserved.+#+# This program is free software: you can redistribute it and/or modify+# it under the terms of the GNU Affero General Public License as published by+# the Free Software Foundation, either version 3 of the License, or+# (at your option) any later version.+#+# This program is distributed in the hope that it will be useful,+# but WITHOUT ANY WARRANTY; without even the implied warranty of+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the+# GNU Affero General Public License for more details.+#+# You should have received a copy of the GNU Affero General Public License+# along with this program. If not, see <https://www.gnu.org/licenses/>.+"""On MLX, trl.__all__ is filtered on first read: resolving every name at import pulled torch in."""++import importlib.util+import pathlib+import platform+import subprocess+import sys+import types++import pytest++_PATH = pathlib.Path(__file__).resolve().parents[1] / "unsloth" / "_mlx_trl_all.py"+++def lazy_all():+ spec = importlib.util.spec_from_file_location("_unsloth_mlx_trl_all_under_test", _PATH)+ module = importlib.util.module_from_spec(spec)+ spec.loader.exec_module(module)+ return module+++def _filter(trl, names):+ """Same contract as unsloth's _safe_mlx_trl_star_exports."""+ kept = []+ for name in names:+ try:+ getattr(trl, name)+ except Exception:+ continue+ kept.append(name)+ for name in ("SFTConfig", "SFTTrainer"):+ if name not in kept:+ kept.append(name)+ return kept+++class _LazyLike(types.ModuleType):+ """trl's _LazyModule shape: a class-level __getattr__ importing on demand."""++ def __init__(self, name, lazy):+ super().__init__(name)+ self._lazy = lazy+ self.resolved = []+ self.__all__ = list(lazy)++ def __getattr__(self, name):+ if name not in self._lazy:+ raise AttributeError(name)+ self.resolved.append(name)+ value = self._lazy[name]()+ setattr(self, name, value)+ return value+++def _broken():+ raise RuntimeError("optional dependency missing")+++def test_nothing_resolves_until_all_is_read(lazy_all, monkeypatch):+ trl = _LazyLike("trl", {"DataCollator": object, "Broken": _broken, "GRPOTrainer": object})+ trl.SFTTrainer = trl.SFTConfig = object+ lazy_all.install_lazy_trl_all(trl, _filter)+ assert trl.resolved == []+ assert lazy_all.raw_trl_all(trl) == ["DataCollator", "Broken", "GRPOTrainer"]+ assert trl.resolved == []+ assert trl.__all__ == ["DataCollator", "GRPOTrainer", "SFTConfig", "SFTTrainer"]+ assert sorted(trl.resolved) == ["Broken", "DataCollator", "GRPOTrainer"]+ # Cached: a second read resolves nothing more.+ trl.resolved.clear()+ assert trl.__all__[-1] == "SFTTrainer" and trl.resolved == []+ monkeypatch.setitem(sys.modules, "trl", trl)+ namespace = {}+ exec("from trl import *", namespace)+ assert set(namespace) - {"__builtins__"} == {+ "DataCollator",+ "GRPOTrainer",+ "SFTConfig",+ "SFTTrainer",+ }+++def test_class_level_getattr_still_serves_other_names(lazy_all):+ trl = _LazyLike("trl", {"DataCollator": lambda: "collator"})+ lazy_all.install_lazy_trl_all(trl, _filter)+ assert trl.DataCollator == "collator"+ with pytest.raises(AttributeError):+ trl.missing_name+ assert "DataCollator" in dir(trl)+++def test_module_dict_getattr_is_chained(lazy_all):+ trl = types.ModuleType("trl")+ trl.ExistingExport = object()+ trl.__all__ = ["ExistingExport", "BrokenExport"]++ def _module_getattr(name):+ if name == "BrokenExport":+ raise RuntimeError("optional dependency missing")+ raise AttributeError(name)++ trl.__getattr__ = _module_getattr+ lazy_all.install_lazy_trl_all(trl, _filter)+ with pytest.raises(RuntimeError):+ trl.BrokenExport+ assert trl.__all__ == ["ExistingExport", "SFTConfig", "SFTTrainer"]+++def test_reinstall_keeps_the_original_names_and_getattr(lazy_all):+ trl = types.ModuleType("trl")+ trl.__all__ = ["A"]+ trl.A = 1+ original = lambda name: (_ for _ in ()).throw(AttributeError(name)) # noqa: E731+ trl.__getattr__ = original+ lazy_all.install_lazy_trl_all(trl, _filter)+ assert trl.__all__ == ["A", "SFTConfig", "SFTTrainer"]+ lazy_all.install_lazy_trl_all(trl, _filter)+ assert lazy_all.raw_trl_all(trl) == ["A"]+ assert trl.__getattr__._unsloth_previous is original+ assert trl.__all__ == ["A", "SFTConfig", "SFTTrainer"]+++def test_module_without_all(lazy_all):+ trl = types.ModuleType("trl")+ lazy_all.install_lazy_trl_all(trl, _filter)+ assert trl.__all__ == ["SFTConfig", "SFTTrainer"]+++def test_a_reentrant_all_read_during_filtering_sees_the_raw_names(lazy_all):+ install_lazy_trl_all = lazy_all.install_lazy_trl_all++ trl = types.ModuleType("fake_trl_reentrant")+ trl.__all__ = ["A", "B"]+ seen = []++ def filter_exports(module, names):+ # An export whose import reads trl.__all__ again mid-filter.+ seen.append(list(module.__all__))+ return [n for n in names if n != "B"]++ install_lazy_trl_all(trl, filter_exports)+ assert trl.__all__ == ["A"]+ assert seen == [["A", "B"]]+ assert trl.__all__ == ["A"]+++class _LazyDirLike(_LazyLike):+ """trl's _LazyModule.__dir__: the namespace listing, then any __all__ name not in it."""++ def __dir__(self):+ result = super().__dir__()+ for attr in self.__all__:+ if attr not in result:+ result.append(attr)+ return result++[email protected]("dir_first", [True, False])+def test_dir_matches_the_eager_filter(lazy_all, dir_first):+ def make():+ trl = _LazyDirLike(+ "trl", {"DataCollator": object, "Broken": _broken, "GRPOTrainer": object}+ )+ trl.SFTTrainer = trl.SFTConfig = object+ return trl++ eager = make()+ eager.__all__ = _filter(eager, list(eager.__all__))+ lazy = make()+ lazy_all.install_lazy_trl_all(lazy, _filter)+ if dir_first:+ listed = dir(lazy)+ assert lazy.__all__ == eager.__all__+ else:+ assert lazy.__all__ == eager.__all__+ listed = dir(lazy)+ assert listed == dir(eager)+ # Built: no hook or bookkeeping name is left in trl's namespace.+ assert not {"__getattr__", "__dir__", "_unsloth_mlx_trl_all"} & set(vars(lazy))+++ platform.system() != "Darwin"+ or platform.machine() != "arm64"+ or importlib.util.find_spec("mlx") is None+ or importlib.util.find_spec("trl") is None,+ reason = "the real MLX import path needs Apple Silicon with mlx and trl",+)+def test_real_mlx_import_leaves_trl_all_unbuilt():+ probe = (+ "import sys, unsloth, trl\n"+ "assert unsloth.DEVICE_TYPE == 'mlx', unsloth.DEVICE_TYPE\n"+ "assert '__all__' not in vars(trl), 'import unsloth filtered trl.__all__ eagerly'\n"+ "names = trl.__all__\n"+ "assert {'SFTConfig', 'SFTTrainer'} <= set(names), names\n"+ "ns = {}\n"+ "exec('from trl import *', ns)\n"+ "assert set(names) <= set(ns), set(names) - set(ns)\n"+ "assert ns['SFTTrainer'] is unsloth.UnslothTrainer\n"+ )+ result = subprocess.run(+ [sys.executable, "-c", probe],+ cwd = pathlib.Path(__file__).resolve().parents[1],+ capture_output = True,+ text = True,+ timeout = 600,+ )+ assert result.returncode == 0, result.stdout[-2000:] + result.stderr[-4000:]diff --git a/unsloth/__init__.py b/unsloth/__init__.pyindex 3dcc26c8f15..7b280779e3a 100644--- a/unsloth/__init__.py+++ b/unsloth/__init__.py@@ -1549,9 +1549,8 @@ if _IS_MLX:)return _train_on_responses_only(*args, **kwargs)- def _safe_mlx_trl_star_exports(_trl):+ def _safe_mlx_trl_star_exports(_trl, exports):"""Return importable TRL star exports plus the MLX SFT shims."""- exports = list(getattr(_trl, "__all__", ()))safe_exports = []for name in exports:try:@@ -1602,6 +1601,11 @@ if _IS_MLX:kwargs.setdefault("num_train_epochs", 3)super().__init__(*args, **kwargs)+ from ._mlx_trl_all import (+ install_lazy_trl_all as _install_lazy_trl_all,+ raw_trl_all as _raw_trl_all,+ )+def _install_mlx_trl_sft_shim():"""Install MLX-backed TRL SFT shims without replacing the TRL module."""_trl = _sys.modules.get("trl")@@ -1619,7 +1623,7 @@ if _IS_MLX:_trl.SFTTrainer = UnslothTrainer_trl.SFTConfig = _MLXSFTConfig# Names come from trl's __all__, never a getattr probe: that triggers trl's lazy import and pulls torch.- _trl_exports = set(getattr(_trl, "__all__", ()) or ())+ _trl_exports = set(_raw_trl_all(_trl))# Stub every non-SFT trl trainer so newer ones fail clearly too; take names from __all__ and never resolve them, since that pulls torch._unsupported = set(_MLX_UNSUPPORTED_TRL_TRAINERS) | {_n for _n in _trl_exports if _n.endswith("Trainer") and _n != "SFTTrainer"@@ -1630,7 +1634,8 @@ if _IS_MLX:continueif _name in _trl_exports or _current is not None:setattr(_trl, _name, _make_mlx_unsupported_trl_trainer(_name))- _trl.__all__ = _safe_mlx_trl_star_exports(_trl)+ # Filtered on first read of trl.__all__: resolving every name here imported all of trl (datasets, peft, ...).+ _install_lazy_trl_all(_trl, _safe_mlx_trl_star_exports)_trl.__UNSLOTH_MLX_COMPAT__ = Truedef _install_mlx_unsloth_trainer_shim():diff --git a/unsloth/_mlx_trl_all.py b/unsloth/_mlx_trl_all.pynew file mode 100644index 00000000000..df1c60f3de9--- /dev/null+++ b/unsloth/_mlx_trl_all.py@@ -0,0 +1,83 @@+# SPDX-License-Identifier: AGPL-3.0-only+# Copyright 2023-present Daniel Han-Chen & the Unsloth team. All rights reserved.+#+# This program is free software: you can redistribute it and/or modify+# it under the terms of the GNU Affero General Public License as published by+# the Free Software Foundation, either version 3 of the License, or+# (at your option) any later version.+#+# This program is distributed in the hope that it will be useful,+# but WITHOUT ANY WARRANTY; without even the implied warranty of+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the+# GNU Affero General Public License for more details.+#+# You should have received a copy of the GNU Affero General Public License+# along with this program. If not, see <https://www.gnu.org/licenses/>.++"""MLX `trl.__all__`, filtered on first read (PEP 562): filtering resolves every name, importing all of trl."""++import weakref++# Kept outside trl's namespace so dir(trl) gains no bookkeeping entry.+_RAW_ALL = weakref.WeakKeyDictionary()+++def raw_trl_all(trl):+ """trl's own export names, never resolving one."""+ if trl in _RAW_ALL:+ return list(_RAW_ALL[trl])+ return list(vars(trl).get("__all__", ()) or ())+++def install_lazy_trl_all(trl, filter_exports):+ """Serve `trl.__all__` as `filter_exports(trl, names)`, computed on first access."""+ namespace = vars(trl)+ _RAW_ALL[trl] = raw_trl_all(trl)+ namespace.pop("__all__", None)+ previous = namespace.get("__getattr__")+ previous = getattr(previous, "_unsloth_previous", previous)+ previous_dir = namespace.get("__dir__")+ previous_dir = getattr(previous_dir, "_unsloth_previous", previous_dir)++ building = []++ def _hand_back():+ # Leave the namespace exactly as the eager filter did, so dir(trl) is unchanged.+ for key, hook, prior in (+ ("__getattr__", __getattr__, previous),+ ("__dir__", __dir__, previous_dir),+ ):+ if namespace.get(key) is hook:+ if prior is None:+ del namespace[key]+ else:+ namespace[key] = prior++ def __getattr__(name):+ if name == "__all__":+ raw = raw_trl_all(trl)+ # Re-entrant read mid-filter gets the raw list, as with the eager filter.+ if building:+ return raw+ building.append(True)+ try:+ exports = filter_exports(trl, raw)+ finally:+ building.clear()+ namespace["__all__"] = exports+ _hand_back()+ return exports+ if previous is not None:+ return previous(name)+ # A class-level __getattr__ (trl's _LazyModule) still runs after this AttributeError.+ raise AttributeError(f"module {trl.__name__!r} has no attribute {name!r}")++ def __dir__():+ # ModuleType.__dir__ (under trl's _LazyModule.__dir__) lists the namespace: build first.+ getattr(trl, "__all__")+ return previous_dir() if previous_dir is not None else list(namespace)++ __getattr__._unsloth_previous = previous+ __dir__._unsloth_previous = previous_dir+ namespace["__getattr__"] = __getattr__+ namespace["__dir__"] = __dir__