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.

12.1 KB
Raw Blame
# SPDX-License-Identifier: AGPL-3.0-only
# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0

"""GGUF imatrix and compressed-tensors export wiring; threading checked by ast, no GPU needed."""

import ast
from pathlib import Path

import pytest
from pydantic import ValidationError

from models.export import ExportGGUFRequest, ExportMergedModelRequest

_BACKEND = Path(__file__).resolve().parent.parent


def _src(rel):
    return (_BACKEND / rel).read_text(encoding = "utf-8")


def _func_src(rel, name):
    src = _src(rel)
    node = next(
        n
        for n in ast.walk(ast.parse(src))
        if isinstance(n, (ast.FunctionDef, ast.AsyncFunctionDef)) and n.name == name
    )
    return ast.get_source_segment(src, node)


def test_gguf_request_imatrix_defaults_and_set():
    assert ExportGGUFRequest(save_directory = "/tmp/x").imatrix is False
    assert ExportGGUFRequest(save_directory = "/tmp/x").imatrix_path is None
    r = ExportGGUFRequest(save_directory = "/tmp/x", imatrix = True, imatrix_path = "/i.dat")
    assert r.imatrix is True and r.imatrix_path == "/i.dat"


def test_gguf_request_private_defaults_and_set():
    assert ExportGGUFRequest(save_directory = "/tmp/x").private is False
    r = ExportGGUFRequest(save_directory = "/tmp/x", private = True)
    assert r.private is True


def test_merged_request_accepts_compressed_formats():
    for fmt in ("16-bit (FP16)", "FP8 (compressed-tensors)", "NVFP4 (compressed-tensors)"):
        assert ExportMergedModelRequest(save_directory = "/tmp/x", format_type = fmt).format_type == fmt


def test_merged_request_rejects_unknown_format():
    with pytest.raises(ValidationError):
        ExportMergedModelRequest(save_directory = "/tmp/x", format_type = "bogus")


def test_export_gguf_threads_imatrix_to_save_and_push():
    g = _func_src("core/export/export.py", "export_gguf")
    assert g.count("**imatrix_kw") >= 2
    # truthiness: a disabled imatrix must not reach an exporter without the kwarg
    assert 'imatrix_kw = {"imatrix_file": imatrix_file} if imatrix_file else {}' in g
    assert "imatrix_file = imatrix_file" not in g


def test_export_gguf_guards_unsupported_imatrix_build():
    # the kwarg probe is not enough: the MLX binding takes **kwargs and filters them
    g = _func_src("core/export/export.py", "export_gguf")
    assert "_imatrix_export_supported(" in g


def test_export_merged_guards_unsupported_compressed_build():
    m = _func_src("core/export/export.py", "export_merged_model")
    assert "_compressed_export_supported()" in m


def test_supports_kwarg_helper():
    # exec just the helper to avoid export.py's heavy import chain
    ns = {}
    for helper in ("_accepts_by_keyword", "_supports_kwarg"):
        exec(_func_src("core/export/export.py", helper), ns)
    supports = ns["_supports_kwarg"]

    def has_it(a, imatrix_file = None):
        pass

    def lacks_it(a):
        pass

    def via_kwargs(a, **kw):
        pass

    # every call site passes the keyword, so positional-only is not support
    positional_only = {}
    exec("def f(a, imatrix_file = None, /): pass", positional_only)

    assert supports(has_it, "imatrix_file") is True
    assert supports(lacks_it, "imatrix_file") is False
    assert supports(via_kwargs, "imatrix_file") is True
    assert supports(positional_only["f"], "imatrix_file") is False


def test_orchestrator_and_worker_pass_imatrix():
    assert "imatrix_file" in _func_src("core/export/orchestrator.py", "export_gguf")
    assert 'imatrix_file = cmd.get("imatrix_file")' in _src("core/export/worker.py")


def test_route_resolves_imatrix_file():
    assert "request.imatrix_path or (True if request.imatrix else None)" in _src("routes/export.py")


def test_export_merged_maps_compressed_to_save_method():
    m = _func_src("core/export/export.py", "export_merged_model")
    assert "is_compressed" in m and '"fp8"' in m and '"nvfp4"' in m


def test_compressed_hub_push_uploads_local_dir_without_recompressing():
    m = _func_src("core/export/export.py", "export_merged_model")
    assert "if output_path and Path(output_path).is_dir():" in m
    assert "is_compressed or is_torchao or save_dir_was_empty" in m
    assert "hf_api.upload_folder(" in m and "folder_path = upload_dir" in m


