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.

13.2 KB
Raw Blame
# Copyright 2023-present Daniel Han-Chen & the Unsloth team. All rights reserved.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

"""Some ST repos keep weights at the root and in subfolders; the subfolder prune must skip them."""

import json
import sys
import types
from pathlib import Path

import pytest

sys.path.insert(0, str(Path(__file__).resolve().parents[1]))

import unsloth.models._utils as U  # noqa: E402


ROOT_ONLY = [
    {"idx": 0, "name": "0", "path": "", "type": "sentence_transformers.models.Transformer"},
    {"idx": 1, "name": "1", "path": "1_Pooling", "type": "sentence_transformers.models.Pooling"},
]

EMBEDDINGGEMMA = ROOT_ONLY + [
    {"idx": 2, "name": "2", "path": "2_Dense", "type": "sentence_transformers.models.Dense"},
    {"idx": 3, "name": "3", "path": "3_Dense", "type": "sentence_transformers.models.Dense"},
    {"idx": 4, "name": "4", "path": "", "type": "sentence_transformers.models.Normalize"},
]


@pytest.fixture
def modules_json(tmp_path, monkeypatch):
    """Stub hf_hub_download so it hands back a modules.json we control."""

    def _install(payload):
        if payload is None:  # repo ships no modules.json

            def boom(*a, **k):
                raise OSError("404 modules.json")

            monkeypatch.setattr(U, "hf_hub_download", boom, raising = False)
            import huggingface_hub

            monkeypatch.setattr(huggingface_hub, "hf_hub_download", boom)
            return
        p = tmp_path / "modules.json"
        p.write_text(payload if isinstance(payload, str) else json.dumps(payload), encoding = "utf-8")
        import huggingface_hub

        monkeypatch.setattr(huggingface_hub, "hf_hub_download", lambda *a, **k: str(p))

    return _install


def test_embeddinggemma_layout_is_detected(modules_json):
    modules_json(EMBEDDINGGEMMA)
    assert U._repo_has_weighted_st_subfolders("unsloth/embeddinggemma-300m") is True


def test_a_root_only_st_model_is_not(modules_json):
    """Pooling lives in a subfolder but holds no weight, so nothing is at risk
    and the existing subdir pruning should stay in force."""
    modules_json(ROOT_ONLY)
    assert U._repo_has_weighted_st_subfolders("org/plain-st") is False


def test_a_repo_without_modules_json_is_not(modules_json):
    """Plain causal LMs, the overwhelming majority, must keep the old behaviour exactly so a fix for
    one notebook does not enlarge other downloads."""
    modules_json(None)
    assert U._repo_has_weighted_st_subfolders("unsloth/Qwen3-0.6B") is False


@pytest.mark.parametrize(
    "payload",
    [
        "{ not json",
        json.dumps({"not": "a list"}),
        json.dumps([None, 3, "x"]),
        json.dumps([{"path": "2_Dense"}]),
        json.dumps([{"type": "...Dense"}]),
        json.dumps([{"path": "  ", "type": "...Dense"}]),
        json.dumps([{"path": "/", "type": "...Dense"}]),
    ],
)
def test_malformed_modules_json_falls_back_to_the_old_behaviour(modules_json, payload):
    """Best-effort by design: anything unreadable must not start failing loads
    that work today."""
    modules_json(payload)
    assert U._repo_has_weighted_st_subfolders("org/whatever") is False


def test_an_unknown_subfolder_module_type_is_not_assumed_weighted(modules_json):
    modules_json([{"path": "2_Custom", "type": "mypkg.WeirdModule"}])
    assert U._repo_has_weighted_st_subfolders("org/custom") is False


@pytest.mark.parametrize("leaf", ["Dense", "CNN", "LSTM", "dense"])
def test_every_weight_bearing_type_counts(modules_json, leaf):
    modules_json([{"path": f"2_{leaf}", "type": f"sentence_transformers.models.{leaf}"}])
    assert U._repo_has_weighted_st_subfolders("org/x") is True


def test_the_taxonomy_is_shared_with_unsloth_zoo_not_restated():
    """If these two ever disagree, unsloth would fetch a module the gate then
    rejects, or prune one it demands -- the exact shape of the original bug."""
    src = (Path(U.__file__)).read_text(encoding = "utf-8")
    assert "_ST_WEIGHTED_MODULE_TYPES" in src
    assert '"dense"' not in src.split("_repo_has_weighted_st_subfolders")[1][:2000]


