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 files to the Hugging Face Hub (#11299)

Nilayf75a4f184a7e
diff --git a/studio/backend/core/export/export.py b/studio/backend/core/export/export.py
index b8ac5f3ef44..977ccc61d22 100644
--- a/studio/backend/core/export/export.py
+++ b/studio/backend/core/export/export.py
@@ -463,6 +463,13 @@ def _staging_dir(export_parent):
return tempfile.TemporaryDirectory(prefix = _STAGING_PREFIX)
+def _dir_is_fresh(directory):
+ # Finder metadata does not count; the upload drops it anyway.
+ return not (
+ Path(directory).is_dir() and any_not_appledouble_metadata(Path(directory).iterdir())
+ )
+
+
def _holds_checkpoint_weights(directory):
return Path(directory).is_dir() and any(
entry.suffix in (".safetensors", ".bin") for entry in Path(directory).iterdir()
@@ -956,11 +963,8 @@ class ExportBackend:
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())
- )
+ # pushed as is.
+ save_dir_was_empty = _dir_is_fresh(save_directory)
ensure_dir(Path(save_directory))
# No push, but the merge resolves the base repo and save.py turns None into
@@ -1129,10 +1133,12 @@ class ExportBackend:
)
output_path: Optional[str] = None
+ save_dir_was_empty = False
try:
if save_directory:
save_directory = str(resolve_export_write_dir(save_directory))
logger.info(f"Saving base model locally to: {save_directory}")
+ save_dir_was_empty = _dir_is_fresh(save_directory)
ensure_dir(Path(save_directory))
if _IS_MLX:
@@ -1188,37 +1194,50 @@ class ExportBackend:
base_model_id or self.current_model.config._name_or_path or "unknown"
)
- 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)
- username = repo_id.split("/")[0]
-
- content = MODEL_CARD.format(
- username = username,
- base_model = base_model,
- model_type = self.current_model.config.model_type,
- method = "",
- extra = "unsloth",
- )
- card = ModelCard(content)
- card.push_to_hub(repo_id, token = hf_token, commit_message = "Unsloth Model Card")
-
- if save_directory:
- hf_api.upload_folder(
- folder_path = save_directory,
- repo_id = repo_id,
- repo_type = "model",
+ with contextlib.ExitStack() as stack:
+ upload_dir = save_directory
+ if save_directory and not 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(save_directory).parent)
+ )
+ self.current_model.save_pretrained(upload_dir)
+ self.current_tokenizer.save_pretrained(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)
+ username = repo_id.split("/")[0]
+
+ content = MODEL_CARD.format(
+ username = username,
+ base_model = base_model,
+ model_type = self.current_model.config.model_type,
+ method = "",
+ extra = "unsloth",
)
- logger.info(f"Model pushed successfully to {repo_id}")
- else:
- return (
- False,
- "Local save directory required for Hub upload",
- None,
+ card = ModelCard(content)
+ card.push_to_hub(
+ repo_id, token = hf_token, commit_message = "Unsloth Model Card"
)
+ if save_directory:
+ hf_api.upload_folder(
+ folder_path = upload_dir,
+ repo_id = repo_id,
+ repo_type = "model",
+ ignore_patterns = _HUB_UPLOAD_IGNORE,
+ )
+ logger.info(f"Model pushed successfully to {repo_id}")
+ else:
+ return (
+ False,
+ "Local save directory required for Hub upload",
+ None,
+ )
+
return True, "Model exported successfully", output_path
except Exception as e:
@@ -1620,25 +1639,30 @@ class ExportBackend:
None,
)
+ def save_lora_gguf(directory):
+ # Writes the adapter files plus "<base>-lora-<outtype>.gguf".
+ self.current_model.save_pretrained_gguf(
+ directory,
+ self.current_tokenizer,
+ save_method = "lora",
+ quantization_method = outtype,
+ # A token fetches a gated base's config; False keeps a denied caller
+ # off get_token().
+ token = normalize_token(hf_token),
+ )
+
output_path: Optional[str] = None
+ save_dir_was_empty = False
try:
if save_directory:
save_directory = str(resolve_export_write_dir(save_directory))
logger.info(f"Saving LoRA adapter locally to: {save_directory}")
+ save_dir_was_empty = _dir_is_fresh(save_directory)
ensure_dir(Path(save_directory))
if gguf:
- # Writes the adapter files plus "<base>-lora-<outtype>.gguf".
_apply_wsl_sudo_patch()
- self.current_model.save_pretrained_gguf(
- save_directory,
- self.current_tokenizer,
- save_method = "lora",
- quantization_method = outtype,
- # A token fetches a gated base's config; False keeps a denied caller
- # off get_token().
- token = normalize_token(hf_token),
- )
+ save_lora_gguf(save_directory)
# iterdir, not glob.glob: glob hides dot-leading names.
final_ggufs = sorted(
str(p)
@@ -1680,12 +1704,23 @@ class ExportBackend:
hf_api = HfApi(token = hf_token)
if gguf:
- repo_id = _open_hub_repo(hf_api, repo_id, private)
- hf_api.upload_folder(
- folder_path = output_path,
- repo_id = repo_id,
- repo_type = "model",
- )
+ with contextlib.ExitStack() as stack:
+ upload_dir = output_path
+ if not save_dir_was_empty:
+ # A reused folder can hold leftovers, so upload a clean second save
+ # instead. The converter names the GGUF's model after its folder.
+ upload_dir = os.path.join(
+ stack.enter_context(_staging_dir(Path(output_path).parent)),
+ Path(output_path).name,
+ )
+ save_lora_gguf(upload_dir)
+ 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,
+ )
elif _IS_MLX:
with tempfile.TemporaryDirectory() as tmp_dir:
# Serialise first: opening the repo before this would leave an empty
diff --git a/studio/backend/tests/test_export_hub_push.py b/studio/backend/tests/test_export_hub_push.py
index fd66015d612..5b8496ccbaa 100644
--- a/studio/backend/tests/test_export_hub_push.py
+++ b/studio/backend/tests/test_export_hub_push.py
@@ -375,6 +375,77 @@ def test_merged_export_push_card_does_not_name_a_local_base_model(tmp_path, monk
assert str(tmp_path) not in seen["card"]
+def test_base_export_push_keeps_the_export_metadata_out_of_the_repo(tmp_path, monkeypatch):
+ calls: list[str] = []
+ seen: dict = {}
+ backend = _non_mlx_backend(monkeypatch, "test_export_hub_push_base_backend", calls, seen)
+
+ success, message, output_path = backend.export_base_model(
+ str(tmp_path / "export"),
+ push_to_hub = True,
+ repo_id = "model",
+ hf_token = "hf_fake",
+ )
+
+ assert success is True, message
+ assert Path(output_path, "export_metadata.json").is_file()
+ assert seen["folder"] == output_path
+ assert seen["uploaded"] == ["model.safetensors", "tokenizer.json"]
+
+
+def test_base_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_base_backend", calls, seen)
+ export_dir = tmp_path / "export"
+ export_dir.mkdir()
+ (export_dir / "old.Q4_K_M.gguf").write_bytes(b"GGUF")
+ (export_dir / "export_metadata.json").write_text("{}")
+
+ success, message, output_path = backend.export_base_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 Path(output_path, "model.safetensors").is_file()
+ assert seen["folder"] != output_path
+ assert not Path(seen["folder"]).exists()
+ assert seen["uploaded"] == ["model.safetensors", "tokenizer.json"]
+
+
+def test_base_export_staging_failure_leaves_the_hub_untouched(tmp_path, monkeypatch):
+ calls: list[str] = []
+ seen: dict = {}
+ backend = _non_mlx_backend(monkeypatch, "test_export_hub_push_stage_failure", calls, seen)
+ export_dir = tmp_path / "export"
+ export_dir.mkdir()
+ (export_dir / "old.gguf").write_bytes(b"GGUF")
+ save = backend.current_model.save_pretrained
+ saved_to = []
+
+ def fail_staging(directory):
+ saved_to.append(directory)
+ if len(saved_to) == 2:
+ raise OSError(28, "No space left on device")
+ save(directory)
+
+ monkeypatch.setattr(backend.current_model, "save_pretrained", fail_staging)
+ success, message, _output_path = backend.export_base_model(
+ 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 len(saved_to) == 2
+ assert Path(export_dir, "model.safetensors").is_file()
+ assert not Path(saved_to[1]).exists()
+ assert calls == []
+
+
class _LoraTokenizer(_Tokenizer):
def __init__(self, calls):
self.calls = calls
@@ -394,6 +465,7 @@ class _LoraModel:
def __init__(self, calls):
self.calls = calls
+ self.conversions = []
def save_pretrained(self, save_directory):
Path(save_directory, "adapter_model.safetensors").write_bytes(b"weights")
@@ -409,7 +481,12 @@ class _LoraModel:
quantization_method = None,
token = None,
):
- Path(save_directory, "model-lora-q8_0.gguf").write_bytes(b"GGUF")
+ self.conversions.append(save_directory)
+ output = Path(save_directory)
+ output.mkdir(parents = True, exist_ok = True)
+ (output / "adapter_config.json").write_text("{}")
+ (output / "adapter_model.safetensors").write_bytes(b"lora")
+ (output / f"model-lora-{quantization_method}.gguf").write_bytes(b"GGUF")
def push_to_hub(
self,
@@ -616,3 +693,56 @@ def test_lora_mlx_push_that_cannot_serialise_leaves_no_repo_behind(tmp_path, mon
assert "MLX serialization failed" in message
assert calls == [] # no create_repo, no tightening, no upload
assert "repo" not in seen
+
+
+_LORA_GGUF_FILES = ["adapter_config.json", "adapter_model.safetensors", "model-lora-q8_0.gguf"]
+
+
+def _gguf_backend(monkeypatch, name, calls, seen):
+ _module, backend, _gguf, _uploads = _lora_backend(monkeypatch, name, calls, seen, "gguf")
+ return backend
+
+
+def test_lora_gguf_export_push_uploads_the_saved_folder(tmp_path, monkeypatch):
+ calls: list[str] = []
+ seen: dict = {}
+ backend = _gguf_backend(
+ monkeypatch, "test_export_hub_push_lora_gguf_fresh_backend", calls, seen
+ )
+ export_dir = tmp_path / "export"
+ export_dir.mkdir()
+ (export_dir / "._old.gguf").write_bytes(b"\x00\x05\x16\x07rsrc")
+
+ success, message, output_path = _push_lora(backend, str(export_dir), True, False)
+
+ assert success is True, message
+ assert backend.current_model.conversions == [str(export_dir)]
+ assert calls == ["create_repo", "upload_folder"]
+ assert seen["folder"] == output_path
+ assert seen["uploaded"] == _LORA_GGUF_FILES
+
+
+def test_lora_gguf_export_push_to_a_reused_folder_does_not_upload_its_leftovers(
+ tmp_path, monkeypatch
+):
+ calls: list[str] = []
+ seen: dict = {}
+ backend = _gguf_backend(
+ monkeypatch, "test_export_hub_push_lora_gguf_reused_backend", calls, seen
+ )
+ export_dir = tmp_path / "export"
+ export_dir.mkdir()
+ (export_dir / "model.Q4_K_M.gguf").write_bytes(b"GGUF")
+ (export_dir / "Modelfile").write_text("FROM model.Q4_K_M.gguf")
+ (export_dir / "export_metadata.json").write_text('{"base_model": "/home/me/models/base"}')
+
+ success, message, output_path = _push_lora(backend, str(export_dir), True, False)
+
+ assert success is True, message
+ assert output_path == str(export_dir.resolve())
+ assert Path(output_path, "model-lora-q8_0.gguf").is_file()
+ assert len(backend.current_model.conversions) == 2
+ assert seen["folder"] != output_path
+ assert Path(seen["folder"]).name == export_dir.name
+ assert not Path(seen["folder"]).exists()
+ assert seen["uploaded"] == _LORA_GGUF_FILES