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.

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.py
index 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_path
diff --git a/studio/backend/tests/test_export_gguf_hub_upload.py b/studio/backend/tests/test_export_gguf_hub_upload.py
index 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, _ModelCard
diff --git a/studio/backend/tests/test_export_hub_push.py b/studio/backend/tests/test_export_hub_push.py
index 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 annotations
import importlib.util
import sys
+import tempfile
import types
from 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_path
assert "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.py
index 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) ---------------------------------