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: use a cached earlier FLUX.3 upsampler quant when the default is missing (#14842)

Daniel Hanc032ada4551e
diff --git a/studio/backend/core/inference/flux3_prompt_upsampler.py b/studio/backend/core/inference/flux3_prompt_upsampler.py
index a6e02e2e134..e0e5355fa51 100644
--- a/studio/backend/core/inference/flux3_prompt_upsampler.py
+++ b/studio/backend/core/inference/flux3_prompt_upsampler.py
@@ -54,6 +54,11 @@ UPSAMPLER_MODEL_FILES = {
# divergence than the imatrix Q4_K_M for 6% more bytes, at the same speed.
UPSAMPLER_DEFAULT_QUANT = "UD-Q4_K_XL"
UPSAMPLER_MODEL_FILE = UPSAMPLER_MODEL_FILES[UPSAMPLER_DEFAULT_QUANT]
+# Cached earlier defaults, best first, used when UPSAMPLER_MODEL_FILE is absent (fresh installs still download it).
+UPSAMPLER_CACHED_FALLBACK_QUANTS = ("Q8_0", "Q4_K_M")
+UPSAMPLER_MODEL_FILE_PREFERENCE = (UPSAMPLER_MODEL_FILE,) + tuple(
+ UPSAMPLER_MODEL_FILES[quant] for quant in UPSAMPLER_CACHED_FALLBACK_QUANTS
+)
# Vision projector, needed only for edits (reference images).
UPSAMPLER_MMPROJ_FILE = "mmproj-F16.gguf"
# Expected sizes of the files as built, for the UI before the download starts (the download reads the real ones).
@@ -726,16 +731,18 @@ def _cached_at_any_revision(filename: str, hub_cache: Optional[Path] = None) ->
def _cached_pair(hub_cache: Optional[Path] = None) -> tuple[Optional[str], Optional[str]]:
"""The model and projector from ONE revision (the recorded one first), as the downloader pins them; a model
- with no projector at its revision when no revision holds both."""
+ with no projector at its revision when no revision holds both. Files tried in UPSAMPLER_MODEL_FILE_PREFERENCE order."""
+ revisions = _candidate_revisions(hub_cache)
model_only = None
- for revision in _candidate_revisions(hub_cache):
- model = _cached_file(UPSAMPLER_MODEL_FILE, hub_cache = hub_cache, revision = revision)
- if model is None:
- continue
- mmproj = _cached_file(UPSAMPLER_MMPROJ_FILE, hub_cache = hub_cache, revision = revision)
- if mmproj is not None:
- return model, mmproj
- model_only = model_only or model
+ for filename in UPSAMPLER_MODEL_FILE_PREFERENCE:
+ for revision in revisions:
+ model = _cached_file(filename, hub_cache = hub_cache, revision = revision)
+ if model is None:
+ continue
+ mmproj = _cached_file(UPSAMPLER_MMPROJ_FILE, hub_cache = hub_cache, revision = revision)
+ if mmproj is not None:
+ return model, mmproj
+ model_only = model_only or model
return model_only, None
@@ -745,7 +752,8 @@ def _cached_download_paths(
hub_cache: Optional[Path] = None,
revision: Optional[str] = None,
) -> Optional[tuple[str, str]]:
- """Both repo files at one revision, or None (the download state's completion check)."""
+ """Both repo files at one revision, or None (the download state's completion check). A pinned revision is the
+ one just downloaded, so it checks the default quant the download fetched; without one, any cached quant counts."""
if revision is None:
model, mmproj = _cached_pair(hub_cache)
else:
@@ -827,9 +835,7 @@ def status() -> dict:
"""The prompt-upsampler status route body."""
model = model_path()
mmproj = mmproj_path()
- model_name = (
- Path(model).name if model and os.environ.get(ENV_MODEL_OVERRIDE) else UPSAMPLER_MODEL_FILE
- )
+ model_name = Path(model).name if model else UPSAMPLER_MODEL_FILE
size = None
if model:
with suppress(OSError):
@@ -840,7 +846,9 @@ def status() -> dict:
"loaded": get_sidecar().loaded,
"repo": UPSAMPLER_REPO,
"filename": model_name,
- "size_bytes": size or UPSAMPLER_FILE_SIZES.get(UPSAMPLER_MODEL_FILE),
+ "size_bytes": size
+ or UPSAMPLER_FILE_SIZES.get(model_name)
+ or UPSAMPLER_FILE_SIZES.get(UPSAMPLER_MODEL_FILE),
"mmproj_filename": UPSAMPLER_MMPROJ_FILE,
"mmproj_size_bytes": UPSAMPLER_FILE_SIZES.get(UPSAMPLER_MMPROJ_FILE),
"mmproj_downloaded": mmproj is not None,
diff --git a/studio/backend/tests/test_flux3_prompt_upsampler.py b/studio/backend/tests/test_flux3_prompt_upsampler.py
index 70a21aff01c..2730843c182 100644
--- a/studio/backend/tests/test_flux3_prompt_upsampler.py
+++ b/studio/backend/tests/test_flux3_prompt_upsampler.py
@@ -1413,6 +1413,131 @@ def test_model_and_projector_come_from_one_revision(monkeypatch):
assert pup._cached_download_paths(pup.UPSAMPLER_ID) is None
+# ── an earlier default quant already in the cache ───────────────────────────────────────────────────────────────────
+_REV_A = "a" * 40
+_REV_B = "b" * 40
+
+
+def fake_hub(monkeypatch, tmp_path):
+ """A real Hugging Face cache layout under tmp_path, with no revision record, so lookups go through
+ hf_hub_download(local_files_only=True) the way the app does."""
+ from core.inference import stt_sidecar
+
+ hub = tmp_path / "hub"
+ repo_dir = hub / f"models--{pup.UPSAMPLER_REPO.replace('/', '--')}"
+ monkeypatch.setattr(stt_sidecar, "_active_hf_hub_cache", lambda: hub)
+ monkeypatch.setattr(stt_sidecar, "_read_revision_record", lambda repo: None)
+ monkeypatch.setattr(pup, "find_llama_server_binary", lambda: "/usr/bin/llama-server")
+
+ def put(
+ revision,
+ *filenames,
+ main = False,
+ ):
+ snapshot = repo_dir / "snapshots" / revision
+ snapshot.mkdir(parents = True, exist_ok = True)
+ for name in filenames:
+ (snapshot / name).write_bytes(name.encode())
+ if main:
+ (repo_dir / "refs").mkdir(parents = True, exist_ok = True)
+ (repo_dir / "refs" / "main").write_text(revision)
+ return snapshot
+
+ return put
+
+
+def test_a_cached_earlier_quant_is_used_when_the_default_is_missing(fake_hub):
+ q4 = pup.UPSAMPLER_MODEL_FILES["Q4_K_M"]
+ snapshot = fake_hub(_REV_A, q4, pup.UPSAMPLER_MMPROJ_FILE, main = True)
+ assert pup.model_path() == str(snapshot / q4)
+ assert pup.mmproj_path() == str(snapshot / pup.UPSAMPLER_MMPROJ_FILE)
+ assert pup._cached_download_paths(pup.UPSAMPLER_ID) == (
+ str(snapshot / q4),
+ str(snapshot / pup.UPSAMPLER_MMPROJ_FILE),
+ )
+ out = pup.status()
+ # Ready: the UI offers no download beside it.
+ assert (
+ out["supported"] is True and out["downloaded"] is True and out["mmproj_downloaded"] is True
+ )
+ assert out["override"] is False
+ assert out["filename"] == q4 and out["size_bytes"] == len(q4.encode())
+
+
+def test_the_default_quant_wins_over_a_cached_fallback(fake_hub):
+ fake_hub(_REV_B, pup.UPSAMPLER_MODEL_FILES["Q8_0"], pup.UPSAMPLER_MMPROJ_FILE)
+ snapshot = fake_hub(
+ _REV_A,
+ pup.UPSAMPLER_MODEL_FILE,
+ pup.UPSAMPLER_MODEL_FILES["Q4_K_M"],
+ pup.UPSAMPLER_MMPROJ_FILE,
+ main = True,
+ )
+ assert pup.model_path() == str(snapshot / pup.UPSAMPLER_MODEL_FILE)
+ out = pup.status()
+ assert out["downloaded"] is True and out["filename"] == pup.UPSAMPLER_MODEL_FILE
+
+
+def test_q8_0_is_preferred_over_q4_k_m_among_fallbacks(fake_hub):
+ snapshot = fake_hub(
+ _REV_A,
+ pup.UPSAMPLER_MODEL_FILES["Q4_K_M"],
+ pup.UPSAMPLER_MODEL_FILES["Q8_0"],
+ pup.UPSAMPLER_MMPROJ_FILE,
+ main = True,
+ )
+ assert pup.model_path() == str(snapshot / pup.UPSAMPLER_MODEL_FILES["Q8_0"])
+ assert pup.UPSAMPLER_MODEL_FILE_PREFERENCE == (
+ pup.UPSAMPLER_MODEL_FILE,
+ pup.UPSAMPLER_MODEL_FILES["Q8_0"],
+ pup.UPSAMPLER_MODEL_FILES["Q4_K_M"],
+ )
+ assert set(pup.UPSAMPLER_MODEL_FILE_PREFERENCE) == set(pup.UPSAMPLER_MODEL_FILES.values())
+
+
+def test_a_fallback_quant_pairs_with_the_projector_at_its_own_revision(fake_hub):
+ q4 = pup.UPSAMPLER_MODEL_FILES["Q4_K_M"]
+ # The newest revision holds only the projector; the old quant and its projector sit at an older one.
+ fake_hub(_REV_B, pup.UPSAMPLER_MMPROJ_FILE, main = True)
+ old = fake_hub(_REV_A, q4, pup.UPSAMPLER_MMPROJ_FILE)
+ assert (pup.model_path(), pup.mmproj_path()) == (
+ str(old / q4),
+ str(old / pup.UPSAMPLER_MMPROJ_FILE),
+ )
+
+
+def test_the_completion_check_of_a_pinned_download_still_wants_the_default(fake_hub):
+ # A download pins the revision it fetched; an older quant there does not complete the default's download.
+ fake_hub(_REV_A, pup.UPSAMPLER_MODEL_FILES["Q4_K_M"], pup.UPSAMPLER_MMPROJ_FILE, main = True)
+ assert pup._cached_download_paths(pup.UPSAMPLER_ID, revision = _REV_A) is None
+
+
+def test_nothing_cached_is_not_ready_and_downloads_the_default(fake_hub):
+ out = pup.status()
+ assert out["downloaded"] is False and out["mmproj_downloaded"] is False
+ assert out["filename"] == pup.UPSAMPLER_MODEL_FILE == "flux-3-image-klein-pup-UD-Q4_K_XL.gguf"
+ assert out["size_bytes"] == pup.UPSAMPLER_FILE_SIZES[pup.UPSAMPLER_MODEL_FILE]
+ assert pup.model_path() is None and pup._cached_download_paths(pup.UPSAMPLER_ID) is None
+ spec = pup._get_download_state()._spec(pup.UPSAMPLER_ID)
+ assert (spec.model_file, spec.mmproj_file) == (
+ pup.UPSAMPLER_MODEL_FILE,
+ pup.UPSAMPLER_MMPROJ_FILE,
+ )
+
+
+def test_an_override_still_beats_a_cached_quant(fake_hub, monkeypatch, tmp_path):
+ fake_hub(_REV_A, pup.UPSAMPLER_MODEL_FILES["Q4_K_M"], pup.UPSAMPLER_MMPROJ_FILE, main = True)
+ local = tmp_path / "local.gguf"
+ local.write_bytes(b"x")
+ monkeypatch.setenv(pup.ENV_MODEL_OVERRIDE, str(local))
+ assert pup.model_path() == str(local)
+ assert pup.status()["filename"] == "local.gguf" and pup.status()["override"] is True
+ # A missing override is a typo: not ready, never the cached quant instead.
+ monkeypatch.setenv(pup.ENV_MODEL_OVERRIDE, str(tmp_path / "missing.gguf"))
+ assert pup.model_path() is None
+
+
def test_no_repo_download_beside_an_override(routes, monkeypatch):
client, backend, saved = routes
started = []