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.

Export full fine-tunes in 16-bit from the CLI by default (#11716)

Nilay16f636a7a82b
diff --git a/studio/backend/core/export/orchestrator.py b/studio/backend/core/export/orchestrator.py
index f7b5dc2a9f3..d8e712bb05a 100644
--- a/studio/backend/core/export/orchestrator.py
+++ b/studio/backend/core/export/orchestrator.py
@@ -470,7 +470,7 @@ class ExportOrchestrator:
self,
checkpoint_path: str,
max_seq_length: int = 2048,
- load_in_4bit: bool = True,
+ load_in_4bit: Optional[bool] = True,
trust_remote_code: bool = False,
approved_remote_code_fingerprint: Optional[str] = None,
hf_token: HfTokenArg = None,
@@ -483,8 +483,18 @@ class ExportOrchestrator:
Always spawns a fresh subprocess to ensure a clean Python interpreter.
``base_model`` pins an already authorized adapter base; the worker then ignores the
adapter config, which its owner can rewrite after the check.
+ ``load_in_4bit = None`` picks 16-bit for an unquantized full fine-tune, else 4-bit.
"""
validate_job_paths({"checkpoint_path": checkpoint_path})
+ if load_in_4bit is None:
+ from utils.models.checkpoints import is_unquantized_full_finetune
+ load_in_4bit = not is_unquantized_full_finetune(checkpoint_path, hf_token)
+ if not load_in_4bit:
+ logger.info(
+ "Full fine-tune checkpoint %s has no quantization_config - "
+ "loading in 16-bit for export",
+ checkpoint_path,
+ )
sub_config = {
"checkpoint_path": checkpoint_path,
"base_model": base_model,
diff --git a/studio/backend/mcp_server.py b/studio/backend/mcp_server.py
index 35b2109318c..3125c28719e 100644
--- a/studio/backend/mcp_server.py
+++ b/studio/backend/mcp_server.py
@@ -210,7 +210,7 @@ def create_studio_mcp() -> FastMCP:
from models import LoadCheckpointRequest
from routes.export import load_checkpoint as load
- # Omit an unset load_in_4bit so the route can pick 16-bit for a full fine-tune.
+ # Omit an unset load_in_4bit so the backend can pick 16-bit for a full fine-tune.
optional = {} if load_in_4bit is None else {"load_in_4bit": load_in_4bit}
request = LoadCheckpointRequest(
checkpoint_path = checkpoint_path,
diff --git a/studio/backend/routes/export.py b/studio/backend/routes/export.py
index c9bc02ee772..25622a9479e 100644
--- a/studio/backend/routes/export.py
+++ b/studio/backend/routes/export.py
@@ -111,49 +111,6 @@ def _authorized_adapter_base(checkpoint_path: str) -> Optional[str]:
return base or None
-def _hub_config(repo_id: str, hf_token: HfTokenArg) -> Optional[dict]:
- """config.json for a Hub repo id, or None when it cannot be resolved.
-
- The worker loads remote checkpoints too, so a Hub id that never touches the local
- filesystem would otherwise keep the 4-bit default and re-introduce the very export
- this function exists to prevent. Only config.json is fetched -- a few KB against the
- gigabytes the load is about to pull anyway, and cached by huggingface_hub after the
- first call.
-
- Every failure (offline, gated without a token, no such repo, no network) returns
- None, which the caller reads as "unknown" and leaves on the historical default.
- """
- try:
- from huggingface_hub import file_exists, hf_hub_download
-
- # An adapter repo carries a base config.json as well, so this has to be asked
- # first or a remote LoRA reads as a full model.
- if file_exists(repo_id, "adapter_config.json", token = hf_token):
- return None
- path = hf_hub_download(repo_id, "config.json", token = hf_token)
- return json.loads(Path(path).read_text(encoding = "utf-8-sig"))
- except Exception:
- return None
-
-
-def _is_unquantized_full_finetune(checkpoint_path: str, hf_token: HfTokenArg = None) -> bool:
- """Whether this checkpoint is a full model that is not already quantized.
-
- Only ever used to turn 4-bit OFF, so every uncertain answer here is False and
- behaves exactly as the code did before.
- """
- from utils.models.checkpoints import is_unquantized_full_model_dir
-
- try:
- is_local = Path(checkpoint_path).exists()
- except OSError:
- return False
- if is_local:
- return is_unquantized_full_model_dir(checkpoint_path)
- config = _hub_config(checkpoint_path, hf_token)
- return isinstance(config, dict) and "quantization_config" not in config
-
-
@router.post("/load-checkpoint", response_model = ExportOperationResponse)
async def load_checkpoint(
request: LoadCheckpointRequest,
@@ -172,17 +129,8 @@ async def load_checkpoint(
try:
await _ensure_export_supported()
export_hf_token = _resolve_export_hf_token(request.hf_token, allow_ambient = allow_ambient)
- load_in_4bit = request.load_in_4bit
- # Off-loop: a Hub id makes this reach the network, and the SSE log stream is
- # served from this same event loop.
- if "load_in_4bit" not in request.model_fields_set and await asyncio.to_thread(
- _is_unquantized_full_finetune, request.checkpoint_path, export_hf_token
- ):
- load_in_4bit = False
- logger.info(
- f"Full fine-tune checkpoint {request.checkpoint_path} has no quantization_config - "
- "loading in 16-bit for export"
- )
+ # Unset lets the backend pick 16-bit for a full fine-tune.
+ load_in_4bit = request.load_in_4bit if "load_in_4bit" in request.model_fields_set else None
backend = get_export_backend()
# Run in a worker thread (spawns and waits on a subprocess, can take
# minutes) so the event loop stays free to serve the live log SSE stream.
diff --git a/studio/backend/tests/test_export_load_checkpoint_full_finetune.py b/studio/backend/tests/test_export_load_checkpoint_full_finetune.py
index c0bbd3ba0a8..87dbe419ede 100644
--- a/studio/backend/tests/test_export_load_checkpoint_full_finetune.py
+++ b/studio/backend/tests/test_export_load_checkpoint_full_finetune.py
@@ -10,6 +10,7 @@ from fastapi.testclient import TestClient
from auth.authentication import allow_ambient_hf_token, get_current_subject
from routes import export as export_routes
+from utils.models import checkpoints
async def _fake_ensure_export_supported():
@@ -30,57 +31,52 @@ _BNB_QUANTIZED = {
_MALFORMED_CONFIG = {"config.json": "{not json"}
+def _load_via_orchestrator(
+ monkeypatch,
+ checkpoint_path,
+ load_in_4bit,
+ hf_token = None,
+):
+ from core.export.orchestrator import ExportOrchestrator
+
+ backend = ExportOrchestrator()
+ spawned = {}
+ monkeypatch.setattr(backend, "_ensure_subprocess_alive", lambda: False)
+ monkeypatch.setattr(backend, "_spawn_subprocess", spawned.update)
+ monkeypatch.setattr(
+ backend, "_wait_response", lambda *a, **k: {"success": True, "message": "loaded"}
+ )
+ assert backend.load_checkpoint(checkpoint_path, load_in_4bit = load_in_4bit, hf_token = hf_token)[0]
+ return spawned["load_in_4bit"]
+
+
@pytest.mark.parametrize(
- "files,extra,expected",
+ "files,load_in_4bit,expected",
[
- (_FULL_FINETUNE, {}, False),
- (_FULL_FINETUNE, {"load_in_4bit": True}, True),
- (_LORA_ADAPTER, {}, True),
- (_BNB_QUANTIZED, {}, True),
- (_MALFORMED_CONFIG, {}, True),
+ (_FULL_FINETUNE, None, False),
+ (_FULL_FINETUNE, True, True),
+ (_LORA_ADAPTER, None, True),
+ (_LORA_ADAPTER, False, False),
+ (_BNB_QUANTIZED, None, True),
+ (_MALFORMED_CONFIG, None, True),
],
ids = [
"full_finetune",
"full_finetune_explicit_4bit",
"lora_adapter",
+ "lora_adapter_explicit_16bit",
"bnb_quantized",
"malformed_config",
],
)
def test_load_checkpoint_uses_16bit_for_unquantized_full_finetunes(
- monkeypatch, tmp_path, files, extra, expected
+ monkeypatch, tmp_path, files, load_in_4bit, expected
):
for name, content in files.items():
text = content if isinstance(content, str) else json.dumps(content)
(tmp_path / name).write_text(text, encoding = "utf-8")
- monkeypatch.setattr(export_routes, "_ensure_export_supported", _fake_ensure_export_supported)
- backend = MagicMock()
- backend.load_checkpoint.return_value = (True, "loaded")
- monkeypatch.setattr(export_routes, "get_export_backend", lambda: backend)
-
- app = FastAPI()
- app.include_router(export_routes.router, prefix = "/api/export")
- app.dependency_overrides[get_current_subject] = lambda: "alice"
- app.dependency_overrides[allow_ambient_hf_token] = lambda: True
-
- response = TestClient(app).post(
- "/api/export/load-checkpoint",
- json = {"checkpoint_path": str(tmp_path), "hf_token": None, **extra},
- )
-
- assert response.status_code == 200
- assert backend.load_checkpoint.call_args.kwargs["load_in_4bit"] is expected
-
-
-def _hub_client(monkeypatch, backend):
- monkeypatch.setattr(export_routes, "_ensure_export_supported", _fake_ensure_export_supported)
- monkeypatch.setattr(export_routes, "get_export_backend", lambda: backend)
- app = FastAPI()
- app.include_router(export_routes.router, prefix = "/api/export")
- app.dependency_overrides[get_current_subject] = lambda: "alice"
- app.dependency_overrides[allow_ambient_hf_token] = lambda: True
- return TestClient(app)
+ assert _load_via_orchestrator(monkeypatch, str(tmp_path), load_in_4bit) is expected
@pytest.mark.parametrize(
@@ -99,22 +95,59 @@ def _hub_client(monkeypatch, backend):
def test_load_checkpoint_resolves_hub_ids_before_choosing_4bit(
monkeypatch, tmp_path, adapter_on_hub, hub_config, expected
):
- """A Hub id never touches the local filesystem, so without this the request keeps the
- request model's True default and a remote full fine-tune exports as 4-bit anyway."""
+ """A Hub id never touches the local filesystem, so its config.json has to be fetched."""
+ import huggingface_hub
+
config_file = tmp_path / "config.json"
config_file.write_text(json.dumps(hub_config), encoding = "utf-8")
+ tokens = []
- monkeypatch.setattr(
- export_routes,
- "_hub_config",
- lambda repo_id, hf_token: None if adapter_on_hub else hub_config,
+ def _file_exists(
+ repo_id,
+ filename,
+ token = None,
+ ):
+ tokens.append(token)
+ return adapter_on_hub and filename == "adapter_config.json"
+
+ def _hf_hub_download(
+ repo_id,
+ filename,
+ token = None,
+ ):
+ tokens.append(token)
+ return str(config_file)
+
+ monkeypatch.setattr(huggingface_hub, "file_exists", _file_exists)
+ monkeypatch.setattr(huggingface_hub, "hf_hub_download", _hf_hub_download)
+
+ # False is the "ambient token denied" sentinel; it must reach the Hub unchanged.
+ load_in_4bit = _load_via_orchestrator(
+ monkeypatch, "unsloth/Llama-3.2-1B-Instruct", None, hf_token = False
)
+ assert load_in_4bit is expected
+ assert tokens and all(token is False for token in tokens)
+
+
+ "extra,expected",
+ [({}, None), ({"load_in_4bit": True}, True), ({"load_in_4bit": False}, False)],
+ ids = ["unset", "explicit_4bit", "explicit_16bit"],
+)
+def test_route_leaves_unset_load_in_4bit_to_the_backend(monkeypatch, tmp_path, extra, expected):
+ monkeypatch.setattr(export_routes, "_ensure_export_supported", _fake_ensure_export_supported)
backend = MagicMock()
backend.load_checkpoint.return_value = (True, "loaded")
+ monkeypatch.setattr(export_routes, "get_export_backend", lambda: backend)
- response = _hub_client(monkeypatch, backend).post(
+ app = FastAPI()
+ app.include_router(export_routes.router, prefix = "/api/export")
+ app.dependency_overrides[get_current_subject] = lambda: "alice"
+ app.dependency_overrides[allow_ambient_hf_token] = lambda: True
+
+ response = TestClient(app).post(
"/api/export/load-checkpoint",
- json = {"checkpoint_path": "unsloth/Llama-3.2-1B-Instruct", "hf_token": None},
+ json = {"checkpoint_path": str(tmp_path), "hf_token": None, **extra},
)
assert response.status_code == 200
@@ -135,5 +168,5 @@ def test_hub_lookup_failure_keeps_the_old_default(monkeypatch):
import huggingface_hub
monkeypatch.setattr(huggingface_hub, "file_exists", _boom, raising = False)
- assert export_routes._hub_config("org/model", None) is None
- assert export_routes._is_unquantized_full_finetune("org/model", None) is False
+ assert checkpoints._hub_model_config("org/model", None) is None
+ assert checkpoints.is_unquantized_full_finetune("org/model", None) is False
diff --git a/studio/backend/utils/models/checkpoints.py b/studio/backend/utils/models/checkpoints.py
index 9bbc49e9709..8c608277368 100644
--- a/studio/backend/utils/models/checkpoints.py
+++ b/studio/backend/utils/models/checkpoints.py
@@ -11,6 +11,7 @@ import structlog
from loggers import get_logger
from pathlib import Path
from typing import List, Optional, Tuple
+from hub.utils.hf_tokens import HfTokenArg
from storage.studio_db import get_connection
from utils.training_runs import (
build_default_output_dir_name,
@@ -280,6 +281,34 @@ def is_unquantized_full_model_dir(path: str | Path) -> bool:
return isinstance(config, dict) and "quantization_config" not in config
+def _hub_model_config(repo_id: str, hf_token: HfTokenArg) -> Optional[dict]:
+ """config.json of a Hub model repo; None for an adapter repo or on any lookup failure."""
+ try:
+ from huggingface_hub import file_exists, hf_hub_download
+
+ # An adapter repo carries a base config.json too, so a remote LoRA would read as a full model.
+ if file_exists(repo_id, "adapter_config.json", token = hf_token):
+ return None
+ path = hf_hub_download(repo_id, "config.json", token = hf_token)
+ return json.loads(Path(path).read_text(encoding = "utf-8-sig"))
+ except Exception:
+ return None
+
+
+def is_unquantized_full_finetune(checkpoint_path: str, hf_token: HfTokenArg = None) -> bool:
+ """Whether a local or Hub checkpoint is an unquantized full model.
+
+ False when unsure, so the caller keeps the 4-bit load that used to fit."""
+ try:
+ is_local = Path(checkpoint_path).exists()
+ except OSError:
+ return False
+ if is_local:
+ return is_unquantized_full_model_dir(checkpoint_path)
+ config = _hub_model_config(checkpoint_path, hf_token)
+ return isinstance(config, dict) and "quantization_config" not in config
+
+
def is_full_finetune_output(path: Optional[str]) -> bool:
if not path:
return False
diff --git a/unsloth_cli/commands/export.py b/unsloth_cli/commands/export.py
index 938389d926d..c72c0a81814 100644
--- a/unsloth_cli/commands/export.py
+++ b/unsloth_cli/commands/export.py
@@ -64,7 +64,12 @@ def export(
),
private: bool = typer.Option(False, "--private", help = "Make the HuggingFace repo private."),
max_seq_length: int = typer.Option(2048, "--max-seq-length"),
- load_in_4bit: bool = typer.Option(True, "--load-in-4bit/--no-load-in-4bit"),
+ load_in_4bit: Optional[bool] = typer.Option(
+ None,
+ "--load-in-4bit/--no-load-in-4bit",
+ help = "Load the checkpoint in 4-bit. Default: 16-bit for an unquantized full model "
+ "(except with merged-4bit), 4-bit otherwise.",
+ ),
):
"""Export a checkpoint to various formats (merged, GGUF, LoRA adapter)."""
if format not in EXPORT_FORMATS:
@@ -78,6 +83,10 @@ def export(
typer.echo("Error: --repo-id required when using --push-to-hub", err = True)
raise typer.Exit(code = 2)
+ # A full model is saved as loaded, so merged-4bit still needs the 4-bit load.
+ if load_in_4bit is None and format == "merged-4bit":
+ load_in_4bit = True
+
with studio_backend_imports("unsloth export"):
from studio.backend.core.export import ExportBackend
diff --git a/unsloth_cli/tests/test_export_load_in_4bit.py b/unsloth_cli/tests/test_export_load_in_4bit.py
new file mode 100644
index 00000000000..0d5addbeb81
--- /dev/null
+++ b/unsloth_cli/tests/test_export_load_in_4bit.py
@@ -0,0 +1,60 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import contextlib
+import sys
+import types
+
+import pytest
+import typer
+from typer.testing import CliRunner
+
+from unsloth_cli.commands import export as export_command
+
+
+ "flags,expected",
+ [
+ ([], None),
+ (["--format", "gguf"], None),
+ (["--load-in-4bit"], True),
+ (["--no-load-in-4bit"], False),
+ (["--format", "merged-4bit"], True),
+ (["--format", "merged-4bit", "--no-load-in-4bit"], False),
+ ],
+ ids = [
+ "default",
+ "gguf_default",
+ "explicit_4bit",
+ "explicit_16bit",
+ "merged_4bit_default",
+ "merged_4bit_explicit_16bit",
+ ],
+)
+def test_export_load_in_4bit_default_per_format(monkeypatch, tmp_path, flags, expected):
+ calls = {}
+
+ class ExportBackend:
+ def load_checkpoint(self, **kwargs):
+ calls.update(kwargs)
+ return True, "loaded"
+
+ def export_merged_model(self, **kwargs):
+ return True, "exported", kwargs["save_directory"]
+
+ def export_gguf(self, **kwargs):
+ return True, "exported", kwargs["save_directory"]
+
+ module = types.ModuleType("studio.backend.core.export")
+ module.ExportBackend = ExportBackend
+ monkeypatch.setitem(sys.modules, "studio.backend.core.export", module)
+ monkeypatch.setattr(
+ export_command, "studio_backend_imports", lambda *a, **k: contextlib.nullcontext()
+ )
+
+ app = typer.Typer()
+ app.command()(export_command.export)
+ result = CliRunner().invoke(app, [str(tmp_path), str(tmp_path / "out"), *flags])
+
+ assert result.exit_code == 0, result.output
+ assert calls["load_in_4bit"] is expected