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: rebuild an image / video GGUF from the cached copy when only its header changed (#12928)
Daniel Haneb5ae46aa9f4
diff --git a/studio/backend/core/inference/diffusion.py b/studio/backend/core/inference/diffusion.pyindex cbd22bd0ee1..be678e65c4f 100644--- a/studio/backend/core/inference/diffusion.py+++ b/studio/backend/core/inference/diffusion.py@@ -2929,6 +2929,7 @@ class DiffusionBackend:cancel_event = cancel,reuse_other_cache_root = True,local_files_only = local_files_only,+ gguf_header_delta = True,)# Base repo (VAE / text-encoder / scheduler); list comes from the estimate.snapshot_root: Optional[str] = Nonediff --git a/studio/backend/core/inference/sd_cpp_backend.py b/studio/backend/core/inference/sd_cpp_backend.pyindex 2e1936f29f3..8dce6805d9f 100644--- a/studio/backend/core/inference/sd_cpp_backend.py+++ b/studio/backend/core/inference/sd_cpp_backend.py@@ -3542,6 +3542,7 @@ class SdCppDiffusionBackend:cancel_event = cancel,reuse_other_cache_root = True,local_files_only = local_files_only,+ gguf_header_delta = True,)except _local_entry_not_found_error() as exc:# Raised by huggingface_hub for exactly "not cached and outgoing traffic is disabled", so it candiff --git a/studio/backend/core/inference/video.py b/studio/backend/core/inference/video.pyindex 6773b720184..3463f16cf57 100644--- a/studio/backend/core/inference/video.py+++ b/studio/backend/core/inference/video.py@@ -3168,6 +3168,7 @@ class VideoBackend:# An API-initiated load takes the cached checkpoint or fails; it never pulls the multi-GB file# itself.local_files_only = local_files_only,+ gguf_header_delta = True,))# An LTX-2.3 checkpoint supplies the VAEs/vocoder/connectors, so the base pull shrinks to scheduler + TE +@@ -3578,6 +3579,7 @@ class VideoBackend:cancel_event = cancel_event,reuse_other_cache_root = True,local_files_only = local_files_only,+ gguf_header_delta = True,))except Exception as exc: # noqa: BLE001 -- re-raised below, narrowed by name@@ -8287,6 +8289,7 @@ class VideoBackend:hf_token,reuse_other_cache_root = True,local_files_only = local_files_only,+ gguf_header_delta = True,))diff --git a/studio/backend/core/inference/video_ltx2.py b/studio/backend/core/inference/video_ltx2.pyindex 804afea2b31..dbe514fe479 100644--- a/studio/backend/core/inference/video_ltx2.py+++ b/studio/backend/core/inference/video_ltx2.py@@ -607,6 +607,7 @@ def _load_extras_file(reuse_other_cache_root = True,# the switch's locality gate cleared these three artifacts by namelocal_files_only = local_files_only,+ gguf_header_delta = True,)return load_file(path)diff --git a/studio/backend/core/inference/video_minimax_h3_te.py b/studio/backend/core/inference/video_minimax_h3_te.pyindex e6c792b03c9..8be23e5a58a 100644--- a/studio/backend/core/inference/video_minimax_h3_te.py+++ b/studio/backend/core/inference/video_minimax_h3_te.py@@ -345,6 +345,7 @@ def load_h3_quantized_text_encoder(# pinned to cache_dir alone a moved cache folder re-pulls 27 GB.reuse_other_cache_root = True,local_files_only = local_files_only,+ gguf_header_delta = True,)config = transformers.AutoConfig.from_pretrained(diff --git a/studio/backend/hub/utils/gguf_header_delta.py b/studio/backend/hub/utils/gguf_header_delta.pynew file mode 100644index 00000000000..b2c08cd0736--- /dev/null+++ b/studio/backend/hub/utils/gguf_header_delta.py@@ -0,0 +1,574 @@+# SPDX-License-Identifier: AGPL-3.0-only+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0++"""Rebuild a republished image / video GGUF from the cached older copy when only its header changed.++A metadata fix (an architecture label, a new KV) rewrites the GGUF header and leaves every tensor byte alone, but the+file's sha256 changes, so huggingface_hub downloads the whole file again. Here the new header is fetched with a Range+request, its tensor table is checked against the cached copy's, and the new file is written as the new header plus the+cached copy's tensor data, hashed in the same pass. It is kept only when its sha256 equals the Hub's.++Opt-in (Images / Video loads, and image / video GGUFs in the download manager). No network unless the file for the+target commit is missing AND an older snapshot holds the same path; anything unproven falls back to the normal+download, and nothing here raises."""++from __future__ import annotations++import glob+import hashlib+import json+import os+import re+import shutil+import struct+import threading+import time+import uuid+from dataclasses import dataclass+from pathlib import Path+from typing import Callable, Optional++from loggers import get_logger++logger = get_logger(__name__)++DELTA_ENV = "UNSLOTH_GGUF_HEADER_DELTA"+_SHA256 = re.compile(r"^[0-9a-f]{64}$")+_COMMIT = re.compile(r"^[0-9a-f]{40}$")+_GGUF_MAGIC = b"GGUF"+# The first Range asks for the cached header's size plus this, so a header that only gained a few KVs takes one request.+_HEADER_SLACK = 64 << 10+_FIRST_RANGE = 64 << 10+# Text encoder GGUFs carry a tokenizer (tens of MB); past this a full download is the better deal.+_MAX_HEADER_BYTES = 256 << 20+_COPY_CHUNK = 16 << 20+_DISK_MARGIN = 256 << 20+_METADATA_TIMEOUT = 10.0+_RANGE_TIMEOUT = 60.0+# "image-diffusion-unsupported" is an image / video family this install cannot run yet; still rebuilt.+_MEDIA_TASKS = frozenset({"text-to-image", "text-to-video", "image-diffusion-unsupported"})++_SCALAR_SIZES = {0: 1, 1: 1, 2: 2, 3: 2, 4: 4, 5: 4, 6: 4, 7: 1, 10: 8, 11: 8, 12: 8}+_STRING, _ARRAY, _UINT32 = 8, 9, 4++FetchRange = Callable[[int, int], bytes]++# Refused (repo cache dir, path, new sha256), persisted under Studio's state dir so a restart does not retry them.+_REFUSED_FILE = "gguf_header_delta_refused.json"+_REFUSED_LIMIT = 512+_refused: Optional[list] = None+_refused_lock = threading.Lock()+++class _NeedMore(Exception):+ pass+++@dataclass(frozen = True)+class GgufLayout:+ data_offset: int+ # (name, dims, ggml type, offset relative to the data section), in file order.+ tensors: tuple+++@dataclass(frozen = True)+class DeltaResult:+ placed: bool = False+ fetched_bytes: int = 0+ size: int = 0+ reason: str = ""+ decide_s: float = 0.0+ build_s: float = 0.0+++def delta_enabled() -> bool:+ return (os.environ.get(DELTA_ENV) or "").strip().lower() not in ("0", "off", "false", "no")+++def parse_gguf_layout(buf: bytes) -> GgufLayout:+ """Tensor table and data offset of a GGUF v2/v3 header held in ``buf``. Raises ``_NeedMore`` when ``buf`` ends+ inside the header (the data offset itself may lie past it), ``ValueError`` when it is not a GGUF this can read."""+ pos = 0++ def take(n: int) -> bytes:+ nonlocal pos+ if pos + n > len(buf):+ raise _NeedMore()+ out = buf[pos : pos + n]+ pos += n+ return out++ def u32() -> int:+ return struct.unpack("<I", take(4))[0]++ def u64() -> int:+ return struct.unpack("<Q", take(8))[0]++ def string() -> bytes:+ n = u64()+ if n > (1 << 30):+ raise ValueError("implausible string length")+ return take(n)++ def skip_value(vtype: int) -> None:+ if vtype in _SCALAR_SIZES:+ take(_SCALAR_SIZES[vtype])+ elif vtype == _STRING:+ string()+ elif vtype == _ARRAY:+ item = u32()+ count = u64()+ if item in _SCALAR_SIZES:+ take(_SCALAR_SIZES[item] * count)+ elif item == _STRING:+ for _ in range(count):+ string()+ else:+ # Nested arrays are legal but no published GGUF writes them; not worth a reader here.+ raise ValueError(f"unsupported array item type {item}")+ else:+ raise ValueError(f"unknown value type {vtype}")++ if take(4) != _GGUF_MAGIC:+ raise ValueError("not a GGUF")+ version = u32()+ if version not in (2, 3):+ raise ValueError(f"unsupported GGUF version {version}")+ n_tensors = u64()+ n_kv = u64()+ if n_tensors > 10_000_000 or n_kv > 10_000_000:+ raise ValueError("implausible header counts")+ alignment = 32+ for _ in range(n_kv):+ key = string()+ vtype = u32()+ if key == b"general.alignment" and vtype == _UINT32:+ alignment = u32()+ else:+ skip_value(vtype)+ if alignment <= 0 or alignment & (alignment - 1):+ raise ValueError(f"bad alignment {alignment}")+ tensors = []+ for _ in range(n_tensors):+ name = string()+ n_dims = u32()+ if n_dims > 16:+ raise ValueError("implausible tensor rank")+ dims = tuple(u64() for _ in range(n_dims))+ ggml_type = u32()+ offset = u64()+ tensors.append((name, dims, ggml_type, offset))+ data_offset = -(-pos // alignment) * alignment+ return GgufLayout(data_offset, tuple(tensors))+++def _layout_of_local(path: Path, cap: int) -> GgufLayout:+ want = _FIRST_RANGE+ with open(path, "rb") as f:+ while True:+ f.seek(0)+ buf = f.read(want)+ try:+ return parse_gguf_layout(buf)+ except _NeedMore:+ if len(buf) < want or want >= cap:+ raise ValueError("cached GGUF header unreadable within the cap")+ want = min(want * 2, cap)+++def _layout_of_remote(+ fetch: FetchRange, size: int, cap: int, first: int+) -> tuple[GgufLayout, bytes]:+ """Layout plus the new file's bytes up to its data offset. One Range of ``first`` bytes, grown only if the header+ turns out longer."""+ buf = b""+ want = min(max(first, 1), size, cap)+ while True:+ if want > len(buf):+ part = fetch(len(buf), want - 1)+ if len(part) != want - len(buf):+ raise ValueError("short range response")+ buf += part+ try:+ layout = parse_gguf_layout(buf)+ except _NeedMore:+ if want >= min(cap, size):+ raise ValueError("new GGUF header larger than the fetch cap")+ want = min(want * 2, cap, size)+ continue+ if layout.data_offset > len(buf):+ if layout.data_offset > min(cap, size):+ raise ValueError("new GGUF header larger than the fetch cap")+ part = fetch(len(buf), layout.data_offset - 1)+ if len(part) != layout.data_offset - len(buf):+ raise ValueError("short range response")+ buf += part+ return layout, buf[: layout.data_offset]+++def _other_snapshot_copies(repo_dir: Path, commit: str, rel_path: str) -> list[Path]:+ """Copies of ``rel_path`` in snapshots other than ``commit``, newest first. Local only."""+ try:+ snaps = [p for p in (repo_dir / "snapshots").iterdir() if p.is_dir() and p.name != commit]+ except OSError:+ return []+ out = [snap / rel_path for snap in snaps if os.path.isfile(snap / rel_path)]+ if len(out) > 1:+ from hub.utils.hf_cache_state import snapshot_selection_key+ out.sort(key = lambda p: snapshot_selection_key(p.parent), reverse = True)+ return out+++def _refused_path() -> Optional[Path]:+ try:+ from hub.utils.state_dir import state_root+ root = state_root(create = True)+ except Exception: # noqa: BLE001 - no state dir: the memo stays in memory+ return None+ return None if root is None else root / _REFUSED_FILE+++def _refused_keys() -> list:+ global _refused+ if _refused is None:+ _refused = []+ path = _refused_path()+ if path is not None:+ try:+ data = json.loads(path.read_text(encoding = "utf-8"))+ if isinstance(data, list):+ _refused = [k for k in data if isinstance(k, str)][-_REFUSED_LIMIT:]+ except (OSError, ValueError):+ pass+ return _refused+++def _refused_key(repo_dir: Path, rel_path: str, digest: str) -> str:+ return "|".join((os.path.normcase(os.path.abspath(str(repo_dir))), rel_path, digest))+++def _refuse(repo_dir: Path, rel_path: str, digest: str) -> None:+ key = _refused_key(repo_dir, rel_path, digest)+ with _refused_lock:+ keys = _refused_keys()+ if key in keys:+ return+ keys.append(key)+ del keys[:-_REFUSED_LIMIT]+ path = _refused_path()+ if path is None:+ return+ tmp = path.with_name(f".{path.name}.tmp-{uuid.uuid4().hex[:8]}")+ try:+ tmp.write_text(json.dumps(keys), encoding = "utf-8")+ os.replace(tmp, path)+ except OSError as exc:+ logger.debug("could not persist the gguf header delta memo: %s", exc)+ try:+ tmp.unlink()+ except OSError:+ pass+++def _was_refused(repo_dir: Path, rel_path: str, digest: str) -> bool:+ with _refused_lock:+ return _refused_key(repo_dir, rel_path, digest) in _refused_keys()+++def _lock_path(repo_dir: Path, digest: str) -> Path:+ return repo_dir.parent / ".locks" / repo_dir.name / f"{digest}.lock"+++def _is_media_gguf(path: Path, repo_id: str, rel_path: str) -> bool:+ """Whether Studio lists this GGUF for the Images or Video page (header + name, as the catalog does)."""+ try:+ from hub.services.models.catalog_classification import _gguf_file_task+ return _gguf_file_task(path, (repo_id, rel_path)) in _MEDIA_TASKS+ except Exception: # noqa: BLE001 - unclassifiable is not a media model+ return False+++def _build(+ old_path: Path,+ old_data_offset: int,+ prefix: bytes,+ tmp: Path,+ size: int,+ digest: str,+ cancel_event: Optional[threading.Event],+) -> bool:+ """Write prefix + the old tensor data to ``tmp`` and check the sha256 in the same pass."""+ h = hashlib.sha256(prefix)+ written = len(prefix)+ with open(tmp, "wb") as out, open(old_path, "rb") as src:+ out.write(prefix)+ src.seek(old_data_offset)+ while True:+ if cancel_event is not None and cancel_event.is_set():+ return False+ chunk = src.read(_COPY_CHUNK)+ if not chunk:+ break+ out.write(chunk)+ h.update(chunk)+ written += len(chunk)+ if written > size:+ return False+ return written == size and h.hexdigest() == digest+++def rebuild_from_older_snapshot(+ repo_dir: Path,+ commit: str,+ rel_path: str,+ size: int,+ digest: str,+ fetch: FetchRange,+ *,+ protected_blob_hashes: frozenset = frozenset(),+ cancel_event: Optional[threading.Event] = None,+ media_gate: Optional[Callable[[Path], bool]] = None,+) -> DeltaResult:+ """Place ``rel_path`` at ``commit`` (blob + pointer, in the cache's own layout) from an older snapshot's copy when+ only the header differs. ``media_gate`` (old copy -> bool) restricts it to some files. Never raises; ``placed``+ False means use the normal download."""+ t0 = time.perf_counter()+ tmp: Optional[Path] = None+ fetched = 0+ decided = 0.0++ def done(+ reason: str,+ placed: bool = False,+ build_s: float = 0.0,+ ) -> DeltaResult:+ return DeltaResult(+ placed,+ fetched,+ size,+ reason,+ decided or time.perf_counter() - t0,+ build_s,+ )++ try:+ if not delta_enabled():+ return done("disabled")+ if not rel_path.lower().endswith(".gguf") or not _SHA256.match(digest or "") or size <= 0:+ return done("not a sha256-addressed GGUF")+ if digest in protected_blob_hashes:+ return done("blob protected")+ pointer = repo_dir / "snapshots" / commit / rel_path+ blob = repo_dir / "blobs" / digest+ if os.path.lexists(pointer) or os.path.exists(blob):+ return done("already cached")+ olds = _other_snapshot_copies(repo_dir, commit, rel_path)+ if not olds:+ return done("no older copy")+ if _was_refused(repo_dir, rel_path, digest):+ return done("refused before")+ if media_gate is not None and not media_gate(olds[0]):+ return done("not an image / video GGUF")+ cap = min(_MAX_HEADER_BYTES, max(size // 4, _FIRST_RANGE))+ local = []+ for candidate in olds:+ try:+ local.append(+ (candidate, os.path.getsize(candidate), _layout_of_local(candidate, cap))+ )+ except (OSError, ValueError):+ continue+ if not local:+ _refuse(repo_dir, rel_path, digest)+ return done("cached copy unreadable")++ def counted_fetch(start: int, end: int) -> bytes:+ nonlocal fetched+ data = fetch(start, end)+ fetched += len(data)+ return data++ layout, prefix = _layout_of_remote(+ counted_fetch, size, cap, local[0][2].data_offset + _HEADER_SLACK+ )+ data_len = size - layout.data_offset+ old = next(+ (+ (path, old_layout)+ for path, old_size, old_layout in local+ if old_size - old_layout.data_offset == data_len+ and old_layout.tensors == layout.tensors+ ),+ None,+ )+ if old is None:+ _refuse(repo_dir, rel_path, digest)+ return done("tensor table differs")+ decided = time.perf_counter() - t0+ old_path, old_layout = old+ symlinked = os.path.islink(old_path)+ stage_dir = (repo_dir / "blobs") if symlinked else pointer.parent+ stage_dir.mkdir(parents = True, exist_ok = True)+ if shutil.disk_usage(stage_dir).free < size + _DISK_MARGIN:+ return done("not enough disk")+ from filelock import FileLock, Timeout++ lock = _lock_path(repo_dir, digest)+ lock.parent.mkdir(parents = True, exist_ok = True)+ t_build = time.perf_counter()+ try:+ with FileLock(str(lock), timeout = 0):+ for stale in stage_dir.glob(f".{glob.escape(digest)}.delta-*"):+ try:+ stale.unlink()+ except OSError:+ pass+ tmp = stage_dir / f".{digest}.delta-{os.getpid()}-{uuid.uuid4().hex[:8]}"+ if not _build(+ old_path, old_layout.data_offset, prefix, tmp, size, digest, cancel_event+ ):+ if cancel_event is None or not cancel_event.is_set():+ _refuse(repo_dir, rel_path, digest)+ return done("sha256 mismatch", build_s = time.perf_counter() - t_build)+ if os.path.lexists(pointer) or os.path.exists(blob):+ return done("raced")+ pointer.parent.mkdir(parents = True, exist_ok = True)+ if symlinked:+ os.replace(tmp, blob)+ tmp = None+ from huggingface_hub.file_download import _create_symlink++ _create_symlink(str(blob), str(pointer), new_blob = False)+ else:+ # No-symlink cache: huggingface_hub keeps the file under the snapshot and blobs/ empty.+ os.replace(tmp, pointer)+ tmp = None+ except Timeout:+ return done("blob locked")+ build_s = time.perf_counter() - t_build+ logger.info(+ "gguf header delta: rebuilt %s from the cached copy, fetched %.2f MB of %.2f GB "+ "(decided in %.2f s, written in %.1f s)",+ rel_path,+ fetched / 1e6,+ size / 1e9,+ decided,+ build_s,+ )+ return done("rebuilt", True, build_s)+ except Exception as exc: # noqa: BLE001 - an optimisation only: the normal download follows+ logger.info("gguf header delta skipped for %s: %s", rel_path, exc)+ return done(f"error: {exc}")+ finally:+ if tmp is not None:+ try:+ os.unlink(tmp)+ except OSError:+ pass+++def hub_range_fetcher(+ repo_id: str,+ filename: str,+ token,+ *,+ repo_type: str = "model",+ revision: Optional[str] = None,+) -> FetchRange:+ """Range GETs on the file's resolve URL, authenticated like huggingface_hub's own downloads. A server that ignores+ Range (status 200) is refused before its body is read."""+ from huggingface_hub import hf_hub_url+ from huggingface_hub.utils import build_hf_headers, get_session++ url = hf_hub_url(repo_id, filename, repo_type = repo_type, revision = revision)+ base_headers = build_hf_headers(token = token)++ def fetch(start: int, end: int) -> bytes:+ # requests (huggingface_hub 0.x, Python 3.9) or httpx / httpx2 (1.x / 2.x).+ from core.inference.diffusion_compat import _iter_body, _ranged_stream++ headers = dict(base_headers)+ headers["Range"] = f"bytes={start}-{end}"+ with _ranged_stream(get_session(), url, headers) as resp:+ if resp.status_code != 206:+ raise ValueError(f"range request answered {resp.status_code}")+ return b"".join(_iter_body(resp, 1 << 20))++ return fetch+++def prepare_media_gguf(+ repo_id: str,+ filename: str,+ token,+ *,+ repo_type: str = "model",+ revision: Optional[str] = None,+ cache_dir: Optional[str] = None,+ cancel_event: Optional[threading.Event] = None,+ metadata_fn: Optional[Callable] = None,+ fetcher_fn: Optional[Callable] = None,+) -> DeltaResult:+ """Single-file entry for the Images / Video load paths, run before ``hf_hub_download``.++ Local checks first, no network: the file for the locally known target commit (``refs/<revision>``, or the commit+ itself) must be missing and an older snapshot must hold the same path. That is the only case where a download+ follows anyway. Then one HEAD for the current commit, size and sha256, and the rebuild. On success ``refs/<revision>``+ names the new commit, so the caller's cache probe finds the rebuilt file."""+ t0 = time.perf_counter()+ try:+ if not delta_enabled() or not str(filename).lower().endswith(".gguf"):+ return DeltaResult(reason = "not applicable", decide_s = time.perf_counter() - t0)+ from huggingface_hub import constants+ from huggingface_hub.file_download import repo_folder_name++ root = Path(cache_dir) if cache_dir else Path(constants.HF_HUB_CACHE)+ repo_dir = root / repo_folder_name(repo_id = repo_id, repo_type = repo_type)+ ref = revision or "main"+ if _COMMIT.match(ref):+ local_commit = ref+ else:+ try:+ local_commit = (repo_dir / "refs" / ref).read_text(encoding = "utf-8").strip()+ except OSError:+ local_commit = ""+ if local_commit and os.path.lexists(repo_dir / "snapshots" / local_commit / filename):+ return DeltaResult(reason = "already cached", decide_s = time.perf_counter() - t0)+ if not _other_snapshot_copies(repo_dir, local_commit, filename):+ return DeltaResult(reason = "no older copy", decide_s = time.perf_counter() - t0)+ if constants.HF_HUB_OFFLINE:+ return DeltaResult(reason = "offline", decide_s = time.perf_counter() - t0)+ if metadata_fn is None:+ from huggingface_hub import get_hf_file_metadata, hf_hub_url+ def metadata_fn():+ return get_hf_file_metadata(+ hf_hub_url(repo_id, filename, repo_type = repo_type, revision = revision),+ token = token,+ timeout = _METADATA_TIMEOUT,+ )++ meta = metadata_fn()+ commit = getattr(meta, "commit_hash", None) or ""+ digest = (getattr(meta, "etag", None) or "").strip('"').lower()+ size = int(getattr(meta, "size", 0) or 0)+ if not _COMMIT.match(commit) or not _SHA256.match(digest) or size <= 0:+ return DeltaResult(reason = "no sha256 for this file", decide_s = time.perf_counter() - t0)+ fetch = (fetcher_fn or hub_range_fetcher)(+ repo_id, filename, token, repo_type = repo_type, revision = commit+ )+ result = rebuild_from_older_snapshot(+ repo_dir, commit, filename, size, digest, fetch, cancel_event = cancel_event+ )+ if result.placed and ref != commit:+ from huggingface_hub.file_download import _cache_commit_hash_for_specific_revision+ _cache_commit_hash_for_specific_revision(str(repo_dir), ref, commit)+ return result+ except Exception as exc: # noqa: BLE001 - an optimisation only+ logger.info("gguf header delta skipped for %s/%s: %s", repo_id, filename, exc)+ return DeltaResult(reason = f"error: {exc}", decide_s = time.perf_counter() - t0)+++def reset_for_tests() -> None:+ global _refused+ with _refused_lock:+ _refused = Nonediff --git a/studio/backend/hub/workers/hf_download.py b/studio/backend/hub/workers/hf_download.pyindex f074e3e104f..06f82f03abf 100644--- a/studio/backend/hub/workers/hf_download.py+++ b/studio/backend/hub/workers/hf_download.py@@ -239,6 +239,52 @@ def _model_info_with_retry(repo_id: str, hf_token: str | None):return info+def _rebuild_header_only_ggufs(+ repo_type: RepoType, repo_id: str, commit_hash, expected_files: list, hf_token: str | None+) -> None:+ """Rebuild each pending image / video GGUF whose new revision changed only its header from the older snapshot's+ copy. Chat, audio and other GGUFs keep the plain download; the gate is read only when a rebuild is possible."""+ try:+ from hub.utils.download_manifest import expected_path_is_safe, normalized_commit_hash+ from hub.utils.gguf_header_delta import (+ _is_media_gguf,+ delta_enabled,+ hub_range_fetcher,+ rebuild_from_older_snapshot,+ )+ from hub.utils.snapshot_reuse import repo_cache_dir++ commit = normalized_commit_hash(commit_hash)+ if not commit or not delta_enabled():+ return+ repo_dir = repo_cache_dir(repo_type, repo_id)+ protected = _protected_blob_hashes()+ for item in expected_files:+ path = getattr(item, "path", None)+ digest = getattr(item, "sha256", None)+ size = int(getattr(item, "size", 0) or 0)+ if not expected_path_is_safe(path) or not str(path).lower().endswith(".gguf"):+ continue+ result = rebuild_from_older_snapshot(+ repo_dir,+ commit,+ path,+ size,+ digest or "",+ hub_range_fetcher(repo_id, path, hf_token, repo_type = repo_type, revision = commit),+ protected_blob_hashes = protected,+ media_gate = lambda old, path = path: _is_media_gguf(old, repo_id, path),+ )+ if result.placed:+ print(+ f"Rebuilt {path} from the cached older copy (only its header changed): fetched "+ f"{result.fetched_bytes / 1e6:.2f} MB instead of {result.size / 1e9:.2f} GB.",+ file = sys.stderr,+ )+ except Exception as exc: # noqa: BLE001 - an optimisation only: snapshot_download fetches what is left+ print(f"GGUF header reuse skipped for {repo_id}: {exc}", file = sys.stderr)++def _reuse_unchanged_files(repo_type: RepoType, repo_id: str, commit_hash, expected_files: list, hf_token: str | None) -> list:@@ -261,6 +307,7 @@ def _reuse_unchanged_files(f"from an older snapshot of {repo_id} instead of downloading them again.",file = sys.stderr,)+ _rebuild_header_only_ggufs(repo_type, repo_id, commit_hash, expected_files, hf_token)# Files an earlier attempt placed are skipped by snapshot_download and have no blob for the preflight to discount.present = paths_in_snapshot(repo_type, repo_id, commit_hash, [getattr(f, "path", None) for f in expected_files]diff --git a/studio/backend/tests/test_gguf_header_delta.py b/studio/backend/tests/test_gguf_header_delta.pynew file mode 100644index 00000000000..5beb8cf5603--- /dev/null+++ b/studio/backend/tests/test_gguf_header_delta.py@@ -0,0 +1,646 @@+# SPDX-License-Identifier: AGPL-3.0-only+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0++"""Rebuilding a republished GGUF from the cached older copy when only its header changed."""++from __future__ import annotations++import hashlib+import os+import struct+import threading+from pathlib import Path+from types import SimpleNamespace++import pytest++from hub.utils import gguf_header_delta as delta++COMMIT_OLD = "a" * 40+COMMIT_NEW = "b" * 40+NAME = "model-Q4_K_M.gguf"+++def _s(text: str) -> bytes:+ raw = text.encode()+ return struct.pack("<Q", len(raw)) + raw+++def make_gguf(+ kvs: dict,+ tensors: list,+ *,+ alignment: int = 32,+) -> bytes:+ """``tensors``: (name, dims, ggml type, payload bytes). String KVs only, plus an optional alignment KV."""+ head = b"GGUF" + struct.pack("<I", 3) + struct.pack("<QQ", len(tensors), len(kvs))+ for key, value in kvs.items():+ if key == "general.alignment":+ head += _s(key) + struct.pack("<I", 4) + struct.pack("<I", value)+ else:+ head += _s(key) + struct.pack("<I", 8) + _s(value)+ offset, blobs = 0, b""+ for name, dims, ggml_type, payload in tensors:+ head += (+ _s(name) + struct.pack("<I", len(dims)) + b"".join(struct.pack("<Q", d) for d in dims)+ )+ head += struct.pack("<I", ggml_type) + struct.pack("<Q", offset)+ pad = -len(payload) % alignment+ blobs += payload + b"\0" * pad+ offset += len(payload) + pad+ head += b"\0" * (-len(head) % alignment)+ return head + blobs+++TENSORS = [+ ("blk.0.attn_q.weight", (8, 4), 0, os.urandom(4096)),+ ("blk.0.ffn_up.weight", (16, 4), 1, os.urandom(4096)),+]+OLD = make_gguf({"general.architecture": "llama"}, TENSORS)+NEW = make_gguf(+ {"general.architecture": "llama", "tokenizer.chat_template": "{{ fixed }}" * 50}, TENSORS+)+++def sha(data: bytes) -> str:+ return hashlib.sha256(data).hexdigest()+++class Fetcher:+ def __init__(+ self,+ data: bytes,+ *,+ fail: bool = False,+ ):+ self.data, self.fail, self.calls = data, fail, []++ def __call__(self, start: int, end: int) -> bytes:+ self.calls.append((start, end))+ if self.fail:+ raise ValueError("range request answered 200")+ return self.data[start : end + 1]+++def cache_with_old(+ tmp_path: Path,+ *,+ symlinks: bool,+ data: bytes = OLD,+) -> Path:+ repo_dir = tmp_path / "models--unsloth--Model-GGUF"+ snap = repo_dir / "snapshots" / COMMIT_OLD+ snap.mkdir(parents = True)+ (repo_dir / "refs").mkdir()+ (repo_dir / "refs" / "main").write_text(COMMIT_OLD)+ if symlinks:+ blobs = repo_dir / "blobs"+ blobs.mkdir()+ (blobs / sha(data)).write_bytes(data)+ os.symlink(os.path.join("..", "..", "blobs", sha(data)), snap / NAME)+ else:+ (snap / NAME).write_bytes(data)+ return repo_dir++[email protected](autouse = True)+def _small_ranges(monkeypatch, tmp_path):+ monkeypatch.delenv(delta.DELTA_ENV, raising = False)+ monkeypatch.setattr(delta, "_FIRST_RANGE", 64)+ monkeypatch.setattr(delta, "_HEADER_SLACK", 64)+ memo = tmp_path / "refused.json"+ monkeypatch.setattr(delta, "_refused_path", lambda: memo)+ delta.reset_for_tests()+ yield+ delta.reset_for_tests()+++def rebuild(+ repo_dir: Path,+ new: bytes = NEW,+ fetch = None,+ **kw,+):+ return delta.rebuild_from_older_snapshot(+ repo_dir, COMMIT_NEW, NAME, len(new), sha(new), fetch or Fetcher(new), **kw+ )+++def test_parse_layout_matches_writer():+ layout = delta.parse_gguf_layout(NEW)+ assert [t[0] for t in layout.tensors] == [b"blk.0.attn_q.weight", b"blk.0.ffn_up.weight"]+ assert layout.data_offset % 32 == 0+ assert NEW[layout.data_offset :] == OLD[delta.parse_gguf_layout(OLD).data_offset :]+++def test_parse_layout_honours_alignment_kv():+ data = make_gguf({"general.alignment": 64}, TENSORS, alignment = 64)+ assert delta.parse_gguf_layout(data).data_offset % 64 == 0+++def test_parse_truncated_asks_for_more():+ with pytest.raises(delta._NeedMore):+ delta.parse_gguf_layout(NEW[:40])+++def test_header_only_change_rebuilds_in_blob_layout(tmp_path):+ repo_dir = cache_with_old(tmp_path, symlinks = True)+ fetch = Fetcher(NEW)+ result = rebuild(repo_dir, fetch = fetch)+ assert result.placed, result.reason+ pointer = repo_dir / "snapshots" / COMMIT_NEW / NAME+ assert pointer.is_symlink()+ assert pointer.read_bytes() == NEW+ assert (repo_dir / "blobs" / sha(NEW)).read_bytes() == NEW+ # Only the header crossed the network: ranges grow by doubling, so at most twice its size.+ assert result.fetched_bytes <= 2 * delta.parse_gguf_layout(NEW).data_offset < len(NEW)+ # The old revision is untouched.+ assert (repo_dir / "snapshots" / COMMIT_OLD / NAME).read_bytes() == OLD+++def test_header_only_change_rebuilds_in_no_symlink_layout(tmp_path):+ repo_dir = cache_with_old(tmp_path, symlinks = False)+ result = rebuild(repo_dir)+ assert result.placed, result.reason+ pointer = repo_dir / "snapshots" / COMMIT_NEW / NAME+ assert not pointer.is_symlink() and pointer.read_bytes() == NEW+ assert not (repo_dir / "blobs").exists()+++def test_huggingface_hub_then_serves_the_rebuilt_file(tmp_path):+ repo_dir = cache_with_old(tmp_path, symlinks = True)+ assert rebuild(repo_dir).placed+ from huggingface_hub import try_to_load_from_cache++ (repo_dir / "refs" / "main").write_text(COMMIT_NEW)+ got = try_to_load_from_cache("unsloth/Model-GGUF", NAME, cache_dir = str(tmp_path))+ assert Path(got).read_bytes() == NEW+++ "new",+ [+ # A tensor's bytes changed: same table, the sha256 check refuses it.+ make_gguf(+ {"general.architecture": "llama", "x": "y"},+ [TENSORS[0], (TENSORS[1][0], TENSORS[1][1], TENSORS[1][2], os.urandom(4096))],+ ),+ # A tensor's size changed.+ make_gguf(+ {"general.architecture": "llama"},+ [TENSORS[0], (TENSORS[1][0], (16, 8), 1, os.urandom(8192))],+ ),+ # Same tensors, reordered.+ make_gguf({"general.architecture": "llama", "x": "y"}, [TENSORS[1], TENSORS[0]]),+ # Requantized type.+ make_gguf(+ {"general.architecture": "llama"},+ [TENSORS[0], (TENSORS[1][0], TENSORS[1][1], 2, TENSORS[1][3])],+ ),+ ],+ ids = ["tensor-bytes", "tensor-size", "reordered", "type"],+)+def test_changed_tensors_fall_back(tmp_path, new):+ repo_dir = cache_with_old(tmp_path, symlinks = True)+ result = rebuild(repo_dir, new = new)+ assert not result.placed+ assert not (repo_dir / "snapshots" / COMMIT_NEW).exists()+ assert not (repo_dir / "blobs" / sha(new)).exists()+ assert not list((repo_dir / "blobs").glob(".*delta-*"))+++def test_hash_mismatch_falls_back_and_cleans_up(tmp_path):+ repo_dir = cache_with_old(tmp_path, symlinks = True)+ result = delta.rebuild_from_older_snapshot(+ repo_dir, COMMIT_NEW, NAME, len(NEW), "f" * 64, Fetcher(NEW)+ )+ assert not result.placed and result.reason == "sha256 mismatch"+ assert sorted(p.name for p in (repo_dir / "blobs").iterdir()) == [sha(OLD)]+++def test_corrupt_cached_copy_falls_back(tmp_path):+ bad = bytearray(OLD)+ bad[-5] ^= 0xFF+ repo_dir = cache_with_old(tmp_path, symlinks = False, data = bytes(bad))+ result = rebuild(repo_dir)+ assert not result.placed and result.reason == "sha256 mismatch"+++def test_range_failure_falls_back(tmp_path):+ repo_dir = cache_with_old(tmp_path, symlinks = True)+ result = rebuild(repo_dir, fetch = Fetcher(NEW, fail = True))+ assert not result.placed and result.reason.startswith("error")+++def test_short_range_response_falls_back(tmp_path):+ repo_dir = cache_with_old(tmp_path, symlinks = True)+ result = rebuild(repo_dir, fetch = lambda start, end: NEW[start : start + 3])+ assert not result.placed+++def test_header_past_cap_falls_back(tmp_path, monkeypatch):+ monkeypatch.setattr(delta, "_MAX_HEADER_BYTES", 80)+ repo_dir = cache_with_old(tmp_path, symlinks = True)+ assert not rebuild(repo_dir).placed+++def test_kill_switch(tmp_path, monkeypatch):+ monkeypatch.setenv(delta.DELTA_ENV, "0")+ repo_dir = cache_with_old(tmp_path, symlinks = True)+ fetch = Fetcher(NEW)+ assert rebuild(repo_dir, fetch = fetch).reason == "disabled"+ assert fetch.calls == []+++def test_no_older_copy_asks_nothing(tmp_path):+ repo_dir = tmp_path / "models--unsloth--Model-GGUF"+ fetch = Fetcher(NEW)+ assert rebuild(repo_dir, fetch = fetch).reason == "no older copy"+ assert fetch.calls == []+++def test_protected_blob_is_left_alone(tmp_path):+ repo_dir = cache_with_old(tmp_path, symlinks = True)+ fetch = Fetcher(NEW)+ result = rebuild(repo_dir, fetch = fetch, protected_blob_hashes = frozenset({sha(NEW)}))+ assert result.reason == "blob protected" and fetch.calls == []+++def test_locked_blob_is_left_alone(tmp_path):+ repo_dir = cache_with_old(tmp_path, symlinks = True)+ from filelock import FileLock++ lock = delta._lock_path(repo_dir, sha(NEW))+ lock.parent.mkdir(parents = True, exist_ok = True)+ held, release = threading.Event(), threading.Event()++ def hold():+ with FileLock(str(lock)):+ held.set()+ release.wait(5)++ t = threading.Thread(target = hold)+ t.start()+ held.wait(5)+ try:+ result = rebuild(repo_dir)+ finally:+ release.set()+ t.join()+ assert result.reason == "blob locked"+ assert not (repo_dir / "blobs" / sha(NEW)).exists()+++def test_already_cached_target_is_left_alone(tmp_path):+ repo_dir = cache_with_old(tmp_path, symlinks = True)+ (repo_dir / "blobs" / sha(NEW)).write_bytes(NEW)+ fetch = Fetcher(NEW)+ assert rebuild(repo_dir, fetch = fetch).reason == "already cached"+ assert fetch.calls == []+++def test_not_enough_disk_falls_back(tmp_path, monkeypatch):+ repo_dir = cache_with_old(tmp_path, symlinks = True)+ monkeypatch.setattr(delta.shutil, "disk_usage", lambda p: SimpleNamespace(free = 10))+ assert rebuild(repo_dir).reason == "not enough disk"+++def test_cancel_falls_back(tmp_path):+ repo_dir = cache_with_old(tmp_path, symlinks = True)+ cancel = threading.Event()+ cancel.set()+ assert not rebuild(repo_dir, cancel_event = cancel).placed+ assert not list((repo_dir / "blobs").glob(".*delta-*"))+++def _meta(data: bytes, commit: str = COMMIT_NEW):+ return SimpleNamespace(commit_hash = commit, etag = sha(data), size = len(data))+++def test_first_range_is_sized_from_the_cached_header(tmp_path):+ repo_dir = cache_with_old(tmp_path, symlinks = True)+ small_change = make_gguf({"general.architecture": "llama", "x": "y"}, TENSORS)+ fetch = Fetcher(small_change)+ assert rebuild(repo_dir, new = small_change, fetch = fetch).placed+ assert len(fetch.calls) == 1+++def test_refused_verdict_is_not_retried(tmp_path):+ repo_dir = cache_with_old(tmp_path, symlinks = True)+ other = make_gguf({"general.architecture": "llama"}, [TENSORS[1], TENSORS[0]])+ first = Fetcher(other)+ assert rebuild(repo_dir, new = other, fetch = first).reason == "tensor table differs"+ again = Fetcher(other)+ assert rebuild(repo_dir, new = other, fetch = again).reason == "refused before"+ assert again.calls == []+++def test_media_gate_refuses_before_any_fetch(tmp_path):+ repo_dir = cache_with_old(tmp_path, symlinks = True)+ fetch = Fetcher(NEW)+ result = rebuild(repo_dir, fetch = fetch, media_gate = lambda old: False)+ assert result.reason == "not an image / video GGUF" and fetch.calls == []+++def _prepare(tmp_path, metadata, **kw):+ return delta.prepare_media_gguf(+ "unsloth/Model-GGUF",+ NAME,+ None,+ cache_dir = str(tmp_path),+ metadata_fn = metadata,+ fetcher_fn = kw.pop("fetcher_fn", lambda *a, **k: Fetcher(NEW)),+ **kw,+ )+++def _no_head():+ raise AssertionError("no HEAD expected")+++def test_prepare_needs_no_network_when_the_ref_has_the_file(tmp_path):+ cache_with_old(tmp_path, symlinks = True)+ assert _prepare(tmp_path, _no_head).reason == "already cached"+++def test_prepare_needs_no_network_without_an_older_copy(tmp_path):+ assert _prepare(tmp_path, _no_head).reason == "no older copy"+ assert delta.prepare_media_gguf("u/m", "m.safetensors", None, metadata_fn = _no_head).reason == (+ "not applicable"+ )+++def test_prepare_rebuilds_after_the_ref_moved(tmp_path):+ repo_dir = cache_with_old(tmp_path, symlinks = True)+ # Another file of the repo was fetched at the new commit, so refs/main moved and this GGUF is missing there.+ (repo_dir / "snapshots" / COMMIT_NEW).mkdir()+ (repo_dir / "refs" / "main").write_text(COMMIT_NEW)+ result = _prepare(tmp_path, lambda: _meta(NEW))+ assert result.placed, result.reason+ from huggingface_hub import try_to_load_from_cache++ got = try_to_load_from_cache("unsloth/Model-GGUF", NAME, cache_dir = str(tmp_path))+ assert Path(got).read_bytes() == NEW+++def test_prepare_moves_the_ref_to_the_rebuilt_commit(tmp_path):+ repo_dir = cache_with_old(tmp_path, symlinks = True)+ (repo_dir / "refs" / "main").write_text("c" * 40)+ result = _prepare(tmp_path, lambda: _meta(NEW))+ assert result.placed, result.reason+ assert (repo_dir / "refs" / "main").read_text() == COMMIT_NEW+++def test_prepare_never_raises(tmp_path):+ repo_dir = cache_with_old(tmp_path, symlinks = True)+ (repo_dir / "refs" / "main").write_text(COMMIT_NEW)++ def boom():+ raise OSError("network down")++ result = _prepare(tmp_path, boom)+ assert not result.placed and result.reason.startswith("error")+++def _fake_shared(monkeypatch, seen):+ from utils import hf_xet_fallback as fallback++ def fake_download(repo_id, filename, token, **kwargs):+ seen.update(kwargs)+ return "path"++ monkeypatch.setattr(fallback, "_shared_hf_hub_download_with_xet_fallback", fake_download)+ return fallback+++def test_wrapper_without_opt_in_never_calls_the_delta(tmp_path, monkeypatch):+ seen = {}+ fallback = _fake_shared(monkeypatch, seen)+ monkeypatch.setattr(delta, "prepare_media_gguf", lambda *a, **k: _no_head())+ fallback.hf_hub_download_with_xet_fallback(+ "unsloth/Model-GGUF", NAME, None, force_download = True, cache_dir = str(tmp_path)+ )+ assert seen["force_download"] is True+++def test_wrapper_opt_in_skips_force_after_a_rebuild(tmp_path, monkeypatch):+ seen = {}+ fallback = _fake_shared(monkeypatch, seen)+ monkeypatch.setattr(delta, "prepare_media_gguf", lambda *a, **k: delta.DeltaResult(placed = True))+ fallback.hf_hub_download_with_xet_fallback(+ "unsloth/Model-GGUF",+ NAME,+ None,+ force_download = True,+ cache_dir = str(tmp_path),+ gguf_header_delta = True,+ )+ assert seen["force_download"] is False+++def test_wrapper_opt_in_keeps_force_without_a_rebuild(tmp_path, monkeypatch):+ seen = {}+ fallback = _fake_shared(monkeypatch, seen)+ monkeypatch.setattr(delta, "prepare_media_gguf", lambda *a, **k: delta.DeltaResult())+ fallback.hf_hub_download_with_xet_fallback(+ "unsloth/Model-GGUF",+ NAME,+ None,+ force_download = True,+ cache_dir = str(tmp_path),+ gguf_header_delta = True,+ )+ assert seen["force_download"] is True+++H3_REPO, H3_NAME = "unsloth/MiniMax-H3-GGUF", "minimax_h3_fl2va_pruned-Q4_K.gguf"+++def _worker_cache(tmp_path, repo: str, name: str, data: bytes) -> Path:+ from huggingface_hub.file_download import repo_folder_name++ repo_dir = tmp_path / repo_folder_name(repo_id = repo, repo_type = "model")+ snap = repo_dir / "snapshots" / COMMIT_OLD+ snap.mkdir(parents = True)+ (repo_dir / "blobs").mkdir()+ (repo_dir / "blobs" / sha(data)).write_bytes(data)+ os.symlink(os.path.join("..", "..", "blobs", sha(data)), snap / name)+ return repo_dir+++def test_download_worker_rebuilds_a_video_gguf(tmp_path, monkeypatch):+ from hub.workers import hf_download++ repo_dir = _worker_cache(tmp_path, H3_REPO, H3_NAME, OLD)+ monkeypatch.setattr("huggingface_hub.constants.HF_HUB_CACHE", str(tmp_path))+ monkeypatch.setattr(delta, "hub_range_fetcher", lambda *a, **k: Fetcher(NEW))+ files = [SimpleNamespace(path = H3_NAME, size = len(NEW), sha256 = sha(NEW))]+ left = hf_download._reuse_unchanged_files("model", H3_REPO, COMMIT_NEW, files, None)+ assert left == []+ assert (repo_dir / "snapshots" / COMMIT_NEW / H3_NAME).read_bytes() == NEW+++def test_download_worker_leaves_chat_ggufs_alone(tmp_path, monkeypatch):+ from hub.workers import hf_download++ repo, name = "unsloth/Llama-3.2-1B-Instruct-GGUF", "Llama-3.2-1B-Instruct-Q4_K_M.gguf"+ repo_dir = _worker_cache(tmp_path, repo, name, OLD)+ monkeypatch.setattr("huggingface_hub.constants.HF_HUB_CACHE", str(tmp_path))+ fetch = Fetcher(NEW)+ monkeypatch.setattr(delta, "hub_range_fetcher", lambda *a, **k: fetch)+ files = [SimpleNamespace(path = name, size = len(NEW), sha256 = sha(NEW))]+ left = hf_download._reuse_unchanged_files("model", repo, COMMIT_NEW, files, None)+ assert [f.path for f in left] == [name]+ assert fetch.calls == []+ assert not (repo_dir / "snapshots" / COMMIT_NEW).exists()+++def test_refused_verdict_survives_a_restart(tmp_path):+ repo_dir = cache_with_old(tmp_path, symlinks = True)+ other = make_gguf({"general.architecture": "llama"}, [TENSORS[1], TENSORS[0]])+ assert rebuild(repo_dir, new = other).reason == "tensor table differs"+ delta.reset_for_tests() # a new backend process: only the file remains+ fetch = Fetcher(other)+ assert rebuild(repo_dir, new = other, fetch = fetch).reason == "refused before"+ assert fetch.calls == []+ # A different new sha (a later republish) is tried again.+ assert rebuild(repo_dir).placed+++BACKEND = Path(__file__).resolve().parents[1]+OPT_IN_MODULES = {+ "core/inference/diffusion.py",+ "core/inference/sd_cpp_backend.py",+ "core/inference/video.py",+ "core/inference/video_ltx2.py",+ "core/inference/video_minimax_h3_te.py",+}+++def _opt_in_sites() -> dict:+ import ast++ found: dict = {}+ for path in BACKEND.rglob("*.py"):+ rel = path.relative_to(BACKEND).as_posix()+ if rel.startswith("tests/"):+ continue+ try:+ tree = ast.parse(path.read_text(encoding = "utf-8"))+ except (OSError, SyntaxError, UnicodeDecodeError):+ continue+ for node in ast.walk(tree):+ if isinstance(node, ast.Call):+ for kw in node.keywords:+ if kw.arg == "gguf_header_delta":+ found.setdefault(rel, []).append(ast.unparse(kw.value))+ return found+++def test_only_the_images_and_video_paths_opt_in():+ sites = _opt_in_sites()+ sites.pop("utils/hf_xet_fallback.py", None)+ assert set(sites) == OPT_IN_MODULES+ assert all(v == "True" for values in sites.values() for v in values)+ assert "core/inference/llama_cpp.py" not in sites+++def test_a_chat_gguf_download_never_reaches_the_delta(tmp_path, monkeypatch):+ # Called the way llama_cpp._download_gguf / the mmproj fetch call it: no opt-in. Even with an older snapshot+ # present and the target missing, neither the delta, a HEAD nor a Range request is made.+ repo_dir = cache_with_old(tmp_path, symlinks = True)+ (repo_dir / "refs" / "main").write_text(COMMIT_NEW)+ seen = {}+ fallback = _fake_shared(monkeypatch, seen)+ monkeypatch.setattr(delta, "prepare_media_gguf", lambda *a, **k: _no_head())+ monkeypatch.setattr(delta, "hub_range_fetcher", lambda *a, **k: _no_head())+ monkeypatch.setattr("huggingface_hub.get_hf_file_metadata", lambda *a, **k: _no_head())+ assert (+ fallback.hf_hub_download_with_xet_fallback(+ "unsloth/Model-GGUF", NAME, None, cache_dir = str(tmp_path)+ )+ == "path"+ )+++def test_the_image_gguf_prefetch_opts_in(monkeypatch):+ import threading as _threading++ from core.inference.diffusion import DiffusionBackend+ from utils import hf_xet_fallback++ calls = []++ def fake(repo_id, filename, token, **kwargs):+ calls.append((filename, kwargs))+ return "/nonexistent"++ monkeypatch.setattr(hf_xet_fallback, "hf_hub_download_with_xet_fallback", fake)+ stub = SimpleNamespace(_cancel_event = _threading.Event())+ DiffusionBackend._prefetch_files(+ stub,+ "unsloth/Qwen-Image-2.1-GGUF",+ "qwen-image-2.1-Q4_K_M.gguf",+ "base/x",+ [],+ None,+ fetch_base = "base/x",+ )+ assert calls and calls[0][0] == "qwen-image-2.1-Q4_K_M.gguf"+ assert calls[0][1].get("gguf_header_delta") is True+++ "task, expected",+ [+ ("text-to-image", True),+ ("text-to-video", True),+ ("image-diffusion-unsupported", True),+ ("text-generation", False),+ ("text-to-speech", False),+ (None, False),+ ],+)+def test_media_gate_follows_the_catalog_task(tmp_path, monkeypatch, task, expected):+ from hub.services.models import catalog_classification+ monkeypatch.setattr(catalog_classification, "_gguf_file_task", lambda path, hints: task)+ assert delta._is_media_gguf(tmp_path / "x.gguf", "u/m", "x.gguf") is expected++[email protected]("client", ["httpx", "httpx2", "requests"])[email protected]("status, ok", [(206, True), (200, False)])+def test_range_fetcher_streams_on_the_hub_session(monkeypatch, client, status, ok):+ seen = []++ class Resp:+ status_code = status++ def __enter__(self):+ return self++ def __exit__(self, *exc):+ return False++ def _chunks(self, size):+ seen.append("read")+ return iter([b"x" * 4, b"x" * 6])++ if client == "requests":+ Resp.iter_content = Resp._chunks+ session = type("Session", (), {"__module__": "requests.sessions", "stream": False})()+ session.get = lambda url, **kw: seen.append(kw["headers"]["Range"]) or Resp()+ else:+ Resp.iter_bytes = Resp._chunks+ session = type("Client", (), {"__module__": client})()+ session.stream = lambda method, url, **kw: seen.append(kw["headers"]["Range"]) or Resp()+ import huggingface_hub.utils as hf_utils++ monkeypatch.setattr(hf_utils, "get_session", lambda: session)+ fetch = delta.hub_range_fetcher("u/m", NAME, None, revision = COMMIT_NEW)+ if ok:+ assert fetch(0, 9) == b"x" * 10+ else:+ with pytest.raises(ValueError):+ fetch(0, 9)+ assert "read" not in seen+ assert seen[0] == "bytes=0-9"diff --git a/studio/backend/utils/hf_xet_fallback.py b/studio/backend/utils/hf_xet_fallback.pyindex 56664524bf9..0daa72fac5f 100644--- a/studio/backend/utils/hf_xet_fallback.py+++ b/studio/backend/utils/hf_xet_fallback.py@@ -952,6 +952,7 @@ def hf_hub_download_with_xet_fallback(cache_dir: Optional[str] = None,reuse_other_cache_root: bool = False,local_files_only: bool = False,+ gguf_header_delta: bool = False,) -> str:"""Single-file download via the shared fallback with Unsloth's marker-aware HTTP-retry prep.``force_download`` re-fetches a newer blob over a cached one (Unsloth's model-update path).@@ -971,7 +972,11 @@ def hf_hub_download_with_xet_fallback(already cleared it. Routed THROUGH the other root rather than returned raw, so the ref stillresolves and a republished file is picked up; the blob is reused, and offline/401hf_hub_download keeps the failed HEAD and serves the cached pointer. Off for- ``force_download``, whose point is to re-fetch."""+ ``force_download``, whose point is to re-fetch.++ ``gguf_header_delta`` (opt-in, Images / Video GGUF loads only) rebuilds a GGUF whose new revision changed only its+ header from the cached older copy (``hub.utils.gguf_header_delta``); no network unless that file is missing for+ the target commit and an older snapshot holds it."""if cache_dir is None:from utils.hf_cache_settings import get_hf_cache_pathscache_dir = str(get_hf_cache_paths().hub_cache)@@ -1010,6 +1015,22 @@ def hf_hub_download_with_xet_fallback(if cancel_event is not None and cancel_event.is_set():raise RuntimeError("Cancelled")return path+ if gguf_header_delta and str(filename).lower().endswith(".gguf"):+ # A rebuilt file has the Hub's sha256, so it already is the newer blob a forced fetch wants.+ try:+ from hub.utils.gguf_header_delta import prepare_media_gguf+ if prepare_media_gguf(+ repo_id,+ filename,+ token,+ repo_type = repo_type,+ revision = revision,+ cache_dir = cache_dir,+ cancel_event = cancel_event,+ ).placed:+ force_download = False+ except Exception: # noqa: BLE001 - an optimisation only: the normal download follows+ pass# Omit rather than forward None: an older unsloth_zoo hands `interval` straight to Event.wait()optional: dict[str, Any] = {}if stall_timeout is not None: