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
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.pyindex 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. Emptydiff --git a/studio/backend/core/inference/media_auto_switch.py b/studio/backend/core/inference/media_auto_switch.pyindex 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 pickreturn 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_diskfrom core.inference.media_locality import flux3_seeded_cache_repo, seeded_family_overridefrom models.inference import DiffusionLoadRequestfrom routes.inference import load_diffusion_model_gated@@ -276,6 +283,9 @@ async def _start_load(model_path = pick.model_pathfamily_override = Noneseeded_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 = Noneif seeded_repo:model_path = seeded_repo# The listing named the family from the snapshot's modular_model_index.json; an opaquely named repo iddiff --git a/studio/backend/models/inference.py b/studio/backend/models/inference.pyindex 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 Noneand 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, Noneself.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 selfdiff --git a/studio/backend/tests/test_flux3_retired_copy_on_disk.py b/studio/backend/tests/test_flux3_retired_copy_on_disk.pynew file mode 100644index 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.pyindex 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.tsindex 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?: Imagcurrent: 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.tsxindex 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.0import { 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.tsindex 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 andconst 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.tsindex 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 savedrememberPendingImageLoad({ ...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.tsindex 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"));+});