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: keep a LoRA push private when the Hub repo already exists (#11229)

Nilayc14892baf1e3
diff --git a/studio/backend/core/export/export.py b/studio/backend/core/export/export.py
index 86823d2d9ae..b8ac5f3ef44 100644
--- a/studio/backend/core/export/export.py
+++ b/studio/backend/core/export/export.py
@@ -488,6 +488,48 @@ def _ensure_hub_repo_private(hf_api, repo_id):
) from exception
+def _open_hub_repo(hf_api, repo_id, private):
+ """Create or reuse the repo we are about to upload into, private before anything lands.
+
+ Call this immediately before the upload, not earlier: it is what turns a failure after
+ this point into an empty repo.
+ """
+ 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)
+ 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.
+
+ Unsloth's `upload_to_huggingface` only writes it when its own `create_repo(exist_ok=False)`
+ finds the repo absent, so opening the repo first silently costs a fresh push its card.
+ Best-effort, and an existing card is kept, exactly as the merged and base paths do.
+ """
+ try:
+ if hf_api.file_exists(repo_id, "README.md", repo_type = "model"):
+ return
+ config = getattr(model, "config", None)
+ if config is None:
+ return
+ base_model = getattr(config, "_name_or_path", "unknown") or "unknown"
+ # method/extra reproduce what upload_to_huggingface passed for this path
+ # ("finetuned", "trl"): the template already carries the unsloth tag, so `extra`
+ # is where trl goes, and the heading already reads "Uploaded finetuned ... model".
+ 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(config, "model_type", "llm"),
+ method = "",
+ extra = "trl",
+ )
+ 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}")
+
+
class ExportBackend:
def __init__(self):
self.inference_backend = get_inference_backend()
@@ -1627,17 +1669,18 @@ class ExportBackend:
logger.info(f"Pushing LoRA adapter to Hub: {repo_id}")
+ # Needs a local save_directory so the conversion is not re-run.
+ if gguf and not (output_path and Path(output_path).is_dir()):
+ return (
+ False,
+ "GGUF LoRA Hub upload requires a local save directory; set one and retry.",
+ None,
+ )
+
+ hf_api = HfApi(token = hf_token)
+
if gguf:
- # Needs a local save_directory so the conversion is not re-run.
- if not (output_path and Path(output_path).is_dir()):
- return (
- False,
- "GGUF LoRA Hub upload requires a local save directory; set one and "
- "retry.",
- None,
- )
- hf_api = HfApi(token = hf_token)
- hf_api.create_repo(repo_id, private = private, exist_ok = True)
+ repo_id = _open_hub_repo(hf_api, repo_id, private)
hf_api.upload_folder(
folder_path = output_path,
repo_id = repo_id,
@@ -1645,16 +1688,22 @@ class ExportBackend:
)
elif _IS_MLX:
with tempfile.TemporaryDirectory() as tmp_dir:
+ # Serialise first: opening the repo before this would leave an empty
+ # one behind whenever the adapter or tokenizer fails to write.
self.current_model.save_lora_adapters(tmp_dir)
self.current_tokenizer.save_pretrained(tmp_dir)
- hf_api = HfApi(token = hf_token)
- hf_api.create_repo(repo_id, private = private, exist_ok = True)
+ repo_id = _open_hub_repo(hf_api, repo_id, private)
hf_api.upload_folder(
folder_path = tmp_dir,
repo_id = repo_id,
repo_type = "model",
)
else:
+ # Opened here rather than left to push_to_hub: a repo that does not exist
+ # yet is one another client can create public first, and `private` cannot
+ # change an existing repo's visibility, so the adapter would land in it.
+ repo_id = _open_hub_repo(hf_api, repo_id, private)
+ _publish_unsloth_model_card(hf_api, repo_id, self.current_model, hf_token)
self.current_model.push_to_hub(repo_id, token = hf_token, private = private)
self.current_tokenizer.push_to_hub(repo_id, token = hf_token, private = private)
logger.info(f"Adapter pushed successfully to {repo_id}")
diff --git a/studio/backend/tests/test_export_gguf_hub_upload.py b/studio/backend/tests/test_export_gguf_hub_upload.py
index 6284afcac0e..304ff68aa06 100644
--- a/studio/backend/tests/test_export_gguf_hub_upload.py
+++ b/studio/backend/tests/test_export_gguf_hub_upload.py
@@ -63,6 +63,16 @@ def _hub_doubles(calls, seen):
calls.append("repo_info")
return seen.get("repo_info_result")
+ def repo_exists(
+ self,
+ repo_id,
+ repo_type = None,
+ ):
+ calls.append("repo_exists")
+ # Default True: the interesting case is an existing repo, and a test that wants
+ # a fresh one says so.
+ return seen.get("repo_exists", True)
+
def file_exists(
self,
repo_id,
diff --git a/studio/backend/tests/test_export_hub_push.py b/studio/backend/tests/test_export_hub_push.py
index 79c6e210eb9..fd66015d612 100644
--- a/studio/backend/tests/test_export_hub_push.py
+++ b/studio/backend/tests/test_export_hub_push.py
@@ -373,3 +373,246 @@ def test_merged_export_push_card_does_not_name_a_local_base_model(tmp_path, monk
assert success is True, message
assert "base_model: owner/model" in seen["card"]
assert str(tmp_path) not in seen["card"]
+
+
+class _LoraTokenizer(_Tokenizer):
+ def __init__(self, calls):
+ self.calls = calls
+
+ def push_to_hub(
+ self,
+ repo_id,
+ token = None,
+ private = None,
+ ):
+ self.calls.append(f"tokenizer_push:{repo_id}")
+
+
+class _LoraModel:
+ config = _Config()
+ peft_config: dict = {}
+
+ def __init__(self, calls):
+ self.calls = calls
+
+ def save_pretrained(self, save_directory):
+ Path(save_directory, "adapter_model.safetensors").write_bytes(b"weights")
+
+ def save_lora_adapters(self, save_directory):
+ Path(save_directory, "adapters.safetensors").write_bytes(b"weights")
+
+ def save_pretrained_gguf(
+ self,
+ save_directory,
+ tokenizer,
+ save_method = None,
+ quantization_method = None,
+ token = None,
+ ):
+ Path(save_directory, "model-lora-q8_0.gguf").write_bytes(b"GGUF")
+
+ def push_to_hub(
+ self,
+ repo_id,
+ token = None,
+ private = None,
+ ):
+ self.calls.append(f"model_push:{repo_id}")
+
+
+# leg -> (gguf, is_mlx, what lands in the repo)
+# Every leg opens the repo itself: leaving a fresh one to push_to_hub would let another
+# client create it public in the gap. The adapter leg writes the model card that the
+# delegated push can then no longer write.
+_LORA_LEGS = {
+ "adapter": (
+ False,
+ False,
+ ["model_card", "model_push:owner/model", "tokenizer_push:owner/model"],
+ ),
+ "gguf": (True, False, ["upload_folder"]),
+ "mlx": (False, True, ["upload_folder"]),
+}
+
+
+def _lora_backend(monkeypatch, name, calls, seen, leg):
+ gguf, is_mlx, uploads = _LORA_LEGS[leg]
+ backend = _non_mlx_backend(monkeypatch, name, calls, seen)
+ export_module = sys.modules[type(backend).__module__]
+ monkeypatch.setattr(export_module, "_IS_MLX", is_mlx)
+ monkeypatch.setattr(export_module, "_export_runtime_available", lambda: True)
+ monkeypatch.setattr(export_module, "_apply_wsl_sudo_patch", lambda: None)
+ backend.current_model = _LoraModel(calls)
+ backend.current_tokenizer = _LoraTokenizer(calls)
+ backend.is_peft = True
+ return export_module, backend, gguf, uploads
+
+
+def _push_lora(backend, save_directory, gguf, private):
+ return backend.export_lora_adapter(
+ save_directory,
+ push_to_hub = True,
+ repo_id = "model",
+ hf_token = "hf_fake",
+ private = private,
+ gguf = gguf,
+ )
+
+
[email protected]("leg", list(_LORA_LEGS))
[email protected]("private", [True, False])
+def test_lora_export_push_makes_an_existing_repo_private_before_uploading(
+ tmp_path, monkeypatch, leg, private
+):
+ calls: list[str] = []
+ seen: dict = {}
+ _module, backend, gguf, uploads = _lora_backend(
+ monkeypatch, f"test_export_hub_push_lora_{leg}_backend", calls, seen, leg
+ )
+
+ success, message, _path = _push_lora(backend, str(tmp_path / "export"), gguf, private)
+
+ assert success is True, message
+ assert seen["token"] == "hf_fake"
+ assert seen["repo"] == {"repo_id": "model", "private": private, "exist_ok": True}
+ visibility = ["update_repo_settings"] if private else []
+ assert calls == ["create_repo", *visibility, *uploads]
+ if private:
+ assert seen["visibility"] == {"repo_id": "owner/model", "private": True}
+ else:
+ assert "visibility" not in seen
+
+
[email protected]("leg", list(_LORA_LEGS))
+def test_lora_export_push_refuses_to_upload_when_privacy_cannot_be_confirmed(
+ tmp_path, monkeypatch, leg
+):
+ calls: list[str] = []
+ seen: dict = {}
+ module, backend, gguf, _uploads = _lora_backend(
+ monkeypatch, f"test_export_hub_push_lora_{leg}_denied_backend", calls, seen, leg
+ )
+
+ def _denied(
+ self,
+ repo_id,
+ private = None,
+ repo_type = None,
+ ):
+ raise RuntimeError("403 Forbidden: write:repo_settings missing")
+
+ monkeypatch.setattr(module.HfApi, "update_repo_settings", _denied)
+ seen["repo_info_result"] = types.SimpleNamespace(private = False)
+
+ success, message, output_path = _push_lora(backend, str(tmp_path / "export"), gguf, True)
+
+ assert success is False
+ assert "could not be confirmed private" in message
+ assert output_path is None
+ assert calls == ["create_repo", "repo_info"]
+
+
[email protected]("leg", list(_LORA_LEGS))
+def test_lora_export_push_uploads_when_the_repo_is_already_private(tmp_path, monkeypatch, leg):
+ calls: list[str] = []
+ seen: dict = {}
+ module, backend, gguf, uploads = _lora_backend(
+ monkeypatch, f"test_export_hub_push_lora_{leg}_ok_backend", calls, seen, leg
+ )
+
+ def _denied(
+ self,
+ repo_id,
+ private = None,
+ repo_type = None,
+ ):
+ raise RuntimeError("403 Forbidden: write:repo_settings missing")
+
+ monkeypatch.setattr(module.HfApi, "update_repo_settings", _denied)
+ seen["repo_info_result"] = types.SimpleNamespace(private = True)
+
+ success, message, _path = _push_lora(backend, str(tmp_path / "export"), gguf, True)
+
+ assert success is True, message
+ assert calls == ["create_repo", "repo_info", *uploads]
+
+
+def test_lora_adapter_push_writes_the_card_the_delegated_push_can_no_longer_write(
+ tmp_path, monkeypatch
+):
+ """Opening the repo first makes Unsloth's wrapper skip its own card, so we write it.
+
+ `upload_to_huggingface` writes MODEL_CARD only when its `create_repo(exist_ok=False)`
+ finds the repo absent, which opening it here makes impossible.
+ """
+ calls: list[str] = []
+ seen: dict = {}
+ _module, backend, gguf, _uploads = _lora_backend(
+ monkeypatch, "test_export_hub_push_lora_card_backend", calls, seen, "adapter"
+ )
+
+ success, message, _path = _push_lora(backend, str(tmp_path / "export"), gguf, True)
+
+ assert success is True, message
+ assert seen["card_repo"] == "owner/model"
+ assert "base_model: unsloth/Qwen2.5-0.5B-Instruct" in seen["card"]
+ # Same tags upload_to_huggingface produced for this path, trl included and unsloth
+ # not duplicated (the template already carries it).
+ tags = seen["card"].split("tags:", 1)[1].split("license:", 1)[0]
+ assert sorted(line.strip("- ").strip() for line in tags.strip().splitlines()) == [
+ "qwen2",
+ "text-generation-inference",
+ "transformers",
+ "trl",
+ "unsloth",
+ ]
+ # empty `method` leaves a double space the template supplies; markdown collapses it
+ assert "# Uploaded finetuned model" in seen["card"]
+ # written before the weights, never after
+ assert calls.index("model_card") < calls.index("model_push:owner/model")
+
+
+def test_lora_adapter_push_keeps_the_card_of_an_existing_repo(tmp_path, monkeypatch):
+ calls: list[str] = []
+ seen: dict = {"existing_files": {"README.md": True}}
+ _module, backend, gguf, _uploads = _lora_backend(
+ monkeypatch, "test_export_hub_push_lora_keepcard_backend", calls, seen, "adapter"
+ )
+
+ success, message, _path = _push_lora(backend, str(tmp_path / "export"), gguf, True)
+
+ assert success is True, message
+ assert "card" not in seen
+ assert calls == [
+ "create_repo",
+ "update_repo_settings",
+ "model_push:owner/model",
+ "tokenizer_push:owner/model",
+ ]
+
+
+def test_lora_mlx_push_that_cannot_serialise_leaves_no_repo_behind(tmp_path, monkeypatch):
+ """The repo is opened after serialisation, so a failed save cannot orphan one."""
+ calls: list[str] = []
+ seen: dict = {}
+ _module, backend, gguf, _uploads = _lora_backend(
+ monkeypatch, "test_export_hub_push_lora_mlx_orphan_backend", calls, seen, "mlx"
+ )
+
+ saves = {"n": 0}
+ real_save = backend.current_model.save_lora_adapters
+
+ def _fail_the_upload_save(save_directory):
+ saves["n"] += 1
+ if saves["n"] >= 2: # 1st is the local save, 2nd is the temp dir to upload
+ raise RuntimeError("MLX serialization failed")
+ real_save(save_directory)
+
+ backend.current_model.save_lora_adapters = _fail_the_upload_save
+
+ success, message, _path = _push_lora(backend, str(tmp_path / "export"), gguf, True)
+
+ assert success is False
+ assert "MLX serialization failed" in message
+ assert calls == [] # no create_repo, no tightening, no upload
+ assert "repo" not in seen