def _ignores(
    model_name,
    monkeypatch,
    siblings = None,
    **kw,
):
    """Drives maybe_prefetch_hf_snapshot itself; _prefetch_ignore_patterns skips the subdir branch."""
    seen = {}

    def fake_download(name, **kwargs):
        seen.update(kwargs)
        return "/nonexistent/snapshot"

    # The prefetch is a no-op in offline mode; the downloader is stubbed anyway.
    for flag in ("HF_HUB_OFFLINE", "TRANSFORMERS_OFFLINE"):
        monkeypatch.delenv(flag, raising = False)

    import unsloth_zoo.hf_xet_fallback as XF

    monkeypatch.setattr(XF, "snapshot_download_with_xet_fallback", fake_download)
    # The auto format branch calls model_info; unstubbed that hits the network.
    import huggingface_hub

    class _Api:
        def model_info(self, *a, **k):
            if siblings is None:
                raise RuntimeError("no network in test")
            return types.SimpleNamespace(
                siblings = [types.SimpleNamespace(rfilename = f) for f in siblings]
            )

    monkeypatch.setattr(huggingface_hub, "HfApi", _Api)
    U.maybe_prefetch_hf_snapshot(model_name, weights_at_root = True, **kw)
    assert seen, "the downloader was never reached; the call bailed out early"
    return list(seen.get("ignore_patterns") or [])


def test_the_subdir_weight_patterns_are_dropped_for_such_a_repo(modules_json, monkeypatch):
    modules_json(EMBEDDINGGEMMA)
    got = _ignores("unsloth/embeddinggemma-300m", monkeypatch)
    assert "*/*.safetensors" not in got, got


def test_the_subdir_weight_patterns_are_kept_for_everything_else(modules_json, monkeypatch):
    """The other half of the claim. Without this, the test above would pass
    just as well if the patterns had been deleted outright."""
    modules_json(None)
    got = _ignores("unsloth/Qwen3-0.6B", monkeypatch)
    assert "*/*.safetensors" in got, got


def test_only_the_subdir_weight_patterns_differ(modules_json, monkeypatch):
    """The fix must not quietly change anything else about the request."""
    modules_json(None)
    plain = set(_ignores("unsloth/Qwen3-0.6B", monkeypatch))
    modules_json(EMBEDDINGGEMMA)
    st = set(_ignores("unsloth/embeddinggemma-300m", monkeypatch))
    assert plain - st == set(U._SUBDIR_WEIGHT_IGNORE_PATTERNS)
    assert st - plain == set()


def test_the_patterns_still_exist(modules_json):
    """The subdir weight ignore patterns are correct for fp16/ or experimental/ directories a root
    load never reads; this fix narrows where they apply and does not retire them."""
    assert "*/*.safetensors" in U._SUBDIR_WEIGHT_IGNORE_PATTERNS
    assert "*/*.bin" in U._SUBDIR_WEIGHT_IGNORE_PATTERNS


def test_an_older_unsloth_zoo_degrades_instead_of_crashing(modules_json):
    """`_ST_WEIGHTED_MODULE_TYPES` is private, so a user on an older zoo must
    fall back to today's pruning rather than get an ImportError on every load."""
    import unsloth_zoo.hf_cache_state as HCS

    modules_json(EMBEDDINGGEMMA)
    saved = HCS._ST_WEIGHTED_MODULE_TYPES
    del HCS._ST_WEIGHTED_MODULE_TYPES
    try:
        assert U._repo_has_weighted_st_subfolders("unsloth/embeddinggemma-300m") is False
    finally:
        HCS._ST_WEIGHTED_MODULE_TYPES = saved
    assert U._repo_has_weighted_st_subfolders("unsloth/embeddinggemma-300m") is True


