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 diffusion: price a released pipeline from its bf16 table while its cache is incomplete (#15236)

Daniel Han4533c4636a8e
diff --git a/studio/backend/core/inference/diffusion.py b/studio/backend/core/inference/diffusion.py
index 2e6f34bac09..eda31a3b873 100644
--- a/studio/backend/core/inference/diffusion.py
+++ b/studio/backend/core/inference/diffusion.py
@@ -75,6 +75,7 @@ from .diffusion_families import (
assert_flux3_checkpoint_matches_family,
assert_pipeline_class_available,
_is_local_path,
+ _MIRROR_UPSTREAM,
canonical_base,
cache_holds_files,
comfy_flow_shift_for,
@@ -669,6 +670,45 @@ def _listing_extra(listing_repo: str, rfilename: str) -> bool:
)
+_GB_TO_MIB = (1000.0**3) / (1024.0 * 1024.0)
+# Upstream releases Studio keeps a byte mirror of: their size is the family table's, not a fine-tune's.
+_MIRRORED_UPSTREAMS: frozenset[str] = frozenset(
+ u.strip().lower() for u in _MIRROR_UPSTREAM.values()
+)
+
+
+def _incomplete_release_cache_floor(
+ fam: Any,
+ repo_id: Optional[str],
+ complete: bool,
+ model_dense_mib: Optional[int],
+ companion_mib: Optional[int],
+ text_encoder_mib: Optional[int],
+) -> Optional[tuple[int, int, int]]:
+ """(model, companions, text encoders) MiB floored at the bf16 table for a mirrored release whose cache is incomplete.
+
+ A downloading load plans before bytes land: a text-encoder-only cache priced FLUX.1-dev at 9.3 GB, then OOM'd on
+ a 22 GB card. Fine-tunes keep their own bytes."""
+ if complete or not repo_id:
+ return None
+ release = canonical_base(repo_id).strip()
+ key = release.lower()
+ if not (
+ key == str(getattr(fam, "base_repo", "") or "").strip().lower()
+ or key in _MIRRORED_UPSTREAMS
+ or base_repo_bf16_components_gb(release) is not None
+ ):
+ return None
+ table = family_bf16_components_gb(fam, release)
+ if table is None:
+ return None
+ return (
+ max(model_dense_mib or 0, int(sum(table) * _GB_TO_MIB)),
+ max(companion_mib or 0, int(sum(table[1:]) * _GB_TO_MIB)),
+ max(text_encoder_mib or 0, int(table[1] * _GB_TO_MIB)),
+ )
+
+
def hub_cache_dir() -> str:
"""The cache root every loader call must be pinned to. diffusers resolves an unset cache_dir
through huggingface_hub's import-time constant, which a mid-session cache-folder change does
@@ -7583,6 +7623,29 @@ class DiffusionBackend:
return [live]
return [live, Path(other) / folder]
+ @staticmethod
+ def _pipeline_source_complete(
+ local_repo: Optional[Path], staged_repo: Optional[Path], cache_repo: Optional[str]
+ ) -> bool:
+ """True if a local, staged or live cached snapshot holds every manifest component."""
+ trees = [p for p in (local_repo, staged_repo) if p is not None]
+ if cache_repo:
+ trees += [
+ DiffusionBackend._live_snapshot_dir(d)
+ for d in DiffusionBackend._hub_cache_repo_dirs(cache_repo)
+ ]
+ for tree in trees:
+ if tree is None:
+ continue
+ try:
+ if tree.is_dir() and local_pipeline_components_are_complete(
+ tree, "model_index.json"
+ ):
+ return True
+ except OSError:
+ continue
+ return False
+
@staticmethod
def _live_snapshot_dir(repo_dir: Path) -> Optional[Path]:
"""The snapshot ``refs/main`` names: the ONE revision a load reads out of this root.
@@ -12647,6 +12710,18 @@ class DiffusionBackend:
text_encoder_mib = int(table[1] * (1000.0**3) / (1024.0 * 1024.0))
# Already the dense bf16 encoders, an upper bound on any pre-cast one: swapping would add it on top.
companions_from_cache = False
+ elif table is None:
+ floored = _incomplete_release_cache_floor(
+ fam,
+ repo_id,
+ self._pipeline_source_complete(local_repo, staged_repo, cache_repo),
+ model_dense_mib,
+ companion_mib,
+ text_encoder_mib,
+ )
+ if floored is not None:
+ model_dense_mib, companion_mib, text_encoder_mib = floored
+ companions_from_cache = False
if companion_mib is not None and model_dense_mib is not None:
# The two terms come from different merges over the cache roots, so a repo only one of them can see
# must not report companions larger than the model.
diff --git a/studio/backend/tests/test_diffusion_incomplete_release_cache.py b/studio/backend/tests/test_diffusion_incomplete_release_cache.py
new file mode 100644
index 00000000000..081be1f488f
--- /dev/null
+++ b/studio/backend/tests/test_diffusion_incomplete_release_cache.py
@@ -0,0 +1,164 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Incomplete release caches are priced from the family bf16 table (CPU only)."""
+
+from __future__ import annotations
+
+import json
+import types
+from pathlib import Path
+
+import pytest
+
+from core.inference import diffusion as dmod
+from core.inference.diffusion import DiffusionBackend
+from core.inference.diffusion_families import (
+ detect_family,
+ local_pipeline_components_are_complete,
+)
+from core.inference.diffusion_memory import OFFLOAD_NONE, DeviceMemory
+
+MIRROR = "unsloth/FLUX.1-dev"
+UPSTREAM = "black-forest-labs/FLUX.1-dev"
+FINETUNE = "someone/flux-dev-finetune"
+REV = "0" * 40
+MIB = 1024 * 1024
+
+_MODELS = {
+ "text_encoder": ("transformers", "CLIPTextModel", "model.safetensors"),
+ "text_encoder_2": ("transformers", "T5EncoderModel", "model.safetensors"),
+ "transformer": ("diffusers", "FluxTransformer2DModel", "diffusion_pytorch_model.safetensors"),
+ "vae": ("diffusers", "AutoencoderKL", "diffusion_pytorch_model.safetensors"),
+}
+
+
+def _safetensors(path: Path, mib: int) -> None:
+ """A valid one-tensor safetensors file of about ``mib`` MiB."""
+ numel = mib * MIB // 2
+ header = json.dumps(
+ {"w": {"dtype": "BF16", "shape": [numel], "data_offsets": [0, numel * 2]}}
+ ).encode()
+ header += b" " * (-len(header) % 8)
+ path.parent.mkdir(parents = True, exist_ok = True)
+ with open(path, "wb") as fh:
+ fh.write(len(header).to_bytes(8, "little") + header)
+ fh.truncate(8 + len(header) + numel * 2)
+
+
+def _snapshot(
+ hub: Path,
+ repo_id: str,
+ components: tuple[str, ...],
+ mib: int = 2,
+) -> Path:
+ repo = hub / f"models--{repo_id.replace('/', '--')}"
+ (repo / "refs").mkdir(parents = True)
+ (repo / "refs" / "main").write_text(REV)
+ snap = repo / "snapshots" / REV
+ index = {"_class_name": "FluxPipeline", "_diffusers_version": "0.30.0"}
+ index["scheduler"] = ["diffusers", "FlowMatchEulerDiscreteScheduler"]
+ index["tokenizer"] = ["transformers", "CLIPTokenizer"]
+ index["tokenizer_2"] = ["transformers", "T5TokenizerFast"]
+ for name, (lib, cls, _f) in _MODELS.items():
+ index[name] = [lib, cls]
+ snap.mkdir(parents = True)
+ (snap / "model_index.json").write_text(json.dumps(index))
+ for folder, files in (
+ ("scheduler", {"scheduler_config.json": "{}"}),
+ ("tokenizer", {"tokenizer_config.json": "{}", "vocab.json": "{}", "merges.txt": "#v\n"}),
+ ("tokenizer_2", {"tokenizer_config.json": "{}", "tokenizer.json": "{}"}),
+ ):
+ (snap / folder).mkdir()
+ for name, text in files.items():
+ (snap / folder / name).write_text(text)
+ for name in components:
+ (snap / name).mkdir()
+ (snap / name / "config.json").write_text("{}")
+ _safetensors(snap / name / _MODELS[name][2], mib)
+ return snap
+
+
+def l4(monkeypatch, tmp_path):
+ from huggingface_hub import constants as hf_constants
+
+ live, other = tmp_path / "live-hub", tmp_path / "import-time-hub"
+ live.mkdir()
+ other.mkdir()
+ monkeypatch.setattr(dmod, "hub_cache_dir", lambda: str(live))
+ monkeypatch.setattr(hf_constants, "HF_HUB_CACHE", str(other))
+ monkeypatch.setattr(
+ dmod,
+ "settled_snapshot_device_memory",
+ lambda t: DeviceMemory("cuda", "cuda", "discrete_vram", 22_200, 23_034),
+ )
+ monkeypatch.setattr(dmod, "estimate_image_runtime_mib", lambda **kw: 1_000)
+ target = types.SimpleNamespace(device = "cuda", backend = "cuda", supports_model_cpu_offload = True)
+ return types.SimpleNamespace(target = target, hub = live)
+
+
+def _plan(
+ target,
+ repo_id,
+ base = UPSTREAM,
+):
+ fam = detect_family(UPSTREAM)
+ assert fam is not None
+ return DiffusionBackend()._plan_memory(
+ target, None, base, fam, None, False, kind = "pipeline", repo_id = repo_id, fetch_base = repo_id
+ )
+
+
+def _table_total_mib():
+ fam = detect_family(UPSTREAM)
+ table = dmod.family_bf16_components_gb(fam, UPSTREAM)
+ return int(sum(table) * dmod._GB_TO_MIB)
+
+
+def test_fixture_snapshots_read_as_complete_and_incomplete(l4):
+ full = _snapshot(l4.hub, "a/full", tuple(_MODELS))
+ part = _snapshot(l4.hub, "a/part", ("text_encoder", "text_encoder_2"))
+ assert local_pipeline_components_are_complete(full, "model_index.json")
+ assert not local_pipeline_components_are_complete(part, "model_index.json")
+
+
[email protected]("repo_id", [MIRROR, UPSTREAM])
+def test_text_encoders_only_cache_prices_the_release_from_its_table(l4, repo_id):
+ """A cache holding only the text encoders must not price the pipeline at the encoders."""
+ _snapshot(l4.hub, repo_id, ("text_encoder", "text_encoder_2"), mib = 64)
+ plan = _plan(l4.target, repo_id)
+ assert plan.estimates["model_dense_mib"] >= _table_total_mib(), plan.estimates
+ assert plan.estimates["companion_dense_mib"] is not None
+ assert plan.estimates["text_encoder_dense_mib"] is not None
+ assert plan.offload_policy != OFFLOAD_NONE, plan.reasons
+
+
+def test_an_empty_cache_prices_the_release_from_its_table(l4):
+ plan = _plan(l4.target, MIRROR)
+ assert plan.estimates["model_dense_mib"] >= _table_total_mib(), plan.estimates
+ assert plan.offload_policy != OFFLOAD_NONE, plan.reasons
+
+
+def test_a_complete_cache_keeps_its_own_bytes(l4):
+ """A load whose cache already holds every component plans exactly from those bytes, as before."""
+ _snapshot(l4.hub, MIRROR, tuple(_MODELS), mib = 4)
+ plan = _plan(l4.target, MIRROR)
+ assert plan.estimates["model_dense_mib"] < 64, plan.estimates
+
+
+def test_a_finetune_with_a_partial_cache_keeps_its_own_bytes(l4):
+ _snapshot(l4.hub, FINETUNE, ("text_encoder", "text_encoder_2"), mib = 8)
+ plan = _plan(l4.target, FINETUNE, base = FINETUNE)
+ assert plan.estimates["model_dense_mib"] < 64, plan.estimates
+
+
+def test_floor_helper_contract():
+ fam = detect_family(UPSTREAM)
+ total = _table_total_mib()
+ floored = dmod._incomplete_release_cache_floor(fam, MIRROR, False, 9318, 9318, 9318)
+ assert floored is not None and floored[0] == total
+ assert floored[1] >= 9318 and floored[2] >= 9318
+ assert dmod._incomplete_release_cache_floor(fam, MIRROR, True, 9318, 9318, 9318) is None
+ assert dmod._incomplete_release_cache_floor(fam, FINETUNE, False, 9318, 9318, 9318) is None
+ assert dmod._incomplete_release_cache_floor(fam, None, False, None, None, None) is None