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
Studio: stop merging the model twice when pushing a merged export to the Hub (#11050)
Nilaydba74909ad1f
diff --git a/studio/backend/core/export/export.py b/studio/backend/core/export/export.pyindex 30038e6d996..86823d2d9ae 100644--- a/studio/backend/core/export/export.py+++ b/studio/backend/core/export/export.py@@ -39,7 +39,7 @@ from utils.paths import (resolve_output_dir,)from core.inference import get_inference_backend-from utils.paths.path_utils import drop_appledouble_metadata+from utils.paths.path_utils import any_not_appledouble_metadata, drop_appledouble_metadata# GPU/PyTorch-only imports, skipped on MLX and --no-torch installs so the module stays importable.torch = None@@ -436,6 +436,39 @@ This model was converted to GGUF format using [Unsloth](https://github.com/unslo"""+# export_metadata.json is local bookkeeping whose base model can be a local path; the GGUF push+# keeps it out of the repo too.+_HUB_UPLOAD_IGNORE = ["export_metadata.json", "._*"]++_STAGING_PREFIX = "unsloth-hub-upload-"+++def _staging_dir(export_parent):+ """Stage a copy of an export where it fits: merge_and_overwrite_lora refuses a save its+ destination cannot hold, and neither the temporary directory nor the export's own filesystem is+ reliably the roomier, or even writable — only the export directory itself has to be.+ """+ roomiest = []+ for parent in (Path(tempfile.gettempdir()), Path(export_parent)):+ try:+ roomiest.append((shutil.disk_usage(parent).free, parent))+ except OSError:+ continue+ roomiest.sort(key = lambda candidate: -candidate[0])+ for _, parent in roomiest:+ try:+ return tempfile.TemporaryDirectory(prefix = _STAGING_PREFIX, dir = parent)+ except OSError:+ continue+ return tempfile.TemporaryDirectory(prefix = _STAGING_PREFIX)+++def _holds_checkpoint_weights(directory):+ return Path(directory).is_dir() and any(+ entry.suffix in (".safetensors", ".bin") for entry in Path(directory).iterdir()+ )++def _ensure_hub_repo_private(hf_api, repo_id):"""Tighten an existing repo to private: create_repo sets `private` only at creation."""try:@@ -779,6 +812,7 @@ class ExportBackend:# save_pretrained_merged is a no-op merge for non-PEFT base models, so one path covers both.output_path: Optional[str] = None+ save_dir_was_empty = False# Two backends: compressed-tensors (llm-compressor, NVIDIA-only) and portable torchao FP8/INT8.# The alias comes from compressed_method (the "all formats" dropdown) or the format_type label._LABEL_TO_ALIAS = {@@ -879,6 +913,12 @@ class ExportBackend:if save_directory:save_directory = str(resolve_export_write_dir(save_directory))logger.info(f"Saving merged model locally to: {save_directory}")+ # Leftovers in a reused folder would be uploaded too, so only a fresh one is+ # pushed as is. Finder metadata does not count; the upload drops it anyway.+ save_dir_was_empty = not (+ Path(save_directory).is_dir()+ and any_not_appledouble_metadata(Path(save_directory).iterdir())+ )ensure_dir(Path(save_directory))# No push, but the merge resolves the base repo and save.py turns None into@@ -947,38 +987,73 @@ class ExportBackend:token = hf_token,private = private,)- elif (is_compressed or is_torchao) and output_path and Path(output_path).is_dir():- # Upload the artifact already built in output_path; push_to_hub_merged(save_method=...) would- # redo the expensive quantization.- hf_api = HfApi(token = hf_token)- repo_url = hf_api.create_repo(repo_id, private = private, exist_ok = True)- repo_id = getattr(repo_url, "repo_id", repo_id)- if private:- _ensure_hub_repo_private(hf_api, repo_id)- content = MODEL_CARD.format(- username = repo_id.split("/")[0],- base_model = getattr(self.current_model.config, "_name_or_path", "unknown"),- model_type = getattr(self.current_model.config, "model_type", "llm"),- method = compressed_alias or format_type,- extra = "unsloth",- )- ModelCard(content).push_to_hub(- repo_id, token = hf_token, commit_message = "Unsloth Model Card"- )- hf_api.upload_folder(- folder_path = output_path,- repo_id = repo_id,- repo_type = "model",- )else:- hub_save_method = save_method if save_method is not None else "merged_16bit"- self.current_model.push_to_hub_merged(- repo_id,- self.current_tokenizer,- save_method = hub_save_method,- token = hf_token,- private = private,- )+ uploaded = False+ if output_path and Path(output_path).is_dir():+ # Upload the artifact already built in output_path; push_to_hub_merged(save_method=...) would+ # redo the expensive merge and quantization.+ with contextlib.ExitStack() as stack:+ upload_dir = output_path+ if not (is_compressed or is_torchao or save_dir_was_empty):+ # A reused folder can hold leftovers, so upload a clean second save+ # instead.+ upload_dir = stack.enter_context(+ _staging_dir(Path(output_path).parent)+ )+ self.current_model.save_pretrained_merged(+ upload_dir,+ self.current_tokenizer,+ save_method = save_method,+ **merged_token_kw,+ )+ # Whatever was built, only weights are worth a repo; without them the+ # merging push below runs instead, as it did before this was uploaded.+ if _holds_checkpoint_weights(upload_dir):+ hf_api = HfApi(token = hf_token)+ repo_url = hf_api.create_repo(+ repo_id, private = private, exist_ok = True+ )+ repo_id = getattr(repo_url, "repo_id", repo_id)+ if private:+ _ensure_hub_repo_private(hf_api, repo_id)+ hf_api.upload_folder(+ folder_path = upload_dir,+ repo_id = repo_id,+ repo_type = "model",+ ignore_patterns = _HUB_UPLOAD_IGNORE,+ )+ uploaded = True+ if uploaded:+ # Last and best-effort like the GGUF card; an existing card is kept, as+ # push_to_hub_merged does.+ try:+ if not hf_api.file_exists(repo_id, "README.md", repo_type = "model"):+ base_model = getattr(+ self.current_model.config, "_name_or_path", "unknown"+ )+ content = MODEL_CARD.format(+ username = repo_id.split("/")[0],+ base_model = repo_id if os.path.isdir(base_model) else base_model,+ model_type = getattr(+ self.current_model.config, "model_type", "llm"+ ),+ method = compressed_alias or format_type,+ extra = "unsloth",+ )+ ModelCard(content).push_to_hub(+ repo_id, token = hf_token, commit_message = "Unsloth Model Card"+ )+ except Exception as exception:+ logger.warning(f"Could not publish the model card: {exception}")+ else:+ hub_save_method = save_method if save_method is not None else "merged_16bit"+ self.current_model.push_to_hub_merged(+ repo_id,+ self.current_tokenizer,+ save_method = hub_save_method,+ token = hf_token,+ private = private,+ )logger.info(f"Model pushed successfully to {repo_id}")return True, "Model exported successfully", output_pathdiff --git a/studio/backend/tests/test_export_gguf_hub_upload.py b/studio/backend/tests/test_export_gguf_hub_upload.pyindex 3f1d037e782..6284afcac0e 100644--- a/studio/backend/tests/test_export_gguf_hub_upload.py+++ b/studio/backend/tests/test_export_gguf_hub_upload.py@@ -63,6 +63,14 @@ def _hub_doubles(calls, seen):calls.append("repo_info")return seen.get("repo_info_result")+ def file_exists(+ self,+ repo_id,+ filename,+ repo_type = None,+ ):+ return seen.get("existing_files", {}).get(filename, False)+def upload_file(self,path_or_fileobj,@@ -106,6 +114,8 @@ def _hub_doubles(calls, seen):):calls.append("model_card")seen["card_repo"] = repo_id+ if seen.get("card_error"):+ raise seen["card_error"]return _HfApi, _ModelCarddiff --git a/studio/backend/tests/test_export_hub_push.py b/studio/backend/tests/test_export_hub_push.pyindex 46f3f430d4a..79c6e210eb9 100644--- a/studio/backend/tests/test_export_hub_push.py+++ b/studio/backend/tests/test_export_hub_push.py@@ -5,6 +5,7 @@ from __future__ import annotationsimport importlib.utilimport sys+import tempfileimport typesfrom pathlib import Path@@ -33,6 +34,9 @@ class _Tokenizer:class _Model:config = _Config()+ def __init__(self):+ self.merges = []+def save_pretrained(self, save_directory):Path(save_directory, "model.safetensors").write_bytes(b"weights")@@ -43,9 +47,14 @@ class _Model:save_method = None,token = None,):- output = Path(f"{save_directory}-torchao-fp8")- output.mkdir(parents = True)- (output / "model.safetensors").write_bytes(b"fp8")+ self.merges.append(save_method)+ suffix = "-torchao-fp8" if save_method == "torchao_fp8" else ""+ output = Path(f"{save_directory}{suffix}")+ output.mkdir(parents = True, exist_ok = True)+ (output / "model.safetensors").write_bytes(b"weights")++ def push_to_hub_merged(self, *args, **kwargs):+ self.merges.append("push_to_hub_merged")def _non_mlx_backend(monkeypatch, name, calls, seen):@@ -90,6 +99,11 @@ def _expected_calls(private):return ["create_repo", *visibility, "model_card", "upload_folder"]+def _expected_merged_calls(private):+ visibility = ["update_repo_settings"] if private else []+ return ["create_repo", *visibility, "upload_folder", "model_card"]++@pytest.mark.parametrize("private", [True, False])def test_base_export_push_creates_the_repo_without_push_to_hub_mixin(tmp_path, monkeypatch, private@@ -133,10 +147,229 @@ def test_merged_torchao_export_push_creates_the_repo_without_push_to_hub_mixin()assert success is True, message+ assert backend.current_model.merges == ["torchao_fp8"]assert output_path == str(Path(f"{tmp_path / 'export'}-torchao-fp8").resolve())assert seen["token"] == "hf_fake"assert seen["repo"] == {"repo_id": "model", "private": private, "exist_ok": True}- assert calls == _expected_calls(private)+ assert calls == _expected_merged_calls(private)assert seen["card_repo"] == "owner/model"assert seen["folder"] == output_pathassert "model.safetensors" in seen["uploaded"]+++ "format_type, save_method",+ [("16-bit (FP16)", "merged_16bit"), ("4-bit (FP4)", "merged_4bit_forced")],+)[email protected]("private", [True, False])+def test_merged_export_push_uploads_the_saved_folder_instead_of_merging_again(+ tmp_path, monkeypatch, format_type, save_method, private+):+ calls: list[str] = []+ seen: dict = {}+ backend = _non_mlx_backend(monkeypatch, "test_export_hub_push_merged_backend", calls, seen)++ success, message, output_path = backend.export_merged_model(+ str(tmp_path / "export"),+ format_type = format_type,+ push_to_hub = True,+ repo_id = "model",+ hf_token = "hf_fake",+ private = private,+ )++ assert success is True, message+ assert backend.current_model.merges == [save_method]+ assert output_path == str((tmp_path / "export").resolve())+ assert seen["repo"] == {"repo_id": "model", "private": private, "exist_ok": True}+ assert calls == _expected_merged_calls(private)+ assert f"# Uploaded finetuned {format_type} model" in seen["card"]+ assert "base_model: unsloth/Qwen2.5-0.5B-Instruct" in seen["card"]+ assert seen["folder"] == output_path+ assert seen["uploaded"] == ["model.safetensors"]+++def test_merged_export_push_to_a_reused_folder_does_not_upload_its_leftovers(tmp_path, monkeypatch):+ calls: list[str] = []+ seen: dict = {}+ backend = _non_mlx_backend(monkeypatch, "test_export_hub_push_merged_backend", calls, seen)+ export_dir = tmp_path / "export"+ export_dir.mkdir()+ (export_dir / "adapter_config.json").write_text("{}")++ success, message, output_path = backend.export_merged_model(+ str(export_dir),+ push_to_hub = True,+ repo_id = "model",+ hf_token = "hf_fake",+ )++ assert success is True, message+ assert output_path == str(export_dir.resolve())+ assert backend.current_model.merges == ["merged_16bit", "merged_16bit"]+ assert seen["folder"] != output_path+ assert not Path(seen["folder"]).exists()+ assert seen["uploaded"] == ["model.safetensors"]++[email protected]("roomier", ["temp", "export", "export_but_unwritable"])+def test_merged_export_push_stages_the_clean_save_where_there_is_room(+ tmp_path, monkeypatch, roomier+):+ import shutil++ calls: list[str] = []+ seen: dict = {}+ backend = _non_mlx_backend(monkeypatch, "test_export_hub_push_merged_backend", calls, seen)+ export_dir = tmp_path / "export"+ export_dir.mkdir()+ (export_dir / "adapter_config.json").write_text("{}")+ export_parent = export_dir.resolve().parent++ def fake_disk_usage(path):+ under_export = Path(path).resolve() == export_parent+ roomy = under_export if roomier != "temp" else not under_export+ return types.SimpleNamespace(total = 1 << 40, used = 0, free = (1 << 40) if roomy else 1)++ monkeypatch.setattr(shutil, "disk_usage", fake_disk_usage)++ if roomier == "export_but_unwritable":+ # Only the export directory has to be writable; its parent need not be.+ real_temporary_directory = tempfile.TemporaryDirectory++ def refusing_temporary_directory(+ *args,+ dir = None,+ **kwargs,+ ):+ if dir is not None and Path(dir).resolve() == export_parent:+ raise PermissionError(13, "Permission denied", str(dir))+ return real_temporary_directory(*args, dir = dir, **kwargs)++ monkeypatch.setattr(tempfile, "TemporaryDirectory", refusing_temporary_directory)++ success, message, _ = backend.export_merged_model(+ str(export_dir),+ push_to_hub = True,+ repo_id = "model",+ hf_token = "hf_fake",+ )++ assert success is True, message+ staging_parent = Path(seen["folder"]).resolve().parent+ if roomier == "export":+ assert staging_parent == export_parent+ else:+ assert staging_parent != export_parent+++def test_merged_export_push_treats_a_folder_of_finder_metadata_as_fresh(tmp_path, monkeypatch):+ calls: list[str] = []+ seen: dict = {}+ backend = _non_mlx_backend(monkeypatch, "test_export_hub_push_merged_backend", calls, seen)+ export_dir = tmp_path / "export"+ export_dir.mkdir()+ (export_dir / "._model.safetensors").write_bytes(b"\x00\x05\x16\x07rsrc")++ success, message, output_path = backend.export_merged_model(+ str(export_dir),+ push_to_hub = True,+ repo_id = "model",+ hf_token = "hf_fake",+ )++ assert success is True, message+ assert backend.current_model.merges == ["merged_16bit"]+ assert seen["folder"] == output_path+ assert seen["uploaded"] == ["model.safetensors"]+++def test_merged_export_push_keeps_the_card_of_an_existing_repo(tmp_path, monkeypatch):+ calls: list[str] = []+ seen: dict = {"existing_files": {"README.md": True}}+ backend = _non_mlx_backend(monkeypatch, "test_export_hub_push_merged_backend", calls, seen)++ success, message, _ = backend.export_merged_model(+ str(tmp_path / "export"),+ push_to_hub = True,+ repo_id = "model",+ hf_token = "hf_fake",+ )++ assert success is True, message+ assert calls == ["create_repo", "upload_folder"]+ assert "card" not in seen+ assert seen["uploaded"] == ["model.safetensors"]+++def test_merged_export_push_still_uploads_when_the_card_fails(tmp_path, monkeypatch):+ calls: list[str] = []+ seen: dict = {"card_error": RuntimeError("validate-yaml unreachable")}+ backend = _non_mlx_backend(monkeypatch, "test_export_hub_push_merged_backend", calls, seen)++ success, message, output_path = backend.export_merged_model(+ str(tmp_path / "export"),+ push_to_hub = True,+ repo_id = "model",+ hf_token = "hf_fake",+ )++ assert success is True, message+ assert seen["folder"] == output_path+ assert seen["uploaded"] == ["model.safetensors"]+++# A stale weight file makes the folder look reused, so the emptiness is only visible on the staging+# copy; a fresh folder shows it on the export directory itself.[email protected]("stale_weights", [False, True])+def test_merged_export_push_merges_again_when_the_save_left_no_weights(+ tmp_path, monkeypatch, stale_weights+):+ calls: list[str] = []+ seen: dict = {}+ backend = _non_mlx_backend(monkeypatch, "test_export_hub_push_merged_backend", calls, seen)+ export_dir = tmp_path / "export"+ if stale_weights:+ export_dir.mkdir()+ (export_dir / "model.safetensors").write_bytes(b"stale")++ def save_nothing(+ save_directory,+ tokenizer,+ save_method = None,+ token = None,+ ):+ Path(save_directory).mkdir(parents = True, exist_ok = True)++ backend.current_model.save_pretrained_merged = save_nothing++ success, message, _ = backend.export_merged_model(+ str(export_dir),+ push_to_hub = True,+ repo_id = "model",+ hf_token = "hf_fake",+ )++ assert success is True, message+ assert backend.current_model.merges == ["push_to_hub_merged"]+ assert calls == []+++def test_merged_export_push_card_does_not_name_a_local_base_model(tmp_path, monkeypatch):+ calls: list[str] = []+ seen: dict = {}+ backend = _non_mlx_backend(monkeypatch, "test_export_hub_push_merged_backend", calls, seen)+ backend.current_model.config = types.SimpleNamespace(+ _name_or_path = str(tmp_path), model_type = "qwen2"+ )++ success, message, _ = backend.export_merged_model(+ str(tmp_path / "export"),+ push_to_hub = True,+ repo_id = "model",+ hf_token = "hf_fake",+ )++ assert success is True, message+ assert "base_model: owner/model" in seen["card"]+ assert str(tmp_path) not in seen["card"]diff --git a/studio/backend/tests/test_export_imatrix_compressed.py b/studio/backend/tests/test_export_imatrix_compressed.pyindex acfd47d4bdd..2e1ce1043a7 100644--- a/studio/backend/tests/test_export_imatrix_compressed.py+++ b/studio/backend/tests/test_export_imatrix_compressed.py@@ -126,8 +126,9 @@ def test_export_merged_maps_compressed_to_save_method():def test_compressed_hub_push_uploads_local_dir_without_recompressing():# A compressed / torchao Hub push must upload the built output_path, not re-quantize.m = _func_src("core/export/export.py", "export_merged_model")- assert "elif (is_compressed or is_torchao) and output_path and Path(output_path).is_dir():" in m- assert "hf_api.upload_folder(" in m and "folder_path = output_path" in m+ assert "if output_path and Path(output_path).is_dir():" in m+ assert "if not (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# -- torchao portable FP8/INT8 (device-agnostic, no NVIDIA GPU) ---------------------------------