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: an offline diffusion load reads the mirror the earlier online load staged (#16276)

Daniel Han3ecb1ba36039
diff --git a/studio/backend/core/inference/diffusion.py b/studio/backend/core/inference/diffusion.py
index 60db96a3a28..7a3bf200e6d 100644
--- a/studio/backend/core/inference/diffusion.py
+++ b/studio/backend/core/inference/diffusion.py
@@ -1445,6 +1445,21 @@ def _base_manifest_name(fam: Any) -> str:
return FLUX3_INDEX if is_flux3_family(fam) else "model_index.json"
+def _cached_mirror_manifest(base: str, manifest: str) -> tuple[str, ...]:
+ """Offline mirror probe: the manifest when the mirror's cache holds it, else ().
+
+ With no file list, ``prefer_ungated_mirror`` keeps the upstream for ANY cached weight, so a stray single-file
+ checkpoint in the upstream snapshot pinned offline loads there although the pipeline was staged under the mirror.
+ """
+
+ from .diffusion_families import mirror_repo
+
+ mirror = mirror_repo(base)
+ if mirror and mirror.lower() != (base or "").lower() and cache_holds_files(mirror, (manifest,)):
+ return (manifest,)
+ return ()
+
+
def _te_quant_for_supplied_encoders(requested: Optional[str]) -> Optional[str]:
"""Unset / auto never re-casts a supplied encoder (it would fetch the hosted encoder the file replaces)."""
if requested is None or str(requested).strip().lower() in ("", "auto"):
@@ -5558,7 +5573,9 @@ class DiffusionBackend:
) or _local_base_transformer_present(base)
# One mirror decision per load, so staging and assembly use the same repo.
fetch_base = fetch_repos.get(base) or prefer_ungated_mirror(
- base, kwargs.get("hf_token"), files = base_files
+ base,
+ kwargs.get("hf_token"),
+ files = base_files or _cached_mirror_manifest(base, _base_manifest_name(fam)),
)
kwargs["_fetch_base"] = fetch_base
# Catch a gated base before the prefetch moves any bytes; probes fetch_base.
diff --git a/studio/backend/tests/test_diffusion_offline_mirror_cache.py b/studio/backend/tests/test_diffusion_offline_mirror_cache.py
new file mode 100644
index 00000000000..3a180432403
--- /dev/null
+++ b/studio/backend/tests/test_diffusion_offline_mirror_cache.py
@@ -0,0 +1,100 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Offline loads must use the mirror the online prefetch staged, not an upstream snapshot holding only a stray file."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from core.inference import diffusion as D
+from core.inference.diffusion import DiffusionBackend, _LoadingState
+from utils import hf_cache_settings
+
+
+def _snapshot(hub: Path, repo_id: str, sha: str, files: dict[str, bytes]) -> Path:
+ repo = hub / ("models--" + repo_id.replace("/", "--"))
+ (repo / "refs").mkdir(parents = True, exist_ok = True)
+ (repo / "refs" / "main").write_text(sha)
+ snap = repo / "snapshots" / sha
+ for name, data in files.items():
+ (snap / name).parent.mkdir(parents = True, exist_ok = True)
+ (snap / name).write_bytes(data)
+ return snap
+
+
+_PIPELINE = {
+ "model_index.json": b"{}",
+ "unet/config.json": b"{}",
+ "unet/diffusion_pytorch_model.safetensors": b"0",
+ "vae/config.json": b"{}",
+ "vae/diffusion_pytorch_model.safetensors": b"0",
+}
+
+# (upstream, mirror, what the stray download left in the upstream snapshot)
+_CASES = [
+ (
+ "stabilityai/stable-diffusion-xl-base-1.0",
+ "unsloth/stable-diffusion-xl-base-1.0",
+ {"sd_xl_base_1.0.safetensors": b"0"},
+ ),
+ (
+ "Tongyi-MAI/Z-Image-Turbo",
+ "unsloth/Z-Image-Turbo",
+ {
+ "text_encoder/model-00001-of-00003.safetensors": b"0",
+ "transformer/diffusion_pytorch_model-00001-of-00003.safetensors": b"0",
+ },
+ ),
+]
+
+
+def hub(monkeypatch, tmp_path):
+ hub = tmp_path / "hub"
+ hub.mkdir()
+ monkeypatch.delenv("UNSLOTH_DIFFUSION_NO_MIRROR", raising = False)
+ monkeypatch.setattr(hf_cache_settings, "active_hf_hub_cache", lambda: str(hub))
+ monkeypatch.setattr(D, "hub_cache_dir", lambda: str(hub))
+ return hub
+
+
+def _offline_fetch_base(monkeypatch, repo_id: str) -> str:
+ loaded: dict = {}
+ monkeypatch.setattr(DiffusionBackend, "_prefetch_files", lambda self, *a, **k: None)
+ monkeypatch.setattr(DiffusionBackend, "load_pipeline", lambda self, **k: loaded.update(k))
+ backend = DiffusionBackend()
+ backend._loading = _LoadingState(repo_id = repo_id, base_repo = repo_id)
+ backend._run_load(
+ repo_id = repo_id,
+ local_files_only = True,
+ _load_token = backend._load_token,
+ )
+ assert backend._loading is None, "the staging phase raised before load_pipeline"
+ assert loaded.get("local_files_only") is True
+ return loaded["_fetch_base"]
+
+
[email protected]("upstream,mirror,stray", _CASES)
+def test_offline_load_reads_the_mirror_prefetch_staged(monkeypatch, hub, upstream, mirror, stray):
+ _snapshot(hub, upstream, "a" * 40, stray)
+ _snapshot(hub, mirror, "b" * 40, _PIPELINE)
+ assert _offline_fetch_base(monkeypatch, upstream) == mirror
+
+
[email protected]("upstream,mirror,stray", _CASES)
+def test_offline_load_keeps_a_full_upstream_pipeline(monkeypatch, hub, upstream, mirror, stray):
+ _snapshot(hub, upstream, "a" * 40, {**stray, **_PIPELINE})
+ _snapshot(hub, mirror, "b" * 40, _PIPELINE)
+ assert _offline_fetch_base(monkeypatch, upstream) == upstream
+
+
+def test_without_a_cached_mirror_manifest_the_old_decision_stands(hub):
+ upstream, mirror, stray = _CASES[0]
+ _snapshot(hub, upstream, "a" * 40, stray)
+ assert D._cached_mirror_manifest(upstream, "model_index.json") == ()
+ _snapshot(hub, mirror, "b" * 40, _PIPELINE)
+ assert D._cached_mirror_manifest(upstream, "model_index.json") == ("model_index.json",)
+ assert D._cached_mirror_manifest("someone/finetune", "model_index.json") == ()