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 Images: keep v-prediction detection on cache-only SDXL loads by remembering the online markers per snapshot (#14873)

Daniel Hand436a92f2c3a
diff --git a/studio/backend/core/inference/diffusion_sampler.py b/studio/backend/core/inference/diffusion_sampler.py
index 6de4f1c7a88..f5f71e44859 100644
--- a/studio/backend/core/inference/diffusion_sampler.py
+++ b/studio/backend/core/inference/diffusion_sampler.py
@@ -215,6 +215,110 @@ def _marker_overrides(keys: Any) -> dict[str, Any]:
return overrides
+# Hub marker reads cached per (repo, snapshot commit) so later offline loads sample the same way.
+_MARKS_FILE = "diffusion_prediction_markers.json"
+_MAX_RECORDED_MARKS = 512
+
+
+def _marks_record_path() -> Any:
+ try:
+ from utils.paths.storage_roots import cache_root
+ return cache_root() / _MARKS_FILE
+ except Exception: # noqa: BLE001 - no Studio cache root: nothing is recorded
+ return None
+
+
+def _snapshot_commit(root: Optional[str], repo_id: str, revision: Optional[str]) -> Optional[str]:
+ """Snapshot commit from a ``snapshots/<commit>`` path, else the cached ``model_index.json``."""
+ from pathlib import Path
+
+ try:
+ if root:
+ folder = Path(str(root))
+ if folder.parent.name == "snapshots" and folder.name:
+ return folder.name
+ from huggingface_hub import try_to_load_from_cache
+
+ from utils.hf_cache_settings import active_hf_hub_cache
+
+ hit = try_to_load_from_cache(
+ repo_id,
+ "model_index.json",
+ cache_dir = active_hf_hub_cache(),
+ revision = revision,
+ )
+ except Exception: # noqa: BLE001 - no cache view: nothing to key on
+ return None
+ return Path(hit).parent.name if isinstance(hit, str) else None
+
+
+def _marks_key(repo_id: str, commit: str) -> str:
+ return f"{repo_id.strip().lower()}@{commit}"
+
+
+def _recorded_marks(repo_id: str, commit: Optional[str]) -> list[dict[str, Any]]:
+ import json
+
+ path = _marks_record_path()
+ if not commit or path is None:
+ return []
+ try:
+ hit = json.loads(path.read_text(encoding = "utf-8")).get(_marks_key(repo_id, commit))
+ except Exception: # noqa: BLE001 - absent / unreadable record: nothing recorded
+ return []
+ if not isinstance(hit, list) or not all(_well_formed_marks(m) for m in hit):
+ return []
+ return [_marker_overrides(set(m.get("markers") or ())) for m in hit]
+
+
+def _well_formed_marks(entry: Any) -> bool:
+ if not isinstance(entry, dict):
+ return False
+ markers = entry.get("markers")
+ return markers is None or (
+ isinstance(markers, list) and all(isinstance(m, str) for m in markers)
+ )
+
+
+def _record_marks(repo_id: str, commit: Optional[str], markers: list[list[str]]) -> None:
+ import contextlib
+ import json
+ import os
+ import threading
+
+ path = _marks_record_path()
+ if not commit or path is None:
+ return
+ tmp = path.with_name(f"{path.name}.{os.getpid()}.{threading.get_ident()}.tmp")
+ try:
+ path.parent.mkdir(parents = True, exist_ok = True)
+ try:
+ from filelock import FileLock
+ lock: Any = FileLock(f"{path}.lock", timeout = 30)
+ except ImportError:
+ lock = contextlib.nullcontext()
+ # One read / evict / write under a cross-process lock, so concurrent probes never drop entries.
+ with lock:
+ try:
+ record = json.loads(path.read_text(encoding = "utf-8"))
+ if not isinstance(record, dict):
+ record = {}
+ except Exception: # noqa: BLE001 - absent / corrupt: start over
+ record = {}
+ key = _marks_key(repo_id, commit)
+ record.pop(key, None)
+ while len(record) >= _MAX_RECORDED_MARKS:
+ record.pop(next(iter(record)))
+ record[key] = [{"markers": sorted(m)} for m in markers]
+ tmp.write_text(json.dumps(record), encoding = "utf-8")
+ os.replace(tmp, path)
+ except Exception: # noqa: BLE001 - read-only cache / lock timeout: the next offline load lacks the markers
+ try:
+ tmp.unlink()
+ except OSError:
+ pass
+
+
def _root_single_marks(
root: Optional[str],
repo_id: Optional[str] = None,
@@ -241,40 +345,50 @@ def _root_single_marks(
if singles:
return [checkpoint_prediction_overrides(str(p)) for p in singles]
rid = (repo_id or "").strip()
- if not allow_network or rid.count("/") != 1:
+ if rid.count("/") != 1:
return []
try:
if Path(rid).expanduser().exists():
return []
- from huggingface_hub import HfApi
-
from .diffusion_families import pinned_revision_kwargs
+ rev = pinned_revision_kwargs(rid)
+ commit = _snapshot_commit(root, rid, rev.get("revision"))
+ except Exception: # noqa: BLE001 - odd id: the shipped scheduler config stands
+ return []
+ if not allow_network:
+ # A cache-only load of a snapshot an online load already read keeps that read's verdict.
+ return _recorded_marks(rid, commit)
+ if commit:
+ # Read the snapshot the record is keyed on, never a HEAD that moved past the staged copy.
+ rev = {"revision": commit}
+ try:
+ from huggingface_hub import HfApi
+
from hub.utils.hf_tokens import normalize_token
# One normalisation for every Hub call here: False (anonymous) never becomes None (ambient).
hf_token = normalize_token(hf_token)
api = HfApi()
- rev = pinned_revision_kwargs(rid)
names = sorted(
f
for f in api.list_repo_files(rid, token = hf_token, **rev)
if "/" not in f and f.lower().endswith(".safetensors")
)
- return [
- _marker_overrides(
- {
- k
- for k in api.parse_safetensors_file_metadata(
- rid, name, token = hf_token, **rev
- ).tensors
- if "." not in k
- }
+ markers = [
+ sorted(
+ k
+ for k in api.parse_safetensors_file_metadata(
+ rid, name, token = hf_token, **rev
+ ).tensors
+ if k in ("v_pred", "ztsnr")
)
for name in names
]
- except Exception: # noqa: BLE001 - offline / gated / odd: the shipped scheduler config stands
- return []
+ except Exception: # noqa: BLE001 - offline / gated / odd: an earlier read of this snapshot, else the config
+ return _recorded_marks(rid, commit)
+ _record_marks(rid, commit, markers)
+ return [_marker_overrides(set(m)) for m in markers]
def pipeline_prediction_overrides(
diff --git a/studio/backend/tests/test_diffusion_vpred_sdxl_detect.py b/studio/backend/tests/test_diffusion_vpred_sdxl_detect.py
index 9ee3248d461..d0930886f72 100644
--- a/studio/backend/tests/test_diffusion_vpred_sdxl_detect.py
+++ b/studio/backend/tests/test_diffusion_vpred_sdxl_detect.py
@@ -71,6 +71,12 @@ def _write_safetensors(path: Path, keys) -> Path:
return path
[email protected](autouse = True)
+def _private_studio_cache(tmp_path, monkeypatch):
+ """Recorded marker reads land in a per-test Studio cache, never the real one."""
+ monkeypatch.setenv("UNSLOTH_STUDIO_HOME", str(tmp_path / "studio_home"))
+
+
@pytest.fixture
def hub_cache(tmp_path, monkeypatch):
"""An empty HF hub cache root, pinned as the live one; ``put`` caches a repo file."""
@@ -572,6 +578,114 @@ def test_a_staged_pipeline_snapshot_reads_the_root_markers_off_the_hub(tmp_path,
assert seen == []
+def _stub_noob_hub(monkeypatch, keys, seen):
+ import huggingface_hub
+
+ def files(
+ self,
+ repo_id,
+ token = None,
+ **kw,
+ ):
+ seen.append("list")
+ return ["model_index.json", NOOB_FILE]
+
+ def parse(
+ self,
+ repo_id,
+ filename,
+ token = None,
+ **kw,
+ ):
+ seen.append("header")
+ if keys is None:
+ raise OSError("offline")
+ return types.SimpleNamespace(tensors = {k: None for k in keys}, metadata = {})
+
+ monkeypatch.setattr(huggingface_hub.HfApi, "list_repo_files", files)
+ monkeypatch.setattr(huggingface_hub.HfApi, "parse_safetensors_file_metadata", parse)
+
+
+def _staged_snapshot(hub_cache, commit = SHA) -> Path:
+ # A staged pipeline snapshot: model_index.json + scheduler config, no root single file.
+ hub_cache.put(NOOB, "model_index.json", payload = SDXL_INDEX)
+ target = hub_cache.put(NOOB, "scheduler/scheduler_config.json", payload = NOOB_SCHEDULER)
+ snap = target.parent.parent
+ if commit != SHA:
+ renamed = snap.parent / commit
+ snap.rename(renamed)
+ (snap.parent.parent / "refs" / "main").write_text(commit)
+ snap = renamed
+ return snap
+
+
+VPRED = {
+ "prediction_type": "v_prediction",
+ "rescale_betas_zero_snr": True,
+ "timestep_spacing": "trailing",
+}
+
+
+def test_a_cache_only_reload_of_a_staged_snapshot_keeps_the_online_marker_read(
+ hub_cache, monkeypatch
+):
+ diffusers = pytest.importorskip("diffusers")
+ from core.inference.diffusion_sampler import apply_pipeline_prediction_type
+
+ snap = _staged_snapshot(hub_cache)
+ seen = []
+ _stub_noob_hub(monkeypatch, SDXL_UNET_KEYS + ["v_pred", "ztsnr"], seen)
+ assert pipeline_prediction_overrides(NOOB_SCHEDULER, str(snap), NOOB, None, True) == VPRED
+ assert seen == ["list", "header"]
+ # Offline loads (by snapshot path or repo id) reuse the recorded markers.
+ seen.clear()
+ _stub_noob_hub(monkeypatch, None, seen)
+ assert pipeline_prediction_overrides(NOOB_SCHEDULER, str(snap), NOOB, None, False) == VPRED
+ assert pipeline_prediction_overrides(NOOB_SCHEDULER, None, NOOB, None, False) == VPRED
+ assert seen == []
+ pipe = types.SimpleNamespace(
+ scheduler = diffusers.EulerDiscreteScheduler.from_config(NOOB_SCHEDULER)
+ )
+ assert apply_pipeline_prediction_type(pipe, str(snap), repo_id = NOOB, allow_network = False)
+ cfg = pipe.scheduler.config
+ assert (cfg.prediction_type, cfg.rescale_betas_zero_snr, cfg.timestep_spacing) == (
+ "v_prediction",
+ True,
+ "trailing",
+ )
+
+
+def test_a_failed_online_marker_read_falls_back_to_the_recorded_one(hub_cache, monkeypatch):
+ snap = _staged_snapshot(hub_cache)
+ seen = []
+ _stub_noob_hub(monkeypatch, SDXL_UNET_KEYS + ["v_pred", "ztsnr"], seen)
+ assert pipeline_prediction_overrides(NOOB_SCHEDULER, str(snap), NOOB, None, True) == VPRED
+ _stub_noob_hub(monkeypatch, None, seen)
+ assert pipeline_prediction_overrides(NOOB_SCHEDULER, str(snap), NOOB, None, True) == VPRED
+
+
+def test_a_recorded_marker_read_is_per_snapshot_commit(hub_cache, monkeypatch):
+ snap = _staged_snapshot(hub_cache)
+ _stub_noob_hub(monkeypatch, SDXL_UNET_KEYS + ["v_pred", "ztsnr"], [])
+ assert pipeline_prediction_overrides(NOOB_SCHEDULER, str(snap), NOOB, None, True) == VPRED
+ other = snap.parent / ("f" * 40)
+ other.mkdir()
+ # Another commit of the repo was never read: its shipped config stands offline.
+ assert pipeline_prediction_overrides(NOOB_SCHEDULER, str(other), NOOB, None, False) == {}
+ # An online read that finds no markers replaces the record, so an eps re-release stays eps offline.
+ _stub_noob_hub(monkeypatch, SDXL_UNET_KEYS, [])
+ assert pipeline_prediction_overrides(NOOB_SCHEDULER, str(snap), NOOB, None, True) == {}
+ assert pipeline_prediction_overrides(NOOB_SCHEDULER, str(snap), NOOB, None, False) == {}
+
+
+def test_an_unrecorded_cache_only_load_keeps_the_shipped_config(hub_cache, monkeypatch):
+ snap = _staged_snapshot(hub_cache)
+ seen = []
+ _stub_noob_hub(monkeypatch, SDXL_UNET_KEYS + ["v_pred", "ztsnr"], seen)
+ assert pipeline_prediction_overrides(NOOB_SCHEDULER, str(snap), NOOB, None, False) == {}
+ assert seen == []
+
+
def test_the_load_passes_the_repo_to_the_pipeline_marker_check():
import ast
@@ -693,3 +807,82 @@ def test_the_load_hands_the_uncollapsed_token_to_the_marker_probe():
assert len(probe) == 1
token_kw = next(k for k in probe[0].keywords if k.arg == "hf_token")
assert isinstance(token_kw.value, ast.Name) and token_kw.value.id == "hub_token"
+
+
+def test_the_marker_probe_reads_the_snapshot_it_records(hub_cache, monkeypatch):
+ import huggingface_hub
+
+ snap = _staged_snapshot(hub_cache)
+ revisions = []
+
+ def files(
+ self,
+ repo_id,
+ token = None,
+ **kw,
+ ):
+ revisions.append(kw.get("revision"))
+ return ["model_index.json", NOOB_FILE]
+
+ def parse(
+ self,
+ repo_id,
+ filename,
+ token = None,
+ **kw,
+ ):
+ revisions.append(kw.get("revision"))
+ keys = SDXL_UNET_KEYS + ["v_pred", "ztsnr"]
+ return types.SimpleNamespace(tensors = {k: None for k in keys}, metadata = {})
+
+ monkeypatch.setattr(huggingface_hub.HfApi, "list_repo_files", files)
+ monkeypatch.setattr(huggingface_hub.HfApi, "parse_safetensors_file_metadata", parse)
+ # No revision pin: both Hub reads still target the staged commit, not the moving HEAD.
+ assert pipeline_prediction_overrides(NOOB_SCHEDULER, str(snap), NOOB, None, True) == VPRED
+ assert revisions == [SHA, SHA]
+
+
[email protected]("markers", [5, [["v_pred"]], "v_pred", [1]])
+def test_a_malformed_recorded_entry_is_a_cache_miss(hub_cache, monkeypatch, markers):
+ from core.inference.diffusion_sampler import _marks_key, _marks_record_path
+
+ snap = _staged_snapshot(hub_cache)
+ path = _marks_record_path()
+ path.parent.mkdir(parents = True, exist_ok = True)
+ path.write_text(json.dumps({_marks_key(NOOB, SHA): [{"markers": markers}]}))
+ assert pipeline_prediction_overrides(NOOB_SCHEDULER, str(snap), NOOB, None, False) == {}
+ _stub_noob_hub(monkeypatch, None, [])
+ assert pipeline_prediction_overrides(NOOB_SCHEDULER, str(snap), NOOB, None, True) == {}
+
+
+def test_concurrent_marker_records_keep_every_entry(hub_cache, monkeypatch):
+ import os
+ import threading
+
+ import core.inference.diffusion_sampler as sampler
+
+ real_replace = os.replace
+ first_read = threading.Event()
+ release = threading.Event()
+ calls = []
+
+ def slow_replace(src, dst):
+ # The first writer has read the record; hold it until the second writer has had its turn.
+ if not calls:
+ calls.append(1)
+ first_read.set()
+ release.wait(5)
+ return real_replace(src, dst)
+
+ monkeypatch.setattr(os, "replace", slow_replace)
+ a = threading.Thread(target = sampler._record_marks, args = (NOOB, "a" * 40, [["v_pred"]]))
+ a.start()
+ assert first_read.wait(5)
+ b = threading.Thread(target = sampler._record_marks, args = (NOOB, "b" * 40, [["v_pred"]]))
+ b.start()
+ b.join(1)
+ release.set()
+ a.join(5)
+ b.join(5)
+ record = json.loads(sampler._marks_record_path().read_text(encoding = "utf-8"))
+ assert {sampler._marks_key(NOOB, "a" * 40), sampler._marks_key(NOOB, "b" * 40)} <= set(record)