def test_merged_request_accepts_torchao_aliases():
    for alias in ("torchao_fp8", "torchao_int8"):
        r = ExportMergedModelRequest(save_directory = "/tmp/x", compressed_method = alias)
        assert r.compressed_method == alias


def test_export_merged_routes_torchao_and_skips_nvidia_guard():
    m = _func_src("core/export/export.py", "export_merged_model")
    assert "_normalize_torchao_method(compressed_alias)" in m
    assert "is_torchao = torchao_info is not None" in m
    assert "is_compressed = compressed_alias is not None and not is_torchao" in m
    assert "_has_nvidia_gpu()" in m
    assert "elif is_compressed or is_torchao:" in m


def test_export_merged_nvidia_guard_present():
    m = _func_src("core/export/export.py", "export_merged_model")
    assert "requires an NVIDIA GPU" in m


def test_has_nvidia_gpu_helper_reads_hardware_module():
    h = _func_src("core/export/export.py", "_has_nvidia_gpu")
    assert "DeviceType.CUDA" in h and "IS_ROCM" in h


def test_export_merged_relaxes_is_peft_guard():
    m = _func_src("core/export/export.py", "export_merged_model")
    assert "Use 'Export Base Model' instead." not in m


def test_unsloth_save_has_torchao_registry_and_path():
    # read as text so this runs in the CPU suite without unsloth
    save_py = (_BACKEND.parent.parent / "unsloth" / "save.py").read_text(encoding = "utf-8")
    assert "def _normalize_torchao_method" in save_py
    assert "def _unsloth_save_torchao" in save_py
    assert "TORCHAO_EXPORT_SCHEMES = {" in save_py
    assert '"torchao_fp8": ("fp8", "torchao-fp8")' in save_py
    assert '"torchao_int8": ("int8", "torchao-int8")' in save_py


@pytest.mark.parametrize("wrapper_name", ["_save_pretrained_gguf", "_push_to_hub_gguf"])
def test_sentence_transformer_gguf_wrappers_forward_imatrix(wrapper_name):
    # both take **kwargs, so they must forward imatrix rather than swallow it
    st = (_BACKEND.parent.parent / "unsloth" / "models" / "sentence_transformer.py").read_text(
        encoding = "utf-8"
    )
    wrapper = st[st.index(f"def {wrapper_name}(") :]
    wrapper = wrapper[: wrapper.index("\n# ")]
    assert "imatrix_file = None," in wrapper
    assert "imatrix_file = imatrix_file," in wrapper


def test_gguf_export_request_falls_back_to_the_load_token():
    # a local imatrix export resolves from a Hub repo, but the UI sets `token` only for a push
    store = (
        _BACKEND.parent
        / "frontend"
        / "src"
        / "features"
        / "export"
        / "stores"
        / "export-runtime-store.ts"
    ).read_text(encoding = "utf-8")
    gguf = store[store.index("exportGGUF({") :]
    gguf = gguf[: gguf.index("}),")]
    assert "hf_token: params.token ?? params.loadToken ?? null," in gguf


def test_gguf_request_accepts_list_of_quants():
    r = ExportGGUFRequest(save_directory = "/tmp/x", quantization_method = ["Q4_K_M", "Q8_0"])
    assert r.quantization_method == ["Q4_K_M", "Q8_0"]
    r2 = ExportGGUFRequest(save_directory = "/tmp/x", quantization_method = "Q4_K_M")
    assert r2.quantization_method == "Q4_K_M"


def test_export_gguf_normalizes_quant_list():
    g = _func_src("core/export/export.py", "export_gguf")
    assert "isinstance(quantization_method, (list, tuple))" in g
    assert "quant_methods" in g


def test_lora_request_has_gguf_fields():
    from models.export import ExportLoRAAdapterRequest

    r = ExportLoRAAdapterRequest(save_directory = "/tmp/x")
    assert r.gguf is False and r.gguf_outtype == "q8_0"
    r2 = ExportLoRAAdapterRequest(save_directory = "/tmp/x", gguf = True, gguf_outtype = "q8_0")
    assert r2.gguf is True and r2.gguf_outtype == "q8_0"


