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
# SPDX-License-Identifier: AGPL-3.0-only
# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
"""SDXL fine-tunes named for no family (NoobAI-XL V-Pred, Illustrious) are detected from their own
model_index.json / checkpoint header, and load with the scheduler the checkpoint asks for.
Config-only fixtures: safetensors headers with empty tensors, no weights."""
from __future__ import annotations
import json
import struct
import types
from pathlib import Path
import pytest
import core.inference.diffusion_hub_evidence as evidence
from core.inference.diffusion_families import detect_family_for_pick
from core.inference.diffusion_sampler import (
checkpoint_prediction_overrides,
pipeline_prediction_overrides,
)
NOOB = "Laxhar/noobai-XL-Vpred-1.0"
NOOB_FILE = "NoobAI-XL-Vpred-v1.0.safetensors"
ILLU = "OnomaAIResearch/Illustrious-xl-early-release-v0"
ILLU_FILE = "Illustrious-XL-v0.1.safetensors"
SHA = "0123456789abcdef0123456789abcdef01234567"
# Laxhar/noobai-XL-Vpred-1.0 model_index.json (trimmed) and scheduler_config.json: the repo's
# diffusers scheduler says epsilon; only the root single file carries v_pred / ztsnr.
SDXL_INDEX = {
"_class_name": "StableDiffusionXLPipeline",
"scheduler": ["diffusers", "EulerDiscreteScheduler"],
"unet": ["diffusers", "UNet2DConditionModel"],
"text_encoder_2": ["transformers", "CLIPTextModelWithProjection"],
}
NOOB_SCHEDULER = dict(
beta_end = 0.012,
beta_schedule = "scaled_linear",
beta_start = 0.00085,
num_train_timesteps = 1000,
prediction_type = "epsilon",
rescale_betas_zero_snr = False,
steps_offset = 1,
timestep_spacing = "leading",
)
# The ComfyUI / original-SD layout of an SDXL checkpoint (label_emb = SDXL's ADM conditioning).
SDXL_UNET_KEYS = [
"model.diffusion_model.input_blocks.0.0.weight",
"model.diffusion_model.middle_block.0.in_layers.0.weight",
"model.diffusion_model.output_blocks.0.0.in_layers.0.weight",
"model.diffusion_model.label_emb.0.0.weight",
"model.diffusion_model.time_embed.0.weight",
"conditioner.embedders.1.model.transformer.resblocks.0.attn.in_proj_weight",
"first_stage_model.decoder.conv_in.weight",
]
SD15_UNET_KEYS = [
"model.diffusion_model.input_blocks.0.0.weight",
"model.diffusion_model.middle_block.0.in_layers.0.weight",
"model.diffusion_model.output_blocks.0.0.in_layers.0.weight",
"model.diffusion_model.time_embed.0.weight",
]
def _write_safetensors(path: Path, keys) -> Path:
header = {k: {"dtype": "F16", "shape": [0], "data_offsets": [0, 0]} for k in keys}
blob = json.dumps(header).encode()
path.parent.mkdir(parents = True, exist_ok = True)
path.write_bytes(struct.pack("<Q", len(blob)) + blob)
return path
@pytest.fixture(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."""
root = tmp_path / "hub"
root.mkdir()
import utils.hf_cache_settings as settings
monkeypatch.setattr(settings, "active_hf_hub_cache", lambda: str(root))
# The import-time root is the shared HF cache; these fake ids are never in it, but keep it out anyway.
import huggingface_hub
real = huggingface_hub.try_to_load_from_cache
def only_tmp(
repo_id,
filename,
cache_dir = None,
**kw,
):
return real(repo_id, filename, cache_dir = str(root), **kw)
monkeypatch.setattr(huggingface_hub, "try_to_load_from_cache", only_tmp)
evidence._HEADER_VERDICTS.clear()
def put(
repo_id: str,
filename: str,
*,
payload = None,
keys = None,
) -> Path:
repo_dir = root / ("models--" + repo_id.replace("/", "--"))
(repo_dir / "refs").mkdir(parents = True, exist_ok = True)
(repo_dir / "refs" / "main").write_text(SHA)
target = repo_dir / "snapshots" / SHA / filename
target.parent.mkdir(parents = True, exist_ok = True)
if keys is not None:
return _write_safetensors(target, keys)
target.write_text(json.dumps(payload))
return target
yield types.SimpleNamespace(root = root, put = put)
evidence._HEADER_VERDICTS.clear()
def _name(fam):
return fam.name if fam is not None else None
# ---- detection ---------------------------------------------------------------------------------
def test_a_cached_index_alone_is_not_evidence(hub_cache):
# The picked file's header is the evidence; a repo's model_index.json does not vouch for anything.
hub_cache.put(NOOB, "model_index.json", payload = SDXL_INDEX)
assert detect_family_for_pick(NOOB) is None
assert detect_family_for_pick(NOOB, NOOB_FILE) is None
def test_vpred_single_file_detected_from_cached_header(hub_cache):
path = hub_cache.put(NOOB, NOOB_FILE, keys = SDXL_UNET_KEYS + ["v_pred", "ztsnr"])
assert _name(detect_family_for_pick(NOOB, NOOB_FILE)) == "sdxl"
# ComfyUI supported_models.SDXL.model_type: v_pred -> V_PREDICTION, ztsnr -> zsnr sampling.
assert checkpoint_prediction_overrides(str(path)) == {
"prediction_type": "v_prediction",
"rescale_betas_zero_snr": True,
"timestep_spacing": "trailing",
}
def test_eps_sdxl_single_file_detected_and_left_epsilon(hub_cache):
path = hub_cache.put(ILLU, ILLU_FILE, keys = SDXL_UNET_KEYS)
assert _name(detect_family_for_pick(ILLU, ILLU_FILE)) == "sdxl"
assert checkpoint_prediction_overrides(str(path)) == {}
def test_checkpoint_header_outranks_the_repo_index(hub_cache):
hub_cache.put(NOOB, "model_index.json", payload = SDXL_INDEX)
hub_cache.put(NOOB, "sd15.safetensors", keys = SD15_UNET_KEYS)
assert detect_family_for_pick(NOOB, "sd15.safetensors") is None
def test_index_does_not_vouch_for_a_file_in_a_subfolder(hub_cache):
hub_cache.put(NOOB, "model_index.json", payload = SDXL_INDEX)
assert detect_family_for_pick(NOOB, "extras/other.safetensors") is None
def test_fetch_reads_header_then_detection_is_offline(hub_cache, monkeypatch):
import huggingface_hub
calls = []
def parse(
self,
repo_id,
filename,
token = None,
**kw,
):
calls.append((repo_id, filename))
tensors = {k: types.SimpleNamespace(shape = [0]) for k in SDXL_UNET_KEYS + ["v_pred"]}
return types.SimpleNamespace(tensors = tensors, metadata = {})
monkeypatch.setattr(huggingface_hub.HfApi, "parse_safetensors_file_metadata", parse)
monkeypatch.setattr(
huggingface_hub,
"hf_hub_download",
lambda *a, **k: pytest.fail("the header answered; no index fetch"),
)
assert detect_family_for_pick(NOOB, NOOB_FILE) is None
evidence.prefetch_for_pick(NOOB, NOOB_FILE, None, None)
assert calls == [(NOOB, NOOB_FILE)]
assert _name(detect_family_for_pick(NOOB, NOOB_FILE)) == "sdxl"
# Validation after the prefetch answers from the remembered header, with no further read.
assert _name(detect_family_for_pick(NOOB, NOOB_FILE)) == "sdxl"
assert calls == [(NOOB, NOOB_FILE)]
def test_a_pipeline_pick_makes_no_hub_call(hub_cache, monkeypatch):
import huggingface_hub
def boom(*a, **k):
raise AssertionError("a pipeline pick reads no evidence")
monkeypatch.setattr(huggingface_hub, "hf_hub_download", boom)
monkeypatch.setattr(huggingface_hub.HfApi, "parse_safetensors_file_metadata", boom)
evidence.prefetch_for_pick(NOOB, None, None, "hf_x")
assert detect_family_for_pick(NOOB) is None
def test_prefetch_is_skipped_for_named_overridden_local_and_gguf_picks(
hub_cache, monkeypatch, tmp_path
):
import huggingface_hub
def boom(*a, **k):
raise AssertionError("no network for this pick")
monkeypatch.setattr(huggingface_hub, "hf_hub_download", boom)
monkeypatch.setattr(huggingface_hub.HfApi, "parse_safetensors_file_metadata", boom)
evidence.prefetch_for_pick("stabilityai/stable-diffusion-xl-base-1.0", None, None, None)
evidence.prefetch_for_pick(NOOB, NOOB_FILE, "sdxl", None)
evidence.prefetch_for_pick(NOOB, "noob-Q4_K.gguf", None, None)
evidence.prefetch_for_pick(str(tmp_path), None, None, None)
def test_name_veto_is_not_overridden_by_the_header(hub_cache):
# The name matched SDXL and then refused the edit variant; a cached SDXL header must not undo that.
repo = "someone/neutral"
hub_cache.put(repo, "sdxl-edit.safetensors", keys = SDXL_UNET_KEYS)
assert detect_family_for_pick(repo, "sdxl-edit.safetensors") is None
def test_named_sdxl_repos_never_read_evidence(monkeypatch):
monkeypatch.setattr(
evidence, "cached_family", lambda *a, **k: pytest.fail("name already answered")
)
assert _name(detect_family_for_pick("stabilityai/stable-diffusion-xl-base-1.0")) == "sdxl"
assert _name(detect_family_for_pick("stabilityai/sdxl-turbo")) == "sdxl"
# ---- scheduler for a diffusers pipeline directory ----------------------------------------------
def _pipeline_dir(tmp_path: Path, scheduler: dict, root_singles: dict) -> Path:
root = tmp_path / "pipe"
(root / "scheduler").mkdir(parents = True)
(root / "model_index.json").write_text(json.dumps(SDXL_INDEX))
(root / "scheduler" / "scheduler_config.json").write_text(json.dumps(scheduler))
for name, keys in root_singles.items():
_write_safetensors(root / name, keys)
return root
def test_vpred_folder_with_eps_config_takes_the_root_file_markers(tmp_path):
root = _pipeline_dir(
tmp_path, NOOB_SCHEDULER, {NOOB_FILE: SDXL_UNET_KEYS + ["v_pred", "ztsnr"]}
)
assert pipeline_prediction_overrides(NOOB_SCHEDULER, str(root)) == {
"prediction_type": "v_prediction",
"rescale_betas_zero_snr": True,
"timestep_spacing": "trailing",
}
def test_eps_sdxl_folder_is_unchanged(tmp_path):
root = _pipeline_dir(tmp_path, NOOB_SCHEDULER, {ILLU_FILE: SDXL_UNET_KEYS})
assert pipeline_prediction_overrides(NOOB_SCHEDULER, str(root)) == {}
assert pipeline_prediction_overrides(NOOB_SCHEDULER, None) == {}
assert pipeline_prediction_overrides(NOOB_SCHEDULER, "stabilityai/sdxl-turbo") == {}
def test_disagreeing_root_files_keep_the_config(tmp_path):
root = _pipeline_dir(
tmp_path,
NOOB_SCHEDULER,
{"eps.safetensors": SDXL_UNET_KEYS, "vpred.safetensors": SDXL_UNET_KEYS + ["v_pred"]},
)
assert pipeline_prediction_overrides(NOOB_SCHEDULER, str(root)) == {}
def test_declared_vpred_zsnr_config_samples_the_terminal_timestep():
config = {**NOOB_SCHEDULER, "prediction_type": "v_prediction", "rescale_betas_zero_snr": True}
assert pipeline_prediction_overrides(config, None) == {"timestep_spacing": "trailing"}
assert pipeline_prediction_overrides({**config, "timestep_spacing": "trailing"}, None) == {}
# v-prediction without zero SNR is honoured as declared.
assert (
pipeline_prediction_overrides({**NOOB_SCHEDULER, "prediction_type": "v_prediction"}, None)
== {}
)
def test_apply_rebuilds_a_real_scheduler(tmp_path):
diffusers = pytest.importorskip("diffusers")
from core.inference.diffusion_sampler import apply_pipeline_prediction_type
root = _pipeline_dir(
tmp_path, NOOB_SCHEDULER, {NOOB_FILE: SDXL_UNET_KEYS + ["v_pred", "ztsnr"]}
)
pipe = types.SimpleNamespace(
scheduler = diffusers.EulerDiscreteScheduler.from_config(NOOB_SCHEDULER)
)
assert apply_pipeline_prediction_type(pipe, str(root)) is True
cfg = pipe.scheduler.config
assert (cfg.prediction_type, cfg.rescale_betas_zero_snr, cfg.timestep_spacing) == (
"v_prediction",
True,
"trailing",
)
pipe.scheduler.set_timesteps(25)
assert int(pipe.scheduler.timesteps[0]) == 999 # starts at the zero-SNR terminal step
assert apply_pipeline_prediction_type(pipe, str(root)) is False # idempotent
eps_root = _pipeline_dir(tmp_path / "eps", NOOB_SCHEDULER, {ILLU_FILE: SDXL_UNET_KEYS})
eps = types.SimpleNamespace(
scheduler = diffusers.EulerDiscreteScheduler.from_config(NOOB_SCHEDULER)
)
assert apply_pipeline_prediction_type(eps, str(eps_root)) is False
assert eps.scheduler.config.prediction_type == "epsilon"
SDXL_DIFFUSERS_UNET_ONLY_KEYS = [
"conv_in.weight",
"time_embedding.linear_1.weight",
"add_embedding.linear_1.weight",
"down_blocks.0.resnets.0.conv1.weight",
"mid_block.resnets.0.conv1.weight",
"up_blocks.0.resnets.0.conv1.weight",
]
def _stub_header(monkeypatch, keys_by_call):
import huggingface_hub
calls = []
def parse(
self,
repo_id,
filename,
token = None,
**kw,
):
keys = keys_by_call[min(len(calls), len(keys_by_call) - 1)]
calls.append((repo_id, filename))
return types.SimpleNamespace(
tensors = {k: types.SimpleNamespace(shape = [0]) for k in keys}, metadata = {}
)
monkeypatch.setattr(huggingface_hub.HfApi, "parse_safetensors_file_metadata", parse)
return calls
def test_catalog_identifies_whole_sdxl_files_by_content_even_when_names_are_neutral(monkeypatch):
from hub.routes.inventory import is_sdxl_checkpoint
keys = [
["transformer.single_transformer_blocks.0.attn.to_k.lora_A.weight"],
SDXL_DIFFUSERS_UNET_ONLY_KEYS,
SDXL_UNET_KEYS,
]
_stub_header(monkeypatch, keys)
picks = [
is_sdxl_checkpoint("example/checkpoint", filename, "1" * 40, False, "test-user")
for filename in ("edition-1.safetensors", "unet.safetensors", "edition-2.safetensors")
]
assert picks == [False, False, True]
def test_a_denoiser_only_unet_is_not_evidence_for_a_whole_pipeline_family(hub_cache, monkeypatch):
import huggingface_hub
_stub_header(monkeypatch, [SDXL_DIFFUSERS_UNET_ONLY_KEYS])
monkeypatch.setattr(
huggingface_hub, "hf_hub_download", lambda *a, **k: pytest.fail("header read")
)
evidence.prefetch_for_pick(NOOB, "unet.safetensors", None, None)
assert detect_family_for_pick(NOOB, "unet.safetensors") is None
hub_cache.put(ILLU, "unet.safetensors", keys = SDXL_DIFFUSERS_UNET_ONLY_KEYS)
assert detect_family_for_pick(ILLU, "unet.safetensors") is None
def test_each_prefetch_rereads_a_replaced_header(hub_cache, monkeypatch):
calls = _stub_header(monkeypatch, [SD15_UNET_KEYS, SDXL_UNET_KEYS + ["v_pred"]])
evidence.prefetch_for_pick(NOOB, NOOB_FILE, None, None)
assert detect_family_for_pick(NOOB, NOOB_FILE) is None
# The repo replaced the file with an SDXL checkpoint: the next request judges the new header.
evidence.prefetch_for_pick(NOOB, NOOB_FILE, None, None)
assert len(calls) == 2
assert _name(detect_family_for_pick(NOOB, NOOB_FILE)) == "sdxl"
def test_a_remembered_header_expires(hub_cache, monkeypatch):
_stub_header(monkeypatch, [SDXL_UNET_KEYS])
evidence.prefetch_for_pick(NOOB, NOOB_FILE, None, None)
assert _name(detect_family_for_pick(NOOB, NOOB_FILE)) == "sdxl"
now = evidence.time.monotonic()
monkeypatch.setattr(evidence.time, "monotonic", lambda: now + evidence._VERDICT_TTL_S + 1)
assert detect_family_for_pick(NOOB, NOOB_FILE) is None
def test_the_prefetch_writes_nothing_to_the_shared_cache(hub_cache, monkeypatch):
import huggingface_hub
monkeypatch.setattr(
huggingface_hub, "hf_hub_download", lambda *a, **k: pytest.fail("header range read only")
)
_stub_header(monkeypatch, [SDXL_UNET_KEYS])
evidence.prefetch_for_pick(NOOB, NOOB_FILE, None, "hf_private")
assert _name(detect_family_for_pick(NOOB, NOOB_FILE)) == "sdxl"
assert list(hub_cache.root.iterdir()) == []
def test_a_cache_only_prefetch_never_touches_the_hub(hub_cache, monkeypatch):
import huggingface_hub
def boom(*a, **k):
raise AssertionError("an automatic load is cache-only")
monkeypatch.setattr(huggingface_hub, "hf_hub_download", boom)
monkeypatch.setattr(huggingface_hub.HfApi, "parse_safetensors_file_metadata", boom)
evidence.prefetch_for_pick(NOOB, NOOB_FILE, None, None, allow_network = False)
evidence.prefetch_for_pick(NOOB, None, None, None, allow_network = False)
assert detect_family_for_pick(NOOB, NOOB_FILE) is None
def test_the_load_route_passes_user_initiated_to_the_prefetch():
import ast
source = (Path(__file__).resolve().parents[1] / "routes" / "inference.py").read_text(
encoding = "utf-8"
)
tree = ast.parse(source)
route = next(
n
for n in ast.walk(tree)
if isinstance(n, ast.AsyncFunctionDef) and n.name == "load_diffusion_model_gated"
)
calls = [
c
for c in ast.walk(route)
if isinstance(c, ast.Call)
and any(isinstance(a, ast.Name) and a.id == "prefetch_for_pick" for a in c.args)
]
assert len(calls) == 1
passed = [a.id for a in calls[0].args if isinstance(a, ast.Name)] + [
k.value.id for k in calls[0].keywords if isinstance(k.value, ast.Name)
]
assert "user_initiated" in passed
FLUX1_DEV_KEYS = [
"transformer_blocks.0.attn.to_q.weight",
"single_transformer_blocks.0.attn.to_q.weight",
"x_embedder.weight",
"context_embedder.weight",
"time_text_embed.timestep_embedder.linear_1.weight",
"time_text_embed.guidance_embedder.linear_1.weight",
]
def test_a_flux_dev_header_is_not_evidence_for_an_unnamed_pick(hub_cache, monkeypatch):
# FLUX.1 dev and schnell share one layout; resolved by family alone it would get schnell's base and defaults.
_stub_header(monkeypatch, [FLUX1_DEV_KEYS])
evidence.prefetch_for_pick("someone/neutral-ft", "model.safetensors", None, None)
assert detect_family_for_pick("someone/neutral-ft", "model.safetensors") is None
hub_cache.put("someone/cached-ft", "model.safetensors", keys = FLUX1_DEV_KEYS)
assert detect_family_for_pick("someone/cached-ft", "model.safetensors") is None
def test_a_transformer_family_index_is_not_evidence_for_an_unnamed_pick(hub_cache):
hub_cache.put(
"someone/neutral-pipe", "model_index.json", payload = {"_class_name": "FluxPipeline"}
)
assert detect_family_for_pick("someone/neutral-pipe") is None
def test_the_anonymous_token_sentinel_reaches_every_hub_call(hub_cache, monkeypatch):
import huggingface_hub
seen = []
def parse(
self,
repo_id,
filename,
token = None,
**kw,
):
seen.append(("header", token))
raise OSError("not a safetensors")
def size(
url,
token = None,
**kw,
):
seen.append(("size", token))
return types.SimpleNamespace(size = 400)
def download(
repo_id,
filename,
token = None,
cache_dir = None,
**kw,
):
seen.append(("download", token))
return str(hub_cache.put(repo_id, filename, payload = SDXL_INDEX))
monkeypatch.setattr(huggingface_hub.HfApi, "parse_safetensors_file_metadata", parse)
monkeypatch.setattr(huggingface_hub, "get_hf_file_metadata", size)
monkeypatch.setattr(huggingface_hub, "hf_hub_download", download)
evidence.prefetch_for_pick(NOOB, NOOB_FILE, None, False)
assert seen == [("header", False)]
def test_a_positive_verdict_is_reread_when_the_hub_file_changes(hub_cache, monkeypatch):
calls = _stub_header(monkeypatch, [SDXL_UNET_KEYS, SD15_UNET_KEYS])
evidence.prefetch_for_pick(NOOB, NOOB_FILE, None, None)
assert _name(detect_family_for_pick(NOOB, NOOB_FILE)) == "sdxl"
# The repo replaced the SDXL checkpoint with an SD 1.5 one: the next request must see it.
evidence.prefetch_for_pick(NOOB, NOOB_FILE, None, None)
assert len(calls) == 2
assert detect_family_for_pick(NOOB, NOOB_FILE) is None
def test_a_cached_copy_is_rechecked_against_the_current_hub_header(hub_cache, monkeypatch):
hub_cache.put(NOOB, NOOB_FILE, keys = SDXL_UNET_KEYS)
assert _name(detect_family_for_pick(NOOB, NOOB_FILE)) == "sdxl"
calls = _stub_header(monkeypatch, [SD15_UNET_KEYS])
evidence.prefetch_for_pick(NOOB, NOOB_FILE, None, None)
assert len(calls) == 1
assert detect_family_for_pick(NOOB, NOOB_FILE) is None
def test_a_named_pick_never_reads_hub_evidence(hub_cache, monkeypatch):
calls = _stub_header(monkeypatch, [SDXL_UNET_KEYS])
evidence.prefetch_for_pick("someone/my-sdxl-ft", "model.safetensors", None, None)
assert calls == []
def test_root_single_file_extensions_match_case_insensitively(tmp_path):
root = _pipeline_dir(
tmp_path,
NOOB_SCHEDULER,
{"NOOBAI-XL-VPRED.SAFETENSORS": SDXL_UNET_KEYS + ["v_pred", "ztsnr"]},
)
assert pipeline_prediction_overrides(NOOB_SCHEDULER, str(root)) == {
"prediction_type": "v_prediction",
"rescale_betas_zero_snr": True,
"timestep_spacing": "trailing",
}
def test_a_staged_pipeline_snapshot_reads_the_root_markers_off_the_hub(tmp_path, monkeypatch):
import huggingface_hub
# The staged snapshot keeps only model_index.json at its root; the packaged single file stays on the Hub.
root = _pipeline_dir(tmp_path, NOOB_SCHEDULER, {})
seen = []
def files(
self,
repo_id,
token = None,
**kw,
):
seen.append(("list", repo_id, token))
return ["model_index.json", NOOB_FILE, "unet/diffusion_pytorch_model.safetensors"]
def parse(
self,
repo_id,
filename,
token = None,
**kw,
):
seen.append(("header", filename, token))
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)
want = {
"prediction_type": "v_prediction",
"rescale_betas_zero_snr": True,
"timestep_spacing": "trailing",
}
assert pipeline_prediction_overrides(NOOB_SCHEDULER, str(root), NOOB, "hf_x", True) == want
assert seen == [("list", NOOB, "hf_x"), ("header", NOOB_FILE, "hf_x")]
# A cache-only load never reaches the Hub; the shipped config stands.
seen.clear()
assert pipeline_prediction_overrides(NOOB_SCHEDULER, str(root), NOOB, None, False) == {}
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) == {}
# A commit is immutable: a later online load of the same snapshot answers from the record, no Hub call.
seen = []
_stub_noob_hub(monkeypatch, SDXL_UNET_KEYS, seen)
assert pipeline_prediction_overrides(NOOB_SCHEDULER, str(snap), NOOB, None, True) == VPRED
assert seen == []
# A re-release is a new commit: read online, recorded under its own key.
newer = _staged_snapshot(hub_cache, commit = "e" * 40)
assert pipeline_prediction_overrides(NOOB_SCHEDULER, str(newer), NOOB, None, True) == {}
assert seen == ["list", "header"]
assert pipeline_prediction_overrides(NOOB_SCHEDULER, str(newer), 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
source = (
Path(__file__).resolve().parents[1] / "core" / "inference" / "diffusion.py"
).read_text(encoding = "utf-8")
calls = [
c
for c in ast.walk(ast.parse(source))
if isinstance(c, ast.Call)
and getattr(c.func, "id", None) == "apply_pipeline_prediction_type"
]
assert len(calls) == 1
assert {k.arg for k in calls[0].keywords} >= {"repo_id", "hf_token", "allow_network"}
@pytest.mark.parametrize(
"repo, filename",
[
("someone/neutral-inpaint", "model.safetensors"),
("someone/neutral-ft", "model-inpainting-edit.safetensors"),
("someone/neutral-ft", "inpaint/model.safetensors"),
],
)
def test_a_variant_named_pick_is_not_answered_from_its_header(hub_cache, repo, filename):
hub_cache.put(repo, filename, keys = SDXL_UNET_KEYS)
assert detect_family_for_pick(repo, filename) is None
def test_a_refresh_keeps_the_last_verdict_visible(hub_cache, monkeypatch):
import huggingface_hub
_stub_header(monkeypatch, [SDXL_UNET_KEYS])
evidence.prefetch_for_pick(NOOB, NOOB_FILE, None, None)
during = []
def parse(
self,
repo_id,
filename,
token = None,
**kw,
):
# An overlapping request validating while this refresh reads the header.
during.append(_name(detect_family_for_pick(NOOB, NOOB_FILE)))
raise OSError("offline")
monkeypatch.setattr(huggingface_hub.HfApi, "parse_safetensors_file_metadata", parse)
evidence.prefetch_for_pick(NOOB, NOOB_FILE, None, None)
assert during == ["sdxl"]
# A failed refresh keeps the last good read rather than forgetting it.
assert _name(detect_family_for_pick(NOOB, NOOB_FILE)) == "sdxl"
@pytest.mark.parametrize("given, sent", [(False, False), (" hf_x ", "hf_x"), ("", None)])
def test_the_pipeline_marker_probe_keeps_the_anonymous_sentinel(tmp_path, monkeypatch, given, sent):
import huggingface_hub
root = _pipeline_dir(tmp_path, NOOB_SCHEDULER, {})
seen = []
def files(
self,
repo_id,
token = None,
**kw,
):
seen.append(token)
return [NOOB_FILE]
def parse(
self,
repo_id,
filename,
token = None,
**kw,
):
seen.append(token)
return types.SimpleNamespace(tensors = {"v_pred": None}, metadata = {})
monkeypatch.setattr(huggingface_hub.HfApi, "list_repo_files", files)
monkeypatch.setattr(huggingface_hub.HfApi, "parse_safetensors_file_metadata", parse)
pipeline_prediction_overrides(NOOB_SCHEDULER, str(root), NOOB, given, True)
assert seen == [sent, sent]
def test_the_load_hands_the_uncollapsed_token_to_the_marker_probe():
import ast
source = (
Path(__file__).resolve().parents[1] / "core" / "inference" / "diffusion.py"
).read_text(encoding = "utf-8")
tree = ast.parse(source)
methods = {
n.name: n
for n in ast.walk(tree)
if isinstance(n, ast.FunctionDef) and n.name in ("begin_load", "load_pipeline")
}
# begin_load forwards normalize_token(hf_token) to the worker before collapsing hf_token.
begin = methods["begin_load"]
assigns = [
a
for a in ast.walk(begin)
if isinstance(a, ast.Assign)
and any(isinstance(t, ast.Name) and t.id == "hub_token" for t in a.targets)
]
assert assigns and isinstance(assigns[0].value, ast.Call)
assert getattr(assigns[0].value.func, "id", None) == "normalize_token"
assert any(isinstance(k, ast.keyword) and k.arg == "_hub_token" for k in ast.walk(begin))
# load_pipeline accepts it and the marker probe receives it, never the collapsed hf_token.
load = methods["load_pipeline"]
assert "_hub_token" in {a.arg for a in load.args.kwonlyargs}
probe = [
c
for c in ast.walk(load)
if isinstance(c, ast.Call)
and getattr(c.func, "id", None) == "apply_pipeline_prediction_type"
]
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]
@pytest.mark.parametrize("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)
def test_the_root_headers_are_read_side_by_side_in_name_order(hub_cache, monkeypatch):
import threading
import time
import huggingface_hub
snap = _staged_snapshot(hub_cache)
names = ["a.safetensors", "b.safetensors", "c.safetensors"]
active, peak = [0], [0]
lock = threading.Lock()
def files(
self,
repo_id,
token = None,
**kw,
):
return ["model_index.json", *names]
def parse(
self,
repo_id,
filename,
token = None,
**kw,
):
with lock:
active[0] += 1
peak[0] = max(peak[0], active[0])
time.sleep(0.2)
with lock:
active[0] -= 1
keys = ["v_pred", "ztsnr"] if filename == "c.safetensors" else []
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)
from core.inference import diffusion_sampler as smp
marks = smp._root_single_marks(str(snap), NOOB, None, True)
assert peak[0] > 1
# Results stay in name order: only the last file carries the markers.
assert [bool(m) for m in marks] == [False, False, True]
def test_the_overlapped_marker_read_matches_the_inline_one(hub_cache, monkeypatch):
diffusers = pytest.importorskip("diffusers")
from core.inference import diffusion_sampler as smp
snap = _staged_snapshot(hub_cache)
seen = []
_stub_noob_hub(monkeypatch, SDXL_UNET_KEYS + ["v_pred", "ztsnr"], seen)
future = smp.start_root_single_marks(str(snap), NOOB, None, True)
pipe = types.SimpleNamespace(
scheduler = diffusers.EulerDiscreteScheduler.from_config(NOOB_SCHEDULER)
)
assert smp.apply_pipeline_prediction_type(
pipe, str(snap), repo_id = NOOB, allow_network = True, marks_future = future
)
assert seen == ["list", "header"]
assert pipe.scheduler.config.prediction_type == "v_prediction"
def test_a_failed_overlapped_read_is_read_again_inline(hub_cache, monkeypatch):
from concurrent.futures import Future
diffusers = pytest.importorskip("diffusers")
from core.inference import diffusion_sampler as smp
snap = _staged_snapshot(hub_cache)
seen = []
_stub_noob_hub(monkeypatch, SDXL_UNET_KEYS + ["v_pred", "ztsnr"], seen)
failed: Future = Future()
failed.set_exception(RuntimeError("thread died"))
pipe = types.SimpleNamespace(
scheduler = diffusers.EulerDiscreteScheduler.from_config(NOOB_SCHEDULER)
)
assert smp.apply_pipeline_prediction_type(
pipe, str(snap), repo_id = NOOB, allow_network = True, marks_future = failed
)
assert seen == ["list", "header"]
def test_the_load_starts_the_marker_read_before_the_weights():
import ast
source = (
Path(__file__).resolve().parents[1] / "core" / "inference" / "diffusion.py"
).read_text(encoding = "utf-8")
tree = ast.parse(source)
starts = [
c.lineno
for c in ast.walk(tree)
if isinstance(c, ast.Call) and getattr(c.func, "id", None) == "start_root_single_marks"
]
loads = [
c.lineno
for c in ast.walk(tree)
if isinstance(c, ast.Call)
and isinstance(c.func, ast.Attribute)
and c.func.attr == "from_pretrained"
and getattr(c.func.value, "id", None) == "pipeline_cls"
]
applies = [
c
for c in ast.walk(tree)
if isinstance(c, ast.Call)
and getattr(c.func, "id", None) == "apply_pipeline_prediction_type"
]
assert len(starts) == 1 and any(starts[0] < line < starts[0] + 20 for line in loads)
assert "marks_future" in {k.arg for k in applies[0].keywords}
def test_the_marker_read_overlaps_only_a_staged_snapshot():
# A Hub id resolves its revision inside from_pretrained: an early read could take refs/main's older commit while
# the load downloads a newer one, so the overlap is gated on the staged, commit-pinned snapshot dir.
import ast
source = (
Path(__file__).resolve().parents[1] / "core" / "inference" / "diffusion.py"
).read_text(encoding = "utf-8")
tree = ast.parse(source)
calls = [
node
for node in ast.walk(tree)
if isinstance(node, ast.IfExp)
and isinstance(node.body, ast.Call)
and getattr(node.body.func, "id", None) == "start_root_single_marks"
]
assert len(calls) == 1
gate = ast.unparse(calls[0].test)
assert "_base_local_dir" in gate
first = calls[0].body.args[0]
assert ast.unparse(first) == "_base_local_dir"
def test_a_managed_account_reads_checkpoint_headers_without_the_installation_token(monkeypatch):
import huggingface_hub
from fastapi import HTTPException
from hub.routes import inventory
from hub.services.models import account_access
tokens = []
def parse(
self,
repo_id,
filename,
token = None,
**kw,
):
tokens.append(token)
return types.SimpleNamespace(
tensors = {k: types.SimpleNamespace(shape = [0]) for k in SDXL_UNET_KEYS},
metadata = {},
)
monkeypatch.setattr(huggingface_hub.HfApi, "parse_safetensors_file_metadata", parse)
for managed in (False, True):
monkeypatch.setattr(account_access, "managed_account", lambda managed = managed: managed)
assert inventory.is_sdxl_checkpoint("example/ckpt", "a.safetensors", None, None, "u")
assert tokens == [None, False]
monkeypatch.setattr(account_access, "model_allowlist", lambda: ["allowed/*"])
with pytest.raises(HTTPException):
inventory.is_sdxl_checkpoint("example/ckpt", "a.safetensors", None, None, "u")
assert len(tokens) == 2
def test_the_catalog_never_offers_a_checkpoint_the_loader_vetoes_by_name(monkeypatch):
from core.inference.diffusion import get_diffusion_backend
from hub.routes.inventory import is_sdxl_checkpoint
_stub_header(monkeypatch, [SDXL_UNET_KEYS])
repo = "example/neutral-mix"
assert is_sdxl_checkpoint(repo, "edition.safetensors", None, False, "u")
assert not is_sdxl_checkpoint(repo, "edition-inpaint.safetensors", None, False, "u")
get_diffusion_backend().validate_load_request(
repo, gguf_filename = "edition.safetensors", family_override = None, model_kind = "single_file"
)