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.

Normalize save_method before the merge so a respelled merged_16bit still writes config.json (#16933)

Vineeth Sai Varikuntla3696d7d3274c
diff --git a/tests/saving/test_save_method_lora_routing.py b/tests/saving/test_save_method_lora_routing.py
index e7daebe45e4..86e3212781f 100644
--- a/tests/saving/test_save_method_lora_routing.py
+++ b/tests/saving/test_save_method_lora_routing.py
@@ -345,6 +345,100 @@ def test_every_other_method_still_merges(monkeypatch, tmp_path, save_method):
assert len(calls["convert"]) == (save_method != "merged_4bit_forced")
+ "spelling, canonical",
+ [
+ ("Merged_16bit", "merged_16bit"),
+ ("merged 16bit", "merged_16bit"),
+ ("merged-16bit", "merged_16bit"),
+ (" merged_16bit ", "merged_16bit"),
+ ("Merged_4bit_Forced", "merged_4bit"),
+ ],
+)
+def test_a_respelled_merge_method_reaches_the_merge_canonically(
+ monkeypatch, tmp_path, spelling, canonical
+):
+ """The merge writes config.json only for the exact string, so a respelling saved no config."""
+ model = _PeftModel()
+ generic_save, calls = _routing_environment(monkeypatch, model)
+ generic_save(model, None, save_directory = str(tmp_path), save_method = spelling)
+ assert [c["save_method"] for c in calls["merge"]] == [canonical]
+
+
+ "spelling, canonical",
+ [
+ ("Merged_4bit_Forced", "merged_4bit_forced"),
+ ("forced merged 4bit", "forced_merged_4bit"),
+ (" Merged-16bit ", "merged_16bit"),
+ ("LoRA", "lora"),
+ ],
+)
[email protected]("by_keyword", [True, False])
+def test_the_fsdp2_gather_placement_reads_the_canonical_method(spelling, canonical, by_keyword):
+ """FSDP2 picks where gathered weights live before unsloth_generic_save canonicalizes, so a
+ respelled merged_4bit offloaded the LoRA operands its in-place merge needs on the GPU."""
+ ns = _load("_merged_save_method", "_fsdp2_merged_offload")
+ args, kwargs = ((), {"save_method": spelling}) if by_keyword else (("d", None, spelling), {})
+ assert ns["_merged_save_method"](args, kwargs) == canonical
+ fsdp2 = types.ModuleType("unsloth.models.fsdp2_save")
+ fsdp2.offload_all_but_4bit_merge_operands = lambda model: "keep-4bit-merge-operands"
+ with pytest.MonkeyPatch.context() as mp:
+ mp.setitem(sys.modules, "unsloth.models.fsdp2_save", fsdp2)
+ ns["__package__"] = "unsloth"
+ ns["__name__"] = "unsloth.save"
+ offload = ns["_fsdp2_merged_offload"](object(), args, kwargs)
+ assert offload == ("keep-4bit-merge-operands" if "4bit" in canonical else True)
+ assert ns["_merged_save_method"]((), {}) == "merged_16bit"
+ assert ns["_merged_save_method"]((), {"save_method": None}) is None
+
+
[email protected]("spelling", ["merged-4bit-forced", "Merged 4bit", "forced-merged-4bit"])
+def test_a_respelled_in_place_merge_is_refused_under_tensor_parallel(spelling):
+ refuse = _load(
+ "_refuse_tp_in_place_merge",
+ _TP_IN_PLACE_MERGES = ("merged_4bit", "merged_4bit_forced", "forced_merged_4bit"),
+ )["_refuse_tp_in_place_merge"]
+
+ def fn(
+ save_directory,
+ tokenizer = None,
+ save_method = "merged_16bit",
+ ):
+ pass
+
+ for args, kwargs in ((("d", None, spelling), {}), (("d",), {"save_method": spelling})):
+ with pytest.raises(RuntimeError, match = "tensor parallel"):
+ refuse(fn, "save_pretrained_merged", args, kwargs)
+ refuse(fn, "save_pretrained_merged", ("d",), {"save_method": "merged-16bit"})
+
+
[email protected]("spelling", ["Merged_4bit", "merged-4bit", " MERGED 4BIT "])
+def test_unsloth_save_model_guards_a_respelled_merged_4bit(spelling):
+ """unsloth_save_model checked the guard before lowercasing, then merged into 4bit anyway."""
+ save_model = _load(
+ "unsloth_save_model",
+ torch = types.SimpleNamespace(save = None),
+ _refuse_mtp_variant = lambda model, variant: None,
+ _attached_mtp_head = lambda model: None,
+ PreTrainedTokenizerBase = type("T", (), {}),
+ ProcessorMixin = type("P", (), {}),
+ _normalize_safe_serialization = lambda value: True,
+ get_token = lambda: None,
+ )["unsloth_save_model"]
+ with pytest.raises(RuntimeError, match = "merged_4bit_forced"):
+ save_model(object(), None, "d", save_method = spelling)
+
+
[email protected]("spelling", ["Merged_4bit", "merged-4bit", " MERGED 4BIT "])
+def test_a_respelled_merged_4bit_still_hits_the_accuracy_guard(monkeypatch, tmp_path, spelling):
+ model = _PeftModel()
+ generic_save, calls = _routing_environment(monkeypatch, model)
+ with pytest.raises(RuntimeError, match = "merged_4bit_forced"):
+ generic_save(model, None, save_directory = str(tmp_path), save_method = spelling)
+ assert calls["merge"] == []
+
+
@pytest.mark.parametrize(
"save_method, from_modelscope", [("merged_16bit", True), ("merged_4bit_forced", False)]
)
diff --git a/tests/test_st_save_merged_signature.py b/tests/test_st_save_merged_signature.py
index b5c08e9cd0c..5b0d351d3bb 100644
--- a/tests/test_st_save_merged_signature.py
+++ b/tests/test_st_save_merged_signature.py
@@ -352,7 +352,7 @@ def test_the_reference_normalizes_before_validating():
body = ast.get_source_segment(
SAVE_PY.read_text(encoding = "utf-8"), _defs("unsloth_save_model", SAVE_PY)[0]
)
- assert 'save_method.lower().replace(" ", "_")' in body
+ assert 'save_method.lower().strip().replace("-", "_").replace(" ", "_")' in body
@pytest.mark.parametrize("method", ["MERGED_16BIT", "merged 16bit", "Merged_16bit"])
diff --git a/unsloth/save.py b/unsloth/save.py
index 2bfa13f8776..53e4607cdd2 100644
--- a/unsloth/save.py
+++ b/unsloth/save.py
@@ -1528,7 +1528,10 @@ def _refuse_tp_in_place_merge(fn, method, args, kwargs):
)
except (TypeError, ValueError):
save_method = kwargs.get("save_method")
- if isinstance(save_method, str) and save_method.lower().strip() in _TP_IN_PLACE_MERGES:
+ if (
+ isinstance(save_method, str)
+ and save_method.lower().strip().replace("-", "_").replace(" ", "_") in _TP_IN_PLACE_MERGES
+ ):
raise RuntimeError(
f'Unsloth: `{method}(save_method = "{save_method}")` merges the LoRA weights into the 4-bit base in '
"place (merge_and_unload). On a tensor parallel model only rank 0 would end up with that merged "
@@ -1642,6 +1645,8 @@ def unsloth_save_model(
elif "Unsloth 2x faster" not in commit_description:
commit_description += " (Trained with Unsloth 2x faster)"
+ if isinstance(save_method, str):
+ save_method = save_method.lower().strip().replace("-", "_").replace(" ", "_")
if save_method == "merged_4bit":
raise RuntimeError(
"Unsloth: Merging into 4bit will cause your model to lose accuracy if you plan\n"
@@ -1678,7 +1683,6 @@ def unsloth_save_model(
_collect_garbage(before = clean_gpu_cache)
- save_method = save_method.lower().replace(" ", "_")
raise_if_merging_mistral_format_view(model, save_method)
if save_method != "lora" and save_method != "merged_16bit" and save_method != "merged_4bit":
raise RuntimeError(
@@ -6896,6 +6900,9 @@ def unsloth_generic_save(
dtype = None,
):
_refuse_mtp_variant(model, variant)
+ # merge_and_overwrite_lora compares save_method exactly, so respellings must be canonical here.
+ if isinstance(save_method, str):
+ save_method = save_method.lower().strip().replace("-", "_").replace(" ", "_")
if save_method == "merged_4bit":
raise RuntimeError(
"Unsloth: Merging into 4bit will cause your model to lose accuracy if you plan\n"
@@ -7279,10 +7286,15 @@ def _fsdp2_rank():
def _merged_save_method(args, kwargs):
- if "save_method" in kwargs:
- return kwargs["save_method"]
- # (save_directory, tokenizer, save_method, ...)
- return args[2] if len(args) > 2 else "merged_16bit"
+ # (save_directory, tokenizer, save_method, ...); canonical, as unsloth_generic_save sees it.
+ method = (
+ kwargs["save_method"]
+ if "save_method" in kwargs
+ else (args[2] if len(args) > 2 else "merged_16bit")
+ )
+ if isinstance(method, str):
+ method = method.lower().strip().replace("-", "_").replace(" ", "_")
+ return method
def _fsdp2_merged_offload(model, args, kwargs):