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
# SPDX-License-Identifier: AGPL-3.0-only
# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved.
"""save_method='lora' must reach the adapter save, not a 16bit merge; None must mean safetensors."""
from __future__ import annotations
import ast
import contextlib
import json
import os
import sys
import types
from pathlib import Path
import pytest
_SAVE_PY = Path(__file__).resolve().parent.parent.parent / "unsloth" / "save.py"
_SOURCE = _SAVE_PY.read_text(encoding = "utf-8")
_TREE = ast.parse(_SOURCE)
def _function_source(name: str) -> str:
for node in ast.walk(_TREE):
if isinstance(node, ast.FunctionDef) and node.name == name:
segment = ast.get_source_segment(_SOURCE, node)
indent = len(segment) - len(segment.lstrip())
if indent:
segment = "\n".join(line[indent:] for line in segment.split("\n"))
return segment
raise AssertionError(f"{name} not found in unsloth/save.py")
def _load(*names, **env):
"""Exec the named top-level functions against `env` and return the namespace."""
# save.py imports this from models.mistral_format (#12144) and calls it on every merge and
# GGUF path; none of these fixtures is a Mistral-format view, so it never refuses here.
namespace = {
"raise_if_merging_mistral_format_view": lambda model, save_method: None,
"lora_relative_to_original_base": lambda model: contextlib.nullcontext(),
# Unmerges FSDP2 streamed layers when a save raises; these fixtures never stream.
"_unmerge_flags_on_error": lambda streamed: contextlib.nullcontext(),
"nullcontext": contextlib.nullcontext,
# Full saves add bare Params4bit quant state (fused 4-bit experts); none in these fixtures.
"PeftModel": type("PeftModel", (), {}),
"_save_bare_params4bit_quant_state": lambda model: contextlib.nullcontext(),
"_with_bare_params4bit_state_dict": lambda model, original, args, kwargs: (args, kwargs),
**env,
}
for name in names:
exec(compile(_function_source(name), str(_SAVE_PY), "exec"), namespace)
return namespace
@pytest.mark.parametrize(
"value, expected",
[(None, True), (True, True), (False, False)],
)
def test_none_means_the_safetensors_default(value, expected):
"""`None` is the documented override, so it must not fall through as falsy."""
namespace = _load("_normalize_safe_serialization")
assert namespace["_normalize_safe_serialization"](value) is expected
@pytest.mark.parametrize(
"value, expected",
[
("lora", True),
("LoRA", True),
(" lora ", True),
("Lora", True),
("merged_16bit", False),
("merged_4bit", False),
("merged 16bit", False),
("mxfp4", False),
("lora_16bit", False),
("", False),
(None, False),
(17, False),
],
)
def test_the_adapter_save_method_is_spelled_the_same_way_everywhere(value, expected):
"""None and other non-strings must answer False, not raise; Studio passes None for whisper."""
namespace = _load("_is_adapter_save_method")
assert namespace["_is_adapter_save_method"](value) is expected
def test_push_keywords_this_transformers_cannot_take_are_dropped():
"""transformers 5 removed `use_temp_dir` and `safe_serialization` from push_to_hub."""
warnings_seen = []
namespace = _load(
"_filter_push_to_hub_kwargs",
logger = types.SimpleNamespace(warning_once = lambda message: warnings_seen.append(message)),
)
def transformers_5_push(
repo_id,
*,
commit_message = None,
commit_description = None,
private = None,
token = None,
revision = None,
create_pr = False,
max_shard_size = "50GB",
tags = None,
):
raise AssertionError("not called")
kept = namespace["_filter_push_to_hub_kwargs"](
transformers_5_push,
dict(
repo_id = "owner/model",
use_temp_dir = None,
safe_serialization = True,
max_shard_size = "5GB",
tags = ["unsloth"],
),
)
assert kept == dict(repo_id = "owner/model", max_shard_size = "5GB", tags = ["unsloth"])
assert warnings_seen == []
def test_a_dropped_pickle_request_is_reported():
"""`safe_serialization = False` asked for a pickle and will not get one: say so."""
warnings_seen = []
namespace = _load(
"_filter_push_to_hub_kwargs",
logger = types.SimpleNamespace(warning_once = lambda message: warnings_seen.append(message)),
)
def transformers_5_push(repo_id, *, token = None):
raise AssertionError("not called")
kept = namespace["_filter_push_to_hub_kwargs"](
transformers_5_push,
dict(repo_id = "owner/model", safe_serialization = False),
)
assert kept == dict(repo_id = "owner/model")
assert len(warnings_seen) == 1 and "safe_serialization" in warnings_seen[0]
def test_a_var_keyword_signature_keeps_everything():
"""peft's own wrappers take **kwargs, so nothing may be filtered out of them."""
namespace = _load(
"_filter_push_to_hub_kwargs", logger = types.SimpleNamespace(warning_once = lambda m: None)
)
def anything(repo_id, **kwargs):
raise AssertionError("not called")
arguments = dict(repo_id = "owner/model", use_temp_dir = True, safe_serialization = False)
assert namespace["_filter_push_to_hub_kwargs"](anything, arguments) == arguments
def test_an_unreadable_callable_is_left_alone():
"""An object with no readable signature forwards unchanged, which is what main did."""
namespace = _load(
"_filter_push_to_hub_kwargs", logger = types.SimpleNamespace(warning_once = lambda m: None)
)
arguments = dict(repo_id = "owner/model", use_temp_dir = True)
assert namespace["_filter_push_to_hub_kwargs"](object(), arguments) == arguments
class _PeftModel:
"""Stands in for `peft.PeftModel`; the branch under test is an isinstance check."""
def __init__(self):
self.config = types.SimpleNamespace(_name_or_path = "base/model", model_type = "llama")
self.saved = []
def state_dict(self):
return {}
def save_pretrained(self, directory, **kwargs):
self.saved.append((directory, kwargs))
class _FullModel:
"""A model with no adapter. Deliberately NOT a subclass of the PeftModel stand-in, so
the isinstance check the branch turns on answers False here."""
def __init__(self):
self.config = types.SimpleNamespace(_name_or_path = "base/model", model_type = "llama")
self.saved = []
def state_dict(self):
return {}
def save_pretrained(self, directory, **kwargs):
self.saved.append((directory, kwargs))
# Run as real code: each decides how a save is routed or refused. Everything else is stubbed;
# test_every_helper_the_generic_save_calls_is_loaded_or_stubbed keeps both lists complete.
_GENERIC_SAVE_REAL_HELPERS = (
"_normalize_safe_serialization",
"_is_adapter_save_method",
"_honours_safe_serialization",
"_refuse_unsaveable_text_core",
"_cast_state_dict_16bit",
"_requests_float32",
"_stamp_saved_config_float32",
)
_GENERIC_SAVE_STUBBED_HELPERS = frozenset(
{
"patch_saving_functions",
"_push_merged_to_hub_revision",
"_prewarm_base_model_hub_cache",
"_is_qwen3_5_vlm",
"_qwen3_5_vlm_state_dict_for_save",
"_determine_username",
"unsloth_save_model",
# Trained MTP head hooks: no head is attached in these fixtures.
"_refuse_mtp_variant",
"_attached_mtp_head",
"_internal_mtp_save",
"_stitch_mtp_head",
"_mtp_head_tensor_names",
"_unmerge_flags_on_error",
# LFM3-Audio config rewrite: no LFM3-Audio checkpoint in these fixtures.
"_release_layout_for_merged_save",
"_push_lfm3_audio_release_config",
# Decorator factory; _load strips decorators.
"_model_parallel_refuses_save",
}
)
def _not_reached(*args, **kwargs):
raise AssertionError("the routing harness does not reach this helper")
def _routing_environment(monkeypatch, model):
calls = {"merge": [], "adapter": [], "prewarm": [], "convert": []}
zoo = types.ModuleType("unsloth_zoo.saving_utils")
zoo.merge_and_overwrite_lora = lambda *args, **kwargs: calls["merge"].append(kwargs)
monkeypatch.setitem(sys.modules, "unsloth_zoo.saving_utils", zoo)
namespace = _load(
*_GENERIC_SAVE_REAL_HELPERS,
"_collect_garbage",
"unsloth_generic_save",
os = os,
json = json,
PeftModel = _PeftModel,
PreTrainedTokenizerBase = type("Tokenizer", (), {}),
ProcessorMixin = type("Processor", (), {}),
patch_saving_functions = lambda tokenizer: tokenizer,
get_token = lambda: "fixture-token",
get_model_name = lambda name: name,
_push_merged_to_hub_revision = lambda kwargs: calls.setdefault("revision", []).append(kwargs),
_prewarm_base_model_hub_cache = lambda *args, **kwargs: calls["prewarm"].append(kwargs),
_is_qwen3_5_vlm = lambda model: False,
_qwen3_5_vlm_state_dict_for_save = _not_reached,
_determine_username = lambda repo, old, token: (repo, "owner"),
unsloth_save_model = lambda *args, **kwargs: calls["adapter"].append(kwargs),
_refuse_mtp_variant = lambda model, variant: None,
_attached_mtp_head = lambda model: None,
_internal_mtp_save = contextlib.nullcontext,
_stitch_mtp_head = lambda model, directory: None,
_mtp_head_tensor_names = lambda model: [],
_release_layout_for_merged_save = lambda model, directory, method: False,
_push_lfm3_audio_release_config = lambda model, save_directory, token = None: False,
lora_relative_to_original_base = lambda model: (
calls["convert"].append(model) or contextlib.nullcontext()
),
logger = types.SimpleNamespace(warning_once = lambda *a, **k: None),
gc = types.SimpleNamespace(collect = lambda: None, get_stats = lambda: [{}, {}, {}]),
torch = types.SimpleNamespace(
bfloat16 = "bfloat16",
float16 = "float16",
float32 = "float32",
save = lambda *args, **kwargs: None,
cuda = types.SimpleNamespace(is_bf16_supported = lambda: False),
),
)
return namespace["unsloth_generic_save"], calls
@pytest.mark.parametrize("spelling", ["lora", "LoRA", " lora "])
def test_an_adapter_save_never_reaches_the_merge(monkeypatch, tmp_path, spelling):
"""The defect: "lora" matched no branch inside the merge and was merged anyway."""
model = _PeftModel()
generic_save, calls = _routing_environment(monkeypatch, model)
generic_save(model, None, save_directory = str(tmp_path), save_method = spelling)
assert calls["merge"] == [], "save_method='lora' must not call merge_and_overwrite_lora"
assert len(calls["adapter"]) == 1
# Canonical spelling: unsloth_save_model turns " lora " into "_lora_" and rejects it.
assert calls["adapter"][0]["save_method"] == "lora"
assert calls["adapter"][0]["save_directory"] == str(tmp_path)
# The base is only needed to merge against, so nothing is downloaded for it.
assert calls["prewarm"] == []
def test_the_adapter_save_method_the_router_forwards_is_one_unsloth_save_model_accepts():
"""Forward the canonical spelling: unsloth_save_model rejects a padded ' lora ' value."""
source = Path(_SAVE_PY).read_text(encoding = "utf-8")
tree = ast.parse(source)
def _find(name):
for node in ast.walk(tree):
if isinstance(node, ast.FunctionDef) and node.name == name:
return node
raise AssertionError(f"{name} is gone from unsloth/save.py")
forwarded = [
keyword.value.value
for node in ast.walk(_find("unsloth_generic_save"))
if isinstance(node, ast.Call)
and isinstance(node.func, ast.Name)
and node.func.id == "unsloth_save_model"
for keyword in node.keywords
if keyword.arg == "save_method" and isinstance(keyword.value, ast.Constant)
]
assert forwarded == ["lora"], (
"the adapter branch must forward the canonical spelling, got " + repr(forwarded)
)
accepted = {
comparator.value
for node in ast.walk(_find("unsloth_save_model"))
if isinstance(node, ast.Compare)
for comparator in node.comparators
if isinstance(comparator, ast.Constant) and isinstance(comparator.value, str)
}
assert "lora" in accepted, "unsloth_save_model no longer names 'lora' as a save_method"
for value in forwarded:
assert (
value.lower().replace(" ", "_") in accepted
), f"unsloth_save_model would reject the forwarded save_method {value!r}"
@pytest.mark.parametrize("save_method", ["merged_16bit", "mxfp4", "fp8", "merged_4bit_forced"])
def test_every_other_method_still_merges(monkeypatch, tmp_path, save_method):
"""The merge is what changed for exactly one value of save_method and no other."""
model = _PeftModel()
generic_save, calls = _routing_environment(monkeypatch, model)
generic_save(model, None, save_directory = str(tmp_path), save_method = save_method)
assert calls["adapter"] == []
assert len(calls["merge"]) == 1
assert len(calls["prewarm"]) == 1
assert len(calls["convert"]) == (save_method != "merged_4bit_forced")
@pytest.mark.parametrize(
"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]
@pytest.mark.parametrize(
"spelling, canonical",
[
("Merged_4bit_Forced", "merged_4bit_forced"),
("forced merged 4bit", "forced_merged_4bit"),
(" Merged-16bit ", "merged_16bit"),
("LoRA", "lora"),
],
)
@pytest.mark.parametrize("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
@pytest.mark.parametrize("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"})
@pytest.mark.parametrize("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)
@pytest.mark.parametrize("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)]
)
def test_modelscope_base_is_fetched_only_when_the_merge_reads_one(
monkeypatch, tmp_path, save_method, from_modelscope
):
"""#3726: an in-place 4bit merge folds into the loaded weights, so it downloads no 16bit base."""
monkeypatch.setenv("UNSLOTH_USE_MODELSCOPE", "1")
model = _PeftModel()
generic_save, calls = _routing_environment(monkeypatch, model)
resolvers = []
sys.modules["unsloth_zoo.saving_utils"].merge_and_overwrite_lora = (
lambda resolve, **kwargs: resolvers.append(resolve)
)
namespace = generic_save.__globals__
namespace["_modelscope_base_model_name"] = lambda *args, **kwargs: None
generic_save(model, None, save_directory = str(tmp_path), save_method = save_method)
expected = "_modelscope_base_model_name" if from_modelscope else "get_model_name"
assert resolvers == [namespace[expected]]
def test_a_model_with_no_adapter_is_unchanged(monkeypatch, tmp_path):
"""A full fine-tune asked for "lora" has no adapter, so it writes itself, as before."""
model = _FullModel()
generic_save, calls = _routing_environment(monkeypatch, model)
generic_save(model, None, save_directory = str(tmp_path), save_method = "lora")
assert calls["merge"] == [] and calls["adapter"] == []
assert len(model.saved) == 1
def test_none_is_normalised_before_the_merge_is_reached(monkeypatch, tmp_path):
"""Whatever the writer, `None` must have become `True` by the time it is forwarded."""
model = _PeftModel()
generic_save, calls = _routing_environment(monkeypatch, model)
generic_save(
model, None, save_directory = str(tmp_path), save_method = "lora", safe_serialization = None
)
assert calls["adapter"][0]["safe_serialization"] is True
model = _FullModel()
generic_save, calls = _routing_environment(monkeypatch, model)
generic_save(
model,
None,
save_directory = str(tmp_path),
save_method = "merged_16bit",
safe_serialization = None,
)
assert model.saved[0][1]["safe_serialization"] is True
def _adapter_save_environment(monkeypatch):
# unsloth_save_model checks credentials via whoami before pushing; these tests stay offline.
import huggingface_hub
monkeypatch.setattr(huggingface_hub, "whoami", lambda token = None: {"name": "owner"})
# Stubbed, not importorskip'd, so this file still gates the cross-platform runners, which ship no peft.
if "peft" not in sys.modules:
peft = types.ModuleType("peft")
peft.PeftModelForCausalLM = type("PeftModelForCausalLM", (), {})
monkeypatch.setitem(sys.modules, "peft", peft)
uploads = []
def upload_to_huggingface(*args, **kwargs):
uploads.append(kwargs)
return None
return _load(
"_normalize_safe_serialization",
"_filter_push_to_hub_kwargs",
"_collect_garbage",
"unsloth_save_model",
PreTrainedTokenizerBase = type("Tokenizer", (), {}),
ProcessorMixin = type("Processor", (), {}),
patch_saving_functions = lambda tokenizer: tokenizer,
get_token = lambda: "fixture-token",
upload_to_huggingface = upload_to_huggingface,
logger = types.SimpleNamespace(warning_once = lambda *a, **k: None),
gc = types.SimpleNamespace(collect = lambda: None, get_stats = lambda: [{}, {}, {}]),
psutil = types.SimpleNamespace(cpu_count = lambda logical = True: 8),
torch = types.SimpleNamespace(
save = lambda *args, **kwargs: None,
cuda = types.SimpleNamespace(empty_cache = lambda: None),
),
fast_save_pickle = lambda *args, **kwargs: None,
clean_gpu_cache = lambda: None,
# Trained MTP head hooks: no head is attached in these fixtures.
_refuse_mtp_variant = lambda model, variant: None,
_attached_mtp_head = lambda model: None,
_internal_mtp_save = contextlib.nullcontext,
_save_mtp_head_beside_adapter = lambda model, directory: None,
_stitch_mtp_head = lambda model, directory: None,
_mtp_head_tensor_names = lambda model: [],
), uploads
class _AdapterModel:
def __init__(self, push_signature):
self.config = types.SimpleNamespace(_name_or_path = "base/model", model_type = "llama")
self.saved = []
self.pushed = []
self.original_push_to_hub = push_signature(self.pushed)
def add_model_tags(self, tags):
pass
def push_to_hub(self, **kwargs):
# `getattr(model, "original_push_to_hub", model.push_to_hub)` evaluates its default eagerly.
raise AssertionError("the unpatched push_to_hub must not be the one called")
def save_pretrained(self, **kwargs):
self.saved.append(kwargs)
def test_the_adapter_save_forwards_a_real_safe_serialization(monkeypatch, tmp_path):
"""`None` must not reach `save_pretrained`, and the bookkeeping must not either."""
namespace, _ = _adapter_save_environment(monkeypatch)
model = _AdapterModel(lambda sink: (lambda **kwargs: sink.append(kwargs)))
namespace["unsloth_save_model"](
model,
None,
save_directory = str(tmp_path),
save_method = "lora",
safe_serialization = None,
)
assert len(model.saved) == 1
settings = model.saved[0]
assert settings["safe_serialization"] is True
assert settings["save_directory"] == str(tmp_path)
assert "_force_safe_serialization" not in settings
assert "save_method" not in settings
def test_an_adapter_push_survives_a_transformers_that_dropped_the_keywords(monkeypatch, tmp_path):
"""transformers 5's push_to_hub has no use_temp_dir, so the adapter push must not pass it."""
namespace, uploads = _adapter_save_environment(monkeypatch)
def transformers_5_signature(sink):
def push_to_hub(
repo_id,
*,
commit_message = None,
commit_description = None,
private = None,
token = None,
revision = None,
create_pr = False,
max_shard_size = "50GB",
tags = None,
):
sink.append(
dict(
repo_id = repo_id,
commit_message = commit_message,
private = private,
token = token,
revision = revision,
create_pr = create_pr,
max_shard_size = max_shard_size,
tags = tags,
)
)
return push_to_hub
model = _AdapterModel(transformers_5_signature)
namespace["unsloth_save_model"](
model,
None,
save_directory = "owner/model",
save_method = "lora",
push_to_hub = True,
token = "fixture-token",
)
assert len(model.pushed) == 1
assert model.pushed[0]["repo_id"] == "owner/model"
assert "unsloth" in model.pushed[0]["tags"]
assert len(uploads) == 1
# An adapter push goes straight to the Hub, so nothing is written locally.
assert model.saved == []
def test_an_adapter_push_still_passes_every_keyword_a_transformers_4_accepts(monkeypatch, tmp_path):
"""The filter must subtract only what the installed signature cannot take."""
namespace, _ = _adapter_save_environment(monkeypatch)
def transformers_4_signature(sink):
def push_to_hub(
repo_id,
use_temp_dir = None,
commit_message = None,
private = None,
token = None,
max_shard_size = "5GB",
create_pr = False,
safe_serialization = True,
revision = None,
commit_description = None,
tags = None,
):
sink.append(
dict(
use_temp_dir = use_temp_dir,
safe_serialization = safe_serialization,
revision = revision,
)
)
return push_to_hub
model = _AdapterModel(transformers_4_signature)
namespace["unsloth_save_model"](
model,
None,
save_directory = "owner/model",
save_method = "lora",
push_to_hub = True,
token = "fixture-token",
safe_serialization = None,
use_temp_dir = True,
revision = "candidate",
)
assert model.pushed == [dict(use_temp_dir = True, safe_serialization = True, revision = "candidate")]
def test_the_model_save_pretrained_wrapper_rewrites_only_none():
"""`model.save_pretrained(..., safe_serialization = None)` is the call in #1792."""
namespace = _load(
"unsloth_model_save_pretrained",
"_normalize_safe_serialization",
)
wrapper = namespace["unsloth_model_save_pretrained"]
class Model:
def __init__(self):
self.calls = []
def original_model_save_pretrained(self, *args, **kwargs):
self.calls.append((args, kwargs))
return "result"
model = Model()
assert wrapper(model, "out", safe_serialization = None) == "result"
assert model.calls[-1] == (("out",), {"safe_serialization": True})
wrapper(model, "out", safe_serialization = False)
assert model.calls[-1] == (("out",), {"safe_serialization": False})
wrapper(model, "out", max_shard_size = "5GB")
assert model.calls[-1] == (("out",), {"max_shard_size": "5GB"})
def test_the_wrapper_is_installed_on_models_and_is_idempotent():
"""A second `patch_saving_functions` must not wrap the wrapper."""
source = _function_source("patch_saving_functions")
assert "model.original_model_save_pretrained = model.save_pretrained" in source
assert '!= "unsloth_model_save_pretrained"' in source
# A distinct attribute name, so the tokenizer wrapper above is not shadowed.
assert "original_save_pretrained" in source and "original_model_save_pretrained" in source
def test_the_generated_push_to_hub_normalises_none():
"""`unsloth_push_to_hub` is built from a source template, so gate it as source."""
source = _function_source("patch_saving_functions")
assert 'arguments["safe_serialization"] is None' in source
assert 'arguments["safe_serialization"] = True' in source
def test_the_documented_advice_no_longer_tells_anyone_to_pass_none_for_a_pickle():
"""The warning used to say "to force safe_serialization, set it to None"."""
assert "To force `safe_serialization`, set it to `None` instead." not in _SOURCE
assert "`safe_serialization` defaults to safetensors" in _SOURCE
def _sentence_transformer_source():
path = (
Path(__file__).resolve().parent.parent.parent
/ "unsloth"
/ "models"
/ "sentence_transformer.py"
)
return path.read_text(encoding = "utf-8"), ast.parse(path.read_text(encoding = "utf-8"))
def _modules_branch_save_pretrained_merged(tree):
"""The second _save_pretrained_merged forwards save_method to auto_model, so it inherits 'lora'."""
found = [
node
for node in ast.walk(tree)
if isinstance(node, ast.FunctionDef) and node.name == "_save_pretrained_merged"
]
assert len(found) == 2, f"expected two definitions, found {len(found)}"
keeps_save_method = [
node
for node in found
if any(
isinstance(call, ast.Call)
and getattr(getattr(call.func, "attr", None), "__str__", lambda: "")() == "setdefault"
for call in ast.walk(node)
)
]
assert len(keeps_save_method) == 1
return keeps_save_method[0]
def test_sentence_transformer_merge_refuses_the_adapter_save_method():
"""lora' here leaves a SentenceTransformer dir with no model, so the merge branch must refuse it."""
_, tree = _sentence_transformer_source()
node = _modules_branch_save_pretrained_merged(tree)
guards = [
call
for call in ast.walk(node)
if isinstance(call, ast.Call)
and isinstance(call.func, ast.Name)
and call.func.id == "_is_adapter_save_method"
]
assert guards, (
"the modules branch of _save_pretrained_merged forwards save_method = 'lora' to "
"the adapter save, which writes no base weights into the SentenceTransformer "
"directory it is building"
)
raises = [
stmt
for stmt in ast.walk(node)
if isinstance(stmt, ast.Raise)
and isinstance(stmt.exc, ast.Call)
and getattr(stmt.exc.func, "id", "") == "NotImplementedError"
]
assert len(raises) >= 2, "the adapter method has to be refused, not warned about"
def test_sentence_transformer_shares_the_router_definition_of_lora():
"""One definition of the spellings, so the two files cannot drift apart."""
source, _ = _sentence_transformer_source()
assert "_is_adapter_save_method" in source
assert "from ..save import" in source
def test_the_lora_docstring_does_not_promise_an_adapter_only_directory():
"""Adapter saves may write tokenizer files too; the guarantee is no base-model weights."""
import re
from pathlib import Path
source = (Path(__file__).resolve().parents[2] / "unsloth" / "save.py").read_text(
encoding = "utf-8",
)
assert "and nothing else. Useful for HF inference." not in source, (
"a save_method='lora' docstring still promises an adapter-only directory, which a "
"call that passes `tokenizer` does not produce"
)
promises = re.findall(r"`adapter_model\.safetensors`,[^\n]*", source)
assert promises, "the save_method list no longer names adapter_model.safetensors"
for promise in promises:
assert "no base-model weights" in promise, promise
@pytest.mark.parametrize("spelling", ["lora", "LoRA", " lora ", " LORA", "lora\t", " Lora "])
def test_the_sentence_transformer_normaliser_keeps_whitespace_aliases_recognisable(spelling):
"""_normalize_save_method must not turn an accepted spelling like ' lora ' into a rejected one."""
from unsloth.models.sentence_transformer import _normalize_save_method
from unsloth.save import _is_adapter_save_method
assert _is_adapter_save_method(spelling), "the router already calls this spelling LoRA"
assert _is_adapter_save_method(_normalize_save_method(spelling)), (
f"_normalize_save_method({spelling!r}) produced "
f"{_normalize_save_method(spelling)!r}, which the adapter guard no longer accepts"
)
@pytest.mark.parametrize(
"spelling, expected",
[
("merged_16bit", "merged_16bit"),
(" MERGED 16BIT ", "merged_16bit"),
("merged 16bit", "merged_16bit"),
# NEGATIVE CONTROL: Studio passes None for whisper; unrelated methods are not rewritten.
(None, None),
("fp8", "fp8"),
],
)
def test_the_sentence_transformer_normaliser_is_otherwise_unchanged(spelling, expected):
from unsloth.models.sentence_transformer import _normalize_save_method
assert _normalize_save_method(spelling) == expected
def test_the_docstrings_describe_none_as_the_stronger_safetensors_request():
"""None forces safetensors via _force_safe_serialization; it is not a synonym for the default True."""
from pathlib import Path
save_py = Path(__file__).resolve().parents[2] / "unsloth" / "save.py"
source = save_py.read_text(encoding = "utf-8")
assert (
"`None` is accepted and means the same thing" not in source
), "a docstring still equates None with the default True"
assert (
source.count("`None` is stronger than the default") == 4
), "all four save_method docstrings have to describe None the same way"
assert "elif safe_serialization and (n_cpus <= 2) and not _keeps_mtp_head:" in source
assert "if _force_safe_serialization:" in source
def _wrapped_model_save_pretrained(original):
"""The shipped `unsloth_model_save_pretrained`, bound to a stub whose
`original_model_save_pretrained` is `original`. Executed, not read."""
import ast
import inspect
import textwrap
import types as _types
from unsloth import save as save_module
source = inspect.getsource(save_module.patch_saving_functions)
tree = ast.parse(textwrap.dedent(source))
node = next(
n
for n in ast.walk(tree)
if isinstance(n, ast.FunctionDef) and n.name == "unsloth_model_save_pretrained"
)
module = ast.Module(body = [node], type_ignores = [])
ast.fix_missing_locations(module)
namespace = dict(vars(save_module))
exec(compile(module, "<unsloth_model_save_pretrained>", "exec"), namespace)
stub = _types.SimpleNamespace(original_model_save_pretrained = original)
return _types.MethodType(namespace["unsloth_model_save_pretrained"], stub)
def test_a_positional_none_is_normalised_on_a_peft_style_signature():
"""`PeftModel.save_pretrained` takes safe_serialization as its SECOND positional
parameter, so `model.save_pretrained(directory, None)` is the same request as the
keyword form and used to reach peft as a falsy value, writing adapter_model.bin."""
seen = {}
def peft_like(
save_directory,
safe_serialization = True,
selected_adapters = None,
**kwargs,
):
seen["safe_serialization"] = safe_serialization
seen["save_directory"] = save_directory
_wrapped_model_save_pretrained(peft_like)("out_dir", None)
assert seen["save_directory"] == "out_dir"
assert seen["safe_serialization"] is True
def test_a_positional_second_argument_that_is_not_safe_serialization_is_untouched():
"""NEGATIVE CONTROL, and the reason the position cannot be assumed:
`PreTrainedModel.save_pretrained`'s second parameter is `is_main_process`, so
rewriting index 1 would corrupt an ordinary transformers call."""
seen = {}
def transformers_like(
save_directory,
is_main_process = True,
state_dict = None,
**kwargs,
):
seen["is_main_process"] = is_main_process
seen["kwargs"] = kwargs
_wrapped_model_save_pretrained(transformers_like)("out_dir", None)
assert seen["is_main_process"] is None, "an unrelated positional argument was rewritten"
assert "safe_serialization" not in seen["kwargs"]
def test_an_explicit_positional_false_still_writes_a_pickle():
"""NEGATIVE CONTROL: only None is rewritten. False is a request, not the default."""
seen = {}
def peft_like(
save_directory,
safe_serialization = True,
**kwargs,
):
seen["safe_serialization"] = safe_serialization
_wrapped_model_save_pretrained(peft_like)("out_dir", False)
assert seen["safe_serialization"] is False
def test_an_unreadable_signature_forwards_the_call_unchanged():
"""A builtin or C callable has no readable signature; that must not break the save."""
seen = {}
class _NoSignature:
def __call__(self, *args, **kwargs):
seen["args"] = args
seen["kwargs"] = kwargs
_wrapped_model_save_pretrained(_NoSignature())("out_dir", None)
assert seen["args"] == ("out_dir", None)
def test_every_helper_the_generic_save_calls_is_loaded_or_stubbed():
"""A helper added to unsloth_generic_save and missing here surfaces as a NameError in every
routing test at once (#11526's _refuse_unsaveable_text_core did). Name it instead."""
top_level = {node.name for node in _TREE.body if isinstance(node, ast.FunctionDef)}
generic_save = next(
node
for node in _TREE.body
if isinstance(node, ast.FunctionDef) and node.name == "unsloth_generic_save"
)
called = {
node.func.id
for node in ast.walk(generic_save)
if isinstance(node, ast.Call)
and isinstance(node.func, ast.Name)
and node.func.id in top_level
}
covered = set(_GENERIC_SAVE_REAL_HELPERS) | _GENERIC_SAVE_STUBBED_HELPERS
assert called <= covered, (
f"unsloth_generic_save calls {sorted(called - covered)} from save.py, which the routing "
"harness neither loads nor stubs"
)
assert (
covered <= called
), f"{sorted(covered - called)} are no longer called by unsloth_generic_save"