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 loading a downloaded retired FLUX.3 full copy from disk (#14835)

Daniel Hand72ad8d5c4fa
diff --git a/studio/backend/core/inference/diffusion_families.py b/studio/backend/core/inference/diffusion_families.py
index e4d0ad5f106..8b0873b17fd 100644
--- a/studio/backend/core/inference/diffusion_families.py
+++ b/studio/backend/core/inference/diffusion_families.py
@@ -1823,6 +1823,40 @@ def retired_full_copy_base(repo_id: Optional[str]) -> Optional[str]:
return base
+def retired_copy_loads_from_disk(source: Optional[str], *, companion: bool = False) -> bool:
+ """Whether a retired full copy complete on disk (snapshot path, or id with a ``refs/main`` snapshot) loads as itself.
+
+ Its files are the base's own, and the base's mirror may not be cached (offline) or would download again (online).
+ A ``companion`` base serves a single file that supplies the transformer, so that folder needs only its config.
+ PURE: local stat only."""
+ key = (source or "").strip()
+ if not key or retired_full_copy_base(key) is None and not _is_local_path(key):
+ return False
+ try:
+ if _is_local_path(key):
+ root: Optional[Path] = Path(key).expanduser()
+ else:
+ from utils.hf_cache_settings import active_hf_hub_cache
+
+ copy_id = next(c for c in _RETIRED_FULL_COPIES if c == key.lower())
+ # A load by id resolves refs/main (offline too): a commit-pinned snapshot with no main ref is not found.
+ repo = Path(active_hf_hub_cache()) / f"models--{copy_id.replace('/', '--')}"
+ commit = (repo / "refs" / "main").read_text(encoding = "utf-8").strip()
+ root = repo / "snapshots" / commit if commit else None
+ if root is None or not root.is_dir():
+ return False
+ from .diffusion_flux3 import FLUX3_COMPONENT_FOLDERS, FLUX3_INDEX
+
+ return local_pipeline_components_are_complete(
+ root,
+ FLUX3_INDEX,
+ excluded_components = ("transformer",) if companion else (),
+ fixed_component_folders = FLUX3_COMPONENT_FOLDERS,
+ )
+ except (OSError, StopIteration):
+ return False
+
+
# Repo id (lowercased) -> the commit a load's plan pinned it to, for the duration of that load's assembly. Set only by
# ``pinned_repo_revision`` around a video load; every hub-id CONFIG read of a base repo (encoder / VAE / transformer
# configs, model_index, the LTX-2.5 companions) asks ``pinned_revision_kwargs`` so it reads the planned commit. Empty
diff --git a/studio/backend/core/inference/media_auto_switch.py b/studio/backend/core/inference/media_auto_switch.py
index d68ad67f632..8fec4b458fb 100644
--- a/studio/backend/core/inference/media_auto_switch.py
+++ b/studio/backend/core/inference/media_auto_switch.py
@@ -141,8 +141,12 @@ def _resolve_pick(owner: str, name: str, task: str) -> Optional[MediaModelPick]:
def _retired_copy_as_base(pick: MediaModelPick) -> MediaModelPick:
"""A downloaded retired FLUX.3 full copy as the load will read it: the pick of the base it copies, which
``DiffusionLoadRequest`` redirects it to. So locality is proven for the files that load fetches (the -FP8 mirror's),
- not the copy's snapshot, and the resident match compares the id the status publishes."""
- from core.inference.diffusion_families import retired_full_copy_base
+ not the copy's snapshot, and the resident match compares the id the status publishes. A copy complete on disk stays
+ itself, as the load route keeps it (``retired_copy_loads_from_disk``)."""
+ from core.inference.diffusion_families import (
+ retired_copy_loads_from_disk,
+ retired_full_copy_base,
+ )
base = retired_full_copy_base(pick.model_id)
if base is None:
@@ -150,6 +154,8 @@ def _retired_copy_as_base(pick: MediaModelPick) -> MediaModelPick:
single = (pick.gguf_filename or "").replace("\\", "/")
if single and single != "model.safetensors":
return pick
+ if retired_copy_loads_from_disk(pick.model_path):
+ return pick
return MediaModelPick(base, base, None, "pipeline")
@@ -267,6 +273,7 @@ async def _start_load(
"""Run the load its own route would run, as an API load rather than a user one."""
partition = expected_partition(pick)
if owner == DIFFUSION:
+ from core.inference.diffusion_families import retired_copy_loads_from_disk
from core.inference.media_locality import flux3_seeded_cache_repo, seeded_family_override
from models.inference import DiffusionLoadRequest
from routes.inference import load_diffusion_model_gated
@@ -276,6 +283,9 @@ async def _start_load(
model_path = pick.model_path
family_override = None
seeded_repo = None if pick.gguf_filename else flux3_seeded_cache_repo(pick.model_path)
+ # By id only the active cache is searched: a complete retired copy in an earlier Models folder keeps its path.
+ if seeded_repo and retired_copy_loads_from_disk(pick.model_path):
+ seeded_repo = None
if seeded_repo:
model_path = seeded_repo
# The listing named the family from the snapshot's modular_model_index.json; an opaquely named repo id
diff --git a/studio/backend/models/inference.py b/studio/backend/models/inference.py
index 25b796ca898..f85d4a55ced 100644
--- a/studio/backend/models/inference.py
+++ b/studio/backend/models/inference.py
@@ -4927,17 +4927,18 @@ class DiffusionLoadRequest(BaseModel):
# id), loads the base it copies, exactly as the picker's own row does, so the load fetches what the plan prices
# (hosted encoder, mirror folders) instead of the whole bf16 repo. Its root bf16 ``model.safetensors`` is that
# base's transformer, so a single-file pick of it is the pipeline load; supplied encoder / VAE files or another
- # companion base make it a different build, which stays on the copy.
- from core.inference.diffusion_families import retired_full_copy_base
+ # companion base make it a different build, which stays on the copy. A copy complete on disk loads from disk.
+ from core.inference.diffusion_families import (
+ retired_copy_loads_from_disk,
+ retired_full_copy_base,
+ )
base = retired_full_copy_base(self.model_path) or retired_full_copy_base(
self.display_repo_id
)
if base is not None:
single = (self.gguf_filename or "").strip().replace("\\", "/")
- if not single:
- self.model_path, self.display_repo_id = base, None
- elif (
+ root_pick = (
single == "model.safetensors"
and self.text_encoder_file is None
and self.vae_file is None
@@ -4946,10 +4947,18 @@ class DiffusionLoadRequest(BaseModel):
not (self.base_repo or "").strip()
or (retired_full_copy_base(self.base_repo) or self.base_repo) == base
)
- ):
+ )
+ if (not single or root_pick) and retired_copy_loads_from_disk(self.model_path):
+ # As a pipeline: a cached snapshot's root file links into blobs/, which single-file validation refuses.
+ if root_pick:
+ self.gguf_filename, self.model_kind = None, "pipeline"
+ elif not single or root_pick:
self.model_path, self.display_repo_id = base, None
self.gguf_filename, self.model_kind = None, "pipeline"
- if retired_full_copy_base(self.base_repo) is not None:
+ # A companion base serving a single file only needs the transformer config; a pipeline opens its weights.
+ if retired_full_copy_base(self.base_repo) is not None and not retired_copy_loads_from_disk(
+ self.base_repo, companion = bool((self.gguf_filename or "").strip())
+ ):
self.base_repo = retired_full_copy_base(self.base_repo)
return self
diff --git a/studio/backend/tests/test_flux3_retired_copy_on_disk.py b/studio/backend/tests/test_flux3_retired_copy_on_disk.py
new file mode 100644
index 00000000000..714fc7e5f73
--- /dev/null
+++ b/studio/backend/tests/test_flux3_retired_copy_on_disk.py
@@ -0,0 +1,240 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""A retired FLUX.3 full copy that is already complete on disk keeps loading from disk. The copies were retired for
+size and hold the base's own files, so redirecting one to its base would need the base's -FP8 mirror: offline that is
+a LocalEntryNotFoundError for a model the install already holds, online the same weights downloaded again. An
+incomplete copy still loads through the base."""
+
+import json
+from unittest.mock import patch
+
+import pytest
+
+from core.inference import diffusion_families as df
+from core.inference import diffusion_flux3 as flux3
+from models.inference import DiffusionLoadRequest
+
+_COPY = "unsloth/flux-3-image-klein"
+_BASE = "black-forest-labs/flux-3-image-klein"
+
+
+def _write(path, data = b"x"):
+ path.parent.mkdir(parents = True, exist_ok = True)
+ path.write_bytes(data)
+
+
+def _flux3_pipeline(root, *, complete = True):
+ """A FLUX.3 Modular Diffusers layout with every folder the loader reads (tiny placeholder weights)."""
+ _write(root / flux3.FLUX3_INDEX, json.dumps({"_class_name": "Flux3ModularPipeline"}).encode())
+ _write(root / "model.safetensors")
+ _write(root / "text_encoder" / "config.json", b"{}")
+ _write(root / "text_encoder" / "model.safetensors")
+ _write(root / "text_encoder" / "processor_config.json", b"{}")
+ _write(root / "text_encoder" / "tokenizer.json", b"{}")
+ for folder in ("transformer", "vae"):
+ _write(root / folder / "config.json", b"{}")
+ if complete or folder == "vae":
+ _write(root / folder / "diffusion_pytorch_model.safetensors")
+ return root
+
+
+def _snapshot(
+ tmp_path,
+ repo = _COPY,
+ *,
+ complete = True,
+):
+ root = tmp_path / "hub" / f"models--{repo.replace('/', '--')}"
+ snapshot = _flux3_pipeline(root / "snapshots" / "0123abc", complete = complete)
+ _write(root / "refs" / "main", b"0123abc")
+ return snapshot
+
+
+def offline_hub(tmp_path, monkeypatch):
+ """HF offline mode with a live hub cache under tmp_path; any Hub lookup is a cache miss."""
+ monkeypatch.setenv("HF_HUB_OFFLINE", "1")
+ monkeypatch.setattr(
+ "utils.hf_cache_settings.active_hf_hub_cache", lambda: str(tmp_path / "hub")
+ )
+ return tmp_path / "hub"
+
+
+def _load_reads_local_index(request):
+ """What the FLUX.3 loader does first with the request: resolve the fetch repo, then read its manifest (cache only)."""
+ from huggingface_hub.errors import LocalEntryNotFoundError
+
+ fetched = df.prefer_ungated_mirror(request.model_path)
+ with patch(
+ "huggingface_hub.hf_hub_download",
+ side_effect = LocalEntryNotFoundError("not in the offline cache"),
+ ) as hub:
+ try:
+ index = flux3._read_index(fetched, None, True)
+ except LocalEntryNotFoundError:
+ index = None
+ return index, hub.call_count
+
+
[email protected]("display", [_COPY, None])
+def test_a_complete_downloaded_copy_loads_offline_from_its_snapshot(tmp_path, offline_hub, display):
+ snapshot = str(_snapshot(tmp_path))
+ request = DiffusionLoadRequest(model_path = snapshot, display_repo_id = display)
+ assert (request.model_path, request.display_repo_id) == (snapshot, display)
+ index, hub_lookups = _load_reads_local_index(request)
+ assert index == {"_class_name": "Flux3ModularPipeline"} and hub_lookups == 0
+
+
+def test_an_explicit_base_on_the_root_transformer_pick_is_kept(tmp_path, offline_hub):
+ snapshot = str(_snapshot(tmp_path))
+ request = DiffusionLoadRequest(
+ model_path = snapshot,
+ gguf_filename = "model.safetensors",
+ model_kind = "single_file",
+ base_repo = _BASE,
+ )
+ assert request.base_repo == _BASE
+
+
+def test_the_copy_named_by_id_loads_from_a_complete_cached_snapshot(tmp_path, offline_hub):
+ _snapshot(tmp_path)
+ request = DiffusionLoadRequest(model_path = _COPY, model_kind = "pipeline", base_repo = _COPY)
+ assert (request.model_path, request.base_repo) == (_COPY, _COPY)
+
+
+def test_an_incomplete_copy_still_loads_through_its_base(tmp_path, offline_hub):
+ snapshot = str(_snapshot(tmp_path, complete = False))
+ request = DiffusionLoadRequest(model_path = snapshot, display_repo_id = _COPY)
+ assert (request.model_path, request.display_repo_id) == (_BASE, None)
+ # Named by id, with only that partial snapshot cached.
+ assert DiffusionLoadRequest(model_path = _COPY).model_path == _BASE
+
+
+def test_a_copy_not_on_disk_loads_through_its_base(offline_hub):
+ assert DiffusionLoadRequest(model_path = _COPY).model_path == _BASE
+ assert (
+ DiffusionLoadRequest(
+ model_path = "/no/such/hub/models--unsloth--flux-3-image-klein/snapshots/abc"
+ ).model_path
+ == _BASE
+ )
+
+
+def test_the_copy_named_by_id_needs_its_main_ref(tmp_path, offline_hub):
+ """A load by id resolves refs/main, so a lone commit-pinned snapshot with no main ref cannot serve it offline."""
+ snapshot = _snapshot(tmp_path)
+ (snapshot.parent.parent / "refs" / "main").unlink()
+ assert not df.retired_copy_loads_from_disk(_COPY)
+ assert DiffusionLoadRequest(model_path = _COPY).model_path == _BASE
+ # Its path still loads from disk: a snapshot path needs no ref.
+ assert df.retired_copy_loads_from_disk(str(snapshot))
+
+
[email protected]("by_id", [False, True])
+def test_its_root_transformer_pick_loads_the_copy_as_its_pipeline(tmp_path, offline_hub, by_id):
+ """The root model.safetensors is the copy's own transformer, so the pick loads the copy's pipeline from disk."""
+ snapshot = str(_snapshot(tmp_path))
+ source = _COPY if by_id else snapshot
+ request = DiffusionLoadRequest(
+ model_path = source,
+ display_repo_id = None if by_id else _COPY,
+ gguf_filename = "model.safetensors",
+ model_kind = "single_file",
+ )
+ assert (request.model_path, request.gguf_filename, request.model_kind) == (
+ source,
+ None,
+ "pipeline",
+ )
+ if not by_id:
+ index, lookups = _load_reads_local_index(request)
+ assert index == {"_class_name": "Flux3ModularPipeline"} and lookups == 0
+
+
+def _hf_cache_snapshot(tmp_path):
+ """A complete copy as huggingface_hub stores it: every snapshot file a symlink into blobs/."""
+ import os
+
+ snapshot = _snapshot(tmp_path)
+ blobs = snapshot.parent.parent / "blobs"
+ blobs.mkdir()
+ for i, path in enumerate(sorted(p for p in snapshot.rglob("*") if p.is_file())):
+ blob = blobs / f"blob{i}"
+ path.replace(blob)
+ path.symlink_to(os.path.relpath(blob, path.parent))
+ return snapshot
+
+
[email protected]("pick", ["pipeline", "root"])
+def test_a_snapshot_in_the_hf_cache_layout_passes_the_route_validator(tmp_path, offline_hub, pick):
+ """The root file of a cached snapshot resolves into blobs/, outside the snapshot, which a single-file pick of that
+ path refuses ("gguf_filename must resolve to a file inside the repo"); as the pipeline load it validates."""
+ from core.inference.diffusion import DiffusionBackend
+
+ snapshot = str(_hf_cache_snapshot(tmp_path))
+ single = (
+ {"gguf_filename": "model.safetensors", "model_kind": "single_file"}
+ if pick == "root"
+ else {}
+ )
+ request = DiffusionLoadRequest(model_path = snapshot, display_repo_id = _COPY, **single)
+ assert request.model_path == snapshot
+ DiffusionBackend.__new__(DiffusionBackend).validate_load_request(
+ request.model_path,
+ gguf_filename = request.gguf_filename,
+ model_kind = request.model_kind,
+ base_repo = request.base_repo,
+ family_override = "flux.3-klein",
+ )
+
+
+def test_a_root_transformer_pick_missing_its_file_loads_the_copys_pipeline(tmp_path, offline_hub):
+ snapshot = _snapshot(tmp_path)
+ (snapshot / "model.safetensors").unlink()
+ request = DiffusionLoadRequest(
+ model_path = str(snapshot), gguf_filename = "model.safetensors", model_kind = "single_file"
+ )
+ assert (request.model_path, request.gguf_filename, request.model_kind) == (
+ str(snapshot),
+ None,
+ "pipeline",
+ )
+
+
+def test_a_copy_without_transformer_weights(tmp_path, offline_hub):
+ """Its pipeline (and the root pick, loaded as that pipeline) goes through the base; as the companion base of
+ another single file, which supplies the transformer, only the config is read, so it stays."""
+ snapshot = str(_snapshot(tmp_path, complete = False))
+ root = DiffusionLoadRequest(
+ model_path = snapshot, gguf_filename = "model.safetensors", model_kind = "single_file"
+ )
+ assert (root.model_path, root.gguf_filename, root.model_kind) == (_BASE, None, "pipeline")
+ gguf = DiffusionLoadRequest(
+ model_path = "/models/klein.gguf", gguf_filename = "klein.gguf", base_repo = snapshot
+ )
+ assert gguf.base_repo == snapshot
+ # A pipeline redirected to the base cannot use it as its base either: the pipeline opens the transformer weights.
+ pipeline = DiffusionLoadRequest(model_path = snapshot, base_repo = snapshot, model_kind = "pipeline")
+ assert (pipeline.model_path, pipeline.base_repo) == (_BASE, _BASE)
+
+
+def test_the_auto_switch_loads_a_copy_in_an_earlier_models_folder_from_its_snapshot(
+ tmp_path, offline_hub
+):
+ """The seeded-snapshot rewrite would load it by id, which searches only the active cache, so the copy kept in an
+ earlier Models folder would be redirected to its base."""
+ import asyncio
+
+ from core.inference import media_auto_switch as mas
+
+ snapshot = _snapshot(tmp_path / "earlier")
+ pick = mas.MediaModelPick(_COPY, str(snapshot), None, "pipeline")
+ sent = []
+
+ async def _gated(request, *_args, **_kwargs):
+ sent.append(request)
+
+ with patch("routes.inference.load_diffusion_model_gated", _gated):
+ asyncio.run(mas._start_load(mas.DIFFUSION, pick, "subject"))
+ assert [(r.model_path, r.gguf_filename) for r in sent] == [(str(snapshot), None)]
diff --git a/studio/backend/tests/test_media_auto_switch.py b/studio/backend/tests/test_media_auto_switch.py
index d52864c875d..125982e9a4c 100644
--- a/studio/backend/tests/test_media_auto_switch.py
+++ b/studio/backend/tests/test_media_auto_switch.py
@@ -2602,6 +2602,40 @@ def test_a_downloaded_retired_flux3_copy_switches_to_the_base_it_copies(
assert len(loads) == 1
+def test_a_complete_downloaded_retired_flux3_copy_switches_to_itself(
+ catalog, enabled, backend, loads, tmp_path
+):
+ # A copy complete on disk loads from disk (the load route keeps it too): its base's mirror may not be cached, and
+ # offline it could not be fetched, so the switch neither plans nor waits for it.
+ snapshot = tmp_path / "models--unsloth--flux-3-image-klein" / "snapshots" / "abc"
+ for name, data in {
+ "modular_model_index.json": '{"_class_name": "Flux3ModularPipeline"}',
+ "text_encoder/config.json": "{}",
+ "text_encoder/model.safetensors": "x",
+ "text_encoder/processor_config.json": "{}",
+ "text_encoder/tokenizer.json": "{}",
+ "transformer/config.json": "{}",
+ "transformer/diffusion_pytorch_model.safetensors": "x",
+ "vae/config.json": "{}",
+ "vae/diffusion_pytorch_model.safetensors": "x",
+ }.items():
+ (snapshot / name).parent.mkdir(parents = True, exist_ok = True)
+ (snapshot / name).write_text(data)
+ catalog.append(_info("unsloth/flux-3-image-klein", snapshot, task = mas.IMAGE_TASK))
+ planned: list = []
+
+ def _plan(model_path, **kwargs):
+ planned.append(model_path)
+ return {"total_bytes": 5_000}
+
+ backend.download_plan = _plan
+ _switch("unsloth/flux-3-image-klein")
+ assert [(p.model_id, p.model_path) for _owner, p in loads] == [
+ ("unsloth/flux-3-image-klein", str(snapshot))
+ ]
+ assert "black-forest-labs/flux-3-image-klein" not in planned
+
+
def test_a_retired_flux3_copy_name_reloads_the_mirror_that_replaced_it(
catalog, enabled, backend, loads, tmp_path
):
diff --git a/studio/frontend/src/features/images/image-model-recall.ts b/studio/frontend/src/features/images/image-model-recall.ts
index 83deebef10e..fec2297f956 100644
--- a/studio/frontend/src/features/images/image-model-recall.ts
+++ b/studio/frontend/src/features/images/image-model-recall.ts
@@ -32,6 +32,34 @@ function retiredSnapshotRepo(path: string): string {
return match ? `unsloth/${match[1].toLowerCase()}` : "";
}
+/** A retired copy pick (its id or a snapshot): the backend loads it from disk when complete, else through its base. */
+export function isRetiredCopySnapshot(pick: { repoId: string; displayRepoId?: string }): boolean {
+ return Boolean(retiredCopyOf(pick));
+}
+
+function retiredCopyOf(pick: { repoId: string; displayRepoId?: string }): string {
+ const id = pick.repoId.trim().toLowerCase();
+ const display = (pick.displayRepoId ?? "").trim().toLowerCase();
+ if (RETIRED_FULL_COPIES[id]) return id;
+ return RETIRED_FULL_COPIES[display] ? display : retiredSnapshotRepo(pick.repoId);
+}
+
+/** A retired snapshot that loaded through its base, as that base (else the pick), so Reapply and recall match the status. */
+export function retiredSnapshotAsLoaded<T extends RememberedImageModel & { displayRepoId?: string; baseRepo?: string }>(
+ pick: T,
+ status: Parameters<typeof matchesRememberedModel>[1],
+): T {
+ if (!isRetiredCopySnapshot(pick) || matchesRememberedModel(pick, status)) return pick;
+ // A complete snapshot's root model.safetensors pick loads as the snapshot's own pipeline.
+ const { filename: _filename, baseRepo: _base, ...asPipeline } = { ...pick, kind: "pipeline" as const };
+ if (matchesRememberedModel(asPipeline as T, status)) return asPipeline as T;
+ const copy = retiredCopyOf(pick);
+ // A redirect loads another checkpoint, whose base the backend infers (handleLoad drops it the same way).
+ const { baseRepo: _baseRepo, ...rest } = pick;
+ const asBase = redirectRetiredImagePick({ ...rest, repoId: copy } as T);
+ return asBase.repoId !== copy && matchesRememberedModel(asBase, status) ? asBase : pick;
+}
+
export function redirectRetiredImagePick<
T extends {
repoId: string;
@@ -42,12 +70,7 @@ export function redirectRetiredImagePick<
vaeFile?: string;
},
>(pick: T): T {
- // A downloaded copy arrives as its snapshot path with the retired id as the display id; a model remembered by an
- // older build is that snapshot path alone.
- const base =
- RETIRED_FULL_COPIES[pick.repoId.trim().toLowerCase()] ??
- RETIRED_FULL_COPIES[(pick.displayRepoId ?? "").trim().toLowerCase()] ??
- RETIRED_FULL_COPIES[retiredSnapshotRepo(pick.repoId)];
+ const base = RETIRED_FULL_COPIES[pick.repoId.trim().toLowerCase()];
if (!base) return pick;
const { displayRepoId: _display, ...rest } = pick;
if (pick.kind === "pipeline") return { ...rest, repoId: base } as T;
@@ -77,7 +100,7 @@ export function readImageModel(): RememberedImageModel | null {
(f: unknown): f is string => typeof f === "string" && f.length > 0,
)
: [];
- return redirectRetiredImagePick({
+ return {
repoId: value.repoId,
kind: value.kind,
...(typeof value.filename === "string"
@@ -88,7 +111,7 @@ export function readImageModel(): RememberedImageModel | null {
...(typeof value.vaeFile === "string" && value.vaeFile
? { vaeFile: value.vaeFile }
: {}),
- } as RememberedImageModel);
+ } as RememberedImageModel;
} catch {
return null;
}
@@ -401,9 +424,11 @@ export function finishedLoadTarget<T extends ImageModelKey & { fieldFiles?: Imag
current: T | null,
status: Parameters<typeof matchesRememberedModel>[1] & Parameters<typeof forgetStaleImageComponents>[1],
): T | PendingImageLoad | null {
- const pending = readPendingImageLoad();
+ const stored = readPendingImageLoad();
clearPendingImageLoad();
if (current?.fieldFiles) return current;
+ // A retired snapshot is published as what it loaded as (its base, or its own pipeline for a root pick).
+ const pending = stored ? retiredSnapshotAsLoaded(stored, status) : stored;
if (
pending &&
matchesRememberedModel(pending, status) &&
diff --git a/studio/frontend/src/features/images/images-page.tsx b/studio/frontend/src/features/images/images-page.tsx
index be5b8db762c..d455005f175 100644
--- a/studio/frontend/src/features/images/images-page.tsx
+++ b/studio/frontend/src/features/images/images-page.tsx
@@ -2,7 +2,7 @@
// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
import { generationFailureLogsAction } from "@/features/settings/lib/view-logs-action";
-import { readImageModel, redirectRetiredImagePick, rememberImageModel, matchesRememberedModel, componentFilesMatch, componentFieldsOwnerAfterLoad, componentFilesForModel, forgetStaleImageComponents, forgetStaleResidentComponents, recalledComponentFiles, reconcileRememberedComponents, rememberLoadedImageComponents, recoveredComponentFields, seedImageComponents, rememberPendingImageLoad, clearPendingImageLoad, finishedLoadTarget, type ImageComponentFiles, type ImageModelKey, type RememberedImageModel } from "./image-model-recall";
+import { isRetiredCopySnapshot, readImageModel, retiredSnapshotAsLoaded, rememberImageModel, matchesRememberedModel, componentFilesMatch, componentFieldsOwnerAfterLoad, componentFilesForModel, forgetStaleImageComponents, forgetStaleResidentComponents, recalledComponentFiles, reconcileRememberedComponents, rememberLoadedImageComponents, recoveredComponentFields, seedImageComponents, rememberPendingImageLoad, clearPendingImageLoad, finishedLoadTarget, type ImageComponentFiles, type ImageModelKey, type RememberedImageModel } from "./image-model-recall";
import { componentFileFields, splitComponentFileList } from "./component-files";
import type { CompareContext } from "./compare/compare-axes";
import type { CompareRun } from "./compare/compare-run";
@@ -3498,8 +3498,10 @@ export function ImagesPage({
pendingEvicted.current = [];
toast.success("Model loaded", evictedToastOptions(evicted));
const started = lastLoad.current;
- lastLoad.current = finishedLoadTarget(started, loaded);
- if (lastLoad.current) rememberFinishedLoad(lastLoad.current, loaded, lastLoad.current !== started);
+ const finished = finishedLoadTarget(started, loaded);
+ // An incomplete retired-copy snapshot loaded as the base it copies: Reapply and the recall name that base now.
+ lastLoad.current = finished ? retiredSnapshotAsLoaded(finished, loaded) : finished;
+ if (lastLoad.current) rememberFinishedLoad(lastLoad.current, loaded, finished !== started);
setBusy(null);
// A fallback-recipe pick takes the loaded family recipe on an untouched form (else SDXL runs 9 steps, CFG 0).
const loadedRecipe = loadedRecipeFor(
@@ -3936,18 +3938,7 @@ export function ImagesPage({
bakedLorasOnLoad.current = bakeLoras.length > 0;
const componentFiles = componentFileFields(opts.kind, advanced.text_encoder_file, advanced.vae_file);
const fieldFiles = componentFileFields(opts.kind, picked.text_encoder_file, picked.vae_file);
- // A retired FLUX.3 full copy (named, or a downloaded snapshot of one) loads the base it copies, as the backend
- // redirects it, so the load, Reapply and the remembered model all name the id the status will report.
- const redirected = redirectRetiredImagePick({
- repoId,
- ...opts,
- textEncoderFiles: componentFiles.text_encoder_file,
- vaeFile: componentFiles.vae_file,
- });
- // A redirect loads another checkpoint, whose base the backend infers.
- const baseRepo = redirected.repoId === repoId ? opts.baseRepo : undefined;
- repoId = redirected.repoId;
- opts = { kind: redirected.kind, filename: redirected.filename, displayRepoId: redirected.displayRepoId, baseRepo };
+ opts = { kind: opts.kind, filename: opts.filename, displayRepoId: opts.displayRepoId, baseRepo: opts.baseRepo };
lastLoad.current = {
repoId,
kind: opts.kind,
@@ -4284,6 +4275,7 @@ export function ImagesPage({
repoId: string,
opts: ImageLoadOptions,
picked: LoadAdvanced,
+ displayRepoId?: string,
) => {
// Normalised exactly as handleLoad does, so the plan describes the load that will run.
const advanced = nativeLoadAdvanced(
@@ -4294,6 +4286,8 @@ export function ImagesPage({
);
return getDiffusionDownloadPlan({
model_path: repoId,
+ // A retired copy's snapshot plans as its path: the display id lets the plan redirect it as the load will.
+ ...(displayRepoId ? { display_repo_id: displayRepoId } : {}),
gguf_filename: opts.filename,
base_repo: opts.baseRepo,
model_kind: opts.kind,
@@ -4373,22 +4367,9 @@ export function ImagesPage({
: a;
// ONE snapshot for the plan and the load it fires: the download runs for minutes without setting `busy`.
let advanced = downloadSnapshot ?? withPicked(currentLoadAdvanced(repoId, familyOverrideRequired));
- // A retired FLUX.3 full copy is planned, staged and loaded as the base it copies, so the staged
- // checkpoint is the one the load opens (the backend redirects the same picks).
- const component = componentFileFields(opts.kind, advanced.text_encoder_file, advanced.vae_file);
- const redirected = redirectRetiredImagePick({
- repoId,
- ...opts,
- textEncoderFiles: component.text_encoder_file,
- vaeFile: component.vae_file,
- });
- if (redirected.repoId !== repoId) {
- repoId = redirected.repoId;
- opts = { kind: redirected.kind, filename: redirected.filename, displayRepoId: redirected.displayRepoId };
- advanced = downloadSnapshot ?? withPicked(currentLoadAdvanced(repoId, familyOverrideRequired));
- // A local snapshot of the copy is now a Hub load of the base: plan and stage it like one.
- source = "hub";
- }
+ // Only the backend knows if a retired FLUX.3 copy is complete: plan it so an incomplete one stages its base.
+ const retiredSnapshot = isRetiredCopySnapshot({ repoId, displayRepoId: opts.displayRepoId });
+ if (retiredSnapshot) source = "hub";
// The retry's override rides the same snapshot, so its plan and its load both carry it.
if (oversizedRetry) advanced = { ...advanced, allow_oversized_load: true };
// Resolve the engine into the snapshot, so the plan and the load it fires cannot read different selects.
@@ -4409,7 +4390,9 @@ export function ImagesPage({
let incompatible: string | null = null;
let incompatibleCode: string | null = null;
try {
- const plan = await requestDownloadPlan(opts.displayRepoId ?? repoId, opts, advanced);
+ const plan = retiredSnapshot
+ ? await requestDownloadPlan(repoId, opts, advanced, opts.displayRepoId)
+ : await requestDownloadPlan(opts.displayRepoId ?? repoId, opts, advanced);
// Only load intents are superseded; accepted downloads keep their own plans.
if (!downloadOnly && (pick !== pickSeq.current || !owns())) {
pickToast.dismiss(pickToastId);
@@ -4431,7 +4414,10 @@ export function ImagesPage({
};
stagedQuantRevert.current = ownRevert;
}
- const entries = diffusionStagingEntries(plan.entries, repoId, opts);
+ // Every entry of a retired snapshot's plan is to fetch: the snapshot's own files are not in it.
+ const entries = retiredSnapshot
+ ? diffusionStagingEntries(plan.entries, repoId, { filename: opts.filename })
+ : diffusionStagingEntries(plan.entries, repoId, opts);
if (entries.length === 0) {
pickToast.dismiss(pickToastId);
if (downloadOnly) return true;
diff --git a/studio/frontend/tests/image-engine-choice.test.ts b/studio/frontend/tests/image-engine-choice.test.ts
index 257e094329c..7c5b93cdac6 100644
--- a/studio/frontend/tests/image-engine-choice.test.ts
+++ b/studio/frontend/tests/image-engine-choice.test.ts
@@ -346,7 +346,7 @@ test("a reload from status keeps the resident GGUF's base repo, on the load and
const source = readSrc("features/images/images-page.tsx");
assert.equal(source.match(/base_repo: opts\.baseRepo,/g)?.length, 2);
assert.equal(source.match(/displayRepoId: l\.displayRepoId, baseRepo: l\.baseRepo \}/g)?.length, 2);
- // Carried into the next Reapply target, dropped by a retired-copy redirect.
- assert.match(source, /const baseRepo = redirected\.repoId === repoId \? opts\.baseRepo : undefined;/);
+ // Carried into the next Reapply target.
+ assert.match(source, /opts = \{ kind: opts\.kind, filename: opts\.filename, displayRepoId: opts\.displayRepoId, baseRepo: opts\.baseRepo \};/);
assert.match(source, /displayRepoId: opts\.displayRepoId,\s*baseRepo: opts\.baseRepo,/);
});
diff --git a/studio/frontend/tests/image-load-resume.test.ts b/studio/frontend/tests/image-load-resume.test.ts
index 240476804ba..d6808644c59 100644
--- a/studio/frontend/tests/image-load-resume.test.ts
+++ b/studio/frontend/tests/image-load-resume.test.ts
@@ -69,7 +69,7 @@ test("a load resumed after a page reload records the paths it was started with",
test("the page stores the pending load at start and clears it on every way a load ends", () => {
const source = readSrc("features/images/images-page.tsx");
assert.match(source, /lastLoad\.current = \{[\s\S]*?fieldFiles: \{[^}]*\},\s*\};[\s\S]{0,200}rememberPendingImageLoad\(lastLoad\.current\);/);
- assert.match(source, /const started = lastLoad\.current;\s*lastLoad\.current = finishedLoadTarget\(started, loaded\);\s*if \(lastLoad\.current\) rememberFinishedLoad\(lastLoad\.current, loaded, lastLoad\.current !== started\);/);
+ assert.match(source, /const started = lastLoad\.current;\s*const finished = finishedLoadTarget\(started, loaded\);[\s\S]{0,200}lastLoad\.current = finished \? retiredSnapshotAsLoaded\(finished, loaded\) : finished;\s*if \(lastLoad\.current\) rememberFinishedLoad\(lastLoad\.current, loaded, finished !== started\);/);
assert.match(source, /if \(p\.phase === "error"\) \{\s*clearPendingImageLoad\(\);/);
assert.match(source, /if \(p\.phase === null\) \{\s*clearPendingImageLoad\(\);/);
assert.match(source, /\} catch \(err\) \{\s*pendingEvicted\.current = \[\];\s*clearPendingImageLoad\(\);/);
@@ -149,3 +149,16 @@ test("a pending load whose files the resident build does not use keeps the saved
rememberPendingImageLoad({ ...zImage, fieldFiles: other });
assert.deepEqual(finishedLoadTarget(null, native)?.fieldFiles, other);
});
+
+test("a retired snapshot's load resumed after a page reload is recovered as what it loaded as", () => {
+ store.clear();
+ const snapshot = "/hf/hub/models--unsloth--flux-3-image-klein/snapshots/abc";
+ const asPipeline = { loaded: true, repo_id: snapshot, model_kind: "pipeline" };
+ rememberPendingImageLoad({ repoId: snapshot, kind: "single_file", filename: "model.safetensors", baseRepo: snapshot });
+ const root = finishedLoadTarget(null, asPipeline);
+ assert.deepEqual([root?.repoId, root?.kind, root?.filename], [snapshot, "pipeline", undefined]);
+ const asBase = { loaded: true, repo_id: "black-forest-labs/flux-3-image-klein", model_kind: "pipeline" };
+ rememberPendingImageLoad({ repoId: snapshot, kind: "pipeline", displayRepoId: "unsloth/flux-3-image-klein" });
+ const redirected = finishedLoadTarget(null, asBase);
+ assert.deepEqual([redirected?.repoId, redirected?.kind], ["black-forest-labs/flux-3-image-klein", "pipeline"]);
+});
diff --git a/studio/frontend/tests/image-retired-full-copies.test.ts b/studio/frontend/tests/image-retired-full-copies.test.ts
index 645b0375f94..1ef6be81ac4 100644
--- a/studio/frontend/tests/image-retired-full-copies.test.ts
+++ b/studio/frontend/tests/image-retired-full-copies.test.ts
@@ -4,12 +4,14 @@
import assert from "node:assert/strict";
import test from "node:test";
import {
+ isRetiredCopySnapshot,
matchesRememberedModel,
readImageModel,
redirectRetiredImagePick,
rememberImageModel,
+ retiredSnapshotAsLoaded,
} from "../src/features/images/image-model-recall.ts";
-import { installLocalStorageFake } from "./helpers/kit.ts";
+import { installLocalStorageFake, readSrc } from "./helpers/kit.ts";
installLocalStorageFake();
@@ -47,40 +49,105 @@ test("its root bf16 transformer is the pipeline load; other picks stay as named"
assert.equal(redirectRetiredImagePick(other), other);
});
-test("a downloaded snapshot of a retired copy is redirected by its display id", () => {
- assert.deepEqual(
- redirectRetiredImagePick({
- repoId: "/hf/hub/models--unsloth--flux-3-image-klein-base/snapshots/abc",
- kind: "pipeline" as const,
- displayRepoId: "unsloth/flux-3-image-klein-base",
- }),
- { repoId: "black-forest-labs/flux-3-image-klein-base", kind: "pipeline" },
- );
+test("a downloaded snapshot of a retired copy loads from disk, not through its base", () => {
+ // The copy holds the base's own files; redirecting it would need the base's mirror, which may not be cached
+ // (offline it cannot load at all). The backend keeps a complete snapshot the same way.
+ const downloaded = {
+ repoId: "/hf/hub/models--unsloth--flux-3-image-klein-base/snapshots/abc",
+ kind: "pipeline" as const,
+ displayRepoId: "unsloth/flux-3-image-klein-base",
+ };
+ assert.equal(redirectRetiredImagePick(downloaded), downloaded);
+ const rootTransformer = {
+ repoId: "/hf/hub/models--unsloth--flux-3-image-klein/snapshots/abc",
+ kind: "single_file" as const,
+ filename: "model.safetensors",
+ displayRepoId: "unsloth/flux-3-image-klein",
+ };
+ assert.equal(redirectRetiredImagePick(rootTransformer), rootTransformer);
});
-test("a remembered retired copy is recalled as its base, so it matches the status the load reports", () => {
+test("a remembered retired copy is recalled as itself: the backend decides whether it loads from disk", () => {
rememberImageModel({ repoId: "unsloth/flux-3-image-klein", kind: "pipeline" });
const recalled = readImageModel();
- assert.deepEqual(recalled, { repoId: "black-forest-labs/flux-3-image-klein", kind: "pipeline" });
- assert.equal(
- matchesRememberedModel(recalled!, {
- loaded: true,
- repo_id: "black-forest-labs/flux-3-image-klein",
- model_kind: "pipeline",
- }),
- true,
- );
+ assert.deepEqual(recalled, { repoId: "unsloth/flux-3-image-klein", kind: "pipeline" });
+ // Loaded through the base (not complete on disk), the finished load is remembered as that base.
+ const base = { loaded: true, repo_id: "black-forest-labs/flux-3-image-klein", model_kind: "pipeline" };
+ assert.deepEqual(retiredSnapshotAsLoaded(recalled!, base), { repoId: "black-forest-labs/flux-3-image-klein", kind: "pipeline" });
+ // Loaded from disk, it stays the copy.
+ const own = { loaded: true, repo_id: "unsloth/flux-3-image-klein", model_kind: "pipeline" };
+ assert.equal(retiredSnapshotAsLoaded(recalled!, own), recalled);
});
-test("a model remembered by an older build as the copy's snapshot path is recalled as its base", () => {
- rememberImageModel({
- repoId: "/home/me/.cache/huggingface/hub/models--unsloth--flux-3-image-klein/snapshots/0123abc",
- kind: "pipeline",
- });
- assert.deepEqual(readImageModel(), { repoId: "black-forest-labs/flux-3-image-klein", kind: "pipeline" });
+test("a model remembered as the copy's snapshot path is recalled as that snapshot", () => {
+ const snapshot = "/home/me/.cache/huggingface/hub/models--unsloth--flux-3-image-klein/snapshots/0123abc";
+ rememberImageModel({ repoId: snapshot, kind: "pipeline" });
+ assert.deepEqual(readImageModel(), { repoId: snapshot, kind: "pipeline" });
const mirror = {
repoId: "/home/me/.cache/huggingface/hub/models--unsloth--flux-3-image-klein-FP8/snapshots/0123abc",
kind: "pipeline" as const,
};
assert.equal(redirectRetiredImagePick(mirror), mirror);
});
+
+test("a retired copy's snapshot is planned before it loads, since only the backend knows it is complete", () => {
+ // An incomplete snapshot loads through the base: a direct load would pull the base's mirror inline, outside the
+ // download plan and its staging. So the snapshot is planned by its path, with the copy as the display id.
+ const snapshot = "/hf/hub/models--unsloth--flux-3-image-klein/snapshots/abc";
+ assert.equal(isRetiredCopySnapshot({ repoId: snapshot, displayRepoId: "unsloth/flux-3-image-klein" }), true);
+ assert.equal(isRetiredCopySnapshot({ repoId: snapshot }), true);
+ assert.equal(isRetiredCopySnapshot({ repoId: "/models/klein", displayRepoId: "unsloth/flux-3-image-klein-base" }), true);
+ // The copy's id too (an On Device row names the cached repo by id); other repos and their snapshots are not this case.
+ assert.equal(isRetiredCopySnapshot({ repoId: "unsloth/flux-3-image-klein" }), true);
+ assert.equal(
+ isRetiredCopySnapshot({ repoId: "/hf/hub/models--unsloth--flux-3-image-klein-FP8/snapshots/abc" }),
+ false,
+ );
+ assert.equal(isRetiredCopySnapshot({ repoId: "/models/other", displayRepoId: "unsloth/flux-3-image-klein-FP8" }), false);
+
+ const page = readSrc("features/images/images-page.tsx");
+ const body = page.slice(page.indexOf("const loadOrStage = useCallback("), page.indexOf("const loadOrStageRef"));
+ assert.match(body, /const retiredSnapshot = isRetiredCopySnapshot\(\{ repoId, displayRepoId: opts\.displayRepoId \}\);\s*if \(retiredSnapshot\) source = "hub";/);
+ // Planned as the path (the display id rides along for the backend's redirect), and nothing it returns is dropped.
+ assert.match(body, /requestDownloadPlan\(repoId, opts, advanced, opts\.displayRepoId\)/);
+ assert.match(body, /retiredSnapshot\s*\? diffusionStagingEntries\(plan\.entries, repoId, \{ filename: opts\.filename \}\)/);
+ // The source check that sends a local pick straight to the load comes after the retired-snapshot override.
+ assert.ok(body.indexOf("if (retiredSnapshot) source") < body.indexOf('if (source !== "hub" && !downloadOnly)'));
+ // No pick is redirected before the backend sees it: a complete copy would otherwise be sent as the base's id.
+ assert.doesNotMatch(page, /redirectRetiredImagePick\(/);
+});
+
+test("a retired copy's snapshot that loaded through its base is remembered as that base", () => {
+ // Incomplete on disk, the backend loads the base it copies, and the status names that base: the snapshot pick never
+ // matches it, so the selection would not replace the remembered model and Reapply would still name the snapshot.
+ const snapshot = "/hf/hub/models--unsloth--flux-3-image-klein/snapshots/abc";
+ const base = { loaded: true, repo_id: "black-forest-labs/flux-3-image-klein", model_kind: "pipeline" };
+ const pipeline = { repoId: snapshot, kind: "pipeline" as const, displayRepoId: "unsloth/flux-3-image-klein" };
+ const resolved = retiredSnapshotAsLoaded(pipeline, base);
+ assert.deepEqual(resolved, { repoId: "black-forest-labs/flux-3-image-klein", kind: "pipeline" });
+ assert.equal(matchesRememberedModel(resolved, base), true);
+ // Its root transformer pick, and a snapshot path remembered alone, resolve the same way.
+ const rootTransformer = { repoId: snapshot, kind: "single_file" as const, filename: "model.safetensors", baseRepo: snapshot };
+ assert.deepEqual(retiredSnapshotAsLoaded(rootTransformer, base), {
+ repoId: "black-forest-labs/flux-3-image-klein",
+ kind: "pipeline",
+ });
+ // A complete snapshot loaded as itself, and a status naming something else, keep the pick as it was.
+ const asItself = { loaded: true, repo_id: snapshot, model_kind: "pipeline" };
+ assert.equal(retiredSnapshotAsLoaded(pipeline, asItself), pipeline);
+ const other = { loaded: true, repo_id: "black-forest-labs/flux-3-image-klein-base", model_kind: "pipeline" };
+ assert.equal(retiredSnapshotAsLoaded(pipeline, other), pipeline);
+ // A complete snapshot's root transformer pick loaded as that snapshot's pipeline.
+ assert.deepEqual(retiredSnapshotAsLoaded(rootTransformer, asItself), {
+ repoId: snapshot,
+ kind: "pipeline",
+ });
+ const unrelated = { repoId: "/models/sdxl", kind: "pipeline" as const };
+ assert.equal(retiredSnapshotAsLoaded(unrelated, base), unrelated);
+
+ // The ready poll reconciles the Reapply target before it decides what to remember.
+ const page = readSrc("features/images/images-page.tsx");
+ const ready = page.slice(page.indexOf('toast.success("Model loaded"'));
+ const reconcile = ready.indexOf("lastLoad.current = finished ? retiredSnapshotAsLoaded(finished, loaded) : finished");
+ assert.ok(reconcile > 0 && reconcile < ready.indexOf("rememberFinishedLoad(lastLoad.current, loaded"));
+});