def test_lora_request_rejects_bad_outtype():
    from models.export import ExportLoRAAdapterRequest
    with pytest.raises(ValidationError):
        ExportLoRAAdapterRequest(save_directory = "/tmp/x", gguf_outtype = "q3_k")


def test_export_lora_wires_gguf_save_method():
    la = _func_src("core/export/export.py", "export_lora_adapter")
    assert 'save_method = "lora"' in la
    assert "quantization_method = outtype" in la


def test_orchestrator_and_worker_pass_lora_gguf():
    o = _func_src("core/export/orchestrator.py", "export_lora_adapter")
    assert '"gguf": gguf' in o and '"gguf_outtype": gguf_outtype' in o
    w = _src("core/export/worker.py")
    assert 'gguf = cmd.get("gguf", False)' in w
    assert 'gguf_outtype = cmd.get("gguf_outtype", "q8_0")' in w


def test_route_passes_lora_gguf():
    r = _src("routes/export.py")
    assert "gguf = request.gguf" in r and "gguf_outtype = request.gguf_outtype" in r


def test_merged_request_accepts_compressed_method():
    assert ExportMergedModelRequest(save_directory = "/tmp/x").compressed_method is None
    for alias in ("fp8", "fp8_static", "w8a8", "w8a16", "w4a16", "mxfp4", "mxfp8", "nvfp4"):
        r = ExportMergedModelRequest(save_directory = "/tmp/x", compressed_method = alias)
        assert r.compressed_method == alias


def test_export_merged_resolves_alias_via_registry():
    m = _func_src("core/export/export.py", "export_merged_model")
    assert "compressed_method" in m
    assert "_normalize_compressed_method(compressed_alias)" in m
    assert "compressed_alias = compressed_method or _LABEL_TO_ALIAS.get(format_type)" in m
    assert "compressed_suffix" in m and 'f"{save_directory}-{compressed_suffix}"' in m


def test_orchestrator_and_worker_pass_compressed_method():
    o = _func_src("core/export/orchestrator.py", "export_merged_model")
    assert "compressed_method" in o and '"compressed_method": compressed_method' in o
    assert 'compressed_method = cmd.get("compressed_method")' in _src("core/export/worker.py")


def test_route_passes_compressed_method():
    assert "compressed_method = request.compressed_method" in _src("routes/export.py")


def test_export_gguf_threads_private_to_push_to_hub():
    g = _func_src("core/export/export.py", "export_gguf")
    assert "private: bool = False" in g
    assert "private = private" in g


def test_route_passes_gguf_private():
    src = _func_src("routes/export.py", "export_gguf")
    assert "private = request.private" in src


def test_route_export_gguf_forwards_private(monkeypatch):
    import asyncio
    from routes import export as export_route

    captured = {}

    class FakeBackend:
        def export_gguf(self, **kwargs):
            captured.update(kwargs)
            return True, "ok", "/tmp/out"

    async def _mock_supported():
        return None

    monkeypatch.setattr(export_route, "_ensure_export_supported", _mock_supported)
    monkeypatch.setattr(export_route, "get_export_backend", lambda: FakeBackend())
    monkeypatch.setattr(export_route, "_export_details", lambda *args, **kwargs: {})

    req = ExportGGUFRequest(save_directory = "/tmp/out", private = True)
    res = asyncio.run(export_route.export_gguf(req, current_subject = "test"))
    assert res.success is True
    assert captured.get("private") is True

    captured.clear()
    req_default = ExportGGUFRequest(save_directory = "/tmp/out")
    res_default = asyncio.run(export_route.export_gguf(req_default, current_subject = "test"))
    assert res_default.success is True
    assert captured.get("private") is False


def test_orchestrator_passes_gguf_private():
    o = _func_src("core/export/orchestrator.py", "export_gguf")
    assert "private: bool = False" in o and '"private": private' in o


def test_worker_passes_gguf_private():
    import queue
    from core.export.worker import _handle_export

    captured = {}

    class FakeBackend:
        def export_gguf(self, **kwargs):
            captured.update(kwargs)
            return True, "ok", "/out"

    q = queue.Queue()
    _handle_export(
        FakeBackend(),
        {"export_type": "gguf", "save_directory": "/tmp/out", "private": True},
        q,
    )
    assert captured.get("private") is True

    captured.clear()
    _handle_export(
        FakeBackend(),
        {"export_type": "gguf", "save_directory": "/tmp/out"},
        q,
    )
    assert captured.get("private") is False