Skip to content

Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.

Studio: 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.py
index 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] = None
diff --git a/studio/backend/core/inference/sd_cpp_backend.py b/studio/backend/core/inference/sd_cpp_backend.py
index 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 can
diff --git a/studio/backend/core/inference/video.py b/studio/backend/core/inference/video.py
index 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.py
index 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 name
local_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.py
index 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.py
new file mode 100644
index 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 = None
diff --git a/studio/backend/hub/workers/hf_download.py b/studio/backend/hub/workers/hf_download.py
index 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.py
new file mode 100644
index 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.py
index 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 still
resolves and a republished file is picked up; the blob is reused, and offline/401
hf_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_paths
cache_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: