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 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.pyindex 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_dirthrough 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+@staticmethoddef _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 = Falseif 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.pynew file mode 100644index 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