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: push only the exported merged model to the Hub on a Mac (#12239)

Nilay852795db9db8
diff --git a/studio/backend/core/export/export.py b/studio/backend/core/export/export.py
index 7e16f3a8f4b..c53090c8315 100644
--- a/studio/backend/core/export/export.py
+++ b/studio/backend/core/export/export.py
@@ -605,6 +605,32 @@ def _open_hub_repo(hf_api, repo_id, private):
return repo_id
+def _push_mlx_merged(
+ model, tokenizer, *, save_method, output_path, output_is_fresh, repo_id, hf_token, private
+):
+ """Upload an MLX merged save; returns the repo id the Hub resolved."""
+ with contextlib.ExitStack() as stack:
+ upload_dir = output_path
+ if not output_is_fresh:
+ # A reused folder can hold leftovers, so upload a clean second save; without a
+ # local save this is the only one.
+ upload_dir = stack.enter_context(
+ _staging_dir(Path(output_path).parent)
+ if output_path
+ else tempfile.TemporaryDirectory()
+ )
+ model.save_pretrained_merged(upload_dir, tokenizer, save_method = save_method)
+ hf_api = HfApi(token = hf_token)
+ repo_id = _open_hub_repo(hf_api, repo_id, private)
+ hf_api.upload_folder(
+ folder_path = upload_dir,
+ repo_id = repo_id,
+ repo_type = "model",
+ ignore_patterns = _HUB_UPLOAD_IGNORE,
+ )
+ return repo_id
+
+
def _publish_unsloth_model_card(hf_api, repo_id, model, hf_token):
"""Write the card the delegated push can no longer write for itself.
@@ -1125,28 +1151,16 @@ class ExportBackend:
logger.info(f"Pushing merged model to Hub: {repo_id}")
if _IS_MLX:
- if save_directory:
- self.current_model.push_to_hub_merged(
- repo_id,
- self.current_tokenizer,
- save_directory = save_directory,
- token = hf_token,
- private = private,
- )
- else:
- with tempfile.TemporaryDirectory() as tmp_dir:
- self.current_model.save_pretrained_merged(
- tmp_dir,
- self.current_tokenizer,
- save_method = mlx_save_method,
- )
- self.current_model.push_to_hub_merged(
- repo_id,
- self.current_tokenizer,
- save_directory = tmp_dir,
- token = hf_token,
- private = private,
- )
+ repo_id = _push_mlx_merged(
+ self.current_model,
+ self.current_tokenizer,
+ save_method = mlx_save_method,
+ output_path = output_path,
+ output_is_fresh = save_dir_was_empty,
+ repo_id = repo_id,
+ hf_token = hf_token,
+ private = private,
+ )
else:
uploaded = False
if output_path and Path(output_path).is_dir():
@@ -1281,28 +1295,16 @@ class ExportBackend:
logger.info(f"Pushing base model to Hub: {repo_id}")
if _IS_MLX:
- if save_directory:
- self.current_model.push_to_hub_merged(
- repo_id,
- self.current_tokenizer,
- save_directory = save_directory,
- token = hf_token,
- private = private,
- )
- else:
- with tempfile.TemporaryDirectory() as tmp_dir:
- self.current_model.save_pretrained_merged(
- tmp_dir,
- self.current_tokenizer,
- save_method = "merged_16bit",
- )
- self.current_model.push_to_hub_merged(
- repo_id,
- self.current_tokenizer,
- save_directory = tmp_dir,
- token = hf_token,
- private = private,
- )
+ _push_mlx_merged(
+ self.current_model,
+ self.current_tokenizer,
+ save_method = "merged_16bit",
+ output_path = output_path,
+ output_is_fresh = save_dir_was_empty,
+ repo_id = repo_id,
+ hf_token = hf_token,
+ private = private,
+ )
else:
base_model = (
base_model_id or self.current_model.config._name_or_path or "unknown"
diff --git a/studio/backend/tests/test_export_gguf_hub_upload.py b/studio/backend/tests/test_export_gguf_hub_upload.py
index f630b1a86d5..ff819a2b76c 100644
--- a/studio/backend/tests/test_export_gguf_hub_upload.py
+++ b/studio/backend/tests/test_export_gguf_hub_upload.py
@@ -102,6 +102,7 @@ def _hub_doubles(calls, seen):
):
calls.append("upload_folder")
seen["folder"] = folder_path
+ seen["upload_repo"] = repo_id
root = Path(folder_path)
paths = [p.relative_to(root).as_posix() for p in root.rglob("*") if p.is_file()]
if allow_patterns is not None:
diff --git a/studio/backend/tests/test_export_hub_push.py b/studio/backend/tests/test_export_hub_push.py
index 5b8496ccbaa..465b7e52eae 100644
--- a/studio/backend/tests/test_export_hub_push.py
+++ b/studio/backend/tests/test_export_hub_push.py
@@ -3,6 +3,7 @@
from __future__ import annotations
+import functools
import importlib.util
import sys
import tempfile
@@ -375,6 +376,169 @@ def test_merged_export_push_card_does_not_name_a_local_base_model(tmp_path, monk
assert str(tmp_path) not in seen["card"]
+_MLX_MERGED_FILES = ["README.md", "model.safetensors", "model.safetensors.index.json"]
+
+
+class _MlxMergeModel(_Model):
+ def __init__(self, hf_api):
+ super().__init__()
+ self.hf_api = hf_api
+
+ def save_pretrained_merged(
+ self,
+ save_directory,
+ tokenizer,
+ save_method = None,
+ token = None,
+ ):
+ self.merges.append(save_method)
+ output = Path(save_directory)
+ output.mkdir(parents = True, exist_ok = True)
+ for name in _MLX_MERGED_FILES:
+ (output / name).write_bytes(b"merged")
+
+ def push_to_hub_merged(
+ self,
+ repo_id,
+ tokenizer,
+ save_directory = None,
+ token = None,
+ private = None,
+ ):
+ api = self.hf_api(token = token)
+ api.create_repo(repo_id, private = private, exist_ok = True)
+ if private is not None:
+ api.update_repo_settings(repo_id = repo_id, private = private, repo_type = "model")
+ api.upload_folder(folder_path = str(save_directory), repo_id = repo_id, repo_type = "model")
+
+
+# export -> (ExportBackend method, is_peft, extra kwargs, save_method)
+_MLX_EXPORTS = {
+ "merged": ("export_merged_model", True, {}, "merged_16bit"),
+ "merged_4bit": ("export_merged_model", True, {"format_type": "4-bit (FP4)"}, "merged_4bit"),
+ "base": ("export_base_model", False, {}, "merged_16bit"),
+}
+
+
+def _mlx_backend(monkeypatch, name, calls, seen, export):
+ method, is_peft, kwargs, _save_method = _MLX_EXPORTS[export]
+ backend = _non_mlx_backend(monkeypatch, name, calls, seen)
+ export_module = sys.modules[type(backend).__module__]
+ monkeypatch.setattr(export_module, "_IS_MLX", True)
+ monkeypatch.setattr(export_module, "_export_runtime_available", lambda: True)
+ backend.current_model = _MlxMergeModel(export_module.HfApi)
+ backend.is_peft = is_peft
+ return backend, functools.partial(getattr(backend, method), **kwargs)
+
+
[email protected]("export", _MLX_EXPORTS)
+def test_mlx_export_push_keeps_the_export_metadata_out_of_the_repo(tmp_path, monkeypatch, export):
+ calls: list[str] = []
+ seen: dict = {}
+ backend, push = _mlx_backend(
+ monkeypatch, "test_export_hub_push_mlx_fresh_backend", calls, seen, export
+ )
+
+ success, message, output_path = push(
+ str(tmp_path / "export"),
+ push_to_hub = True,
+ repo_id = "model",
+ hf_token = "hf_fake",
+ )
+
+ assert success is True, message
+ assert seen["uploaded"] == _MLX_MERGED_FILES
+ assert seen["upload_repo"] == "owner/model"
+ assert Path(output_path, "export_metadata.json").is_file()
+ assert backend.current_model.merges == [_MLX_EXPORTS[export][3]]
+ assert seen["folder"] == output_path
+
+
[email protected]("export", _MLX_EXPORTS)
+def test_mlx_export_push_to_a_reused_folder_does_not_upload_its_leftovers(
+ tmp_path, monkeypatch, export
+):
+ calls: list[str] = []
+ seen: dict = {}
+ backend, push = _mlx_backend(
+ monkeypatch, "test_export_hub_push_mlx_reused_backend", calls, seen, export
+ )
+ export_dir = tmp_path / "export"
+ export_dir.mkdir()
+ (export_dir / "adapter_config.json").write_text("{}")
+ (export_dir / "adapters.safetensors").write_bytes(b"lora")
+
+ success, message, output_path = push(
+ str(export_dir),
+ push_to_hub = True,
+ repo_id = "model",
+ hf_token = "hf_fake",
+ )
+
+ assert success is True, message
+ assert seen["uploaded"] == _MLX_MERGED_FILES
+ assert output_path == str(export_dir.resolve())
+ assert backend.current_model.merges == [_MLX_EXPORTS[export][3]] * 2
+ assert seen["folder"] != output_path
+ assert not Path(seen["folder"]).exists()
+
+
[email protected]("export", _MLX_EXPORTS)
+def test_mlx_export_staging_failure_leaves_the_hub_untouched(tmp_path, monkeypatch, export):
+ calls: list[str] = []
+ seen: dict = {}
+ backend, push = _mlx_backend(
+ monkeypatch, "test_export_hub_push_mlx_stage_failure", calls, seen, export
+ )
+ export_dir = tmp_path / "export"
+ export_dir.mkdir()
+ (export_dir / "old.gguf").write_bytes(b"GGUF")
+ save = backend.current_model.save_pretrained_merged
+
+ def fail_staging(directory, *args, **kwargs):
+ save(directory, *args, **kwargs)
+ if len(backend.current_model.merges) == 2:
+ raise OSError(28, "No space left on device")
+
+ monkeypatch.setattr(backend.current_model, "save_pretrained_merged", fail_staging)
+ success, message, _path = push(
+ str(export_dir), push_to_hub = True, repo_id = "model", hf_token = "hf_fake"
+ )
+
+ assert success is False
+ assert "No space left on device" in message
+ assert Path(export_dir, "model.safetensors").is_file()
+ assert calls == []
+
+
[email protected]("export", _MLX_EXPORTS)
[email protected]("private", [True, False])
+def test_mlx_export_push_never_makes_an_existing_private_repo_public(
+ tmp_path, monkeypatch, private, export
+):
+ calls: list[str] = []
+ seen: dict = {}
+ _backend, push = _mlx_backend(
+ monkeypatch, "test_export_hub_push_mlx_private_backend", calls, seen, export
+ )
+
+ success, message, _path = push(
+ str(tmp_path / "export"),
+ push_to_hub = True,
+ repo_id = "owner/model",
+ hf_token = "hf_fake",
+ private = private,
+ )
+
+ assert success is True, message
+ visibility = ["update_repo_settings"] if private else []
+ assert calls == ["create_repo", *visibility, "upload_folder"]
+ assert seen.get("visibility") == (
+ {"repo_id": "owner/model", "private": True} if private else None
+ )
+ assert seen["uploaded"] == _MLX_MERGED_FILES
+
+
def test_base_export_push_keeps_the_export_metadata_out_of_the_repo(tmp_path, monkeypatch):
calls: list[str] = []
seen: dict = {}