def test_both_weights_at_root_call_sites_go_through_the_check():
    """`weights_at_root = True` is passed only from vision.py and llama.py, and every
    such call reaches the prune through maybe_prefetch_hf_snapshot (directly, or via
    resolve_vllm_model_path for the vLLM path, #13486), so one carve-out covers them
    all. A call into anything else, or an inlined copy of the patterns, fails here
    instead of leaving some loader pruning ST weights."""
    # AST, not grep: the names also appear in docstring prose.
    import ast

    routed = {"maybe_prefetch_hf_snapshot", "resolve_vllm_model_path"}
    root = Path(U.__file__).resolve().parents[1]
    sites = []
    for p in root.rglob("*.py"):
        if "tests" in p.parts:
            continue
        for n in ast.walk(ast.parse(p.read_text(encoding = "utf-8"))):
            if not isinstance(n, ast.Call):
                continue
            for k in n.keywords:
                if (
                    k.arg == "weights_at_root"
                    and isinstance(k.value, ast.Constant)
                    and k.value.value is True
                ):
                    callee = getattr(n.func, "id", getattr(n.func, "attr", None))
                    sites.append((p.name, n.lineno, callee))
    assert {s[0] for s in sites} == {"llama.py", "vision.py"}, sites
    assert all(s[2] in routed for s in sites), sites
    # Each loader's normal and vLLM paths, so losing the keyword on either one fails too.
    expected = {(f, callee) for f in ("llama.py", "vision.py") for callee in routed}
    assert expected <= {(s[0], s[2]) for s in sites}, sites

    tree = ast.parse(Path(U.__file__).read_text(encoding = "utf-8"))
    resolver = next(
        n
        for n in ast.walk(tree)
        if isinstance(n, ast.FunctionDef) and n.name == "resolve_vllm_model_path"
    )
    # `**kwargs` forwarded, or the resolver could drop weights_at_root on the way.
    assert any(
        isinstance(c, ast.Call)
        and getattr(c.func, "id", None) == "maybe_prefetch_hf_snapshot"
        and any(k.arg is None for k in c.keywords)
        for c in ast.walk(resolver)
    ), "resolve_vllm_model_path no longer forwards its kwargs to maybe_prefetch_hf_snapshot"

    loads = [
        n
        for n in ast.walk(tree)
        if isinstance(n, ast.Name)
        and n.id == "_SUBDIR_WEIGHT_IGNORE_PATTERNS"
        and isinstance(n.ctx, ast.Load)
    ]
    assert len(loads) == 1, [n.lineno for n in loads]


def test_a_hub_failure_keeps_the_patterns(monkeypatch):
    """Network trouble must not silently enlarge every download."""
    import huggingface_hub

    def boom(*a, **k):
        raise RuntimeError("hub down")

    monkeypatch.setattr(huggingface_hub, "hf_hub_download", boom)
    got = _ignores("org/anything", monkeypatch)
    assert "*/*.safetensors" in got


if __name__ == "__main__":
    raise SystemExit(pytest.main([__file__, "-q"]))


BIN_DENSE_FILES = [
    "config.json",
    "modules.json",
    "model.safetensors",
    "pytorch_model.bin",
    "1_Pooling/config.json",
    "2_Dense/config.json",
    "2_Dense/pytorch_model.bin",
]


def _kept(files, patterns):
    """What snapshot_download would actually fetch, using its own matcher."""
    import fnmatch
    return [f for f in files if not any(fnmatch.fnmatch(f, p) for p in patterns)]


def test_a_bin_only_dense_module_keeps_its_only_weight(modules_json, monkeypatch):
    """Root model.safetensors plus 2_Dense/pytorch_model.bin, the legacy ST head shape. The redundant
    format prune adds a bare "*.bin", and "*" spans "/" in the Hub's fnmatch, so the glob would strip
    the Dense module's only weight: the same unsatisfiable request, one branch further along."""
    modules_json(EMBEDDINGGEMMA)
    patterns = _ignores("org/st-bin-dense", monkeypatch, siblings = BIN_DENSE_FILES)
    kept = _kept(BIN_DENSE_FILES, patterns)
    assert "2_Dense/pytorch_model.bin" in kept, patterns
    assert "pytorch_model.bin" not in kept, (
        "the redundant ROOT .bin must still be pruned",
        patterns,
    )
    assert "model.safetensors" in kept, patterns


def test_the_bin_prune_is_untouched_without_st_modules(modules_json, monkeypatch):
    """A plain repo still gets the cheap glob, not an enumeration."""
    modules_json(None)
    patterns = _ignores("org/plain", monkeypatch, siblings = BIN_DENSE_FILES)
    assert "*.bin" in patterns
    assert "pytorch_model.bin" not in _kept(BIN_DENSE_FILES, patterns)


def test_an_explicit_format_request_keeps_both_for_such_a_repo(modules_json, monkeypatch):
    """use_safetensors fetches no repo listing, so the glob cannot be scoped and pruning it would
    drop the module weight. Keeping both formats is the trade the multi-component case already makes."""
    modules_json(EMBEDDINGGEMMA)
    patterns = _ignores("org/st-bin-dense", monkeypatch, use_safetensors = True)
    assert "*.bin" not in patterns
    modules_json(None)
    assert "*.bin" in _ignores("org/plain", monkeypatch, use_safetensors = True)


def test_a_module_path_is_not_read_as_a_glob(modules_json, monkeypatch):
    """Repo filenames go into ignore_patterns verbatim, so a "[" in a name would silently become a
    character class and stop matching itself."""
    modules_json(EMBEDDINGGEMMA)
    files = ["modules.json", "model.safetensors", "weird[1].bin", "2_Dense/pytorch_model.bin"]
    patterns = _ignores("org/st-bin-dense", monkeypatch, siblings = files)
    kept = _kept(files, patterns)
    assert "weird[1].bin" not in kept, patterns
    assert "2_Dense/pytorch_model.bin" in kept, patterns