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.

MLX: run DPO, ORPO, KTO, GRPO and CPO through trl, and stop blocking SFT arguments zoo honors (#16461)

Long Yixing88fe11eccb6d
diff --git a/tests/python/test_mlx_public_trainer_api.py b/tests/python/test_mlx_public_trainer_api.py
index 27d564b6146..fe74a774d75 100644
--- a/tests/python/test_mlx_public_trainer_api.py
+++ b/tests/python/test_mlx_public_trainer_api.py
@@ -389,13 +389,14 @@ def test_mlx_training_arguments_warn_on_meaningful_inert_kwargs():
"""Unsupported TrainingArguments knobs should not be silently ignored."""
unsloth = _import_mlx_unsloth()
- with pytest.warns(RuntimeWarning, match = "push_to_hub.*save_strategy"):
+ with pytest.warns(RuntimeWarning, match = "push_to_hub") as caught:
args = unsloth.UnslothTrainingArguments(
save_strategy = "steps",
push_to_hub = True,
padding_free = False,
)
+ assert "save_strategy" not in str(caught[0].message), "MLXTrainer honors save_strategy"
assert args.save_strategy == "steps"
assert args.push_to_hub is True
assert args.padding_free is False
@@ -405,14 +406,15 @@ def test_mlx_training_arguments_reject_unknown_kwargs():
"""Unknown SFTConfig flags should fail instead of becoming inert attributes."""
unsloth = _import_mlx_unsloth()
- with pytest.raises(NotImplementedError, match = "assistant_only_loss"):
- unsloth.UnslothTrainingArguments(assistant_only_loss = True)
+ with pytest.raises(NotImplementedError, match = "no_such_flag"):
+ unsloth.UnslothTrainingArguments(no_such_flag = True)
+ assert unsloth.UnslothTrainingArguments(assistant_only_loss = True).assistant_only_loss is True
completion_args = unsloth.UnslothTrainingArguments(completion_only_loss = True)
assert completion_args.completion_only_loss is True
-def test_mlx_training_arguments_reject_unsupported_object_flags():
+def test_mlx_training_arguments_keep_object_flags():
"""Object-style SFTConfig flags should not be silently dropped."""
unsloth = _import_mlx_unsloth()
@@ -420,8 +422,7 @@ def test_mlx_training_arguments_reject_unsupported_object_flags():
max_steps = 1
assistant_only_loss = True
- with pytest.raises(NotImplementedError, match = "assistant_only_loss"):
- unsloth._coerce_mlx_training_args(ArgsObject())
+ assert unsloth._coerce_mlx_training_args(ArgsObject()).assistant_only_loss is True
class CompletionArgsObject:
max_steps = 1
@@ -460,8 +461,7 @@ def test_mlx_training_arguments_normalize_optim_and_object_aliases():
warmup_ratio = 0.1
warmup_steps = 0
- with pytest.warns(RuntimeWarning, match = "save_strategy"):
- args = unsloth._coerce_mlx_training_args(ArgsObject())
+ args = unsloth._coerce_mlx_training_args(ArgsObject())
assert args.optim == "adamw_8bit"
assert args.eval_steps == 0
@@ -480,7 +480,7 @@ def test_mlx_training_arguments_accept_supported_notebook_kwargs():
with pytest.warns(
RuntimeWarning,
- match = "bf16.*dataset_kwargs.*gradient_checkpointing_kwargs.*save_strategy",
+ match = "bf16.*dataset_kwargs.*gradient_checkpointing_kwargs",
):
args = unsloth.UnslothTrainingArguments(
bf16 = True,
@@ -540,11 +540,10 @@ def test_mlx_training_arguments_honor_direct_no_save_strategy():
"""Direct kwargs should map save_strategy=no to save_steps=0."""
unsloth = _import_mlx_unsloth()
- with pytest.warns(RuntimeWarning, match = "save_strategy"):
- args = unsloth.UnslothTrainingArguments(
- save_strategy = "no",
- save_steps = 500,
- )
+ args = unsloth.UnslothTrainingArguments(
+ save_strategy = "no",
+ save_steps = 500,
+ )
assert args.save_steps == 0
@@ -942,20 +941,20 @@ def test_mlx_trainer_rejects_custom_data_collator():
)
-def test_mlx_trainer_rejects_text_completion_only_loss():
- """Text MLX training should not silently ignore completion_only_loss=True."""
+def test_mlx_trainer_allows_text_completion_only_loss():
unsloth = _import_mlx_unsloth()
- with pytest.raises(NotImplementedError, match = "completion_only_loss=True"):
- unsloth.UnslothTrainer(
- model = _DummyModel(),
- tokenizer = None,
- train_dataset = [],
- args = unsloth.UnslothTrainingArguments(
- max_steps = 1,
- completion_only_loss = True,
- ),
- )
+ trainer = unsloth.UnslothTrainer(
+ model = _DummyModel(),
+ tokenizer = None,
+ train_dataset = [],
+ args = unsloth.UnslothTrainingArguments(
+ max_steps = 1,
+ completion_only_loss = True,
+ ),
+ )
+
+ assert trainer.args.completion_only_loss is True
def test_mlx_trainer_allows_vlm_completion_only_loss():
@@ -1156,9 +1155,6 @@ def test_mlx_trl_star_import_exports_public_shims():
def test_mlx_rl_trainers_stub_with_clear_error(monkeypatch):
- """GRPO/DPO/ORPO trainers have no MLX path, so the shim retargets the ones trl
- exposes to a clear NotImplementedError instead of a confusing CUDA crash, and
- never invents trainers trl does not have."""
unsloth = _import_mlx_unsloth()
trl = types.ModuleType("trl")
trl.__path__ = ["real-trainer-package"]
@@ -1167,21 +1163,20 @@ def test_mlx_rl_trainers_stub_with_clear_error(monkeypatch):
def __init__(self, *args, **kwargs):
raise AssertionError("the real torch/CUDA trainer must not run on MLX")
- trl.GRPOTrainer = _RealTrainer
- trl.DPOTrainer = _RealTrainer
+ trl.PPOTrainer = _RealTrainer
monkeypatch.setitem(sys.modules, "trl", trl)
unsloth._install_mlx_trl_sft_shim()
- for name in ("GRPOTrainer", "DPOTrainer"):
+ for name in ("PPOTrainer",):
assert getattr(trl, name) is not _RealTrainer
with pytest.raises(NotImplementedError) as exc:
getattr(trl, name)(model = None, args = None)
assert "MLX" in str(exc.value) and name in str(exc.value)
- assert not hasattr(trl, "PPOTrainer")
- stub = trl.GRPOTrainer
+ assert not hasattr(trl, "RewardTrainer")
+ stub = trl.PPOTrainer
unsloth._install_mlx_trl_sft_shim()
- assert trl.GRPOTrainer is stub
+ assert trl.PPOTrainer is stub
def test_mlx_rl_trainer_stub_is_lazy_import_safe(monkeypatch):
@@ -1189,7 +1184,7 @@ def test_mlx_rl_trainer_stub_is_lazy_import_safe(monkeypatch):
unsloth = _import_mlx_unsloth()
trl = types.ModuleType("trl")
trl.__path__ = ["real-trainer-package"]
- trl.__all__ = ["SFTTrainer", "SFTConfig", "GRPOTrainer", "DPOTrainer"]
+ trl.__all__ = ["SFTTrainer", "SFTConfig", "RLOOTrainer", "GKDTrainer"]
resolved = []
def _lazy_getattr(name):
@@ -1202,7 +1197,7 @@ def test_mlx_rl_trainer_stub_is_lazy_import_safe(monkeypatch):
unsloth._install_mlx_trl_sft_shim()
assert resolved == []
- for name in ("GRPOTrainer", "DPOTrainer"):
+ for name in ("RLOOTrainer", "GKDTrainer"):
with pytest.raises(NotImplementedError):
getattr(trl, name)(model = None)
diff --git a/tests/test_mlx_trl_lazy_all.py b/tests/test_mlx_trl_lazy_all.py
index 8609bc8128f..e267a91a159 100644
--- a/tests/test_mlx_trl_lazy_all.py
+++ b/tests/test_mlx_trl_lazy_all.py
@@ -15,7 +15,9 @@
# 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.metadata
import importlib.util
+import os
import pathlib
import platform
import subprocess
@@ -194,13 +196,17 @@ def test_dir_matches_the_eager_filter(lazy_all, dir_first):
assert not {"__getattr__", "__dir__", "_unsloth_mlx_trl_all"} & set(vars(lazy))
+_needs_real_mlx = pytest.mark.skipif(
platform.system() != "Darwin"
or platform.machine() != "arm64"
+ or os.environ.get("UNSLOTH_FORCE_GPU_PATH", "0") == "1"
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",
)
+
+
+@_needs_real_mlx
def test_real_mlx_import_leaves_trl_all_unbuilt():
probe = (
"import sys, unsloth, trl\n"
@@ -221,3 +227,392 @@ def test_real_mlx_import_leaves_trl_all_unbuilt():
timeout = 600,
)
assert result.returncode == 0, result.stdout[-2000:] + result.stderr[-4000:]
+
+
+_SHIM_PROBE_PREAMBLE = """
+import pickle, unsloth, trl
+import mlx.nn as nn
+from unsloth_zoo.mlx import trainer as zoo
+assert unsloth.DEVICE_TYPE == "mlx"
+def refused(fn, *needles, kind=NotImplementedError):
+ try:
+ fn()
+ except kind as exc:
+ assert all(n in str(exc) for n in needles), str(exc)
+ else:
+ raise AssertionError(f"not refused: {needles}")
+model = nn.Linear(1, 1)
+model.max_seq_length = 96
+tok = object()
+"""
+
+
+def _run_shim_probe(body, before_unsloth = ""):
+ result = subprocess.run(
+ [sys.executable, "-c", before_unsloth + _SHIM_PROBE_PREAMBLE + body],
+ cwd = pathlib.Path(__file__).resolve().parents[1],
+ capture_output = True,
+ text = True,
+ timeout = 600,
+ )
+ assert result.returncode == 0, result.stdout[-2000:] + result.stderr[-4000:]
+
+
+@_needs_real_mlx
+def test_trl_trainers_zoo_implements_are_mapped():
+ _run_shim_probe("""
+for stem in ("DPO", "ORPO", "KTO", "GRPO", "CPO"):
+ trainer, config = getattr(trl, stem + "Trainer"), getattr(trl, stem + "Config")
+ assert issubclass(trainer, getattr(zoo, f"MLX{stem}Trainer")), stem
+ assert issubclass(config, getattr(zoo, f"MLX{stem}Config")), stem
+ cfg = config(output_dir="o", optim="adamw_torch")
+ assert cfg.learning_rate == 1e-6 and cfg.per_device_train_batch_size == 8, stem
+ assert cfg.gradient_accumulation_steps == 1 and cfg.warmup_steps == 0, stem
+ assert cfg.weight_decay == 0.0 and cfg.num_train_epochs == 3, stem
+ assert cfg.optim == "adamw" and cfg.save_steps == 500, stem
+ assert config(max_steps=1, save_strategy="no").save_steps == 0, stem
+ assert config(learning_rate=0.5, max_steps=2).learning_rate == 0.5, stem
+ assert type(pickle.loads(pickle.dumps(cfg))) is config, stem
+for name in ("PatchDPOTrainer", "PatchKTOTrainer", "PatchFastRL"):
+ assert getattr(unsloth, name)() is None
+
+# TRL's own positional order, ref_model and a trainer-level config field.
+cfg = trl.DPOConfig(max_steps=1, max_length=512, max_prompt_length=64)
+t = trl.DPOTrainer(model, None, cfg, None, [], None, tok, beta=0.25)
+assert t.args.beta == 0.25 and cfg.beta == 0.1
+assert t.args.max_length == 512, t.args.max_length
+assert cfg.max_seq_length == zoo.MLXTrainingConfig.max_seq_length, "max_length is not the SFT alias here"
+assert t.args.max_seq_length == 96, "follows the loaded model"
+c = trl.DPOTrainer(model=model, args=cfg, train_dataset=[], processing_class=tok, max_seq_length=2048)
+assert (c.args.max_seq_length, c.args.max_length) == (2048, 512), "trainer context length keeps TRL's budget"
+long_model = nn.Linear(1, 1)
+long_model.max_seq_length = 4096
+b = trl.DPOTrainer(model=long_model, args=trl.DPOConfig(max_steps=1), train_dataset=[], max_length=48)
+assert (b.args.max_seq_length, b.args.max_length) == (4096, 48), "trainer budget leaves the context length implicit"
+import dataclasses
+swept = trl.DPOTrainer(model=long_model, args=dataclasses.replace(trl.DPOConfig(max_length=4096), beta=0.2), train_dataset=[]).args
+assert (swept.max_seq_length, swept.dataset_order, swept.beta) == (4096, "torch_randperm", 0.2), "a replaced config stays implicit"
+assigned = trl.DPOConfig(max_length=4096)
+assigned.max_seq_length = zoo.MLXTrainingConfig.max_seq_length
+assert trl.DPOTrainer(model=long_model, args=assigned, train_dataset=[]).args.max_seq_length == zoo.MLXTrainingConfig.max_seq_length
+ordered = trl.DPOConfig()
+ordered.dataset_order = "default"
+for overrides in ({}, {"seed": 9}):
+ assert trl.DPOTrainer(model=model, args=ordered, train_dataset=[], **overrides).args.dataset_order == "default", overrides
+plain = trl.DPOTrainer(model=model, args=zoo.MLXTrainingConfig(max_steps=1), train_dataset=[]).args
+assert (plain.max_grad_norm, plain.max_grad_leaf_norm) == (0.0, 1.0), "zoo's leaf clip default survives conversion"
+assert trl.DPOTrainer(model=model, args=trl.SFTConfig(max_steps=1), train_dataset=[]).args.max_grad_norm == 1.0
+assert t.args.dataset_order == "torch_randperm" and t.args.max_grad_norm == 1.0
+assert t.args.append_eos is True, "TRL appends EOS to completions"
+assert t.tokenizer is tok and t.ref_model is None
+ref = object()
+assert trl.DPOTrainer(model=model, ref_model=ref, args=cfg, train_dataset=[], processing_class=tok).ref_model is ref
+
+k = trl.KTOTrainer(model, ref, trl.KTOConfig(max_steps=1), [], None, tok, model_adapter_name="a")
+assert k.ref_model is ref and k.model_adapter_name == "a"
+assert k.args.dataset_order == "default", "each row's KL pair is its batch neighbor"
+o = trl.ORPOTrainer(model, trl.ORPOConfig(max_steps=1), None, [], None, tok)
+assert o.args.dataset_order == "torch_randperm"
+assert isinstance(trl.CPOTrainer(model, trl.CPOConfig(max_steps=1), None, [], None, tok).args, zoo.MLXCPOConfig)
+
+reward = lambda completions, **kw: [0.0] * len(completions)
+g_cfg = trl.GRPOConfig(max_steps=1, num_generations=2, per_device_train_batch_size=2, max_completion_length=8)
+g = trl.GRPOTrainer(model, [reward], g_cfg, [], None, tok)
+assert g.reward_funcs == [reward] and g.args.dataset_order == "default"
+refused(lambda: trl.GRPOTrainer(model, [reward], g_cfg, [], None, tok, beta=0.5), "GRPOConfig")
+
+# Trainer-level overrides are normalized like config arguments.
+o_cfg = trl.DPOConfig(max_steps=100, warmup_ratio=0.1)
+o = trl.DPOTrainer(model=model, args=o_cfg, train_dataset=[], loraplus_lr_ratio=16, warmup_steps=30, optim="adamw_torch")
+assert o.args.lora_plus_ratio == 16 and o.args.optim == "adamw"
+assert o.args.warmup_steps == 30 and o.args._unsloth_mlx_warmup_steps_explicit
+for trainer, cfg_ in ((trl.DPOTrainer, o_cfg), (trl.SFTTrainer, trl.SFTConfig(max_steps=1))):
+ for kw in ({"lora_plus_ratio": 8, "loraplus_lr_ratio": 16}, {"loraplus_lr_ratio": 16, "lora_plus_ratio": 8}):
+ assert trainer(model=model, args=cfg_, train_dataset=[], **kw).args.lora_plus_ratio == 8, kw
+r = trl.DPOTrainer(model=model, args=o_cfg, train_dataset=[], max_steps=200)
+assert r.args.warmup_steps == 20, r.args.warmup_steps
+
+# Another config type carries its fields over, zoo's own config passes untouched.
+assert trl.DPOTrainer(model=model, args=trl.SFTConfig(max_steps=7, learning_rate=0.1), train_dataset=[], processing_class=tok).args.learning_rate == 0.1
+raw = zoo.MLXDPOConfig(max_steps=1, beta=0.3)
+assert trl.DPOTrainer(model=model, args=raw, train_dataset=[], processing_class=tok).args.beta == 0.3
+assert trl.DPOTrainer(model=model, args=raw, train_dataset=[]).args.max_seq_length == 96, "default follows the model"
+for length, expected in ((64, 64), (512, 96)):
+ raw = zoo.MLXDPOConfig(max_steps=1, max_seq_length=length)
+ assert trl.DPOTrainer(model=model, args=raw, train_dataset=[]).args.max_seq_length == expected
+""")
+
+
+@_needs_real_mlx
+def test_trl_mappings_refuse_what_zoo_lacks():
+ _run_shim_probe("""
+# A TRL field at its inert value is accepted, any other value is refused by name.
+trl.DPOConfig(rpo_alpha=None, label_pad_token_id=-100, use_weighting=False)
+refused(lambda: trl.DPOConfig(rpo_alpha=0.1), "rpo_alpha")
+refused(lambda: trl.DPOConfig(use_weighting=True), "use_weighting")
+refused(lambda: trl.DPOConfig(no_such_field=1), "no_such_field")
+refused(
+ lambda: trl.DPOTrainer(model=model, args=trl.DPOConfig(max_steps=1), train_dataset=[], compute_metrics=print),
+ "DPOTrainer", "compute_metrics",
+)
+refused(lambda: trl.ORPOTrainer(model=model, train_dataset=[], peft_config=object()), "ORPOTrainer", "peft_config")
+refused(lambda: trl.DPOTrainer(model="org/repo", train_dataset=[]), "model")
+refused(lambda: trl.DPOTrainer(model=model, ref_model="org/repo", train_dataset=[]), "ref_model")
+for name in ("GKDTrainer", "PPOTrainer", "RewardTrainer"):
+ trainer = getattr(trl, name, None)
+ if trainer is None:
+ continue
+ assert getattr(trainer, "_unsloth_mlx_unsupported", False), name
+ refused(trainer, name, "DPO", "GRPO", "SFT")
+""")
+
+
+@_needs_real_mlx
+def test_trl_configs_match_trl_semantics_and_stay_the_callers():
+ _run_shim_probe("""
+cfg = trl.DPOConfig(output_dir="o", max_seq_length=4096)
+first = trl.DPOTrainer(model=model, args=cfg, train_dataset=[])
+assert first.args.max_seq_length == 96 and cfg.max_seq_length == 4096
+longer = nn.Linear(1, 1)
+longer.max_seq_length = 2048
+assert trl.DPOTrainer(model=longer, args=cfg, train_dataset=[]).args.max_seq_length == 2048
+assert trl.DPOTrainer(model=model, evaluation_strategy="epoch", train_dataset=[]).args.eval_strategy == "epoch"
+assert trl.SFTConfig(output_dir="o", eval_strategy="steps", logging_steps=7).eval_steps == 7
+assert trl.SFTConfig(output_dir="o", eval_strategy="steps", eval_steps=3, logging_steps=7).eval_steps == 3
+assert trl.SFTConfig(output_dir="o", eval_strategy="no", logging_steps=7).eval_steps == 0
+assert trl.DPOConfig(output_dir="o", f_alpha_divergence_coef=0.5).output_dir == "o"
+assert trl.DPOConfig(output_dir="o", use_liger_loss=None).output_dir == "o"
+refused(lambda: trl.DPOConfig(output_dir="o", use_liger_loss=True), "use_liger_loss")
+refused(lambda: trl.DPOConfig(output_dir="o", f_divergence_type="alpha_divergence"), "f_divergence_type")
+""")
+
+
+@_needs_real_mlx
+def test_trl_config_defaults_match_trl():
+ _run_shim_probe("""
+assert trl.SFTConfig(output_dir="o", eval_strategy="steps").eval_steps == 10
+assert trl.DPOConfig(output_dir="o", eval_strategy="steps").eval_steps == 10
+assert trl.DPOConfig(output_dir="o", eval_strategy="steps", logging_steps=7).eval_steps == 7
+assert trl.DPOConfig(output_dir="o", eval_steps=1).eval_strategy == "no"
+assert trl.DPOConfig(output_dir="o").logging_steps == 10
+assert unsloth.UnslothTrainingArguments(output_dir="o", eval_strategy="steps").eval_steps == 10
+assert trl.DPOTrainer(model=model, args=trl.DPOConfig(output_dir="o"), train_dataset=[], eval_strategy="steps").args.eval_steps == 10
+sft = trl.SFTTrainer(model=model, args=trl.SFTConfig(output_dir="o"), train_dataset=[], eval_strategy="steps")
+assert sft.args.eval_steps == 10 and sft.args.logging_steps == 1
+assert trl.SFTTrainer(model=model, args=trl.SFTConfig(output_dir="o", logging_steps=1), train_dataset=[], eval_strategy="steps").args.eval_steps == 1
+
+from packaging.version import Version
+modern = Version(trl.__version__) >= Version("0.29.0")
+assert trl.DPOConfig(output_dir="o").truncation_mode == ("keep_start" if modern else "keep_end")
+assert trl.DPOConfig(output_dir="o", truncation_mode="keep_end").truncation_mode == "keep_end"
+assert trl.ORPOConfig(output_dir="o").truncation_mode == "keep_end"
+assert trl.DPOConfig(output_dir="o").max_prompt_length == (None if modern else 512)
+assert trl.DPOConfig(output_dir="o", max_prompt_length=64).max_prompt_length == 64
+grpo = trl.GRPOConfig(output_dir="o", num_generations=2, per_device_train_batch_size=2)
+assert grpo.max_completion_length == (512 if Version(trl.__version__) >= Version("1.10.0") else 256)
+
+over = trl.DPOTrainer(model=model, args=trl.DPOConfig(output_dir="o"), train_dataset=[], max_grad_norm=0, dataset_order="default").args
+assert (over.max_grad_norm, over.dataset_order) == (0, "default")
+warm = trl.SFTConfig(output_dir="o", num_train_epochs=1, warmup_steps=0, warmup_ratio=0.1)
+assert trl.SFTTrainer(model=model, args=warm, train_dataset=[], warmup_ratio=0.0).args.warmup_steps == 0
+
+edited = trl.SFTConfig(output_dir="o", max_steps=100, warmup_ratio=0.1)
+edited.warmup_steps, edited.logging_steps = 30, 7
+rebuilt = trl.SFTTrainer(model=model, args=edited, train_dataset=[], learning_rate=1e-4).args
+assert (rebuilt.warmup_steps, rebuilt.logging_steps) == (30, 7)
+untouched = trl.SFTConfig(output_dir="o", max_steps=100, warmup_ratio=0.1)
+assert trl.SFTTrainer(model=model, args=untouched, train_dataset=[], max_steps=200).args.warmup_steps == 20
+""")
+
+
+@_needs_real_mlx
+def test_trainers_fall_back_to_the_models_tokenizer():
+ _run_shim_probe("""
+model._tokenizer = tok
+for trainer in (trl.DPOTrainer(model=model, train_dataset=[]), trl.SFTTrainer(model=model, train_dataset=[])):
+ assert trainer.tokenizer is tok and trainer.processing_class is tok
+other = object()
+assert trl.DPOTrainer(model=model, train_dataset=[], processing_class=other).tokenizer is other
+assert trl.SFTTrainer(model=model, train_dataset=[], data_collator=unsloth.UnslothVisionDataCollator(model, other)).processing_class is other
+""")
+
+
+@_needs_real_mlx
+def test_hf_argument_parser_builds_the_same_trl_configs():
+ pytest.importorskip("transformers")
+ _run_shim_probe("""
+import dataclasses
+from transformers import HfArgumentParser
+
+def parsed(config, *flags):
+ return HfArgumentParser(config).parse_args_into_dataclasses(args=["--output_dir", "o", *flags])[0]
+
+for stem, extra in (("DPO", {}), ("ORPO", {}), ("KTO", {}), ("CPO", {}), ("GRPO", {"num_generations": 2, "per_device_train_batch_size": 2})):
+ config = getattr(trl, stem + "Config")
+ flags = [text for key, value in extra.items() for text in ("--" + key, str(value))]
+ built, direct = parsed(config, *flags), config(output_dir="o", **extra)
+ for field in dataclasses.fields(config):
+ assert getattr(built, field.name) == getattr(direct, field.name), (stem, field.name)
+ for name, value in vars(direct).items():
+ if name.startswith("_unsloth"):
+ assert getattr(built, name) == value, (stem, name)
+
+explicit = parsed(trl.DPOConfig, "--learning_rate", "0.0002", "--max_steps", "60", "--loss_type", "ipo")
+assert (explicit.learning_rate, explicit.max_steps, explicit.loss_type) == (0.0002, 60, ["ipo"])
+assert parsed(trl.DPOConfig, "--max_grad_norm", "0.5")._unsloth_mlx_grad_clip_explicit is True
+assert parsed(trl.DPOConfig, "--num_train_epochs", "0.5").num_train_epochs == 0.5
+
+long_model = nn.Linear(1, 1)
+long_model.max_seq_length = 4096
+args = parsed(trl.DPOConfig, "--max_seq_length", "2048", "--dataset_order", "default")
+explicit = trl.DPOTrainer(model=long_model, args=args, train_dataset=[]).args
+assert (explicit.max_seq_length, explicit.dataset_order) == (2048, "default")
+unset = trl.DPOTrainer(model=long_model, args=parsed(trl.DPOConfig), train_dataset=[]).args
+assert (unset.max_seq_length, unset.dataset_order) == (4096, "torch_randperm")
+assert trl.DPOConfig(output_dir="o").max_seq_length == zoo.MLXTrainingConfig.max_seq_length
+
+off = parsed(trl.DPOConfig, "--max_grad_norm", "0")
+assert trl.DPOTrainer(model=model, args=off, train_dataset=[]).args.max_grad_norm == 0
+kept = dataclasses.replace(trl.DPOConfig(output_dir="o", max_grad_norm=0.0), beta=0.3)
+assert trl.DPOTrainer(model=model, args=kept, train_dataset=[]).args.max_grad_norm == 0
+assert trl.DPOConfig(output_dir="o", max_grad_value=0.0).max_grad_norm == 0
+assert trl.DPOConfig(output_dir="o", max_grad_value=None).max_grad_norm == 1.0
+assert zoo._resolve_mlx_grad_clipping(trl.DPOConfig(output_dir="o", max_grad_value=None))[-1] == "global_norm"
+assert zoo._resolve_mlx_grad_clipping(trl.DPOConfig(output_dir="o", max_grad_value=0.0))[-1] == "none"
+for stem in ("DPO", "ORPO", "KTO", "CPO", "GRPO"):
+ extra = {"num_generations": 2, "per_device_train_batch_size": 2} if stem == "GRPO" else {}
+ extra = {**extra, "max_completion_length": 8} if stem == "GRPO" else extra
+ trainer_extra = {"reward_funcs": [print], "processing_class": tok} if stem == "GRPO" else {}
+ config, trainer = getattr(trl, stem + "Config"), getattr(trl, stem + "Trainer")
+ for norm in (0, -1, None):
+ built = trainer(model=model, args=config(output_dir="o", max_grad_norm=norm, **extra), train_dataset=[], **trainer_extra)
+ assert zoo._resolve_mlx_grad_clipping(built.args)[-1] == "none", stem
+for key in ("max_grad_value", "max_grad_leaf_norm"):
+ t = trl.DPOTrainer(model=model, args=trl.DPOConfig(output_dir="o"), train_dataset=[], **{key: 0.0})
+ assert zoo._resolve_mlx_grad_clipping(t.args)[-1] == "none", key
+long_model = nn.Linear(1, 1)
+long_model.max_seq_length = 4096
+for name, value in (
+ ("max_grad_norm", 0.0), ("max_grad_norm", -1), ("max_grad_norm", None), ("max_grad_norm", 0.5),
+ ("max_grad_value", 0.0), ("max_grad_value", 0.5), ("max_grad_leaf_norm", 0.0), ("max_grad_leaf_norm", 0.5),
+ ("max_seq_length", 128), ("warmup_steps", 30), ("logging_steps", 7),
+):
+ for overrides in ({}, {"seed": 9}):
+ built = trl.DPOTrainer(model=long_model, args=trl.DPOConfig(output_dir="o", **{name: value}), train_dataset=[], **overrides).args
+ late = trl.DPOConfig(output_dir="o")
+ setattr(late, name, value)
+ assigned = trl.DPOTrainer(model=long_model, args=late, train_dataset=[], **overrides).args
+ assert getattr(built, name) == getattr(assigned, name) == value, (name, value, overrides)
+ assert zoo._resolve_mlx_grad_clipping(built) == zoo._resolve_mlx_grad_clipping(assigned), (name, value, overrides)
+ assert built.max_seq_length == assigned.max_seq_length, (name, value, overrides)
+
+reused = trl.DPOTrainer(model=long_model, args=trl.DPOConfig(output_dir="o"), train_dataset=[]).args
+assert trl.DPOTrainer(model=model, args=reused, train_dataset=[]).args.max_seq_length == 96
+native = zoo.MLXDPOConfig(max_steps=1)
+for overrides in ({}, {"seed": native.seed}):
+ args = trl.DPOTrainer(model=model, args=native, train_dataset=[], **overrides).args
+ assert zoo._resolve_mlx_grad_clipping(args)[-1] == "leaf_norm", overrides
+edited_norm = trl.DPOConfig(output_dir="o")
+edited_norm.max_grad_norm = 0.5
+assert trl.DPOTrainer(model=model, args=edited_norm, train_dataset=[], seed=9).args.max_grad_norm == 0.5
+assert trl.DPOTrainer(model=model, args=trl.DPOConfig(output_dir="o"), train_dataset=[], seed=9).args.max_grad_norm == 1.0
+assert parsed(trl.GRPOConfig, "--num_generations", "2", "--per_device_train_batch_size", "2", "--scale_rewards", "batch").scale_rewards == "batch"
+assert pickle.loads(pickle.dumps(parsed(trl.DPOConfig))).learning_rate == 1e-6
+""")
+
+
+@_needs_real_mlx
+def test_sft_shim_forwards_what_zoo_honors():
+ _run_shim_probe("""
+import warnings
+with warnings.catch_warnings():
+ warnings.simplefilter("error", RuntimeWarning)
+ args = trl.SFTConfig(
+ max_steps=1,
+ assistant_only_loss=True,
+ logging_first_step=True,
+ eval_delay=3,
+ include_num_input_tokens_seen="all",
+ eval_strategy="epoch",
+ save_strategy="epoch",
+ logging_strategy="epoch",
+ )
+assert args.assistant_only_loss is True and args.logging_first_step is True
+assert args.eval_delay == 3 and args.include_num_input_tokens_seen == "all"
+assert (args.eval_strategy, args.save_strategy, args.logging_strategy) == ("epoch",) * 3
+assert trl.SFTConfig(max_steps=1, evaluation_strategy="epoch").eval_strategy == "epoch"
+assert trl.SFTConfig(max_steps=1, completion_only_loss=False).completion_only_loss is False
+
+# Text models train on completions: zoo masks prompt/completion rows.
+for key in ("completion_only_loss", "train_on_completions"):
+ t = trl.SFTTrainer(model, trl.SFTConfig(max_steps=1, **{key: True}), None, [], None, tok)
+ assert getattr(t.args, key) is True
+
+# Rebuilding the config for a trainer-level override keeps them.
+t = trl.SFTTrainer(model=model, args=args, train_dataset=[], processing_class=tok, packing=False, seed=9)
+assert t.args.seed == 9 and t.args.assistant_only_loss is True and t.args.logging_first_step is True
+
+t = trl.SFTTrainer(model=model, args=args, train_dataset=[], processing_class=tok, loraplus_lr_ratio=16)
+assert t.args.lora_plus_ratio == 16
+
+refused(lambda: trl.SFTConfig(dataloader_drop_last=True), "dataloader_drop_last")
+for fast in (unsloth.FastLanguageModel, unsloth.FastModel, unsloth.FastVisionModel):
+ assert fast.for_training(model) is model
+""")
+
+
+@_needs_real_mlx
+def test_trl_configs_built_before_the_shim_keep_their_meaning():
+ # importorskip would find the shim an earlier test left in sys.modules.
+ try:
+ importlib.metadata.version("trl")
+ except importlib.metadata.PackageNotFoundError:
+ pytest.skip(
+ reason = "trl is not installed, so no real DPOConfig can be built before the shim"
+ )
+ _run_shim_probe(
+ """
+assert RealDPO is not trl.DPOConfig
+t = trl.DPOTrainer(model=model, args=RealDPO(output_dir="o", beta=0.3, max_length=99), train_dataset=[], processing_class=tok)
+assert isinstance(t.args, zoo.MLXDPOConfig) and (t.args.beta, t.args.max_length, t.args.learning_rate) == (0.3, 99, 1e-6)
+if hasattr(RealDPO(output_dir="o"), "rpo_alpha"):
+ refused(lambda: trl.DPOTrainer(model=model, args=RealDPO(output_dir="o", rpo_alpha=1.0), train_dataset=[]), "rpo_alpha")
+refused(lambda: trl.DPOTrainer(model=model, args=RealDPO(output_dir="o", use_weighting=True), train_dataset=[]), "use_weighting")
+assert trl.DPOTrainer(model=model, args=RealDPO(output_dir="o", eval_strategy="epoch"), train_dataset=[]).args.eval_strategy == "epoch"
+refused(lambda: trl.DPOTrainer(model=model, args=RealDPO(output_dir="o", dataloader_drop_last=True), train_dataset=[]), "dataloader_drop_last")
+assert trl.DPOTrainer(model=model, args=RealDPO(output_dir="o", bf16=False, learning_rate=0.1, save_strategy="no", optim="adamw_torch"), train_dataset=[]).args.learning_rate == 0.1
+for stem, real in RealConfigs.items():
+ config = getattr(trl, stem + "Config")
+ assert isinstance(unsloth._coerce_mlx_training_args(real(output_dir="o"), None, config), config), stem
+refused(lambda: trl.GRPOTrainer(model, [print], RealGRPO(output_dir="o"), [], None, tok), "GRPOConfig")
+
+class RefusesBf16(RealDPO):
+ def __post_init__(self):
+ assert self.bf16 is False, "Your setup doesn't support bf16/gpu."
+ super().__post_init__()
+assert trl.DPOTrainer(model=model, args=RefusesBf16(output_dir="o", bf16=False), train_dataset=[]).args.beta == 0.1
+""",
+ before_unsloth = (
+ "import dataclasses, trl\n"
+ # TRL defaults bf16 on, which transformers refuses on a Mac VM without MPS (GitHub's runners).
+ "def cpu(c): return dataclasses.make_dataclass(c.__name__, [('bf16', bool, False)], bases=(c,))\n"
+ "RealDPO = cpu(trl.DPOConfig)\n"
+ "RealGRPO = cpu(trl.GRPOConfig)\n"
+ "RealConfigs = {s: cpu(getattr(trl, s + 'Config')) for s in ('ORPO', 'KTO', 'CPO') if hasattr(trl, s + 'Config')}\n"
+ ),
+ )
+
+
+@_needs_real_mlx
+def test_trl_star_import_exposes_the_mappings_without_trl_installed():
+ _run_shim_probe(
+ """
+assert trl.__version__.endswith("unsloth-mlx"), trl.__version__
+namespace = {}
+exec("from trl import *", namespace)
+for stem in ("SFT", "DPO", "ORPO", "KTO", "GRPO", "CPO"):
+ assert namespace[stem + "Trainer"] is getattr(trl, stem + "Trainer"), stem
+ assert namespace[stem + "Config"] is getattr(trl, stem + "Config"), stem
+""",
+ before_unsloth = "import sys\nsys.modules['trl'] = None\n",
+ )
diff --git a/unsloth/__init__.py b/unsloth/__init__.py
index 9af4d7e9b03..dada94b19b6 100644
--- a/unsloth/__init__.py
+++ b/unsloth/__init__.py
@@ -275,9 +275,9 @@ if _IS_MLX:
from unsloth_zoo.mlx.trainer import (
MLXTrainer,
MLXTrainingConfig,
- _is_vlm_model,
_normalize_mlx_optimizer_name,
)
+ from unsloth_zoo.mlx import trainer as _mlx_zoo_trainer
from unsloth_zoo.mlx.loader import FastMLXModel
except ImportError as _e:
raise ImportError(
@@ -286,7 +286,9 @@ if _IS_MLX:
"`pip install -U unsloth-zoo` or rerun install.sh."
) from _e
+ import copy as _copy
import dataclasses as _dataclasses
+ from typing import Optional as _Optional
import inspect as _inspect
import importlib.machinery as _machinery
import sys as _sys
@@ -407,16 +409,16 @@ if _IS_MLX:
def for_inference(*args, **kwargs):
return args[0] if args else None
+ @staticmethod
+ def for_training(*args, **kwargs):
+ return args[0] if args else None
+
class FastVisionModel(FastLanguageModel):
@staticmethod
def from_pretrained(*args, **kwargs):
kwargs.setdefault("text_only", False)
return _mlx_from_pretrained(*args, **kwargs)
- @staticmethod
- def for_training(*args, **kwargs):
- return args[0] if args else None
-
FastTextModel = FastLanguageModel
FastModel = FastLanguageModel
@@ -676,6 +678,7 @@ if _IS_MLX:
_MLX_TRAINING_ARGUMENT_ALIASES = {
"max_length": "max_seq_length",
"loraplus_lr_ratio": "lora_plus_ratio",
+ "evaluation_strategy": "eval_strategy",
}
_MLX_COMPAT_EXTRA_ARGUMENTS = frozenset(
(
@@ -685,40 +688,34 @@ if _IS_MLX:
"dataset_kwargs",
"ddp_find_unused_parameters",
"disable_tqdm",
- "eval_strategy",
- "evaluation_strategy",
"fp16",
"full_determinism",
"gradient_checkpointing_kwargs",
"hub_model_id",
"hub_token",
"log_level",
- "logging_strategy",
- "neftune_noise_alpha",
- "optim_args",
"padding_free",
"push_to_hub",
"remove_unused_columns",
"save_on_each_node",
"save_safetensors",
- "save_strategy",
"torch_compile",
)
)
_MLX_IMPLEMENTED_EXTRA_ARGUMENTS = frozenset(
(
+ "eval_delay",
+ "eval_strategy",
"image_size",
+ "include_num_input_tokens_seen",
+ "logging_first_step",
+ "logging_strategy",
"preserve_dataset_order",
+ "save_strategy",
"warmup_ratio",
)
)
_MLX_ALLOWED_EXTRA_ARGUMENTS = _MLX_COMPAT_EXTRA_ARGUMENTS | _MLX_IMPLEMENTED_EXTRA_ARGUMENTS
- _MLX_UNSUPPORTED_TASK_ARGUMENTS = frozenset(
- (
- "assistant_only_loss",
- "completion_only_loss",
- )
- )
def _is_mlx_no_save_strategy(value):
if hasattr(value, "value"):
@@ -770,9 +767,9 @@ if _IS_MLX:
return "adamw"
raise
- def _mlx_training_argument_values(args):
+ def _mlx_training_argument_values(args, config_class = MLXTrainingConfig):
values = {}
- for field in _dataclasses.fields(MLXTrainingConfig):
+ for field in _dataclasses.fields(config_class):
if hasattr(args, field.name):
values[field.name] = _normalize_mlx_training_value(
field.name,
@@ -786,31 +783,49 @@ if _IS_MLX:
for name in _MLX_ALLOWED_EXTRA_ARGUMENTS:
if hasattr(args, name):
values[name] = getattr(args, name)
- for name in _MLX_UNSUPPORTED_TASK_ARGUMENTS:
- if hasattr(args, name):
- value = getattr(args, name)
- if (
- name == "completion_only_loss"
- and value is not None
- and name in _MLX_TRAINING_CONFIG_FIELDS
- ):
- values[name] = value
- elif value is not None and value is not False:
- values[name] = value
+ trl_arguments = getattr(config_class, "_unsloth_mlx_trl_arguments", None)
+ if trl_arguments is not None:
+ for name in trl_arguments:
+ if name not in values and hasattr(args, name):
+ values[name] = getattr(args, name)
+ # Anything else set is refused. Compare to a fresh config: TrainingArguments rewrites fields at init.
+ if not isinstance(args, MLXTrainingConfig) and _dataclasses.is_dataclass(args):
+ # TRL defaults bf16 on, and older transformers refuses that on a Mac.
+ precision = {"bf16": False} if hasattr(args, "bf16") else {}
+ fresh = type(args)(output_dir = args.output_dir, **precision)
+ for field in _dataclasses.fields(args):
+ if (
+ field.init
+ and field.name not in values
+ and field.name not in ("do_eval", "do_predict", "do_train")
+ ):
+ value = getattr(args, field.name, None)
+ if value != getattr(fresh, field.name, None):
+ values[field.name] = value
if _is_mlx_no_save_strategy(values.get("save_strategy", None)):
values["save_steps"] = 0
return values
- def _split_mlx_trainer_kwargs(kwargs):
+ def _split_mlx_trainer_kwargs(
+ kwargs,
+ extra_trainer_kwargs = (),
+ config_class = MLXTrainingConfig,
+ ):
trainer_kwargs = {}
config_kwargs = {}
ignored_kwargs = {}
+ config_fields = {field.name for field in _dataclasses.fields(config_class)}
+ aliases = getattr(
+ config_class,
+ "_unsloth_mlx_argument_aliases",
+ _MLX_TRAINING_ARGUMENT_ALIASES,
+ )
for key, value in kwargs.items():
- if key in _MLX_TRAINER_KWARGS:
+ if key in _MLX_TRAINER_KWARGS or key in extra_trainer_kwargs:
trainer_kwargs[key] = value
continue
- target = _MLX_TRAINING_ARGUMENT_ALIASES.get(key, key)
- if target in _MLX_TRAINING_CONFIG_FIELDS or key in _MLX_ALLOWED_EXTRA_ARGUMENTS:
+ target = aliases.get(key, key)
+ if target in config_fields or target in _MLX_ALLOWED_EXTRA_ARGUMENTS:
config_kwargs[key] = value
else:
ignored_kwargs[key] = value
@@ -843,15 +858,22 @@ if _IS_MLX:
raise TypeError(f"UnslothTrainer.__init__() got multiple values for argument {name!r}")
kwargs[name] = value
- def _normalize_mlx_trainer_init_args(args, kwargs):
+ def _normalize_mlx_trainer_init_args(
+ args,
+ kwargs,
+ positional_names = None,
+ ):
kwargs = dict(kwargs)
if len(args) == 0:
return kwargs
- use_trl_schema = _should_use_trl_positional_schema(args)
- positional_names = (
- _TRL_SFT_TRAINER_POSITIONAL_KWARGS if use_trl_schema else _MLX_TRAINER_POSITIONAL_KWARGS
- )
+ if positional_names is None:
+ use_trl_schema = _should_use_trl_positional_schema(args)
+ positional_names = (
+ _TRL_SFT_TRAINER_POSITIONAL_KWARGS
+ if use_trl_schema
+ else _MLX_TRAINER_POSITIONAL_KWARGS
+ )
if len(args) > len(positional_names):
raise TypeError(
f"UnslothTrainer.__init__() takes at most "
@@ -893,7 +915,7 @@ if _IS_MLX:
return False
return _is_meaningful_mlx_extra_value(value)
- def _raise_unsupported_mlx_trainer_kwargs(ignored_kwargs):
+ def _raise_unsupported_mlx_trainer_kwargs(ignored_kwargs, trainer_name = "SFTTrainer"):
names = sorted(
key
for key, value in ignored_kwargs.items()
@@ -902,7 +924,7 @@ if _IS_MLX:
if not names:
return
raise NotImplementedError(
- "Unsloth MLX: unsupported SFTTrainer kwargs cannot be ignored safely: "
+ f"Unsloth MLX: unsupported {trainer_name} kwargs cannot be ignored safely: "
f"{', '.join(names)}. Remove these kwargs or use a supported MLX "
"trainer configuration."
)
@@ -948,6 +970,8 @@ if _IS_MLX:
class UnslothTrainingArguments(MLXTrainingConfig):
"""MLX-compatible public training arguments for Unsloth notebooks."""
+ _unsloth_mlx_argument_aliases = _MLX_TRAINING_ARGUMENT_ALIASES
+
def __init__(self, *args, **kwargs):
if len(args) == 1 and isinstance(args[0], dict):
kwargs = {**args[0], **kwargs}
@@ -959,16 +983,20 @@ if _IS_MLX:
"a dict, or a single positional output_dir."
)
- max_length_value = kwargs.get("max_length", None)
+ aliases = self._unsloth_mlx_argument_aliases
+ config_fields = {field.name for field in _dataclasses.fields(type(self))}
+ max_length_is_alias = "max_length" in aliases
+ max_length_value = kwargs.get("max_length", None) if max_length_is_alias else None
# Only the canonical max_seq_length marks context length explicit; TRL max_length stays a
# compatibility alias that defers to the model's context length.
max_seq_length_explicit = (
_positive_mlx_context_length(kwargs.get("max_seq_length", None)) is not None
)
- if "max_length" in kwargs and "max_seq_length" not in kwargs:
+ if max_length_is_alias and "max_length" in kwargs and "max_seq_length" not in kwargs:
kwargs["max_seq_length"] = kwargs["max_length"]
elif (
- "max_length" in kwargs
+ max_length_is_alias
+ and "max_length" in kwargs
and _positive_mlx_context_length(kwargs.get("max_seq_length", None)) is not None
):
max_length_value = kwargs["max_seq_length"]
@@ -994,21 +1022,11 @@ if _IS_MLX:
filtered_kwargs = {}
extra_kwargs = {}
for key, value in kwargs.items():
- target = _MLX_TRAINING_ARGUMENT_ALIASES.get(key, key)
+ target = aliases.get(key, key)
if key != target and target in kwargs:
continue
value = _normalize_mlx_training_value(target, value)
- if target in _MLX_UNSUPPORTED_TASK_ARGUMENTS:
- if (
- target == "completion_only_loss"
- and value is not None
- and target in _MLX_TRAINING_CONFIG_FIELDS
- ):
- filtered_kwargs[target] = value
- elif _is_meaningful_mlx_extra_value(value):
- extra_kwargs[key] = value
- continue
- if target in _MLX_TRAINING_CONFIG_FIELDS:
+ if target in config_fields:
filtered_kwargs[target] = value
else:
extra_kwargs[target if target in _MLX_ALLOWED_EXTRA_ARGUMENTS else key] = value
@@ -1038,7 +1056,7 @@ if _IS_MLX:
self._unsloth_mlx_append_eos_explicit = append_eos_explicit
self._unsloth_mlx_max_seq_length_explicit = max_seq_length_explicit
self._unsloth_mlx_max_length_value = max_length_value
- if "max_length" in kwargs:
+ if max_length_is_alias and "max_length" in kwargs:
self.max_length = max_length_value
self._unsloth_mlx_grad_clip_explicit = grad_clip_explicit
self._unsloth_mlx_warmup_steps_explicit = warmup_steps_explicit
@@ -1046,6 +1064,14 @@ if _IS_MLX:
for key, value in extra_kwargs.items():
setattr(self, key, value)
_warn_ignored_mlx_training_args(extra_kwargs)
+ self._unsloth_mlx_logging_steps_explicit = "logging_steps" in kwargs
+ self._unsloth_mlx_initial_logging_steps = self.logging_steps
+ self._unsloth_mlx_initial_warmup_steps = self.warmup_steps
+ # Like TrainingArguments: zoo's eval_steps=0 would silently never evaluate. That fallback
+ # means TRL's logging_steps default of 10, not zoo's 1.
+ eval_strategy = getattr(self, "eval_strategy", None)
+ if getattr(eval_strategy, "value", eval_strategy) == "steps" and not self.eval_steps:
+ self.eval_steps = kwargs.get("logging_steps") or 10
def _resolve_mlx_cuda_style_max_seq_length(args, model = None):
model_max_seq_length = _positive_mlx_context_length(
@@ -1110,25 +1136,23 @@ if _IS_MLX:
_set_mlx_cuda_style_context_length(args, 1024)
return args
- def _apply_unsloth_trainer_mlx_defaults(
- args,
- model = None,
- max_seq_length_explicit = False,
- ):
+ def _mlx_dataset_order_edited(args):
+ return getattr(args, "_unsloth_mlx_dataset_order_implicit", False) and not isinstance(
+ args.dataset_order, _MLXImplicitStr
+ )
+
+ def _default_mlx_dataset_order(args):
if (
not getattr(args, "streaming", False)
and not getattr(args, "preserve_dataset_order", False)
and not getattr(args, "_unsloth_mlx_dataset_order_explicit", False)
+ and not _mlx_dataset_order_edited(args)
):
default_order = getattr(MLXTrainingConfig, "dataset_order", "default")
if getattr(args, "dataset_order", default_order) in (None, default_order):
args.dataset_order = "torch_randperm"
- if isinstance(args, UnslothTrainingArguments) and not getattr(
- args, "_unsloth_mlx_append_eos_explicit", False
- ):
- args.append_eos = False
-
+ def _default_mlx_grad_clip(args):
if isinstance(args, UnslothTrainingArguments) and not getattr(
args, "_unsloth_mlx_grad_clip_explicit", False
):
@@ -1144,14 +1168,43 @@ if _IS_MLX:
if max_grad_norm is None and max_grad_value is None and max_grad_leaf_norm is None:
args.max_grad_norm = 1.0
+ def _apply_unsloth_trainer_mlx_defaults(
+ args,
+ model = None,
+ max_seq_length_explicit = False,
+ ):
+ _default_mlx_dataset_order(args)
+
+ if isinstance(args, UnslothTrainingArguments) and not getattr(
+ args, "_unsloth_mlx_append_eos_explicit", False
+ ):
+ args.append_eos = False
+
+ _default_mlx_grad_clip(args)
+
if not max_seq_length_explicit:
_resolve_mlx_cuda_style_max_seq_length(args, model = model)
return args
- def _coerce_mlx_training_args(args, overrides = None):
+ def _mlx_context_length_edited(args):
+ initial = getattr(args, "_unsloth_mlx_initial_max_seq_length", None)
+ if initial is None:
+ return False
+ # Assigning zoo's default value over the filled-in one is still an edit.
+ replaced = isinstance(initial, _MLXImplicitInt) and not isinstance(
+ args.max_seq_length, _MLXImplicitInt
+ )
+ return replaced or args.max_seq_length != initial
+
+ def _coerce_mlx_training_args(
+ args,
+ overrides = None,
+ config_class = None,
+ ):
overrides = overrides or {}
- if isinstance(args, MLXTrainingConfig) and not overrides:
+ if isinstance(args, config_class or MLXTrainingConfig) and not overrides:
return args
+ config_class = config_class or UnslothTrainingArguments
dataset_order_explicit = None
append_eos_explicit = None
max_seq_length_explicit = None
@@ -1168,7 +1221,7 @@ if _IS_MLX:
args,
"_unsloth_mlx_dataset_order_explicit",
False,
- )
+ ) or _mlx_dataset_order_edited(args)
append_eos_explicit = getattr(
args,
"_unsloth_mlx_append_eos_explicit",
@@ -1188,6 +1241,7 @@ if _IS_MLX:
args_max_seq_length is not None
and args_max_seq_length != default_max_seq_length
)
+ max_seq_length_explicit = max_seq_length_explicit or _mlx_context_length_edited(args)
max_length_value = getattr(
args,
"_unsloth_mlx_max_length_value",
@@ -1198,11 +1252,46 @@ if _IS_MLX:
"_unsloth_mlx_grad_clip_explicit",
None,
)
- values = _mlx_training_argument_values(args)
+ values = _mlx_training_argument_values(args, config_class)
if hasattr(args, "max_length"):
values["max_length"] = getattr(args, "max_length")
- values.update(overrides)
- coerced = UnslothTrainingArguments(**values)
+ if (
+ values.get("warmup_ratio")
+ and getattr(args, "_unsloth_mlx_warmup_steps_explicit", True) is False
+ and values.get("warmup_steps")
+ == getattr(args, "_unsloth_mlx_initial_warmup_steps", values.get("warmup_steps"))
+ ):
+ if overrides.get("warmup_ratio", values["warmup_ratio"]):
+ values.pop("warmup_steps", None)
+ else:
+ values["warmup_steps"] = 0
+ if getattr(args, "_unsloth_mlx_logging_steps_explicit", True) is False and values.get(
+ "logging_steps"
+ ) == getattr(args, "_unsloth_mlx_initial_logging_steps", None):
+ values.pop("logging_steps", None)
+ # An untouched default norm must not outvote a clip the trainer sets below, and an SFT
+ # config with no clip set takes the TRL config's default norm, as SFT itself would.
+ if (
+ not grad_clip_explicit
+ and values.get("max_grad_norm") == getattr(config_class, "max_grad_norm", None)
+ ) or (
+ grad_clip_explicit is False
+ and hasattr(config_class, "_unsloth_mlx_trl_arguments")
+ and not isinstance(args, _MLXTRLConfig)
+ and not any(
+ _positive_mlx_training_number(values.get(name)) is not None
+ for name in ("max_grad_norm", "max_grad_value", "max_grad_leaf_norm")
+ )
+ ):
+ values.pop("max_grad_norm", None)
+ for key, value in overrides.items():
+ target = key if key == "max_length" else _MLX_TRAINING_ARGUMENT_ALIASES.get(key, key)
+ # The canonical spelling wins over its alias, whatever the keyword order.
+ if target == key or target not in overrides:
+ values[target] = value
+ if hasattr(config_class, "_unsloth_mlx_trl_arguments"):
+ values["_unsloth_mlx_config_copy"] = True
+ coerced = config_class(**values)
if (
dataset_order_explicit is not None
and "dataset_order" not in overrides
@@ -1214,7 +1303,10 @@ if _IS_MLX:
if (
max_seq_length_explicit is not None
and "max_seq_length" not in overrides
- and "max_length" not in overrides
+ and (
+ "max_length" not in overrides
+ or "max_length" not in config_class._unsloth_mlx_argument_aliases
+ )
):
coerced._unsloth_mlx_max_seq_length_explicit = max_seq_length_explicit
if max_length_value is not None and "max_length" not in overrides:
@@ -1261,12 +1353,12 @@ if _IS_MLX:
)
_MLX_TRAINER_KWARGS = frozenset(_MLX_TRAINER_POSITIONAL_KWARGS)
- def _filter_supported_mlx_trainer_kwargs(trainer_kwargs):
+ def _filter_supported_mlx_trainer_kwargs(trainer_kwargs, extra_trainer_kwargs = ()):
"""Drop inert/empty kwargs unsupported by this zoo MLXTrainer."""
unsupported = {
key: value
for key, value in trainer_kwargs.items()
- if not _mlx_trainer_supports_kwarg(key)
+ if not _mlx_trainer_supports_kwarg(key) and key not in extra_trainer_kwargs
}
names = sorted(
key for key, value in unsupported.items() if _is_meaningful_mlx_extra_value(value)
@@ -1380,9 +1472,36 @@ if _IS_MLX:
class UnslothTrainer(MLXTrainer):
"""Backend-aware public trainer that routes supported SFT notebooks to MLX."""
+ _unsloth_mlx_trainer_name = "SFTTrainer"
+ _unsloth_mlx_positional_kwargs = None
+ _unsloth_mlx_extra_kwargs = frozenset()
+ _unsloth_mlx_config_class = MLXTrainingConfig
+
+ def _unsloth_mlx_coerce_args(self, args, overrides):
+ return _coerce_mlx_training_args(args, overrides)
+
+ def _unsloth_mlx_apply_defaults(self, args, model, max_seq_length_explicit):
+ return _apply_unsloth_trainer_mlx_defaults(
+ args,
+ model = model,
+ max_seq_length_explicit = max_seq_length_explicit,
+ )
+
def __init__(self, *args, **kwargs):
- kwargs = _normalize_mlx_trainer_init_args(args, kwargs)
+ kwargs = _normalize_mlx_trainer_init_args(
+ args,
+ kwargs,
+ self._unsloth_mlx_positional_kwargs,
+ )
processing_class = kwargs.pop("processing_class", None)
+ if (
+ processing_class is None
+ and kwargs.get("tokenizer") is None
+ and kwargs.get("processor") is None
+ and not isinstance(kwargs.get("data_collator"), UnslothVisionDataCollator)
+ ):
+ # TRL falls back to the model's own tokenizer too; a vision collator brings its own.
+ processing_class = getattr(kwargs.get("model"), "_tokenizer", None)
processor_from_processing_class = False
if processing_class is not None:
if kwargs.get("processor", None) is None:
@@ -1459,33 +1578,24 @@ if _IS_MLX:
"trainer's native batching path."
)
- trainer_kwargs, config_kwargs, ignored_kwargs = _split_mlx_trainer_kwargs(kwargs)
- _raise_unsupported_mlx_trainer_kwargs(ignored_kwargs)
- trainer_kwargs = _filter_supported_mlx_trainer_kwargs(trainer_kwargs)
- trainer_kwargs["args"] = _coerce_mlx_training_args(
+ trainer_kwargs, config_kwargs, ignored_kwargs = _split_mlx_trainer_kwargs(
+ kwargs,
+ self._unsloth_mlx_extra_kwargs,
+ self._unsloth_mlx_config_class,
+ )
+ _raise_unsupported_mlx_trainer_kwargs(ignored_kwargs, self._unsloth_mlx_trainer_name)
+ trainer_kwargs = _filter_supported_mlx_trainer_kwargs(
+ trainer_kwargs,
+ self._unsloth_mlx_extra_kwargs,
+ )
+ trainer_kwargs["args"] = self._unsloth_mlx_coerce_args(
trainer_kwargs.get("args"),
config_kwargs,
)
- if getattr(
- trainer_kwargs["args"], "completion_only_loss", None
- ) is True and not _is_vlm_model(trainer_kwargs.get("model")):
- raise NotImplementedError(
- "Unsloth MLX: completion_only_loss=True is only supported "
- "for VLM training. For text SFT, call train_on_responses_only "
- "after constructing the trainer."
- )
- if getattr(
- trainer_kwargs["args"], "train_on_completions", None
- ) is True and not _is_vlm_model(trainer_kwargs.get("model")):
- raise NotImplementedError(
- "Unsloth MLX: train_on_completions=True is only supported "
- "for VLM training. For text SFT, call train_on_responses_only "
- "after constructing the trainer."
- )
- trainer_kwargs["args"] = _apply_unsloth_trainer_mlx_defaults(
+ trainer_kwargs["args"] = self._unsloth_mlx_apply_defaults(
trainer_kwargs["args"],
- model = trainer_kwargs.get("model"),
- max_seq_length_explicit = (trainer_kwargs.get("max_seq_length") is not None),
+ trainer_kwargs.get("model"),
+ trainer_kwargs.get("max_seq_length") is not None,
)
super().__init__(**trainer_kwargs)
@@ -1494,7 +1604,9 @@ if _IS_MLX:
if processing_class is not None
else self.processor or self.tokenizer
)
- if trainer_kwargs.get("max_seq_length") is not None:
+ if trainer_kwargs.get("max_seq_length") is not None and not getattr(
+ self, "preference_kind", None
+ ):
_set_mlx_cuda_style_context_length(
self.args,
self.args.max_seq_length,
@@ -1568,6 +1680,17 @@ if _IS_MLX:
)
return _train_on_responses_only(*args, **kwargs)
+ def PatchDPOTrainer():
+ """No-op on MLX: trl's preference trainers already resolve to the MLX ones."""
+
+ def PatchKTOTrainer():
+ """No-op on MLX: trl's preference trainers already resolve to the MLX ones."""
+
+ def PatchFastRL(algorithm = None, FastLanguageModel = None):
+ """No-op on MLX: trl's RL trainers already resolve to the MLX ones."""
+
+ _mlx_trl_mapped_names = {"SFTConfig", "SFTTrainer"}
+
def _safe_mlx_trl_star_exports(_trl, exports):
"""Return importable TRL star exports plus the MLX SFT shims."""
safe_exports = []
@@ -1577,26 +1700,22 @@ if _IS_MLX:
except Exception:
continue
safe_exports.append(name)
- for name in ("SFTConfig", "SFTTrainer"):
+ for name in sorted(_mlx_trl_mapped_names):
if name not in safe_exports:
safe_exports.append(name)
return safe_exports
# Stub trl trainers with no MLX implementation so they fail clearly instead of deep in torch code.
_MLX_UNSUPPORTED_TRL_TRAINERS = (
- "GRPOTrainer",
- "DPOTrainer",
- "ORPOTrainer",
- "KTOTrainer",
"PPOTrainer",
"RewardTrainer",
)
- def _make_mlx_unsupported_trl_trainer(name):
+ def _make_mlx_unsupported_trl_trainer(name, supported):
def __init__(self, *args, **kwargs):
raise NotImplementedError(
f"Unsloth: {name} is not yet supported on the MLX (Apple Silicon) "
- f"backend. Only SFT training runs on MLX today; use a CUDA/ROCm GPU "
+ f"backend, which runs {', '.join(supported)}; use a CUDA/ROCm GPU "
f"for {name}."
)
@@ -1620,6 +1739,358 @@ if _IS_MLX:
kwargs.setdefault("num_train_epochs", 3)
super().__init__(*args, **kwargs)
+ # TRL's own defaults: zoo's base config would run DPO at 200x the learning rate with no signal.
+ _MLX_TRL_CONFIG_DEFAULTS = {
+ "dataset_order": None,
+ "eval_strategy": "no",
+ "gradient_accumulation_steps": 1,
+ "learning_rate": 1e-6,
+ "logging_steps": 10,
+ "max_grad_norm": 1.0,
+ "max_seq_length": None,
+ "max_steps": -1,
+ "num_train_epochs": 3,
+ "per_device_train_batch_size": 8,
+ "save_steps": 500,
+ "warmup_steps": 0,
+ "weight_decay": 0.0,
+ }
+ # Defaults TRL changed: stem -> first release, new defaults.
+ _MLX_TRL_VERSIONED_DEFAULTS = {
+ "DPO": ("0.29.0", {"max_prompt_length": None, "truncation_mode": "keep_start"}),
+ "GRPO": ("1.10.0", {"max_completion_length": 512}),
+ }
+ # What HfArgumentParser needs where zoo's own annotation is missing, too narrow or refused.
+ _MLX_TRL_CONFIG_TYPES = {
+ "dataset_order": _Optional[str],
+ "eval_strategy": str,
+ "max_seq_length": _Optional[int],
+ "num_train_epochs": float,
+ "scale_rewards": str,
+ }
+ _MLX_TRL_INERT_CONFIG_VALUES = {
+ "base_model_attribute_name": "model",
+ "cache_implementation": None,
+ "ds3_gather_for_generation": True,
+ "f_divergence_type": "reverse_kl",
+ "is_encoder_decoder": None,
+ "label_pad_token_id": -100,
+ "ld_alpha": None,
+ "model_init_kwargs": None,
+ "padding_value": None,
+ "ref_model_init_kwargs": None,
+ "rpo_alpha": None,
+ "tools": None,
+ "use_liger_loss": False,
+ "use_logits_to_keep": False,
+ "use_transformers_paged": False,
+ "use_weighting": False,
+ "wandb_log_unique_prompts": False,
+ }
+
+ class _MLXImplicitStr(str):
+ pass
+
+ class _MLXImplicitInt(int):
+ pass
+
+ _MLX_IMPLICIT_TYPES = (_MLXImplicitStr, _MLXImplicitInt)
+
+ class _MLXTRLConfig(_MLXSFTConfig):
+ _unsloth_mlx_trl_arguments = (*_MLX_TRL_INERT_CONFIG_VALUES, "f_alpha_divergence_coef")
+
+ def __init__(self, *args, **kwargs):
+ if len(args) == 1 and isinstance(args[0], dict):
+ kwargs = {**args[0], **kwargs}
+ args = ()
+ fields = _dataclasses.fields(type(self))
+ config_fields = {field.name for field in fields}
+ # HfArgumentParser and dataclasses.replace pass every field: neither an untouched default
+ # nor a value filled in below is the caller's choice.
+ if not kwargs.pop("_unsloth_mlx_config_copy", False) and config_fields <= set(kwargs):
+ for field in fields:
+ value = kwargs[field.name]
+ if value == field.default or isinstance(value, _MLX_IMPLICIT_TYPES):
+ del kwargs[field.name]
+ # A value set on either other knob decides the clip, so TRL's default norm must stay out of it.
+ if (
+ kwargs.get("max_grad_value") is not None
+ or kwargs.get("max_grad_leaf_norm") is not None
+ ):
+ kwargs.setdefault("max_grad_norm", 0.0)
+ divergence = kwargs.get("f_divergence_type", "reverse_kl")
+ # Only alpha_divergence reads it, and its default differs across TRL releases.
+ if getattr(divergence, "value", divergence) == "reverse_kl":
+ kwargs.pop("f_alpha_divergence_coef", None)
+ for key, value in _MLX_TRL_INERT_CONFIG_VALUES.items():
+ if key not in config_fields and key in kwargs:
+ # None: some TRL releases default these fields to it.
+ if getattr(kwargs[key], "value", kwargs[key]) in (value, None):
+ del kwargs[key]
+ super().__init__(*args, **kwargs)
+ # None on the field shows HfArgumentParser's caller left these unset; zoo's default stands,
+ # typed so a dataclasses.replace clone can tell it from an explicit equal value.
+ for key, implicit in (
+ ("dataset_order", _MLXImplicitStr),
+ ("max_seq_length", _MLXImplicitInt),
+ ):
+ if getattr(self, key) is None:
+ setattr(self, key, implicit(getattr(MLXTrainingConfig, key)))
+ self._unsloth_mlx_initial_max_seq_length = self.max_seq_length
+ self._unsloth_mlx_dataset_order_implicit = isinstance(
+ self.dataset_order, _MLXImplicitStr
+ )
+
+ def _resolve_mlx_trl_grad_clip(args):
+ no_other_clip = args.max_grad_value is None and args.max_grad_leaf_norm is None
+ if no_other_clip and (args.max_grad_norm or 0) <= 0:
+ # TRL only clips on a positive norm; zoo would fall back to leaf clipping at 1.0.
+ args.max_grad_leaf_norm = 0.0
+ elif (
+ not no_other_clip
+ and not getattr(args, "_unsloth_mlx_grad_clip_explicit", False)
+ and args.max_grad_norm == type(args).max_grad_norm
+ ):
+ args.max_grad_norm = 0.0
+
+ class _MLXTRLPolicyTrainer(UnslothTrainer):
+ _unsloth_mlx_keep_dataset_order = False
+
+ def __init__(self, *args, **kwargs):
+ kwargs = _normalize_mlx_trainer_init_args(
+ args,
+ kwargs,
+ self._unsloth_mlx_positional_kwargs,
+ )
+ for key in ("model", "ref_model"):
+ if isinstance(kwargs.get(key), (str, os.PathLike)):
+ raise NotImplementedError(
+ f"Unsloth MLX: {self._unsloth_mlx_trainer_name} needs {key} loaded "
+ "with FastLanguageModel.from_pretrained, not a model name."
+ )
+ super().__init__(**kwargs)
+
+ def _unsloth_mlx_coerce_args(self, args, overrides):
+ if self.preference_kind == "grpo" and args is not None:
+ # Its config resolution is not idempotent, and TRL's fills in both batch knobs zoo requires one of.
+ if overrides or not isinstance(args, (self.config_class, dict, str, os.PathLike)):
+ raise NotImplementedError(
+ "Unsloth MLX: set every GRPO option on a GRPOConfig built after "
+ "`import unsloth`, not on an existing config or the trainer."
+ )
+ if isinstance(args, self.config_class) and not overrides:
+ return args
+ # A native zoo config with no clip set means zoo's leaf default, not TRL's "off".
+ if (
+ isinstance(args, MLXTrainingConfig)
+ and not isinstance(args, (_MLXTRLConfig, UnslothTrainingArguments))
+ and (args.max_grad_norm or 0) <= 0
+ and args.max_grad_value is None
+ and args.max_grad_leaf_norm is None
+ and not {"max_grad_norm", "max_grad_value", "max_grad_leaf_norm"} & set(overrides)
+ ):
+ overrides = {**overrides, "max_grad_leaf_norm": 1.0}
+ return _coerce_mlx_training_args(args, overrides, self._unsloth_mlx_config_class)
+
+ def _unsloth_mlx_apply_defaults(self, args, model, max_seq_length_explicit):
+ # args may be the caller's config, which another trainer can reuse.
+ args = _copy.copy(args)
+ if not self._unsloth_mlx_keep_dataset_order:
+ _default_mlx_dataset_order(args)
+ if isinstance(args, _MLXTRLConfig):
+ _resolve_mlx_trl_grad_clip(args)
+ model_length = _positive_mlx_context_length(getattr(model, "max_seq_length", None))
+ args_explicit = getattr(args, "_unsloth_mlx_max_seq_length_explicit", None)
+ if args_explicit is None:
+ args_explicit = args.max_seq_length != MLXTrainingConfig.max_seq_length
+ args_explicit = (
+ max_seq_length_explicit or args_explicit or _mlx_context_length_edited(args)
+ )
+ if model_length is not None and (
+ not args_explicit or args.max_seq_length > model_length
+ ):
+ args.max_seq_length = model_length
+ if not args_explicit:
+ # A trainer's own resolved length is not an edit if that config is reused.
+ args._unsloth_mlx_initial_max_seq_length = args.max_seq_length
+ return args
+
+ _MLX_TRL_POLICY_TRAINERS = (
+ (
+ "DPO",
+ "MLXDPOTrainer",
+ "MLXDPOConfig",
+ (
+ "model",
+ "ref_model",
+ "args",
+ "data_collator",
+ "train_dataset",
+ "eval_dataset",
+ "processing_class",
+ "compute_metrics",
+ "callbacks",
+ "optimizers",
+ "optimizer_cls_and_kwargs",
+ "preprocess_logits_for_metrics",
+ "peft_config",
+ ),
+ ("ref_model",),
+ False,
+ ),
+ (
+ "ORPO",
+ "MLXORPOTrainer",
+ "MLXORPOConfig",
+ (
+ "model",
+ "args",
+ "data_collator",
+ "train_dataset",
+ "eval_dataset",
+ "processing_class",
+ "model_init",
+ "callbacks",
+ "optimizers",
+ "preprocess_logits_for_metrics",
+ "peft_config",
+ "compute_metrics",
+ ),
+ (),
+ False,
+ ),
+ (
+ # TRL cuts KTO batches in dataset order: each row's KL pair is its neighbor in the batch.
+ "KTO",
+ "MLXKTOTrainer",
+ "MLXKTOConfig",
+ (
+ "model",
+ "ref_model",
+ "args",
+ "train_dataset",
+ "eval_dataset",
+ "processing_class",
+ "data_collator",
+ "model_init",
+ "callbacks",
+ "optimizers",
+ "preprocess_logits_for_metrics",
+ "peft_config",
+ "compute_metrics",
+ "model_adapter_name",
+ "ref_adapter_name",
+ ),
+ ("ref_model", "model_adapter_name", "ref_adapter_name"),
+ True,
+ ),
+ (
+ "GRPO",
+ "MLXGRPOTrainer",
+ "MLXGRPOConfig",
+ (
+ "model",
+ "reward_funcs",
+ "args",
+ "train_dataset",
+ "eval_dataset",
+ "processing_class",
+ "reward_processing_classes",
+ "callbacks",
+ "optimizers",
+ "peft_config",
+ ),
+ ("reward_funcs", "reward_processing_classes"),
+ True,
+ ),
+ (
+ "CPO",
+ "MLXCPOTrainer",
+ "MLXCPOConfig",
+ (
+ "model",
+ "args",
+ "data_collator",
+ "train_dataset",
+ "eval_dataset",
+ "processing_class",
+ "model_init",
+ "callbacks",
+ "optimizers",
+ "preprocess_logits_for_metrics",
+ "peft_config",
+ "compute_metrics",
+ ),
+ (),
+ False,
+ ),
+ )
+
+ def _mlx_trl_config_fields(stem, zoo_config):
+ zoo_fields = {field.name: field for field in _dataclasses.fields(zoo_config)}
+ defaults = dict(_MLX_TRL_CONFIG_DEFAULTS)
+ if stem in _MLX_TRL_VERSIONED_DEFAULTS:
+ since, changed = _MLX_TRL_VERSIONED_DEFAULTS[stem]
+ # Read the install, not trl.__version__: touching the module can pull torch.
+ try:
+ if _Version(_package_version("trl")) >= _Version(since):
+ defaults.update(changed)
+ except _PackageNotFoundError:
+ pass
+ if "scale_rewards" in zoo_fields:
+ defaults["scale_rewards"] = zoo_fields["scale_rewards"].default
+ fields = [
+ (name, _MLX_TRL_CONFIG_TYPES.get(name) or zoo_fields[name].type, value)
+ for name, value in defaults.items()
+ ]
+ if stem == "DPO":
+ # HfArgumentParser drops a plain default on a list field, and TRL types this one list[str].
+ fields.append(
+ ("loss_type", list[str], _dataclasses.field(default_factory = lambda: ["sigmoid"]))
+ )
+ return fields
+
+ def _build_mlx_trl_policy_trainers():
+ aliases = {
+ key: value
+ for key, value in _MLX_TRAINING_ARGUMENT_ALIASES.items()
+ if key != "max_length"
+ }
+ built = {}
+ for stem, trainer, config, positional, extra, keep_order in _MLX_TRL_POLICY_TRAINERS:
+ zoo_trainer = getattr(_mlx_zoo_trainer, trainer, None)
+ zoo_config = getattr(_mlx_zoo_trainer, config, None)
+ if zoo_trainer is None or zoo_config is None:
+ continue
+ # Real field defaults, since HfArgumentParser reads them instead of calling the config bare.
+ config_class = _dataclasses.make_dataclass(
+ f"{stem}Config",
+ _mlx_trl_config_fields(stem, zoo_config),
+ bases = (_MLXTRLConfig, zoo_config),
+ init = False,
+ namespace = {"__module__": __name__, "_unsloth_mlx_argument_aliases": aliases},
+ )
+ built[f"{stem}Config"] = config_class
+ # Pickle finds a class by module and name; importing unsloth also installs the trl shim.
+ globals()[f"{stem}Config"] = config_class
+ built[f"{stem}Trainer"] = type(
+ f"{stem}Trainer",
+ (_MLXTRLPolicyTrainer, zoo_trainer),
+ {
+ "_unsloth_mlx_trainer_name": f"{stem}Trainer",
+ "_unsloth_mlx_positional_kwargs": positional,
+ "_unsloth_mlx_extra_kwargs": frozenset(extra),
+ "_unsloth_mlx_config_class": config_class,
+ "_unsloth_mlx_keep_dataset_order": keep_order,
+ },
+ )
+ return built
+
+ from importlib.metadata import PackageNotFoundError as _PackageNotFoundError
+ from importlib.metadata import version as _package_version
+
+ from packaging.version import Version as _Version
+
from ._mlx_trl_all import (
install_lazy_trl_all as _install_lazy_trl_all,
raw_trl_all as _raw_trl_all,
@@ -1639,20 +2110,27 @@ if _IS_MLX:
_trl.__spec__ = _machinery.ModuleSpec("trl", loader = None, is_package = True)
_sys.modules["trl"] = _trl
- _trl.SFTTrainer = UnslothTrainer
- _trl.SFTConfig = _MLXSFTConfig
+ _mapped = {"SFTConfig": _MLXSFTConfig, "SFTTrainer": UnslothTrainer}
+ _mapped.update(_build_mlx_trl_policy_trainers())
+ for _name, _shim in _mapped.items():
+ setattr(_trl, _name, _shim)
+ _mlx_trl_mapped_names.update(_mapped)
+ _supported = sorted(
+ _name[: -len("Trainer")] for _name in _mapped if _name.endswith("Trainer")
+ )
# Names come from trl's __all__, never a getattr probe: that triggers trl's lazy import and pulls torch.
_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"
+ _n for _n in _trl_exports if _n.endswith("Trainer")
}
+ _unsupported -= set(_mapped)
for _name in _unsupported:
_current = vars(_trl).get(_name)
if getattr(_current, "_unsloth_mlx_unsupported", False):
continue
if _name in _trl_exports or _current is not None:
- setattr(_trl, _name, _make_mlx_unsupported_trl_trainer(_name))
+ setattr(_trl, _name, _make_mlx_unsupported_trl_trainer(_name, _supported))
# 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__ = True