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.
Python agentaichatgptdeepseekfine-tuninggemmaimage-generationllamallmllmsopenaipythonqwenreinforcement-learningself-hostedstable-diffusiontext-to-speechttsuiunsloth
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.pyindex 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 theadapter 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.pyindex 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 LoadCheckpointRequestfrom 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.pyindex 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 Nonebackend = 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.pyindex 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 TestClientfrom auth.authentication import allow_ambient_hf_token, get_current_subjectfrom routes import export as export_routes+from utils.models import checkpointsasync 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_hubmonkeypatch.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 Falsediff --git a/studio/backend/utils/models/checkpoints.py b/studio/backend/utils/models/checkpoints.pyindex 9bbc49e9709..8c608277368 100644--- a/studio/backend/utils/models/checkpoints.py+++ b/studio/backend/utils/models/checkpoints.py@@ -11,6 +11,7 @@ import structlogfrom loggers import get_loggerfrom pathlib import Pathfrom typing import List, Optional, Tuple+from hub.utils.hf_tokens import HfTokenArgfrom storage.studio_db import get_connectionfrom 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 Falsediff --git a/unsloth_cli/commands/export.py b/unsloth_cli/commands/export.pyindex 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 ExportBackenddiff --git a/unsloth_cli/tests/test_export_load_in_4bit.py b/unsloth_cli/tests/test_export_load_in_4bit.pynew file mode 100644index 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