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 video: read an LTX-2 checkpoint header once per file when probing for 2.3 (#15738)

Daniel Hanf1dedb663175
diff --git a/studio/backend/core/inference/video_ltx2.py b/studio/backend/core/inference/video_ltx2.py
index b27925597f4..e2711f53117 100644
--- a/studio/backend/core/inference/video_ltx2.py
+++ b/studio/backend/core/inference/video_ltx2.py
@@ -7,6 +7,7 @@ from __future__ import annotations
import contextlib
import contextvars
+import os
import threading
from pathlib import Path
from typing import Any, Iterator, Optional
@@ -249,19 +250,54 @@ def read_checkpoint_header(checkpoint_path: Path | str) -> dict[str, tuple[int,
return names_shapes
+# Keyed by file identity + stamps: an edited or replaced file is re-read; failures never kept.
+_LTX23_VERDICTS: dict[tuple, bool] = {}
+_LTX23_VERDICTS_LOCK = threading.Lock()
+_LTX23_VERDICTS_MAX = 256
+
+
+def _checkpoint_stamp(checkpoint_path: Path | str) -> Optional[tuple]:
+ try:
+ path = os.fspath(checkpoint_path)
+ st = os.stat(path)
+ return (
+ os.path.realpath(path),
+ st.st_dev,
+ st.st_ino,
+ st.st_size,
+ st.st_mtime_ns,
+ st.st_ctime_ns,
+ )
+ except (OSError, TypeError, ValueError):
+ return None
+
+
def is_ltx23_checkpoint(checkpoint_path: Path | str) -> bool:
"""True when the checkpoint carries the 9-row LTX-2.3 modulation tables (2.0 has 6-row
per-block scale/shift tables; 2.3 widens them to 9). An unreadable header returns False so the
caller falls back to the stock 2.0 path."""
+ stamp = _checkpoint_stamp(checkpoint_path)
+ if stamp is not None:
+ with _LTX23_VERDICTS_LOCK:
+ verdict = _LTX23_VERDICTS.get(stamp)
+ if verdict is not None:
+ return verdict
try:
header = read_checkpoint_header(checkpoint_path)
except Exception as exc: # noqa: BLE001
logger.warning("video.ltx2_header_probe_failed: %s", exc)
return False
+ verdict = False
for name, shape in header.items():
if name.endswith("transformer_blocks.0.scale_shift_table"):
- return 9 in shape
- return False
+ verdict = 9 in shape
+ break
+ if stamp is not None:
+ with _LTX23_VERDICTS_LOCK:
+ if len(_LTX23_VERDICTS) >= _LTX23_VERDICTS_MAX:
+ _LTX23_VERDICTS.clear()
+ _LTX23_VERDICTS[stamp] = verdict
+ return verdict
def assert_not_ltx25_checkpoint(checkpoint_path: Path | str) -> None:
diff --git a/studio/backend/tests/test_ltx23_verdict_memo.py b/studio/backend/tests/test_ltx23_verdict_memo.py
new file mode 100644
index 00000000000..0a11add1794
--- /dev/null
+++ b/studio/backend/tests/test_ltx23_verdict_memo.py
@@ -0,0 +1,150 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""is_ltx23_checkpoint reads a checkpoint header once per file identity: a load asks twice (download
+estimate, then the load), and a GGUF header walk builds a view per tensor."""
+
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+
+import pytest
+
+_BACKEND_DIR = Path(__file__).resolve().parent.parent
+if str(_BACKEND_DIR) not in sys.path:
+ sys.path.insert(0, str(_BACKEND_DIR))
+
+from core.inference import video_ltx2 # noqa: E402
+
+KEY = "model.diffusion_model.transformer_blocks.0.scale_shift_table"
+
+
+def reads(monkeypatch):
+ monkeypatch.setattr(video_ltx2, "_LTX23_VERDICTS", {}, raising = False)
+ calls = []
+ headers = {}
+
+ def fake_read(path):
+ calls.append(os.fspath(path))
+ header = headers.get(Path(path).read_bytes())
+ if header is None:
+ raise RuntimeError("bad magic")
+ return header
+
+ monkeypatch.setattr(video_ltx2, "read_checkpoint_header", fake_read)
+ return calls, headers
+
+
+def test_repeat_probes_read_the_header_once(reads, tmp_path):
+ calls, headers = reads
+ headers[b"23"] = {"other": (1,), KEY: (4096, 9)}
+ path = tmp_path / "ltx.gguf"
+ path.write_bytes(b"23")
+ assert [video_ltx2.is_ltx23_checkpoint(p) for p in (path, str(path), path)] == [True] * 3
+ assert len(calls) == 1
+
+
+def test_a_rewritten_or_replaced_file_is_read_again(reads, tmp_path):
+ calls, headers = reads
+ headers[b"23"] = {KEY: (4096, 9)}
+ headers[b"20_"] = {KEY: (4096, 6)}
+ path = tmp_path / "ltx.gguf"
+ path.write_bytes(b"23")
+ assert video_ltx2.is_ltx23_checkpoint(path) is True
+ path.write_bytes(b"20_")
+ assert video_ltx2.is_ltx23_checkpoint(path) is False
+ other = tmp_path / "other.gguf"
+ other.write_bytes(b"23")
+ os.replace(other, path)
+ assert video_ltx2.is_ltx23_checkpoint(path) is True
+ assert len(calls) == 3
+
+
+def test_failures_are_not_kept(reads, tmp_path):
+ calls, headers = reads
+ path = tmp_path / "ltx.gguf"
+ path.write_bytes(b"23")
+ assert video_ltx2.is_ltx23_checkpoint(path) is False
+ headers[b"23"] = {KEY: (9, 4096)}
+ assert video_ltx2.is_ltx23_checkpoint(path) is True
+ assert len(calls) == 2
+
+
+def test_a_missing_path_is_not_cached_and_keeps_the_warning(reads, tmp_path):
+ calls, _ = reads
+ missing = tmp_path / "missing.gguf"
+ assert video_ltx2.is_ltx23_checkpoint(missing) is False
+ assert video_ltx2.is_ltx23_checkpoint(missing) is False
+ assert len(calls) == 2
+ assert video_ltx2._LTX23_VERDICTS == {}
+
+
+def test_a_symlink_shares_its_targets_verdict(reads, tmp_path):
+ calls, headers = reads
+ headers[b"23"] = {KEY: (9, 4096)}
+ blob = tmp_path / "blob"
+ blob.write_bytes(b"23")
+ link = tmp_path / "ltx.safetensors"
+ try:
+ link.symlink_to(blob)
+ except (OSError, NotImplementedError):
+ pytest.skip("os.symlink unavailable here (e.g. Windows without Developer Mode)")
+ assert video_ltx2.is_ltx23_checkpoint(link) is True
+ assert video_ltx2.is_ltx23_checkpoint(blob) is True
+ assert len(calls) == 1
+
+
+def test_first_matching_table_decides_and_no_table_is_false(reads, tmp_path):
+ calls, headers = reads
+ headers[b"a"] = {"x." + KEY: (6, 1), "y." + KEY: (9, 1)}
+ headers[b"bb"] = {"unrelated": (9,)}
+ a, b = tmp_path / "a.gguf", tmp_path / "b.gguf"
+ a.write_bytes(b"a")
+ b.write_bytes(b"bb")
+ for _ in range(2):
+ assert video_ltx2.is_ltx23_checkpoint(a) is False
+ assert video_ltx2.is_ltx23_checkpoint(b) is False
+ assert len(calls) == 2
+
+
+def test_the_cache_is_bounded(reads, tmp_path, monkeypatch):
+ calls, headers = reads
+ monkeypatch.setattr(video_ltx2, "_LTX23_VERDICTS_MAX", 4, raising = False)
+ headers[b"23"] = {KEY: (9, 1)}
+ for i in range(10):
+ p = tmp_path / f"{i}.gguf"
+ p.write_bytes(b"23")
+ assert video_ltx2.is_ltx23_checkpoint(p) is True
+ assert len(video_ltx2._LTX23_VERDICTS) <= 4
+
+
+def test_real_gguf_and_safetensors_headers(tmp_path, monkeypatch):
+ """The real readers, counted: a second probe of either format reads nothing."""
+ gguf = pytest.importorskip("gguf")
+ np = pytest.importorskip("numpy")
+ safetensors_numpy = pytest.importorskip("safetensors.numpy")
+ monkeypatch.setattr(video_ltx2, "_LTX23_VERDICTS", {}, raising = False)
+ tensors = {
+ KEY: np.zeros((9, 8), dtype = np.float16),
+ "blocks.0.w": np.zeros((4, 4), dtype = np.float16),
+ }
+ st = tmp_path / "ltx.safetensors"
+ safetensors_numpy.save_file(tensors, str(st))
+ gg = tmp_path / "ltx.gguf"
+ writer = gguf.GGUFWriter(str(gg), "ltxv")
+ for name, value in tensors.items():
+ writer.add_tensor(name, value)
+ writer.write_header_to_file()
+ writer.write_kv_data_to_file()
+ writer.write_tensors_to_file()
+ writer.close()
+ real = video_ltx2.read_checkpoint_header
+ calls = []
+ monkeypatch.setattr(video_ltx2, "read_checkpoint_header", lambda p: calls.append(p) or real(p))
+ for _ in range(3):
+ assert video_ltx2.is_ltx23_checkpoint(st) is True
+ assert video_ltx2.is_ltx23_checkpoint(gg) is True
+ assert len(calls) == 2
diff --git a/studio/backend/tests/test_video_backend.py b/studio/backend/tests/test_video_backend.py
index dfb4d57d270..8d4a6a25067 100644
--- a/studio/backend/tests/test_video_backend.py
+++ b/studio/backend/tests/test_video_backend.py
@@ -1357,12 +1357,14 @@ def test_is_ltx23_checkpoint_gguf(monkeypatch, tmp_path):
"model.diffusion_model.transformer_blocks.0.scale_shift_table": (4096, 6),
}
)
+ path.write_bytes(b"xy")
assert is_ltx23_checkpoint(path) is False
def _boom(path):
raise RuntimeError("bad magic")
gguf.GGUFReader = _boom
+ path.write_bytes(b"xyz")
assert is_ltx23_checkpoint(path) is False