Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.
Python agentaichatgptdeepseekfine-tuninggemmaimage-generationllamallmllmsopenaipythonqwenreinforcement-learningself-hostedstable-diffusiontext-to-speechttsuiunsloth
# SPDX-License-Identifier: AGPL-3.0-only
# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
"""Offline VideoBackend lifecycle on fake torch/diffusers; signatures are explicit so gates run."""
import builtins
import contextlib
import json
import dataclasses
import functools
import inspect
import sys
import threading
import time
import types
from dataclasses import replace
from pathlib import Path
import pytest
try:
from ._sparse_file import extend_sparse
except (
ImportError
): # imported top-level by a sibling test, or by file path (test_h3_native_resident.py)
import importlib.util as _importlib_util
_sparse_spec = _importlib_util.spec_from_file_location(
"_studio_tests_sparse_file", Path(__file__).with_name("_sparse_file.py")
)
_sparse_module = _importlib_util.module_from_spec(_sparse_spec)
_sparse_spec.loader.exec_module(_sparse_module)
extend_sparse = _sparse_module.extend_sparse
import core.inference.video as video_module
from core.inference.diffusion_device import DiffusionDeviceTarget
from core.inference.video import (
VideoBackend,
_detect_load_family,
get_video_backend,
resolve_video_model_kind,
)
from core.inference.video_families import VIDEO_CANCELLED_MSG, VIDEO_NOT_LOADED_MSG
def _shared_setup_1(tmp_path):
import core.inference.video as video_mod
backend = VideoBackend()
_load_gguf(backend, tmp_path)
return backend, video_mod
def _shared_setup_2():
pytest.importorskip("av")
import base64
from core.inference.video_minimax_h3 import decode_h3_reference_video
return base64, decode_h3_reference_video
def _shared_setup_3():
from core.inference.video_minimax_h3 import H3_COMPONENT_REPO, H3_GGUF_REPO
# The third slot was the Comfy-Org repack the components came from; a video load never reads it any more.
return H3_COMPONENT_REPO, H3_GGUF_REPO, None
def _shared_setup_4(monkeypatch, tmp_path):
root = tmp_path / "sd-home" / "stable-diffusion.cpp"
(root / "sd-bin").mkdir(parents = True)
(root / ".unsloth-studio-owned").touch()
monkeypatch.setenv("UNSLOTH_STUDIO_HOME", str(tmp_path / "sd-home" / "studio"))
managed = root / "sd-bin" / "sd-cli"
return managed
def _shared_setup_5(backend, fam):
backend._run_load_h3_native(
fam = fam,
token = None,
cancel_event = threading.Event(),
repo_id = "leejet/MiniMax-H3-GGUF",
gguf_filename = "minimax_h3_fl2va-Q4_K_M.gguf",
)
def _shared_setup_6(backend, monkeypatch):
monkeypatch.setattr(
type(backend._state.pipe),
"__call__",
_failing_pipe_call(RuntimeError("CUDA out of memory. Tried to allocate 66.54 GiB.")),
)
def _shared_setup_7(monkeypatch, video_mod):
real_plan = video_mod.plan_diffusion_memory
monkeypatch.setattr(
video_mod,
"plan_diffusion_memory",
lambda **kwargs: dataclasses.replace(real_plan(**kwargs), offload_policy = "model"),
)
def _shared_setup_8(_download, gpu_arbiter, monkeypatch):
monkeypatch.setattr("utils.hf_xet_fallback.hf_hub_download_with_xet_fallback", _download)
monkeypatch.setattr(gpu_arbiter, "_owner", gpu_arbiter.VIDEO)
backend = _run_h3_native_load()
assert backend._state is not None
return backend
def _shared_setup_9(monkeypatch):
from core.inference.video_families import detect_video_family
scale = _allow_te_prequant(monkeypatch)
transformer_gb, text_encoder_gb, vae_gb = detect_video_family(
"Lightricks/LTX-2"
).bf16_components_gb
return scale, text_encoder_gb, transformer_gb, vae_gb
def _shared_setup_10(backend, monkeypatch):
records = _capture_generate_failures(monkeypatch)
with pytest.raises(RuntimeError):
backend.generate(prompt = "a clip")
return records
def _shared_setup_11(monkeypatch, sd_cpp_backend):
monkeypatch.setattr(
sd_cpp_backend,
"ensure_sd_cpp_binary",
lambda *, allow_install, accelerator: "/existing/sd-cli",
)
def _shared_setup_12(_download, monkeypatch):
monkeypatch.setattr("utils.hf_xet_fallback.hf_hub_download_with_xet_fallback", _download)
backend = VideoBackend()
fam = _detect_load_family("leejet/MiniMax-H3-GGUF", None, "minimax-h3")
assert fam is not None
return backend, fam
@pytest.fixture(autouse = True)
def _pin_video_fetch_to_the_named_repo(monkeypatch):
"""These tests are about plan / load decisions, written against the UPSTREAM ids their fake Hub serves. The fetch
swap onto the unsloth mirrors depends on the developer's own HF cache, so it is pinned off here, as the image
offline-load tests do; tests/test_video_unsloth_mirrors.py covers the swap itself."""
monkeypatch.setenv("UNSLOTH_DIFFUSION_NO_MIRROR", "1")
@pytest.fixture(autouse = True)
def _roomy_host_ram(monkeypatch):
"""Native H3 loads fit against the host's available RAM, which a CI runner may not have (macos-15: about 3 GiB).
Tests that need a tight host stub usable_host_ram_mib themselves, after this."""
from utils import host_memory
monkeypatch.setattr(host_memory, "usable_host_ram_mib", lambda *a, **k: 1 << 30)
@pytest.fixture(autouse = True)
def _assume_the_restricted_load_is_available(monkeypatch):
"""A checkpoint only deserializes where torchao is importable, which here it may not be. These
tests are about the load/plan decisions; the capability is covered in
test_diffusion_prequant.py."""
import core.inference.diffusion_prequant as _pq
monkeypatch.setattr(
_pq, "restricted_prequant_load_supported", lambda scheme = None, filename = None: True
)
video_module._video_family_capabilities.cache_clear()
yield
video_module._video_family_capabilities.cache_clear()
class _FakeDtype:
def __init__(self, name: str) -> None:
self._name = name
def __repr__(self) -> str:
return f"torch.{self._name}"
__str__ = __repr__
class _FakeGenerator:
def __init__(self, device = None) -> None:
self.device = device
self.manual = None
def seed(self) -> int:
return 4242
def manual_seed(self, value: int):
self.manual = value
return self
class _FakeVae:
def __init__(self) -> None:
self.tiled = False
def enable_tiling(self) -> None:
self.tiled = True
class _FakePipe:
def __init__(self) -> None:
self.moved_to = None
self.vae = _FakeVae()
self.last_kwargs = None
self._interrupt = False
def to(self, device):
self.moved_to = device
return self
def enable_vae_tiling(self) -> None:
self.vae.tiled = True
# Explicit signature so generate() signature-gated kwargs actually engage; **kwargs would defeat the gates.
def __call__(
self,
*,
prompt = None,
negative_prompt = None,
num_inference_steps = None,
guidance_scale = None,
width = None,
height = None,
num_frames = None,
frame_rate = None,
generator = None,
sigmas = None,
callback_on_step_end = None,
**kwargs,
):
self.last_kwargs = {
"prompt": prompt,
"negative_prompt": negative_prompt,
"num_inference_steps": num_inference_steps,
"guidance_scale": guidance_scale,
"width": width,
"height": height,
"num_frames": num_frames,
"frame_rate": frame_rate,
"sigmas": sigmas,
"generator": generator,
**kwargs,
}
if callback_on_step_end is not None:
for step in range(int(num_inference_steps or 1)):
callback_on_step_end(self, step, 0, {})
if self._interrupt:
break
frames = [[object() for _ in range(int(num_frames or 1))]]
return types.SimpleNamespace(frames = frames, audio = None)
class _FakePipeline:
last: dict = {}
@classmethod
def from_pretrained(cls, base, **kwargs):
_FakePipeline.last = {"base": base, **kwargs}
return _FakePipe()
class _FakeTransformer:
last: dict = {}
@classmethod
def from_single_file(cls, path, **kwargs):
_FakeTransformer.last = {"path": path, **kwargs}
return object()
# Wan2.2 fakes: per-DiT trackable transformer; the MoE __call__ carries guidance_scale_2.
class FirstBlockCacheConfig: # noqa: N801 - the name diffusers exports, and what the cache layer matches on
def __init__(self, threshold = None) -> None:
self.threshold = threshold
class _FakeWanDiT:
"""Stub Wan denoiser recording the optimisation helpers applied, to prove both experts got them."""
def __init__(self) -> None:
self.compiled = False
self.cache_config = None
self.attention = None
def compile_repeated_blocks(self, **kwargs) -> None:
self.compiled = True
def enable_cache(self, config) -> None:
self.cache_config = config
# Cache teardown reads the live config diffusers records on the module.
self._cache_config = config
self.is_cache_enabled = True
def disable_cache(self) -> None:
self.cache_config = None
self._cache_config = None
self.is_cache_enabled = False
def set_attention_backend(self, backend) -> None:
self.attention = backend
@contextlib.contextmanager
def cache_context(self, name):
# Real pipelines open a cache_context around the denoise loop for the First-Block-Cache hook, so the fake provides one.
yield
class _FakeWanDecoder:
def __init__(self) -> None:
self.hooks: list = []
def register_forward_hook(self, hook):
self.hooks.append(hook)
class _FakeWanVae:
def __init__(self) -> None:
self.tiled = False
self.decoder = _FakeWanDecoder()
self.decodes = 0
# Fired from INSIDE the real decode, where the phase must already say "decode".
self.on_decode = None
self.decode_raises = None
def decode(self, *args, **kwargs):
self.decodes += 1
if self.on_decode is not None:
self.on_decode()
if self.decode_raises is not None:
raise self.decode_raises
return object()
def enable_tiling(self) -> None:
self.tiled = True
def to(self, *args, **kwargs):
return self
class _FakeWanPipeBase:
"""Shared Wan pipeline state; subclasses give __call__ an explicit signature the gates inspect."""
moe: bool = False
def __init__(self) -> None:
self.vae = _FakeWanVae()
self.transformer = _FakeWanDiT()
self.transformer_2 = _FakeWanDiT() if self.moe else None
self.components = {"transformer": self.transformer, "vae": self.vae}
if self.moe:
self.components["transformer_2"] = self.transformer_2
self.moved_to = None
self.last_kwargs = None
self._interrupt = False
def to(self, device):
self.moved_to = device
return self
def enable_vae_tiling(self) -> None:
self.vae.tiled = True
def _finish(self, num_inference_steps, num_frames, callback_on_step_end):
if callback_on_step_end is not None:
for step in range(int(num_inference_steps or 1)):
callback_on_step_end(self, step, 0, {})
if self._interrupt:
break
if not self._interrupt:
self.vae.decode(object())
frames = [[object() for _ in range(int(num_frames or 1))]]
return types.SimpleNamespace(frames = frames, audio = None)
class _FakeWanPipeSingle(_FakeWanPipeBase):
"""Single-DiT Wan pipeline (TI2V-5B): NO guidance_scale_2 in the signature, so the
cfg2 gate must not thread it."""
moe = False
def __call__(
self,
*,
prompt = None,
negative_prompt = None,
num_inference_steps = None,
guidance_scale = None,
width = None,
height = None,
num_frames = None,
generator = None,
callback_on_step_end = None,
**kwargs,
):
self.last_kwargs = {
"prompt": prompt,
"negative_prompt": negative_prompt,
"num_inference_steps": num_inference_steps,
"guidance_scale": guidance_scale,
"width": width,
"height": height,
"num_frames": num_frames,
**kwargs,
}
with self.transformer.cache_context("cond"):
pass
return self._finish(num_inference_steps, num_frames, callback_on_step_end)
class _FakeWanPipeMoE(_FakeWanPipeBase):
"""Dual-DiT MoE Wan pipeline (A14B): guidance_scale_2 IS in the signature, matching
WanPipeline.__call__ in diffusers 0.39, so the cfg2 gate threads it."""
moe = True
def __call__(
self,
*,
prompt = None,
negative_prompt = None,
num_inference_steps = None,
guidance_scale = None,
guidance_scale_2 = None,
width = None,
height = None,
num_frames = None,
generator = None,
callback_on_step_end = None,
**kwargs,
):
self.last_kwargs = {
"prompt": prompt,
"negative_prompt": negative_prompt,
"num_inference_steps": num_inference_steps,
"guidance_scale": guidance_scale,
"guidance_scale_2": guidance_scale_2,
"width": width,
"height": height,
"num_frames": num_frames,
**kwargs,
}
with self.transformer.cache_context("cond"):
pass
return self._finish(num_inference_steps, num_frames, callback_on_step_end)
class _FakeWanPipelineSingle:
"""WanPipeline fake (from_pretrained). One class serves both families and picks the
single-DiT / dual-DiT pipe by the repo id, exactly as diffusers dispatches on the
repo's model_index.json (A14B lists transformer_2, TI2V-5B does not)."""
last: dict = {}
@classmethod
def from_pretrained(cls, repo, **kwargs):
_FakeWanPipelineSingle.last = {"repo": repo, **kwargs}
moe = "a14b" in str(repo).lower()
return _FakeWanPipeMoE() if moe else _FakeWanPipeSingle()
# HunyuanVideo-1.5 fakes: no guidance kwarg, no step callback, a guider carrying the CFG scale, and a scheduler.step-driven loop.
class _FakeHV15Scheduler:
def __init__(self) -> None:
self.calls = 0
self.on_step = None
def step(self, *args, **kwargs):
self.calls += 1
if self.on_step is not None:
self.on_step(self.calls)
return object()
class _FakeHV15Pipe:
def __init__(self) -> None:
self.vae = _FakeWanVae()
self.transformer = _FakeWanDiT()
self.scheduler = _FakeHV15Scheduler()
self.guider = types.SimpleNamespace(guidance_scale = 6.0)
self.components = {"transformer": self.transformer, "vae": self.vae}
self.moved_to = None
self.last_kwargs = None
self.hooks_freed = 0
def maybe_free_model_hooks(self):
self.hooks_freed += 1
def to(self, device):
self.moved_to = device
return self
def enable_vae_tiling(self) -> None:
self.vae.tiled = True
def __call__(
self,
*,
prompt = None,
negative_prompt = None,
height = None,
width = None,
num_frames = None,
num_inference_steps = None,
generator = None,
**kwargs,
):
self.last_kwargs = {
"prompt": prompt,
"negative_prompt": negative_prompt,
"num_inference_steps": num_inference_steps,
"width": width,
"height": height,
"num_frames": num_frames,
**kwargs,
}
with self.transformer.cache_context("cond"):
pass
for _ in range(int(num_inference_steps or 1)):
self.scheduler.step()
# The real pipeline decodes inside __call__, so the decode phase comes from the decoder.
self.vae.decode(object())
frames = [[object() for _ in range(int(num_frames or 1))]]
return types.SimpleNamespace(frames = frames, audio = None)
class _FakeHV15Pipeline:
last: dict = {}
instance = None
@classmethod
def from_pretrained(cls, repo, **kwargs):
_FakeHV15Pipeline.last = {"repo": repo, **kwargs}
_FakeHV15Pipeline.instance = _FakeHV15Pipe()
return _FakeHV15Pipeline.instance
# MiniMax-H3 fakes: ModularPipeline takes no step callback; its loop drives
# pipe.scheduler.step, which the HV15 wrapper hooks.
class _FakeH3Scheduler:
def __init__(self) -> None:
self.calls = 0
self.on_step = None
def step(self, *args, **kwargs):
self.calls += 1
if self.on_step is not None:
self.on_step(self.calls)
return object()
class _FakeComponentsManager:
def __init__(self) -> None:
self.offload = None
def enable_auto_cpu_offload(self, **kwargs):
self.offload = kwargs
class _FakeModularPipe:
def __init__(self) -> None:
self.scheduler = _FakeH3Scheduler()
self.load_kwargs = None
self.last_kwargs = None
def load_components(self, **kwargs):
self.load_kwargs = kwargs
def __call__(
self,
*,
prompt = None,
num_inference_steps = None,
width = None,
height = None,
num_frames = None,
generator = None,
output = None,
**kwargs,
):
self.last_kwargs = {
"prompt": prompt,
"num_inference_steps": num_inference_steps,
"width": width,
"height": height,
"num_frames": num_frames,
"output": output,
**kwargs,
}
# As diffusers' MiniMaxH3Scheduler: grid points include the terminal 0.
for _ in range(int(num_inference_steps or 2) - 1):
self.scheduler.step(object(), 0, object())
return {"videos": [[object() for _ in range(int(num_frames or 1))]], "audio": None}
class _FakeModularPipeline:
last: dict = {}
instance = None
@classmethod
def from_pretrained(cls, path, **kwargs):
_FakeModularPipeline.last = {"path": path, **kwargs}
_FakeModularPipeline.instance = _FakeModularPipe()
return _FakeModularPipeline.instance
def _load_h3_modular(backend, *, hf_token = None):
"""Commit the H3 BF16 state exactly as load_pipeline's Modular Diffusers branch does."""
diffusers = sys.modules["diffusers"]
diffusers.ComponentsManager = _FakeComponentsManager
diffusers.ModularPipeline = _FakeModularPipeline
fam = _detect_load_family("MiniMaxAI/MiniMax-H3", None, "minimax-h3")
assert fam is not None
backend._load_h3_modular_pipeline(
diffusers = diffusers,
torch = sys.modules["torch"],
fam = fam,
repo_id = "MiniMaxAI/MiniMax-H3",
base = fam.base_repo,
kind = "pipeline",
dtype = sys.modules["torch"].bfloat16,
device = "cpu",
hf_token = hf_token,
memory_mode = None,
_load_token = None,
_base_local_dir = None,
)
return _FakeModularPipeline.instance
class _FakeLtx25Encoder:
def wait_ready(self, cancel = None):
return {}
def close(self):
pass
@pytest.fixture
def fake_runtime(monkeypatch):
torch = types.ModuleType("torch")
torch.bfloat16 = _FakeDtype("bfloat16")
torch.float16 = _FakeDtype("float16")
torch.float32 = _FakeDtype("float32")
torch.Generator = _FakeGenerator
torch.cuda = types.SimpleNamespace(is_available = lambda: False)
torch.backends = types.SimpleNamespace(mps = None)
torch.inference_mode = lambda: contextlib.nullcontext()
diffusers = types.ModuleType("diffusers")
diffusers.GGUFQuantizationConfig = lambda compute_dtype = None: ("quant", compute_dtype)
diffusers.LTX2Pipeline = _FakePipeline
diffusers.LTX2VideoTransformer3DModel = _FakeTransformer
# Wan2.2: one pipeline class serves both families (it dispatches on the repo id).
diffusers.WanPipeline = _FakeWanPipelineSingle
diffusers.WanTransformer3DModel = _FakeTransformer
diffusers.HunyuanVideo15Pipeline = _FakeHV15Pipeline
diffusers.HunyuanVideo15Transformer3DModel = _FakeTransformer
diffusers.Cosmos3OmniPipeline = _FakePipeline
diffusers.Cosmos3OmniTransformer = _FakeTransformer
# A CLASS named as diffusers names it: the cache layer matches on type(...).__name__.
diffusers.FirstBlockCacheConfig = FirstBlockCacheConfig
monkeypatch.setitem(sys.modules, "torch", torch)
monkeypatch.setitem(sys.modules, "diffusers", diffusers)
monkeypatch.setattr("core.inference.video.clear_gpu_cache", lambda: None)
# LTX-2.5's Gemma 4 encoder is a spawned worker on the transformers sidecar: never start one here.
monkeypatch.setattr(
"core.inference.video_ltx25.start_text_encoder", lambda **_kw: _FakeLtx25Encoder()
)
monkeypatch.setattr("core.inference.video_ltx25.attach_to_pipeline", lambda *_a, **_kw: None)
# MP4 encode needs real frames + PyAV; the contract under test is the byte handoff, so stub the encoder.
monkeypatch.setattr(
VideoBackend, "_encode_mp4", staticmethod(lambda frames, fps, audio, pipe: b"MP4")
)
_FakePipeline.last = {}
_FakeTransformer.last = {}
yield
def _load_gguf(backend, tmp_path):
(tmp_path / "model.gguf").write_bytes(b"weights")
return backend.load_pipeline(
str(tmp_path),
gguf_filename = "model.gguf",
base_repo = "Lightricks/LTX-2",
family_override = "ltx-2",
)
def _stub_apply_memory_plan(
monkeypatch,
video_mod,
*,
policy = "model",
vae_tiling = True,
) -> list:
"""Spells out keywords, not **kwargs, so a placement_device mismatch fails as a TypeError."""
calls = []
def _fake(
pipe,
plan,
*,
device = None,
placement_device = None,
logger = None,
):
calls.append({"device": device, "placement_device": placement_device})
return (policy, vae_tiling)
monkeypatch.setattr(video_mod, "apply_memory_plan", _fake)
return calls
def _assert_placement_follows_the_target(calls, video_mod):
"""Placement gets the INDEXED device off the resolved target, the policy string stays bare."""
target = video_mod.resolve_diffusion_device_target()
assert calls, "apply_memory_plan was never called"
assert calls[0]["placement_device"] == target.torch_device
assert calls[0]["device"] == target.device
def test_resolve_kind():
assert resolve_video_model_kind("x.gguf", None) == "gguf"
assert resolve_video_model_kind("x.safetensors", None) == "single_file"
assert resolve_video_model_kind(None, None) == "pipeline"
with pytest.raises(ValueError):
resolve_video_model_kind(None, "bogus")
def test_validate_rejects_unknown_and_untrusted():
backend = VideoBackend()
with pytest.raises(ValueError, match = "not a supported"):
backend.validate_load_request("someorg/some-image-model")
# A known family but an untrusted repo id must not open from_pretrained.
with pytest.raises(ValueError, match = "limited to"):
backend.validate_load_request("evil/ltx-2-repack")
# GGUF loads stay open to any repo (single-file read, no pickle).
fam = backend.validate_load_request(
"anyorg/ltx-2-GGUF", gguf_filename = "x.gguf", model_kind = "gguf"
)
assert fam.name == "ltx-2"
with pytest.raises(ValueError, match = "filename"):
backend.validate_load_request("unsloth/LTX-2.3-GGUF", model_kind = "gguf")
def test_validate_gates_base_repo_and_local_paths(tmp_path):
backend = VideoBackend()
# An arbitrary remote base_repo must not reach from_pretrained via a GGUF pick.
with pytest.raises(ValueError, match = "base_repo"):
backend.validate_load_request(
"unsloth/LTX-2.3-GGUF",
gguf_filename = "x.gguf",
model_kind = "gguf",
base_repo = "evil/companions",
)
fam = backend.validate_load_request(
"unsloth/LTX-2.3-GGUF",
gguf_filename = "x.gguf",
model_kind = "gguf",
base_repo = "Lightricks/LTX-2",
)
assert fam.name == "ltx-2"
with pytest.raises(ValueError):
backend.validate_load_request(
str(tmp_path), gguf_filename = "missing.gguf", family_override = "ltx-2"
)
with pytest.raises(ValueError, match = "does not exist"):
backend.validate_load_request(
str(tmp_path / "nope" / "model.gguf"),
gguf_filename = "model.gguf",
family_override = "ltx-2",
)
def test_validate_rejects_kind_extension_mismatch(tmp_path):
backend = VideoBackend()
# A kind/extension mismatch must be rejected BEFORE the GPU handoff, not fail in the wrong single-file loader after eviction.
with pytest.raises(ValueError, match = "needs model_kind 'gguf'"):
backend.validate_load_request(
"unsloth/LTX-2.3-GGUF",
gguf_filename = "x.gguf",
model_kind = "single_file",
family_override = "ltx-2",
)
with pytest.raises(ValueError, match = "requires a .gguf"):
backend.validate_load_request(
"unsloth/LTX-2.3",
gguf_filename = "x.safetensors",
model_kind = "gguf",
family_override = "ltx-2",
)
with pytest.raises(ValueError, match = "not a loadable single-file checkpoint"):
backend.validate_load_request(
"unsloth/LTX-2.3",
gguf_filename = "readme.md",
model_kind = "single_file",
family_override = "ltx-2",
)
def test_validate_rejects_local_file_suffix_kind_mismatch(tmp_path):
backend = VideoBackend()
# A local FILE ignores gguf_filename, so its own suffix must match the kind.
gguf_file = tmp_path / "ltx.gguf"
gguf_file.write_bytes(b"weights")
safetensors_file = tmp_path / "ltx.safetensors"
safetensors_file.write_bytes(b"weights")
with pytest.raises(ValueError, match = "not a .safetensors file"):
backend.validate_load_request(
str(gguf_file),
gguf_filename = "ltx.safetensors",
model_kind = "single_file",
family_override = "ltx-2",
)
with pytest.raises(ValueError, match = "not a .gguf file"):
backend.validate_load_request(
str(safetensors_file),
gguf_filename = "ltx.gguf",
model_kind = "gguf",
family_override = "ltx-2",
)
assert (
backend.validate_load_request(
str(gguf_file),
gguf_filename = "ltx.gguf",
model_kind = "gguf",
family_override = "ltx-2",
).name
== "ltx-2"
)
assert (
backend.validate_load_request(
str(safetensors_file),
gguf_filename = "ltx.safetensors",
model_kind = "single_file",
family_override = "ltx-2",
).name
== "ltx-2"
)
def test_validate_rejects_windows_shaped_missing_checkpoint(tmp_path):
backend = VideoBackend()
# A missing Windows-shaped local pick must fail HERE, not be treated as a Hub repo and fail after eviction.
with pytest.raises(ValueError, match = "does not exist"):
backend.validate_load_request(
"C:\\models\\ltx.gguf",
gguf_filename = "ltx.gguf",
family_override = "ltx-2",
)
fam = backend.validate_load_request(
"unsloth/LTX-2.3-GGUF",
gguf_filename = "ltx.gguf",
family_override = "ltx-2",
)
assert fam.name == "ltx-2"
def _write_pipeline(root, class_name, cls, **extra):
index = extra.pop("index", "model_index.json")
(root / "transformer").mkdir(parents = True, exist_ok = True)
manifest = {"_class_name": class_name, "transformer": ["diffusers", cls], **extra}
(root / index).write_text(json.dumps(manifest))
(root / "transformer" / "config.json").write_text("{}")
(root / "transformer" / "diffusion_pytorch_model.safetensors").write_bytes(b"x")
def test_validate_rejects_local_pipeline_without_model_index(tmp_path):
backend = VideoBackend()
d = tmp_path / "ltx-local"
(d / "transformer").mkdir(parents = True)
(d / "transformer" / "diffusion_pytorch_model.safetensors").write_bytes(b"x")
# A local dir missing model_index.json is not a loadable pipeline; it must fail preflight BEFORE eviction.
with pytest.raises(ValueError, match = "model_index.json"):
backend.validate_load_request(str(d), family_override = "ltx-2")
(d / "model_index.json").write_text("{}")
with pytest.raises(ValueError, match = "valid model_index.json"):
backend.validate_load_request(str(d), family_override = "ltx-2")
_write_pipeline(d, "LTX2Pipeline", "LTX2VideoTransformer3DModel")
fam = backend.validate_load_request(str(d), family_override = "ltx-2")
assert fam.name == "ltx-2"
def test_validate_modular_family_requires_modular_manifest(tmp_path, fake_runtime, monkeypatch):
backend = VideoBackend()
root = tmp_path / "opaque-h3"
_write_pipeline(root, "LTX2Pipeline", "LTX2Transformer")
original_import = builtins.__import__
def _no_diffusers_import(name, *args, **kwargs):
if name == "diffusers" or name.startswith("diffusers."):
raise ModuleNotFoundError(f"No module named '{name}'", name = name)
return original_import(name, *args, **kwargs)
with monkeypatch.context() as no_diffusers:
no_diffusers.delitem(sys.modules, "diffusers")
no_diffusers.setattr(builtins, "__import__", _no_diffusers_import)
with pytest.raises(ValueError, match = "modular_model_index.json"):
backend.validate_load_request(str(root), family_override = "minimax-h3")
diffusers = sys.modules["diffusers"]
diffusers.ModularPipeline = _FakeModularPipeline
diffusers.MiniMaxH3Transformer3DModel = _FakeTransformer
(root / "modular_model_index.json").write_text("{}")
with pytest.raises(ValueError, match = "valid modular_model_index.json"):
backend.validate_load_request(str(root), family_override = "minimax-h3")
_write_pipeline(
root,
"ModularPipeline",
"MiniMaxH3Transformer3DModel",
index = "modular_model_index.json",
_blocks_class_name = "HunyuanVideo15PipelineBlocks",
)
fam = backend.validate_load_request(str(root), family_override = "minimax-h3")
assert fam.name == "minimax-h3"
def test_validate_rejects_local_file_picked_as_pipeline(tmp_path):
backend = VideoBackend()
# A local FILE sent as a pipeline is not a diffusers directory, so gate on .exists() (not .is_dir()) to catch files too.
f = tmp_path / "ltx-2.safetensors"
f.write_bytes(b"x")
with pytest.raises(ValueError, match = "model_index.json"):
backend.validate_load_request(str(f), model_kind = "pipeline", family_override = "ltx-2")
def test_validate_rejects_local_base_repo_without_model_index(tmp_path):
backend = VideoBackend()
# A local base_repo dir that is NOT a diffusers pipeline passes the trust check but loads via from_pretrained, so reject it here.
bad_base = tmp_path / "bare-base"
bad_base.mkdir()
with pytest.raises(ValueError, match = "model_index.json"):
backend.validate_load_request(
"unsloth/LTX-2.3-GGUF",
gguf_filename = "x.gguf",
model_kind = "gguf",
base_repo = str(bad_base),
)
_write_pipeline(
bad_base,
"LTX2Pipeline",
"LTX2VideoTransformer3DModel",
scheduler = ["diffusers", "FlowMatchEulerDiscreteScheduler"],
)
(bad_base / "transformer" / "diffusion_pytorch_model.safetensors").unlink()
(bad_base / "scheduler").mkdir()
(bad_base / "scheduler" / "scheduler_config.json").write_text("{}")
fam = backend.validate_load_request(
"unsloth/LTX-2.3-GGUF",
gguf_filename = "x.gguf",
model_kind = "gguf",
base_repo = str(bad_base),
)
assert fam.name == "ltx-2"
with pytest.raises(ValueError, match = "valid model_index.json"):
backend.validate_load_request(str(bad_base), model_kind = "pipeline", family_override = "ltx-2")
def test_validate_rejects_gguf_repo_as_pipeline():
backend = VideoBackend()
# A -GGUF repo with no quant filename resolves to pipeline kind and would only fail minutes later, after eviction.
with pytest.raises(ValueError, match = "pick one of its .gguf files"):
backend.validate_load_request("unsloth/LTX-2.3-GGUF")
with pytest.raises(ValueError, match = "pick one of its .gguf files"):
backend.validate_load_request("unsloth/Wan2.2-TI2V-5B-GGUF/")
def test_detect_load_family_filename_fallback():
fam = _detect_load_family("Lightricks/LTX-2", None, None)
assert fam is not None and fam.name == "ltx-2"
# Repo id is opaque but the picked filename carries the family: fall back to the combined path so validate and _run_load agree.
fam = _detect_load_family("someorg/quants", "ltx-2-19b-Q4_K_M.gguf", None)
assert fam is not None and fam.name == "ltx-2"
assert _detect_load_family("someorg/quants", None, None) is None
# An explicit override resolves by name/alias and skips the filename fallback: a bogus override stays None.
fam = _detect_load_family("someorg/quants", "ltx-2-19b-Q4_K_M.gguf", "ltxv")
assert fam is not None and fam.name == "ltx-2"
assert _detect_load_family("someorg/quants", "ltx-2-19b-Q4_K_M.gguf", "bogus") is None
def test_detect_load_family_uses_logical_id_for_an_opaque_pinned_snapshot():
fam = _detect_load_family("/cache/snapshots/deadbeef", None, None, "MiniMaxAI/MiniMax-H3")
assert fam is not None and fam.name == "minimax-h3"
# The logical id outranks a family token in the physical path.
fam = _detect_load_family("/cache/wan2.2/snapshots/deadbeef", None, None, "Lightricks/LTX-2")
assert fam is not None and fam.name == "ltx-2"
def test_detect_load_family_cached_hub_arch_fallback(monkeypatch):
# An opaque repo id and renamed GGUF file resolve the family from the cached blob's arch.
import huggingface_hub
import utils.models.gguf_metadata as gguf_meta
monkeypatch.setattr(
huggingface_hub,
"try_to_load_from_cache",
lambda repo_id, filename, **kw: "/fake/cache/blobs/model.gguf",
)
monkeypatch.setattr(gguf_meta, "read_gguf_architecture", lambda path: "ltxv")
fam = _detect_load_family("someorg/opaque-quants", "model.gguf", None)
assert fam is not None and fam.name == "ltx-2"
monkeypatch.setattr(huggingface_hub, "try_to_load_from_cache", lambda *a, **k: None)
assert _detect_load_family("someorg/opaque-quants", "model.gguf", None) is None
monkeypatch.setattr(
huggingface_hub, "try_to_load_from_cache", lambda *a, **k: "/fake/cache/blobs/model.gguf"
)
monkeypatch.setattr(gguf_meta, "read_gguf_architecture", lambda path: "wan")
assert _detect_load_family("someorg/opaque-quants", "model.gguf", None) is None
# The blob lives in a NON-active cache root: the active probe misses, but the per-root probe finds it.
import hub.utils.paths as hub_paths
monkeypatch.setattr(hub_paths, "legacy_hf_cache_dir", lambda: "/fake/legacy")
monkeypatch.setattr(hub_paths, "hf_default_cache_dir", lambda: "/fake/default")
monkeypatch.setattr(gguf_meta, "read_gguf_architecture", lambda path: "ltxv")
monkeypatch.setattr(
huggingface_hub,
"try_to_load_from_cache",
lambda repo_id, filename, cache_dir = None: (
"/fake/legacy/blobs/model.gguf" if cache_dir else None
),
)
fam = _detect_load_family("someorg/opaque-quants", "model.gguf", None)
assert fam is not None and fam.name == "ltx-2"
def test_loading_repo_ids_guards_in_flight_delete():
# During a background load status() is still False but the repo is downloading, so the delete guard needs loading_repo_ids.
from core.inference.video import _VideoLoadingState
backend = VideoBackend()
assert backend.loading_repo_ids() == ()
backend._loading = _VideoLoadingState(repo_id = "org/ckpt", base_repo = "Lightricks/LTX-2")
# The base's unsloth mirror too: that is the id the fetch actually pulls into.
assert set(backend.loading_repo_ids()) == {"org/ckpt", "Lightricks/LTX-2", "unsloth/LTX-2-FP8"}
# An errored load is no longer in flight, so the files are safe to delete.
backend._loading = _VideoLoadingState(
repo_id = "org/ckpt", base_repo = "Lightricks/LTX-2", error = "boom"
)
assert backend.loading_repo_ids() == ()
backend._loading = _VideoLoadingState(repo_id = "org/ckpt", base_repo = "")
assert backend.loading_repo_ids() == ("org/ckpt",)
def test_load_generate_unload_gguf(fake_runtime, tmp_path):
backend = VideoBackend()
status = _load_gguf(backend, tmp_path)
assert status["loaded"] is True and status["family"] == "ltx-2"
assert status["model_kind"] == "gguf"
assert status["has_audio"] is True
assert _FakeTransformer.last["path"].endswith("model.gguf")
assert _FakeTransformer.last["quantization_config"][0] == "quant"
assert _FakePipeline.last["base"] == "Lightricks/LTX-2"
assert "transformer" in _FakePipeline.last
# Video decode is the memory peak: tiling is always on.
assert status["vae_tiling"] is True
assert status["defaults"]["frame_step"] == 8
result = backend.generate(
prompt = "a sloth surfing", width = 1000, height = 700, num_frames = 120, fps = 24
)
call = backend._state.pipe.last_kwargs
# Shape snapping happened BEFORE the pipe call: /32 sizes, 8k+1 frames.
assert (call["width"], call["height"]) == (992, 672)
assert call["num_frames"] == 113
assert call["frame_rate"] == 24.0
assert result["mp4_bytes"] == b"MP4"
assert result["num_frames"] == 113 and result["fps"] == 24
assert result["has_audio"] is False
assert 0 <= result["seed"] < 2**53
status = backend.unload()
assert status["loaded"] is False
def test_generate_reclaims_model_offload_host_memory(fake_runtime, tmp_path, monkeypatch):
"""Video shares the image offload lifecycle, so host-allocator memory is reclaimed once per
successful 'model'-policy generation, after progress is cleared."""
from core.inference import video as video_mod
trace = []
monkeypatch.setattr(
video_mod,
"reclaim_offload_host_memory",
lambda policy, logger = None: trace.append(policy) or True,
)
backend = VideoBackend()
_load_gguf(backend, tmp_path)
for policy in ("none", "group", "streaming", "sequential", "model"):
backend._state = dataclasses.replace(backend._state, offload_policy = policy)
backend.generate(prompt = "a sloth surfing", width = 256, height = 256, num_frames = 9, fps = 8)
assert trace == ["none", "group", "streaming", "sequential", "model"]
from core.inference import diffusion_memory
monkeypatch.setattr(diffusion_memory, "_resolve_host_memory_reclaimer", lambda: lambda: None)
assert [diffusion_memory.reclaim_offload_host_memory(p) for p in trace] == [
False,
False,
False,
False,
True,
]
# Progress must already be idle: the trim can block for a few hundred ms.
assert backend.generate_progress()["active"] is False
def test_a_stop_during_the_reclaim_cannot_be_answered_true(fake_runtime, tmp_path, monkeypatch):
"""The trim blocks after the last is_set() check, so the event must be deregistered before the
trim, under cancel_generate's lock; a Stop in that window must not be answered true."""
from core.inference import video as video_mod
backend = VideoBackend()
_load_gguf(backend, tmp_path)
backend._state = dataclasses.replace(backend._state, offload_policy = "model")
answered = []
def stop_midway(policy, logger = None):
answered.append(backend.cancel_generate())
return True
monkeypatch.setattr(video_mod, "reclaim_offload_host_memory", stop_midway)
result = backend.generate(prompt = "a sloth surfing", width = 256, height = 256, num_frames = 9, fps = 8)
assert result["mp4_bytes"] == b"MP4"
assert answered == [False], "cancel_generate answered true for a clip that was still persisted"
def test_load_holds_generate_lock_across_placement(fake_runtime, tmp_path, monkeypatch):
# The load holds _generate_lock across GPU placement so unload cannot hand the GPU away.
import threading
from core.inference import video as video_mod
backend = VideoBackend()
placement_started = threading.Event()
release_placement = threading.Event()
real_apply = video_mod.apply_memory_plan
def blocking_apply(pipe, plan, **kw):
placement_started.set()
assert release_placement.wait(timeout = 5), "test placement barrier never released"
return real_apply(pipe, plan, **kw)
monkeypatch.setattr(video_mod, "apply_memory_plan", blocking_apply)
load_exc = []
def do_load():
try:
_load_gguf(backend, tmp_path)
except Exception as e: # noqa: BLE001 -- the concurrent unload supersedes this load
load_exc.append(e)
load_thread = threading.Thread(target = do_load)
load_thread.start()
assert placement_started.wait(timeout = 5), "load never reached placement"
# Placement is in flight, holding _generate_lock, so unload() must block on its barrier.
unload_done = []
def do_unload():
backend.unload()
unload_done.append(True)
unload_thread = threading.Thread(target = do_unload)
unload_thread.start()
unload_thread.join(timeout = 0.5)
assert not unload_done, "unload() returned while placement still held _generate_lock (the race)"
release_placement.set()
unload_thread.join(timeout = 5)
load_thread.join(timeout = 5)
assert unload_done, "unload() did not complete after placement released _generate_lock"
assert not load_thread.is_alive() and not load_exc
assert backend._state is None
def test_load_records_engaged_speed_optims(fake_runtime, tmp_path, monkeypatch):
# The fake runtime forces every optim False, so force one to engage.
from core.inference import video as video_mod
monkeypatch.setattr(
video_mod,
"apply_speed_optims",
lambda *a, **k: {"channels_last": True, "cudnn_benchmark": False},
)
backend = VideoBackend()
status = _load_gguf(backend, tmp_path)
assert status["loaded"] is True
assert status["speed_optims"] == ["channels_last"]
def test_generate_defaults_from_variant(fake_runtime, tmp_path):
backend = _load_ltx23_from_dir(tmp_path)
backend.generate(prompt = "a sloth")
call = backend._state.pipe.last_kwargs
assert call["num_inference_steps"] == 8
assert call["guidance_scale"] == 1.0
# At the distilled default step count the calibrated ltx_core curve is passed verbatim (the scheduler's own spacing lands far off).
from core.inference.video_ltx2 import LTX23_DISTILLED_SIGMAS
assert call["sigmas"] == list(LTX23_DISTILLED_SIGMAS)
@pytest.mark.parametrize("device, expected", [("mps", "cpu"), ("cuda", "cuda")])
def test_generate_seeds_metal_from_a_cpu_generator(fake_runtime, tmp_path, device, expected):
# Metal reproduces a seed only through a CPU generator.
backend = _load_ltx23_from_dir(tmp_path)
backend._state = dataclasses.replace(backend._state, device = device)
backend.generate(prompt = "a sloth", seed = 7)
assert backend._state.pipe.last_kwargs["generator"].device == expected
def test_ltx23_load_forwards_the_precast_encoder(fake_runtime, tmp_path, monkeypatch):
# The wiring half of the same bug: the 2.3 branch does not use pipe_kwargs, so the loader must pass the pre-cast encoder across explicitly.
from core.inference import diffusion_te_prequant, video_ltx2
# The CPU stub cannot cast the encoder; keep the silent fallback for this wiring test.
monkeypatch.setenv("UNSLOTH_DIFFUSION_ALLOW_PRECISION_FALLBACK", "1")
precast = object()
monkeypatch.setattr(
diffusion_te_prequant, "te_prequant_pipe_kwargs", lambda *a, **k: {"text_encoder": precast}
)
monkeypatch.setattr(video_ltx2, "is_ltx23_checkpoint", lambda path: True)
seen: dict = {}
def _assemble(checkpoint_path, **kwargs):
seen.update(kwargs)
return _FakePipeline.from_pretrained("Lightricks/LTX-2")
monkeypatch.setattr(video_ltx2, "load_ltx23_pipeline", _assemble)
(tmp_path / "ltx-2.3-22b-distilled-1.1-Q4_K_M.gguf").write_bytes(b"w")
backend = VideoBackend()
backend.load_pipeline(
str(tmp_path),
gguf_filename = "ltx-2.3-22b-distilled-1.1-Q4_K_M.gguf",
base_repo = "Lightricks/LTX-2",
family_override = "ltx-2",
text_encoder_quant = "fp8",
)
assert seen["text_encoder"] is precast
backend.unload()
def test_generate_distilled_custom_steps_keep_scheduler_spacing(fake_runtime, tmp_path):
backend = _load_ltx23_from_dir(tmp_path)
backend.generate(prompt = "a sloth", steps = 12)
call = backend._state.pipe.last_kwargs
assert call["num_inference_steps"] == 12
assert call["sigmas"] is None
def test_generate_dev_base_never_gets_distilled_sigmas(fake_runtime, tmp_path):
# The dev/base DiT uses the resolution-shifted scheduler spacing even at 8 steps: the calibrated list is distilled-only.
(tmp_path / "ltx-2.3-22b-dev-Q4_K_M.gguf").write_bytes(b"w")
backend = VideoBackend()
backend.load_pipeline(
str(tmp_path),
gguf_filename = "ltx-2.3-22b-dev-Q4_K_M.gguf",
base_repo = "Lightricks/LTX-2",
family_override = "ltx-2",
)
backend.generate(prompt = "a sloth", steps = 8)
call = backend._state.pipe.last_kwargs
assert call["num_inference_steps"] == 8
assert call["sigmas"] is None
def test_ltx23_verbatim_sigmas_restores_scheduler_config():
from core.inference.video_ltx2 import ltx23_verbatim_sigmas
class _Cfg(dict):
pass
class _Sched:
def __init__(self):
self.config = _Cfg(use_dynamic_shifting = True, shift = 1.0, shift_terminal = 0.1)
def register_to_config(self, **kw):
self.config.update(kw)
pipe = types.SimpleNamespace(scheduler = _Sched())
with ltx23_verbatim_sigmas(pipe):
assert pipe.scheduler.config["use_dynamic_shifting"] is False
assert pipe.scheduler.config["shift_terminal"] is None
assert pipe.scheduler.config["use_dynamic_shifting"] is True
assert pipe.scheduler.config["shift_terminal"] == 0.1
with pytest.raises(RuntimeError):
with ltx23_verbatim_sigmas(pipe):
raise RuntimeError("boom")
assert pipe.scheduler.config["use_dynamic_shifting"] is True
with ltx23_verbatim_sigmas(types.SimpleNamespace()):
pass
def test_generate_resets_step_cache_only_when_engaged(fake_runtime, tmp_path):
# Reset FBCache residuals on the DiTs only when a cache is engaged; transformer_2 if present.
import dataclasses
backend = _load_ltx23_from_dir(tmp_path)
resets = []
backend._state.pipe.transformer = types.SimpleNamespace(
_reset_stateful_cache = lambda: resets.append("transformer")
)
backend._state.pipe.transformer_2 = types.SimpleNamespace(
_reset_stateful_cache = lambda: resets.append("transformer_2")
)
backend.generate(prompt = "a sloth")
assert resets == []
backend._state = dataclasses.replace(backend._state, transformer_cache = "fbcache")
backend.generate(prompt = "a sloth")
assert resets == ["transformer", "transformer_2"]
def test_is_ltx23_checkpoint_gguf(monkeypatch, tmp_path):
# diffusers maps every LTX-2 single file to the 2.0 config; detect 2.3 from the header.
from core.inference.video_ltx2 import is_ltx23_checkpoint
def _reader_for(shapes):
tensors = [types.SimpleNamespace(name = n, shape = s) for n, s in shapes.items()]
return lambda path: types.SimpleNamespace(tensors = tensors)
gguf = types.ModuleType("gguf")
# GGUF headers store dims in GGML (reversed) order.
gguf.GGUFReader = _reader_for(
{
"model.diffusion_model.transformer_blocks.0.scale_shift_table": (4096, 9),
}
)
monkeypatch.setitem(sys.modules, "gguf", gguf)
path = tmp_path / "ltx23.gguf"
path.write_bytes(b"x")
assert is_ltx23_checkpoint(path) is True
gguf.GGUFReader = _reader_for(
{
"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
def test_is_ltx23_checkpoint_safetensors(monkeypatch, tmp_path):
from core.inference.video_ltx2 import is_ltx23_checkpoint
class _FakeSlice:
def __init__(self, shape):
self._shape = shape
def get_shape(self):
return self._shape
class _FakeSafe:
def __init__(self, shapes):
self._shapes = shapes
def __enter__(self):
return self
def __exit__(self, *args):
return False
def keys(self):
return list(self._shapes)
def get_slice(self, name):
return _FakeSlice(self._shapes[name])
shapes = {
"model.diffusion_model.transformer_blocks.0.scale_shift_table": (9, 4096),
}
safetensors = types.ModuleType("safetensors")
safetensors.safe_open = lambda path, framework = None: _FakeSafe(shapes)
monkeypatch.setitem(sys.modules, "safetensors", safetensors)
path = tmp_path / "ltx23.safetensors"
path.write_bytes(b"x")
assert is_ltx23_checkpoint(path) is True
def test_ltx23_split_and_variant(tmp_path):
from core.inference.video_ltx2 import _split_checkpoint, checkpoint_variant
state = {
"model.diffusion_model.transformer_blocks.0.attn1.to_q.weight": 1,
"model.diffusion_model.video_embeddings_connector.learnable_registers": 2,
"model.diffusion_model.prompt_adaln_single.linear.weight": 3,
"text_embedding_projection.video_aggregate_embed.weight": 4,
"vae.decoder.conv_in.weight": 5,
"audio_vae.encoder.conv_in.weight": 6,
"vocoder.bwe_generator.conv_pre.weight": 7,
}
groups = _split_checkpoint(state)
assert set(groups["dit"]) == {
"transformer_blocks.0.attn1.to_q.weight",
"prompt_adaln_single.linear.weight",
}
assert set(groups["connectors"]) == {
"video_embeddings_connector.learnable_registers",
"text_embedding_projection.video_aggregate_embed.weight",
}
assert groups["vae"] == {"decoder.conv_in.weight": 5}
assert groups["audio_vae"] == {"encoder.conv_in.weight": 6}
assert groups["vocoder"] == {"bwe_generator.conv_pre.weight": 7}
assert checkpoint_variant("x/ltx-2.3-22b-distilled-1.1-Q4_K_M.gguf") == "distilled"
assert checkpoint_variant("x/ltx-2.3-22b-dev-Q8_0.gguf") == "dev"
def test_ltx23_scaled_fp8_refused(monkeypatch, tmp_path):
# The fp8 files carry scale companions, so a plain dtype cast would corrupt them.
from core.inference import video_ltx2
# Stub the module tree so this also runs under the CI sim, which blocks the real diffusers import.
diffusers = types.ModuleType("diffusers")
diffusers.LTX2Pipeline = object
loaders = types.ModuleType("diffusers.loaders")
sfu = types.ModuleType("diffusers.loaders.single_file_utils")
sfu.load_single_file_checkpoint = lambda path: {
"model.diffusion_model.transformer_blocks.0.attn1.to_q.weight": object(),
"model.diffusion_model.transformer_blocks.0.attn1.to_q.weight_scale": object(),
}
diffusers.loaders = loaders
loaders.single_file_utils = sfu
monkeypatch.setitem(sys.modules, "diffusers", diffusers)
monkeypatch.setitem(sys.modules, "diffusers.loaders", loaders)
monkeypatch.setitem(sys.modules, "diffusers.loaders.single_file_utils", sfu)
monkeypatch.setitem(sys.modules, "transformers", types.ModuleType("transformers"))
path = tmp_path / "ltx-2.3-22b-distilled-fp8.safetensors"
path.write_bytes(b"x")
with pytest.raises(ValueError, match = "scaled fp8"):
video_ltx2.load_ltx23_pipeline(
path, base_repo = "Lightricks/LTX-2", torch_dtype = None, is_gguf = False
)
def _ltx23_assembly_stubs(monkeypatch, tmp_path):
"""Module tree + component loaders for a 2.3 assembly, so only the encoder choice is under test."""
from core.inference import video_ltx2
class _Loaded:
def __init__(self, what: str) -> None:
self.what = what
@classmethod
def from_pretrained(
cls,
base,
subfolder = None,
token = None,
**extra,
):
_Loaded.calls.append(subfolder)
return cls(subfolder or "?")
_Loaded.calls = []
class _FakeLTX2Pipeline:
last: dict = {}
def __init__(self, **kwargs):
_FakeLTX2Pipeline.last = kwargs
@staticmethod
# Exact signature so it follows production: this base-repo read must not become a fetch.
def load_config(
base_repo,
token = None,
local_files_only = False,
cache_dir = None,
):
_FakeLTX2Pipeline.last_config_kwargs = {
"local_files_only": local_files_only,
# Pinned to the LIVE root: huggingface_hub's import-time constant goes stale.
"cache_dir": cache_dir,
}
return {
"scheduler": ["diffusers", "_Loaded"],
"tokenizer": ["transformers", "_Loaded"],
"text_encoder": ["transformers", "_Loaded"],
}
diffusers = types.ModuleType("diffusers")
diffusers.LTX2Pipeline = _FakeLTX2Pipeline
diffusers._Loaded = _Loaded
loaders = types.ModuleType("diffusers.loaders")
sfu = types.ModuleType("diffusers.loaders.single_file_utils")
sfu.load_single_file_checkpoint = lambda path: {
"model.diffusion_model.transformer_blocks.0.attn1.to_q.weight": object(),
}
diffusers.loaders = loaders
loaders.single_file_utils = sfu
transformers = types.ModuleType("transformers")
transformers._Loaded = _Loaded
monkeypatch.setitem(sys.modules, "diffusers", diffusers)
monkeypatch.setitem(sys.modules, "diffusers.loaders", loaders)
monkeypatch.setitem(sys.modules, "diffusers.loaders.single_file_utils", sfu)
monkeypatch.setitem(sys.modules, "transformers", transformers)
monkeypatch.setattr(video_ltx2, "load_ltx23_transformer", lambda *a, **k: "dit")
monkeypatch.setattr(video_ltx2, "load_ltx23_connectors", lambda *a, **k: "connectors")
monkeypatch.setattr(video_ltx2, "load_ltx23_vae", lambda *a, **k: "vae")
monkeypatch.setattr(
video_ltx2, "load_ltx23_audio_vae_and_vocoder", lambda *a, **k: ("audio_vae", "vocoder")
)
path = tmp_path / "ltx-2.3-22b-distilled-Q4_K_M.gguf"
path.write_bytes(b"x")
return video_ltx2, _FakeLTX2Pipeline, _Loaded, path
def test_ltx23_assembly_takes_a_supplied_text_encoder(monkeypatch, tmp_path):
# The 2.3 assembly builds every component itself, so an fp8 request only reaches it through this argument.
video_ltx2, pipeline_cls, loaded, path = _ltx23_assembly_stubs(monkeypatch, tmp_path)
precast = object()
video_ltx2.load_ltx23_pipeline(
path,
base_repo = "Lightricks/LTX-2",
torch_dtype = None,
is_gguf = True,
text_encoder = precast,
)
assert pipeline_cls.last["text_encoder"] is precast
assert loaded.calls == ["scheduler", "tokenizer"]
loaded.calls.clear()
video_ltx2.load_ltx23_pipeline(
path, base_repo = "Lightricks/LTX-2", torch_dtype = None, is_gguf = True
)
assert loaded.calls == ["scheduler", "tokenizer", "text_encoder"]
assert isinstance(pipeline_cls.last["text_encoder"], loaded)
def test_generate_without_load_raises(fake_runtime):
backend = VideoBackend()
with pytest.raises(RuntimeError, match = VIDEO_NOT_LOADED_MSG):
backend.generate(prompt = "x")
def test_generate_progress_and_cancel_idle(fake_runtime):
backend = VideoBackend()
# The idle shape carries the image-endpoint aliases (total_steps / fraction) so one poller works against both APIs.
assert backend.generate_progress() == {"active": False, "total_steps": 0, "fraction": 0.0}
assert backend.cancel_generate() is False
def test_generate_progress_derives_total_steps_and_fraction(fake_runtime):
backend = VideoBackend()
backend._gen = {"active": True, "phase": "denoise", "step": 5, "total": 20}
gen = backend.generate_progress()
assert gen["total"] == 20 and gen["total_steps"] == 20
assert gen["step"] == 5 and gen["fraction"] == 0.25
@pytest.mark.parametrize(
"video, error, total, expected",
[
(
{"id": "clip-1"},
None,
12,
{
"phase": "completed",
"percent": 100,
"step": 12,
"total_steps": 12,
"video_id": "clip-1",
},
),
(
None,
"negative_prompt is not supported by this family.",
0,
{
"phase": "failed",
"percent": 0,
"step": 0,
"total_steps": 0,
"error": "negative_prompt is not supported by this family.",
},
),
],
)
def test_finish_generate_job_logs_each_terminal_outcome_once(
fake_runtime, monkeypatch, video, error, total, expected
):
import core.inference.video as video_mod
events = []
class _Recorder:
def info(self, event, **fields):
events.append((event, fields))
monkeypatch.setattr(video_mod, "logger", _Recorder())
backend = VideoBackend()
token = object()
backend._generate_job_token = token
backend._generate_job_active = True
backend._finish_generate_job(job_token = token, video = video, error = error, total = total)
backend._finish_generate_job(job_token = token, video = video, error = error, total = total)
assert events == [("video_generation_progress", expected)]
def test_failed_background_generate_retains_terminal_error(fake_runtime, tmp_path, monkeypatch):
# A page mounted AFTER a background job failed reads the outcome from this retained terminal record, so a failure must stay pollable until the next job.
backend = VideoBackend()
_load_gguf(backend, tmp_path)
def _boom(
self,
*,
prompt = None,
negative_prompt = None,
num_inference_steps = None,
guidance_scale = None,
width = None,
height = None,
num_frames = None,
frame_rate = None,
generator = None,
callback_on_step_end = None,
**kwargs,
):
raise ValueError("frames exceed the device memory")
monkeypatch.setattr(type(backend._state.pipe), "__call__", _boom)
backend.begin_generate(prompt = "a clip")
deadline = time.monotonic() + 10
while backend.generate_progress()["active"] and time.monotonic() < deadline:
time.sleep(0.01)
gen = backend.generate_progress()
assert gen["active"] is False
assert gen["phase"] == "failed"
assert gen["error"] == "frames exceed the device memory"
assert backend.generate_progress()["phase"] == "failed"
def test_a_stopped_generation_ticket_cancels_the_video_job(fake_runtime, tmp_path, monkeypatch):
from core.inference.generation_ticket import GenerationTicket, generation_ticket
backend = VideoBackend()
_load_gguf(backend, tmp_path)
running, stopped, pipe = threading.Event(), threading.Event(), type(backend._state.pipe)
@functools.wraps(pipe.__call__) # its signature says which arguments to pass
def _hold(self, *_args, **_kwargs):
running.set()
if backend._active_generate_cancel.wait(10):
stopped.set()
raise ValueError("stopped")
monkeypatch.setattr(pipe, "__call__", _hold)
with generation_ticket(ticket := GenerationTicket()):
backend.begin_generate(prompt = "a clip")
assert running.wait(10) and ticket.stop() is True and stopped.wait(10)
def test_cache_bytes_counts_incomplete_blobs(fake_runtime, tmp_path, monkeypatch):
# scan_cache_dir skips *.incomplete blobs; count both, without double-counting symlinks.
import core.inference.video as video_mod
repo_dir = tmp_path / "models--Wan-AI--Wan2.2-TI2V-5B-Diffusers"
blobs = repo_dir / "blobs"
blobs.mkdir(parents = True)
(blobs / "aa11").write_bytes(b"x" * 1000)
(blobs / "bb22.incomplete").write_bytes(b"y" * 500)
snap = repo_dir / "snapshots" / "deadbeef"
snap.mkdir(parents = True)
(snap / "model_index.json").symlink_to(blobs / "aa11") # must not double-count
# The live cache root, not huggingface_hub's import-time constant: the counter must follow a mid-session cache change.
monkeypatch.setattr(video_mod, "hub_cache_dir", lambda: str(tmp_path))
backend = VideoBackend()
assert backend._cache_bytes("Wan-AI/Wan2.2-TI2V-5B-Diffusers") == 1500
assert backend._cache_bytes("Wan-AI/absent-repo") == 0
assert backend._cache_bytes(None) == 0
def test_hv15_guider_and_scheduler_progress(fake_runtime):
# HunyuanVideo-1.5: no guidance kwarg (CFG on the guider), no step callback (progress via the scheduler.step wrapper).
backend = VideoBackend()
status = backend.load_pipeline(
"hunyuanvideo-community/HunyuanVideo-1.5-Diffusers-480p_t2v",
display_repo_id = "Org/pinned-hv15",
model_kind = "pipeline",
)
assert status["family"] == "hunyuanvideo-1.5"
assert status["has_audio"] is False
assert status["defaults"]["frame_step"] == 4
pipe = _FakeHV15Pipeline.instance
result = backend.generate(
prompt = "a fox in the snow", steps = 4, guidance = 3.5, num_frames = 9, fps = 24
)
assert "guidance_scale" not in pipe.last_kwargs
assert "callback_on_step_end" not in pipe.last_kwargs
assert pipe.guider.guidance_scale == 3.5
assert pipe.scheduler.calls == 4
assert pipe.scheduler.step.__func__ is _FakeHV15Scheduler.step
assert result["num_frames"] == 9 and result["has_audio"] is False
assert result["repo_id"] == "Org/pinned-hv15"
def test_pipeline_load_uses_logical_identity_for_a_commit_named_snapshot(fake_runtime, tmp_path):
snapshot = tmp_path / "deadbeef"
_write_pipeline(snapshot, "LTXPipeline", "LTXVideoTransformer3DModel")
status = VideoBackend().load_pipeline(
str(snapshot),
display_repo_id = "Lightricks/LTX-2-Distilled",
model_kind = "pipeline",
)
assert status["family"] == "ltx-2"
assert status["repo_id"] == str(snapshot)
assert status["display_repo_id"] == "Lightricks/LTX-2-Distilled"
assert status["defaults"]["steps"] == 8
assert status["defaults"]["guidance"] == 1.0
def test_hv15_cancel_unwinds_scheduler_loop(fake_runtime):
backend = VideoBackend()
backend.load_pipeline(
"hunyuanvideo-community/HunyuanVideo-1.5-Diffusers-480p_t2v",
model_kind = "pipeline",
)
pipe = _FakeHV15Pipeline.instance
# The cancel lands during the FIRST real step; the next wrapped call must raise out of the loop and generate() must surface the sentinel.
pipe.scheduler.on_step = lambda n: backend.cancel_generate() if n == 1 else None
with pytest.raises(RuntimeError, match = VIDEO_CANCELLED_MSG):
backend.generate(prompt = "a fox", steps = 4)
assert pipe.scheduler.calls == 1
assert pipe.scheduler.step.__func__ is _FakeHV15Scheduler.step
# The exception unwound pipe.__call__ before its own cleanup, so generate() must have freed the offload hooks itself.
assert pipe.hooks_freed == 1
def test_cancel_during_export_discards_clip(fake_runtime, monkeypatch):
# A cancel during the blocking export/mux must still discard the clip: cancel_generate() already reported success.
backend = VideoBackend()
backend.load_pipeline(
"hunyuanvideo-community/HunyuanVideo-1.5-Diffusers-480p_t2v",
model_kind = "pipeline",
)
def _encode_and_cancel(frames, fps, audio, pipe):
backend.cancel_generate()
return b"MP4"
monkeypatch.setattr(VideoBackend, "_encode_mp4", staticmethod(_encode_and_cancel))
with pytest.raises(RuntimeError, match = VIDEO_CANCELLED_MSG):
backend.generate(prompt = "a fox", steps = 4)
def test_singleton():
assert get_video_backend() is get_video_backend()
def test_load_wan_ti2v_5b_pipeline(fake_runtime):
# A full-pipeline load of the single-DiT TI2V-5B repo: WanPipeline.from_pretrained, no audio, tiling forced on, 4k+1 frame lattice.
backend = VideoBackend()
status = backend.load_pipeline("Wan-AI/Wan2.2-TI2V-5B-Diffusers", model_kind = "pipeline")
assert status["loaded"] is True
assert status["family"] == "wan2.2-ti2v-5b"
assert status["model_kind"] == "pipeline"
assert status["has_audio"] is False
assert status["vae_tiling"] is True
assert status["defaults"]["frame_step"] == 4
assert status["transformer_quant"] is None
assert _FakeWanPipelineSingle.last["repo"] == "Wan-AI/Wan2.2-TI2V-5B-Diffusers"
assert backend._state.pipe.vae.decoder.hooks == []
def test_first_clip_seeds_floats_before_the_denoise_and_keeps_them_before_the_decode(
fake_runtime, monkeypatch
):
"""Seeds go in at denoise entry and are kept at decode entry."""
backend = VideoBackend()
backend.load_pipeline("Wan-AI/Wan2.2-TI2V-5B-Diffusers", model_kind = "pipeline")
pipe = backend._state.pipe
events: list = []
class _Seeds:
def seed(self):
events.append("seed")
def keep(self):
events.append("keep")
asked: list = []
monkeypatch.setattr(
VideoBackend, "_inline_float_seeds", lambda self, state: asked.append(state) or _Seeds()
)
original_call = type(pipe).__call__
@functools.wraps(original_call) # keeps the signature generate() gates its kwargs on
def _call(self, *args, **kwargs):
with self.progress_bar(total = 2):
events.append("denoiser")
return original_call(self, *args, **kwargs)
pipe.__class__ = type("_LoopPipe", (type(pipe),), {"__call__": _call})
pipe.progress_bar = lambda *a, **k: contextlib.nullcontext()
pipe.vae.on_decode = lambda: events.append("decode")
backend.generate(prompt = "a fox", steps = 2)
assert asked == [backend._state]
assert events[:2] == ["seed", "denoiser"]
assert events.index("keep") < events.index("decode")
assert events.count("keep") == 1
def test_first_clip_seeds_floats_at_the_first_dit_forward_without_a_pipe_progress_bar(
fake_runtime, monkeypatch
):
"""H3 modular's progress bar is its loop wrapper's: the first DiT forward still seeds first."""
backend = VideoBackend()
backend.load_pipeline("Wan-AI/Wan2.2-TI2V-5B-Diffusers", model_kind = "pipeline")
pipe = backend._state.pipe
events: list = []
class _Dit:
def __init__(self):
self.hooks = []
def register_forward_pre_hook(self, fn):
self.hooks.append(fn)
return types.SimpleNamespace(remove = lambda: self.hooks.remove(fn))
def __call__(self):
for hook in list(self.hooks):
hook(self, ())
events.append("denoiser")
dit = _Dit()
class _Seeds:
modules = [dit]
def seed(self):
if "seed" not in events:
events.append("seed")
def keep(self):
events.append("keep")
monkeypatch.setattr(VideoBackend, "_inline_float_seeds", lambda self, state: _Seeds())
original_call = type(pipe).__call__
@functools.wraps(original_call)
def _call(self, *args, **kwargs):
dit()
dit()
return original_call(self, *args, **kwargs)
pipe.__class__ = type("_ModularLikePipe", (type(pipe),), {"__call__": _call})
backend.generate(prompt = "a fox", steps = 2)
assert events[:3] == ["seed", "denoiser", "denoiser"]
assert dit.hooks == []
def _fits_in_memory_snapshot(device):
"""A memory snapshot big enough that no load is ever refused for size, so a test forcing a
device does not inherit the runner's own free memory as a precondition."""
from core.inference.diffusion_memory import DeviceMemory
total = 512 * 1024
kind = "unified_memory" if device == "mps" else "discrete_vram"
return lambda target: DeviceMemory(device, device, kind, int(total * 0.80), total)
@pytest.mark.parametrize("device,hooked", [("mps", 1), ("cuda", 0)])
def test_load_installs_the_vae_sync_on_mps(fake_runtime, monkeypatch, device, hooked):
# Tiling alone does not bound a Wan decode on MPS; the load must arm the sync.
torch = sys.modules["torch"]
syncs = []
monkeypatch.setattr(
torch,
device,
types.SimpleNamespace(
synchronize = lambda: syncs.append(1),
recommended_max_memory = lambda: 64 * 1024**3,
driver_allocated_memory = lambda: 0,
),
raising = False,
)
monkeypatch.setattr(
"core.inference.video.resolve_diffusion_device_target",
lambda: DiffusionDeviceTarget(
device = device,
dtype = torch.bfloat16,
backend = device,
vendor = None,
supports_model_cpu_offload = False,
supports_default_torch_compile = False,
supports_pinned_transfer = False,
),
)
# device="mps" reads host free RAM; pin a roomy pool so the result is load-independent.
monkeypatch.setattr(
"core.inference.video.settled_snapshot_device_memory",
_fits_in_memory_snapshot(device),
)
backend = VideoBackend()
backend.load_pipeline("Wan-AI/Wan2.2-TI2V-5B-Diffusers", model_kind = "pipeline")
hooks = backend._state.pipe.vae.decoder.hooks
assert len(hooks) == hooked
for hook in hooks:
hook(None, (), None)
assert len(syncs) == hooked
def test_video_dense_speed_defaults_to_compile_profile(fake_runtime):
# A clip denoise amortises the compile within one run, so an UNSET speed on a dense load resolves to `default` -- never max, never off.
backend = VideoBackend()
status = backend.load_pipeline("Wan-AI/Wan2.2-TI2V-5B-Diffusers", model_kind = "pipeline")
assert status["speed_mode"] == "default"
assert status["resolved"]["speed_mode"]["source"] == "auto"
backend.unload()
status_off = backend.load_pipeline(
"Wan-AI/Wan2.2-TI2V-5B-Diffusers", model_kind = "pipeline", speed_mode = "off"
)
assert status_off["speed_mode"] == "off"
assert status_off["resolved"]["speed_mode"]["source"] == "explicit"
def test_video_speed_off_suppresses_auto_dtype_quant(fake_runtime, monkeypatch):
# An explicit Speed="off" load with Precision on auto must NOT promote to auto-quant, which would break the bit-exact request.
import core.inference.video as video_mod
monkeypatch.setattr(video_mod, "dense_transformer_supported", lambda target: True)
calls: list = []
monkeypatch.setattr(
video_mod, "quantize_transformer", lambda view, target, **kw: calls.append(True) or "int8"
)
backend = VideoBackend()
status = backend.load_pipeline(
"Wan-AI/Wan2.2-TI2V-5B-Diffusers", model_kind = "pipeline", speed_mode = "off"
)
assert calls == []
assert status["transformer_quant"] is None
assert status["speed_mode"] == "off"
backend.unload()
# No request may be recorded, or the Auto badge vanishes and quantisation stays off.
resolved = status["resolved"]["transformer_quant"]
assert (
resolved["requested"] is None
), f"the record reports {resolved['requested']!r} as the user's request; nothing was asked for"
assert resolved["source"] == "auto"
_bf16_offloads_quant_fits(monkeypatch)
backend.load_pipeline("Wan-AI/Wan2.2-TI2V-5B-Diffusers", model_kind = "pipeline")
assert calls == [True]
def _bf16_offloads_quant_fits(monkeypatch, threshold_mib = 21_000):
"""Plan a bf16-sized Wan TI2V-5B (~23 GB) at model offload and its int8-sized re-plan (~19 GB) resident."""
import dataclasses
import core.inference.video as video_mod
real = video_mod.plan_diffusion_memory
def _plan(**kw):
plan = real(**kw)
if (kw.get("model_dense_mib") or 0) > threshold_mib:
return dataclasses.replace(plan, offload_policy = "model")
return plan
monkeypatch.setattr(video_mod, "plan_diffusion_memory", _plan)
monkeypatch.setattr(
video_mod,
"select_transformer_quant_scheme",
lambda target, mode, family = None, **_k: "int8",
)
monkeypatch.setattr(
video_mod, "apply_memory_plan", lambda pipe, plan, **_k: (plan.offload_policy, False)
)
def _measured_resident(monkeypatch):
"""Resident plan with a measured budget (fake_runtime's host fallback is unmeasured on macOS / Windows)."""
import dataclasses
import core.inference.video as video_mod
real = video_mod.plan_diffusion_memory
def _plan(**kw):
plan = real(**kw)
estimates = {
**plan.estimates,
"safe_device_budget_mib": 80_000,
"resident_required_mib": 30_000,
}
return dataclasses.replace(plan, offload_policy = "none", estimates = estimates)
monkeypatch.setattr(video_mod, "plan_diffusion_memory", _plan)
def _quant_spy(monkeypatch):
import core.inference.video as video_mod
monkeypatch.setattr(video_mod, "dense_transformer_supported", lambda target: True)
calls: list = []
monkeypatch.setattr(
video_mod,
"quantize_transformer",
lambda view, target, **kw: calls.append(kw.get("mode")) or "int8",
)
return calls
@pytest.mark.parametrize("speed", ["default", "max", "eager", None])
def test_video_auto_quant_keeps_a_resident_bf16_dit(fake_runtime, monkeypatch, speed):
calls = _quant_spy(monkeypatch)
_measured_resident(monkeypatch)
status = VideoBackend().load_pipeline(
"Wan-AI/Wan2.2-TI2V-5B-Diffusers", model_kind = "pipeline", speed_mode = speed
)
assert calls == []
assert status["transformer_quant"] is None
assert status["offload_policy"] == "none"
resolved = status["resolved"]["transformer_quant"]
assert (resolved["requested"], resolved["value"], resolved["source"], resolved["status"]) == (
None,
"off",
"auto",
"applied",
)
assert "fits resident" in resolved["reason"]
def test_video_auto_quant_engages_when_it_avoids_offload(fake_runtime, monkeypatch):
calls = _quant_spy(monkeypatch)
_bf16_offloads_quant_fits(monkeypatch)
status = VideoBackend().load_pipeline(
"Wan-AI/Wan2.2-TI2V-5B-Diffusers", model_kind = "pipeline", speed_mode = "default"
)
assert calls == ["auto"]
assert status["transformer_quant"] == "int8"
assert status["offload_policy"] == "none"
def test_video_auto_quant_stays_off_when_even_the_quant_offloads(fake_runtime, monkeypatch):
calls = _quant_spy(monkeypatch)
_bf16_offloads_quant_fits(monkeypatch, threshold_mib = 1)
status = VideoBackend().load_pipeline(
"Wan-AI/Wan2.2-TI2V-5B-Diffusers", model_kind = "pipeline", speed_mode = "default"
)
assert calls == []
assert status["offload_policy"] == "model"
@pytest.mark.parametrize("scheme", ["int8", "fp8"])
def test_video_explicit_quant_is_honoured_while_resident(fake_runtime, monkeypatch, scheme):
calls = _quant_spy(monkeypatch)
monkeypatch.setattr(
"core.inference.video.select_transformer_quant_scheme",
lambda target, mode, family = None, **_k: scheme,
)
status = VideoBackend().load_pipeline(
"Wan-AI/Wan2.2-TI2V-5B-Diffusers",
model_kind = "pipeline",
speed_mode = "default",
transformer_quant = scheme,
)
assert calls == [scheme]
assert status["offload_policy"] == "none"
def test_video_step_cache_auto_from_default_schedule(fake_runtime, tmp_path):
backend = VideoBackend()
status = backend.load_pipeline(
"Wan-AI/Wan2.2-TI2V-5B-Diffusers", model_kind = "pipeline", speed_mode = "max"
)
assert status["transformer_cache"] == "fbcache"
assert status["resolved"]["transformer_cache"]["source"] == "auto"
backend.unload()
(tmp_path / "ltx-2.3-22b-distilled-1.1-Q4_K_M.gguf").write_bytes(b"w")
status2 = backend.load_pipeline(
str(tmp_path),
gguf_filename = "ltx-2.3-22b-distilled-1.1-Q4_K_M.gguf",
base_repo = "Lightricks/LTX-2",
family_override = "ltx-2",
speed_mode = "max",
)
assert status2["transformer_cache"] is None
assert status2["resolved"]["transformer_cache"]["source"] == "auto"
backend.unload()
@pytest.mark.parametrize("speed_mode", [None, "default", "eager", "off"])
def test_video_step_cache_auto_stays_off_below_max(fake_runtime, speed_mode):
backend = VideoBackend()
status = backend.load_pipeline(
"Wan-AI/Wan2.2-TI2V-5B-Diffusers", model_kind = "pipeline", speed_mode = speed_mode
)
assert status["transformer_cache"] is None
assert status["resolved"]["transformer_cache"]["source"] == "auto"
assert "max speed tier" in status["resolved"]["transformer_cache"]["reason"]
assert backend._state.cache_auto is False
backend.generate(prompt = "a sloth", steps = 30)
assert backend.status()["transformer_cache"] is None
backend.unload()
def test_video_explicit_step_cache_is_honoured_on_the_default_tier(fake_runtime):
backend = VideoBackend()
status = backend.load_pipeline(
"Wan-AI/Wan2.2-TI2V-5B-Diffusers", model_kind = "pipeline", transformer_cache = "fbcache"
)
assert status["speed_mode"] == "default"
assert status["transformer_cache"] == "fbcache"
assert backend._state.cache_auto is False
backend.generate(prompt = "a sloth", steps = 8)
assert backend.status()["transformer_cache"] == "fbcache"
backend.unload()
def test_video_auto_toggle_not_armed_when_the_dit_cannot_cache(fake_runtime, tmp_path, monkeypatch):
monkeypatch.setattr(
"core.inference.video.step_cache_supported", lambda pipe, logger = None: False
)
(tmp_path / "ltx-2.3-22b-distilled-1.1-Q4_K_M.gguf").write_bytes(b"w")
backend = VideoBackend()
status = backend.load_pipeline(
str(tmp_path),
gguf_filename = "ltx-2.3-22b-distilled-1.1-Q4_K_M.gguf",
base_repo = "Lightricks/LTX-2",
family_override = "ltx-2",
speed_mode = "max",
)
assert status["transformer_cache"] is None
assert backend._state.cache_auto is False
assert (
status["resolved"]["transformer_cache"]["reason"]
== "auto: model does not support step caching"
)
backend.unload()
def test_video_gguf_status_does_not_call_a_bf16_gguf_quantized(fake_runtime, tmp_path):
# unsloth/LTX-2.5-GGUF also ships a dense BF16 GGUF: the reason names the file's quant, not "quantized weights".
filename = "ltx-2.3-22b-distilled-1.1-BF16.gguf"
(tmp_path / filename).write_bytes(b"w")
backend = VideoBackend()
status = backend.load_pipeline(
str(tmp_path),
gguf_filename = filename,
base_repo = "Lightricks/LTX-2",
family_override = "ltx-2",
)
assert status["gguf_variant"] == "BF16"
reason = status["resolved"]["transformer_quant"]["reason"]
assert reason == "not engaged (GGUF DiT (BF16) loaded; the file's own weights are used as is)"
assert "quantized" not in reason
backend.unload()
def test_video_gguf_status_reports_selected_quant_instead_of_only_compute_dtype(
fake_runtime, tmp_path
):
filename = "ltx-2.3-22b-distilled-1.1-Q4_K_M.gguf"
(tmp_path / filename).write_bytes(b"w")
backend = VideoBackend()
status = backend.load_pipeline(
str(tmp_path),
gguf_filename = filename,
base_repo = "Lightricks/LTX-2",
family_override = "ltx-2",
)
assert status["gguf_variant"] == "Q4_K_M"
# The DiT is the GGUF's own quantized weights, not a dense bf16 one.
quant = status["resolved"]["transformer_quant"]
assert (quant["value"], quant["source"]) == ("off", "auto")
assert (
quant["reason"]
== "not engaged (GGUF DiT (Q4_K_M) loaded; the file's own weights are used as is)"
)
assert backend.unload()["gguf_variant"] is None
assert (
backend.load_pipeline("Wan-AI/Wan2.2-TI2V-5B-Diffusers", model_kind = "pipeline")[
"gguf_variant"
]
is None
)
backend.unload()
def test_video_status_family_capabilities_are_probed_once(monkeypatch):
from utils.hardware import hardware as hw
detection = threading.Event()
detection.set()
monkeypatch.setattr(hw, "DETECTION_COMPLETE", detection)
monkeypatch.setattr(hw, "DEVICE", hw.DeviceType.CPU)
calls = []
available = (
types.SimpleNamespace(name = "ltx-2", modular_workflow = False),
types.SimpleNamespace(name = "minimax-h3", modular_workflow = True),
)
monkeypatch.setattr(
video_module,
"pipeline_available_video_families",
lambda *, device: calls.append(device) or available,
)
resolves = []
monkeypatch.setattr(
video_module,
"resolve_diffusion_device_target",
lambda: resolves.append(1) or types.SimpleNamespace(device = "cpu"),
)
backend = VideoBackend()
assert backend.status()["supported_families"] == ["ltx-2", "minimax-h3"]
assert backend.status()["modular_families"] == ["minimax-h3"]
assert calls == ["cpu"]
assert resolves == [1]
def test_video_status_response_carries_gguf_variant():
from models.inference import VideoStatusResponse
assert VideoStatusResponse(loaded = True, gguf_variant = "Q4_K_M").gguf_variant == "Q4_K_M"
def test_video_step_cache_auto_toggles_on_actual_steps(fake_runtime):
# The AUTO decision follows each generation's ACTUAL step count; an explicit "off" never toggles.
backend = VideoBackend()
backend.load_pipeline(
"Wan-AI/Wan2.2-TI2V-5B-Diffusers", model_kind = "pipeline", speed_mode = "max"
)
assert backend.status()["transformer_cache"] == "fbcache"
backend.generate(prompt = "a sloth", steps = 8)
assert backend.status()["transformer_cache"] is None
backend.generate(prompt = "a sloth", steps = 30)
assert backend.status()["transformer_cache"] == "fbcache"
backend.unload()
backend.load_pipeline(
"Wan-AI/Wan2.2-TI2V-5B-Diffusers",
model_kind = "pipeline",
transformer_cache = "off",
speed_mode = "max",
)
assert backend.status()["transformer_cache"] is None
backend.generate(prompt = "a sloth", steps = 30)
assert backend.status()["transformer_cache"] is None
backend.unload()
def test_wan_frame_snapping_4k_plus_1(fake_runtime):
# Wan snaps num_frames to 4k+1 (temporal factor 4), unlike LTX-2's 8k+1.
backend = VideoBackend()
backend.load_pipeline("Wan-AI/Wan2.2-TI2V-5B-Diffusers", model_kind = "pipeline")
backend.generate(prompt = "a sloth", width = 1000, height = 700, num_frames = 120)
call = backend._state.pipe.last_kwargs
assert call["num_frames"] == 117 # 4*29 + 1
# /32 spatial snap for TI2V-5B: its VAE is 16x spatial * patch 2 = 32, so 1000x700 gives 992x672 (not the /16 992x688).
assert (call["width"], call["height"]) == (992, 672)
def test_wan_ti2v_defaults_applied(fake_runtime):
# No steps/guidance passed -> ComfyUI's TI2V-5B template defaults (20 / 5.0).
backend = VideoBackend()
backend.load_pipeline("Wan-AI/Wan2.2-TI2V-5B-Diffusers", model_kind = "pipeline")
backend.generate(prompt = "a sloth")
call = backend._state.pipe.last_kwargs
assert call["num_inference_steps"] == 20
assert call["guidance_scale"] == 5.0
def test_wan_ti2v_does_not_thread_cfg2(fake_runtime):
# The single-DiT TI2V pipeline has no guidance_scale_2, so a request value must NOT be threaded (WanPipeline raises).
backend = VideoBackend()
backend.load_pipeline("Wan-AI/Wan2.2-TI2V-5B-Diffusers", model_kind = "pipeline")
backend.generate(prompt = "a sloth", guidance_2 = 3.5)
call = backend._state.pipe.last_kwargs
assert "guidance_scale_2" not in call
_REAL_ENCODE_MP4 = VideoBackend.__dict__["_encode_mp4"].__func__
def test_a_streamed_clip_still_goes_through_encode_mp4(fake_runtime, monkeypatch):
# The streamed mp4 is handed out by _encode_mp4 itself, so a wrapper around it (the in-process bench captures the
# frames there) still sees every clip; the session is consumed once and closed after the render.
import core.inference.video as vid
class _Session:
def __init__(self):
self.took, self.closed = [], 0
def hooks(self):
return contextlib.nullcontext()
def take(self, frames, fps):
self.took.append(fps)
return b"STREAMED"
def close(self):
self.closed += 1
session = _Session()
monkeypatch.setattr(vid, "open_stream_encode", lambda *_a, **_k: session)
seen = []
def grab(frames, fps, audio, pipe, **kwargs):
data = _REAL_ENCODE_MP4(frames, fps, audio, pipe, **kwargs)
seen.append((frames, fps))
return data
monkeypatch.setattr(VideoBackend, "_encode_mp4", staticmethod(grab))
backend = VideoBackend()
backend.load_pipeline("Wan-AI/Wan2.2-TI2V-5B-Diffusers", model_kind = "pipeline")
res = backend.generate(prompt = "a sloth")
assert res["mp4_bytes"] == b"STREAMED"
assert len(seen) == 1 and seen[0][0] is not None
assert session.took == [seen[0][1]] and session.closed == 1
@pytest.mark.parametrize("fail", [False, True])
def test_a_render_returns_its_pinned_clip_to_the_driver(fake_runtime, monkeypatch, fail):
# Each render empties the pinned host cache once, after the session closes and the clip is unreferenced.
import functools
import weakref
import core.inference.video as vid
class _Frames(list):
pass
class _Session:
closed = False
def hooks(self):
return contextlib.nullcontext()
def take(self, frames, fps):
return b"STREAMED"
def close(self):
self.closed = True
session = _Session()
monkeypatch.setattr(vid, "open_stream_encode", lambda *_a, **_k: session)
backend = VideoBackend()
backend.load_pipeline("Wan-AI/Wan2.2-TI2V-5B-Diffusers", model_kind = "pipeline")
pipe_cls = type(backend._state.pipe)
real_call = pipe_cls.__call__
clips = []
# wraps: the backend reads the pipeline's signature to decide which kwargs it threads.
@functools.wraps(real_call)
def call(self, *args, **kwargs):
out = real_call(self, *args, **kwargs)
out.frames = [_Frames(out.frames[0])]
clips.append(weakref.ref(out.frames[0]))
return out
monkeypatch.setattr(pipe_cls, "__call__", call)
if fail:
def boom(*_a, **_k):
raise RuntimeError("encode failed")
monkeypatch.setattr(VideoBackend, "_encode_mp4", staticmethod(boom))
released = []
monkeypatch.setattr(
vid,
"release_pinned_host_memory",
lambda: released.append((session.closed, [ref() is None for ref in clips])),
)
if fail:
with pytest.raises(RuntimeError, match = "encode failed"):
backend.generate(prompt = "a sloth")
# The in-flight traceback still holds the clip; the cache is emptied anyway, after the session is closed.
assert [closed for closed, _ in released] == [True]
else:
assert backend.generate(prompt = "a sloth")["mp4_bytes"]
assert released == [(True, [True])]
def test_wan_a14b_dual_dit_pipeline_loads(fake_runtime):
backend = VideoBackend()
status = backend.load_pipeline("Wan-AI/Wan2.2-T2V-A14B-Diffusers", model_kind = "pipeline")
assert status["loaded"] is True and status["family"] == "wan2.2-t2v-a14b"
pipe = backend._state.pipe
assert pipe.transformer is not None and pipe.transformer_2 is not None
def test_wan_a14b_cfg2_threaded_when_signature_has_it(fake_runtime):
backend = VideoBackend()
backend.load_pipeline("Wan-AI/Wan2.2-T2V-A14B-Diffusers", model_kind = "pipeline")
backend.generate(prompt = "a sloth", guidance = 5.0, guidance_2 = 3.0)
call = backend._state.pipe.last_kwargs
assert call["guidance_scale"] == 5.0
assert call["guidance_scale_2"] == 3.0
backend.generate(prompt = "a sloth", guidance = 5.0)
call2 = backend._state.pipe.last_kwargs
assert call2["guidance_scale_2"] is None
def test_wan_a14b_step_cache_applies_to_both_dits(fake_runtime):
# A dual-DiT MoE load must engage the step cache on BOTH experts: transformer_2 would otherwise run uncached.
backend = VideoBackend()
status = backend.load_pipeline(
"Wan-AI/Wan2.2-T2V-A14B-Diffusers",
model_kind = "pipeline",
transformer_cache = "fbcache",
)
pipe = backend._state.pipe
assert pipe.transformer.cache_config is not None
assert pipe.transformer_2.cache_config is not None
assert status["transformer_cache"] == "fbcache"
def test_wan_a14b_attention_applies_to_both_dits(fake_runtime, monkeypatch):
# An explicit attention backend must be set on both experts. The fake runtime is CPU, where the NVIDIA gate drops explicit kernels, so pin it open.
from core.inference import diffusion_attention as attn_mod
monkeypatch.setattr(attn_mod, "_is_cuda_nvidia", lambda target: True)
backend = VideoBackend()
backend.load_pipeline(
"Wan-AI/Wan2.2-T2V-A14B-Diffusers",
model_kind = "pipeline",
attention_backend = "cudnn",
)
pipe = backend._state.pipe
assert pipe.transformer.attention is not None
assert pipe.transformer_2.attention is not None
assert pipe.transformer.attention == pipe.transformer_2.attention
def test_wan_ti2v_single_dit_only_touches_one(fake_runtime):
backend = VideoBackend()
backend.load_pipeline(
"Wan-AI/Wan2.2-TI2V-5B-Diffusers",
model_kind = "pipeline",
transformer_cache = "fbcache",
)
pipe = backend._state.pipe
assert pipe.transformer_2 is None
assert pipe.transformer.cache_config is not None
def test_wan_a14b_dense_quant_applies_to_both_dits(fake_runtime, monkeypatch):
# transformer_quant on a pipeline load quantises the dense DiT(s). Stub the quant seams to record which pipe view each helper saw: BOTH experts must be quantised.
import core.inference.video as video_mod
monkeypatch.setattr(video_mod, "dense_transformer_supported", lambda target: True)
quantised = []
def _fake_quant(
view,
target,
*,
mode,
family,
logger = None,
):
quantised.append(view.transformer)
return "int8"
monkeypatch.setattr(video_mod, "quantize_transformer", _fake_quant)
backend = VideoBackend()
status = backend.load_pipeline(
"Wan-AI/Wan2.2-T2V-A14B-Diffusers",
model_kind = "pipeline",
transformer_quant = "int8",
)
pipe = backend._state.pipe
assert quantised == [pipe.transformer, pipe.transformer_2]
assert status["transformer_quant"] == "int8"
def test_dense_quant_skipped_under_offload(fake_runtime, monkeypatch):
# Offload hooks use Module.to(), which torchao tensors reject, so offload skips the quant.
import core.inference.video as video_mod
from core.inference import diffusion_transformer_quant as tq
monkeypatch.setenv("UNSLOTH_DIFFUSION_ALLOW_PRECISION_FALLBACK", "1")
monkeypatch.setattr(video_mod, "dense_transformer_supported", lambda target: True)
monkeypatch.setattr(tq, "native_offload_host", lambda target: True)
quantised = []
def _fake_quant(
view,
target,
*,
mode,
family,
logger = None,
):
quantised.append(view.transformer)
return "int8"
monkeypatch.setattr(video_mod, "quantize_transformer", _fake_quant)
# The CPU fake target never plans an offload, so force one at the plan seam and stub the apply step.
import dataclasses
_shared_setup_7(monkeypatch, video_mod)
placements = _stub_apply_memory_plan(monkeypatch, video_mod)
backend = VideoBackend()
status = backend.load_pipeline(
"Wan-AI/Wan2.2-T2V-A14B-Diffusers",
model_kind = "pipeline",
transformer_quant = "fp8",
)
_assert_placement_follows_the_target(placements, video_mod)
assert status["offload_policy"] == "model"
assert quantised == []
assert status["transformer_quant"] is None
resolved = status["resolved"]["transformer_quant"]
assert "moves the DiT" in resolved["reason"]
assert resolved["requested"] == "fp8"
assert resolved["value"] == "off"
assert resolved["status"] == "fell_back"
def test_the_video_load_places_on_the_selected_card_not_a_bare_device(fake_runtime, monkeypatch):
# enable_model_cpu_offload needs the INDEXED placement_device; `device` stays bare for
# policy comparisons against "cuda".
import dataclasses
import core.inference.video as video_mod
real_target = VideoBackend._device_target
def _selected(self, ordinal = None):
return dataclasses.replace(real_target(self, ordinal), ordinal = 1)
monkeypatch.setattr(VideoBackend, "_device_target", _selected)
_shared_setup_7(monkeypatch, video_mod)
placements = _stub_apply_memory_plan(monkeypatch, video_mod)
VideoBackend().load_pipeline("Lightricks/LTX-2", model_kind = "pipeline")
assert placements, "apply_memory_plan was never called"
assert placements[0]["placement_device"] == "cpu:1"
assert placements[0]["device"] == "cpu"
def test_explicit_dense_quant_refuses_under_offload(fake_runtime, monkeypatch):
import dataclasses
import core.inference.video as video_mod
from core.inference import diffusion_transformer_quant as tq
monkeypatch.setattr(video_mod, "dense_transformer_supported", lambda target: True)
monkeypatch.setattr(tq, "native_offload_host", lambda target: True)
monkeypatch.setattr(
video_mod,
"quantize_transformer",
lambda view, target, *, mode, family, logger = None: pytest.fail("must not quantise"),
)
_shared_setup_7(monkeypatch, video_mod)
backend = VideoBackend()
with pytest.raises(RuntimeError) as excinfo:
backend.load_pipeline(
"Wan-AI/Wan2.2-T2V-A14B-Diffusers",
model_kind = "pipeline",
transformer_quant = "fp8",
)
assert "transformer_quant='fp8' could not be used" in str(excinfo.value)
assert "resident memory mode" in str(excinfo.value)
assert backend.status()["loaded"] is False
def test_the_video_refusal_also_names_a_broken_torchao_rather_than_the_gpu(
fake_runtime, monkeypatch
):
# A torchao that cannot import looks like a GPU without kernels; do not blame the GPU.
import core.inference.diffusion_transformer_quant as tq
import core.inference.video as video_mod
monkeypatch.setattr(video_mod, "dense_transformer_supported", lambda target: True)
monkeypatch.setattr(video_mod, "select_transformer_quant_scheme", lambda *a, **k: None)
monkeypatch.setattr(tq, "_TORCHAO_UNAVAILABLE", ("ImportError: no torchao kernels",))
with pytest.raises(RuntimeError) as excinfo:
video_mod.assert_video_precision_available(
types.SimpleNamespace(name = "ltx-2"),
model_kind = "pipeline",
transformer_quant = "nvfp4",
)
message = str(excinfo.value)
assert "transformer_quant='nvfp4' could not be used" in message
assert "no torchao kernels" in message and "not a limit of the GPU" in message
def test_begin_load_refuses_dense_quant_on_a_non_pipeline_video_kind(fake_runtime, monkeypatch):
# The DiT quant exists only on the pipeline path, so refuse it on a GGUF pick.
backend = VideoBackend()
with pytest.raises(RuntimeError) as excinfo:
backend.begin_load(
"unsloth/LTX-2.3-GGUF",
gguf_filename = "ltx-2.3-Q4_K_M.gguf",
model_kind = "gguf",
transformer_quant = "fp8",
)
assert "full-pipeline loads only" in str(excinfo.value)
def test_wan_a14b_partial_quant_fails_the_load(fake_runtime, monkeypatch):
# If the first expert quantises but the second does not, the pipe is left at mismatched precision with no way back, so the load must fail cleanly.
import core.inference.video as video_mod
monkeypatch.setattr(video_mod, "dense_transformer_supported", lambda target: True)
outcomes = iter(["int8", None])
monkeypatch.setattr(
video_mod,
"quantize_transformer",
lambda view, target, *, mode, family, logger = None: next(outcomes),
)
backend = VideoBackend()
with pytest.raises(RuntimeError, match = "1/2 experts"):
backend.load_pipeline(
"Wan-AI/Wan2.2-T2V-A14B-Diffusers",
model_kind = "pipeline",
transformer_quant = "int8",
)
assert backend.status()["loaded"] is False
def test_wan_ti2v_dense_quant_applies_to_single_dit(fake_runtime, monkeypatch):
import core.inference.video as video_mod
monkeypatch.setattr(video_mod, "dense_transformer_supported", lambda target: True)
quantised = []
def _fake_quant(
view,
target,
*,
mode,
family,
logger = None,
):
quantised.append(view.transformer)
return "fp8"
monkeypatch.setattr(video_mod, "quantize_transformer", _fake_quant)
backend = VideoBackend()
status = backend.load_pipeline(
"Wan-AI/Wan2.2-TI2V-5B-Diffusers",
model_kind = "pipeline",
transformer_quant = "fp8",
)
assert quantised == [backend._state.pipe.transformer]
assert status["transformer_quant"] == "fp8"
def test_wan_validate_trusted_repos(fake_runtime):
backend = VideoBackend()
fam = backend.validate_load_request("Wan-AI/Wan2.2-TI2V-5B-Diffusers", model_kind = "pipeline")
assert fam.name == "wan2.2-ti2v-5b"
fam2 = backend.validate_load_request("Wan-AI/Wan2.2-T2V-A14B-Diffusers", model_kind = "pipeline")
assert fam2.name == "wan2.2-t2v-a14b"
with pytest.raises(ValueError, match = "limited to"):
backend.validate_load_request("evil/wan2.2-ti2v-5b-repack", model_kind = "pipeline")
with pytest.raises(ValueError, match = "transformer_quant"):
backend.validate_load_request(
"Wan-AI/Wan2.2-TI2V-5B-Diffusers",
model_kind = "pipeline",
transformer_quant = "bogus",
)
def test_wan_a14b_refuses_unpaired_single_file_loads(fake_runtime):
# A checkpoint whose name pairs no partner expert covers one of the two A14B experts, so validate refuses it; a
# high/low noise expert name loads the pair (test_video_moe_pair.py).
backend = VideoBackend()
with pytest.raises(ValueError, match = "dual-expert"):
backend.validate_load_request(
"QuantStack/Wan2.2-T2V-A14B-GGUF",
gguf_filename = "Wan2.2-T2V-A14B-Q4_K_M.gguf",
)
fam = backend.validate_load_request(
"QuantStack/Wan2.2-T2V-A14B-GGUF",
gguf_filename = "HighNoise/Wan2.2-T2V-A14B-HighNoise-Q4_K_M.gguf",
)
assert fam.name == "wan2.2-t2v-a14b"
# The single-DiT 5B family still accepts GGUF.
fam = backend.validate_load_request(
"unsloth/Wan2.2-TI2V-5B-GGUF",
gguf_filename = "Wan2.2-TI2V-5B-Q4_K_M.gguf",
)
assert fam.name == "wan2.2-ti2v-5b"
def test_second_dit_view_write_through():
# Attribute writes on the proxy must land on the real pipe; a ``transformer`` write mirrors onto the second expert.
from core.inference.video import _SecondDiTView
pipe = types.SimpleNamespace(transformer = "t1", transformer_2 = "t2", flag = None)
view = _SecondDiTView(pipe)
assert view.transformer == "t2"
view.transformer = "t2-compiled"
assert pipe.transformer_2 == "t2-compiled" and pipe.transformer == "t1"
view.flag = "set"
assert pipe.flag == "set"
def _sibling(name, size):
return types.SimpleNamespace(rfilename = name, size = size)
_LTX2_SIBLINGS = [
_sibling("model_index.json", 10),
_sibling("ltx-2-19b-packaged-fp8.safetensors", 170),
_sibling("transformer/config.json", 1),
_sibling("transformer/diffusion_pytorch_model-00001-of-00002.safetensors", 20),
_sibling("transformer/diffusion_pytorch_model-00002-of-00002.safetensors", 18),
_sibling("text_encoder/model-00001-of-00002.safetensors", 25),
_sibling("text_encoder/model-00002-of-00002.safetensors", 25),
_sibling("text_encoder/diffusion_pytorch_model-00001-of-00002.safetensors", 25),
_sibling("text_encoder/diffusion_pytorch_model-00002-of-00002.safetensors", 25),
_sibling("vae/diffusion_pytorch_model.safetensors", 3),
_sibling("tokenizer/tokenizer.model", 1),
_sibling("tokenizer/chat_template.jinja", 1),
_sibling("assets/example.mp4", 500),
]
@pytest.mark.parametrize("picked", ["high", "low"])
def test_wan_a14b_gguf_pair_loads_high_as_transformer_and_low_as_transformer_2(
fake_runtime, tmp_path, monkeypatch, picked
):
# Either expert of a pair loads both, and the high-noise one always serves the early (transformer) steps.
high = tmp_path / "HighNoise" / "Wan2.2-T2V-A14B-HighNoise-Q4_K_M.gguf"
low = tmp_path / "LowNoise" / "Wan2.2-T2V-A14B-LowNoise-Q4_K_M.gguf"
for path in (high, low):
path.parent.mkdir(parents = True)
path.write_bytes(b"weights")
loaded = []
def _from_single_file(path, **kwargs):
loaded.append((Path(path).name, kwargs["subfolder"], kwargs.get("quantization_config")))
return f"dit:{Path(path).name}"
monkeypatch.setattr(_FakeTransformer, "from_single_file", staticmethod(_from_single_file))
pick = high if picked == "high" else low
VideoBackend().load_pipeline(
str(tmp_path),
gguf_filename = pick.relative_to(tmp_path).as_posix(), # a hub path, '/' on every OS
base_repo = "Wan-AI/Wan2.2-T2V-A14B-Diffusers",
family_override = "wan2.2-t2v-a14b",
)
assert [(name, sub) for name, sub, _ in loaded] == [
(high.name, "transformer"),
(low.name, "transformer_2"),
]
assert all(q is not None for _, _, q in loaded)
last = _FakeWanPipelineSingle.last
assert last["transformer"] == f"dit:{high.name}"
assert last["transformer_2"] == f"dit:{low.name}"
def test_wan_a14b_comfy_pair_offloaded_reprices_both_experts(fake_runtime, tmp_path, monkeypatch):
# An offloaded ComfyUI-quantized pair reprices both experts at their offload size before the build.
import core.inference.video as vid
from core.inference.diffusion_comfy_quant import ComfyQuantScan
names = [
"wan2.2_t2v_high_noise_14B_fp8_scaled.safetensors",
"wan2.2_t2v_low_noise_14B_fp8_scaled.safetensors",
]
for name in names:
(tmp_path / name).write_bytes(b"weights")
priced = []
def _resident_mib(
fam,
base,
target,
path,
scan,
*,
keep = True,
keep_key = None,
offload = False,
):
priced.append((Path(path).name, offload))
return 2 if offload else 1
class _Stop(Exception):
pass
def _stop(*args, **kwargs):
raise _Stop
monkeypatch.setattr(vid, "refuse_comfy_quant", lambda path: ComfyQuantScan())
monkeypatch.setattr(vid, "_video_comfy_resident", lambda *args: False)
monkeypatch.setattr(vid, "_video_comfy_resident_mib", _resident_mib)
monkeypatch.setattr(vid, "raise_on_unified_memory_shortfall", _stop)
with pytest.raises(_Stop):
VideoBackend().load_pipeline(
str(tmp_path),
gguf_filename = names[1],
base_repo = "Wan-AI/Wan2.2-T2V-A14B-Diffusers",
family_override = "wan2.2-t2v-a14b",
)
assert sorted(name for name, offload in priced if offload) == sorted(names)
def test_base_download_files_scopes_pipeline_pull():
# A pipeline load skips the packaged root checkpoint, duplicate encoder shards and non-weight assets.
info = types.SimpleNamespace(siblings = _LTX2_SIBLINGS)
files = dict(VideoBackend._base_download_files(info, "pipeline"))
assert "ltx-2-19b-packaged-fp8.safetensors" not in files
assert "text_encoder/diffusion_pytorch_model-00001-of-00002.safetensors" not in files
assert "assets/example.mp4" not in files
assert files["text_encoder/model-00001-of-00002.safetensors"] == 25
assert files["transformer/diffusion_pytorch_model-00001-of-00002.safetensors"] == 20
# The standalone chat template must survive the whitelist: apply_chat_template reads it at generation time.
assert "tokenizer/chat_template.jinja" in files
assert sum(files.values()) == 10 + 1 + 20 + 18 + 25 + 25 + 3 + 1 + 1
def test_base_download_files_gguf_drops_transformer():
# A GGUF/single-file checkpoint replaces the DiT: the base transformer WEIGHTS never pull.
info = types.SimpleNamespace(siblings = _LTX2_SIBLINGS)
names = [n for n, _ in VideoBackend._base_download_files(info, "gguf")]
transformer = [n for n in names if n.startswith("transformer/")]
# config.json is needed: from_single_file resolves config = <repo id> through the Hub.
assert transformer == ["transformer/config.json"]
assert "text_encoder/model-00001-of-00002.safetensors" in names
_H3_SIBLINGS = [
_sibling("model_index.json", 10),
_sibling("modular_model_index.json", 10),
_sibling("transformer/config.json", 1),
_sibling("transformer/diffusion_pytorch_model-00001-of-00002.safetensors", 33),
_sibling("transformer/diffusion_pytorch_model-00002-of-00002.safetensors", 33),
_sibling("transformer_ref/config.json", 1),
_sibling("transformer_ref/diffusion_pytorch_model-00001-of-00002.safetensors", 33),
_sibling("transformer_ref/diffusion_pytorch_model-00002-of-00002.safetensors", 33),
_sibling("text_encoder/model-00001-of-00001.safetensors", 15),
_sibling("tokenizer/chat_template.jinja", 1),
_sibling("vae/diffusion_pytorch_model.safetensors", 3),
_sibling("audio_vae/diffusion_pytorch_model.safetensors", 1),
_sibling("scheduler/scheduler_config.json", 1),
_sibling("audio_scheduler/scheduler_config.json", 1),
_sibling("processor/preprocessor_config.json", 1),
]
def test_base_download_files_stages_the_h3_partition_the_load_will_open():
"""H3 stages only the denoiser partition the load opens; staging both would fetch 132 GB."""
info = types.SimpleNamespace(siblings = _H3_SIBLINGS)
keyframes = [n for n, _ in VideoBackend._base_download_files(info, "pipeline")]
assert "transformer/diffusion_pytorch_model-00001-of-00002.safetensors" in keyframes
assert not any(n.startswith("transformer_ref/") for n in keyframes)
references = [
n for n, _ in VideoBackend._base_download_files(info, "pipeline", h3_task = "ref2va")
]
assert "transformer_ref/diffusion_pytorch_model-00001-of-00002.safetensors" in references
assert "transformer_ref/diffusion_pytorch_model-00002-of-00002.safetensors" in references
assert not any(n.startswith("transformer/") for n in references)
for shared in (
"model_index.json",
"text_encoder/model-00001-of-00001.safetensors",
"vae/diffusion_pytorch_model.safetensors",
):
assert shared in keyframes and shared in references
def test_base_download_files_skips_the_partition_the_prequant_checkpoint_replaces():
"""The skip must drop the partition this load opens, not a hard-coded transformer/ path."""
info = types.SimpleNamespace(siblings = _H3_SIBLINGS)
keyframes = dict(
VideoBackend._base_download_files(info, "pipeline", skip_transformer_weights = True)
)
assert not any(n.startswith("transformer/diffusion_pytorch_model") for n in keyframes)
assert "transformer/config.json" in keyframes
references = dict(
VideoBackend._base_download_files(
info, "pipeline", skip_transformer_weights = True, h3_task = "ref2va"
)
)
assert not any(n.startswith("transformer_ref/diffusion_pytorch_model") for n in references)
assert "transformer_ref/config.json" in references
# The other partition stays absent too, so the skip cannot swap which one is staged.
assert not any(n.startswith("transformer/") for n in references)
# 66 of 68 reference units are the dense denoiser.
assert sum(references.values()) < sum(
size for _n, size in VideoBackend._base_download_files(info, "pipeline", h3_task = "ref2va")
)
def _h3_pipeline_load_is_attemptable(fam) -> bool:
"""Whether this host can reach H3's own pick checks; machine limits are not a rejected pick."""
from core.inference.diffusion_device import resolve_diffusion_device_target
from core.inference.diffusion_families import assert_pipeline_class_available
if resolve_diffusion_device_target().device == "mps":
return False
try:
assert_pipeline_class_available(fam.pipeline_class, fam.name)
except Exception: # noqa: BLE001 -- an unavailable pipeline class is a host fact, not a verdict
return False
if fam.modular_workflow:
try:
import diffusers
# hasattr, not the import, pulls in the lazy submodule.
return hasattr(diffusers, fam.transformer_class)
except Exception: # noqa: BLE001 -- no importable diffusers is a host fact too
return False
return True
def test_the_h3_attemptability_probe_survives_a_host_without_diffusers(monkeypatch):
"""The attemptability probe must not raise without diffusers, which studio.txt does not install."""
fam = _detect_load_family("MiniMaxAI/MiniMax-H3", None, "minimax-h3")
# H3 is modular, so the probe really does reach the import this guards.
assert fam.modular_workflow
original_import = builtins.__import__
def _no_diffusers_import(name, *args, **kwargs):
if name == "diffusers" or name.startswith("diffusers."):
raise ModuleNotFoundError(f"No module named '{name}'", name = name)
return original_import(name, *args, **kwargs)
monkeypatch.setattr(builtins, "__import__", _no_diffusers_import)
assert _h3_pipeline_load_is_attemptable(fam) is False
def test_a_quantized_reference_load_resolves_the_reference_denoiser():
# ref2va artifacts exist now, so the refusal is gone: resolve REFERENCE, not keyframe.
from core.inference.diffusion_prequant import resolve_prequant_source
backend = VideoBackend()
fam = _detect_load_family("MiniMaxAI/MiniMax-H3", None, "minimax-h3")
# Resolution is a registry lookup, valid anywhere; only the refusal needs a capable host.
check_refusal = _h3_pipeline_load_is_attemptable(fam)
for scheme, expected in (
("int8", "MiniMax-H3-Ref2VA-INT8-ConvRot.safetensors"),
("fp8", "MiniMax-H3-Ref2VA-FP8.safetensors"),
):
if check_refusal:
try:
backend.validate_load_request(
"MiniMaxAI/MiniMax-H3",
family_override = "minimax-h3",
model_kind = "pipeline",
transformer_quant = scheme,
h3_task = "ref2va",
)
except ValueError as exc: # pragma: no cover - only on a regression
pytest.fail(f"ref2va {scheme} should be loadable but was refused: {exc}")
except Exception:
pass
source = resolve_prequant_source(fam, scheme, task = "ref2va")
assert source.filename == expected
def test_load_progress_clamps_overshoot(fake_runtime, monkeypatch):
# The cache scan counts blobs a broader previous pull left behind, so the counter must never exceed the scoped estimate.
backend = VideoBackend()
backend._loading = types.SimpleNamespace(
repo_id = "Lightricks/LTX-2", base_repo = None, expected_bytes = 100, error = None
)
monkeypatch.setattr(VideoBackend, "_cache_bytes", lambda self, repo: 150)
progress = backend.load_progress()
assert progress["phase"] == "finalizing"
assert progress["downloaded_bytes"] == 100
assert progress["expected_bytes"] == 100
def test_pipeline_load_uses_predownloaded_dir(fake_runtime, tmp_path):
# When the scoped pre-download produced a local snapshot, from_pretrained must receive that dir, keeping its own sweep off the hub.
backend = VideoBackend()
backend.load_pipeline(
"Lightricks/LTX-2",
model_kind = "pipeline",
_base_local_dir = str(tmp_path),
)
assert _FakePipeline.last["base"] == str(tmp_path)
backend.unload()
def test_base_download_files_ltx23_keeps_only_shared_components():
# A 2.3 checkpoint supplies the DiT, connectors, both VAEs and the vocoder, so the base pull shrinks to scheduler + TE + tokenizer.
siblings = _LTX2_SIBLINGS + [
_sibling("scheduler/scheduler_config.json", 1),
_sibling("connectors/diffusion_pytorch_model.safetensors", 3),
_sibling("latent_upsampler/diffusion_pytorch_model.safetensors", 1),
]
info = types.SimpleNamespace(siblings = siblings)
names = [n for n, _ in VideoBackend._base_download_files(info, "gguf", ltx23 = True)]
assert "model_index.json" in names
assert "scheduler/scheduler_config.json" in names
assert "text_encoder/model-00001-of-00002.safetensors" in names
assert "tokenizer/tokenizer.model" in names
assert not any(
n.startswith(("vae/", "connectors/", "latent_upsampler/", "transformer/")) for n in names
)
def test_hv15_720p_repo_gets_720p_family_defaults():
# The 720p repack is trusted but must resolve its OWN family entry: the generic entry would default to 832x480.
from core.inference.video_families import detect_video_family
fam = detect_video_family("hunyuanvideo-community/HunyuanVideo-1.5-Diffusers-720p_t2v")
assert fam is not None and fam.name == "hunyuanvideo-1.5-720p"
assert fam.resolution_presets[0] == (1280, 720)
assert fam.base_repo.endswith("720p_t2v")
fam480 = detect_video_family("hunyuanvideo-community/HunyuanVideo-1.5-Diffusers-480p_t2v")
assert fam480 is not None and fam480.name == "hunyuanvideo-1.5"
assert fam480.resolution_presets[0] == (832, 480)
def test_predownload_base_honors_cancel_between_files(monkeypatch):
# A warm-cache sweep returns each file without consulting the event, so the loop must check it explicitly.
backend = VideoBackend()
backend._cancel_event.set()
calls: list = []
monkeypatch.setattr(
"utils.hf_xet_fallback.hf_hub_download_with_xet_fallback",
lambda repo, fn, tok, **kw: (calls.append(fn), f"/cache/{fn}")[1],
)
class _Api:
def __init__(self, token = None):
pass
def model_info(
self,
repo,
files_metadata = True,
):
return types.SimpleNamespace(
siblings = [
_sibling("model_index.json", 1),
_sibling("vae/diffusion_pytorch_model.safetensors", 2),
]
)
import huggingface_hub
monkeypatch.setattr(huggingface_hub, "HfApi", _Api)
with pytest.raises(RuntimeError, match = "cancelled"):
backend._predownload_base("base/repo", None, "pipeline")
assert calls == []
def test_detect_load_family_arch_fallback_for_local_gguf(tmp_path, monkeypatch):
# A local GGUF may carry no family token in its path, so the loader must resolve the family from the arch, not the name.
from core.inference import video as vid
from core.inference.video_families import detect_video_family
d = tmp_path / "my-videos"
d.mkdir()
(d / "model.gguf").write_bytes(b"GGUF")
assert detect_video_family(str(d)) is None
assert detect_video_family(f"{d}/model.gguf") is None
monkeypatch.setattr(
"utils.models.gguf_metadata.read_gguf_architecture",
lambda p: "ltxv",
)
fam = vid._detect_load_family(str(d), "model.gguf", None)
assert fam is not None and fam.name == "ltx-2"
monkeypatch.setattr(
"utils.models.gguf_metadata.read_gguf_architecture",
lambda p: "wan",
)
assert vid._detect_load_family(str(d), "model.gguf", None) is None
# An explicit family_override skips the arch read entirely (worker parity).
monkeypatch.setattr(
"utils.models.gguf_metadata.read_gguf_architecture",
lambda p: "ltxv",
)
assert vid._detect_load_family(str(d), "model.gguf", "ltx-2").name == "ltx-2"
class _PlanSibling:
def __init__(self, rfilename: str, size: int) -> None:
self.rfilename = rfilename
self.size = size
class _PlanInfo:
def __init__(self, siblings) -> None:
self.siblings = siblings
_LTX_BASE_SIBLINGS = [
_PlanSibling("model_index.json", 1000),
_PlanSibling("scheduler/scheduler_config.json", 1000),
_PlanSibling("tokenizer/tokenizer.json", 5_000_000),
_PlanSibling("text_encoder/model-00001-of-00005.safetensors", 10_000_000_000),
_PlanSibling("vae/diffusion_pytorch_model.safetensors", 2_400_000_000),
_PlanSibling("vocoder/diffusion_pytorch_model.safetensors", 200_000_000),
_PlanSibling("connectors/diffusion_pytorch_model.safetensors", 2_900_000_000),
_PlanSibling("transformer/diffusion_pytorch_model.safetensors", 37_800_000_000),
]
_LTX23_REPO_SIBLINGS = [
_PlanSibling("ltx-2.3-22b-distilled.gguf", 12_000_000_000),
_PlanSibling("vae/ltx-2.3-22b-distilled_video_vae.safetensors", 2_400_000_000),
_PlanSibling("vae/ltx-2.3-22b-distilled_audio_vae.safetensors", 200_000_000),
_PlanSibling(
"text_encoders/ltx-2.3-22b-distilled_embeddings_connectors.safetensors", 900_000_000
),
_PlanSibling("vae/ltx-2.3-22b-dev_video_vae.safetensors", 2_400_000_000),
]
def _run_h3_native_load(backend = None):
"""Drive the MiniMax-H3 native load path the way every H3 test does."""
backend = backend or VideoBackend()
fam = _detect_load_family("leejet/MiniMax-H3-GGUF", None, "minimax-h3")
assert fam is not None
backend._run_load_h3_native(
fam = fam,
token = None,
cancel_event = threading.Event(),
repo_id = "leejet/MiniMax-H3-GGUF",
gguf_filename = "minimax_h3_fl2va-Q4_K_M.gguf",
)
return backend
def _load_ltx23_from_dir(tmp_path):
"""Materialize the LTX-2.3 GGUF in `tmp_path` and load a pipeline off it."""
(tmp_path / "ltx-2.3-22b-distilled-1.1-Q4_K_M.gguf").write_bytes(b"w")
backend = VideoBackend()
backend.load_pipeline(
str(tmp_path),
gguf_filename = "ltx-2.3-22b-distilled-1.1-Q4_K_M.gguf",
base_repo = "Lightricks/LTX-2",
family_override = "ltx-2",
)
return backend
def _plan_api_ltx23(monkeypatch):
"""The LTX-2.3 GGUF repo plus its LTX-2 base, the pair most plan tests resolve against."""
_plan_api(
monkeypatch,
{
"unsloth/LTX-2.3-GGUF": _LTX23_REPO_SIBLINGS,
"Lightricks/LTX-2": _LTX_BASE_SIBLINGS,
},
)
def _ltx23_download_plan(**kwargs):
return VideoBackend().download_plan(
"unsloth/LTX-2.3-GGUF",
gguf_filename = "ltx-2.3-22b-distilled.gguf",
family_override = "ltx-2",
**kwargs,
)
def _force_device_target(monkeypatch, video_mod, backend):
monkeypatch.setattr(
video_mod,
"resolve_diffusion_device_target",
lambda: types.SimpleNamespace(backend = backend, device = backend, dtype = None),
)
def _plan_api(monkeypatch, repos):
class _Api:
def model_info(
self,
repo_id,
files_metadata = False,
token = None,
):
return _PlanInfo(repos[repo_id])
monkeypatch.setattr("huggingface_hub.HfApi", lambda *a, **k: _Api())
# Keep these hermetic from a developer's real Unsloth cache.
from core.inference.diffusion import DiffusionBackend
monkeypatch.setattr(
DiffusionBackend,
"_hub_file_is_cached",
staticmethod(lambda repo_id, filename, revision = None, expected_size = None, **kwargs: False),
)
def _plan_cache(monkeypatch, cached):
"""Force the plan's cache verdict for every file."""
from core.inference.diffusion import DiffusionBackend
monkeypatch.setattr(
DiffusionBackend,
"_hub_file_is_cached",
staticmethod(
lambda repo_id, filename, revision = None, expected_size = None, **kwargs: cached(filename)
),
)
def test_download_plan_omits_cached_video_files_but_keeps_the_footprint(monkeypatch):
# An unfiltered plan would re-stage a model already on disk.
_plan_api_ltx23(monkeypatch)
_plan_cache(monkeypatch, lambda name: name.endswith(".gguf"))
plan = _ltx23_download_plan()
staged = {f for e in plan["entries"] for f in e["files"]}
assert "ltx-2.3-22b-distilled.gguf" in staged, "the scoped claim stays stable as the repo warms"
assert not any(
e["checkpoint"] for e in plan["entries"] if e["repo_id"] == "unsloth/LTX-2.3-GGUF"
)
assert staged, "its uncached companions still have to be fetched"
assert plan["checkpoint_bytes"] > 0
assert plan["total_bytes"] == sum(e["bytes"] for e in plan["entries"])
assert plan["required_bytes"] == plan["total_bytes"] + plan["checkpoint_bytes"]
def test_download_plan_is_empty_when_the_whole_video_pick_is_cached(monkeypatch):
_plan_api_ltx23(monkeypatch)
_plan_cache(monkeypatch, lambda name: True)
plan = _ltx23_download_plan()
assert plan["entries"] == [] and plan["total_bytes"] == 0
assert plan["required_bytes"] > 0
def test_download_plan_restages_a_video_file_shadowed_in_the_live_cache(monkeypatch):
# A stale copy in the live root shadows the good one in the import-time root, since
# reuse_other_cache_root only switches on a live miss; the shadowed file must be staged.
_plan_api_ltx23(monkeypatch)
from core.inference.diffusion import DiffusionBackend
shadowed = "vae/ltx-2.3-22b-distilled_video_vae.safetensors"
def _cached(
repo_id,
filename,
revision = None,
expected_size = None,
roots = None,
):
if roots != ("live",):
return True # every file has a good copy in the import-time root
return filename == shadowed and expected_size is None
monkeypatch.setattr(DiffusionBackend, "_hub_file_is_cached", staticmethod(_cached))
monkeypatch.setattr("core.inference.video.hub_cache_dir", lambda: "live")
plan = _ltx23_download_plan()
staged = {f for e in plan["entries"] for f in e["files"]}
assert shadowed in staged, "a shadowed file must be restaged, not trusted"
# The shadowed file has to land in the live root, so the rest of that repo now straddles both
# and comes with it. The base repo is wholly in the other root and stays untouched.
assert staged == {s.rfilename for s in _LTX23_REPO_SIBLINGS} - {
"vae/ltx-2.3-22b-dev_video_vae.safetensors"
}
def test_download_plan_restages_a_video_base_split_across_cache_roots(monkeypatch):
# A base straddling both roots cannot be a from_pretrained snapshot, so it must be staged.
_plan_api_ltx23(monkeypatch)
from core.inference.diffusion import DiffusionBackend
live_root = "live"
elsewhere = {
"vae/ltx-2.3-22b-distilled_video_vae.safetensors",
"vae/ltx-2.3-22b-distilled_audio_vae.safetensors",
}
def _cached(
repo_id,
filename,
revision = None,
expected_size = None,
roots = None,
):
"""Half the repo in the live root, half in the other one, nothing missing."""
if roots == (live_root,):
return filename not in elsewhere
return True
monkeypatch.setattr(DiffusionBackend, "_hub_file_is_cached", staticmethod(_cached))
monkeypatch.setattr("core.inference.video.hub_cache_dir", lambda: live_root)
plan = _ltx23_download_plan()
entry = next(e for e in plan["entries"] if e["repo_id"] == "unsloth/LTX-2.3-GGUF")
expected_scope = {s.rfilename for s in _LTX23_REPO_SIBLINGS} - {
"vae/ltx-2.3-22b-dev_video_vae.safetensors"
}
assert set(entry["files"]) == expected_scope
sizes = {s.rfilename: s.size for s in _LTX23_REPO_SIBLINGS}
assert entry["bytes"] == sum(sizes[name] for name in elsewhere)
def test_download_plan_keeps_a_video_base_that_lives_wholly_in_the_other_root(monkeypatch):
# reuse_other_cache_root resolves the whole repo from the other root: nothing to stage.
_plan_api_ltx23(monkeypatch)
from core.inference.diffusion import DiffusionBackend
monkeypatch.setattr(
DiffusionBackend,
"_hub_file_is_cached",
staticmethod(
lambda repo_id, filename, revision = None, expected_size = None, roots = None: (
roots != ("live",)
)
),
)
monkeypatch.setattr("core.inference.video.hub_cache_dir", lambda: "live")
plan = _ltx23_download_plan()
assert plan["entries"] == [] and plan["required_bytes"] > 0
def test_a_companion_only_entry_is_not_labelled_the_checkpoint(monkeypatch):
# The scope names the checkpoint for job adoption, but only the companions add bytes.
_plan_api_ltx23(monkeypatch)
_plan_cache(monkeypatch, lambda name: name.endswith(".gguf"))
plan = _ltx23_download_plan()
entry = next(e for e in plan["entries"] if e["repo_id"] == "unsloth/LTX-2.3-GGUF")
assert "ltx-2.3-22b-distilled.gguf" in entry["files"]
assert entry["bytes"] == 2_400_000_000 + 200_000_000 + 900_000_000
assert entry["checkpoint"] is False, "companion files only, so not the model file"
def test_the_checkpoint_entry_is_labelled_when_its_file_is_staged(monkeypatch):
_plan_api_ltx23(monkeypatch)
_plan_cache(monkeypatch, lambda name: False)
plan = _ltx23_download_plan()
entry = next(e for e in plan["entries"] if e["repo_id"] == "unsloth/LTX-2.3-GGUF")
assert "ltx-2.3-22b-distilled.gguf" in entry["files"]
assert entry["checkpoint"] is True
def test_h3_native_download_plan_stages_the_complete_runtime(monkeypatch):
# The mirror carries the Qwen3-VL encoder quants alongside the denoisers AND the VAEs, so a
# single repo covers the whole native runtime and the plan names no other owner.
_plan_api(
monkeypatch,
{
"unsloth/MiniMax-H3-GGUF": [
_PlanSibling("minimax_h3_fl2va-Q4_K_M.gguf", 19),
_PlanSibling("qwen3vl_32b_minimax_h3-Q4_K_M.gguf", 18),
_PlanSibling("vae/official/minimax_h3_video_vae_fp16.safetensors", 5),
_PlanSibling("vae/official/minimax_h3_audio_vae_fp32.safetensors", 1),
],
},
)
plan = VideoBackend().download_plan(
"unsloth/MiniMax-H3-GGUF",
gguf_filename = "minimax_h3_fl2va-Q4_K_M.gguf",
family_override = "minimax-h3",
model_kind = "gguf",
)
by_repo = {entry["repo_id"]: entry for entry in plan["entries"]}
# Every plan owner is checked, not just one: a fresh install must not stage from others.
assert list(by_repo) == ["unsloth/MiniMax-H3-GGUF"]
assert by_repo["unsloth/MiniMax-H3-GGUF"]["files"] == [
"minimax_h3_fl2va-Q4_K_M.gguf",
"qwen3vl_32b_minimax_h3-Q4_K_M.gguf",
"vae/official/minimax_h3_video_vae_fp16.safetensors",
"vae/official/minimax_h3_audio_vae_fp32.safetensors",
]
assert plan["total_bytes"] == 43
assert plan["required_bytes"] == 43
assert plan["checkpoint_bytes"] == 19
assert by_repo["unsloth/MiniMax-H3-GGUF"]["checkpoint"] is True
_plan_cache(monkeypatch, lambda name: name == "minimax_h3_fl2va-Q4_K_M.gguf")
warming = VideoBackend().download_plan(
"unsloth/MiniMax-H3-GGUF",
gguf_filename = "minimax_h3_fl2va-Q4_K_M.gguf",
family_override = "minimax-h3",
model_kind = "gguf",
)
warming_entry = next(e for e in warming["entries"] if e["repo_id"] == "unsloth/MiniMax-H3-GGUF")
assert warming_entry["files"] == by_repo["unsloth/MiniMax-H3-GGUF"]["files"]
assert warming_entry["checkpoint"] is False
_plan_cache(monkeypatch, lambda _name: True)
cached = VideoBackend().download_plan(
"unsloth/MiniMax-H3-GGUF",
gguf_filename = "minimax_h3_fl2va-Q4_K_M.gguf",
family_override = "minimax-h3",
model_kind = "gguf",
)
assert cached == {
"entries": [],
"total_bytes": 0,
"required_bytes": 43,
"checkpoint_bytes": 19,
}
def test_h3_native_uses_the_local_bundles_own_text_encoder(monkeypatch, tmp_path):
"""A local H3 GGUF bundle supplies its own text encoder, so the Hub repo must not be fetched."""
local = tmp_path / "MiniMax-H3-GGUF"
local.mkdir()
(local / "minimax_h3_fl2va-Q4_K_M.gguf").write_bytes(b"x")
(local / "qwen3vl_32b_minimax_h3-Q4_K_M.gguf").write_bytes(b"x")
assert VideoBackend._h3_text_encoder_repo(
str(local), "qwen3vl_32b_minimax_h3-Q4_K_M.gguf"
) == str(local)
bare = tmp_path / "bare"
bare.mkdir()
assert (
VideoBackend._h3_text_encoder_repo(str(bare), "qwen3vl_32b_minimax_h3-Q4_K_M.gguf")
== "unsloth/MiniMax-H3-GGUF"
)
_plan_api(
monkeypatch,
{
# VAEs mirror beside the denoisers, so native picks never reach a community repo.
"unsloth/MiniMax-H3-GGUF": [
_PlanSibling("minimax_h3_fl2va-Q4_K_M.gguf", 19),
_PlanSibling("qwen3vl_32b_minimax_h3-Q4_K_M.gguf", 18),
_PlanSibling("vae/official/minimax_h3_video_vae_fp16.safetensors", 5),
_PlanSibling("vae/official/minimax_h3_audio_vae_fp32.safetensors", 1),
],
},
)
plan = VideoBackend._h3_native_download_plan(
str(local), "minimax_h3_fl2va-Q4_K_M.gguf", hf_token = None
)
assert [entry["repo_id"] for entry in plan["entries"]] == ["unsloth/MiniMax-H3-GGUF"]
assert plan["total_bytes"] == 6
_H3_BASE_SIBLINGS = [
_PlanSibling("transformer/config.json", 1),
_PlanSibling("transformer/diffusion_pytorch_model-00001-of-00002.safetensors", 40),
_PlanSibling("transformer/diffusion_pytorch_model-00002-of-00002.safetensors", 26),
_PlanSibling("scheduler/scheduler_config.json", 1),
_PlanSibling("vae/diffusion_pytorch_model.safetensors", 11),
]
_H3_PREQUANT_SIBLINGS = [
_PlanSibling("MiniMax-H3-INT8.pt", 20),
_PlanSibling("MiniMax-H3-FP8.pt", 20),
]
def test_download_plan_stages_the_prequant_denoiser_it_drops_the_dense_shards_for(monkeypatch):
# A hosted pre-quantized DiT replaces the dense shards, so stage it in their place.
_cuda_bf16_target(monkeypatch)
_plan_api(
monkeypatch,
{
"MiniMaxAI/MiniMax-H3": _H3_BASE_SIBLINGS,
"unsloth/MiniMax-H3-FP8": _H3_PREQUANT_SIBLINGS,
},
)
plan = VideoBackend().download_plan(
"MiniMaxAI/MiniMax-H3",
family_override = "minimax-h3",
model_kind = "pipeline",
transformer_quant = "int8",
)
by_repo = {entry["repo_id"]: entry for entry in plan["entries"]}
# int8 and fp8 share one repo, so the SCHEME picks the file, not the repo.
assert by_repo["unsloth/MiniMax-H3-FP8"]["files"] == ["MiniMax-H3-INT8.pt"]
base = by_repo["MiniMaxAI/MiniMax-H3"]
assert not any(f.startswith("transformer/diffusion_pytorch_model") for f in base["files"])
assert "transformer/config.json" in base["files"]
assert plan["total_bytes"] == sum(e["bytes"] for e in plan["entries"])
def test_download_plan_keeps_the_dense_denoiser_when_the_prequant_repo_is_missing(monkeypatch):
# An unavailable checkpoint must keep the dense shards and invent no entry.
_cuda_bf16_target(monkeypatch)
class _Api:
def model_info(
self,
repo_id,
files_metadata = False,
token = None,
):
if repo_id == "unsloth/MiniMax-H3-FP8":
raise RuntimeError("404 gated")
return _PlanInfo(_H3_BASE_SIBLINGS)
monkeypatch.setattr("huggingface_hub.HfApi", lambda *a, **k: _Api())
plan = VideoBackend().download_plan(
"MiniMaxAI/MiniMax-H3",
family_override = "minimax-h3",
model_kind = "pipeline",
transformer_quant = "int8",
)
by_repo = {entry["repo_id"]: entry for entry in plan["entries"]}
assert "unsloth/MiniMax-H3-FP8" not in by_repo
assert any(
f.startswith("transformer/diffusion_pytorch_model")
for f in by_repo["MiniMaxAI/MiniMax-H3"]["files"]
)
assert plan["total_bytes"] == sum(e["bytes"] for e in plan["entries"])
_H3_REF_BASE_SIBLINGS = _H3_BASE_SIBLINGS + [
_PlanSibling("modular_model_index.json", 1),
_PlanSibling("transformer_ref/config.json", 1),
_PlanSibling("transformer_ref/diffusion_pytorch_model-00001-of-00002.safetensors", 40),
_PlanSibling("transformer_ref/diffusion_pytorch_model-00002-of-00002.safetensors", 26),
]
def test_download_plan_keeps_the_dense_reference_shards_when_its_artifact_is_absent(monkeypatch):
# A task-specific row has no filename fallback; dropping transformer_ref/ on the
# registry's word alone would leave no denoiser.
_cuda_bf16_target(monkeypatch)
_plan_api(
monkeypatch,
{
"MiniMaxAI/MiniMax-H3": _H3_REF_BASE_SIBLINGS,
"unsloth/MiniMax-H3-FP8": _H3_PREQUANT_SIBLINGS,
},
)
plan = VideoBackend().download_plan(
"MiniMaxAI/MiniMax-H3",
family_override = "minimax-h3",
model_kind = "pipeline",
transformer_quant = "fp8",
h3_task = "ref2va",
)
by_repo = {entry["repo_id"]: entry for entry in plan["entries"]}
assert "unsloth/MiniMax-H3-FP8" not in by_repo
base = by_repo["MiniMaxAI/MiniMax-H3"]["files"]
assert "transformer_ref/diffusion_pytorch_model-00001-of-00002.safetensors" in base
assert "transformer_ref/diffusion_pytorch_model-00002-of-00002.safetensors" in base
assert plan["total_bytes"] == sum(e["bytes"] for e in plan["entries"])
def test_download_plan_still_drops_the_reference_shards_its_artifact_replaces(monkeypatch):
# The other half of the gate: once the Ref2VA artifact really resolves, the dense reference
# shards leave the base entry and the checkpoint is staged in their place.
_cuda_bf16_target(monkeypatch)
_plan_api(
monkeypatch,
{
"MiniMaxAI/MiniMax-H3": _H3_REF_BASE_SIBLINGS,
"unsloth/MiniMax-H3-FP8": _H3_PREQUANT_SIBLINGS
+ [_PlanSibling("MiniMax-H3-Ref2VA-FP8.pt", 20)],
},
)
plan = VideoBackend().download_plan(
"MiniMaxAI/MiniMax-H3",
family_override = "minimax-h3",
model_kind = "pipeline",
transformer_quant = "fp8",
h3_task = "ref2va",
)
by_repo = {entry["repo_id"]: entry for entry in plan["entries"]}
assert by_repo["unsloth/MiniMax-H3-FP8"]["files"] == ["MiniMax-H3-Ref2VA-FP8.pt"]
base = by_repo["MiniMaxAI/MiniMax-H3"]["files"]
assert not any(f.startswith("transformer_ref/diffusion_pytorch_model") for f in base)
assert "transformer_ref/config.json" in base
assert plan["total_bytes"] == sum(e["bytes"] for e in plan["entries"])
def test_the_verified_probe_keeps_the_dense_shards_when_the_artifact_is_absent(monkeypatch):
# Only an artifact that really resolves on the Hub earns the 66 GB skip.
from core.inference.video import _detect_load_family as _fam
fam = _fam("MiniMaxAI/MiniMax-H3", None, "minimax-h3")
backend = VideoBackend()
class _Api:
def __init__(self, names):
self._names = names
def model_info(
self,
repo_id,
files_metadata = False,
token = None,
):
return _PlanInfo([_PlanSibling(n, 20) for n in self._names])
def _use(names):
monkeypatch.setattr("huggingface_hub.HfApi", lambda *a, **k: _Api(names))
_use(["MiniMax-H3-FP8.pt", "MiniMax-H3-INT8-ConvRot.pt"])
assert (
backend._denoiser_prequant_verified(fam, "fp8", "MiniMaxAI/MiniMax-H3", "ref2va", None)
is False
)
assert (
backend._denoiser_prequant_verified(fam, "fp8", "MiniMaxAI/MiniMax-H3", "fl2va", None)
is True
)
_use(["MiniMax-H3-FP8.pt", "MiniMax-H3-Ref2VA-FP8.pt"])
assert (
backend._denoiser_prequant_verified(fam, "fp8", "MiniMaxAI/MiniMax-H3", "ref2va", None)
is True
)
# An unreadable repo is a refusal, not a pass: the dense shards stay.
class _Boom:
def model_info(self, *a, **k):
raise RuntimeError("404 gated")
monkeypatch.setattr("huggingface_hub.HfApi", lambda *a, **k: _Boom())
assert (
backend._denoiser_prequant_verified(fam, "fp8", "MiniMaxAI/MiniMax-H3", "ref2va", None)
is False
)
assert (
backend._denoiser_prequant_verified(fam, None, "MiniMaxAI/MiniMax-H3", "ref2va", None)
is False
)
def test_the_load_path_gates_its_dense_skip_on_the_verified_probe():
"""The dense-skip flag must use the verified probe, or neither denoiser gets staged."""
import ast
import inspect
import textwrap
from core.inference.video import VideoBackend as _VB
tree = ast.parse(textwrap.dedent(inspect.getsource(_VB._run_load)))
assigned = [
n
for n in ast.walk(tree)
if isinstance(n, ast.Assign)
and any(getattr(t, "id", None) == "skip_transformer_weights" for t in n.targets)
]
assert assigned, "skip_transformer_weights is no longer assigned in _run_load"
called = {
n.func.attr
for a in assigned
for n in ast.walk(a)
if isinstance(n, ast.Call) and isinstance(n.func, ast.Attribute)
}
assert "_denoiser_prequant_verified" in called
assert "_denoiser_prequant_covered" not in called
def test_a_named_dit_view_presents_the_reference_denoiser_as_the_transformer():
# The speed/attention helpers only see transformer/transformer_2/unconditional_transformer.
from core.inference.diffusion_attention import _attention_dits
from core.inference.diffusion_speed import _denoiser_dits
from core.inference.video import _denoiser_view
ref = object()
pipe = types.SimpleNamespace(transformer_ref = ref, vae = "vae")
assert _denoiser_dits(pipe) == [] and _attention_dits(pipe) == []
view = _denoiser_view(pipe, "transformer_ref")
assert view.transformer is ref
assert _denoiser_dits(view) == [ref]
assert _attention_dits(view) == [ref]
assert view.vae == "vae"
replacement = object()
view.transformer = replacement
assert pipe.transformer_ref is replacement
assert not hasattr(pipe, "transformer")
# A keyframe load is handed the pipe itself, so its behaviour is byte-for-byte unchanged.
keyframe = types.SimpleNamespace(transformer = ref)
assert _denoiser_view(keyframe, "transformer") is keyframe
def test_the_h3_loader_optimises_the_partition_it_denoises_with():
"""Optimisation helpers must receive the denoiser this workflow actually runs, not the bare pipe."""
import ast
import inspect
import textwrap
from core.inference.video import VideoBackend as _VB
tree = ast.parse(textwrap.dedent(inspect.getsource(_VB._load_h3_modular_pipeline)))
for helper in ("apply_attention_backend", "apply_speed_optims"):
calls = [
n
for n in ast.walk(tree)
if isinstance(n, ast.Call) and getattr(n.func, "id", None) == helper
]
assert len(calls) == 1, f"{helper} is called {len(calls)} times"
first = calls[0].args[0]
assert (
getattr(first, "id", None) == "speed_view"
), f"{helper} is handed {ast.dump(first)}, not the denoiser view"
def test_download_plan_adds_no_prequant_entry_when_bfloat16_is_pinned(monkeypatch):
# Explicit opt-out: an UNSET request now resolves to int8.
_cuda_bf16_target(monkeypatch)
_plan_api(
monkeypatch,
{
"MiniMaxAI/MiniMax-H3": _H3_BASE_SIBLINGS,
"unsloth/MiniMax-H3-FP8": _H3_PREQUANT_SIBLINGS,
},
)
plan = VideoBackend().download_plan(
"MiniMaxAI/MiniMax-H3",
family_override = "minimax-h3",
model_kind = "pipeline",
transformer_quant = "none",
)
by_repo = {entry["repo_id"]: entry for entry in plan["entries"]}
assert "unsloth/MiniMax-H3-FP8" not in by_repo
assert any(
f.startswith("transformer/diffusion_pytorch_model")
for f in by_repo["MiniMaxAI/MiniMax-H3"]["files"]
)
def test_direct_h3_native_load_uses_sd_cpp_path(monkeypatch):
backend = VideoBackend()
calls = []
monkeypatch.setattr("core.inference.video._ensure_mp4_encoder_available", lambda: None)
monkeypatch.setattr(
backend,
"_run_load_h3_native",
lambda **kwargs: calls.append(kwargs),
)
result = backend.load_pipeline(
"leejet/MiniMax-H3-GGUF",
gguf_filename = "minimax_h3_fl2va-Q4_K_M.gguf",
family_override = "minimax-h3",
model_kind = "gguf",
)
assert result["loaded"] is False
assert len(calls) == 1
assert calls[0]["fam"].name == "minimax-h3"
assert calls[0]["gguf_filename"] == "minimax_h3_fl2va-Q4_K_M.gguf"
def test_direct_h3_native_load_hands_speed_mode_to_the_sd_cpp_path(monkeypatch):
backend = VideoBackend()
calls = []
monkeypatch.setattr("core.inference.video._ensure_mp4_encoder_available", lambda: None)
monkeypatch.setattr(backend, "_run_load_h3_native", lambda **kwargs: calls.append(kwargs))
backend.load_pipeline(
"leejet/MiniMax-H3-GGUF",
gguf_filename = "minimax_h3_fl2va-Q4_K_M.gguf",
family_override = "minimax-h3",
model_kind = "gguf",
speed_mode = "max",
)
assert calls and calls[0]["speed_mode"] == "max"
def test_h3_native_load_claims_the_companion_repos_before_the_preflight(monkeypatch, tmp_path):
# Claim H3 companion repos before the minutes-long preflight, so deletes stay guarded.
from core.inference import video as video_mod
from core.inference import sd_cpp_backend, sd_cpp_engine
H3_COMPONENT_REPO, H3_GGUF_REPO, _ = _shared_setup_3()
class _Api:
def __init__(self, **_kwargs):
pass
def model_info(self, *_args, **_kwargs):
return _PlanInfo([])
monkeypatch.setattr("huggingface_hub.HfApi", _Api)
_force_device_target(monkeypatch, video_mod, "cpu")
monkeypatch.setattr(sd_cpp_backend, "_install_allowed", lambda: True)
seen: list[tuple[str, ...]] = []
def _ensure(**_kwargs):
seen.append(backend._loading.asset_repos)
return "/existing/sd-cli"
monkeypatch.setattr(sd_cpp_backend, "ensure_h3_sd_cpp_binary", _ensure)
monkeypatch.setattr(sd_cpp_backend, "sd_cpp_binary_vets_for_h3", lambda _b: True)
class _Engine:
def __init__(self, binary):
self.binary = binary
def version(self):
return "stub-version"
monkeypatch.setattr(sd_cpp_engine, "SdCppEngine", _Engine)
def _download(_repo, wanted, *_args, **_kwargs):
path = tmp_path / Path(wanted).name
path.write_bytes(b"x")
return str(path)
monkeypatch.setattr("utils.hf_xet_fallback.hf_hub_download_with_xet_fallback", _download)
backend = VideoBackend()
fam = _detect_load_family("unsloth/MiniMax-H3-GGUF", None, "minimax-h3")
assert fam is not None
backend._loading = video_mod._VideoLoadingState(
repo_id = "unsloth/MiniMax-H3-GGUF", base_repo = fam.base_repo
)
backend._load_token = 11
backend._run_load_h3_native(
fam = fam,
token = 11,
cancel_event = threading.Event(),
repo_id = "unsloth/MiniMax-H3-GGUF",
gguf_filename = "minimax_h3_fl2va-Q4_K_M.gguf",
)
# Every repo a component is read from (never the Comfy-Org repack). Same pair begin_load publishes.
assert seen == [(H3_GGUF_REPO, H3_COMPONENT_REPO)]
def test_begin_load_publishes_the_h3_companion_claim_with_the_loading_state(
fake_runtime, monkeypatch
):
# begin_load returns once scheduled, so publish the claim with _loading under one lock.
import threading
from types import SimpleNamespace
H3_COMPONENT_REPO, H3_GGUF_REPO, _ = _shared_setup_3()
backend = VideoBackend()
# Never started: the window under test is before the load thread is scheduled.
monkeypatch.setattr(
threading, "Thread", lambda *a, **k: SimpleNamespace(start = lambda: None, daemon = True)
)
backend.begin_load(
"unsloth/MiniMax-H3-GGUF",
gguf_filename = "minimax_h3_fl2va-Q4_K_M.gguf",
family_override = "minimax-h3",
model_kind = "gguf",
)
claimed = backend.loading_repo_ids()
assert H3_GGUF_REPO in claimed
assert H3_COMPONENT_REPO in claimed
def test_begin_load_publishes_the_hosted_ltx23_fp8_claim_with_the_loading_state(
fake_runtime, monkeypatch
):
# The hosted DiT's repo is claimed with _loading (like H3's), so a delete before the worker's claim cannot race the fetch.
import threading
from types import SimpleNamespace
from core.inference import video as video_mod
monkeypatch.setattr(video_mod, "dense_transformer_supported", lambda target: True)
_ltx23_fp8_card(monkeypatch)
monkeypatch.setattr(
video_mod, "assert_video_precision_available", lambda fam, **kw: None, raising = False
)
monkeypatch.setattr(
threading, "Thread", lambda *a, **k: SimpleNamespace(start = lambda: None, daemon = True)
)
def _claimed(**kwargs):
backend = VideoBackend()
backend.begin_load(
"Lightricks/LTX-2.3",
gguf_filename = "ltx-2.3-22b-distilled.safetensors",
family_override = "ltx-2",
model_kind = "single_file",
**kwargs,
)
return backend.loading_repo_ids()
# Read off the asset claim, not loading_repo_ids(): the pick's own bf16 file is now fetched from that same repo
# (it carries Lightricks/LTX-2.3's files), so the delete guard names it either way.
def _asset(**kwargs):
backend = VideoBackend()
backend.begin_load(
"Lightricks/LTX-2.3",
gguf_filename = "ltx-2.3-22b-distilled.safetensors",
family_override = "ltx-2",
model_kind = "single_file",
**kwargs,
)
return backend._loading.asset_repos
assert "unsloth/LTX-2.3-FP8" in _claimed(transformer_quant = "fp8")
assert "unsloth/LTX-2.3-FP8" in _asset(transformer_quant = "fp8")
assert "unsloth/LTX-2.3-FP8" not in _asset()
assert "unsloth/LTX-2.3-FP8" not in _asset(transformer_quant = "fp8", memory_mode = "balanced")
def test_begin_load_claims_no_companion_repos_for_a_non_h3_family(fake_runtime, monkeypatch):
# H3-native only, since a pipeline load would block deletes of repos it never reads.
import threading
from types import SimpleNamespace
H3_COMPONENT_REPO, H3_GGUF_REPO, _ = _shared_setup_3()
backend = VideoBackend()
monkeypatch.setattr(
threading, "Thread", lambda *a, **k: SimpleNamespace(start = lambda: None, daemon = True)
)
backend.begin_load("Wan-AI/Wan2.2-TI2V-5B-Diffusers", family_override = "wan2.2-ti2v-5b")
claimed = backend.loading_repo_ids()
assert H3_GGUF_REPO not in claimed
assert H3_COMPONENT_REPO not in claimed
def test_h3_native_load_honors_install_switch_and_maps_xpu_to_vulkan(monkeypatch, tmp_path):
from core.inference import video as video_mod
from core.inference import sd_cpp_backend, sd_cpp_engine
class _Api:
def __init__(self, **_kwargs):
pass
def model_info(self, *_args, **_kwargs):
return _PlanInfo([])
monkeypatch.setattr("huggingface_hub.HfApi", _Api)
monkeypatch.setattr(
video_mod,
"resolve_diffusion_device_target",
lambda: types.SimpleNamespace(backend = "xpu", device = "xpu", dtype = None),
)
monkeypatch.setattr(sd_cpp_backend, "_install_allowed", lambda: False)
install_calls = []
def _ensure(*, allow_install, accelerator):
install_calls.append((allow_install, accelerator))
return "/existing/sd-cli" if accelerator == "cpu" else None
monkeypatch.setattr(sd_cpp_backend, "ensure_sd_cpp_binary", _ensure)
class _Engine:
def __init__(self, binary):
self.binary = binary
def version(self):
# Only "not None" matters; deliberately not a real tag.
return "stub-version"
monkeypatch.setattr(sd_cpp_engine, "SdCppEngine", _Engine)
def _download(_repo, wanted, *_args, **_kwargs):
path = tmp_path / Path(wanted).name
path.write_bytes(b"x")
return str(path)
monkeypatch.setattr("utils.hf_xet_fallback.hf_hub_download_with_xet_fallback", _download)
backend = _run_h3_native_load()
assert install_calls == [(False, "vulkan"), (False, "cpu")]
assert backend._state is not None
assert backend._state.device == "cpu"
def test_h3_native_cpu_fallback_releases_the_video_gpu_claim(monkeypatch, tmp_path):
"""With the accelerator binary missing the runtime is CPU-only, so /video/load's VIDEO claim
must be released, or chat/image evicts a model that is not on the GPU."""
from core.inference import gpu_arbiter
from core.inference import video as video_mod
from core.inference import sd_cpp_backend, sd_cpp_engine
class _Api:
def __init__(self, **_kwargs):
pass
def model_info(self, *_args, **_kwargs):
return _PlanInfo([])
monkeypatch.setattr("huggingface_hub.HfApi", _Api)
_force_device_target(monkeypatch, video_mod, "cuda")
monkeypatch.setattr(sd_cpp_backend, "_install_allowed", lambda: True)
monkeypatch.setattr(
sd_cpp_backend,
"ensure_sd_cpp_binary",
lambda *, allow_install, accelerator: "/existing/sd-cli" if accelerator == "cpu" else None,
)
class _Engine:
def __init__(self, binary):
self.binary = binary
def version(self):
return "stub-version"
monkeypatch.setattr(sd_cpp_engine, "SdCppEngine", _Engine)
def _download(_repo, wanted, *_args, **_kwargs):
path = tmp_path / Path(wanted).name
path.write_bytes(b"x")
return str(path)
backend = _shared_setup_8(_download, gpu_arbiter, monkeypatch)
assert backend._state.device == "cpu"
assert gpu_arbiter.current_owner() is None
def test_h3_native_accelerator_load_keeps_the_video_gpu_claim(monkeypatch, tmp_path):
"""With the accelerator binary present, the GPU is used, so the VIDEO claim must stay."""
from core.inference import gpu_arbiter
from core.inference import video as video_mod
from core.inference import sd_cpp_backend, sd_cpp_engine
class _Api:
def __init__(self, **_kwargs):
pass
def model_info(self, *_args, **_kwargs):
return _PlanInfo([])
monkeypatch.setattr("huggingface_hub.HfApi", _Api)
_force_device_target(monkeypatch, video_mod, "cuda")
monkeypatch.setattr(sd_cpp_backend, "_install_allowed", lambda: True)
_shared_setup_11(monkeypatch, sd_cpp_backend)
class _Engine:
def __init__(self, binary):
self.binary = binary
def version(self):
return "stub-version"
monkeypatch.setattr(sd_cpp_engine, "SdCppEngine", _Engine)
def _download(_repo, wanted, *_args, **_kwargs):
path = tmp_path / Path(wanted).name
path.write_bytes(b"x")
return str(path)
backend = _shared_setup_8(_download, gpu_arbiter, monkeypatch)
assert backend._state.device == "cuda"
assert gpu_arbiter.current_owner() == gpu_arbiter.VIDEO
def test_the_load_time_accelerator_probe_runs_under_the_reader_claim(monkeypatch, tmp_path):
"""--list-devices spawns the managed sd-cli, so it must hold the reader claim against installs."""
from core.inference import gpu_arbiter
from core.inference import video as video_mod
from core.inference import sd_cpp_backend, sd_cpp_engine
managed = _shared_setup_4(monkeypatch, tmp_path)
managed.write_bytes(b"managed")
class _Api:
def __init__(self, **_kwargs):
pass
def model_info(self, *_args, **_kwargs):
return _PlanInfo([])
monkeypatch.setattr("huggingface_hub.HfApi", _Api)
_force_device_target(monkeypatch, video_mod, "cuda")
monkeypatch.setattr(sd_cpp_backend, "_install_allowed", lambda: True)
monkeypatch.setattr(
sd_cpp_backend,
"ensure_sd_cpp_binary",
lambda *, allow_install, accelerator: str(managed),
)
class _Engine:
def __init__(self, binary):
self.binary = binary
def version(self):
return "stub-version"
monkeypatch.setattr(sd_cpp_engine, "SdCppEngine", _Engine)
def _download(_repo, wanted, *_args, **_kwargs):
path = tmp_path / Path(wanted).name
path.write_bytes(b"x")
return str(path)
monkeypatch.setattr("utils.hf_xet_fallback.hf_hub_download_with_xet_fallback", _download)
monkeypatch.setattr(gpu_arbiter, "_owner", gpu_arbiter.VIDEO)
held: list = []
def _watching_probe(binary):
held.append(sd_cpp_backend._tree_readers)
# An install decided at this instant must stand down rather than replace what is running.
with sd_cpp_backend._tree_claimed_for_install() as claimed:
held.append(claimed)
return True
# video.py imports this inside the load, so patch it at its source module.
monkeypatch.setattr(sd_cpp_backend, "sd_cpp_accelerator_device_verdict", _watching_probe)
monkeypatch.setattr(sd_cpp_backend, "selected_card_identity", lambda _ordinal: "Card A@gfx1100")
backend = _run_h3_native_load()
assert backend._state.pipe.selected_card == "Card A@gfx1100"
# The first two entries are the load-time probe.
assert held[:2] == [1, False], f"probe ran unclaimed: {held}"
assert sd_cpp_backend._tree_readers == 0, "the claim must be released after the probe"
def _load_h3_native_offload(
monkeypatch,
tmp_path,
*,
help_text,
accelerator = True,
memory_mode = None,
speed_mode = None,
devices = None,
installed_accelerator = None,
backend = None,
):
"""Native H3 load on a stub sd-cli; help_text is the only input the graph-cut gate reads."""
from core.inference import gpu_arbiter
from core.inference import video as video_mod
from core.inference import sd_cpp_backend, sd_cpp_engine
class _Api:
def __init__(self, **_kwargs):
pass
def model_info(self, *_args, **_kwargs):
return _PlanInfo([])
monkeypatch.setattr("huggingface_hub.HfApi", _Api)
_force_device_target(monkeypatch, video_mod, "cuda")
monkeypatch.setattr(sd_cpp_backend, "_install_allowed", lambda: True)
monkeypatch.setattr(
sd_cpp_backend,
"ensure_sd_cpp_binary",
lambda *, allow_install, accelerator: "/existing/sd-cli",
)
# One probe helper serves both --list-devices and --help, so the ggml device line rides along or the CPU case is unreachable.
if devices is None:
devices = "CUDA0\tNVIDIA GeForce RTX 4070 Ti\n" if accelerator else "CPU\tAMD Ryzen 9\n"
monkeypatch.setattr(sd_cpp_backend, "_sd_cpp_probe_output", lambda *_a: devices + help_text)
if installed_accelerator is not None:
monkeypatch.setattr(
sd_cpp_backend, "_installed_accelerator_of", lambda _binary: installed_accelerator
)
class _Engine:
def __init__(self, binary):
self.binary = binary
def version(self):
return "stub-version"
monkeypatch.setattr(sd_cpp_engine, "SdCppEngine", _Engine)
def _download(_repo, wanted, *_args, **_kwargs):
path = tmp_path / Path(wanted).name
path.write_bytes(b"x")
return str(path)
monkeypatch.setattr("utils.hf_xet_fallback.hf_hub_download_with_xet_fallback", _download)
monkeypatch.setattr(gpu_arbiter, "_owner", gpu_arbiter.VIDEO)
backend = backend or VideoBackend()
fam = _detect_load_family("leejet/MiniMax-H3-GGUF", None, "minimax-h3")
assert fam is not None
backend._run_load_h3_native(
fam = fam,
token = None,
cancel_event = threading.Event(),
repo_id = "leejet/MiniMax-H3-GGUF",
gguf_filename = "minimax_h3_fl2va-Q4_K_M.gguf",
memory_mode = memory_mode,
speed_mode = speed_mode,
)
assert backend._state is not None
return backend._state, list(backend._state.pipe.offload_flags)
# Both fixtures carry the project banner the identity gate reads and the H3 marker
# ensure_h3_sd_cpp_binary gates on, and differ only in the graph-cut options.
_H3_HELP = (
"stable-diffusion.cpp version master-813\n"
" --ref-video MiniMax-H3 Ref2VA reference video frame directory\n"
)
_GRAPH_CUT_HELP = (
_H3_HELP + " --max-vram <string> VRAM budget\n --stream-layers prefetch\n"
)
_NO_GRAPH_CUT_HELP = _H3_HELP + " --offload-to-cpu place the weights in RAM\n"
def test_h3_native_emits_the_graph_cut_flags_on_an_accelerator(monkeypatch, tmp_path):
"""H3 needs the graph-cut flags: --offload-to-cpu alone still cudaMallocs each module whole."""
state, offload = _load_h3_native_offload(monkeypatch, tmp_path, help_text = _GRAPH_CUT_HELP)
assert state.device == "cuda"
# auto offloads, which is what makes --stream-layers take effect.
assert "--offload-to-cpu" in offload
assert offload[-3:] == ["--max-vram", "-1", "--stream-layers"]
# A negative budget auto-detects per device. A fixed number would misjudge the other card.
assert "0" not in offload
def test_h3_native_preserves_vram_headroom_on_current_builds(monkeypatch, tmp_path):
_state, offload = _load_h3_native_offload(
monkeypatch, tmp_path, help_text = _H3_HELP + " --max-vram <string> VRAM budget\n"
)
assert "--offload-to-cpu" in offload
assert offload[-2:] == ["--max-vram", "-1"]
assert "--stream-layers" not in offload
def test_h3_native_drops_stream_layers_without_cpu_offload(monkeypatch, tmp_path):
"""fast keeps the params resident on the device, and upstream only honours --stream-layers when
the diffusion params backend is CPU: without --offload-to-cpu it warns and ignores the flag.
The budget still segments on its own, so --max-vram stays."""
_state, offload = _load_h3_native_offload(
monkeypatch, tmp_path, help_text = _GRAPH_CUT_HELP, memory_mode = "fast"
)
assert "--offload-to-cpu" not in offload
assert offload[-2:] == ["--max-vram", "-1"]
assert "--stream-layers" not in offload
_AMD_VULKAN = "Vulkan0\tAMD Radeon RX 7800 XT (RADV NAVI32)\n"
# ggml-vulkan's init line rides along on stderr; "uma: 1" is an integrated GPU.
_AMD_UMA_VULKAN = (
"ggml_vulkan: 0 = AMD Radeon Graphics (RADV GFX1151) (radv) | uma: 1 | fp16: 1 | bf16: 0 |\n"
"Vulkan0\tAMD Radeon Graphics (RADV GFX1151)\n"
)
def _tiny_gtt(
monkeypatch,
*,
encoder_fits: bool,
free_vram = 1,
):
"""A GTT pool sized against the harness's one-byte files: denoiser 1 + VAEs 2 + encoder 1 bytes past the
1 GiB margin. ``encoder_fits=False`` holds everything but the encoder. ``free_vram`` is what the card reports,
1 byte by default so Auto can never render resident."""
from core.inference import video as video_mod
from core.inference import video_minimax_h3
limit = video_minimax_h3.H3_NATIVE_PINNED_MARGIN_BYTES + (4 if encoder_fits else 3)
monkeypatch.setattr(video_minimax_h3, "amdgpu_gtt_reading", lambda *a, **k: (limit, True))
monkeypatch.setattr(video_mod, "_h3_card_free_bytes", lambda *a, **k: free_vram)
_discrete_vram(monkeypatch)
def _discrete_vram(monkeypatch, free = 1 << 50):
"""The selected card's sysfs free VRAM; the default holds any render's activations, so nothing spills to GTT."""
from core.inference import video_minimax_h3
monkeypatch.setattr(video_minimax_h3, "amdgpu_vram_free_bytes", lambda *a, **k: free)
def test_h3_native_auto_prepares_the_encoder_on_the_cpu_for_an_offloaded_render(
monkeypatch, tmp_path
):
"""radv keeps every GPU-run module of an offloaded H3 in GTT (31.35 GiB at Q4, measured), past half of a 48 GB
host: the render dies on "Not enough memory for command submission". Auto runs the encoder on the CPU, but
only for a render that is offloaded: the committed flags stay the ones a resident render is derived from."""
_tiny_gtt(monkeypatch, encoder_fits = False)
state, offload = _load_h3_native_offload(
monkeypatch,
tmp_path,
help_text = _GRAPH_CUT_HELP,
devices = _AMD_VULKAN,
installed_accelerator = "vulkan",
)
assert "--offload-to-cpu" in offload and "--clip-on-cpu" not in offload
fitted = list(state.pipe.offloaded_flags)
assert "--clip-on-cpu" in fitted and "te=Vulkan0" not in " ".join(fitted)
assert state.pipe.offload_refusal is None
assert "GTT" in state.resolved["memory_mode"]["reason"]
def test_h3_native_detects_an_unowned_vulkan_build_from_its_device_listing(monkeypatch, tmp_path):
"""SD_CLI_PATH at a user Vulkan build: no install record, and the request was not vulkan."""
_tiny_gtt(monkeypatch, encoder_fits = False)
state, _offload = _load_h3_native_offload(
monkeypatch, tmp_path, help_text = _GRAPH_CUT_HELP, devices = _AMD_VULKAN
)
assert "--clip-on-cpu" in state.pipe.offloaded_flags
@pytest.mark.parametrize(
"devices",
[
"Vulkan0\tIntel(R) Arc(tm) A770 Graphics (DG2)\n",
"Vulkan0\tNVIDIA GeForce RTX 4070 Ti\n",
],
)
def test_h3_native_gtt_pool_binds_only_an_amd_vulkan_device(monkeypatch, tmp_path, devices):
"""An unrelated AMD iGPU's GTT says nothing about an Intel or NVIDIA Vulkan device."""
_tiny_gtt(monkeypatch, encoder_fits = False)
state, offload = _load_h3_native_offload(
monkeypatch, tmp_path, help_text = _GRAPH_CUT_HELP, devices = devices
)
assert "--clip-on-cpu" not in offload and state.pipe.offloaded_flags is None
def test_h3_native_leaves_a_vulkan_gtt_pool_that_fits_alone(monkeypatch, tmp_path):
_tiny_gtt(monkeypatch, encoder_fits = True)
state, offload = _load_h3_native_offload(
monkeypatch,
tmp_path,
help_text = _GRAPH_CUT_HELP,
devices = _AMD_VULKAN,
installed_accelerator = "vulkan",
)
assert "--clip-on-cpu" not in offload and state.pipe.offloaded_flags is None
def _no_gtt_room(monkeypatch, free_vram):
from core.inference import video as video_mod
from core.inference import video_minimax_h3
monkeypatch.setattr(video_minimax_h3, "amdgpu_gtt_reading", lambda *a, **k: (0, True))
monkeypatch.setattr(video_mod, "_h3_card_free_bytes", lambda *a, **k: free_vram)
_discrete_vram(monkeypatch)
def test_h3_native_auto_refuses_at_load_only_when_no_render_could_go_resident(
monkeypatch, tmp_path
):
_no_gtt_room(monkeypatch, free_vram = 1)
with pytest.raises(RuntimeError, match = "GTT"):
_load_h3_native_offload(
monkeypatch,
tmp_path,
help_text = _GRAPH_CUT_HELP,
devices = _AMD_VULKAN,
installed_accelerator = "vulkan",
)
def test_h3_native_auto_defers_the_gtt_refusal_when_a_resident_render_fits(monkeypatch, tmp_path):
_no_gtt_room(monkeypatch, free_vram = 1 << 50)
state, offload = _load_h3_native_offload(
monkeypatch,
tmp_path,
help_text = _GRAPH_CUT_HELP,
devices = _AMD_VULKAN,
installed_accelerator = "vulkan",
)
assert "--clip-on-cpu" not in offload
assert "GTT" in state.pipe.offload_refusal
def test_h3_native_refuses_a_uma_card_whose_gtt_cannot_hold_the_smallest_clips_activations(
monkeypatch, tmp_path
):
"""A UMA card (small carve-out) serves the denoiser's compute buffer from GTT too. Measured on a gfx1151 with the
pool held to 22.5 GiB free: the weights fit, every default-size render failed in sd.cpp's capacity check."""
_tiny_gtt(monkeypatch, encoder_fits = True)
_discrete_vram(monkeypatch, free = 512 << 20)
with pytest.raises(RuntimeError, match = "activations"):
_load_h3_native_offload(
monkeypatch,
tmp_path,
help_text = _GRAPH_CUT_HELP,
devices = _AMD_UMA_VULKAN,
installed_accelerator = "vulkan",
)
# A discrete card's VRAM is not GTT: the same reading leaves its load alone.
state, offload = _load_h3_native_offload(
monkeypatch,
tmp_path,
help_text = _GRAPH_CUT_HELP,
devices = _AMD_VULKAN,
installed_accelerator = "vulkan",
)
assert state.pipe.offload_refusal is None and state.pipe.fit_inputs.uma is False
def test_h3_native_refuses_balanced_on_an_overflowing_vulkan_gtt_pool(monkeypatch, tmp_path):
_tiny_gtt(monkeypatch, encoder_fits = False)
with pytest.raises(RuntimeError, match = "Low VRAM"):
_load_h3_native_offload(
monkeypatch,
tmp_path,
help_text = _GRAPH_CUT_HELP,
memory_mode = "balanced",
devices = _AMD_VULKAN,
installed_accelerator = "vulkan",
)
def test_h3_native_host_ram_check_ignores_studios_own_rss(monkeypatch, tmp_path):
"""sd-cli is its own process: the diffusers guard's add-back of Studio's RssAnon / RssShmem must not admit it."""
from core.inference import video_minimax_h3
from utils import host_memory
_tiny_gtt(monkeypatch, encoder_fits = True)
monkeypatch.setattr(host_memory, "usable_host_ram_mib", lambda: 1)
monkeypatch.setattr(host_memory, "cgroup_swap_allowance_bytes", lambda *a, **k: 0)
monkeypatch.setattr(video_minimax_h3, "h3_process_held_host_bytes", lambda: 1 << 50)
with pytest.raises(RuntimeError, match = "system RAM"):
_load_h3_native_offload(monkeypatch, tmp_path, help_text = _GRAPH_CUT_HELP)
def _loaded_with_slot(monkeypatch, tmp_path, slot):
"""A backend holding a committed native H3 model whose sd-server slot is ``slot``."""
from core.inference import video_minimax_h3
monkeypatch.setattr(video_minimax_h3, "amdgpu_gtt_reading", lambda *a, **k: (1 << 50, True))
backend = VideoBackend()
_load_h3_native_offload(
monkeypatch,
tmp_path,
help_text = _GRAPH_CUT_HELP,
devices = _AMD_VULKAN,
installed_accelerator = "vulkan",
backend = backend,
)
backend._state = dataclasses.replace(
backend._state, pipe = dataclasses.replace(backend._state.pipe, server_slot = slot)
)
return backend
class _ReleasableSlot:
def __init__(self):
self.released = []
def release(self, reason):
self.released.append(reason)
return True
def is_alive(self):
return self.busy
busy = False
def stop(self, reason = "stopped"):
pass
def test_h3_native_replacement_frees_the_outgoing_idle_server_before_refusing(
monkeypatch, tmp_path
):
"""A cached H3 model's sd-server in its keepalive window holds the GTT this load measures; the teardown would free
it, so the load releases it and measures again instead of refusing until the idle timer fires."""
from core.inference import video as video_mod
from core.inference import video_minimax_h3
slot = _ReleasableSlot()
backend = _loaded_with_slot(monkeypatch, tmp_path, slot)
roomy = video_minimax_h3.H3_NATIVE_PINNED_MARGIN_BYTES + 100
monkeypatch.setattr(
video_minimax_h3,
"amdgpu_gtt_reading",
lambda *a, **k: (roomy if slot.released else 0, True),
)
monkeypatch.setattr(video_mod, "_h3_card_free_bytes", lambda *a, **k: 1)
_discrete_vram(monkeypatch)
state, offload = _load_h3_native_offload(
monkeypatch,
tmp_path,
help_text = _GRAPH_CUT_HELP,
devices = _AMD_VULKAN,
installed_accelerator = "vulkan",
backend = backend,
)
assert slot.released and "--clip-on-cpu" not in offload
assert state.pipe.offloaded_flags is None and state.pipe.offload_refusal is None
def test_h3_native_a_busy_outgoing_server_is_not_counted_as_freed(monkeypatch, tmp_path):
"""Mid-render the release is only pending: nothing is freed yet, so no fresh reading is taken, and the refusal
says a render is still running rather than blaming the host."""
from core.inference import video as video_mod
from core.inference import video_minimax_h3
slot = _ReleasableSlot()
backend = _loaded_with_slot(monkeypatch, tmp_path, slot)
slot.busy = True
readings = []
def gtt(*_a, **_k):
readings.append(1)
return 0, True
monkeypatch.setattr(video_minimax_h3, "amdgpu_gtt_reading", gtt)
monkeypatch.setattr(video_mod, "_h3_card_free_bytes", lambda *a, **k: 1)
_discrete_vram(monkeypatch)
with pytest.raises(RuntimeError, match = "still running"):
_load_h3_native_offload(
monkeypatch,
tmp_path,
help_text = _GRAPH_CUT_HELP,
devices = _AMD_VULKAN,
installed_accelerator = "vulkan",
backend = backend,
)
assert slot.released and len(readings) == 1
def _render_runtime(
*,
base = ("--offload-to-cpu", "--diffusion-fa"),
slot = None,
snapshot_refusal = None,
uma = False,
):
from core.inference.video_minimax_h3 import H3NativeFitInputs
inputs = H3NativeFitInputs(
base_flags = base,
accelerator = "vulkan",
check_gtt = True,
gtt_pci_slot = "0000:03:00",
dit_bytes = 1,
te_bytes = 1,
vae_bytes = 2,
device_name = "Vulkan0",
uma = uma,
)
return types.SimpleNamespace(
fit_inputs = inputs,
server_slot = slot,
offloaded_flags = None,
offload_refusal = snapshot_refusal,
)
def _live_gtt(monkeypatch, value):
from core.inference import video_minimax_h3
from utils import host_memory
monkeypatch.setattr(video_minimax_h3, "amdgpu_gtt_reading", lambda *a, **k: (value, True))
monkeypatch.setattr(video_minimax_h3, "h3_native_host_available_bytes", lambda: 1 << 50)
monkeypatch.setattr(host_memory, "cgroup_swap_allowance_bytes", lambda *a, **k: 0)
def test_an_offloaded_auto_render_catches_pressure_since_the_load(monkeypatch):
from core.inference.video import _h3_offloaded_render_flags
from core.inference.video_minimax_h3 import H3NativeMemoryRefusal
_live_gtt(monkeypatch, 0)
with pytest.raises(H3NativeMemoryRefusal, match = "GTT"):
_h3_offloaded_render_flags(
_render_runtime(),
["--offload-to-cpu", "--diffusion-fa"],
render_resident = False,
memory_mode = "auto",
)
def test_an_offloaded_auto_render_lifts_a_refusal_once_memory_is_free(monkeypatch):
from core.inference.video import _h3_offloaded_render_flags
from core.inference import video_minimax_h3
# Room for everything but the encoder: the live fit moves it to the CPU and re-pins it there.
_live_gtt(monkeypatch, video_minimax_h3.H3_NATIVE_PINNED_MARGIN_BYTES + 3)
flags = _h3_offloaded_render_flags(
_render_runtime(snapshot_refusal = "refused at load"),
["--offload-to-cpu", "--diffusion-fa"],
render_resident = False,
memory_mode = "auto",
)
assert "--clip-on-cpu" in flags
assert flags[-2:] == ["--backend", "diffusion=Vulkan0,te=cpu,vae=Vulkan0"]
def test_an_offloaded_render_charges_activations_vram_cannot_hold_to_gtt(monkeypatch):
from core.inference import video_minimax_h3
from core.inference.video import _h3_offloaded_render_flags
from core.inference.video_minimax_h3 import H3NativeMemoryRefusal, h3_native_compute_bytes
compute = h3_native_compute_bytes(864, 480, 124)
# Room for the weights and this clip's activations beside them, nothing more.
_live_gtt(
monkeypatch,
video_minimax_h3.H3_NATIVE_PINNED_MARGIN_BYTES + 4 + compute,
)
_discrete_vram(monkeypatch, free = 0)
def render(compute_bytes, uma = True):
return _h3_offloaded_render_flags(
_render_runtime(uma = uma),
["--offload-to-cpu", "--diffusion-fa"],
render_resident = False,
memory_mode = "auto",
reuse_live_server = False,
compute_bytes = compute_bytes,
)
assert "--clip-on-cpu" not in render(compute)
with pytest.raises(H3NativeMemoryRefusal, match = "activations"):
render(h3_native_compute_bytes(1344, 768, 124))
# A discrete card's compute buffer is in VRAM, whatever sysfs says is free there.
assert "--clip-on-cpu" not in render(h3_native_compute_bytes(1344, 768, 124), uma = False)
# A UMA card whose carve-out holds the activations keeps them out of GTT.
_discrete_vram(monkeypatch, free = 16 << 30)
assert "--clip-on-cpu" not in render(h3_native_compute_bytes(1344, 768, 124))
# Several cards and no slot: the carve-out cannot be read, so the activations count against GTT.
_discrete_vram(monkeypatch, free = None)
with pytest.raises(H3NativeMemoryRefusal, match = "activations"):
render(h3_native_compute_bytes(1344, 768, 124))
def test_an_explicit_mode_on_a_uma_card_launches_with_the_pinned_reserve(monkeypatch):
"""Low VRAM keeps its placement; the --max-vram reserve only corrects the budget sd.cpp reads at startup."""
from core.inference import video_minimax_h3
from core.inference.video import _h3_offloaded_render_flags
_live_gtt(monkeypatch, 1 << 50)
_discrete_vram(monkeypatch, free = 0)
base = ("--offload-to-cpu", "--clip-on-cpu", "--diffusion-fa", "--max-vram", "-1")
pinned = (
1 + 2 + video_minimax_h3.H3_NATIVE_PINNED_MARGIN_BYTES
) # denoiser + VAEs, the encoder on the CPU
flags = _h3_offloaded_render_flags(
_render_runtime(base = base, uma = True),
list(base),
render_resident = False,
memory_mode = "low_vram",
compute_bytes = 1,
)
assert flags == [
"--offload-to-cpu",
"--clip-on-cpu",
"--diffusion-fa",
"--max-vram",
f"-{pinned / 1024**3:.2f}",
]
discrete = _h3_offloaded_render_flags(
_render_runtime(base = base),
list(base),
render_resident = False,
memory_mode = "low_vram",
compute_bytes = 1,
)
assert discrete == list(base)
def test_a_live_offloaded_server_keeps_its_flags_without_a_reading(monkeypatch):
from core.inference.video import _h3_offloaded_render_flags
from core.inference import video_minimax_h3
def boom(*_a, **_k):
raise AssertionError("must not re-read with the server's own weights placed")
monkeypatch.setattr(video_minimax_h3, "h3_native_live_fit", boom)
running = ("--offload-to-cpu", "--diffusion-fa", "--clip-on-cpu")
slot = types.SimpleNamespace(alive_signature = lambda: ("bin", (), running, ()))
assert _h3_offloaded_render_flags(
_render_runtime(slot = slot),
["--offload-to-cpu", "--diffusion-fa"],
render_resident = False,
memory_mode = "auto",
) == list(running)
class _ResidentSlot:
"""A live resident sd-server: ``busy`` keeps it alive through a release (it stops at its render's end)."""
def __init__(self, busy):
self.busy = busy
self.alive = True
self.released = []
def alive_signature(self):
return ("bin", (), ("--diffusion-fa", "--max-vram", "-1"), ()) if self.alive else None
def release(self, reason):
self.released.append(reason)
if not self.busy:
self.alive = False
return True
def is_alive(self):
return self.alive
def test_an_offloaded_render_frees_an_idle_resident_server_before_its_reading(monkeypatch):
from core.inference import video_minimax_h3
from core.inference.video import _h3_offloaded_render_flags
slot = _ResidentSlot(busy = False)
_live_gtt(monkeypatch, 0)
roomy = 1 << 50
monkeypatch.setattr(
video_minimax_h3, "amdgpu_gtt_reading", lambda *a, **k: (0 if slot.alive else roomy, True)
)
flags = _h3_offloaded_render_flags(
_render_runtime(slot = slot),
["--offload-to-cpu", "--diffusion-fa"],
render_resident = False,
memory_mode = "auto",
)
assert slot.released and "--clip-on-cpu" not in flags
def test_an_offloaded_render_behind_a_busy_resident_server_says_a_render_is_running(monkeypatch):
from core.inference.video import _h3_offloaded_render_flags
from core.inference.video_minimax_h3 import H3NativeMemoryRefusal
slot = _ResidentSlot(busy = True)
_live_gtt(monkeypatch, 0)
with pytest.raises(H3NativeMemoryRefusal, match = "still running"):
_h3_offloaded_render_flags(
_render_runtime(slot = slot),
["--offload-to-cpu", "--diffusion-fa"],
render_resident = False,
memory_mode = "auto",
)
assert slot.released
def test_a_new_process_never_reuses_a_live_servers_unchecked_flags(monkeypatch):
"""Reference video / audio (or a server that could not serve) runs a fresh sd-cli: the live offloaded server is
released and the launch is fitted on live readings."""
from core.inference.video import _h3_offloaded_render_flags
from core.inference.video_minimax_h3 import H3NativeMemoryRefusal
running = ("--offload-to-cpu", "--diffusion-fa")
state = {"alive": True}
slot = types.SimpleNamespace(
alive_signature = lambda: ("bin", (), running, ()) if state["alive"] else None,
release = lambda reason: state.update(alive = False) or True,
is_alive = lambda: state["alive"],
)
_live_gtt(monkeypatch, 0)
assert _h3_offloaded_render_flags(
_render_runtime(slot = slot), list(running), render_resident = False, memory_mode = "auto"
) == list(running)
with pytest.raises(H3NativeMemoryRefusal):
_h3_offloaded_render_flags(
_render_runtime(slot = slot),
list(running),
render_resident = False,
memory_mode = "auto",
reuse_live_server = False,
)
assert state["alive"] is False
def test_the_one_shot_sd_cli_launch_is_fitted_afresh():
from core.inference import video as video_mod
source = inspect.getsource(video_mod.VideoBackend._generate_h3_native)
fallback = source[source.index("if generated is None:") :]
assert fallback.index("reuse_live_server = False") < fallback.index(
"runtime.engine.generate_video("
)
BALANCED_FLAGS = [
"--offload-to-cpu",
"--diffusion-fa",
"--backend",
"diffusion=Vulkan0,te=Vulkan0,vae=Vulkan0",
]
def test_an_explicit_mode_is_re_fitted_before_launch_and_never_altered(monkeypatch):
from core.inference import video_minimax_h3
from core.inference.video import _h3_offloaded_render_flags
from core.inference.video_minimax_h3 import H3NativeMemoryRefusal
runtime = _render_runtime()
_live_gtt(monkeypatch, 1 << 50)
assert (
_h3_offloaded_render_flags(
runtime, list(BALANCED_FLAGS), render_resident = False, memory_mode = "balanced"
)
== BALANCED_FLAGS
)
# Room for the encoder-on-CPU set only: Auto would move it, an explicit mode is refused instead.
_live_gtt(monkeypatch, video_minimax_h3.H3_NATIVE_PINNED_MARGIN_BYTES + 3)
with pytest.raises(H3NativeMemoryRefusal, match = "Low VRAM"):
_h3_offloaded_render_flags(
runtime, list(BALANCED_FLAGS), render_resident = False, memory_mode = "balanced"
)
def _host_ram(monkeypatch, ram):
from core.inference import video_minimax_h3
monkeypatch.setattr(video_minimax_h3, "h3_native_host_budgets", lambda: (ram, 1 << 50))
def test_a_reused_server_still_needs_its_per_render_host_ram(monkeypatch):
from core.inference.video import _h3_offloaded_render_flags
from core.inference.video_minimax_h3 import H3NativeMemoryRefusal
running = ("--offload-to-cpu", "--diffusion-fa", "--clip-on-cpu")
slot = types.SimpleNamespace(alive_signature = lambda: ("bin", (), running, ()))
_host_ram(monkeypatch, 1 << 30)
with pytest.raises(H3NativeMemoryRefusal, match = "frames, audio and CPU buffers"):
_h3_offloaded_render_flags(
_render_runtime(slot = slot), list(running), render_resident = False, memory_mode = "auto"
)
# Swap does not count; enough RAM lets the reuse through without a full fit.
_host_ram(monkeypatch, 4 << 30)
assert _h3_offloaded_render_flags(
_render_runtime(slot = slot), list(running), render_resident = False, memory_mode = "auto"
) == list(running)
def test_a_resident_render_and_a_resident_start_check_their_host_ram(monkeypatch):
from core.inference.video import _h3_launch_flags, _h3_offloaded_render_flags
from core.inference.video_minimax_h3 import H3NativeMemoryRefusal
resident = ["--diffusion-fa", "--max-vram", "-1"]
_host_ram(monkeypatch, 1 << 30)
with pytest.raises(H3NativeMemoryRefusal):
_h3_offloaded_render_flags(
_render_runtime(), resident, render_resident = True, memory_mode = "auto"
)
with pytest.raises(H3NativeMemoryRefusal):
_h3_launch_flags(_render_runtime(), resident, "auto")
_host_ram(monkeypatch, 4 << 30)
assert _h3_launch_flags(_render_runtime(), resident, "auto") == resident
class _OffloadedSlot:
def __init__(self, busy):
self.busy = busy
self.alive = True
self.released = []
def alive_signature(self):
return ("bin", (), ("--offload-to-cpu", "--diffusion-fa"), ()) if self.alive else None
def release(self, reason):
self.released.append(reason)
if not self.busy:
self.alive = False
return True
def is_alive(self):
return self.alive
def test_a_resident_render_frees_an_idle_offloaded_server_before_its_ram_check(monkeypatch):
"""get() would replace that server on the signature change; its pinned RAM must not refuse the render."""
from core.inference import video_minimax_h3
from core.inference.video import _h3_offloaded_render_flags
slot = _OffloadedSlot(busy = False)
monkeypatch.setattr(
video_minimax_h3,
"h3_native_host_budgets",
lambda: ((1 << 30) if slot.alive else (8 << 30), 0),
)
resident = ["--diffusion-fa", "--max-vram", "-1"]
assert (
_h3_offloaded_render_flags(
_render_runtime(slot = slot), resident, render_resident = True, memory_mode = "auto"
)
== resident
)
assert slot.released
def test_a_resident_render_behind_a_busy_offloaded_server_says_a_render_is_running(monkeypatch):
from core.inference import video_minimax_h3
from core.inference.video import _h3_offloaded_render_flags
from core.inference.video_minimax_h3 import H3NativeMemoryRefusal
slot = _OffloadedSlot(busy = True)
monkeypatch.setattr(video_minimax_h3, "h3_native_host_budgets", lambda: (1 << 30, 0))
with pytest.raises(H3NativeMemoryRefusal, match = "still running"):
_h3_offloaded_render_flags(
_render_runtime(slot = slot), ["--diffusion-fa"], render_resident = True, memory_mode = "auto"
)
def test_the_kill_switch_turns_off_every_render_time_guard(monkeypatch):
from core.inference.video import _h3_launch_flags, _h3_offloaded_render_flags
monkeypatch.setenv("UNSLOTH_H3_NATIVE_FIT_CHECK", "0")
_live_gtt(monkeypatch, 0)
monkeypatch.setattr(
"core.inference.video_minimax_h3.h3_native_host_budgets", lambda: (1 << 20, 0)
)
slot = _OffloadedSlot(busy = False)
offloaded = ["--offload-to-cpu", "--diffusion-fa"]
assert (
_h3_offloaded_render_flags(
_render_runtime(slot = slot), list(offloaded), render_resident = False, memory_mode = "auto"
)
== offloaded
)
assert _h3_offloaded_render_flags(
_render_runtime(slot = slot), ["--diffusion-fa"], render_resident = True, memory_mode = "auto"
) == ["--diffusion-fa"]
assert _h3_launch_flags(_render_runtime(), list(offloaded), "balanced") == offloaded
assert _h3_launch_flags(_render_runtime(), ["--diffusion-fa"], "auto") == ["--diffusion-fa"]
assert slot.released == []
def test_a_resident_render_is_never_re_fitted(monkeypatch):
from core.inference.video import _h3_offloaded_render_flags
from core.inference import video_minimax_h3
monkeypatch.setattr(video_minimax_h3, "h3_native_live_fit", lambda *a, **k: 1 / 0)
resident = ["--diffusion-fa", "--max-vram", "-1"]
assert (
_h3_offloaded_render_flags(
_render_runtime(), resident, render_resident = True, memory_mode = "auto"
)
== resident
)
def test_h3_native_keeps_the_outgoing_server_when_the_load_fits(monkeypatch, tmp_path):
from core.inference import video as video_mod
slot = _ReleasableSlot()
backend = _loaded_with_slot(monkeypatch, tmp_path, slot)
monkeypatch.setattr(video_mod, "_h3_card_free_bytes", lambda *a, **k: 1)
_load_h3_native_offload(
monkeypatch,
tmp_path,
help_text = _GRAPH_CUT_HELP,
devices = _AMD_VULKAN,
installed_accelerator = "vulkan",
backend = backend,
)
assert slot.released == []
def test_h3_native_explicit_modes_keep_their_fit_inputs(monkeypatch, tmp_path):
_tiny_gtt(monkeypatch, encoder_fits = True)
state, _offload = _load_h3_native_offload(
monkeypatch,
tmp_path,
help_text = _GRAPH_CUT_HELP,
memory_mode = "balanced",
devices = _AMD_VULKAN,
installed_accelerator = "vulkan",
)
assert state.pipe.fit_inputs is not None
def test_h3_native_names_no_gtt_slot_when_the_vulkan_pin_did_not_resolve(monkeypatch, tmp_path):
"""Unpinned, sd.cpp picks its own Vulkan device, so the torch card's slot may name another card."""
from core.inference import video as video_mod
_tiny_gtt(monkeypatch, encoder_fits = True)
monkeypatch.setattr(video_mod, "_torch_pci_slot", lambda *_a: "0000:03:00")
state, _offload = _load_h3_native_offload(
monkeypatch,
tmp_path,
help_text = _GRAPH_CUT_HELP,
devices = _AMD_VULKAN,
installed_accelerator = "vulkan",
)
assert state.pipe.fit_inputs.device_name is None
assert state.pipe.fit_inputs.gtt_pci_slot is None
def test_h3_native_replacing_an_in_process_model_defers_the_refusal_to_the_launch(
monkeypatch, tmp_path
):
"""The outgoing diffusers model's memory is freed by the commit's teardown, before any native process starts;
the load does not refuse on a reading that still counts it, and the pre-launch live fit decides."""
from core.inference import video as video_mod
from core.inference import video_minimax_h3
backend = _loaded_with_slot(monkeypatch, tmp_path, None)
backend._state = dataclasses.replace(backend._state, engine = "diffusers")
monkeypatch.setattr(video_minimax_h3, "amdgpu_gtt_reading", lambda *a, **k: (0, True))
monkeypatch.setattr(video_mod, "_h3_card_free_bytes", lambda *a, **k: 1)
state, _offload = _load_h3_native_offload(
monkeypatch,
tmp_path,
help_text = _GRAPH_CUT_HELP,
memory_mode = "balanced",
devices = _AMD_VULKAN,
installed_accelerator = "vulkan",
backend = backend,
)
assert state.engine == "sd_cpp" and state.pipe.fit_inputs is not None
def test_h3_native_gtt_pool_is_not_a_cuda_build_concern(monkeypatch, tmp_path):
_tiny_gtt(monkeypatch, encoder_fits = False)
state, offload = _load_h3_native_offload(monkeypatch, tmp_path, help_text = _GRAPH_CUT_HELP)
assert "--clip-on-cpu" not in offload and state.pipe.offloaded_flags is None
_SAGE_HELP = _GRAPH_CUT_HELP + " --sage-attn use native CUDA SageAttention\n"
def test_h3_native_sage_attention_only_on_speed_max(monkeypatch, tmp_path):
"""SageAttention is lossy (INT8 QK^T), so it rides only on an explicit speed_mode="max"."""
monkeypatch.delenv("UNSLOTH_H3_SAGE_ATTN", raising = False)
state, offload = _load_h3_native_offload(
monkeypatch, tmp_path, help_text = _SAGE_HELP, speed_mode = "max"
)
assert offload[-1] == "--sage-attn"
assert state.attention_backend == "sage"
assert state.speed_mode == "max" and state.resolved["speed_mode"]["value"] == "max"
for mode in (None, "default", "off"):
state, offload = _load_h3_native_offload(
monkeypatch, tmp_path, help_text = _SAGE_HELP, speed_mode = mode
)
assert "--sage-attn" not in offload, mode
assert state.attention_backend == "flash"
assert state.speed_mode == "off"
def test_h3_native_sage_attention_needs_the_flag_and_honours_the_veto(monkeypatch, tmp_path):
"""An older prebuilt (u13b9d92) has no --sage-attn, and sd-cli exits on an unknown option."""
monkeypatch.delenv("UNSLOTH_H3_SAGE_ATTN", raising = False)
_state, offload = _load_h3_native_offload(
monkeypatch, tmp_path, help_text = _GRAPH_CUT_HELP, speed_mode = "max"
)
assert "--sage-attn" not in offload
monkeypatch.setenv("UNSLOTH_H3_SAGE_ATTN", "0")
_state, offload = _load_h3_native_offload(
monkeypatch, tmp_path, help_text = _SAGE_HELP, speed_mode = "max"
)
assert "--sage-attn" not in offload
def _cuda_devices(*caps):
"""sd-cli --list-devices on a CUDA build: ggml_cuda_init's stderr lines, then the device table."""
lines = [f"ggml_cuda_init: found {len(caps)} CUDA devices (Total VRAM: 1 MiB):"]
lines += [
f" Device {i}: NVIDIA Card {i}, compute capability {cc}, VMM: yes, VRAM: 1 MiB"
for i, cc in enumerate(caps)
]
lines += [f"CUDA{i}\tNVIDIA Card {i}" for i in range(len(caps))]
return "\n".join(lines) + "\n"
_BF16 = {"GGML_CUDA_QUANT_CUBLAS_MIN_BATCH": "1024"}
def test_h3_native_speed_max_takes_the_bf16_cublas_path(monkeypatch, tmp_path):
"""With the capability unreadable (no ggml_cuda_init lines), the older rule holds: speed_mode=max
hands sd-cli GGML_CUDA_QUANT_CUBLAS_MIN_BATCH, every other mode launches with no extra env."""
monkeypatch.delenv("UNSLOTH_H3_SAGE_ATTN", raising = False)
monkeypatch.delenv("GGML_CUDA_QUANT_CUBLAS_MIN_BATCH", raising = False)
state, _offload = _load_h3_native_offload(
monkeypatch, tmp_path, help_text = _SAGE_HELP, speed_mode = "max"
)
assert dict(state.pipe.env) == _BF16
for mode in (None, "default", "off"):
state, _offload = _load_h3_native_offload(
monkeypatch, tmp_path, help_text = _SAGE_HELP, speed_mode = mode
)
assert state.pipe.env == (), mode
# The veto that drops sage drops this too, and a value the user exported (0 included) is never overridden.
monkeypatch.setenv("UNSLOTH_H3_SAGE_ATTN", "0")
state, _offload = _load_h3_native_offload(
monkeypatch, tmp_path, help_text = _SAGE_HELP, speed_mode = "max"
)
assert state.pipe.env == ()
monkeypatch.delenv("UNSLOTH_H3_SAGE_ATTN", raising = False)
monkeypatch.setenv("GGML_CUDA_QUANT_CUBLAS_MIN_BATCH", "0")
state, _offload = _load_h3_native_offload(
monkeypatch, tmp_path, help_text = _SAGE_HELP, speed_mode = "max"
)
assert state.pipe.env == ()
@pytest.mark.parametrize("cc", ["8.0", "8.6", "8.9", "9.0", "10.0", "12.0"])
def test_h3_native_bf16_cublas_is_the_default_on_sm80_plus(monkeypatch, tmp_path, cc):
"""A CUDA card the build reports as sm80+ takes the BF16 cuBLAS path in every speed mode, sage or not."""
monkeypatch.delenv("UNSLOTH_H3_SAGE_ATTN", raising = False)
monkeypatch.delenv("GGML_CUDA_QUANT_CUBLAS_MIN_BATCH", raising = False)
for mode in (None, "default", "off", "max"):
state, offload = _load_h3_native_offload(
monkeypatch, tmp_path, help_text = _SAGE_HELP, speed_mode = mode, devices = _cuda_devices(cc)
)
assert dict(state.pipe.env) == _BF16, (cc, mode)
assert ("--sage-attn" in offload) == (mode == "max")
monkeypatch.setenv("UNSLOTH_H3_SAGE_ATTN", "0")
state, offload = _load_h3_native_offload(
monkeypatch, tmp_path, help_text = _SAGE_HELP, speed_mode = "max", devices = _cuda_devices(cc)
)
assert "--sage-attn" not in offload and dict(state.pipe.env) == _BF16
@pytest.mark.parametrize("value", ["0", "1024", "4096"])
def test_h3_native_bf16_cublas_user_value_wins(monkeypatch, tmp_path, value):
"""An exported GGML_CUDA_QUANT_CUBLAS_MIN_BATCH (0 = MMQ) is inherited untouched, never overridden."""
monkeypatch.setenv("GGML_CUDA_QUANT_CUBLAS_MIN_BATCH", value)
for mode in (None, "max"):
state, _offload = _load_h3_native_offload(
monkeypatch,
tmp_path,
help_text = _SAGE_HELP,
speed_mode = mode,
devices = _cuda_devices("10.0"),
)
assert state.pipe.env == (), (value, mode)
@pytest.mark.parametrize("cc", ["7.5", "7.0", "6.1"])
def test_h3_native_bf16_cublas_skipped_below_sm80(monkeypatch, tmp_path, cc):
"""Below sm80 (no BF16 tensor cores) the cuBLAS route is never taken, in any mode."""
monkeypatch.delenv("UNSLOTH_H3_SAGE_ATTN", raising = False)
monkeypatch.delenv("GGML_CUDA_QUANT_CUBLAS_MIN_BATCH", raising = False)
for mode in (None, "default", "max"):
state, _offload = _load_h3_native_offload(
monkeypatch, tmp_path, help_text = _SAGE_HELP, speed_mode = mode, devices = _cuda_devices(cc)
)
assert state.pipe.env == (), (cc, mode)
def test_h3_native_bf16_cublas_reads_the_pinned_card(monkeypatch, tmp_path):
"""Mixed host: the gate reads the card the load is pinned to, not the first or the best one."""
from core.inference import sd_cpp_backend
monkeypatch.delenv("UNSLOTH_H3_SAGE_ATTN", raising = False)
monkeypatch.delenv("GGML_CUDA_QUANT_CUBLAS_MIN_BATCH", raising = False)
text = _cuda_devices("12.0", "7.5")
monkeypatch.setattr(sd_cpp_backend, "_sd_cpp_probe_output", lambda *_a: text)
assert sd_cpp_backend.sd_cpp_cuda_compute_capability("/x/sd-cli", "CUDA0") == (12, 0)
assert sd_cpp_backend.sd_cpp_cuda_compute_capability("/x/sd-cli", "CUDA1") == (7, 5)
assert sd_cpp_backend.sd_cpp_cuda_compute_capability("/x/sd-cli", "CUDA7") is None
# No pin: sd.cpp picks a card itself, so the lowest decides.
assert sd_cpp_backend.sd_cpp_cuda_compute_capability("/x/sd-cli", None) == (7, 5)
assert sd_cpp_backend.sd_cpp_cuda_compute_capability("/x/sd-cli", "Vulkan0") is None
assert sd_cpp_backend.sd_cpp_cuda_compute_capability(None, "CUDA0") is None
@pytest.mark.parametrize(
"devices",
[
# HIP build: ggml_cuda_init says ROCm, device names are ROCm<i>.
"ggml_cuda_init: found 1 ROCm devices:\n Device 0: AMD Radeon Graphics, gfx1151 (0x1151), "
"compute capability 11.5, VMM: no\nROCm0\tAMD Radeon Graphics\n",
"Vulkan0\tAMD Radeon RX 7900 XTX (RADV NAVI31)\n",
"MTL0\tApple M3 Max\n",
],
)
def test_h3_native_bf16_cublas_never_on_non_cuda_builds(monkeypatch, tmp_path, devices):
from core.inference import sd_cpp_backend
monkeypatch.delenv("UNSLOTH_H3_SAGE_ATTN", raising = False)
monkeypatch.delenv("GGML_CUDA_QUANT_CUBLAS_MIN_BATCH", raising = False)
monkeypatch.setattr(sd_cpp_backend, "_sd_cpp_probe_output", lambda *_a: devices)
assert sd_cpp_backend.sd_cpp_cuda_compute_capability("/x/sd-cli", None) is None
assert sd_cpp_backend.sd_cpp_cuda_compute_capability("/x/sd-cli", "ROCm0") is None
state, _offload = _load_h3_native_offload(
monkeypatch, tmp_path, help_text = _SAGE_HELP, devices = devices
)
assert state.pipe.env == ()
def test_h3_native_bf16_cublas_never_on_the_cpu_build(monkeypatch, tmp_path):
monkeypatch.delenv("UNSLOTH_H3_SAGE_ATTN", raising = False)
monkeypatch.delenv("GGML_CUDA_QUANT_CUBLAS_MIN_BATCH", raising = False)
for mode in (None, "max"):
state, _offload = _load_h3_native_offload(
monkeypatch, tmp_path, help_text = _SAGE_HELP, accelerator = False, speed_mode = mode
)
assert state.pipe.env == (), mode
def test_h3_native_status_names_the_matmul_route(monkeypatch, tmp_path):
"""The speed_mode reason says BF16 cuBLAS exactly when sd-cli gets a nonzero value for it."""
monkeypatch.delenv("UNSLOTH_H3_SAGE_ATTN", raising = False)
monkeypatch.delenv("GGML_CUDA_QUANT_CUBLAS_MIN_BATCH", raising = False)
def reason(**kw):
state, _offload = _load_h3_native_offload(monkeypatch, tmp_path, help_text = _SAGE_HELP, **kw)
return state.resolved["speed_mode"]["reason"]
assert reason(devices = _cuda_devices("10.0")) == "sd.cpp BF16 cuBLAS matmuls"
assert (
reason(devices = _cuda_devices("10.0"), speed_mode = "max")
== "sd.cpp SageAttention + BF16 cuBLAS"
)
assert reason(devices = _cuda_devices("7.5")) == "sd.cpp exact kernels"
assert reason(devices = _cuda_devices("7.5"), speed_mode = "max") == "sd.cpp SageAttention"
assert reason(accelerator = False) == "sd.cpp exact kernels"
monkeypatch.setenv("GGML_CUDA_QUANT_CUBLAS_MIN_BATCH", "0")
assert reason(devices = _cuda_devices("10.0"), speed_mode = "max") == "sd.cpp SageAttention"
monkeypatch.setenv("GGML_CUDA_QUANT_CUBLAS_MIN_BATCH", "2048")
assert reason(devices = _cuda_devices("8.6")) == "sd.cpp BF16 cuBLAS matmuls"
# The fork never takes the route below sm80, whatever the user exported.
assert reason(devices = _cuda_devices("7.5")) == "sd.cpp exact kernels"
def test_h3_native_generate_hands_the_runtime_env_to_sd_cli(monkeypatch):
import dataclasses
calls: list = []
backend = _h3_native_backend(monkeypatch, calls)
backend._state = dataclasses.replace(
backend._state,
pipe = dataclasses.replace(
backend._state.pipe, env = (("GGML_CUDA_QUANT_CUBLAS_MIN_BATCH", "1024"),)
),
)
backend.generate(prompt = "a fox", width = 960, height = 544)
assert calls[0]["env"] == {"GGML_CUDA_QUANT_CUBLAS_MIN_BATCH": "1024"}
calls.clear()
backend._state = dataclasses.replace(
backend._state, pipe = dataclasses.replace(backend._state.pipe, env = ())
)
backend.generate(prompt = "a fox", width = 960, height = 544)
assert calls[0]["env"] is None
def test_h3_native_sage_attention_never_on_the_cpu_build(monkeypatch, tmp_path):
monkeypatch.delenv("UNSLOTH_H3_SAGE_ATTN", raising = False)
_state, offload = _load_h3_native_offload(
monkeypatch, tmp_path, help_text = _SAGE_HELP, accelerator = False, speed_mode = "max"
)
assert "--sage-attn" not in offload
def test_h3_native_skips_the_graph_cut_flags_on_an_older_build(monkeypatch, tmp_path):
"""sd-cli exits non-zero on an option it does not know, so emitting these unconditionally
would break every generation on a build that predates the executor."""
_state, offload = _load_h3_native_offload(monkeypatch, tmp_path, help_text = _NO_GRAPH_CUT_HELP)
assert "--max-vram" not in offload
assert "--stream-layers" not in offload
def test_h3_native_skips_the_graph_cut_flags_on_cpu(monkeypatch, tmp_path):
"""Graph cut needs a device budget; CPU allocates from system RAM, so the cut is skipped."""
state, offload = _load_h3_native_offload(
monkeypatch, tmp_path, help_text = _GRAPH_CUT_HELP, accelerator = False
)
assert state.device == "cpu"
assert "--max-vram" not in offload
def test_h3_native_reused_cpu_binary_still_commits_to_cpu(monkeypatch, tmp_path):
"""A reused CPU-only sd-cli must still commit native_device to cpu, not keep the GPU claim."""
from core.inference import gpu_arbiter
from core.inference import video as video_mod
from core.inference import sd_cpp_backend, sd_cpp_engine
class _Api:
def __init__(self, **_kwargs):
pass
def model_info(self, *_args, **_kwargs):
return _PlanInfo([])
monkeypatch.setattr("huggingface_hub.HfApi", _Api)
_force_device_target(monkeypatch, video_mod, "cuda")
monkeypatch.setattr(sd_cpp_backend, "_install_allowed", lambda: True)
_shared_setup_11(monkeypatch, sd_cpp_backend)
def _probe(_binary, *args):
if args == ("--list-devices",):
return "CPU\tIntel(R) Xeon(R) Platinum 8559C\n"
# The banner identifies the binary AS stable-diffusion.cpp before the H3 check.
return (
"stable-diffusion.cpp version unknown, commit unknown\n"
" --ref-video MiniMax-H3 Ref2VA reference video frame directory at 24 fps\n"
)
monkeypatch.setattr(sd_cpp_backend, "_sd_cpp_probe_output", _probe)
class _Engine:
def __init__(self, binary):
self.binary = binary
def version(self):
return "stub-version"
monkeypatch.setattr(sd_cpp_engine, "SdCppEngine", _Engine)
def _download(_repo, wanted, *_args, **_kwargs):
path = tmp_path / Path(wanted).name
path.write_bytes(b"x")
return str(path)
backend = _shared_setup_8(_download, gpu_arbiter, monkeypatch)
assert backend._state.device == "cpu"
assert backend._state.offload_policy == "none"
assert gpu_arbiter.current_owner() is None
def _h3_managed_cpu_fallback_load(monkeypatch, tmp_path, *, swap_on_fallback):
"""CUDA H3 load whose probe falls back to a managed CPU build that an install may swap."""
from core.inference import video as video_mod
from core.inference import sd_cpp_backend, sd_cpp_engine
root = tmp_path / "sd-home" / "stable-diffusion.cpp"
(root / "sd-bin").mkdir(parents = True)
(root / ".unsloth-studio-owned").touch()
monkeypatch.setenv("UNSLOTH_STUDIO_HOME", str(tmp_path / "sd-home" / "studio"))
managed = root / "sd-bin" / "sd-cli"
managed.write_bytes(b"the cpu build the fallback asked for")
class _Api:
def __init__(self, **_kwargs):
pass
def model_info(self, *_args, **_kwargs):
return _PlanInfo([])
monkeypatch.setattr("huggingface_hub.HfApi", _Api)
_force_device_target(monkeypatch, video_mod, "cuda")
monkeypatch.setattr(sd_cpp_backend, "_install_allowed", lambda: True)
swapped: list = []
def _ensure(*, allow_install, accelerator):
if accelerator == "cpu" and swap_on_fallback:
# The CPU bundle this call asked for is what came back; the install that replaces it
# with a GPU build lands immediately afterwards, before anything probes it again.
swapped.append(True)
return str(managed)
monkeypatch.setattr(sd_cpp_backend, "ensure_sd_cpp_binary", _ensure)
def _probe(_binary, *args):
if args == ("--list-devices",):
if swapped:
return "CUDA0\tNVIDIA H100 PCIe\nCPU\tIntel(R) Xeon(R) Platinum 8559C\n"
return "CPU\tIntel(R) Xeon(R) Platinum 8559C\n"
# The banner identifies the binary AS stable-diffusion.cpp before the H3 check.
return (
"stable-diffusion.cpp version unknown, commit unknown\n"
" --ref-video MiniMax-H3 Ref2VA reference video frame directory at 24 fps\n"
)
monkeypatch.setattr(sd_cpp_backend, "_sd_cpp_probe_output", _probe)
class _Engine:
def __init__(self, binary):
self.binary = binary
def version(self):
return "stub-version"
monkeypatch.setattr(sd_cpp_engine, "SdCppEngine", _Engine)
def _download(_repo, wanted, *_args, **_kwargs):
path = tmp_path / Path(wanted).name
path.write_bytes(b"x")
return str(path)
monkeypatch.setattr("utils.hf_xet_fallback.hf_hub_download_with_xet_fallback", _download)
backend = VideoBackend()
fam = _detect_load_family("leejet/MiniMax-H3-GGUF", None, "minimax-h3")
assert fam is not None
def _run():
backend._run_load_h3_native(
fam = fam,
token = None,
cancel_event = threading.Event(),
repo_id = "leejet/MiniMax-H3-GGUF",
gguf_filename = "minimax_h3_fl2va-Q4_K_M.gguf",
)
return backend, _run
def test_h3_native_cpu_fallback_refuses_a_gpu_build_that_replaced_it(monkeypatch, tmp_path):
"""Compare against the earlier decision, not a re-sample; a swapped GPU build must be refused."""
backend, run = _h3_managed_cpu_fallback_load(monkeypatch, tmp_path, swap_on_fallback = True)
with pytest.raises(RuntimeError, match = "different accelerator"):
run()
assert backend._state is None
def test_h3_native_cpu_fallback_still_commits_to_a_managed_cpu_build(monkeypatch, tmp_path):
"""The control: with the binary untouched, the CPU fallback must still load; refusing it for the
accelerator it chose would drop H3 on every GPU host with no matching prebuilt."""
backend, run = _h3_managed_cpu_fallback_load(monkeypatch, tmp_path, swap_on_fallback = False)
run()
assert backend._state is not None
assert backend._state.device == "cpu"
assert backend._state.offload_policy == "none"
def test_h3_native_load_publishes_the_companion_repos_while_downloading(monkeypatch, tmp_path):
"""loading_repo_ids must list companion repos too, or a delete can remove them mid-download."""
from core.inference import video as video_mod
from core.inference import sd_cpp_backend, sd_cpp_engine
H3_COMPONENT_REPO, H3_GGUF_REPO, _ = _shared_setup_3()
class _Api:
def __init__(self, **_kwargs):
pass
def model_info(self, *_args, **_kwargs):
return _PlanInfo([])
monkeypatch.setattr("huggingface_hub.HfApi", _Api)
_force_device_target(monkeypatch, video_mod, "cpu")
monkeypatch.setattr(sd_cpp_backend, "_install_allowed", lambda: True)
_shared_setup_11(monkeypatch, sd_cpp_backend)
class _Engine:
def __init__(self, binary):
self.binary = binary
def version(self):
return "stub-version"
monkeypatch.setattr(sd_cpp_engine, "SdCppEngine", _Engine)
backend = VideoBackend()
backend._load_token = 7
backend._loading = video_mod._VideoLoadingState(repo_id = "leejet/MiniMax-H3-GGUF", base_repo = "")
guarded: list[tuple[str, ...]] = []
def _download(_repo, wanted, *_args, **_kwargs):
# Sampled per file, so the guard has to be armed BEFORE any of the bytes land.
guarded.append(tuple(backend.loading_repo_ids()))
path = tmp_path / Path(wanted).name
path.write_bytes(b"x")
return str(path)
monkeypatch.setattr("utils.hf_xet_fallback.hf_hub_download_with_xet_fallback", _download)
fam = _detect_load_family("leejet/MiniMax-H3-GGUF", None, "minimax-h3")
assert fam is not None
backend._run_load_h3_native(
fam = fam,
token = 7,
cancel_event = threading.Event(),
repo_id = "leejet/MiniMax-H3-GGUF",
gguf_filename = "minimax_h3_fl2va-Q4_K_M.gguf",
)
assert len(guarded) == 4
for ids in guarded:
assert "leejet/MiniMax-H3-GGUF" in ids
assert fam.base_repo in ids
assert H3_GGUF_REPO in ids
assert H3_COMPONENT_REPO in ids
def test_h3_native_load_refuses_a_binary_that_predates_h3(monkeypatch, tmp_path):
"""ensure_sd_cpp_binary probes runnability only, so an sd.cpp build older than H3 support is
handed back and clears the version() gate: the load reported ready and the first generation
failed, i.e. AFTER the multi-tens-of-GB bundle had downloaded. Gate on the capability.
And gate BEFORE the download: the point of refusing early is lost if the four-file bundle has
already been fetched by the time the gate runs, which is what the ordering here asserts."""
from core.inference import video as video_mod
from core.inference import sd_cpp_backend, sd_cpp_engine
class _Api:
def __init__(self, **_kwargs):
pass
def model_info(self, *_args, **_kwargs):
return _PlanInfo([])
monkeypatch.setattr("huggingface_hub.HfApi", _Api)
_force_device_target(monkeypatch, video_mod, "cpu")
monkeypatch.setattr(sd_cpp_backend, "_install_allowed", lambda: True)
monkeypatch.setattr(
sd_cpp_backend,
"ensure_sd_cpp_binary",
lambda *, allow_install, accelerator: "/usr/local/bin/sd-cli",
)
# The user's own build: not ours to delete, so the load must fail rather than reinstall.
monkeypatch.setattr(sd_cpp_backend, "is_managed_binary", lambda _b: False)
# A pre-H3 --help: vid_gen and --audio-vae predate H3, so the gate uses H3-only options.
monkeypatch.setattr(
sd_cpp_backend,
"_sd_cpp_probe_output",
lambda *_args: (
# The banner is what identifies it AS stable-diffusion.cpp. Without it the gate would
# (correctly) report a different failure: not an old build, not the project at all.
"stable-diffusion.cpp version unknown, commit unknown\n"
" -M, --mode run mode, one of [img_gen, vid_gen, upscale]\n"
" --audio-vae <string> path to standalone LTX audio vae model\n"
),
)
class _Engine:
def __init__(self, binary):
self.binary = binary
def version(self):
# The old build runs perfectly well, which is exactly why this gate cannot catch it.
return "stub-version"
monkeypatch.setattr(sd_cpp_engine, "SdCppEngine", _Engine)
downloads: list[str] = []
def _download(_repo, wanted, *_args, **_kwargs):
downloads.append(wanted)
path = tmp_path / Path(wanted).name
path.write_bytes(b"x")
return str(path)
backend, fam = _shared_setup_12(_download, monkeypatch)
with pytest.raises(RuntimeError, match = "does not advertise MiniMax-H3"):
_shared_setup_5(backend, fam)
assert backend._state is None
# Not one byte of the bundle: the binary is vetted before the four files are resolved.
assert downloads == []
def test_h3_native_load_refuses_a_missing_binary_before_downloading(monkeypatch, tmp_path):
"""A missing sd-cli must be refused before the four-file bundle downloads, not after the loop."""
from core.inference import video as video_mod
from core.inference import sd_cpp_backend
class _Api:
def __init__(self, **_kwargs):
pass
def model_info(self, *_args, **_kwargs):
return _PlanInfo([])
monkeypatch.setattr("huggingface_hub.HfApi", _Api)
_force_device_target(monkeypatch, video_mod, "cpu")
monkeypatch.setattr(sd_cpp_backend, "_install_allowed", lambda: False)
monkeypatch.setattr(sd_cpp_backend, "ensure_h3_sd_cpp_binary", lambda **_kwargs: None)
downloads: list[str] = []
def _download(_repo, wanted, *_args, **_kwargs):
downloads.append(wanted)
path = tmp_path / Path(wanted).name
path.write_bytes(b"x")
return str(path)
backend, fam = _shared_setup_12(_download, monkeypatch)
with pytest.raises(RuntimeError, match = "could not be installed or started"):
_shared_setup_5(backend, fam)
assert backend._state is None
assert downloads == []
def test_h3_native_load_checks_cancellation_before_the_binary_preflight(monkeypatch):
"""The preflight may install the sd-cli prebuilt and takes no cancel_event, so cancellation is
checked before it."""
from core.inference import video as video_mod
from core.inference import sd_cpp_backend
ensures: list[str] = []
_force_device_target(monkeypatch, video_mod, "cpu")
monkeypatch.setattr(
sd_cpp_backend,
"ensure_h3_sd_cpp_binary",
lambda **_kwargs: (ensures.append("ensure"), "/usr/local/bin/sd-cli")[1],
)
cancelled = threading.Event()
cancelled.set()
backend = VideoBackend()
fam = _detect_load_family("leejet/MiniMax-H3-GGUF", None, "minimax-h3")
assert fam is not None
with pytest.raises(RuntimeError, match = VIDEO_CANCELLED_MSG):
backend._run_load_h3_native(
fam = fam,
token = None,
cancel_event = cancelled,
repo_id = "leejet/MiniMax-H3-GGUF",
gguf_filename = "minimax_h3_fl2va-Q4_K_M.gguf",
)
assert ensures == []
def test_h3_native_load_refuses_a_binary_that_is_not_sd_cpp_before_downloading(
monkeypatch, tmp_path
):
"""Discovery skips an unrelated sd executable; only an explicit SD_CLI_PATH reaches this refusal."""
from core.inference import video as video_mod
from core.inference import sd_cpp_backend, sd_cpp_engine
class _Api:
def __init__(self, **_kwargs):
pass
def model_info(self, *_args, **_kwargs):
return _PlanInfo([])
monkeypatch.setattr("huggingface_hub.HfApi", _Api)
_force_device_target(monkeypatch, video_mod, "cpu")
monkeypatch.setattr(sd_cpp_backend, "_install_allowed", lambda: True)
monkeypatch.setattr(
sd_cpp_backend,
"ensure_sd_cpp_binary",
lambda *, allow_install, accelerator: "/usr/bin/sd",
)
monkeypatch.setattr(sd_cpp_backend, "is_managed_binary", lambda _b: False)
# Debian/Ubuntu's find-and-replace `sd`, which is what /usr/bin/sd is on the reporter's box.
monkeypatch.setattr(
sd_cpp_backend,
"_sd_cpp_probe_output",
lambda *_args: "sd 1.0.0\nFind & replace CLI\n\nUSAGE:\n sd <find> <replace-with>\n",
)
class _Engine:
def __init__(self, binary):
self.binary = binary
def version(self):
return "stub-version"
monkeypatch.setattr(sd_cpp_engine, "SdCppEngine", _Engine)
downloads: list[str] = []
def _download(_repo, wanted, *_args, **_kwargs):
downloads.append(wanted)
path = tmp_path / Path(wanted).name
path.write_bytes(b"x")
return str(path)
backend, fam = _shared_setup_12(_download, monkeypatch)
with pytest.raises(RuntimeError, match = "is not stable-diffusion.cpp"):
_shared_setup_5(backend, fam)
assert backend._state is None
assert downloads == []
def test_h3_native_generation_dispatch_does_not_import_torch(monkeypatch):
from core.inference.video import _VideoLoadState
backend = VideoBackend()
fam = _detect_load_family("leejet/MiniMax-H3-GGUF", None, "minimax-h3")
assert fam is not None
backend._state = _VideoLoadState(
pipe = object(),
family = fam,
repo_id = "leejet/MiniMax-H3-GGUF",
base_repo = fam.base_repo,
device = "cpu",
dtype = "Q4_K_M",
kind = "gguf",
engine = "sd_cpp",
gguf_filename = "minimax_h3_fl2va-Q4_K_M.gguf",
)
expected = {"mp4_bytes": b"native"}
monkeypatch.setattr(backend, "_generate_h3_native", lambda **_kwargs: expected)
original_import = builtins.__import__
def _no_torch_import(name, *args, **kwargs):
if name == "torch" or name.startswith("torch."):
raise AssertionError("native generation imported torch")
return original_import(name, *args, **kwargs)
monkeypatch.setattr(builtins, "__import__", _no_torch_import)
assert backend.generate(prompt = "a fox") is expected
def test_h3_native_loaded_repo_ids_cover_the_companion_repos():
# Runtime re-reads the GGUF mirror and component repo, so loaded ones cannot be deleted.
from core.inference.video import _VideoLoadState
H3_COMPONENT_REPO, H3_GGUF_REPO, _ = _shared_setup_3()
backend = VideoBackend()
assert backend.loaded_repo_ids() == ()
fam = _detect_load_family("leejet/MiniMax-H3-GGUF", None, "minimax-h3")
assert fam is not None
backend._state = _VideoLoadState(
pipe = object(),
family = fam,
repo_id = "leejet/MiniMax-H3-GGUF",
base_repo = fam.base_repo,
device = "cpu",
dtype = "Q4_K_M",
kind = "gguf",
engine = "sd_cpp",
gguf_filename = "minimax_h3_fl2va-Q4_K_M.gguf",
)
assert backend.loaded_repo_ids() == (
"leejet/MiniMax-H3-GGUF",
H3_GGUF_REPO,
H3_COMPONENT_REPO,
)
object.__setattr__(backend._state, "engine", "diffusers")
assert backend.loaded_repo_ids() == ()
def test_h3_modular_load_forwards_the_hub_token_to_the_component_loads(fake_runtime):
# The token must reach both the index load and the component from_pretrained calls.
pipe = _load_h3_modular(VideoBackend(), hf_token = "hf_secret")
assert _FakeModularPipeline.last["token"] == "hf_secret"
assert pipe.load_kwargs["token"] == "hf_secret"
pipe = _load_h3_modular(VideoBackend())
assert "token" not in pipe.load_kwargs
def test_h3_modular_load_pins_the_component_loads_to_the_studio_cache(fake_runtime):
"""Component loads need the Studio cache_dir, since HF_HUB_CACHE is a snapshot taken at import."""
from core.inference.video import hub_cache_dir
pipe = _load_h3_modular(VideoBackend())
assert _FakeModularPipeline.last["cache_dir"] == hub_cache_dir()
assert pipe.load_kwargs["cache_dir"] == hub_cache_dir()
def test_h3_modular_load_refuses_a_text_encoder_quant_it_cannot_honour(fake_runtime):
"""The modular path must raise on a text_encoder_quant it cannot honour, never drop it silently."""
backend = VideoBackend()
diffusers = sys.modules["diffusers"]
diffusers.ComponentsManager = _FakeComponentsManager
diffusers.ModularPipeline = _FakeModularPipeline
fam = _detect_load_family("MiniMaxAI/MiniMax-H3", None, "minimax-h3")
with pytest.raises(RuntimeError, match = "text_encoder_quant='fp8' could not be used"):
backend._load_h3_modular_pipeline(
diffusers = diffusers,
torch = sys.modules["torch"],
fam = fam,
repo_id = "MiniMaxAI/MiniMax-H3",
base = fam.base_repo,
kind = "pipeline",
dtype = sys.modules["torch"].bfloat16,
device = "cpu",
hf_token = None,
memory_mode = None,
text_encoder_quant = "fp8",
_load_token = None,
_base_local_dir = None,
)
def test_h3_modular_generation_ticks_and_cancels_through_the_scheduler(fake_runtime):
backend = VideoBackend()
pipe = _load_h3_modular(backend)
steps_seen: list = []
pipe.scheduler.on_step = lambda n: steps_seen.append(backend._gen.get("step"))
result = backend.generate(prompt = "a fox", steps = 4)
assert "callback_on_step_end" not in pipe.last_kwargs
# The reading inside step n is n-1: scheduler.step enqueues the step's update.
assert steps_seen == [0, 1, 2, 3]
assert pipe.scheduler.step.__func__ is _FakeH3Scheduler.step
assert result["num_frames"] == 124 and result["has_audio"] is False
backend = VideoBackend()
pipe = _load_h3_modular(backend)
# The cancel lands during the FIRST step; the next wrapped call must unwind the modular denoise
# instead of leaving Cancel to take effect only after the whole multi-minute run returns.
pipe.scheduler.on_step = lambda n: backend.cancel_generate() if n == 1 else None
with pytest.raises(RuntimeError, match = VIDEO_CANCELLED_MSG):
backend.generate(prompt = "a fox", steps = 4)
assert pipe.scheduler.calls == 1
assert pipe.scheduler.step.__func__ is _FakeH3Scheduler.step
@pytest.mark.parametrize("steps", [1, 2, 8, 20])
def test_h3_modular_runs_one_denoiser_evaluation_per_requested_step(fake_runtime, steps):
backend = VideoBackend()
pipe = _load_h3_modular(backend)
backend.generate(prompt = "a fox", steps = steps)
assert pipe.scheduler.calls == steps
assert pipe.last_kwargs["num_inference_steps"] == steps + 1
def test_h3_step_evaluations_kill_switch_passes_the_grid_through(fake_runtime, monkeypatch):
monkeypatch.setenv("UNSLOTH_H3_STEP_EVALUATIONS", "0")
backend = VideoBackend()
pipe = _load_h3_modular(backend)
backend.generate(prompt = "a fox", steps = 20)
assert pipe.last_kwargs["num_inference_steps"] == 20
assert pipe.scheduler.calls == 19
def test_the_pipeline_call_runs_with_uint8_frames_on_every_family(
fake_runtime, tmp_path, monkeypatch
):
active: list = []
@contextlib.contextmanager
def _frames(pipe):
active.append(pipe)
try:
yield
finally:
active.remove(pipe)
monkeypatch.setattr("core.inference.video.uint8_video_frames", _frames)
seen_inside: list = []
for backend, pipe in (
(_load_ltx23_from_dir(tmp_path), None),
(VideoBackend(), "h3"),
):
if pipe == "h3":
pipe = _load_h3_modular(backend)
else:
pipe = backend._state.pipe
original_call = type(pipe).__call__
def _call(
self,
*a,
_orig = original_call,
**k,
):
seen_inside.append(list(active) == [self])
return _orig(self, *a, **k)
monkeypatch.setattr(type(pipe), "__call__", functools.wraps(original_call)(_call))
backend.generate(prompt = "a fox", steps = 2)
assert seen_inside == [True, True] and active == []
def test_h3_native_transcode_is_torch_free_and_keeps_audio(monkeypatch, tmp_path):
import io
import math
from fractions import Fraction
av = pytest.importorskip("av")
np = pytest.importorskip("numpy")
from core.inference.video_minimax_h3 import transcode_video_to_mp4
source = tmp_path / "native.webm"
fps, sample_rate = 8, 48_000
with av.open(str(source), mode = "w", format = "webm") as output:
video = output.add_stream("libvpx-vp9", rate = fps)
video.width = video.height = 32
video.pix_fmt = "yuv420p"
audio = output.add_stream("libopus", rate = sample_rate)
audio.layout = "stereo"
for value in (0, 128):
frame = av.VideoFrame.from_ndarray(
np.full((32, 32, 3), value, dtype = np.uint8), format = "rgb24"
)
for packet in video.encode(frame):
output.mux(packet)
written = 0
while written < sample_rate // 4:
count = min(960, sample_rate // 4 - written)
tone = np.array(
[
int(12_000 * math.sin(2 * math.pi * 440 * (written + i) / sample_rate))
for i in range(count)
],
dtype = np.int16,
)
frame = av.AudioFrame.from_ndarray(
np.repeat(tone, 2).reshape(1, count * 2),
format = "s16",
layout = "stereo",
)
frame.sample_rate = sample_rate
frame.pts = written
frame.time_base = Fraction(1, sample_rate)
for packet in audio.encode(frame):
output.mux(packet)
written += count
for packet in video.encode():
output.mux(packet)
for packet in audio.encode():
output.mux(packet)
original_import = builtins.__import__
def _no_ml_stack_import(name, *args, **kwargs):
if name == "torch" or name.startswith(("torch.", "diffusers")):
raise AssertionError(f"native transcode imported {name}")
return original_import(name, *args, **kwargs)
monkeypatch.setattr(builtins, "__import__", _no_ml_stack_import)
mp4 = transcode_video_to_mp4(source, fps = fps)
with av.open(io.BytesIO(mp4)) as container:
assert container.streams.video[0].codec_context.name == "h264"
assert container.streams.audio[0].codec_context.name == "aac"
assert sum(frame.samples for frame in container.decode(audio = 0)) > 0
def test_download_plan_narrows_an_ltx23_pick_and_stages_its_extras(monkeypatch):
# A 2.3 checkpoint has its own VAEs/vocoder/connectors: stage those, not 2.0 base copies.
_plan_api_ltx23(monkeypatch)
plan = _ltx23_download_plan()
by_repo = {e["repo_id"]: e for e in plan["entries"]}
# One repo must be ONE entry, or two jobs collide on the scoped job key.
assert set(by_repo) == {"unsloth/LTX-2.3-GGUF", "Lightricks/LTX-2"}
ckpt = by_repo["unsloth/LTX-2.3-GGUF"]
assert ckpt["gguf_filename"] == "ltx-2.3-22b-distilled.gguf"
assert "vae/ltx-2.3-22b-distilled_video_vae.safetensors" in ckpt["files"]
assert "vae/ltx-2.3-22b-distilled_audio_vae.safetensors" in ckpt["files"]
assert "text_encoders/ltx-2.3-22b-distilled_embeddings_connectors.safetensors" in ckpt["files"]
assert "vae/ltx-2.3-22b-dev_video_vae.safetensors" not in ckpt["files"]
base = by_repo["Lightricks/LTX-2"]
assert "scheduler/scheduler_config.json" in base["files"]
assert any(f.startswith("text_encoder/") for f in base["files"])
for dropped in ("vae/", "vocoder/", "connectors/", "transformer/"):
assert not any(f.startswith(dropped) for f in base["files"]), dropped
assert plan["total_bytes"] == ckpt["bytes"] + base["bytes"]
def test_download_plan_stages_the_companions_of_a_cached_checkpoints_content_variant(
monkeypatch, tmp_path
):
# A cached checkpoint whose weights are dev under a distilled name stages the dev companions the load reads.
import core.inference.video as vid
import core.inference.video_ltx2 as ltx2
_plan_api_ltx23(monkeypatch)
cached = tmp_path / "ltx-2.3-22b-distilled.gguf"
monkeypatch.setattr(vid, "_cached_checkpoint_file", lambda repo_id, filename: cached)
monkeypatch.setattr(
ltx2, "ltx23_checkpoint_variant", lambda path: "dev" if Path(str(path)) == cached else None
)
plan = _ltx23_download_plan()
files = {e["repo_id"]: e for e in plan["entries"]}["unsloth/LTX-2.3-GGUF"]["files"]
assert "vae/ltx-2.3-22b-dev_video_vae.safetensors" in files
assert "vae/ltx-2.3-22b-distilled_video_vae.safetensors" not in files
def test_wan_a14b_local_base_excludes_both_experts(fake_runtime, monkeypatch):
# A paired pick replaces transformer and transformer_2, so a local base needs neither expert's weights.
import core.inference.diffusion as diffusion
seen = []
monkeypatch.setattr(
diffusion,
"_assert_local_base_is_pipeline",
lambda base, *, excluded_components = (), **kw: seen.append(tuple(excluded_components)),
)
VideoBackend().validate_load_request(
"QuantStack/Wan2.2-T2V-A14B-GGUF",
gguf_filename = "HighNoise/Wan2.2-T2V-A14B-HighNoise-Q4_K_M.gguf",
)
assert seen and set(seen[-1]) == {"transformer", "transformer_2"}
def _cuda_bf16_target(monkeypatch):
"""Pretend the box can run layerwise fp8, so the pre-cast encoder resolves off-GPU."""
import torch
monkeypatch.setattr(
"core.inference.video.resolve_diffusion_device_target",
lambda: types.SimpleNamespace(device = "cuda", dtype = torch.bfloat16),
)
_LTX2_FP8_SIBLINGS = [_PlanSibling("LTX-2-text_encoder-FP8.pt", 13_000_000_000)]
def test_base_download_files_skips_precast_text_encoder_weights():
# The pre-cast checkpoint supplies the encoder WEIGHTS only: the config and shard index stay, since the loader meta-inits from them.
siblings = _LTX2_SIBLINGS + [
_sibling("text_encoder/config.json", 1),
_sibling("text_encoder/model.safetensors.index.json", 1),
]
info = types.SimpleNamespace(siblings = siblings)
names = [
n
for n, _ in VideoBackend._base_download_files(
info, "gguf", skip_te_components = ("text_encoder",)
)
]
assert not any(n.endswith(".safetensors") and n.startswith("text_encoder/") for n in names)
assert "text_encoder/config.json" in names
assert "text_encoder/model.safetensors.index.json" in names
assert "vae/diffusion_pytorch_model.safetensors" in names
def test_download_plan_swaps_the_dense_encoder_for_the_precast_checkpoint(monkeypatch):
# An fp8 encoder request loads unsloth/LTX-2-FP8, so do not stage the dense Gemma3.
_cuda_bf16_target(monkeypatch)
_plan_api(
monkeypatch,
{
"unsloth/LTX-2.3-GGUF": _LTX23_REPO_SIBLINGS,
"Lightricks/LTX-2": _LTX_BASE_SIBLINGS,
"unsloth/LTX-2-FP8": _LTX2_FP8_SIBLINGS,
},
)
plan = VideoBackend().download_plan(
"unsloth/LTX-2.3-GGUF",
gguf_filename = "ltx-2.3-22b-distilled.gguf",
family_override = "ltx-2",
text_encoder_quant = "fp8",
)
by_repo = {e["repo_id"]: e for e in plan["entries"]}
assert by_repo["unsloth/LTX-2-FP8"]["files"] == ["LTX-2-text_encoder-FP8.pt"]
base = by_repo["Lightricks/LTX-2"]
assert not any(f.startswith("text_encoder/") for f in base["files"])
assert "scheduler/scheduler_config.json" in base["files"]
assert "tokenizer/tokenizer.json" in base["files"]
assert plan["total_bytes"] == sum(e["bytes"] for e in plan["entries"])
def test_download_plan_keeps_dense_encoder_for_a_custom_family_pipeline(monkeypatch):
_cuda_bf16_target(monkeypatch)
custom = "someone/custom-ltx-2"
_plan_api(
monkeypatch,
{
custom: _LTX_BASE_SIBLINGS,
"unsloth/LTX-2-FP8": _LTX2_FP8_SIBLINGS,
},
)
plan = VideoBackend().download_plan(
custom,
model_kind = "pipeline",
family_override = "ltx-2",
text_encoder_quant = "fp8",
)
by_repo = {entry["repo_id"]: entry for entry in plan["entries"]}
assert "unsloth/LTX-2-FP8" not in by_repo
assert any(name.startswith("text_encoder/") for name in by_repo[custom]["files"])
def test_download_plan_keeps_the_dense_encoder_without_an_fp8_request(monkeypatch):
# No fp8 request means the dense encoder IS the encoder: dropping it would break the load.
_cuda_bf16_target(monkeypatch)
_plan_api_ltx23(monkeypatch)
plan = _ltx23_download_plan()
by_repo = {e["repo_id"]: e for e in plan["entries"]}
assert "unsloth/LTX-2-FP8" not in by_repo
assert any(f.startswith("text_encoder/") for f in by_repo["Lightricks/LTX-2"]["files"])
def test_download_plan_keeps_the_dense_encoder_when_the_precast_repo_is_missing(monkeypatch):
# An unavailable hosted artifact must neither drop the dense encoder nor sink the plan.
_cuda_bf16_target(monkeypatch)
_plan_api_ltx23(monkeypatch)
plan = VideoBackend().download_plan(
"unsloth/LTX-2.3-GGUF",
gguf_filename = "ltx-2.3-22b-distilled.gguf",
family_override = "ltx-2",
text_encoder_quant = "fp8",
)
by_repo = {e["repo_id"]: e for e in plan["entries"]}
assert set(by_repo) == {"unsloth/LTX-2.3-GGUF", "Lightricks/LTX-2"}
assert any(f.startswith("text_encoder/") for f in by_repo["Lightricks/LTX-2"]["files"])
assert plan["total_bytes"] == sum(e["bytes"] for e in plan["entries"]) > 0
def test_fetch_te_prequant_only_reports_what_it_downloaded(monkeypatch):
# The dense skip is earned by the pre-cast file being on disk; an unreachable checkpoint must report nothing.
backend = VideoBackend()
source = types.SimpleNamespace(
kind = "repo", location = "unsloth/LTX-2-FP8", filename = "LTX-2-text_encoder-FP8.pt"
)
def _boom(
repo,
filename,
token,
cancel_event = None,
**kwargs,
):
raise OSError("404")
monkeypatch.setattr("utils.hf_xet_fallback.hf_hub_download_with_xet_fallback", _boom)
assert backend._fetch_te_prequant({"text_encoder": source}, None) == ()
monkeypatch.setattr(
"utils.hf_xet_fallback.hf_hub_download_with_xet_fallback",
lambda repo, filename, token, cancel_event = None, **kwargs: "/tmp/precast.pt",
)
assert backend._fetch_te_prequant({"text_encoder": source}, None) == ("text_encoder",)
local = types.SimpleNamespace(kind = "path", location = "/tmp/x.pt", filename = None)
assert backend._fetch_te_prequant({"text_encoder": local}, None) == ()
def test_fetch_te_prequant_takes_a_mirrored_encoder_without_the_hub(monkeypatch, tmp_path):
from core.inference import diffusion_te_prequant as te_prequant
backend = VideoBackend()
source = types.SimpleNamespace(
kind = "repo", location = "unsloth/LTX-2-FP8", filename = "LTX-2-text_encoder-FP8.safetensors"
)
(tmp_path / "unsloth" / "LTX-2-FP8").mkdir(parents = True)
(tmp_path / "unsloth" / "LTX-2-FP8" / "LTX-2-text_encoder-FP8.safetensors").write_bytes(b"x")
monkeypatch.setenv(te_prequant.TE_PREQUANT_MIRROR_ENV, str(tmp_path))
def _no_hub(*_a, **_k):
raise AssertionError("the Hub was asked")
monkeypatch.setattr("utils.hf_xet_fallback.hf_hub_download_with_xet_fallback", _no_hub)
for offline in (False, True):
assert backend._fetch_te_prequant(
{"text_encoder": source}, None, local_files_only = offline
) == ("text_encoder",)
def test_load_pipeline_tops_up_the_dense_encoder_when_injection_fails(fake_runtime, tmp_path):
# A failed injection must restore the dropped dense shards rather than crash.
backend = VideoBackend()
calls: list[dict] = []
backend._predownload_base = lambda *a, **k: ( # type: ignore[method-assign]
calls.append({"args": a, "kwargs": k}) or str(tmp_path)
)
backend.load_pipeline(
"Lightricks/LTX-2",
model_kind = "pipeline",
_base_local_dir = str(tmp_path),
_te_prequant_skipped = ("text_encoder",),
)
assert len(calls) == 1 and calls[0]["kwargs"]["ltx23"] is False
backend.unload()
calls.clear()
backend.load_pipeline("Lightricks/LTX-2", model_kind = "pipeline", _base_local_dir = str(tmp_path))
assert calls == []
backend.unload()
def test_download_plan_keeps_the_wide_base_for_a_plain_ltx2_pick(monkeypatch):
# Only 2.3 checkpoints supply their own companions; a 2.0 pick still needs the base's.
_plan_api(
monkeypatch,
{
"someone/LTX-2-GGUF": [_PlanSibling("ltx-2-dev.gguf", 12_000_000_000)],
"Lightricks/LTX-2": _LTX_BASE_SIBLINGS,
},
)
plan = VideoBackend().download_plan(
"someone/LTX-2-GGUF", gguf_filename = "ltx-2-dev.gguf", family_override = "ltx-2"
)
base = next(e for e in plan["entries"] if e["repo_id"] == "Lightricks/LTX-2")
assert any(f.startswith("vae/") for f in base["files"])
assert any(f.startswith("connectors/") for f in base["files"])
assert not any(f.startswith("transformer/") for f in base["files"])
def test_each_video_load_gets_its_own_cancel_event(monkeypatch):
"""Each load gets its own cancel event; a shared one would un-cancel the previous worker."""
import threading
from types import SimpleNamespace
from core.inference.video import VideoBackend
backend = VideoBackend.__new__(VideoBackend)
backend._lock = threading.RLock()
backend._generate_lock = threading.RLock()
backend._cancel_event = threading.Event()
backend._load_token = 0
backend._loading = None
backend._active_generate_cancel = None
backend._state = None
started: list[threading.Event] = []
monkeypatch.setattr(
threading, "Thread", lambda *a, **k: SimpleNamespace(start = lambda: None, daemon = True)
)
fam = SimpleNamespace(base_repo = "org/base", name = "wan2.2-ti2v-5b")
monkeypatch.setattr(VideoBackend, "validate_load_request", lambda self, *a, **k: fam)
monkeypatch.setattr(VideoBackend, "status", lambda self: {})
backend.begin_load("org/base")
first = backend._cancel_event
started.append(first)
# unload() signals the in-flight worker and clears _loading, letting a new load through.
backend._teardown_waiters = 0
backend._teardown_state_locked = lambda: None
backend.unload()
assert first.is_set(), "unload must cancel the in-flight load"
backend.begin_load("org/other")
second = backend._cancel_event
assert second is not first, "each load needs its own event"
assert first.is_set(), "the replaced load must stay cancelled"
assert not second.is_set(), "a fresh load starts uncancelled"
class _HookedLock:
"""threading.Lock wrapper that fires on_release after a release by the named thread, so a
generation parked on _generate_lock is admitted at that instant."""
def __init__(self, on_release, thread_name: str) -> None:
self._lock = threading.Lock()
self._on_release = on_release
self._thread_name = thread_name
def acquire(self, *args, **kwargs):
return self._lock.acquire(*args, **kwargs)
def release(self) -> None:
self._lock.release()
if threading.current_thread().name == self._thread_name:
self._on_release()
def __enter__(self):
self.acquire()
return self
def __exit__(self, *_exc) -> None:
self.release()
def _run_teardown_race(backend, teardown):
"""Park a generation on _generate_lock, admit it on release, and report its outcome."""
queued: dict = {}
admitted = threading.Event()
finished = threading.Event()
def queued_generate():
assert admitted.wait(timeout = 5), "queued generation never admitted"
try:
queued["out"] = backend.generate(prompt = "queued", steps = 2)
except RuntimeError as exc:
queued["error"] = str(exc)
finally:
finished.set()
waiter = threading.Thread(target = queued_generate, daemon = True)
waiter.start()
def on_release():
# The barrier just released _generate_lock: hold the teardown here until the queued generation has had its turn.
admitted.set()
finished.wait(timeout = 5)
backend._generate_lock = _HookedLock(on_release, "teardown-under-test")
runner = threading.Thread(target = teardown, name = "teardown-under-test")
runner.start()
runner.join(timeout = 10)
assert not runner.is_alive(), "teardown never finished"
waiter.join(timeout = 5)
assert not waiter.is_alive(), "queued generation never finished"
return queued
def test_unload_fences_a_generation_queued_behind_its_barrier(fake_runtime, tmp_path):
# A queued run has no cancel event; locks are not FIFO, so it may hit a freed pipeline.
backend = VideoBackend()
_load_gguf(backend, tmp_path)
queued = _run_teardown_race(backend, backend.unload)
assert (
"out" not in queued
), "a generation queued behind the unload barrier ran against a pipeline being torn down"
assert queued.get("error") in (VIDEO_NOT_LOADED_MSG, VIDEO_CANCELLED_MSG), queued
assert backend._state is None
assert backend._teardown_waiters == 0
def test_superseding_load_fences_a_generation_queued_behind_its_barrier(fake_runtime, tmp_path):
# The load path takes the same barrier before tearing the old model down, so it has the same hole.
backend = VideoBackend()
_load_gguf(backend, tmp_path)
queued = _run_teardown_race(backend, lambda: _load_gguf(backend, tmp_path))
assert (
"out" not in queued
), "a generation queued behind the load barrier ran against a pipeline being torn down"
assert queued.get("error") in (VIDEO_NOT_LOADED_MSG, VIDEO_CANCELLED_MSG), queued
assert backend._teardown_waiters == 0
def test_generation_refuses_while_a_teardown_is_waiting(fake_runtime, tmp_path):
# The fence's effect: with a teardown waiting on _generate_lock, a generation that wins the lock refuses instead of denoising.
backend = VideoBackend()
_load_gguf(backend, tmp_path)
assert backend.generate(prompt = "before", steps = 2)["mp4_bytes"] == b"MP4"
backend._teardown_waiters = 1
with pytest.raises(RuntimeError, match = "cancelled"):
backend.generate(prompt = "during", steps = 2)
assert backend._state is not None
backend._teardown_waiters = 0
assert backend.generate(prompt = "after", steps = 2)["mp4_bytes"] == b"MP4"
def test_a_raising_teardown_still_drains_the_fence(fake_runtime, tmp_path, monkeypatch):
# clear_gpu_cache() raises on a sticky CUDA fault; the finally keeps the fence from sticking.
from core.inference import video as video_mod
backend = VideoBackend()
_load_gguf(backend, tmp_path)
def _sticky():
raise RuntimeError("CUDA error: an illegal memory access was encountered")
monkeypatch.setattr(video_mod, "clear_gpu_cache", _sticky)
with pytest.raises(RuntimeError, match = "illegal memory access"):
backend.unload()
assert backend._teardown_waiters == 0, "a failed teardown must not leave the fence up"
monkeypatch.setattr(video_mod, "clear_gpu_cache", lambda: None)
_load_gguf(backend, tmp_path)
assert backend.generate(prompt = "after", steps = 2)["mp4_bytes"] == b"MP4"
def test_teardown_returns_freed_host_pages_after_the_gpu_cache(fake_runtime, tmp_path, monkeypatch):
from core.inference import video as video_mod
backend = VideoBackend()
_load_gguf(backend, tmp_path)
order = []
monkeypatch.setattr(video_mod, "clear_gpu_cache", lambda: order.append("clear"))
monkeypatch.setattr(
video_mod,
"reclaim_host_memory",
lambda logger = None: order.append(("trim", backend._state is None)) or True,
)
assert backend.unload()["loaded"] is False
assert order == ["clear", ("trim", True)]
def test_the_h3_native_load_never_puts_the_vae_on_the_cpu():
"""H3 must never get --vae-on-cpu, since its audio VAE aborts sd-cli on that path (exit 134)."""
import ast
from pathlib import Path
source = (Path(__file__).resolve().parent.parent / "core" / "inference" / "video.py").read_text(
encoding = "utf-8"
)
tree = ast.parse(source)
calls = [
node
for node in ast.walk(tree)
if isinstance(node, ast.Call)
and isinstance(node.func, ast.Name)
and node.func.id == "offload_flags"
]
assert calls, "video.py no longer builds native offload flags"
for call in calls:
opt_out = [kw for kw in call.keywords if kw.arg == "vae_on_cpu"]
assert opt_out, "the H3 native path must ask for the VAE to stay off the CPU"
assert isinstance(opt_out[0].value, ast.Constant) and opt_out[0].value.value is False
from core.inference.sd_cpp_args import OFFLOAD_MODEL, offload_flags
assert "--vae-on-cpu" in offload_flags(OFFLOAD_MODEL)
assert "--vae-on-cpu" not in offload_flags(OFFLOAD_MODEL, vae_on_cpu = False)
def test_h3_rejects_companion_checkpoints_as_the_transformer():
"""Only denoiser partitions are valid H3 transformer picks; the mirror also ships encoder quants."""
from core.inference.video_minimax_h3 import (
H3_TASK_KEYFRAMES,
H3_TASK_REFERENCES,
h3_transformer_task,
validate_h3_transformer_filename,
)
for good, task in (
("minimax_h3_fl2va_pruned-UD-Q2_K_XL.gguf", H3_TASK_KEYFRAMES),
("minimax_h3_fl2va_pruned-UD-Q3_K_XL.gguf", H3_TASK_KEYFRAMES),
("minimax_h3_fl2va_pruned-Q4_K.gguf", H3_TASK_KEYFRAMES),
("minimax_h3_fl2va-Q4_K_M.gguf", H3_TASK_KEYFRAMES),
("minimax_h3_ref2va_pruned-Q2_K_M.gguf", H3_TASK_REFERENCES),
("minimax_h3_ref2va-Q4_K_M.gguf", H3_TASK_REFERENCES),
):
validate_h3_transformer_filename(good)
assert h3_transformer_task(good) == task
for bad in (
"qwen3vl_32b_minimax_h3-Q2_K_M.gguf",
"qwen3vl_32b_minimax_h3-Q4_K_M.gguf",
"minimax_h3_video_vae_fp16.safetensors",
"minimax_h3_fl2va_pruned_bf16.safetensors",
):
with pytest.raises(ValueError):
validate_h3_transformer_filename(bad)
def _no_legacy_cache(monkeypatch):
"""Pretend no legacy repo ids are cached, so a machine's real HF cache cannot change the answer."""
from core.inference import diffusion_families
monkeypatch.setattr(
diffusion_families, "_upstream_is_cached", lambda *a, **k: False, raising = True
)
def test_every_h3_asset_comes_from_an_unsloth_repo(monkeypatch):
"""Every H3 repo a fresh install reaches must be Unsloth's; legacy ids are the only exemption."""
from core.inference.video_minimax_h3 import (
H3_COMPONENT_REPO,
H3_GGUF_REPO,
h3_native_hub_files,
)
from core.inference.video_minimax_h3_te import H3_TE_QUANT_REPO, h3_te_quant_source
_no_legacy_cache(monkeypatch)
named = {H3_GGUF_REPO, H3_COMPONENT_REPO, H3_TE_QUANT_REPO, h3_te_quant_source("int8")}
named.update(repo for repo, _ in h3_native_hub_files("minimax_h3_fl2va_pruned-Q2_K.gguf"))
offenders = sorted(r for r in named if not r.startswith("unsloth/"))
assert not offenders, f"H3 would download from a repo we do not control: {offenders}"
def test_the_native_h3_vaes_come_from_a_local_bundle_when_it_has_them(tmp_path):
"""A local mirror clone is self-contained, so its VAEs must not be fetched from the Hub."""
from core.inference.video import VideoBackend
from core.inference.video_minimax_h3 import (
H3_AUDIO_VAE,
H3_COMPONENT_REPO,
H3_GGUF_REPO,
H3_VIDEO_VAE,
h3_text_encoder_filename,
)
gguf = "minimax_h3_fl2va_pruned-Q2_K.gguf"
qwen = h3_text_encoder_filename(gguf)
bundle = tmp_path / "MiniMax-H3-GGUF"
(bundle / "vae").mkdir(parents = True)
for name in (gguf, qwen):
(bundle / name).write_bytes(b"x")
for name in (H3_VIDEO_VAE, H3_AUDIO_VAE):
(bundle / name).parent.mkdir(parents = True, exist_ok = True)
(bundle / name).write_bytes(b"x")
requests = VideoBackend._h3_native_requests(str(bundle), gguf, qwen)
assert [repo for repo, _ in requests] == [str(bundle)] * 4
assert [name for _, name in requests] == [gguf, qwen, H3_VIDEO_VAE, H3_AUDIO_VAE]
# A bundle missing the audio VAE keeps that ONE file on the mirror, not the whole set.
(bundle / H3_AUDIO_VAE).unlink()
assert VideoBackend._h3_native_requests(str(bundle), gguf, qwen) == (
(str(bundle), gguf),
(str(bundle), qwen),
(str(bundle), H3_VIDEO_VAE),
(H3_COMPONENT_REPO, H3_AUDIO_VAE),
)
assert VideoBackend._h3_native_requests(H3_GGUF_REPO, gguf, qwen) == (
(H3_GGUF_REPO, gguf),
(H3_GGUF_REPO, qwen),
(H3_COMPONENT_REPO, H3_VIDEO_VAE),
(H3_COMPONENT_REPO, H3_AUDIO_VAE),
)
def _legacy_cache_holding(monkeypatch, names):
"""Pretend the repack's cache holds exactly ``names``, and nothing else does."""
from core.inference import diffusion_families
def _probe(
repo_id,
files = None,
*,
other_root = False,
):
return bool(files) and set(files) <= set(names)
monkeypatch.setattr(diffusion_families, "_upstream_is_cached", _probe)
def test_the_h3_native_repo_matches_the_family_gguf_repo():
"""H3_GGUF_REPO must match the family gguf_repo, since the native path never reads that field."""
from core.inference.video_families import detect_video_family
from core.inference.video_minimax_h3 import (
H3_GGUF_REPO,
h3_native_hub_files,
)
family = detect_video_family("MiniMaxAI/MiniMax-H3")
assert family is not None
assert H3_GGUF_REPO == family.gguf_repo, (
f"H3 native downloads from {H3_GGUF_REPO} but the family advertises "
f"{family.gguf_repo}; the curated-mirror test would pass vacuously"
)
files = h3_native_hub_files("minimax_h3_fl2va_pruned-UD-Q2_K_XL.gguf")
transformer_repo, transformer_name = files[0]
encoder_repo, encoder_name = files[1]
assert transformer_repo == encoder_repo == H3_GGUF_REPO
assert transformer_name == "minimax_h3_fl2va_pruned-UD-Q2_K_XL.gguf"
# The dynamic rung names must still route to the matching encoder tier.
assert encoder_name == "qwen3vl_32b_minimax_h3-Q2_K_M.gguf"
assert h3_native_hub_files("minimax_h3_fl2va_pruned-UD-Q3_K_XL.gguf")[1][1] == (
"qwen3vl_32b_minimax_h3-Q4_K_M.gguf"
)
def test_h3_names_the_component_when_a_download_is_refused():
"""A refused H3 download must name its component; the Hub's Repository Not Found is ambiguous."""
from unittest.mock import Mock
from huggingface_hub.errors import GatedRepoError, RepositoryNotFoundError
from core.inference.video_minimax_h3 import (
H3_AUDIO_VAE,
H3_QWEN_Q2,
h3_download_error,
)
def _hub_error(cls):
response = Mock()
response.status_code = 401
response.headers = {}
return cls("Repository Not Found for url: ...", response = response)
denoiser = h3_download_error(
"unsloth/MiniMax-H3-GGUF",
"minimax_h3_fl2va_pruned-UD-Q2_K_XL.gguf",
_hub_error(RepositoryNotFoundError),
)
assert isinstance(denoiser, RuntimeError)
text = str(denoiser)
assert "unsloth/MiniMax-H3-GGUF" in text
assert "denoiser" in text
assert "not published yet" in text
# The same repo serves the encoder, so the component name has to come from the FILE.
encoder = str(
h3_download_error(
"unsloth/MiniMax-H3-GGUF", H3_QWEN_Q2, _hub_error(RepositoryNotFoundError)
)
)
assert "text encoder" in encoder and "denoiser" not in encoder
# A gated repo has a different remedy, so it must not reuse the private wording.
gated = str(h3_download_error("Comfy-Org/MiniMax-H3", H3_AUDIO_VAE, _hub_error(GatedRepoError)))
assert "audio VAE" in gated
assert "accept its licence" in gated
assert "not published yet" not in gated
# Non-access errors pass through, so a timeout is not reworded as a permissions problem.
timeout = TimeoutError("read timed out")
assert h3_download_error("unsloth/MiniMax-H3-GGUF", H3_QWEN_Q2, timeout) is timeout
def test_the_h3_native_path_pins_cfg_scale_to_one():
"""H3 must pin cfg to 1.0 on the native path: any higher cfg hits a ggml assert and aborts sd-cli."""
import ast
from pathlib import Path
source = (Path(__file__).resolve().parent.parent / "core" / "inference" / "video.py").read_text(
encoding = "utf-8"
)
calls = [
node
for node in ast.walk(ast.parse(source))
if isinstance(node, ast.Call)
and isinstance(node.func, ast.Name)
and node.func.id == "SdCppVideoGenParams"
]
assert calls, "video.py no longer builds native video params"
for call in calls:
pinned = [kw for kw in call.keywords if kw.arg == "cfg_scale"]
assert (
pinned
), "the H3 native path must pass cfg_scale explicitly, not fall back to a default"
value = pinned[0].value
assert isinstance(value, ast.Constant), (
"cfg_scale must be a literal 1.0 on the H3 native path; forwarding the request's "
"guidance reintroduces GGML_ASSERT(!ggml_is_transposed(a)), SIGABRT exit 134"
)
assert value.value == 1.0, value.value
from core.inference.video_families import detect_video_family
assert detect_video_family("MiniMaxAI/MiniMax-H3").supports_cfg is False
def _trim_spy(monkeypatch):
"""Record every install_hunyuan_attention_trim call and report it as engaged."""
from core.inference import video as video_mod
calls: list = []
def _fake(
pipe,
family,
*,
logger = None,
):
calls.append(getattr(family, "name", None))
return True
monkeypatch.setattr(video_mod, "install_hunyuan_attention_trim", _fake)
return calls
def test_attention_trim_installed_and_reported(fake_runtime, monkeypatch):
# Padded-text trim installs once per pipe, and reports as a speed optim when engaged.
calls = _trim_spy(monkeypatch)
backend = VideoBackend()
status = backend.load_pipeline(
"Wan-AI/Wan2.2-TI2V-5B-Diffusers", model_kind = "pipeline", speed_mode = "default"
)
assert status["loaded"] is True
assert len(calls) == 1
assert "hunyuan_attn_trim" in status["speed_optims"]
def test_attention_trim_skipped_on_the_off_tier(fake_runtime, monkeypatch):
calls = _trim_spy(monkeypatch)
backend = VideoBackend()
status = backend.load_pipeline(
"Wan-AI/Wan2.2-TI2V-5B-Diffusers", model_kind = "pipeline", speed_mode = "off"
)
assert status["loaded"] is True
assert calls == []
assert "hunyuan_attn_trim" not in status["speed_optims"]
@pytest.mark.parametrize("mode", ["eager", "default", "max"])
def test_attention_trim_installed_on_every_speed_tier(fake_runtime, monkeypatch, mode):
calls = _trim_spy(monkeypatch)
backend = VideoBackend()
status = backend.load_pipeline(
"Wan-AI/Wan2.2-TI2V-5B-Diffusers", model_kind = "pipeline", speed_mode = mode
)
assert status["loaded"] is True
assert len(calls) == 1
assert "hunyuan_attn_trim" in status["speed_optims"]
def test_every_video_fetch_resolves_both_cache_roots():
"""Every video load fetch must resolve both cache roots, or planner-skipped files get re-pulled."""
# Every module on the video load path, including video_ltx2.py.
root = Path(__file__).resolve().parents[1] / "core/inference"
for name in ("video.py", "video_ltx2.py"):
src = (root / name).read_text(encoding = "utf-8")
# The bare `from ... import name` has no trailing paren, so this counts call sites only.
calls = src.count("hf_hub_download_with_xet_fallback(")
if calls == 0:
continue
optins = src.count("reuse_other_cache_root = True")
assert optins == calls, (
f"{name}: {calls - optins} of {calls} video fetches resolve only the active cache "
"root, so the planner's both-roots probe can drop a file the load cannot then find"
)
def _unified_snapshot(total_gib):
"""Stand in for a Mac's memory snapshot: unified pool, 80% of RAM free."""
from core.inference.diffusion_memory import DeviceMemory
total = total_gib * 1024
return lambda target: DeviceMemory("mps", "mps", "unified_memory", int(total * 0.80), total)
def test_unified_memory_refuses_an_oversized_video_load(fake_runtime, monkeypatch):
"""Unified memory refuses an oversized video load up front; the OS would kill it silently."""
import core.inference.video as video_mod
monkeypatch.setattr(video_mod, "settled_snapshot_device_memory", _unified_snapshot(16))
backend = VideoBackend()
with pytest.raises(RuntimeError) as excinfo:
backend.load_pipeline("Lightricks/LTX-2", model_kind = "pipeline")
message = str(excinfo.value)
assert "ltx-2" in message
assert "unified memory" in message
assert "UNSLOTH_DIFFUSION_ALLOW_OVERSIZED_LOAD=1" in message
# Refused BEFORE the pipeline was built: nothing was allocated and nothing is loaded.
assert backend.status()["loaded"] is False
def test_unified_memory_allows_a_video_load_that_fits(fake_runtime, monkeypatch):
# The same family on a 128 GiB Mac fits, so the refusal must stay out of the way.
import core.inference.video as video_mod
monkeypatch.setattr(video_mod, "settled_snapshot_device_memory", _unified_snapshot(128))
backend = VideoBackend()
status = backend.load_pipeline("Lightricks/LTX-2", model_kind = "pipeline")
assert status["loaded"] is True
def test_unified_memory_refusal_is_overridable_at_the_video_load_seam(fake_runtime, monkeypatch):
import core.inference.video as video_mod
from core.inference.diffusion_memory import UNIFIED_OVERSIZE_ENV
monkeypatch.setattr(video_mod, "settled_snapshot_device_memory", _unified_snapshot(16))
monkeypatch.setenv(UNIFIED_OVERSIZE_ENV, "1")
backend = VideoBackend()
assert backend.load_pipeline("Lightricks/LTX-2", model_kind = "pipeline")["loaded"] is True
def test_discrete_vram_video_load_is_unaffected_by_the_refusal(fake_runtime, monkeypatch):
"""A discrete-VRAM snapshot must not hit the refusal; offload streams weights from host RAM."""
import core.inference.video as video_mod
from core.inference.diffusion_memory import DeviceMemory
monkeypatch.setattr(
video_mod,
"settled_snapshot_device_memory",
lambda target: DeviceMemory("cuda", "cuda", "discrete_vram", 13_107, 16_384),
)
backend = VideoBackend()
assert backend.load_pipeline("Lightricks/LTX-2", model_kind = "pipeline")["loaded"] is True
def test_the_mps_allocator_cache_is_released_before_the_budget_is_read(monkeypatch):
"""Empty the MPS cache before reading the budget; freed pipelines stay reserved and look used."""
import sys
import types
import core.inference.diffusion_memory as dm
calls: list = []
fake_torch = types.SimpleNamespace(
mps = types.SimpleNamespace(empty_cache = lambda: calls.append("mps"))
)
monkeypatch.setitem(sys.modules, "torch", fake_torch)
monkeypatch.setattr(
dm,
"snapshot_device_memory",
lambda t: dm.DeviceMemory("mps", "mps", "unified_memory", 1, 2),
)
dm.settled_snapshot_device_memory(types.SimpleNamespace(device = "mps", backend = "mps"))
assert calls == ["mps"], "the MPS allocator must be emptied before the reading is taken"
def _fake_h3_vae():
"""A stand-in with the shapes that matter: an encoder half, a decoder with both
autocast-eligible and float32-only parameters, and a post_quant_conv."""
import torch
class _VAE(torch.nn.Module):
def __init__(self):
super().__init__()
self.encoder = torch.nn.Sequential(torch.nn.Conv3d(4, 8, 1))
self.quant_conv = torch.nn.Conv3d(8, 8, 1)
self.decoder = torch.nn.Module()
self.decoder.proj = torch.nn.Linear(8, 16)
self.decoder.conv = torch.nn.Conv3d(16, 4, 1)
self.decoder.norm = torch.nn.LayerNorm(16)
# Read directly rather than through an autocast-eligible op.
self.decoder.register_parameter(
"scale1", torch.nn.Parameter(torch.ones(16, dtype = torch.float32))
)
self.post_quant_conv = torch.nn.Conv3d(4, 4, 1)
return _VAE().to(torch.float32)
def test_h3_vae_trim_drops_the_encoder_only_for_a_workflow_that_never_encodes():
import torch
from core.inference.video_minimax_h3 import trim_h3_video_vae
vae = _fake_h3_vae()
report = trim_h3_video_vae(vae, workflow = "t2va")
assert vae.encoder is None and vae.quant_conv is None
assert report["encoder_freed"] > 0
other = _fake_h3_vae()
other_report = trim_h3_video_vae(other, workflow = "ref2va")
assert other.encoder is not None and other.quant_conv is not None
assert other_report["encoder_freed"] == 0
assert other_report["decoder_freed"] > 0
assert other.decoder.proj.weight.dtype is torch.float16
def test_h3_vae_trim_precasts_only_what_autocast_would_cast():
import torch
from core.inference.video_minimax_h3 import trim_h3_video_vae
vae = _fake_h3_vae()
trim_h3_video_vae(vae, workflow = "t2va")
# Linear and Conv weights and biases are what torch.autocast casts on entry.
assert vae.decoder.proj.weight.dtype is torch.float16
assert vae.decoder.proj.bias.dtype is torch.float16
assert vae.decoder.conv.weight.dtype is torch.float16
assert vae.post_quant_conv.weight.dtype is torch.float16
# A norm gain is on autocast's float32 list and a bare parameter is read directly.
assert vae.decoder.norm.weight.dtype is torch.float32
assert vae.decoder.scale1.dtype is torch.float32
def test_h3_vae_trim_leaves_the_decode_arithmetic_bit_identical():
# Pre-casting is valid because autocast does the same cast; verify on a real matmul.
import torch
from core.inference.video_minimax_h3 import trim_h3_video_vae
torch.manual_seed(0)
reference = _fake_h3_vae()
trimmed = _fake_h3_vae()
trimmed.load_state_dict(reference.state_dict())
trim_h3_video_vae(trimmed, workflow = "t2va")
x = torch.randn(3, 8, dtype = torch.float16)
autocast_style = torch.nn.functional.linear(
x,
reference.decoder.proj.weight.to(torch.float16),
reference.decoder.proj.bias.to(torch.float16),
)
precast = trimmed.decoder.proj(x)
assert torch.equal(autocast_style, precast)
def test_h3_vae_trim_survives_a_renamed_attribute():
# A diffusers release that moves these attributes should cost the saving, not the render.
import torch
from core.inference.video_minimax_h3 import trim_h3_video_vae
assert trim_h3_video_vae(None, workflow = "t2va") == {"encoder_freed": 0, "decoder_freed": 0}
bare = torch.nn.Module()
assert trim_h3_video_vae(bare, workflow = "t2va")["decoder_freed"] == 0
def test_h3_canvas_follows_the_released_checkpoint_rule():
from core.inference.video_minimax_h3 import h3_canvas_for_aspect
# The area cap brings 16:9 to the checkpoint's 1344x768 default.
assert h3_canvas_for_aspect(1920, 1080) == (1344, 768)
assert h3_canvas_for_aspect(1080, 1920) == (768, 1344)
assert h3_canvas_for_aspect(1000, 1000) == (768, 768)
# 4:3 stays under the cap, so the short edge is honoured exactly.
assert h3_canvas_for_aspect(1024, 768) == (1024, 768)
assert h3_canvas_for_aspect(160, 90) == h3_canvas_for_aspect(3840, 2160)
# Outside the trained 1:4 - 4:1 band, refuse rather than generate off-distribution.
with pytest.raises(ValueError, match = "aspect ratios"):
h3_canvas_for_aspect(2000, 400)
with pytest.raises(ValueError, match = "aspect ratio"):
h3_canvas_for_aspect(0, 100)
def test_h3_keyframe_fit_stretches_the_first_and_crops_the_last():
Image = pytest.importorskip("PIL.Image")
from core.inference.video_minimax_h3 import (
H3_ANCHOR_FIRST,
H3_ANCHOR_LAST,
fit_h3_keyframe,
)
# A 2:1 source on a square canvas distinguishes stretch from center crop.
source = Image.new("RGB", (200, 100), (0, 0, 0))
for x in range(200):
for y in range(100):
source.putpixel((x, y), (255, 0, 0) if x < 20 or x >= 180 else (0, 0, 255))
first = fit_h3_keyframe(source, 128, 128, anchor = H3_ANCHOR_FIRST)
assert first.size == (128, 128)
assert first.getpixel((2, 64))[0] > 200 # the red margin was squeezed in, not cut
last = fit_h3_keyframe(source, 128, 128, anchor = H3_ANCHOR_LAST)
assert last.size == (128, 128)
assert last.getpixel((2, 64))[2] > 200 # the red margin fell outside the centre crop
with pytest.raises(ValueError, match = "anchor"):
fit_h3_keyframe(source, 64, 64, anchor = "middle")
def _h3_native_backend(
monkeypatch,
calls,
binary = None,
):
"""H3 sd.cpp backend whose fake engine records params; binary is what the native load vets."""
from core.inference.video import _VideoLoadState
from core.inference.video_minimax_h3 import MiniMaxH3NativeRuntime
class _Engine:
def generate_video(self, files, params, **kwargs):
from PIL import Image
# The staged PNGs live in a scratch dir the run deletes, so measure them here.
def staged_size(path):
if path is None:
return None
with Image.open(path) as image:
return image.size
calls.append(
{
"files": files,
"params": params,
"init_size": staged_size(params.init_img),
"end_size": staged_size(params.end_img),
**kwargs,
}
)
return Path("/tmp/does-not-exist.webm")
backend = VideoBackend()
fam = _detect_load_family("unsloth/MiniMax-H3-GGUF", None, "minimax-h3")
from core.inference.video import _sd_cli_identity
engine = _Engine()
if binary is not None:
engine.binary = str(binary)
backend._state = _VideoLoadState(
pipe = MiniMaxH3NativeRuntime(
engine = engine,
files = object(),
offload_flags = (),
binary_identity = _sd_cli_identity(str(binary)) if binary is not None else None,
),
family = fam,
repo_id = "unsloth/MiniMax-H3-GGUF",
base_repo = fam.base_repo,
device = "cuda",
dtype = "Q4_K_M",
kind = "gguf",
engine = "sd_cpp",
h3_task = "fl2va",
gguf_filename = "minimax_h3_fl2va-Q4_K_M.gguf",
)
# Imported inside _generate_h3_native, so patched at their own module.
from core.inference import video_minimax_h3 as h3_mod
monkeypatch.setattr(h3_mod, "inspect_video", lambda path: (1344, 768, 124, True))
monkeypatch.setattr(h3_mod, "transcode_video_to_mp4", lambda path, fps: b"MP4")
return backend
def _data_url(width, height):
import base64
import io
Image = pytest.importorskip("PIL.Image")
buf = io.BytesIO()
Image.new("RGB", (width, height), (10, 20, 30)).save(buf, format = "PNG")
return "data:image/png;base64," + base64.b64encode(buf.getvalue()).decode()
def test_h3_native_generate_stages_both_keyframes_on_the_canvas(monkeypatch):
pytest.importorskip("PIL.Image")
calls: list = []
backend = _h3_native_backend(monkeypatch, calls)
result = backend.generate(
prompt = "a fox runs through snow",
width = 960,
height = 544,
first_frame = _data_url(1920, 1080),
last_frame = _data_url(400, 400),
)
assert calls[0]["params"].init_img and calls[0]["params"].end_img
assert calls[0]["init_size"] == (960, 544)
assert calls[0]["end_size"] == (960, 544)
assert result["conditioning"] == "fl2va"
def test_h3_native_generate_records_the_build_it_ran_on(monkeypatch):
"""Native results must carry build fields; omitted ones are saved as null in the gallery sidecar."""
pytest.importorskip("PIL.Image")
calls: list = []
backend = _h3_native_backend(monkeypatch, calls)
object.__setattr__(backend._state, "display_repo_id", "Org/pinned-h3")
result = backend.generate(prompt = "a fox runs through snow", width = 960, height = 544)
state = backend._state
assert result["repo_id"] == "Org/pinned-h3"
assert result["model_kind"] == state.kind == "gguf"
assert result["gguf_filename"] == state.gguf_filename
assert result["memory_mode"] == state.memory_mode
assert result["offload_policy"] == state.offload_policy
assert result["transformer_quant"] == state.transformer_quant
assert result["text_encoder_quant"] == state.text_encoder_quant
def test_h3_native_generate_names_each_keyframe_combination(monkeypatch):
calls: list = []
backend = _h3_native_backend(monkeypatch, calls)
image = _data_url(640, 360)
assert backend.generate(prompt = "p", width = 960, height = 544)["conditioning"] == "t2va"
assert calls[-1]["params"].init_img is None and calls[-1]["params"].end_img is None
assert (
backend.generate(prompt = "p", width = 960, height = 544, first_frame = image)["conditioning"]
== "i2va"
)
assert calls[-1]["params"].end_img is None
assert (
backend.generate(prompt = "p", width = 960, height = 544, last_frame = image)["conditioning"]
== "l2va"
)
assert calls[-1]["params"].init_img is None
def test_h3_omitted_size_takes_the_canvas_from_the_keyframe(monkeypatch):
pytest.importorskip("PIL.Image")
calls: list = []
backend = _h3_native_backend(monkeypatch, calls)
backend.generate(prompt = "p", first_frame = _data_url(1920, 1080))
assert (calls[-1]["params"].width, calls[-1]["params"].height) == (1344, 768)
# With no first frame the last one drives it, matching the Diffusers blocks.
backend.generate(prompt = "p", last_frame = _data_url(1080, 1920))
assert (calls[-1]["params"].width, calls[-1]["params"].height) == (768, 1344)
assert calls[-1]["end_size"] == (768, 1344)
backend.generate(prompt = "p")
assert (calls[-1]["params"].width, calls[-1]["params"].height) == (1344, 768)
def test_h3_native_clip_records_the_build_it_came_off(monkeypatch):
"""Native clips must return the diffusers build record, or their saved recipes come out blank."""
calls: list = []
backend = _h3_native_backend(monkeypatch, calls)
import dataclasses
backend._state = dataclasses.replace(
backend._state,
transformer_quant = "fp8",
text_encoder_quant = "int8",
memory_mode = "low",
offload_policy = "model",
)
result = backend.generate(prompt = "p", width = 960, height = 544)
assert result["model_kind"] == "gguf"
assert result["gguf_filename"] == "minimax_h3_fl2va-Q4_K_M.gguf"
assert result["transformer_quant"] == "fp8"
assert result["text_encoder_quant"] == "int8"
assert result["memory_mode"] == "low"
assert result["offload_policy"] == "model"
def test_a_cfg_free_family_records_the_guidance_it_actually_ran(monkeypatch):
"""A CFG-free family must record the guidance it ran, not the caller's requested value."""
calls: list = []
backend = _h3_native_backend(monkeypatch, calls)
result = backend.generate(prompt = "p", width = 960, height = 544, guidance = 7.0)
assert result["guidance"] == 1.0
assert calls[-1]["params"].cfg_scale == 1.0
def test_keyframes_are_refused_by_a_family_that_has_none(fake_runtime, tmp_path):
# Silently dropping the image would render a text-only clip with nothing to do with it.
backend = VideoBackend()
backend.load_pipeline(
"hunyuanvideo-community/HunyuanVideo-1.5-Diffusers-480p_t2v", model_kind = "pipeline"
)
with pytest.raises(ValueError, match = "no first or last frame"):
backend.begin_generate(prompt = "a sloth", first_frame = _data_url(64, 64))
with pytest.raises(ValueError, match = "no first or last frame"):
backend.generate(prompt = "a sloth", last_frame = _data_url(64, 64))
# The refusal must not leave the busy flag set, or every later generation 409s.
assert backend.generate_progress()["active"] is False
status = backend.status()
assert status["supports_first_frame"] is False and status["supports_last_frame"] is False
def test_a_first_frame_only_family_refuses_a_last_frame(fake_runtime, tmp_path):
backend = VideoBackend()
_load_gguf(backend, tmp_path)
with pytest.raises(ValueError, match = "first frame only"):
backend.begin_generate(prompt = "a sloth", last_frame = _data_url(64, 64))
with pytest.raises(ValueError, match = "first frame only"):
backend.generate(
prompt = "a sloth", first_frame = _data_url(64, 64), last_frame = _data_url(64, 64)
)
assert backend.generate_progress()["active"] is False
# ── image-to-video through a declared i2v pipeline (video_i2v) ───────────────────────────────────
class _FakeWanI2VPipe(_FakeWanPipeBase):
"""WanImageToVideoPipeline fake. Constructed only as the template the swap reads its own
instance state from; the render then runs this __call__ on the LOADED pipe object."""
calls: list = []
def __init__(
self,
transformer = None,
vae = None,
image_encoder = None,
image_processor = None,
):
self.transformer = transformer
self.vae = vae
self.image_encoder = image_encoder
self.image_processor = image_processor
self.video_processor = "i2v-video-processor"
def __call__(
self,
*,
image = None,
prompt = None,
negative_prompt = None,
num_inference_steps = None,
guidance_scale = None,
width = None,
height = None,
num_frames = None,
generator = None,
callback_on_step_end = None,
explode = False,
**kwargs,
):
self.last_kwargs = {
"image": image,
"width": width,
"height": height,
"num_frames": num_frames,
"guidance_scale": guidance_scale,
**kwargs,
}
_FakeWanI2VPipe.calls.append(
{
"self": self,
"class": type(self).__name__,
"video_processor": getattr(self, "video_processor", None),
"image_size": getattr(image, "size", None),
}
)
if explode:
raise RuntimeError("i2v render failed")
return self._finish(num_inference_steps, num_frames, callback_on_step_end)
class _FakeLTX2I2VPipe(_FakePipe):
def __init__(self, vae = None):
self.vae = vae
self.video_processor = "bilinear"
def __call__(
self,
*,
image = None,
image_crf = None,
prompt = None,
num_frames = None,
frame_rate = None,
callback_on_step_end = None,
**kwargs,
):
self.last_kwargs = {"image": image, "image_crf": image_crf, "class": type(self).__name__}
frames = [[object() for _ in range(int(num_frames or 1))]]
return types.SimpleNamespace(frames = frames, audio = None)
@pytest.fixture
def fake_i2v(fake_runtime):
diffusers = sys.modules["diffusers"]
diffusers.WanImageToVideoPipeline = _FakeWanI2VPipe
diffusers.LTX2ImageToVideoPipeline = _FakeLTX2I2VPipe
_FakeWanI2VPipe.calls = []
yield
def test_wan_first_frame_runs_the_i2v_pipeline_over_the_loaded_one(fake_i2v):
backend = VideoBackend()
status = backend.load_pipeline("Wan-AI/Wan2.2-TI2V-5B-Diffusers", model_kind = "pipeline")
assert status["supports_first_frame"] is True
assert status["supports_last_frame"] is False
assert status["supports_keyframes"] is False # the H3 contract older frontends read
pipe = backend._state.pipe
t2v_cls = type(pipe)
keys_before = set(pipe.__dict__)
result = backend.generate(prompt = "a car", steps = 2, first_frame = _data_url(1920, 1080))
call = _FakeWanI2VPipe.calls[-1]
# The loaded object ran the i2v __call__ with the i2v instance state, then got its own class back.
assert call["self"] is pipe and call["class"] == "_FakeWanI2VPipe"
assert call["video_processor"] == "i2v-video-processor"
assert type(pipe) is t2v_cls
assert "image_encoder" not in pipe.__dict__ and "video_processor" not in pipe.__dict__
assert set(pipe.__dict__) - keys_before <= {"last_kwargs"}
assert (result["width"], result["height"]) == (1280, 704)
assert call["image_size"] == (1280, 704)
assert result["conditioning"] == "i2va"
_FakeWanI2VPipe.calls.clear()
backend.generate(prompt = "a car", steps = 2)
assert _FakeWanI2VPipe.calls == []
assert "image" not in pipe.last_kwargs
def test_wan_portrait_first_frame_takes_the_portrait_preset(fake_i2v):
backend = VideoBackend()
backend.load_pipeline("Wan-AI/Wan2.2-TI2V-5B-Diffusers", model_kind = "pipeline")
result = backend.generate(prompt = "p", steps = 2, first_frame = _data_url(832, 1104))
assert (result["width"], result["height"]) == (704, 1280)
result = backend.generate(
prompt = "p", steps = 2, width = 1280, height = 704, first_frame = _data_url(832, 1104)
)
assert (result["width"], result["height"]) == (1280, 704)
assert _FakeWanI2VPipe.calls[-1]["image_size"] == (1280, 704)
def test_the_swap_is_undone_when_the_i2v_render_fails(fake_i2v, monkeypatch):
backend = VideoBackend()
backend.load_pipeline("Wan-AI/Wan2.2-TI2V-5B-Diffusers", model_kind = "pipeline")
pipe = backend._state.pipe
t2v_cls = type(pipe)
from core.inference import video as video_mod
monkeypatch.setattr(video_mod, "video_i2v_call_kwargs", lambda fam, *ids: {"explode": True})
with pytest.raises(RuntimeError, match = "i2v render failed"):
backend.generate(prompt = "p", steps = 2, first_frame = _data_url(64, 64))
assert type(pipe) is t2v_cls
assert "image_encoder" not in pipe.__dict__
assert backend.generate_progress()["active"] is False
def test_ltx23_first_frame_carries_comfyui_image_crf(fake_i2v, tmp_path):
backend = VideoBackend()
(tmp_path / "ltx-2.3-22b-distilled-Q4_K_M.gguf").write_bytes(b"weights")
backend.load_pipeline(
str(tmp_path),
gguf_filename = "ltx-2.3-22b-distilled-Q4_K_M.gguf",
base_repo = "Lightricks/LTX-2",
family_override = "ltx-2",
)
pipe = backend._state.pipe
backend.generate(prompt = "p", steps = 2, first_frame = _data_url(1920, 1080))
assert pipe.last_kwargs["class"] == "_FakeLTX2I2VPipe"
assert pipe.last_kwargs["image_crf"] == 18
assert pipe.last_kwargs["image"].size == (1216, 704)
assert type(pipe) is _FakePipe
def test_ltx2_first_frame_keeps_the_pipeline_crf_default(fake_i2v, tmp_path):
backend = VideoBackend()
_load_gguf(backend, tmp_path)
pipe = backend._state.pipe
backend.generate(prompt = "p", steps = 2, first_frame = _data_url(512, 768))
assert pipe.last_kwargs["class"] == "_FakeLTX2I2VPipe"
assert pipe.last_kwargs["image_crf"] is None
assert pipe.last_kwargs["image"].size == (512, 768)
backend.generate(prompt = "p", steps = 2)
assert "image" not in pipe.last_kwargs and "class" not in pipe.last_kwargs
def test_begin_generate_rejects_an_undecodable_keyframe(monkeypatch):
# begin_generate returns before the job runs, so a bad image has to fail on the POST.
backend = _h3_native_backend(monkeypatch, [])
with pytest.raises(ValueError):
backend.begin_generate(prompt = "p", first_frame = "data:image/png;base64,notanimage")
assert backend.generate_progress()["active"] is False
def test_h3_modular_load_restricts_the_components_not_the_blocks(monkeypatch, tmp_path):
# Restrict components without pruning t2va/fl2va routing blocks.
import types
from core.inference.video import VideoBackend
seen: dict = {}
class _FakeModularPipeline:
@classmethod
def from_pretrained(cls, repo, **kwargs):
seen["from_pretrained"] = {"repo": repo, **kwargs}
return cls()
def load_components(self, **kwargs):
seen["load_components"] = kwargs
def to(self, device):
return self
diffusers = types.SimpleNamespace(
ComponentsManager = lambda: types.SimpleNamespace(
enable_auto_cpu_offload = lambda **kwargs: seen.setdefault("offload", kwargs)
),
ModularPipeline = _FakeModularPipeline,
)
torch = types.SimpleNamespace(bfloat16 = "bf16")
fam = _detect_load_family("MiniMaxAI/MiniMax-H3", None, "minimax-h3")
backend = VideoBackend()
status = backend._load_h3_modular_pipeline(
# An unset request resolves to int8 now, which takes the hosted-checkpoint path.
transformer_quant = "none",
diffusers = diffusers,
torch = torch,
fam = fam,
repo_id = "MiniMaxAI/MiniMax-H3",
display_repo_id = "MiniMaxAI/MiniMax-H3",
base = fam.base_repo,
kind = "pipeline",
dtype = torch.bfloat16,
device = "cuda",
hf_token = None,
memory_mode = None,
_load_token = None,
_base_local_dir = None,
)
assert "workflow" not in seen["from_pretrained"]
assert seen["load_components"]["workflow"] == "fl2va"
assert status["supports_keyframes"] is True
assert status["display_repo_id"] == "MiniMaxAI/MiniMax-H3"
assert status["defaults"]["canvas_short_edge"] == 768
def test_h3_modular_load_pins_a_hosted_prequant_denoiser_out_of_the_offload_rotation(monkeypatch):
"""Pin a pre-quantized denoiser at load; torchao modules break on the offload mid-block move."""
import types
from core.inference.video import VideoBackend
calls: dict = {}
class _FakeModularPipeline:
@classmethod
def from_pretrained(cls, repo, **kwargs):
return cls()
def load_components(self, **kwargs):
pass
def update_components(self, **kwargs):
self.transformer = kwargs.get("transformer")
def to(self, device):
return self
manager = types.SimpleNamespace(enable_auto_cpu_offload = lambda **kwargs: None)
diffusers = types.SimpleNamespace(
ComponentsManager = lambda: manager,
ModularPipeline = _FakeModularPipeline,
MiniMaxH3Transformer3DModel = object,
)
torch = types.SimpleNamespace(bfloat16 = "bf16")
fam = _detect_load_family("MiniMaxAI/MiniMax-H3", None, "minimax-h3")
seeded = object()
import core.inference.diffusion_prequant as prequant_module
monkeypatch.setattr(
prequant_module,
"load_prequantized_transformer",
lambda *args, **kwargs: seeded,
)
monkeypatch.setattr(
prequant_module,
"pin_prequantized_module",
lambda mgr, module, device, **kwargs: (
calls.setdefault("pinned", {"manager": mgr, "module": module, "device": device})
is not None
),
)
def load(scheme):
calls.clear()
return VideoBackend()._load_h3_modular_pipeline(
diffusers = diffusers,
torch = torch,
fam = fam,
repo_id = "MiniMaxAI/MiniMax-H3",
base = fam.base_repo,
kind = "pipeline",
dtype = torch.bfloat16,
device = "cuda",
hf_token = None,
memory_mode = None,
transformer_quant = scheme,
_load_token = None,
_base_local_dir = None,
)
status = load("fp8")
assert status["transformer_quant"] == "fp8"
assert calls["pinned"]["module"] is seeded
assert calls["pinned"]["manager"] is manager
assert calls["pinned"]["device"] == "cuda"
# Asked for EXPLICITLY: an unset request resolves to int8 now.
status = load("none")
assert status["transformer_quant"] is None
assert "pinned" not in calls
def test_h3_modular_load_seeds_the_partition_its_workflow_denoises_against(monkeypatch):
"""Seed the partition the workflow denoises: ref2va reads transformer_ref, fl2va reads transformer."""
import types
from core.inference.video import VideoBackend
calls: dict = {}
class _FakeModularPipeline:
@classmethod
def from_pretrained(cls, repo, **kwargs):
return cls()
def load_components(self, **kwargs):
calls["workflow"] = kwargs.get("workflow")
def update_components(self, **kwargs):
calls.setdefault("seeded", {}).update(kwargs)
for name, value in kwargs.items():
setattr(self, name, value)
def to(self, device):
return self
manager = types.SimpleNamespace(enable_auto_cpu_offload = lambda **kwargs: None)
diffusers = types.SimpleNamespace(
ComponentsManager = lambda: manager,
ModularPipeline = _FakeModularPipeline,
MiniMaxH3Transformer3DModel = object,
)
torch = types.SimpleNamespace(bfloat16 = "bf16")
fam = _detect_load_family("MiniMaxAI/MiniMax-H3", None, "minimax-h3")
seeded = object()
import core.inference.diffusion_prequant as prequant_module
monkeypatch.setattr(
prequant_module,
"load_prequantized_transformer",
lambda *args, **kwargs: calls.setdefault("loader_kwargs", kwargs) and seeded or seeded,
)
monkeypatch.setattr(
prequant_module,
"pin_prequantized_module",
lambda mgr, module, device, **kwargs: calls.setdefault("pinned", module) is not None,
)
def load(task):
calls.clear()
return VideoBackend()._load_h3_modular_pipeline(
diffusers = diffusers,
torch = torch,
fam = fam,
repo_id = "MiniMaxAI/MiniMax-H3",
base = fam.base_repo,
kind = "pipeline",
dtype = torch.bfloat16,
device = "cuda",
hf_token = None,
memory_mode = None,
transformer_quant = "int8",
h3_task = task,
_load_token = None,
_base_local_dir = None,
)
status = load("ref2va")
assert status["transformer_quant"] == "int8"
assert calls["workflow"] == "ref2va"
assert calls["seeded"] == {"transformer_ref": seeded}
assert calls["pinned"] is seeded
# The config comes from the same partition: the scoped download stages only that one.
assert calls["loader_kwargs"]["config_subfolder"] == "transformer_ref"
status = load("fl2va")
assert status["transformer_quant"] == "int8"
assert calls["seeded"] == {"transformer": seeded}
assert calls["loader_kwargs"]["config_subfolder"] == "transformer"
def test_denoiser_prequant_coverage_is_asked_per_partition():
# A scheme whose only artifact belongs to the other partition covers nothing here.
from core.inference.video_families import VideoFamily
fam = VideoFamily(
name = "partitioned",
pipeline_class = "P",
transformer_class = "T",
base_repo = "org/partitioned",
modular_workflow = "fl2va",
prequant_repos = (("int8", "unsloth/Test-FP8"), ("fp8", "unsloth/Test-FP8")),
prequant_filenames = (("fp8", "ref2va", "Test-Ref2VA-FP8.pt"),),
prequant_partition_tasks = ("ref2va",),
)
assert VideoBackend._denoiser_prequant_covered(fam, "int8", None, "fl2va") is True
assert VideoBackend._denoiser_prequant_covered(fam, "int8", None, "ref2va") is False
assert VideoBackend._denoiser_prequant_covered(fam, "fp8", None, "ref2va") is True
assert VideoBackend._denoiser_prequant_covered(fam, "int8", None) is True
def test_h3_native_progress_reads_only_the_denoise_bar(monkeypatch):
# Replay real log shapes to isolate the denoise progress bar.
calls: list = []
backend = _h3_native_backend(monkeypatch, calls)
transcript = [
"[INFO ] stable-diffusion.cpp:4365 - sampling using Euler method",
"[INFO ] stable-diffusion.cpp:6107 - MiniMax-H3 I2VA",
# keyframe VAE encode: same shape, its own loop
" |==============> | 3/6 - 9.17it/s",
"[INFO ] stable-diffusion.cpp:6899 - generate_video 640x384x124",
# the denoiser's own weights streaming in, rated in GB/s
" |======================| 532/532 - 3.81GB/s",
" |=====> | 1/4 - 1.63it/s",
" |==========> | 2/4 - 1.70it/s",
"[INFO ] stable-diffusion.cpp:6997 - sampling completed, taking 13.20s",
# VAE decode tiles, after the denoise window closed
" |======================| 6/6 - 9.17it/s",
]
class _ReplayEngine:
def generate_video(self, files, params, *, on_log, **kwargs):
seen = []
for line in transcript:
on_log(line)
seen.append((backend._gen["step"], backend._gen["total"], backend._gen["phase"]))
calls.append(seen)
return Path("/tmp/does-not-exist.webm")
from core.inference.video_minimax_h3 import MiniMaxH3NativeRuntime
object.__setattr__(
backend._state,
"pipe",
MiniMaxH3NativeRuntime(engine = _ReplayEngine(), files = object(), offload_flags = ()),
)
backend.generate(prompt = "p", width = 640, height = 384, steps = 4)
seen = calls[-1]
assert seen[2] == (0, 4, "denoise")
assert seen[4] == (0, 4, "denoise")
assert seen[5] == (1, 4, "denoise")
assert seen[6] == (2, 4, "denoise")
assert seen[7] == (2, 4, "decode")
assert seen[8] == (2, 4, "decode")
def test_h3_native_progress_survives_the_real_in_place_redraws(monkeypatch):
"""Reader and bar pattern must be fixed together; the test feeds the real sd-cli redraw bytes."""
from core.inference.sd_cpp_engine import iter_sd_cpp_records
redraw = "\r |=====> | {}/{} - 1.63it/s\x1b[K"
# One flush per element, as the child writes them; one big chunk would hide the lateness.
flushes = [
"[INFO ] stable-diffusion.cpp:6899 - generate_video 640x384x124\n",
redraw.format(1, 4),
redraw.format(2, 4),
redraw.format(3, 4),
redraw.format(4, 4) + "\n",
"[INFO ] stable-diffusion.cpp:6997 - sampling completed, taking 13.20s\n",
]
class _Raw:
def __init__(self, owner) -> None:
self._owner = owner
def read1(self, _n: int) -> bytes:
if not self._owner.pending:
return b""
self._owner.reads += 1
return self._owner.pending.pop(0).encode()
class _PipeStream:
def __init__(self, payload: list[str]) -> None:
self.pending = list(payload)
self.reads = 0
self.buffer = _Raw(self)
def __iter__(self):
raise AssertionError("a redraw carries no newline, so line iteration would block")
calls: list = []
backend = _h3_native_backend(monkeypatch, calls)
class _ReplayEngine:
def generate_video(self, files, params, *, on_log, **kwargs):
seen = []
stream = _PipeStream(flushes)
for record in iter_sd_cpp_records(stream):
on_log(record)
seen.append((stream.reads, backend._gen["step"], backend._gen["phase"]))
calls.append(seen)
return Path("/tmp/does-not-exist.webm")
from core.inference.video_minimax_h3 import MiniMaxH3NativeRuntime
object.__setattr__(
backend._state,
"pipe",
MiniMaxH3NativeRuntime(engine = _ReplayEngine(), files = object(), offload_flags = ()),
)
backend.generate(prompt = "p", width = 640, height = 384, steps = 4)
seen = calls[-1]
# Each step is observed while sampling, in order; a redraw yields two records.
progression: list[int] = []
for _reads, step, phase in seen:
if phase == "denoise" and (not progression or progression[-1] != step):
progression.append(step)
assert progression == [0, 1, 2, 3, 4]
# Step N must be visible after the flush that carried it (read N + 1, the opening log line
# being read 1), not one redraw later. Being "eventually right" is the bug, not the fix.
first_read_for = {}
for reads, step, phase in seen:
if phase == "denoise" and step:
first_read_for.setdefault(step, reads)
assert first_read_for == {1: 2, 2: 3, 3: 4, 4: 5}
assert seen[-1][2] == "decode"
def _h3_ref_backend(monkeypatch, calls):
"""The native backend with the Ref2VA partition resident instead of FL2VA."""
backend = _h3_native_backend(monkeypatch, calls)
object.__setattr__(backend._state, "h3_task", "ref2va")
object.__setattr__(backend._state, "gguf_filename", "minimax_h3_ref2va_pruned-Q4_K_M.gguf")
return backend
def _reference_video_data_url(
seconds = 3.0,
fps = 24,
size = (160, 96),
with_audio = True,
audio_seconds = None,
audio_start_seconds = 0.0,
):
"""A real encoded MP4, so the decode path is exercised rather than stubbed."""
import base64
import io
av = pytest.importorskip("av")
np = pytest.importorskip("numpy")
buf = io.BytesIO()
with av.open(buf, mode = "w", format = "mp4") as out:
video = out.add_stream("libx264", rate = fps)
video.width, video.height = size
video.pix_fmt = "yuv420p"
audio = None
if with_audio:
audio = out.add_stream("aac", rate = 44_100)
audio.layout = "stereo"
for index in range(int(seconds * fps)):
frame = av.VideoFrame.from_ndarray(
np.full((size[1], size[0], 3), index % 255, dtype = np.uint8), format = "rgb24"
)
for packet in video.encode(frame):
out.mux(packet)
if audio is not None:
written = 0
total = int((seconds if audio_seconds is None else audio_seconds) * 44_100)
pts = int(round(audio_start_seconds * 44_100))
while written < total:
count = min(1024, total - written)
samples = np.zeros((1, count * 2), dtype = np.int16)
frame = av.AudioFrame.from_ndarray(samples, format = "s16", layout = "stereo")
frame.sample_rate = 44_100
# Placing the track later on the shared timeline, as an offset soundtrack does.
frame.pts = pts
for packet in audio.encode(frame):
out.mux(packet)
written += count
pts += count
for packet in audio.encode():
out.mux(packet)
for packet in video.encode():
out.mux(packet)
return "data:video/mp4;base64," + base64.b64encode(buf.getvalue()).decode()
def _vfr_reference_video_data_url():
"""A four-second VFR clip whose media timeline begins at five seconds."""
import base64
import io
from fractions import Fraction
av = pytest.importorskip("av")
np = pytest.importorskip("numpy")
timestamps = []
elapsed = 0.0
while elapsed < 4.0 - 1e-6:
timestamps.append(elapsed)
elapsed += 0.1 if elapsed < 2.0 - 1e-6 else 1 / 30
buf = io.BytesIO()
with av.open(buf, mode = "w", format = "mp4") as out:
video = out.add_stream("libx264", rate = 30)
video.width, video.height = (160, 96)
video.pix_fmt = "yuv420p"
video.time_base = Fraction(1, 1000)
video.codec_context.gop_size = 12
for elapsed in timestamps:
value = min(250, int(round(elapsed * 50)))
frame = av.VideoFrame.from_ndarray(
np.full((96, 160, 3), value, dtype = np.uint8), format = "rgb24"
)
frame.pts = 5_000 + int(round(elapsed * 1_000))
frame.time_base = Fraction(1, 1000)
for packet in video.encode(frame):
out.mux(packet)
for packet in video.encode():
out.mux(packet)
return "data:video/mp4;base64," + base64.b64encode(buf.getvalue()).decode()
def _offset_audio_reference_video_data_url():
"""A four-second video at t=5 whose three-second soundtrack begins at t=6."""
import base64
import io
from fractions import Fraction
av = pytest.importorskip("av")
np = pytest.importorskip("numpy")
buf = io.BytesIO()
with av.open(buf, mode = "w", format = "matroska") as out:
video = out.add_stream("ffv1", rate = 24)
video.width, video.height = (64, 64)
video.pix_fmt = "yuv444p"
video.time_base = Fraction(1, 1000)
audio = out.add_stream("pcm_s16le", rate = 44_100)
audio.layout = "stereo"
audio.time_base = Fraction(1, 44_100)
for index in range(4 * 24):
frame = av.VideoFrame.from_ndarray(
np.zeros((64, 64, 3), dtype = np.uint8), format = "rgb24"
)
frame.pts = 5_000 + round(index * 1_000 / 24)
frame.time_base = Fraction(1, 1000)
for packet in video.encode(frame):
out.mux(packet)
written = 0
while written < 3 * 44_100:
count = min(1024, 3 * 44_100 - written)
samples = np.full((1, count * 2), 10_000, dtype = np.int16)
frame = av.AudioFrame.from_ndarray(samples, format = "s16", layout = "stereo")
frame.sample_rate = 44_100
frame.pts = 6 * 44_100 + written
frame.time_base = Fraction(1, 44_100)
for packet in audio.encode(frame):
out.mux(packet)
written += count
for packet in audio.encode():
out.mux(packet)
for packet in video.encode():
out.mux(packet)
return "data:video/x-matroska;base64," + base64.b64encode(buf.getvalue()).decode()
def test_h3_reference_video_decodes_onto_the_models_own_clock():
pytest.importorskip("av")
from core.inference.video_minimax_h3 import decode_h3_reference_video
import base64
blob = base64.b64decode(_reference_video_data_url(seconds = 3.0, fps = 30).split(",", 1)[1])
frames, waveform, sample_rate = decode_h3_reference_video(blob)
# 3 seconds at 24 fps whatever the container's own rate was.
assert len(frames) == 72
assert waveform is not None and sample_rate == 44_100
# And onto the canvas its own aspect ratio resolves to, never upscaled past the source.
assert frames[0].size == (160, 96)
def test_h3_reference_video_refuses_a_clip_below_the_trained_window():
base64, decode_h3_reference_video = _shared_setup_2()
blob = base64.b64decode(_reference_video_data_url(seconds = 0.5).split(",", 1)[1])
with pytest.raises(ValueError, match = "2 to 15 seconds"):
decode_h3_reference_video(blob)
def test_h3_reference_video_refuses_instead_of_silently_truncating_a_long_clip():
base64, decode_h3_reference_video = _shared_setup_2()
blob = base64.b64decode(
_reference_video_data_url(seconds = 15.1, fps = 24, with_audio = True).split(",", 1)[1]
)
with pytest.raises(ValueError, match = "longer than 15s"):
decode_h3_reference_video(blob)
def test_h3_reference_video_decodes_an_explicit_trim_with_matching_audio():
base64, decode_h3_reference_video = _shared_setup_2()
blob = base64.b64decode(_reference_video_data_url(seconds = 20.0, fps = 24).split(",", 1)[1])
frames, waveform, sample_rate = decode_h3_reference_video(
blob,
trim_start_seconds = 5.0,
trim_end_seconds = 15.0,
)
assert len(frames) == 240
assert sample_rate == 44_100
assert waveform is not None and waveform.shape[0] == 10 * sample_rate
def test_h3_reference_video_trim_uses_vfr_pts_relative_to_a_nonzero_stream_start():
pytest.importorskip("av")
import base64
import numpy as np
from core.inference.video_minimax_h3 import decode_h3_reference_video
blob = base64.b64decode(_vfr_reference_video_data_url().split(",", 1)[1])
frames, waveform, sample_rate = decode_h3_reference_video(
blob,
trim_start_seconds = 0.5,
trim_end_seconds = 2.5,
)
assert len(frames) == 48
assert waveform is None and sample_rate is None
# Ordinal selection would start near value 50 instead of 25.
assert float(np.asarray(frames[0]).mean()) == pytest.approx(25, abs = 8)
assert float(np.asarray(frames[-1]).mean()) > 110
def test_h3_reference_video_trim_preserves_an_embedded_audio_timeline_offset():
pytest.importorskip("av")
import base64
import numpy as np
from core.inference.video_minimax_h3 import decode_h3_reference_video
blob = base64.b64decode(_offset_audio_reference_video_data_url().split(",", 1)[1])
frames, waveform, sample_rate = decode_h3_reference_video(
blob,
trim_start_seconds = 0.5,
trim_end_seconds = 2.5,
)
assert len(frames) == 48
assert sample_rate == 44_100
assert waveform is not None and waveform.shape == (2 * sample_rate, 2)
assert np.max(np.abs(waveform[: sample_rate // 2])) == 0
assert np.mean(np.abs(waveform[sample_rate // 2 :])) > 0.25
@pytest.mark.parametrize("duration", [2.0, 15.0])
def test_h3_reference_video_trim_keeps_exact_boundary_frame_and_sample_counts(duration):
base64, decode_h3_reference_video = _shared_setup_2()
blob = base64.b64decode(_reference_video_data_url(seconds = duration, fps = 24).split(",", 1)[1])
frames, waveform, sample_rate = decode_h3_reference_video(
blob,
trim_start_seconds = 0.0,
trim_end_seconds = duration,
)
assert len(frames) == round(duration * 24)
assert sample_rate == 44_100
assert waveform is not None and waveform.shape[0] == round(duration * sample_rate)
@pytest.mark.parametrize("duration", [2.0, 15.0])
def test_h3_reference_video_without_trim_discards_aac_padding(duration):
base64, decode_h3_reference_video = _shared_setup_2()
blob = base64.b64decode(_reference_video_data_url(seconds = duration, fps = 24).split(",", 1)[1])
frames, waveform, sample_rate = decode_h3_reference_video(blob)
assert len(frames) == round(duration * 24)
assert sample_rate == 44_100
assert waveform is not None and waveform.shape[0] == round(duration * sample_rate)
@pytest.mark.parametrize("audio_seconds", [15.05, 15.1, 16.0])
def test_h3_reference_video_without_trim_clamps_audio_past_the_video(audio_seconds):
"""A soundtrack longer than its video is clamped, since codec overshoot is normal padding."""
base64, decode_h3_reference_video = _shared_setup_2()
blob = base64.b64decode(
_reference_video_data_url(seconds = 15.0, fps = 24, audio_seconds = audio_seconds).split(",", 1)[
1
]
)
frames, waveform, sample_rate = decode_h3_reference_video(blob)
assert len(frames) == round(15.0 * 24)
assert waveform is not None
assert waveform.shape[0] == round(15.0 * sample_rate)
def test_h3_reference_video_trim_seeks_and_stops_both_decoders(monkeypatch):
av = pytest.importorskip("av")
import base64
from core.inference.video_minimax_h3 import decode_h3_reference_video
blob = base64.b64decode(_reference_video_data_url(seconds = 20.0, fps = 24).split(",", 1)[1])
real_open = av.open
opened = []
class _CountingContainer:
def __init__(self, *args, **kwargs):
self.inner = real_open(*args, **kwargs)
self.seek_types = []
self.decoded = {"video": 0, "audio": 0}
opened.append(self)
@property
def streams(self):
return self.inner.streams
def seek(self, *args, **kwargs):
self.seek_types.append(kwargs["stream"].type)
return self.inner.seek(*args, **kwargs)
def decode(self, *args, **kwargs):
media_type = "video" if "video" in kwargs else "audio"
for frame in self.inner.decode(*args, **kwargs):
self.decoded[media_type] += 1
yield frame
def __enter__(self):
self.inner.__enter__()
return self
def __exit__(self, *args):
return self.inner.__exit__(*args)
monkeypatch.setattr(av, "open", _CountingContainer)
frames, waveform, sample_rate = decode_h3_reference_video(
blob,
trim_start_seconds = 15.0,
trim_end_seconds = 17.0,
)
assert len(frames) == 48
assert waveform is not None and waveform.shape[0] == 2 * sample_rate
assert any("video" in item.seek_types for item in opened)
assert any("audio" in item.seek_types for item in opened)
assert sum(item.decoded["video"] for item in opened) < 200
assert sum(item.decoded["audio"] for item in opened) < 120
def test_h3_reference_video_trim_outlasting_a_short_soundtrack_stays_silent():
"""A trim outlasting a short soundtrack keeps the video and pads silence, not refuses."""
base64, decode_h3_reference_video = _shared_setup_2()
blob = base64.b64decode(
_reference_video_data_url(seconds = 10.0, fps = 24, audio_seconds = 6.0).split(",", 1)[1]
)
frames, waveform, sample_rate = decode_h3_reference_video(
blob, trim_start_seconds = 2.0, trim_end_seconds = 8.0
)
assert len(frames) == round(6.0 * 24)
assert waveform is not None
assert waveform.shape[0] == round(6.0 * sample_rate)
# Audio runs out 4s into the interval; everything past that is silence, not a refusal.
assert abs(waveform[: round(4.0 * sample_rate)]).max() >= 0.0
assert abs(waveform[round(4.0 * sample_rate) + sample_rate // 10 :]).max() == 0.0
def test_h3_reference_video_trim_entirely_past_the_soundtrack_drops_the_audio():
base64, decode_h3_reference_video = _shared_setup_2()
blob = base64.b64decode(
_reference_video_data_url(seconds = 12.0, fps = 24, audio_seconds = 3.0).split(",", 1)[1]
)
frames, waveform, _ = decode_h3_reference_video(
blob, trim_start_seconds = 6.0, trim_end_seconds = 10.0
)
assert len(frames) == round(4.0 * 24)
assert waveform is None
def test_h3_reference_video_trim_before_an_offset_soundtrack_drops_the_audio():
"""A track starting after the trim interval is dropped, not made silent, which would fake a track."""
base64, decode_h3_reference_video = _shared_setup_2()
blob = base64.b64decode(
_reference_video_data_url(
seconds = 15.0, fps = 24, audio_seconds = 5.0, audio_start_seconds = 10.0
).split(",", 1)[1]
)
frames, waveform, _ = decode_h3_reference_video(
blob, trim_start_seconds = 0.0, trim_end_seconds = 5.0
)
assert len(frames) == round(5.0 * 24)
assert waveform is None
def test_h3_reference_video_trim_reaching_an_offset_soundtrack_keeps_the_audio():
"""The same offset track is still decoded by a trim that does overlap it."""
base64, decode_h3_reference_video = _shared_setup_2()
blob = base64.b64decode(
_reference_video_data_url(
seconds = 15.0, fps = 24, audio_seconds = 5.0, audio_start_seconds = 10.0
).split(",", 1)[1]
)
frames, waveform, sample_rate = decode_h3_reference_video(
blob, trim_start_seconds = 9.0, trim_end_seconds = 13.0
)
assert len(frames) == round(4.0 * 24)
assert waveform is not None
assert waveform.shape[0] == round(4.0 * sample_rate)
def test_h3_reference_video_trim_tolerates_a_container_longer_than_its_video():
"""Container duration can overrun the video; the last frame is held, not refused."""
base64, decode_h3_reference_video = _shared_setup_2()
blob = base64.b64decode(
_reference_video_data_url(seconds = 14.9, fps = 24, audio_seconds = 15.2).split(",", 1)[1]
)
frames, _, _ = decode_h3_reference_video(blob, trim_start_seconds = 0.0, trim_end_seconds = 15.0)
assert len(frames) == round(15.0 * 24)
def test_h3_reference_video_trim_still_refuses_a_real_overshoot():
"""The slack covers container metadata, not a range that genuinely is not there."""
base64, decode_h3_reference_video = _shared_setup_2()
blob = base64.b64decode(
_reference_video_data_url(seconds = 6.0, fps = 24, with_audio = False).split(",", 1)[1]
)
with pytest.raises(ValueError, match = "after the source video"):
decode_h3_reference_video(blob, trim_start_seconds = 2.0, trim_end_seconds = 10.0)
def test_h3_reference_video_trim_must_be_complete_bounded_and_inside_the_source():
base64, decode_h3_reference_video = _shared_setup_2()
blob = base64.b64decode(
_reference_video_data_url(seconds = 3.0, with_audio = False).split(",", 1)[1]
)
with pytest.raises(ValueError, match = "provided together"):
decode_h3_reference_video(blob, trim_start_seconds = 0.0)
with pytest.raises(ValueError, match = "2 to 15 seconds"):
decode_h3_reference_video(blob, trim_start_seconds = 0.0, trim_end_seconds = 1.0)
with pytest.raises(ValueError, match = "after the source video"):
decode_h3_reference_video(blob, trim_start_seconds = 2.0, trim_end_seconds = 5.0)
def _frame_index_video(
seconds = 10.0,
fps = 24,
width = 256,
height = 64,
bar = 4,
):
"""Frame index is a bar position, since grey levels collide under limited-range YUV."""
av = pytest.importorskip("av")
np = pytest.importorskip("numpy")
import io
buf = io.BytesIO()
with av.open(buf, mode = "w", format = "mp4") as out:
video = out.add_stream("libx264", rate = fps)
video.width, video.height = width, height
video.pix_fmt = "yuv420p"
# Every frame a keyframe, so the two decoders differ only in selection.
video.options = {"g": "1", "crf": "0", "tune": "zerolatency"}
for index in range(int(seconds * fps)):
plane = np.zeros((height, width, 3), dtype = np.uint8)
plane[:, index : index + bar] = 255
for packet in video.encode(av.VideoFrame.from_ndarray(plane, format = "rgb24")):
out.mux(packet)
for packet in video.encode():
out.mux(packet)
return buf.getvalue()
def _decoded_frame_index(image, width = 256):
"""Recover the source frame index from the bar's left edge."""
np = pytest.importorskip("numpy")
plane = np.asarray(image.convert("L"), dtype = "float64")
columns = plane.mean(axis = 0)
lit = np.flatnonzero(columns > columns.max() / 2)
assert lit.size, "no bar found in the decoded frame"
return int(round(lit[0] * width / plane.shape[1]))
def test_h3_reference_video_ordinal_fallback_selects_the_same_frames_as_timestamps():
"""Ordinal fallback picks floor(t*fps) frames; ceiling would drift a fractional start by one."""
av = pytest.importorskip("av")
from core.inference.video_minimax_h3 import (
_decode_h3_video_trim_by_ordinal,
_decode_h3_video_trim_by_timestamp,
)
blob = _frame_index_video()
for start, end in ((2.0, 8.0), (2.02, 8.02)):
ordinal, _ = _decode_h3_video_trim_by_ordinal(blob, av, (start, end))
timestamp, _ = _decode_h3_video_trim_by_timestamp(blob, av, (start, end))
assert len(ordinal) == len(timestamp) == round((end - start) * 24)
assert _decoded_frame_index(ordinal[0]) == _decoded_frame_index(timestamp[0])
ordinal, _ = _decode_h3_video_trim_by_ordinal(blob, av, (2.02, 8.02))
assert _decoded_frame_index(ordinal[0]) == 48
def test_h3_reference_video_falls_back_when_timestamps_are_missing(monkeypatch):
"""Prove the dispatcher reaches the ordinal decoder at all, rather than raising."""
av = pytest.importorskip("av")
import core.inference.video_minimax_h3 as h3
blob = _frame_index_video()
calls = []
original = h3._decode_h3_video_trim_by_ordinal
monkeypatch.setattr(
h3,
"_decode_h3_video_trim_by_ordinal",
lambda *args: (calls.append(1), original(*args))[1],
)
real_open = av.open
class _PtsLess:
"""PyAV container attributes are read-only, so the generator is replaced from outside."""
def __init__(self, container):
self._container = container
def decode(self, *args, **kwargs):
for frame in self._container.decode(*args, **kwargs):
frame.pts = None
yield frame
def __getattr__(self, name):
return getattr(self._container, name)
def __enter__(self):
self._container.__enter__()
return self
def __exit__(self, *exc):
return self._container.__exit__(*exc)
monkeypatch.setattr(av, "open", lambda *a, **k: _PtsLess(real_open(*a, **k)))
frames, _, _ = h3.decode_h3_reference_video(
blob, trim_start_seconds = 2.0, trim_end_seconds = 8.0, decode_audio = False
)
assert calls == [1]
assert len(frames) == round(6.0 * 24)
def test_h3_replacement_audio_bypasses_a_short_embedded_soundtrack():
pytest.importorskip("av")
from core.inference.video import VideoBackend
from core.inference.video_families import detect_video_family
references = VideoBackend._resolve_references(
detect_video_family("MiniMaxAI/MiniMax-H3", None),
"ref2va",
"diffusers",
None,
[
{
"video": _reference_video_data_url(
seconds = 5.0, fps = 24, with_audio = True, audio_seconds = 1.0
),
"audio": _data_url_wav(seconds = 5.0, rate = 32_000),
"trim_start_seconds": 2.0,
"trim_end_seconds": 4.0,
}
],
None,
"match",
960,
544,
)
frames, waveform, sample_rate = references.videos[0]
assert len(frames) == 48
assert sample_rate == 32_000
assert waveform.shape == (64_000, 2)
def test_h3_replacement_audio_starts_at_its_own_zero():
"""A replacement soundtrack is independent of the video, so it starts at its own zero."""
pytest.importorskip("av")
import numpy as np
from core.inference.video import VideoBackend
from core.inference.video_families import detect_video_family
# Signal only in the first second, so the decoded offset is recoverable.
references = VideoBackend._resolve_references(
detect_video_family("MiniMaxAI/MiniMax-H3", None),
"ref2va",
"diffusers",
None,
[
{
"video": _reference_video_data_url(seconds = 12.0, fps = 24, with_audio = False),
"audio": _data_url_wav(seconds = 3.0, rate = 32_000, silent_after = 1.0),
"trim_start_seconds": 5.0,
"trim_end_seconds": 8.0,
}
],
None,
"match",
960,
544,
)
_, waveform, sample_rate = references.videos[0]
assert sample_rate == 32_000
# The clip's length, taken from the replacement's start rather than from its 5s mark.
assert waveform.shape == (96_000, 2)
energy = np.abs(waveform).max(axis = 1)
assert energy[: sample_rate // 2].max() > 0.01
assert energy[2 * sample_rate :].max() <= 0.01
def test_h3_replacement_audio_shorter_than_the_trim_start_is_kept():
"""The same file, shorter than where the video's trim begins, is padded not refused."""
pytest.importorskip("av")
from core.inference.video import VideoBackend
from core.inference.video_families import detect_video_family
references = VideoBackend._resolve_references(
detect_video_family("MiniMaxAI/MiniMax-H3", None),
"ref2va",
"diffusers",
None,
[
{
"video": _reference_video_data_url(seconds = 20.0, fps = 24, with_audio = False),
"audio": _data_url_wav(seconds = 2.0, rate = 32_000),
"trim_start_seconds": 10.0,
"trim_end_seconds": 14.0,
}
],
None,
"match",
960,
544,
)
_, waveform, sample_rate = references.videos[0]
assert waveform.shape == (4 * 32_000, 2)
assert sample_rate == 32_000
def test_h3_begin_generate_reuses_preflight_resolved_references(monkeypatch):
import core.inference.video as video_mod
backend = _h3_ref_backend(monkeypatch, [])
expected = object()
resolve_calls = []
captured = {}
def _resolve(*args, **kwargs):
resolve_calls.append((args, kwargs))
return expected
class _DeferredThread:
def __init__(
self,
*,
target,
args = (),
kwargs,
daemon,
):
# The worker is pinned to its account: the thread target is run_as, the real target rides last in args.
captured.update(target = args[-1] if args else target, kwargs = kwargs, daemon = daemon)
def start(self):
return None
monkeypatch.setattr(backend, "_resolve_references", _resolve)
monkeypatch.setattr(backend, "_state_device_target", lambda _state: None)
monkeypatch.setattr(video_mod.threading, "Thread", _DeferredThread)
monkeypatch.setattr(backend, "_generate_h3_native", lambda **kwargs: kwargs["references"])
backend.begin_generate(prompt = "p")
assert len(resolve_calls) == 1
original_state = backend._state
backend._state = dataclasses.replace(original_state)
with pytest.raises(RuntimeError, match = VIDEO_CANCELLED_MSG):
backend.generate(**captured["kwargs"])
backend._state = original_state
assert backend.generate(**captured["kwargs"]) is expected
assert len(resolve_calls) == 1
assert backend.generate(prompt = "p") is expected
assert len(resolve_calls) == 2
def test_a_v1_videos_job_id_stays_out_of_the_replayable_worker_kwargs(monkeypatch):
"""Keep the /v1/videos job id out of worker kwargs, or replays into generate() raise TypeError."""
import core.inference.video as video_mod
backend = _h3_ref_backend(monkeypatch, [])
expected = object()
captured = {}
class _DeferredThread:
def __init__(
self,
*,
target,
args = (),
kwargs,
daemon,
):
captured.update(target = args[-1] if args else target, kwargs = kwargs, daemon = daemon)
def start(self):
return None
monkeypatch.setattr(backend, "_resolve_references", lambda *a, **k: expected)
monkeypatch.setattr(backend, "_state_device_target", lambda _state: None)
monkeypatch.setattr(video_mod.threading, "Thread", _DeferredThread)
monkeypatch.setattr(backend, "_generate_h3_native", lambda **kwargs: kwargs["references"])
backend.begin_generate(prompt = "p", video_id = "video_abc123")
assert "video_id" not in captured["kwargs"]
assert captured["target"].keywords["video_id"] == "video_abc123"
assert backend.generate(**captured["kwargs"]) is expected
def test_h3_native_refuses_a_later_video_soundtrack_after_a_silent_video(monkeypatch):
pytest.importorskip("av")
backend = _h3_ref_backend(monkeypatch, [])
with pytest.raises(ValueError, match = "Video 2 has audio after a silent earlier video"):
backend.begin_generate(
prompt = "match <Video 1> and <Video 2>",
reference_videos = [
{"video": _reference_video_data_url(with_audio = False)},
{"video": _reference_video_data_url(with_audio = True)},
],
)
def test_h3_reference_images_are_fitted_to_the_requested_policy():
Image = pytest.importorskip("PIL.Image")
from core.inference.video_minimax_h3 import fit_h3_reference_image
source = Image.new("RGB", (6000, 3000), (0, 0, 0))
# "match" brings the reference down to the generation's pixel area, aspect kept.
matched = fit_h3_reference_image(source, width = 960, height = 544, policy = "match")
assert matched.size[0] / matched.size[1] == pytest.approx(2.0, abs = 0.05)
assert matched.size[0] * matched.size[1] <= 960 * 544 * 1.1
# "max" targets the reference pipeline's own 2048px short edge instead.
biggest = fit_h3_reference_image(source, width = 960, height = 544, policy = "max")
assert min(biggest.size) == 2048 and max(biggest.size) == 4096
# Neither ever upscales a source already under its target; it only snaps to 32.
small = Image.new("RGB", (128, 128), (0, 0, 0))
assert fit_h3_reference_image(small, width = 1344, height = 768, policy = "max").size == (128, 128)
with pytest.raises(ValueError, match = "policy"):
fit_h3_reference_image(source, width = 960, height = 544, policy = "huge")
def test_h3_reference_image_fits_a_phone_photo_before_the_generic_source_limit():
pytest.importorskip("PIL.Image")
from core.inference.diffusion import decode_b64_image
from core.inference.video import VideoBackend
from core.inference.video_families import detect_video_family
source = _data_url(5712, 4284)
with pytest.raises(ValueError, match = "maximum is 4096px per side"):
decode_b64_image(source)
references = VideoBackend._resolve_references(
detect_video_family("MiniMaxAI/MiniMax-H3", None),
"ref2va",
"diffusers",
[source],
None,
None,
"match",
960,
544,
)
assert len(references.images) == 1
fitted = references.images[0]
assert fitted.size[0] * fitted.size[1] <= 960 * 544 * 1.1
assert fitted.size[0] / fitted.size[1] == pytest.approx(5712 / 4284, abs = 0.05)
largest = VideoBackend._resolve_references(
detect_video_family("MiniMaxAI/MiniMax-H3", None),
"ref2va",
"diffusers",
[source],
None,
None,
"max",
960,
544,
).images[0]
assert min(largest.size) == 2048
def test_h3_reference_image_source_policy_rejects_excessive_area_before_loading(monkeypatch):
Image = pytest.importorskip("PIL.Image")
from core.inference.diffusion import decode_b64_image
from core.inference.video_minimax_h3 import (
H3_REF_IMAGE_SOURCE_MAX_PIXELS,
H3_REF_IMAGE_SOURCE_MAX_SIDE,
)
loaded = False
def tracked_load():
nonlocal loaded
loaded = True
monkeypatch.setattr(
Image,
"open",
lambda _stream: types.SimpleNamespace(size = (8000, 5000), load = tracked_load),
)
with pytest.raises(ValueError, match = "source pixels"):
decode_b64_image(
"eA==",
max_side = H3_REF_IMAGE_SOURCE_MAX_SIDE,
max_pixels = H3_REF_IMAGE_SOURCE_MAX_PIXELS,
)
assert loaded is False
def test_h3_render_failure_is_recorded_against_the_card_the_load_resolved(monkeypatch, tmp_path):
"""Re-resolving the card when the render dies reads None whenever amd-smi or the inventory is
unavailable at that moment, and a card-less record diverts every card. The load's answer is used."""
from core.inference import sd_cpp_backend
from core.inference.video_minimax_h3 import MiniMaxH3NativeRuntime
backend = _h3_native_backend(monkeypatch, [])
binary = tmp_path / "sd-cli"
binary.write_bytes(b"")
class _Engine:
def __init__(self):
self.binary = str(binary)
def generate_video(self, files, params, **kwargs):
raise RuntimeError(
"sd-cli exited 1. Last output: ROCm error: CUBLAS_STATUS_INVALID_VALUE at hipblasSetStream"
)
object.__setattr__(
backend._state,
"pipe",
MiniMaxH3NativeRuntime(
engine = _Engine(),
files = object(),
offload_flags = (),
selected_card = "Card B@gfx1201",
),
)
monkeypatch.setattr(sd_cpp_backend, "selected_card_identity", lambda _ordinal: None)
noted: list = []
monkeypatch.setattr(
sd_cpp_backend,
"note_accelerator_failure_from_output",
lambda binary, output, *, source = "diffusion", card = None: noted.append(card),
)
with pytest.raises(RuntimeError, match = "CUBLAS_STATUS_INVALID_VALUE"):
backend.generate(prompt = "a cat", width = 960, height = 544)
assert noted == ["Card B@gfx1201"]
def test_h3_native_generate_stages_every_reference_kind(monkeypatch, tmp_path):
pytest.importorskip("av")
calls: list = []
backend = _h3_ref_backend(monkeypatch, calls)
staged: dict = {}
class _Engine:
def generate_video(self, files, params, **kwargs):
# The scratch dir is deleted with the run, so read it here.
staged["images"] = [Path(p).name for p in params.ref_images]
staged["video_frames"] = sorted(Path(params.ref_videos[0]).iterdir())
staged["video_audios"] = [Path(p).name for p in params.ref_video_audios]
staged["audios"] = [Path(p).name for p in params.ref_audios]
staged["wav_ok"] = all(
Path(p).read_bytes()[:4] == b"RIFF"
for p in params.ref_video_audios + params.ref_audios
)
staged["keyframes"] = (params.init_img, params.end_img)
return Path("/tmp/does-not-exist.webm")
from core.inference.video_minimax_h3 import MiniMaxH3NativeRuntime
object.__setattr__(
backend._state,
"pipe",
MiniMaxH3NativeRuntime(engine = _Engine(), files = object(), offload_flags = ()),
)
result = backend.generate(
prompt = "the cat from <Picture 1> surfing, matching <Video 1>",
width = 960,
height = 544,
reference_images = [_data_url(1200, 800), _data_url(640, 640)],
reference_videos = [{"video": _reference_video_data_url()}],
reference_audios = [_data_url_wav()],
)
assert staged["images"] == ["ref-image-00.png", "ref-image-01.png"]
# A reference video is a DIRECTORY of frames sd-cli reads lexicographically, at 24 fps.
assert len(staged["video_frames"]) == 72
assert [p.name for p in staged["video_frames"][:2]] == ["00000.png", "00001.png"]
assert staged["video_audios"] == ["ref-video-audio-00.wav"]
assert staged["audios"] == ["ref-audio-00.wav"]
assert staged["wav_ok"]
assert staged["keyframes"] == (None, None)
assert result["conditioning"] == "ref2va"
def _data_url_wav(
seconds = 1.0,
rate = 32_000,
silent_after = None,
):
"""A 440Hz tone; `silent_after` mutes the tail so a decoded offset is recoverable."""
import base64
import io
import math
import wave
buf = io.BytesIO()
with wave.open(buf, "wb") as handle:
handle.setnchannels(2)
handle.setsampwidth(2)
handle.setframerate(rate)
frames = bytearray()
loud = int(seconds * rate) if silent_after is None else int(silent_after * rate)
for i in range(int(seconds * rate)):
value = int(8000 * math.sin(2 * math.pi * 440 * i / rate)) if i < loud else 0
frames += int(value).to_bytes(2, "little", signed = True) * 2
handle.writeframes(bytes(frames))
return "data:audio/wav;base64," + base64.b64encode(buf.getvalue()).decode()
def test_h3_reference_audio_decodes_inside_the_trained_window():
pytest.importorskip("av")
import base64
from core.inference.video_minimax_h3 import decode_h3_reference_audio
blob = base64.b64decode(_data_url_wav(seconds = 2.0).split(",", 1)[1])
waveform, rate = decode_h3_reference_audio(blob)
assert rate == 32_000
assert waveform.shape == (64_000, 2)
def test_h3_reference_audio_refuses_a_clip_past_the_window_while_decoding():
# Encoded size does not bound the float32 decode (32 MiB is ~1.9 GB), so refuse during it.
pytest.importorskip("av")
import base64
from core.inference.video_minimax_h3 import decode_h3_reference_audio
blob = base64.b64decode(_data_url_wav(seconds = 15.5).split(",", 1)[1])
with pytest.raises(ValueError, match = "up to 15 seconds"):
decode_h3_reference_audio(blob)
def test_h3_partitions_refuse_each_others_conditioning(monkeypatch):
# The resident partition decides which conditioning is valid.
keyframe_backend = _h3_native_backend(monkeypatch, [])
with pytest.raises(ValueError, match = "Load a minimax_h3_ref2va checkpoint"):
keyframe_backend.generate(prompt = "p", reference_images = [_data_url(64, 64)])
reference_backend = _h3_ref_backend(monkeypatch, [])
with pytest.raises(ValueError, match = "Load a minimax_h3_fl2va checkpoint"):
reference_backend.generate(prompt = "p", first_frame = _data_url(64, 64))
def test_h3_native_refuses_the_max_reference_policy(monkeypatch):
# sd.cpp cannot preserve the 2048px "max" policy.
backend = _h3_ref_backend(monkeypatch, [])
with pytest.raises(ValueError, match = "needs the Diffusers engine"):
backend.generate(
prompt = "p", reference_images = [_data_url(64, 64)], reference_image_size = "max"
)
def test_h3_status_reports_the_resident_partition(monkeypatch):
keyframe_backend = _h3_native_backend(monkeypatch, [])
status = keyframe_backend.status()
assert status["h3_task"] == "fl2va"
assert status["supports_keyframes"] is True and status["supports_references"] is False
reference_backend = _h3_ref_backend(monkeypatch, [])
status = reference_backend.status()
assert status["h3_task"] == "ref2va"
assert status["supports_keyframes"] is False and status["supports_references"] is True
def test_h3_load_refuses_a_task_that_contradicts_the_picked_checkpoint():
backend = VideoBackend()
backend.validate_load_request(
"unsloth/MiniMax-H3-GGUF",
gguf_filename = "minimax_h3_ref2va_pruned-Q4_K_M.gguf",
family_override = "minimax-h3",
h3_task = "ref2va",
)
with pytest.raises(ValueError, match = "is the ref2va partition"):
backend.validate_load_request(
"unsloth/MiniMax-H3-GGUF",
gguf_filename = "minimax_h3_ref2va_pruned-Q4_K_M.gguf",
family_override = "minimax-h3",
h3_task = "fl2va",
)
def test_h3_modular_load_brings_up_the_requested_partition(monkeypatch):
import types
seen: dict = {}
class _FakeModularPipeline:
@classmethod
def from_pretrained(cls, repo, **kwargs):
return cls()
def load_components(self, **kwargs):
seen["workflow"] = kwargs.get("workflow")
def to(self, device):
return self
diffusers = types.SimpleNamespace(
ComponentsManager = lambda: types.SimpleNamespace(
enable_auto_cpu_offload = lambda **kwargs: None
),
ModularPipeline = _FakeModularPipeline,
)
torch = types.SimpleNamespace(bfloat16 = "bf16")
fam = _detect_load_family("MiniMaxAI/MiniMax-H3", None, "minimax-h3")
backend = VideoBackend()
status = backend._load_h3_modular_pipeline(
# An unset request resolves to int8 now, which takes the hosted-checkpoint path.
transformer_quant = "none",
diffusers = diffusers,
torch = torch,
fam = fam,
repo_id = "MiniMaxAI/MiniMax-H3",
base = fam.base_repo,
kind = "pipeline",
dtype = torch.bfloat16,
device = "cuda",
hf_token = None,
memory_mode = None,
h3_task = "ref2va",
)
assert seen["workflow"] == "ref2va"
assert status["supports_references"] is True and status["supports_keyframes"] is False
def test_h3_flow_shift_defaults_to_the_released_schedule(monkeypatch):
calls: list = []
backend = _h3_native_backend(monkeypatch, calls)
result = backend.generate(prompt = "p", width = 640, height = 384)
assert calls[-1]["params"].flow_shift == 12.0
assert (result["flow_shift"], result["audio_flow_shift"]) == (12.0, 3.0)
backend.generate(prompt = "p", width = 640, height = 384, flow_shift = 6.5)
assert calls[-1]["params"].flow_shift == 6.5
# sd.cpp accepts only the released audio shift it already applies.
backend.generate(prompt = "p", width = 640, height = 384, audio_flow_shift = 3.0)
with pytest.raises(ValueError, match = "Diffusers engine"):
backend.generate(prompt = "p", width = 640, height = 384, audio_flow_shift = 5.0)
status = backend.status()
assert status["defaults"]["flow_shift"] == 12.0
assert status["defaults"]["audio_flow_shift"] == 3.0
assert status["defaults"]["supports_audio_flow_shift"] is False
def test_schedule_shifts_are_refused_by_families_that_do_not_expose_them():
fam = _detect_load_family("Lightricks/LTX-2", None, None)
with pytest.raises(ValueError, match = "does not expose a video flow_shift"):
VideoBackend._resolve_flow_shifts(fam, "diffusers", 5.0, None)
with pytest.raises(ValueError, match = "does not expose an audio_flow_shift"):
VideoBackend._resolve_flow_shifts(fam, "diffusers", None, 3.0)
def test_h3_modular_generate_sets_both_schedule_shifts(fake_runtime, monkeypatch):
import contextlib
import types
from core.inference.video import _VideoLoadState
shifts: dict = {}
class _Scheduler:
def __init__(self, name):
self._name = name
def set_shift(self, value):
shifts[self._name] = value
def step(self, *args, **kwargs):
return None
class _ModularPipe:
scheduler = _Scheduler("video")
audio_scheduler = _Scheduler("audio")
def __call__(self, **kwargs):
shifts["called"] = True
return {"videos": [[object()]], "audio": None, "sampling_rate": None}
backend = VideoBackend()
fam = _detect_load_family("MiniMaxAI/MiniMax-H3", None, "minimax-h3")
backend._state = _VideoLoadState(
pipe = _ModularPipe(),
family = fam,
repo_id = "MiniMaxAI/MiniMax-H3",
base_repo = fam.base_repo,
device = "cpu",
dtype = "bfloat16",
kind = "pipeline",
engine = "diffusers",
h3_task = "fl2va",
)
monkeypatch.setattr(VideoBackend, "_encode_mp4", staticmethod(lambda *a, **k: b"MP4"))
monkeypatch.setattr("core.inference.video.contextlib", contextlib)
result = backend.generate(prompt = "p", width = 960, height = 544, steps = 2)
assert shifts["video"] == 12.0 and shifts["audio"] == 3.0
backend.generate(
prompt = "p",
width = 960,
height = 544,
steps = 2,
flow_shift = 7.0,
audio_flow_shift = 4.0,
)
assert shifts["video"] == 7.0 and shifts["audio"] == 4.0
assert result["flow_shift"] == 12.0
def test_h3_begin_generate_refuses_an_unhonourable_audio_shift(monkeypatch):
# Reject unsupported shifts before the asynchronous job starts.
backend = _h3_native_backend(monkeypatch, [])
with pytest.raises(ValueError, match = "Diffusers engine"):
backend.begin_generate(prompt = "p", audio_flow_shift = 6.0)
assert backend.generate_progress()["active"] is False
backend.begin_generate(prompt = "p", audio_flow_shift = 3.0)
def test_h3_ref2va_partition_refuses_a_reference_less_request(monkeypatch):
"""Ref2VA loads only transformer_ref, so text-only requests are refused up front on both engines."""
backend = _h3_ref_backend(monkeypatch, [])
with pytest.raises(ValueError, match = "Add at least one reference"):
backend.generate(prompt = "a fox in snow", width = 640, height = 384)
with pytest.raises(ValueError, match = "Add at least one reference"):
backend.begin_generate(prompt = "a fox in snow")
assert backend.generate_progress()["active"] is False
keyframe_backend = _h3_native_backend(monkeypatch, [])
assert (
keyframe_backend.generate(prompt = "a fox in snow", width = 640, height = 384)["conditioning"]
== "t2va"
)
def test_h3_vae_trim_keeps_the_encoder_for_the_workflows_that_encode():
"""Encoder drop is t2va-only: fl2va and ref2va encode keyframes or references through it."""
torch = pytest.importorskip("torch")
from core.inference.video_minimax_h3 import trim_h3_video_vae
def _vae():
vae = types.SimpleNamespace()
vae.encoder = torch.nn.Conv2d(3, 8, 3)
vae.quant_conv = torch.nn.Conv2d(8, 8, 1)
vae.decoder = torch.nn.Conv2d(8, 3, 3)
vae.post_quant_conv = torch.nn.Conv2d(8, 8, 1)
return vae
for workflow in ("fl2va", "ref2va"):
vae = _vae()
report = trim_h3_video_vae(vae, workflow = workflow)
assert vae.encoder is not None, workflow
assert vae.quant_conv is not None, workflow
assert report["encoder_freed"] == 0, workflow
assert report["decoder_freed"] > 0, workflow
assert vae.decoder.weight.dtype is torch.float16, workflow
vae = _vae()
assert trim_h3_video_vae(vae, workflow = "t2va")["encoder_freed"] > 0
assert vae.encoder is None
def _failing_pipe_call(exc):
# Explicit signature: generate() inspects it; **kwargs would route to scheduler-wrapping.
def _boom(
self,
*,
prompt = None,
negative_prompt = None,
num_inference_steps = None,
guidance_scale = None,
width = None,
height = None,
num_frames = None,
frame_rate = None,
generator = None,
callback_on_step_end = None,
**kwargs,
):
raise exc
return _boom
def _capture_generate_failures(monkeypatch):
"""Collects video.generate_failed_request lines, since caplog cannot see the structlog logger."""
import core.inference.video as video_mod
lines: list = []
real = video_mod.logger
class _Recorder:
def error(self, fmt, *a, **k):
message = fmt % a if a else fmt
if "generate_failed_request" in message:
lines.append(message)
return real.error(fmt, *a, **k)
def __getattr__(self, name):
return getattr(real, name)
monkeypatch.setattr(video_mod, "logger", _Recorder())
return lines
def test_a_failed_generation_logs_the_resolved_request(fake_runtime, tmp_path, monkeypatch):
# Log the request shape behind an OOM (#8225).
backend, video_mod = _shared_setup_1(tmp_path)
_shared_setup_6(backend, monkeypatch)
monkeypatch.setattr(video_mod, "sdpa_math_only", lambda target, *_: False)
records = _capture_generate_failures(monkeypatch)
with pytest.raises(RuntimeError):
backend.generate(prompt = "a sloth surfing", width = 1000, height = 700, num_frames = 120)
assert len(records) == 1
line = records[0]
# The SNAPPED shape, which is what actually ran, not the caller's raw request.
assert "width=992" in line and "height=672" in line and "frames=113" in line
assert "steps=" in line and "seed=" in line and "family=ltx-2" in line
assert "device=" in line and "offload=" in line
def test_a_rejected_request_is_not_recorded_as_a_server_failure(
fake_runtime, tmp_path, monkeypatch
):
# ValueErrors map to client feedback, so the shape log must not emit an ERROR.
backend, video_mod = _shared_setup_1(tmp_path)
monkeypatch.setattr(
type(backend._state.pipe),
"__call__",
_failing_pipe_call(ValueError("`height` and `width` have to be divisible by 32")),
)
records = _capture_generate_failures(monkeypatch)
with pytest.raises(ValueError):
backend.generate(prompt = "a sloth surfing", width = 1000, height = 700, num_frames = 120)
assert records == []
def test_the_failure_log_carries_no_prompt_text(fake_runtime, tmp_path, monkeypatch):
# A length only: the server log is not the place for user content.
backend, video_mod = _shared_setup_1(tmp_path)
monkeypatch.setattr(
type(backend._state.pipe), "__call__", _failing_pipe_call(RuntimeError("kaboom"))
)
monkeypatch.setattr(video_mod, "sdpa_math_only", lambda target, *_: False)
records = _capture_generate_failures(monkeypatch)
with pytest.raises(RuntimeError):
backend.generate(prompt = "a secret about oranges", negative_prompt = "blurry")
line = records[0]
assert "oranges" not in line and "blurry" not in line
assert "prompt_chars=22" in line and "negative_prompt_chars=6" in line
def test_an_oom_on_a_math_only_device_names_the_quadratic_cost(fake_runtime, tmp_path, monkeypatch):
# With no fused kernel, an OOM should carry the score-matrix diagnosis.
backend, video_mod = _shared_setup_1(tmp_path)
_shared_setup_6(backend, monkeypatch)
monkeypatch.setattr(video_mod, "sdpa_math_only", lambda target, *_: True)
records = _shared_setup_10(backend, monkeypatch)
assert len(records) == 2
assert "score matrix" in records[1] and "SQUARE" in records[1]
def test_a_non_oom_failure_does_not_blame_attention(fake_runtime, tmp_path, monkeypatch):
# Only allocator failures get the diagnosis.
backend, video_mod = _shared_setup_1(tmp_path)
monkeypatch.setattr(
type(backend._state.pipe),
"__call__",
_failing_pipe_call(RuntimeError("scheduler produced NaN sigmas")),
)
monkeypatch.setattr(video_mod, "sdpa_math_only", lambda target, *_: True)
records = _shared_setup_10(backend, monkeypatch)
assert len(records) == 1
assert "score matrix" not in records[0]
def test_a_cancel_is_not_logged_as_a_failure(fake_runtime, tmp_path, monkeypatch):
# Cancels share this handler; logging a user stop as a failure would bury the real ones.
from core.inference.video_families import VIDEO_CANCELLED_MSG
backend = VideoBackend()
_load_gguf(backend, tmp_path)
records = _capture_generate_failures(monkeypatch)
cancel = threading.Event()
cancel.set()
with pytest.raises(RuntimeError, match = VIDEO_CANCELLED_MSG):
backend.generate(prompt = "a clip", cancel_event = cancel)
assert records == []
def test_a_failure_before_the_request_resolves_logs_nothing(fake_runtime, tmp_path, monkeypatch):
# Log nothing until the shape is snapped; a half-bound record is worse than none.
backend, video_mod = _shared_setup_1(tmp_path)
records = _capture_generate_failures(monkeypatch)
def _broken(fam, w, h):
raise RuntimeError("resolution table is broken")
monkeypatch.setattr(video_mod, "snap_video_size", _broken)
with pytest.raises(RuntimeError, match = "resolution table"):
backend.generate(prompt = "a clip")
assert records == []
def test_a_broken_diagnostic_never_replaces_the_real_failure(fake_runtime, tmp_path, monkeypatch):
# If the probe or the formatting raises, the caller must still see the original exception.
backend, video_mod = _shared_setup_1(tmp_path)
_shared_setup_6(backend, monkeypatch)
def _boom(target, *_):
raise RuntimeError("the probe itself is broken")
monkeypatch.setattr(video_mod, "sdpa_math_only", _boom)
with pytest.raises(RuntimeError, match = "66.54 GiB"):
backend.generate(prompt = "a clip")
@pytest.mark.parametrize(
"exc, expected",
[
(RuntimeError("CUDA out of memory. Tried to allocate 66.54 GiB."), True),
(RuntimeError("HIP out of memory"), True),
(RuntimeError("Tried to allocate 2.00 GiB"), True),
(RuntimeError("scheduler produced NaN sigmas"), False),
(ValueError("bad prompt"), False),
],
)
def test_out_of_memory_is_recognised_by_text_not_only_by_class(exc, expected):
# Some backends raise a plain RuntimeError for OOM, so isinstance alone misses it.
import core.inference.video as video_mod
assert video_mod._is_out_of_memory(exc) is expected
def test_the_oom_diagnosis_is_skipped_when_an_external_backend_ran(
fake_runtime, tmp_path, monkeypatch
):
"""AITER / xFormers replace torch's SDPA dispatch, so probing native SDPA describes code never
run; with AITER, every OOM was falsely blamed on the quadratic math backend."""
backend, video_mod = _shared_setup_1(tmp_path)
backend._state = replace(backend._state, attention_backend = "aiter")
monkeypatch.setattr(
type(backend._state.pipe),
"__call__",
_failing_pipe_call(RuntimeError("HIP out of memory. Tried to allocate 66.54 GiB.")),
)
probed: list = []
def _never(target, *_):
probed.append(target)
return True
monkeypatch.setattr(video_mod, "sdpa_math_only", _never)
records = _shared_setup_10(backend, monkeypatch)
assert probed == [], "an engaged external backend must not be diagnosed as native SDPA"
assert not any(video_mod.SDPA_MATH_ONLY_MESSAGE in line for line in records)
assert any("family=ltx-2" in line for line in records)
def test_the_oom_probe_uses_the_dtype_the_run_actually_used(fake_runtime, tmp_path, monkeypatch):
"""Video families promote a resolved fp16 to fp32, but fused SDPA kernels are half-precision
only; a dtypeless probe defaults to fp16, answering for a precision never used."""
import torch
backend, video_mod = _shared_setup_1(tmp_path)
backend._state = replace(backend._state, dtype = "float32", attention_backend = None)
_shared_setup_6(backend, monkeypatch)
seen: list = []
monkeypatch.setattr(
video_mod, "sdpa_math_only", lambda target, *a: seen.append((target, *a)) or True
)
monkeypatch.setattr(video_mod, "_dit_head_dims", lambda pipe: {128})
records = _shared_setup_10(backend, monkeypatch)
assert [a for _, *a in seen] == [[[128]]]
assert any("dtype=float32" in line for line in records)
assert len(seen) == 1
def test_the_probe_target_resolves_the_recorded_dtype():
"""The other half: that recorded string becomes the real torch dtype the probe asks about."""
import torch
import core.inference.video as video_mod
assert video_mod._probe_target({"device": "cuda", "dtype": "float32"}).dtype is torch.float32
assert video_mod._probe_target({"device": "cuda", "dtype": "bfloat16"}).dtype is torch.bfloat16
assert video_mod._probe_target({"device": "cuda"}).dtype is None
assert video_mod._probe_target({"device": "cuda", "dtype": "nonsense"}).dtype is None
assert video_mod._probe_target({"device": "cuda", "dtype": "nn"}).dtype is None
# Text-encoder budgeting: a pre-cast fp8 encoder loads ~half the bf16 table size; for
# ltx-2 (Gemma3-12B) the bf16 figure would over-state by ~11 GB and refuse fitting loads.
_MIB_PER_GB = 1000.0**3 / (1024.0 * 1024.0)
def _capture_plan(monkeypatch):
"""Record every plan_diffusion_memory call's kwargs, keeping the real planner."""
import core.inference.video as video_mod
calls = []
real = video_mod.plan_diffusion_memory
def _spy(**kwargs):
calls.append(kwargs)
return real(**kwargs)
monkeypatch.setattr(video_mod, "plan_diffusion_memory", _spy)
return calls
def _allow_te_prequant(monkeypatch, *, injects = True):
"""Stub the pre-cast encoder as resolvable; injects=False models the dense fallback."""
import core.inference.diffusion_precision as precision
import core.inference.diffusion_te_prequant as tpq
# The CPU stub has no castable encoder; keep the legacy silent fallback here.
monkeypatch.setenv("UNSLOTH_DIFFUSION_ALLOW_PRECISION_FALLBACK", "1")
monkeypatch.setattr(precision, "te_quant_supported", lambda target, mode: True)
injected = {"text_encoder": object()} if injects else {}
monkeypatch.setattr(tpq, "te_prequant_pipe_kwargs", lambda *a, **k: dict(injected))
return tpq.TE_PREQUANT_BUDGET_SCALE
def _capture_te_quant_lines(monkeypatch):
import core.inference.video as video_mod
lines: list = []
real = video_mod.logger
class _Recorder:
def info(self, fmt, *a, **k):
message = fmt % a if a else fmt
if message.startswith("video.text_encoder_quant:"):
lines.append(message)
return real.info(fmt, *a, **k)
def __getattr__(self, name):
return getattr(real, name)
monkeypatch.setattr(video_mod, "logger", _Recorder())
return lines
@pytest.mark.parametrize("injects", [True, False])
def test_a_failed_te_prefetch_is_logged_by_the_retried_outcome(
fake_runtime, monkeypatch, tmp_path, injects
):
_allow_te_prequant(monkeypatch, injects = injects)
lines = _capture_te_quant_lines(monkeypatch)
(tmp_path / "model.gguf").write_bytes(b"weights")
VideoBackend().load_pipeline(
str(tmp_path),
gguf_filename = "model.gguf",
base_repo = "Lightricks/LTX-2",
family_override = "ltx-2",
_te_prequant_failed = {"text_encoder": "unsloth/LTX-2-FP8: HTTP 503"},
)
assert len(lines) == 1
if injects:
assert "'fp8' selected automatically for ltx-2" in lines[0]
else:
assert "is not available" in lines[0] and "HTTP 503" in lines[0]
def test_gguf_plan_budgets_a_pre_cast_text_encoder_at_its_real_size(
fake_runtime, monkeypatch, tmp_path
):
scale, text_encoder_gb, transformer_gb, vae_gb = _shared_setup_9(monkeypatch)
calls = _capture_plan(monkeypatch)
backend = VideoBackend()
(tmp_path / "model.gguf").write_bytes(b"weights")
backend.load_pipeline(
str(tmp_path),
gguf_filename = "model.gguf",
base_repo = "Lightricks/LTX-2",
family_override = "ltx-2",
text_encoder_quant = "fp8",
)
quant_companion = calls[0]["companion_dense_mib"]
quant_dense = calls[0]["model_dense_mib"]
calls.clear()
backend = VideoBackend()
backend.load_pipeline(
str(tmp_path),
gguf_filename = "model.gguf",
base_repo = "Lightricks/LTX-2",
family_override = "ltx-2",
# Pinned dense: unset now takes the family's hosted fp8 encoder.
text_encoder_quant = "none",
)
bf16_companion = calls[0]["companion_dense_mib"]
bf16_dense = calls[0]["model_dense_mib"]
assert quant_companion == int((text_encoder_gb * scale + vae_gb) * _MIB_PER_GB)
# ...the VAE is NOT: nothing on this path quantises it, and the Wan families widen it to fp32.
assert quant_companion - int(text_encoder_gb * scale * _MIB_PER_GB) == int(vae_gb * _MIB_PER_GB)
assert bf16_companion == int((text_encoder_gb + vae_gb) * _MIB_PER_GB)
# The saving reaches model_dense_mib, which is the number PR #8213 refuses on.
assert bf16_dense - quant_dense == bf16_companion - quant_companion
# ~11 GB for Gemma3-12B, so this is worth a whole offload tier rather than rounding noise.
assert (bf16_dense - quant_dense) / _MIB_PER_GB > 8.0
assert bf16_dense - bf16_companion == quant_dense - quant_companion
def test_pipeline_plan_budgets_a_pre_cast_text_encoder_at_its_real_size(fake_runtime, monkeypatch):
scale, text_encoder_gb, transformer_gb, vae_gb = _shared_setup_9(monkeypatch)
calls = _capture_plan(monkeypatch)
VideoBackend().load_pipeline(
"Lightricks/LTX-2", model_kind = "pipeline", text_encoder_quant = "fp8"
)
assert calls[0]["model_dense_mib"] == int(
(transformer_gb + text_encoder_gb * scale + vae_gb) * _MIB_PER_GB
)
assert calls[0]["companion_dense_mib"] == int((text_encoder_gb * scale + vae_gb) * _MIB_PER_GB)
assert calls[0]["text_encoder_dense_mib"] == int(text_encoder_gb * scale * _MIB_PER_GB)
def test_plan_returns_to_bf16_when_the_pre_cast_encoder_does_not_inject(fake_runtime, monkeypatch):
# If the checkpoint resolves but cannot load, assembly falls back to dense, so the plan
# must be rebuilt at bf16 before placement.
from core.inference.video_families import detect_video_family
components = detect_video_family("Lightricks/LTX-2").bf16_components_gb
_allow_te_prequant(monkeypatch, injects = False)
calls = _capture_plan(monkeypatch)
VideoBackend().load_pipeline(
"Lightricks/LTX-2", model_kind = "pipeline", text_encoder_quant = "fp8"
)
assert calls[0]["model_dense_mib"] < int(sum(components) * _MIB_PER_GB)
assert calls[-1]["model_dense_mib"] == int(sum(components) * _MIB_PER_GB)
def test_plan_keeps_the_bf16_budget_without_a_hosted_pre_cast_encoder(fake_runtime, monkeypatch):
# A family requesting fp8 without a hosted pre-cast checkpoint casts the dense encoder in place
# after assembly, so its peak is bf16 and the budget must not shrink.
import dataclasses
import core.inference.video_families as vf
from core.inference.video_families import detect_video_family
_allow_te_prequant(monkeypatch)
wan = detect_video_family("Wan-AI/Wan2.2-TI2V-5B-Diffusers")
bare = dataclasses.replace(wan, te_prequant_repos = (), te_quant_auto = None)
monkeypatch.setattr(vf, "_FAMILIES", tuple(bare if f is wan else f for f in vf._FAMILIES))
import core.inference.diffusion_te_prequant as tpq
monkeypatch.setattr(tpq, "TE_INT8_CONVROT_FILES", {})
components = wan.bf16_components_gb
calls = _capture_plan(monkeypatch)
VideoBackend().load_pipeline(
"Wan-AI/Wan2.2-TI2V-5B-Diffusers", model_kind = "pipeline", text_encoder_quant = "fp8"
)
assert calls[0]["model_dense_mib"] == int(sum(components) * _MIB_PER_GB)
def test_default_load_budgets_the_hosted_encoder_its_family_defaults_to(fake_runtime, monkeypatch):
# An unset request on a te_quant_auto family takes the hosted fp8 encoder and budgets its
# pre-cast size, as explicit fp8 does; "none" keeps the bf16 budget. The hosted file must be
# CONFIRMED (on disk or listed by the Hub) or the dense encoder is budgeted.
import core.inference.diffusion_te_prequant as tpq
from core.inference.video_families import detect_video_family
scale = _allow_te_prequant(monkeypatch)
for repo in ("Wan-AI/Wan2.2-TI2V-5B-Diffusers", "Wan-AI/Wan2.1-T2V-1.3B-Diffusers"):
fam = detect_video_family(repo)
transformer_gb, text_encoder_gb, vae_gb = fam.bf16_components_gb
monkeypatch.setattr(tpq, "te_prequant_sources_confirmed", lambda *a, **k: True)
calls = _capture_plan(monkeypatch)
VideoBackend().load_pipeline(repo, model_kind = "pipeline")
assert calls[0]["text_encoder_dense_mib"] == int(
text_encoder_gb * scale * _MIB_PER_GB
), repo
monkeypatch.setattr(tpq, "te_prequant_sources_confirmed", lambda *a, **k: False)
calls = _capture_plan(monkeypatch)
VideoBackend().load_pipeline(repo, model_kind = "pipeline")
assert calls[0]["text_encoder_dense_mib"] == int(text_encoder_gb * _MIB_PER_GB), repo
calls = _capture_plan(monkeypatch)
VideoBackend().load_pipeline(repo, model_kind = "pipeline", text_encoder_quant = "none")
assert calls[0]["text_encoder_dense_mib"] == int(text_encoder_gb * _MIB_PER_GB), repo
def test_plan_is_unchanged_when_no_text_encoder_quant_is_requested(fake_runtime, monkeypatch):
# A default load is inert: every family keeps its bf16 budget, so no decision moves.
from core.inference.diffusion_families import family_pipeline_available
from core.inference.video_families import _FAMILIES
_allow_te_prequant(monkeypatch)
monkeypatch.setenv("UNSLOTH_COSMOS3_SAFETY_CHECKER", "0")
calls = _capture_plan(monkeypatch)
for fam in _FAMILIES:
if fam.bf16_components_gb is None or fam.name == "wan2.2-t2v-a14b":
continue
# Modular-workflow families dispatch to their own loader before plan_diffusion_memory.
if fam.modular_workflow:
continue
calls.clear()
# "none": a family with te_quant_auto takes its hosted encoder on an unset request, which
# test_default_load_budgets_the_hosted_encoder_its_family_defaults_to covers.
VideoBackend().load_pipeline(
fam.base_repo,
model_kind = "pipeline",
text_encoder_quant = "none" if fam.te_quant_auto else None,
)
# LTX-2.5's encoder runs in a second process; its CUDA context is priced on top of the table.
from core.inference.video_ltx25 import LTX25_WORKER_RESIDENT_GB
extra_gb = LTX25_WORKER_RESIDENT_GB if fam.name == "ltx-2.5" else 0.0
# LTX-2.5's unset request keeps its bf16 encoder (int8 is opt-in), so it is priced at the table too.
components = list(fam.bf16_components_gb)
assert calls[0]["model_dense_mib"] == int(
(sum(components) + extra_gb) * _MIB_PER_GB
), fam.name
def test_dense_quant_replan_uses_the_scaled_text_encoder(fake_runtime, monkeypatch):
# The transformer-quant re-plan must carry the same scaled encoder.
import core.inference.video as video_mod
from core.inference.diffusion_auto_policy import _QUANT_STEADY_FACTOR
scale, text_encoder_gb, transformer_gb, vae_gb = _shared_setup_9(monkeypatch)
monkeypatch.setattr(video_mod, "dense_transformer_supported", lambda target: True)
monkeypatch.setattr(
video_mod,
"select_transformer_quant_scheme",
lambda target, mode, family = None, **_kw: "int8",
)
monkeypatch.setattr(video_mod, "quantize_transformer", lambda *a, **k: None)
# Force the first plan to offload so the re-plan branch runs.
import dataclasses
real = video_mod.plan_diffusion_memory
calls = []
def _spy(**kwargs):
calls.append(kwargs)
return dataclasses.replace(real(**kwargs), offload_policy = "model")
monkeypatch.setattr(video_mod, "plan_diffusion_memory", _spy)
placements = _stub_apply_memory_plan(monkeypatch, video_mod)
VideoBackend().load_pipeline(
"Lightricks/LTX-2",
model_kind = "pipeline",
transformer_quant = "int8",
text_encoder_quant = "fp8",
)
_assert_placement_follows_the_target(placements, video_mod)
assert len(calls) == 2, "the dense-quant re-plan did not run"
assert calls[1]["model_dense_mib"] == int(
(transformer_gb * _QUANT_STEADY_FACTOR["int8"] + text_encoder_gb * scale + vae_gb)
* _MIB_PER_GB
)
_H3_TWO_PARTITION_SIBLINGS = [
_sibling("model_index.json", 1),
_sibling("modular_model_index.json", 1),
_sibling("scheduler/scheduler_config.json", 1),
_sibling("audio_scheduler/scheduler_config.json", 1),
_sibling("vae/diffusion_pytorch_model.safetensors", 10),
_sibling("audio_vae/diffusion_pytorch_model.safetensors", 1),
_sibling("text_encoder/model-00001-of-00002.safetensors", 66),
_sibling("tokenizer/tokenizer.json", 1),
_sibling("processor/preprocessor_config.json", 1),
_sibling("transformer/config.json", 1),
_sibling("transformer/diffusion_pytorch_model-00001-of-00002.safetensors", 66),
_sibling("transformer_ref/config.json", 1),
_sibling("transformer_ref/diffusion_pytorch_model-00001-of-00002.safetensors", 66),
_sibling("FL2VA/single_file.safetensors", 144),
_sibling("Ref2VA/single_file.safetensors", 144),
]
def test_a_ref2va_pick_stages_the_reference_denoiser_and_only_that_one():
"""A ref2va pick stages only transformer_ref/, the one denoiser its load builds."""
info = types.SimpleNamespace(siblings = _H3_TWO_PARTITION_SIBLINGS)
ref = [n for n, _ in VideoBackend._base_download_files(info, "pipeline", h3_task = "ref2va")]
assert any(n.startswith("transformer_ref/") for n in ref)
assert not any(n.startswith("transformer/") for n in ref)
for task in (None, "fl2va"):
keyframes = [
n for n, _ in VideoBackend._base_download_files(info, "pipeline", h3_task = task)
]
assert any(n.startswith("transformer/") for n in keyframes)
assert not any(n.startswith("transformer_ref/") for n in keyframes)
assert not any(n.startswith(("FL2VA/", "Ref2VA/")) for n in ref)
def test_download_plan_keys_the_h3_denoiser_on_the_requested_task(monkeypatch):
# The task must reach the plan, or a References pick stages 66.28 GB it never opens.
_cuda_bf16_target(monkeypatch)
_plan_api(monkeypatch, {"MiniMaxAI/MiniMax-H3": _H3_TWO_PARTITION_SIBLINGS})
def files_for(task):
plan = VideoBackend().download_plan(
"MiniMaxAI/MiniMax-H3",
family_override = "minimax-h3",
model_kind = "pipeline",
h3_task = task,
)
by_repo = {entry["repo_id"]: entry for entry in plan["entries"]}
return by_repo["MiniMaxAI/MiniMax-H3"]["files"]
assert any(n.startswith("transformer_ref/") for n in files_for("ref2va"))
assert not any(n.startswith("transformer/") for n in files_for("ref2va"))
assert any(n.startswith("transformer/") for n in files_for(None))
def test_h3_records_the_guidance_that_actually_ran(monkeypatch):
"""H3's supports_cfg=False means recorded guidance must be the value that ran, not the request."""
pytest.importorskip("PIL.Image")
calls: list = []
backend = _h3_native_backend(monkeypatch, calls)
result = backend.generate(prompt = "a fox runs through snow", width = 960, height = 544, guidance = 7.5)
assert result["guidance"] == backend._state.family.default_guidance == 1.0
assert calls[-1]["params"].cfg_scale == 1.0
def test_h3_guidance_normalises_to_its_own_default_not_a_neighbours(monkeypatch):
"""Normalise guidance with the family default; a local path can match a neighbour's id."""
import dataclasses
pytest.importorskip("PIL.Image")
calls: list = []
backend = _h3_native_backend(monkeypatch, calls)
local = "/models/ltx/minimax_h3_fl2va-Q4_K_M.gguf"
backend._state = dataclasses.replace(backend._state, repo_id = local)
# Precondition: the id resolves to a different family's guidance, not H3's.
from core.inference.video import default_video_generation_params
fam = backend._state.family
_steps, derived = default_video_generation_params(
local, fallback = (fam.default_steps, fam.default_guidance)
)
assert derived != fam.default_guidance
result = backend.generate(prompt = "a fox runs through snow", width = 960, height = 544)
assert result["guidance"] == fam.default_guidance == 1.0
assert calls[-1]["params"].cfg_scale == 1.0
def test_h3_records_no_negative_prompt_because_neither_engine_takes_one(monkeypatch):
"""H3 records no negative prompt: it is guidance-distilled and neither engine can consume one."""
pytest.importorskip("PIL.Image")
calls: list = []
backend = _h3_native_backend(monkeypatch, calls)
result = backend.generate(
prompt = "a fox runs through snow",
negative_prompt = "blurry, watermark",
width = 960,
height = 544,
)
assert result["negative_prompt"] is None
assert not hasattr(calls[-1]["params"], "negative_prompt")
def test_the_video_sidecar_records_the_negative_prompt_that_ran(monkeypatch, tmp_path):
"""The gallery recipe comes from the RESULT like guidance beside it, not the request;
normalising only inside generate() would leave _run_generate persisting the original string."""
from core.inference import video as video_mod
from core.inference import video_gallery
saved: list = []
monkeypatch.setattr(
video_gallery, "save", lambda data, meta: (saved.append(meta), {"id": "v1"})[1]
)
backend = VideoBackend()
result = {
"mp4_bytes": b"MP4",
"seed": 7,
"repo_id": "unsloth/MiniMax-H3-GGUF",
"width": 960,
"height": 544,
"num_frames": 124,
"fps": 24,
"duration_s": 5.0,
"has_audio": True,
"conditioning": "t2va",
"steps": 30,
"guidance": 1.0,
"negative_prompt": None,
}
monkeypatch.setattr(backend, "generate", lambda **kw: result)
monkeypatch.setattr(backend, "_finish_generate_job", lambda **kw: None)
backend._run_generate(
cancel_event = threading.Event(),
prompt = "a fox runs through snow",
negative_prompt = "blurry, watermark",
)
assert saved and saved[-1]["negative_prompt"] is None
assert saved[-1]["prompt"] == "a fox runs through snow"
def test_a_managed_h3_native_run_holds_the_install_off(monkeypatch, tmp_path):
"""An H3 native run is an sd-cli run from the managed tree, so it takes the reader claim;
without one, an install's sweep unlinks the CLI it resolved at load."""
pytest.importorskip("PIL.Image")
import core.inference.sd_cpp_backend as bk
managed = _shared_setup_4(monkeypatch, tmp_path)
managed.write_bytes(b"managed")
calls: list = []
backend = _h3_native_backend(monkeypatch, calls, binary = managed)
held: list = []
inner = backend._state.pipe.engine.generate_video
def _watching(files, params, **kwargs):
held.append(bk._tree_readers)
# An install decided right now must stand down rather than replace what is executing.
with bk._tree_claimed_for_install() as claimed:
held.append(claimed)
return inner(files, params, **kwargs)
backend._state.pipe.engine.generate_video = _watching
monkeypatch.setattr(bk, "_sd_cpp_backend", None)
backend.generate(prompt = "p", width = 960, height = 544)
assert held == [1, False]
assert bk._tree_readers == 0
def test_an_unmanaged_h3_native_run_takes_no_claim(monkeypatch, tmp_path):
"""A user-supplied sd-cli is one the installer cannot replace, so it must not be blocked
behind an unrelated managed install."""
pytest.importorskip("PIL.Image")
import core.inference.sd_cpp_backend as bk
outside = tmp_path / "mine" / "sd-cli"
outside.parent.mkdir(parents = True)
outside.write_bytes(b"my own build")
calls: list = []
backend = _h3_native_backend(monkeypatch, calls, binary = outside)
held: list = []
inner = backend._state.pipe.engine.generate_video
def _watching(files, params, **kwargs):
held.append(bk._tree_readers)
return inner(files, params, **kwargs)
backend._state.pipe.engine.generate_video = _watching
monkeypatch.setattr(bk, "_sd_cpp_backend", None)
backend.generate(prompt = "p", width = 960, height = 544)
assert held == [0]
def test_an_in_place_binary_swap_stops_the_h3_run(monkeypatch, tmp_path):
"""Existence is not identity: a binary swapped in place must fail the run, not be accepted."""
pytest.importorskip("PIL.Image")
import contextlib
import os
import core.inference.sd_cpp_backend as bk
managed = _shared_setup_4(monkeypatch, tmp_path)
managed.write_bytes(b"the build the load checked")
calls: list = []
backend = _h3_native_backend(monkeypatch, calls, binary = managed)
monkeypatch.setattr(bk, "_sd_cpp_backend", None)
backend.generate(prompt = "p", width = 960, height = 544)
assert len(calls) == 1
# Compare against the load-time value: two reads now would agree.
managed.write_bytes(b"some other accelerator's build")
os.utime(managed, (1, 1))
with pytest.raises(RuntimeError, match = "Reload the model"):
backend.generate(prompt = "p", width = 960, height = 544)
assert len(calls) == 1, "the run must not reach a build the load never checked"
# A replacement that lands DURING the wait is caught the same way.
@contextlib.contextmanager
def _install_lands_during_the_wait(
_binary,
_cancel = None,
_msg = None,
):
managed.write_bytes(b"yet another build")
os.utime(managed, (2, 2))
yield
backend = _h3_native_backend(monkeypatch, calls, binary = managed)
monkeypatch.setattr(bk, "_tree_reader", _install_lands_during_the_wait)
with pytest.raises(RuntimeError, match = "Reload the model"):
backend.generate(prompt = "p", width = 960, height = 544)
assert len(calls) == 1
def test_a_cancelled_h3_install_wait_reads_as_a_cancellation(monkeypatch, tmp_path):
"""The reader is shared with the image path, whose sentinel _run_generate does not recognise.
Left untranslated, an ordinary H3 cancellation surfaces as "Video generation failed"."""
pytest.importorskip("PIL.Image")
import threading
import core.inference.sd_cpp_backend as bk
from core.inference.video_families import VIDEO_CANCELLED_MSG
managed = _shared_setup_4(monkeypatch, tmp_path)
managed.write_bytes(b"managed")
calls: list = []
backend = _h3_native_backend(monkeypatch, calls, binary = managed)
monkeypatch.setattr(bk, "_sd_cpp_backend", None)
monkeypatch.setattr(bk, "_tree_installing", True)
monkeypatch.setattr(bk, "_TREE_WAIT_TICK_S", 0.02)
threading.Timer(0.1, lambda: backend.cancel_generate()).start()
with pytest.raises(RuntimeError) as exc:
backend.generate(prompt = "p", width = 960, height = 544)
assert str(exc.value) == VIDEO_CANCELLED_MSG
assert calls == []
# The unified-memory refusal must read the plan the load will actually take.
def _fp32_promoted_cuda_target(monkeypatch):
"""A CUDA target whose fp16 promotes to fp32, i.e. dtype_scale == 2 in the video planner."""
import torch
import core.inference.video as video_mod
from core.inference.diffusion_device import DiffusionDeviceTarget
target = DiffusionDeviceTarget(
device = "cuda",
dtype = torch.float16,
backend = "cuda",
vendor = "nvidia",
supports_model_cpu_offload = True,
supports_default_torch_compile = False,
supports_pinned_transfer = True,
)
monkeypatch.setattr(video_mod, "resolve_diffusion_device_target", lambda: target)
return target
def test_the_fp32_promotion_does_not_double_an_already_fp32_wan_vae(fake_runtime, monkeypatch):
# Wan's VAE is already fp32 and pinned, so the bf16 promotion must not double it.
from core.inference.diffusion_fp16_guard import FP16_GUARD_ENV
from core.inference.video_families import detect_video_family
# TI2V-5B keeps fp16 by default (fp16_guard "native"); the kill switch restores the promotion under test.
monkeypatch.setenv(FP16_GUARD_ENV, "0")
_fp32_promoted_cuda_target(monkeypatch)
transformer_gb, te_gb, vae_gb = detect_video_family(
"Wan-AI/Wan2.2-TI2V-5B-Diffusers"
).bf16_components_gb
calls = _capture_plan(monkeypatch)
VideoBackend().load_pipeline("Wan-AI/Wan2.2-TI2V-5B-Diffusers", model_kind = "pipeline")
# bf16 terms doubled, the fp32 VAE term left exactly where the table put it.
assert calls[0]["model_dense_mib"] == int(
((transformer_gb + te_gb) * 2.0 + vae_gb) * _MIB_PER_GB
)
def test_fp16_native_wan_is_planned_at_fp16_size(fake_runtime, monkeypatch):
# On an fp16-only card TI2V-5B now stays fp16, so the plan prices the bf16-sized table as is (no doubling).
from core.inference.diffusion_fp16_guard import FP16_GUARD_ENV
from core.inference.video_families import detect_video_family
monkeypatch.delenv(FP16_GUARD_ENV, raising = False)
_fp32_promoted_cuda_target(monkeypatch)
components = detect_video_family("Wan-AI/Wan2.2-TI2V-5B-Diffusers").bf16_components_gb
calls = _capture_plan(monkeypatch)
VideoBackend().load_pipeline("Wan-AI/Wan2.2-TI2V-5B-Diffusers", model_kind = "pipeline")
assert calls[0]["model_dense_mib"] == int(sum(components) * _MIB_PER_GB)
def test_the_fp32_promotion_still_doubles_a_bf16_vae(fake_runtime, monkeypatch):
# LTX-2 does not force fp32, so its VAE term IS a bf16 one and must keep scaling with the rest.
from core.inference.video_families import detect_video_family
_fp32_promoted_cuda_target(monkeypatch)
components = detect_video_family("Lightricks/LTX-2").bf16_components_gb
calls = _capture_plan(monkeypatch)
VideoBackend().load_pipeline("Lightricks/LTX-2", model_kind = "pipeline")
assert calls[0]["model_dense_mib"] == int(sum(components) * 2.0 * _MIB_PER_GB)
def test_unified_memory_refuses_on_the_dense_peak_even_when_a_quant_is_requested(
fake_runtime, monkeypatch
):
"""Refuse on the dense peak: video builds the transformer dense before quantizing in place."""
import torch
import core.inference.video as video_mod
from core.inference.diffusion_device import DiffusionDeviceTarget
from core.inference.diffusion_memory import DeviceMemory
target = DiffusionDeviceTarget(
device = "cuda",
dtype = torch.bfloat16,
backend = "cuda",
vendor = "nvidia",
supports_model_cpu_offload = True,
supports_default_torch_compile = False,
supports_pinned_transfer = True,
)
monkeypatch.setattr(video_mod, "resolve_diffusion_device_target", lambda: target)
monkeypatch.setattr(video_mod, "dense_transformer_supported", lambda t: True)
monkeypatch.setattr(
video_mod, "select_transformer_quant_scheme", lambda t, q, family = None, **_kw: "fp8"
)
# Integrated CUDA, 48 GiB shared: dense LTX-2 (~65 GB) cannot fit, but fp8 steady would.
total = 48 * 1024
monkeypatch.setattr(
video_mod,
"settled_snapshot_device_memory",
lambda t: DeviceMemory("cuda", "cuda", "unified_memory", int(total * 0.80), total),
)
with pytest.raises(RuntimeError) as excinfo:
VideoBackend().load_pipeline(
"Lightricks/LTX-2", model_kind = "pipeline", transformer_quant = "auto"
)
assert "unified memory" in str(excinfo.value)
def test_unified_memory_refuses_the_h3_modular_load_before_load_components(
fake_runtime, monkeypatch
):
"""H3's modular path skipped the unified-memory refusal, so it must refuse before load_components."""
import core.inference.video as video_mod
from core.inference.diffusion_device import DiffusionDeviceTarget
torch = sys.modules["torch"]
diffusers = sys.modules["diffusers"]
diffusers.ComponentsManager = _FakeComponentsManager
diffusers.ModularPipeline = _FakeModularPipeline
_FakeModularPipeline.instance = None
target = DiffusionDeviceTarget(
device = "mps",
dtype = torch.bfloat16,
backend = "mps",
vendor = "apple",
supports_model_cpu_offload = True,
supports_default_torch_compile = False,
supports_pinned_transfer = False,
)
monkeypatch.setattr(video_mod, "resolve_diffusion_device_target", lambda: target)
monkeypatch.setattr(video_mod, "settled_snapshot_device_memory", _unified_snapshot(128))
fam = _detect_load_family("MiniMaxAI/MiniMax-H3", None, "minimax-h3")
backend = VideoBackend()
with pytest.raises(RuntimeError) as excinfo:
backend._load_h3_modular_pipeline(
diffusers = diffusers,
torch = torch,
fam = fam,
repo_id = "MiniMaxAI/MiniMax-H3",
base = fam.base_repo,
kind = "pipeline",
dtype = torch.bfloat16,
device = "mps",
hf_token = None,
memory_mode = None,
target = target,
)
message = str(excinfo.value)
assert "minimax-h3" in message and "unified memory" in message
assert _FakeModularPipeline.instance is not None
assert _FakeModularPipeline.instance.load_kwargs is None
assert backend.status()["loaded"] is False
def test_the_h3_modular_refusal_prices_a_seeded_prequant_denoiser(fake_runtime, monkeypatch):
"""A hosted pre-quantized denoiser replaces the dense 66.3 GB one, so the refusal must price it,
not the dense figure; the encoder and VAEs stay dense."""
import core.inference.video as video_mod
from core.inference.video_families import detect_video_family
fam = detect_video_family("MiniMaxAI/MiniMax-H3")
transformer_gb, te_gb, vae_gb = fam.bf16_components_gb
seen: list[int] = []
def _capture(*, model_dense_mib = None, **kwargs):
seen.append(int(model_dense_mib or 0))
return types.SimpleNamespace(offload_policy = "none", estimates = {}, device_memory = None)
monkeypatch.setattr(video_mod, "plan_diffusion_memory", _capture)
monkeypatch.setattr(video_mod, "settled_snapshot_device_memory", lambda t: None)
monkeypatch.setattr(video_mod, "raise_on_unified_memory_shortfall", lambda *a, **k: None)
# The MEASURED hosted size: H3 checkpoints are pruned, so the 0.55 factor overstates by 16 GB.
assert fam.prequant_resident_gb == 20.3
for scheme, expected_transformer in (
(None, transformer_gb),
("fp8", fam.prequant_resident_gb),
("int8", fam.prequant_resident_gb),
# Unknown scheme: the hosted size if published, else the generic factor as fallback.
("bogus", fam.prequant_resident_gb),
):
VideoBackend._raise_on_modular_unified_shortfall(
fam,
target = None,
dtype = sys.modules["torch"].bfloat16,
device = "mps",
memory_mode = None,
scheme = scheme,
)
assert seen[-1] == int(
(expected_transformer + te_gb + vae_gb) * (1000.0**3 / (1024.0 * 1024.0))
), scheme
# A unified host that fits ~20.3 GB but not the factor's 36.5 GB must not refuse fp8.
from core.inference.diffusion_memory import unified_memory_shortfall_message
from core.inference.diffusion_memory import (
DeviceMemory,
estimate_video_runtime_mib,
plan_diffusion_memory,
)
mib_per_gb = 1000.0**3 / (1024.0 * 1024.0)
total = 160 * 1024
memory = DeviceMemory("mps", "mps", "unified_memory", int(total * 0.80), total)
device = type("T", (), {"supports_model_cpu_offload": True, "device": "mps"})()
headroom = estimate_video_runtime_mib(
width = fam.resolution_presets[0][0],
height = fam.resolution_presets[0][1],
num_frames = fam.default_num_frames,
)
for gb, refused in (
(fam.prequant_resident_gb + te_gb + vae_gb, False),
# What the generic 0.55 factor would have budgeted: refused, for 16 GB that do not exist.
(transformer_gb * 0.55 + te_gb + vae_gb, True),
(sum(fam.bf16_components_gb), True),
):
plan = plan_diffusion_memory(
target = device,
device_memory = memory,
model_dense_mib = int(gb * mib_per_gb),
runtime_headroom_mib = headroom,
)
assert (unified_memory_shortfall_message(plan, family = fam.name) is not None) is refused, gb
def test_the_h3_modular_refusal_reruns_when_the_prequant_checkpoint_does_not_land(
fake_runtime, monkeypatch
):
"""A hosted denoiser that fails to land must rerun the memory refusal against the dense size."""
import core.inference.video as video_mod
from core.inference.diffusion_device import DiffusionDeviceTarget
torch = sys.modules["torch"]
diffusers = sys.modules["diffusers"]
diffusers.ComponentsManager = _FakeComponentsManager
diffusers.ModularPipeline = _FakeModularPipeline
diffusers.MiniMaxH3Transformer3DModel = _FakeTransformer
_FakeModularPipeline.instance = None
target = DiffusionDeviceTarget(
device = "mps",
dtype = torch.bfloat16,
backend = "mps",
vendor = "apple",
supports_model_cpu_offload = True,
supports_default_torch_compile = False,
supports_pinned_transfer = False,
)
monkeypatch.setattr(video_mod, "resolve_diffusion_device_target", lambda: target)
# 160 GiB: the prequant pick fits, the dense component set does not.
monkeypatch.setattr(video_mod, "settled_snapshot_device_memory", _unified_snapshot(160))
fam = _detect_load_family("MiniMaxAI/MiniMax-H3", None, "minimax-h3")
sized: list = []
real = VideoBackend._raise_on_modular_unified_shortfall
def _spy(family, **kwargs):
sized.append(kwargs["scheme"])
return real(family, **kwargs)
monkeypatch.setattr(VideoBackend, "_raise_on_modular_unified_shortfall", staticmethod(_spy))
# The checkpoint resolves but does not load: exactly the best-effort None contract.
import core.inference.diffusion_prequant as prequant_mod
monkeypatch.setattr(
prequant_mod,
"resolve_prequant_source",
lambda fam, scheme, base_repo = None, task = None: types.SimpleNamespace(
location = "unsloth/H3-FP8"
),
)
monkeypatch.setattr(prequant_mod, "load_prequantized_transformer", lambda *a, **k: None)
with pytest.raises(RuntimeError) as excinfo:
VideoBackend()._load_h3_modular_pipeline(
diffusers = diffusers,
torch = torch,
fam = fam,
repo_id = "MiniMaxAI/MiniMax-H3",
base = fam.base_repo,
kind = "pipeline",
dtype = torch.bfloat16,
device = "mps",
hf_token = None,
memory_mode = None,
transformer_quant = "fp8",
target = target,
)
assert "minimax-h3" in str(excinfo.value) and "unified memory" in str(excinfo.value)
# Sized twice: once for the pick that was requested, once for what actually landed.
assert sized == ["fp8", None]
assert _FakeModularPipeline.instance.load_kwargs is None
def test_generation_in_flight_tracks_a_background_job(fake_runtime, tmp_path, monkeypatch):
backend, video_mod = _shared_setup_1(tmp_path)
monkeypatch.setattr(video_mod, "_backend", backend)
rendering = threading.Event()
release = threading.Event()
inside = {}
def _block(
self,
*,
cancel_event = None,
**gen_kwargs,
):
inside["in_flight"] = video_mod.generation_in_flight()
rendering.set()
release.wait(10)
raise ValueError("stopped after the probe")
monkeypatch.setattr(VideoBackend, "generate", _block)
assert video_mod.generation_in_flight() is False
backend.begin_generate(prompt = "a clip")
assert rendering.wait(10), "the generate worker never started"
assert (
video_mod.generation_in_flight() is True
), "liveness cannot tell this backend from a dead one while it renders a clip"
assert inside["in_flight"] is True
release.set()
deadline = time.monotonic() + 10
while backend.generate_progress()["active"] and time.monotonic() < deadline:
time.sleep(0.01)
assert video_mod.generation_in_flight() is False, (
"the marker stayed lit after the job ended, so the watchdog would hold the widened "
"budget against a backend that really did hang"
)
def test_generation_in_flight_never_builds_a_backend(fake_runtime, monkeypatch):
import core.inference.video as video_mod
monkeypatch.setattr(video_mod, "_backend", None)
monkeypatch.setattr(
video_mod,
"VideoBackend",
lambda *a, **k: pytest.fail("liveness constructed a video backend"),
)
assert video_mod.generation_in_flight() is False
def _video_result(tag: str) -> dict:
"""The result shape _run_generate_body persists; tag identifies which job produced it."""
return {
"mp4_bytes": tag.encode(),
"negative_prompt": None,
"width": 64,
"height": 64,
"num_frames": 9,
"fps": 8,
"duration_s": 1.0,
"steps": 2,
"guidance": 1.0,
"seed": 1,
"has_audio": False,
"conditioning": "t2v",
"flow_shift": None,
"audio_flow_shift": None,
"repo_id": "test/model",
}
def _until(predicate, timeout = 10.0):
deadline = time.monotonic() + timeout
while time.monotonic() < deadline:
if predicate():
return True
time.sleep(0.005)
return False
def test_a_worker_that_never_started_does_not_hold_the_job_open(
fake_runtime, tmp_path, monkeypatch
):
"""A failed spawn must release begin_generate's slot, or generate stays refused for the session."""
backend, video_mod = _shared_setup_1(tmp_path)
monkeypatch.setattr(video_mod, "_backend", backend)
real_start = threading.Thread.start
monkeypatch.setattr(
threading.Thread,
"start",
lambda self: (_ for _ in ()).throw(RuntimeError("can't start new thread")),
)
with pytest.raises(RuntimeError, match = "can't start new thread"):
backend.begin_generate(prompt = "a clip")
assert video_mod.generation_in_flight() is False
assert backend._active_generate_cancel is None
progress = backend.generate_progress()
assert progress["active"] is False, "progress stayed queued for a job that never ran"
monkeypatch.setattr(threading.Thread, "start", real_start)
monkeypatch.setattr(backend, "generate", lambda **kw: _video_result("second"))
from core.inference import video_gallery
monkeypatch.setattr(video_gallery, "save", lambda data, meta: {"id": "second"})
backend.begin_generate(prompt = "second")
assert _until(lambda: not video_mod.generation_in_flight())
assert backend.generate_progress()["phase"] == "completed"
@pytest.mark.filterwarnings("ignore::pytest.PytestUnhandledThreadExceptionWarning")
def test_a_worker_killed_outright_does_not_hold_the_job_open(fake_runtime, tmp_path, monkeypatch):
"""The worker names ValueError, RuntimeError and Exception, so SystemExit and KeyboardInterrupt
unwound past every terminal path and left the marker lit; unload() does not clear it."""
backend, video_mod = _shared_setup_1(tmp_path)
monkeypatch.setattr(video_mod, "_backend", backend)
entered = threading.Event()
def _die(
self,
*,
cancel_event = None,
**gen_kwargs,
):
entered.set()
raise SystemExit("worker killed")
monkeypatch.setattr(VideoBackend, "generate", _die)
backend.begin_generate(prompt = "a clip")
assert entered.wait(10), "the generate worker never started"
assert _until(lambda: not video_mod.generation_in_flight()), (
"the marker outlived the worker, so liveness reports this backend as rendering "
"for the rest of the process"
)
assert backend.generate_progress()["active"] is False
def test_a_finished_job_cannot_finalise_the_one_that_replaced_it(
fake_runtime, tmp_path, monkeypatch
):
"""The backstop must key on the job's own token, not the busy flag, which a successor holds."""
import core.inference.video as video_mod
from core.inference import video_gallery
from core.inference.video_families import VIDEO_GENERATION_BUSY_MSG
backend = VideoBackend()
_load_gguf(backend, tmp_path)
monkeypatch.setattr(video_mod, "_backend", backend)
monkeypatch.setattr(video_gallery, "save", lambda data, meta: {"id": data.decode()})
second_running = threading.Event()
release_second = threading.Event()
calls = []
def _generate(*, cancel_event, **gen_kwargs):
calls.append(1)
if len(calls) == 1:
return _video_result("one")
second_running.set()
assert release_second.wait(10)
return _video_result("two")
monkeypatch.setattr(backend, "generate", _generate)
first_published = threading.Event()
release_first = threading.Event()
backstop_ran = threading.Event()
real_finish = backend._finish_generate_job
def _gated_finish(**kwargs):
# Hold job one between publishing its outcome and backstop, where job two reserves.
if (kwargs.get("video") or {}).get("id") == "one":
real_finish(**kwargs)
first_published.set()
assert release_first.wait(10)
return
real_finish(**kwargs)
if kwargs.get("error") == "Video generation failed." and first_published.is_set():
backstop_ran.set()
monkeypatch.setattr(backend, "_finish_generate_job", _gated_finish)
backend.begin_generate(prompt = "one")
assert first_published.wait(10)
backend.begin_generate(prompt = "two")
assert second_running.wait(10)
assert video_mod.generation_in_flight() is True
release_first.set()
assert backstop_ran.wait(10), "the first job's backstop never ran"
assert video_mod.generation_in_flight() is True, (
"the finished job cleared the running job's marker; liveness now calls a rendering "
"backend idle, which is the failure this marker exists to prevent"
)
assert backend.generate_progress()["active"] is True
with pytest.raises(RuntimeError, match = VIDEO_GENERATION_BUSY_MSG):
backend.begin_generate(prompt = "three")
release_second.set()
assert _until(lambda: not video_mod.generation_in_flight())
progress = backend.generate_progress()
assert progress["phase"] == "completed"
assert progress["video"]["id"] == "two", "the running job lost its own outcome"
def test_the_backstop_leaves_a_cancelled_job_reported_as_cancelled(
fake_runtime, tmp_path, monkeypatch
):
"""Cancellation is a RuntimeError carrying a sentinel the route maps to its own status.
A backstop that overwrote it would turn every cancel into a generic failure."""
backend, video_mod = _shared_setup_1(tmp_path)
monkeypatch.setattr(video_mod, "_backend", backend)
entered = threading.Event()
def _wait_for_cancel(*, cancel_event, **gen_kwargs):
entered.set()
assert cancel_event.wait(10)
raise RuntimeError(VIDEO_CANCELLED_MSG)
monkeypatch.setattr(backend, "generate", _wait_for_cancel)
backend.begin_generate(prompt = "cancel me")
assert entered.wait(10)
backend.cancel_generate()
assert _until(lambda: not video_mod.generation_in_flight())
progress = backend.generate_progress()
assert progress["phase"] == "failed"
assert progress["error"] == VIDEO_CANCELLED_MSG
# The backstop runs after the body returns; give it room to prove it changed nothing.
time.sleep(0.1)
assert backend.generate_progress()["error"] == VIDEO_CANCELLED_MSG
def test_an_interrupted_spawn_leaves_a_live_worker_its_reservation(
fake_runtime, tmp_path, monkeypatch
):
"""An interrupt inside Thread.start() must keep the reservation: the worker is already running."""
backend, video_mod = _shared_setup_1(tmp_path)
monkeypatch.setattr(video_mod, "_backend", backend)
rendering = threading.Event()
release = threading.Event()
def _hold(*, cancel_event = None, **gen_kwargs):
rendering.set()
assert release.wait(10)
return _video_result("held")
monkeypatch.setattr(backend, "generate", _hold)
from core.inference import video_gallery
monkeypatch.setattr(video_gallery, "save", lambda data, meta: {"id": "held"})
real_start = threading.Thread.start
def _start_then_interrupt(self):
real_start(self)
raise KeyboardInterrupt("signal delivered while waiting on the child")
monkeypatch.setattr(threading.Thread, "start", _start_then_interrupt)
with pytest.raises(KeyboardInterrupt):
backend.begin_generate(prompt = "a clip")
assert rendering.wait(10), "the worker never started"
assert video_mod.generation_in_flight() is True, (
"the interrupted spawn retired a running render's reservation, so liveness reports "
"this backend as idle while it renders"
)
assert backend._active_generate_cancel is not None, "the running job lost its cancel handle"
monkeypatch.setattr(threading.Thread, "start", real_start)
with pytest.raises(RuntimeError, match = "already in progress"):
backend.begin_generate(prompt = "second")
release.set()
assert _until(lambda: not video_mod.generation_in_flight())
assert backend.generate_progress()["phase"] == "completed"
def test_a_direct_worker_call_keeps_the_outcome_it_recorded(fake_runtime, tmp_path, monkeypatch):
"""_run_generate can run unreserved, finalising with the backstop's token, which must not
overwrite the recorded outcome."""
import core.inference.video as video_mod
from core.inference import video_gallery
backend = VideoBackend()
_load_gguf(backend, tmp_path)
monkeypatch.setattr(video_mod, "_backend", backend)
monkeypatch.setattr(video_gallery, "save", lambda data, meta: {"id": "direct"})
monkeypatch.setattr(backend, "generate", lambda **kw: _video_result("direct"))
backend._run_generate(cancel_event = threading.Event(), prompt = "a clip")
progress = backend.generate_progress()
assert (
progress["phase"] == "completed"
), f"a direct call recorded {progress['phase']!r}; the backstop overwrote its result"
assert progress["video"]["id"] == "direct"
def test_a_direct_worker_call_keeps_its_cancellation(fake_runtime, tmp_path, monkeypatch):
"""Same path, the outcome that matters most: a cancellation carries a sentinel the route
maps to its own status, and turning it into a generic failure loses that."""
backend, video_mod = _shared_setup_1(tmp_path)
monkeypatch.setattr(video_mod, "_backend", backend)
def _cancelled(**kwargs):
raise RuntimeError(VIDEO_CANCELLED_MSG)
monkeypatch.setattr(backend, "generate", _cancelled)
backend._run_generate(cancel_event = threading.Event(), prompt = "a clip")
progress = backend.generate_progress()
assert progress["phase"] == "failed"
assert (
progress["error"] == VIDEO_CANCELLED_MSG
), f"a direct call reported {progress['error']!r} instead of the cancellation sentinel"
def test_cuda_graph_is_a_per_family_opt_in():
"""No video family opts into CUDA graphs: each is GPU-bound, so capture costs VRAM for no gain."""
from core.inference.video_families import _FAMILIES, detect_video_family
h3 = detect_video_family("MiniMaxAI/MiniMax-H3")
assert h3 is not None and h3.name == "minimax-h3"
assert h3.supports_cuda_graph is False
wan = detect_video_family("Wan-AI/Wan2.2-TI2V-5B-Diffusers")
assert wan is not None and wan.name == "wan2.2-ti2v-5b"
assert wan.supports_cuda_graph is False
opted_in = [f.name for f in _FAMILIES if f.supports_cuda_graph]
assert opted_in == [], f"{opted_in} opts into CUDA graphs with no measurement on record"
# Offloaded denoisers: the replay records onloads; each opt-in has a measurement.
offloaded = sorted(f.name for f in _FAMILIES if f.offload_cuda_graph)
assert offloaded == sorted(OFFLOAD_GRAPH_FAMILIES), offloaded
assert (
h3.offload_cuda_graph is False
) # streamed H3 onloads with host waits; a graph cannot record them
assert "GPU-bound" in h3.cuda_graph_decline and "wait on the host" in h3.cuda_graph_decline
OFFLOAD_GRAPH_FAMILIES = ("wan2.2-ti2v-5b", "hunyuanvideo-1.5")
def test_h3_modular_load_arms_a_deferred_graph_after_placement():
"""A forced H3 graph is deferred to placement by apply_speed_optims; the modular load must arm it (or record why
it stays eager). Without the call the status read "off: armed after placement" for the whole load."""
import ast
import textwrap
src = textwrap.dedent(inspect.getsource(video_module.VideoBackend._load_h3_modular_pipeline))
calls = [
node
for node in ast.walk(ast.parse(src))
if isinstance(node, ast.Call)
and getattr(node.func, "id", None) == "arm_graphs_after_placement"
]
assert calls and isinstance(calls[0].args[0], ast.Name) and calls[0].args[0].id == "speed_view"
speed = src.index("applied = autoopt.run_speed_layer(")
arm = src.index("arm_graphs_after_placement(")
status = src.index('"cuda_graph": (')
assert (
speed < arm < status
) # after the deferring speed pass, before the resolved record reads the reason
def test_every_rebuilt_speed_target_carries_the_backend():
"""The CUDA-graph arm refuses ROCm by target.backend, which ROCm reports as device "cuda"."""
import ast
from pathlib import Path
source = Path(__file__).resolve().parents[1] / "core" / "inference" / "video.py"
tree = ast.parse(source.read_text(encoding = "utf-8"))
rebuilt = []
for node in ast.walk(tree):
if not isinstance(node, ast.Call) or getattr(node.func, "id", None) != "apply_speed_optims":
continue
for arg in node.args:
if isinstance(arg, ast.Call) and getattr(arg.func, "attr", None) == "SimpleNamespace":
rebuilt.append(arg)
assert rebuilt
for call in rebuilt:
fields = {kw.arg for kw in call.keywords}
assert "backend" in fields, f"video.py:{call.lineno} target lacks backend: {sorted(fields)}"
def test_h3_speed_optims_get_the_denoisers_own_placement():
"""A denoiser pinned under H3's offload policy must not read as offloaded."""
import ast
from pathlib import Path
source = Path(__file__).resolve().parents[1] / "core" / "inference" / "video.py"
text = source.read_text(encoding = "utf-8")
tree = ast.parse(text)
h3 = next(
n
for n in ast.walk(tree)
if isinstance(n, ast.FunctionDef) and n.name == "_load_h3_modular_pipeline"
)
calls = [
n
for n in ast.walk(h3)
if isinstance(n, ast.Call) and getattr(n.func, "id", None) == "apply_speed_optims"
]
assert len(calls) == 1
kw = {k.arg: k.value for k in calls[0].keywords}
assert "denoiser_offloaded" in kw
expr = ast.unparse(kw["denoiser_offloaded"])
names = {n.id for n in ast.walk(kw["denoiser_offloaded"]) if isinstance(n, ast.Name)}
assert (
{"denoiser_pinned", "denoiser_streamed"}
<= names
<= {"denoiser_pinned", "denoiser_streamed", "bool"}
), expr
for pinned, streamed, offloaded in (
(True, None, False),
(True, "group", True),
(False, None, True),
):
got = eval(
compile(ast.Expression(kw["denoiser_offloaded"]), "<h3>", "eval"),
{"bool": bool},
{"denoiser_pinned": pinned, "denoiser_streamed": streamed},
)
assert bool(got) is offloaded, (expr, pinned, streamed)
installs = [
n
for n in ast.walk(h3)
if isinstance(n, ast.Call) and getattr(n.func, "id", None) == "install_int8_gemm"
]
assert len(installs) == 1 and "device" in {k.arg for k in installs[0].keywords}
class _GraphHandle:
"""Stands in for a captured denoiser graph: only reset() matters to generate()."""
def __init__(self):
self.resets = 0
def reset(self):
self.resets += 1
return self
def test_h3_generate_oom_drops_the_graphs_before_raising(fake_runtime):
"""H3 is the one video family that captures graphs; an OOM must not leave them pinned."""
backend = VideoBackend()
pipe = _load_h3_modular(backend)
handle = _GraphHandle()
pipe._unsloth_cuda_graphs = (handle,)
def _oom(_n):
raise RuntimeError("CUDA out of memory. Tried to allocate 1.70 GiB")
pipe.scheduler.on_step = _oom
with pytest.raises(RuntimeError, match = "out of memory"):
backend.generate(prompt = "a fox", steps = 4)
assert handle.resets == 1, "the graphs stayed pinned across the raise"
def test_h3_generate_non_oom_error_leaves_the_graphs_alone(fake_runtime):
"""Only an OOM justifies throwing away working graphs; a bad shape does not."""
backend = VideoBackend()
pipe = _load_h3_modular(backend)
handle = _GraphHandle()
pipe._unsloth_cuda_graphs = (handle,)
def _boom(_n):
raise RuntimeError("shape mismatch")
pipe.scheduler.on_step = _boom
with pytest.raises(RuntimeError, match = "shape mismatch"):
backend.generate(prompt = "a fox", steps = 4)
assert handle.resets == 0
def _stub_denoiser_seed(
monkeypatch,
*,
scheme = "nvfp4",
components = ("transformer", "transformer_2"),
seeded = True,
repo = "unsloth/Wan2.2-T2V-A14B-NVFP4",
plan_scheme = "nvfp4",
):
"""Stub the whole seeding route: plan-time scheme, registry lookup and checkpoint load."""
import core.inference.video as video_mod
import core.inference.video_denoiser_prequant as dq
if plan_scheme is not None:
monkeypatch.setattr(video_mod, "_video_auto_denoiser_scheme", lambda fam, **kw: plan_scheme)
source = types.SimpleNamespace(
kind = "repo", location = repo, filename = "x.pt", fallback_filename = None
)
monkeypatch.setattr(
dq, "denoiser_prequant_sources", lambda fam, s, base, **_: {c: source for c in components}
)
modules = {c: object() for c in components}
calls = []
def _fake_pipe_kwargs(fam, base, **kwargs):
calls.append({"base": base, **kwargs})
return dict(modules) if seeded else {}
monkeypatch.setattr(dq, "denoiser_prequant_pipe_kwargs", _fake_pipe_kwargs)
return calls, modules
def test_wan_a14b_prequant_seeds_both_dits_instead_of_quantising_them(fake_runtime, monkeypatch):
"""The prequant twin of ``test_wan_a14b_dense_quant_applies_to_both_dits``."""
import core.inference.video as video_mod
monkeypatch.setattr(video_mod, "dense_transformer_supported", lambda target: True)
quantised = []
def _fake_quant(
view,
target,
*,
mode,
family,
logger = None,
):
quantised.append(view.transformer)
return "int8"
monkeypatch.setattr(video_mod, "quantize_transformer", _fake_quant)
calls, modules = _stub_denoiser_seed(monkeypatch)
backend = VideoBackend()
status = backend.load_pipeline(
"Wan-AI/Wan2.2-T2V-A14B-Diffusers",
model_kind = "pipeline",
transformer_quant = "nvfp4",
)
assembled = _FakeWanPipelineSingle.last
assert assembled["transformer"] is modules["transformer"]
assert assembled["transformer_2"] is modules["transformer_2"]
assert quantised == [], "a seeded DiT must not be quantised again"
assert status["transformer_quant"] == "nvfp4"
resolved = status["resolved"]["transformer_quant"]
assert "unsloth/Wan2.2-T2V-A14B-NVFP4" in resolved["reason"]
assert resolved["requested"] == "nvfp4" and resolved["value"] == "nvfp4"
assert resolved["status"] == "applied"
assert calls and calls[0]["scheme"] == "nvfp4"
def test_a_checkpoint_that_will_not_load_falls_back_to_the_dense_quant(fake_runtime, monkeypatch):
import core.inference.video as video_mod
monkeypatch.setattr(video_mod, "dense_transformer_supported", lambda target: True)
quantised = []
def _fake_quant(
view,
target,
*,
mode,
family,
logger = None,
):
quantised.append(view.transformer)
return "nvfp4"
monkeypatch.setattr(video_mod, "quantize_transformer", _fake_quant)
_stub_denoiser_seed(monkeypatch, seeded = False)
backend = VideoBackend()
status = backend.load_pipeline(
"Wan-AI/Wan2.2-T2V-A14B-Diffusers",
model_kind = "pipeline",
transformer_quant = "nvfp4",
)
pipe = backend._state.pipe
assert quantised == [pipe.transformer, pipe.transformer_2]
assert status["transformer_quant"] == "nvfp4"
assert "unsloth/" not in status["resolved"]["transformer_quant"]["reason"]
def test_a_superseded_nvfp4_load_cannot_overwrite_the_install_reason(fake_runtime, monkeypatch):
# A superseded load returning from the install must not overwrite the newer load's reason.
import threading
import core.inference.video as video_mod
from core.inference import diffusion_nvfp4_install as inst
monkeypatch.setattr(video_mod, "dense_transformer_supported", lambda target: True)
monkeypatch.setattr(video_mod, "quantize_transformer", lambda *a, **k: "nvfp4")
_stub_denoiser_seed(monkeypatch, seeded = False)
old_entered, release_old = threading.Event(), threading.Event()
def _ensure(
device,
*,
logger = None,
local_files_only = False,
owner = None,
**kw,
):
if threading.current_thread() is not threading.main_thread():
old_entered.set()
assert release_old.wait(timeout = 10), "test never released the old load"
outcome = (False, "old load: flashinfer install refused")
else:
outcome = (True, "installed flashinfer for NVFP4")
inst.record_install_reason(owner, *outcome, device)
return outcome
monkeypatch.setattr(inst, "ensure_flashinfer_for_nvfp4", _ensure)
monkeypatch.setattr(
VideoBackend, "_nvfp4_denoiser_checkpoint_will_load", lambda self, *a, **k: True
)
inst.reset_install_state()
backend = VideoBackend()
kwargs = dict(model_kind = "pipeline", transformer_quant = "nvfp4")
old_exc = []
def _old_load():
try:
backend.load_pipeline("Wan-AI/Wan2.2-T2V-A14B-Diffusers", _load_token = 1, **kwargs)
except Exception as exc: # noqa: BLE001 - superseded by the newer load
old_exc.append(exc)
backend._load_token = 1
old = threading.Thread(target = _old_load)
old.start()
try:
assert old_entered.wait(timeout = 10), "old load never reached the FlashInfer install"
backend._load_token = 2
backend.load_pipeline("Wan-AI/Wan2.2-T2V-A14B-Diffusers", _load_token = 2, **kwargs)
committed = backend._state
assert inst._REASONS[backend][0] is None
finally:
release_old.set()
old.join(timeout = 10)
assert old_exc and "superseded" in str(old_exc[0])
assert backend._state is committed
assert inst._REASONS[backend][0] is None, "the superseded load relabelled the resident model"
inst.reset_install_state()
def test_an_on_the_fly_nvfp4_load_clears_the_previous_install_reason(fake_runtime, monkeypatch):
# A skipped install must still clear the previous model's reason.
import core.inference.video as video_mod
from core.inference import diffusion_nvfp4_install as inst
monkeypatch.setattr(video_mod, "dense_transformer_supported", lambda target: True)
monkeypatch.setattr(video_mod, "quantize_transformer", lambda *a, **k: "nvfp4")
_stub_denoiser_seed(monkeypatch, seeded = False)
def _ensure(*a, **k):
raise AssertionError("the gate should have skipped the install")
monkeypatch.setattr(inst, "ensure_flashinfer_for_nvfp4", _ensure)
monkeypatch.setattr(
VideoBackend, "_nvfp4_denoiser_checkpoint_will_load", lambda self, *a, **k: False
)
inst.reset_install_state()
backend = VideoBackend()
inst.record_install_reason(backend, False, "offline: flashinfer is not downloaded", 0)
backend.load_pipeline(
"Wan-AI/Wan2.2-T2V-A14B-Diffusers", model_kind = "pipeline", transformer_quant = "nvfp4"
)
assert inst._REASONS[backend][0] is None
assert (
inst.nvfp4_backend_fields("torchao", owner = backend)["transformer_quant_backend_reason"]
!= "offline: flashinfer is not downloaded"
)
inst.reset_install_state()
def test_seeding_is_skipped_entirely_under_offload(fake_runtime, monkeypatch):
import core.inference.video as video_mod
monkeypatch.setenv("UNSLOTH_DIFFUSION_ALLOW_PRECISION_FALLBACK", "1")
monkeypatch.setattr(video_mod, "dense_transformer_supported", lambda target: True)
monkeypatch.setattr(video_mod, "quantize_transformer", lambda *a, **k: None)
calls, _modules = _stub_denoiser_seed(monkeypatch)
real_plan = video_mod.plan_diffusion_memory
monkeypatch.setattr(
video_mod,
"plan_diffusion_memory",
lambda **kwargs: dataclasses.replace(real_plan(**kwargs), offload_policy = "model"),
)
_stub_apply_memory_plan(monkeypatch, video_mod)
backend = VideoBackend()
status = backend.load_pipeline(
"Wan-AI/Wan2.2-T2V-A14B-Diffusers",
model_kind = "pipeline",
transformer_quant = "nvfp4",
)
assert calls == [], "no checkpoint may be fetched for a load that cannot keep it resident"
assert status["transformer_quant"] is None
assert "moves the DiT" in status["resolved"]["transformer_quant"]["reason"]
@pytest.mark.parametrize("switch", [None, "0"])
def test_a_seed_declined_by_the_loads_own_offload_plan_reads_the_hosted_native_build(
fake_runtime, monkeypatch, switch
):
"""Probe prices the seed resident but the load's plan offloads it (LTX-2.5 sidecar encoder): read the hosted file."""
import core.inference.video as video_mod
if switch is not None:
monkeypatch.setenv(video_mod.OFFLOAD_HOSTED_READ_ENV, switch)
monkeypatch.setattr(video_mod, "dense_transformer_supported", lambda target: True)
monkeypatch.setattr(video_mod, "quantize_transformer", lambda *a, **k: "int8")
_stub_denoiser_seed(monkeypatch, scheme = "int8", plan_scheme = "int8")
real_plan = video_mod.plan_diffusion_memory
monkeypatch.setattr(
video_mod,
"plan_diffusion_memory",
lambda **kwargs: dataclasses.replace(real_plan(**kwargs), offload_policy = "model"),
)
_stub_apply_memory_plan(monkeypatch, video_mod)
monkeypatch.setattr(
video_mod, "_video_native_hosted_scheme", lambda fam, scheme, target: "int8"
)
monkeypatch.setattr(video_mod, "_video_native_cache_spec", lambda fam, **kw: {"scheme": "int8"})
monkeypatch.setattr(video_mod, "_read_native_quant_from_cache", lambda *a, **k: {})
monkeypatch.setattr(video_mod, "_video_native_stream_build", lambda *a, **k: {})
hosted_reads = []
monkeypatch.setattr(
video_mod, "_read_native_quant_from_hosted", lambda *a, **k: hosted_reads.append(k) or {}
)
# The fake target lacks a native int8 kernel, so the load refuses after the read.
with contextlib.suppress(RuntimeError):
VideoBackend().load_pipeline(
"Wan-AI/Wan2.2-T2V-A14B-Diffusers", model_kind = "pipeline", transformer_quant = "int8"
)
assert len(hosted_reads) == (0 if switch == "0" else 1)
def _plans_for(monkeypatch, video_mod):
"""Every ``model_dense_mib`` the memory planner was asked to judge, in order."""
real_plan = video_mod.plan_diffusion_memory
seen: list = []
def _record(**kwargs):
seen.append(kwargs.get("model_dense_mib"))
return real_plan(**kwargs)
monkeypatch.setattr(video_mod, "plan_diffusion_memory", _record)
return seen
def test_the_memory_plan_prices_a_seeded_denoiser_at_the_measured_row(fake_runtime, monkeypatch):
"""The memory plan prices a seeded denoiser at the measured row, not the dense term."""
import core.inference.video as video_mod
monkeypatch.setattr(video_mod, "dense_transformer_supported", lambda target: True)
monkeypatch.setattr(video_mod, "quantize_transformer", lambda *a, **k: None)
monkeypatch.setattr(video_mod, "video_family_prequant_resident_gb", lambda fam, scheme: 8.0)
_stub_denoiser_seed(monkeypatch)
seen = _plans_for(monkeypatch, video_mod)
backend = VideoBackend()
backend.load_pipeline(
"Wan-AI/Wan2.2-T2V-A14B-Diffusers",
model_kind = "pipeline",
transformer_quant = "nvfp4",
)
fam = _detect_load_family("Wan-AI/Wan2.2-T2V-A14B-Diffusers", None, None)
mib_per_gb = 1000.0**3 / (1024.0 * 1024.0)
companions = fam.bf16_components_gb[1] + fam.bf16_components_gb[2]
assert seen == [int((8.0 + companions) * mib_per_gb)]
assert seen[0] < int((fam.bf16_components_gb[0] + companions) * mib_per_gb)
def test_a_failed_seed_replans_at_bf16_and_refuses_again(fake_runtime, monkeypatch):
"""The artifact-sized budget is valid only once the checkpoint is in hand."""
import core.inference.video as video_mod
monkeypatch.setattr(video_mod, "dense_transformer_supported", lambda target: True)
monkeypatch.setattr(video_mod, "quantize_transformer", lambda *a, **k: "nvfp4")
monkeypatch.setattr(video_mod, "video_family_prequant_resident_gb", lambda fam, scheme: 8.0)
_stub_denoiser_seed(monkeypatch, seeded = False)
seen = _plans_for(monkeypatch, video_mod)
refusals: list = []
monkeypatch.setattr(
video_mod,
"raise_on_unified_memory_shortfall",
lambda plan, family = None, logger = None: refusals.append(
plan.model_dense_mib if hasattr(plan, "model_dense_mib") else None
),
)
backend = VideoBackend()
backend.load_pipeline(
"Wan-AI/Wan2.2-T2V-A14B-Diffusers",
model_kind = "pipeline",
transformer_quant = "nvfp4",
)
fam = _detect_load_family("Wan-AI/Wan2.2-T2V-A14B-Diffusers", None, None)
mib_per_gb = 1000.0**3 / (1024.0 * 1024.0)
companions = fam.bf16_components_gb[1] + fam.bf16_components_gb[2]
assert seen == [
int((8.0 + companions) * mib_per_gb),
int((fam.bf16_components_gb[0] + companions) * mib_per_gb),
]
assert len(refusals) == 2
def test_the_planned_scheme_is_what_the_load_seeds(fake_runtime, monkeypatch):
"""The scheme the plan committed to is the one the load seeds."""
import core.inference.video as video_mod
monkeypatch.setattr(video_mod, "dense_transformer_supported", lambda target: True)
monkeypatch.setattr(video_mod, "quantize_transformer", lambda *a, **k: None)
calls, _modules = _stub_denoiser_seed(monkeypatch, plan_scheme = None)
monkeypatch.setattr(video_mod, "_video_auto_denoiser_scheme", lambda fam, **kw: None)
backend = VideoBackend()
status = backend.load_pipeline(
"Wan-AI/Wan2.2-T2V-A14B-Diffusers",
model_kind = "pipeline",
transformer_quant = "nvfp4",
_video_auto_denoiser_planned = "nvfp4",
)
assert [c["scheme"] for c in calls] == ["nvfp4"]
assert status["transformer_quant"] == "nvfp4"
def test_a_seed_the_plan_declined_is_not_re_taken_by_the_load(fake_runtime, monkeypatch):
"""The load honours the plan's decline, or it would fetch the artifact inline."""
import core.inference.video as video_mod
monkeypatch.setattr(video_mod, "dense_transformer_supported", lambda target: True)
monkeypatch.setattr(video_mod, "quantize_transformer", lambda *a, **k: "nvfp4")
calls, _modules = _stub_denoiser_seed(monkeypatch, plan_scheme = None)
monkeypatch.setattr(video_mod, "_video_auto_denoiser_scheme", lambda fam, **kw: "nvfp4")
backend = VideoBackend()
status = backend.load_pipeline(
"Wan-AI/Wan2.2-T2V-A14B-Diffusers",
model_kind = "pipeline",
transformer_quant = "nvfp4",
_video_auto_denoiser_planned = video_mod.DENOISER_SEED_DECLINED,
)
assert calls == [], "a seed the plan declined may not be fetched inline by the load"
assert status["transformer_quant"] == "nvfp4"
assert "unsloth/" not in status["resolved"]["transformer_quant"]["reason"]
_A14B_SIBLINGS = [
_sibling("model_index.json", 10),
_sibling("transformer/config.json", 1),
_sibling("transformer/diffusion_pytorch_model-00001-of-00002.safetensors", 14),
_sibling("transformer/diffusion_pytorch_model-00002-of-00002.safetensors", 14),
_sibling("transformer_2/config.json", 1),
_sibling("transformer_2/diffusion_pytorch_model-00001-of-00002.safetensors", 14),
_sibling("transformer_2/diffusion_pytorch_model-00002-of-00002.safetensors", 14),
_sibling("text_encoder/model-00001-of-00001.safetensors", 11),
_sibling("vae/diffusion_pytorch_model.safetensors", 3),
_sibling("scheduler/scheduler_config.json", 1),
]
def test_base_download_files_drops_both_experts_and_keeps_both_configs():
"""A seeded MoE drops both experts' dense shards and keeps both configs."""
info = types.SimpleNamespace(siblings = _A14B_SIBLINGS)
dense = dict(VideoBackend._base_download_files(info, "pipeline"))
seeded = dict(
VideoBackend._base_download_files(
info,
"pipeline",
skip_transformer_weights = True,
skip_transformer_components = ("transformer", "transformer_2"),
)
)
assert not any(n.endswith(".safetensors") and n.startswith("transformer") for n in seeded)
assert seeded["transformer/config.json"] == 1
assert seeded["transformer_2/config.json"] == 1
assert seeded["text_encoder/model-00001-of-00001.safetensors"] == 11
assert sum(dense.values()) - sum(seeded.values()) == 56
def test_base_download_files_keeps_the_h3_partition_default():
info = types.SimpleNamespace(siblings = _H3_SIBLINGS)
references = dict(
VideoBackend._base_download_files(
info, "pipeline", skip_transformer_weights = True, h3_task = "ref2va"
)
)
assert not any(n.startswith("transformer_ref/diffusion_pytorch_model") for n in references)
assert "transformer_ref/config.json" in references
def test_the_download_plan_stages_both_experts_artifacts(monkeypatch):
"""The download plan stages both experts' artifacts."""
import core.inference.video as video_mod
import core.inference.video_denoiser_prequant as dq
_plan_api(
monkeypatch,
{
"Wan-AI/Wan2.2-T2V-A14B-Diffusers": [
_PlanSibling("model_index.json", 1000),
_PlanSibling("transformer/config.json", 1000),
_PlanSibling("transformer/diffusion_pytorch_model.safetensors", 28_000_000_000),
_PlanSibling("transformer_2/config.json", 1000),
_PlanSibling("transformer_2/diffusion_pytorch_model.safetensors", 28_000_000_000),
_PlanSibling("text_encoder/model-00001-of-00001.safetensors", 11_000_000_000),
_PlanSibling("vae/diffusion_pytorch_model.safetensors", 500_000_000),
],
"unsloth/Wan2.2-T2V-A14B-NVFP4": [
_PlanSibling("Wan2.2-T2V-A14B-NVFP4.safetensors", 8_000_000_000),
_PlanSibling("Wan2.2-T2V-A14B-transformer_2-NVFP4.safetensors", 8_100_000_000),
],
},
)
sources = {
"transformer": types.SimpleNamespace(
kind = "repo",
location = "unsloth/Wan2.2-T2V-A14B-NVFP4",
filename = "Wan2.2-T2V-A14B-NVFP4.safetensors",
fallback_filename = None,
),
"transformer_2": types.SimpleNamespace(
kind = "repo",
location = "unsloth/Wan2.2-T2V-A14B-NVFP4",
filename = "Wan2.2-T2V-A14B-transformer_2-NVFP4.safetensors",
fallback_filename = None,
),
}
monkeypatch.setattr(dq, "denoiser_prequant_sources", lambda fam, scheme, base, **_: sources)
monkeypatch.setattr(video_mod, "_video_auto_denoiser_scheme", lambda fam, **kw: "nvfp4")
monkeypatch.setattr(video_mod, "_video_seed_stays_resident", lambda fam, **kw: True)
plan = VideoBackend().download_plan(
"Wan-AI/Wan2.2-T2V-A14B-Diffusers",
model_kind = "pipeline",
transformer_quant = "nvfp4",
)
staged = {f for e in plan["entries"] for f in e["files"]}
assert "Wan2.2-T2V-A14B-NVFP4.safetensors" in staged
assert "Wan2.2-T2V-A14B-transformer_2-NVFP4.safetensors" in staged
assert not any(
f.endswith("diffusion_pytorch_model.safetensors") and f.startswith("transformer")
for f in staged
)
assert "transformer/config.json" in staged and "transformer_2/config.json" in staged
assert (
plan["required_bytes"]
== 8_000_000_000 + 8_100_000_000 + 1000 * 3 + 11_000_000_000 + 500_000_000
)
def test_an_explicit_scheme_under_speed_off_stages_the_hosted_experts(monkeypatch):
"""An EXPLICIT scheme under speed_mode="off" is still quantized, so the plan keeps its seed."""
import core.inference.video as video_mod
import core.inference.video_denoiser_prequant as dq
_plan_api(
monkeypatch,
{
"Wan-AI/Wan2.2-T2V-A14B-Diffusers": [
_PlanSibling("model_index.json", 1000),
_PlanSibling("transformer/config.json", 1000),
_PlanSibling("transformer/diffusion_pytorch_model.safetensors", 28_000_000_000),
_PlanSibling("transformer_2/config.json", 1000),
_PlanSibling("transformer_2/diffusion_pytorch_model.safetensors", 28_000_000_000),
_PlanSibling("text_encoder/model-00001-of-00001.safetensors", 11_000_000_000),
_PlanSibling("vae/diffusion_pytorch_model.safetensors", 500_000_000),
],
"unsloth/Wan2.2-T2V-A14B-NVFP4": [
_PlanSibling("Wan2.2-T2V-A14B-NVFP4.safetensors", 8_000_000_000),
_PlanSibling("Wan2.2-T2V-A14B-transformer_2-NVFP4.safetensors", 8_100_000_000),
],
},
)
sources = {
"transformer": types.SimpleNamespace(
kind = "repo",
location = "unsloth/Wan2.2-T2V-A14B-NVFP4",
filename = "Wan2.2-T2V-A14B-NVFP4.safetensors",
fallback_filename = None,
),
"transformer_2": types.SimpleNamespace(
kind = "repo",
location = "unsloth/Wan2.2-T2V-A14B-NVFP4",
filename = "Wan2.2-T2V-A14B-transformer_2-NVFP4.safetensors",
fallback_filename = None,
),
}
monkeypatch.setattr(dq, "denoiser_prequant_sources", lambda fam, scheme, base, **_: sources)
monkeypatch.setattr(
video_mod, "select_transformer_quant_scheme", lambda target, requested, **kw: requested
)
monkeypatch.setattr(video_mod, "_video_seed_stays_resident", lambda fam, **kw: True)
plan = VideoBackend().download_plan(
"Wan-AI/Wan2.2-T2V-A14B-Diffusers",
model_kind = "pipeline",
transformer_quant = "nvfp4",
speed_mode = "off",
)
staged = {f for e in plan["entries"] for f in e["files"]}
assert "transformer/diffusion_pytorch_model.safetensors" not in staged
assert "transformer_2/diffusion_pytorch_model.safetensors" not in staged
assert {
"Wan2.2-T2V-A14B-NVFP4.safetensors",
"Wan2.2-T2V-A14B-transformer_2-NVFP4.safetensors",
} <= staged
def test_the_video_status_response_carries_the_nvfp4_backend_label():
"""The same backend field the image status exposes: 'NVFP4' alone does not say what ran."""
from models.inference import VideoStatusResponse
resp = VideoStatusResponse(
loaded = True,
transformer_quant = "nvfp4",
transformer_quant_backend = "flashinfer",
)
assert resp.model_dump()["transformer_quant_backend"] == "flashinfer"
assert VideoStatusResponse(loaded = True).model_dump()["transformer_quant_backend"] is None
def _cuda_plan_target(monkeypatch, video_mod, *, free_gib):
"""Point the planning path at a cuda card of ``free_gib``, off the test host's own hardware."""
import torch
from core.inference.diffusion_device import DiffusionDeviceTarget
from core.inference.diffusion_memory import DeviceMemory
target = DiffusionDeviceTarget(
device = "cuda",
dtype = torch.bfloat16,
backend = "cuda",
vendor = "nvidia",
supports_model_cpu_offload = True,
supports_default_torch_compile = True,
supports_pinned_transfer = True,
)
monkeypatch.setattr(video_mod, "resolve_diffusion_device_target", lambda **kw: target)
monkeypatch.setattr(
video_mod,
"settled_snapshot_device_memory",
lambda t, *a, **k: DeviceMemory(
backend = "cuda",
device = "cuda",
memory_kind = "discrete_vram",
free_mib = int(free_gib * 1024),
total_mib = int(free_gib * 1024),
),
)
def _a14b_plan(monkeypatch):
"""The A14B repo pair the seeded-plan tests resolve against."""
import core.inference.video_denoiser_prequant as dq
_plan_api(
monkeypatch,
{
"Wan-AI/Wan2.2-T2V-A14B-Diffusers": [
_PlanSibling("model_index.json", 1000),
_PlanSibling("transformer/config.json", 1000),
_PlanSibling("transformer/diffusion_pytorch_model.safetensors", 28_000_000_000),
_PlanSibling("transformer_2/config.json", 1000),
_PlanSibling("transformer_2/diffusion_pytorch_model.safetensors", 28_000_000_000),
_PlanSibling("text_encoder/model-00001-of-00001.safetensors", 11_000_000_000),
_PlanSibling("vae/diffusion_pytorch_model.safetensors", 500_000_000),
],
"unsloth/Wan2.2-T2V-A14B-NVFP4": [
_PlanSibling("Wan2.2-T2V-A14B-NVFP4.safetensors", 8_000_000_000),
_PlanSibling("Wan2.2-T2V-A14B-transformer_2-NVFP4.safetensors", 8_100_000_000),
],
},
)
sources = {
"transformer": types.SimpleNamespace(
kind = "repo",
location = "unsloth/Wan2.2-T2V-A14B-NVFP4",
filename = "Wan2.2-T2V-A14B-NVFP4.safetensors",
fallback_filename = None,
),
"transformer_2": types.SimpleNamespace(
kind = "repo",
location = "unsloth/Wan2.2-T2V-A14B-NVFP4",
filename = "Wan2.2-T2V-A14B-transformer_2-NVFP4.safetensors",
fallback_filename = None,
),
}
monkeypatch.setattr(dq, "denoiser_prequant_sources", lambda fam, scheme, base, **_: sources)
def test_a_plan_that_still_offloads_at_artifact_size_stages_the_dense_experts(monkeypatch):
import core.inference.video as video_mod
_a14b_plan(monkeypatch)
monkeypatch.setattr(video_mod, "_video_auto_denoiser_scheme", lambda fam, **kw: "nvfp4")
_cuda_plan_target(monkeypatch, video_mod, free_gib = 24)
plan = VideoBackend().download_plan(
"Wan-AI/Wan2.2-T2V-A14B-Diffusers",
model_kind = "pipeline",
transformer_quant = "nvfp4",
)
staged = {f for e in plan["entries"] for f in e["files"]}
assert "transformer/diffusion_pytorch_model.safetensors" in staged
assert "transformer_2/diffusion_pytorch_model.safetensors" in staged
assert not any(f.endswith(".pt") for f in staged)
def test_a_card_the_artifact_fits_on_still_stages_the_artifacts(monkeypatch):
import core.inference.video as video_mod
_a14b_plan(monkeypatch)
monkeypatch.setattr(video_mod, "_video_auto_denoiser_scheme", lambda fam, **kw: "nvfp4")
_cuda_plan_target(monkeypatch, video_mod, free_gib = 180)
plan = VideoBackend().download_plan(
"Wan-AI/Wan2.2-T2V-A14B-Diffusers",
model_kind = "pipeline",
transformer_quant = "nvfp4",
)
staged = {f for e in plan["entries"] for f in e["files"]}
assert "Wan2.2-T2V-A14B-NVFP4.safetensors" in staged
assert "Wan2.2-T2V-A14B-transformer_2-NVFP4.safetensors" in staged
assert not any(
f.endswith("diffusion_pytorch_model.safetensors") and f.startswith("transformer")
for f in staged
)
def test_an_offloading_memory_mode_stages_the_dense_experts_on_any_card(monkeypatch):
import core.inference.video as video_mod
_a14b_plan(monkeypatch)
monkeypatch.setattr(video_mod, "_video_auto_denoiser_scheme", lambda fam, **kw: "nvfp4")
_cuda_plan_target(monkeypatch, video_mod, free_gib = 180)
plan = VideoBackend().download_plan(
"Wan-AI/Wan2.2-T2V-A14B-Diffusers",
model_kind = "pipeline",
transformer_quant = "nvfp4",
memory_mode = "low_vram",
)
staged = {f for e in plan["entries"] for f in e["files"]}
assert "transformer/diffusion_pytorch_model.safetensors" in staged
assert not any(f.endswith(".pt") for f in staged)
def test_a_dense_encoder_fallback_that_forces_offload_also_drops_the_seed(
fake_runtime, monkeypatch
):
"""A dense-encoder fallback re-plan that selects offload must re-take the seed decision."""
import core.inference.diffusion_te_prequant as te
import core.inference.video as video_mod
monkeypatch.setenv("UNSLOTH_DIFFUSION_ALLOW_PRECISION_FALLBACK", "1")
monkeypatch.setattr(video_mod, "dense_transformer_supported", lambda target: True)
monkeypatch.setattr(video_mod, "quantize_transformer", lambda *a, **k: None)
calls, _modules = _stub_denoiser_seed(monkeypatch)
monkeypatch.setattr(te, "te_prequant_budget_scale", lambda fam, **kwargs: 0.5)
monkeypatch.setattr(te, "te_prequant_pipe_kwargs", lambda fam, base, **kwargs: {})
real_plan = video_mod.plan_diffusion_memory
seen: list = []
def _plan(**kwargs):
seen.append(kwargs.get("model_dense_mib"))
planned = real_plan(**kwargs)
return planned if len(seen) == 1 else dataclasses.replace(planned, offload_policy = "model")
monkeypatch.setattr(video_mod, "plan_diffusion_memory", _plan)
_stub_apply_memory_plan(monkeypatch, video_mod)
backend = VideoBackend()
status = backend.load_pipeline(
"Wan-AI/Wan2.2-T2V-A14B-Diffusers",
model_kind = "pipeline",
transformer_quant = "nvfp4",
)
assert calls == [], "no checkpoint may be seeded into a load that will offload the DiT"
assert status["transformer_quant"] is None
# Track GPU progress, not the host queue: CUDA-graph steps enqueue in ~1s, denoise for ~26s.
class _FakeCudaEvent:
"""A ``torch.cuda.Event`` stand-in whose completion the test controls."""
def __init__(self) -> None:
self.done = False
self.queries = 0
def query(self) -> bool:
self.queries += 1
return self.done
class _ClassDecoder:
"""A decoder whose ``decode`` lives on the CLASS, as an untouched diffusers VAE's does."""
def __init__(self) -> None:
self.calls = 0
def decode(self, *args, **kwargs):
self.calls += 1
return "decoded"
def _ticker(monkeypatch, total):
"""A ticker whose events the test owns, plus the list they land in."""
import core.inference.video as video_mod
events: list = []
def _fake_event():
event = _FakeCudaEvent()
events.append(event)
return event
monkeypatch.setattr(video_mod, "_record_device_event", _fake_event)
return video_mod._CompletedStepTicker(total), events
def test_ticker_reports_only_steps_the_gpu_finished(monkeypatch):
ticker, events = _ticker(monkeypatch, 8)
for step in range(1, 9):
ticker.record(step)
assert ticker.completed() == 0
assert ticker.event_backed is True
events[0].done = True
events[1].done = True
assert ticker.completed() == 2
# Still nothing beyond the contiguous run of finished events, even if a later one lands first.
events[5].done = True
assert ticker.completed() == 2
for event in events:
event.done = True
assert ticker.completed() == 8
def test_ticker_never_walks_backwards_or_past_the_total(monkeypatch):
ticker, events = _ticker(monkeypatch, 4)
for step in range(1, 5):
ticker.record(step)
for event in events:
event.done = True
assert ticker.completed() == 4
# A duplicated tick, and an event that starts failing its query, must not lower the bar.
ticker.record(2)
for event in events:
event.done = False
assert ticker.completed() == 4
# Records past the total are counted as enqueued but mark no further events.
ticker.record(9)
assert len(events) == 4
assert ticker.completed() == 4
def test_ticker_caught_up_waits_only_for_steps_before_the_lead(monkeypatch):
ticker, events = _ticker(monkeypatch, 4)
ticker.record(1)
assert ticker.caught_up(1)
ticker.record(2)
assert not ticker.caught_up(1)
events[0].done = True
assert ticker.caught_up(1)
ticker.record(3)
ticker.record(4)
# The last step is enqueued: nothing is left to cancel, so the host is never held.
assert ticker.caught_up(1)
def test_ticker_falls_back_to_the_host_count_without_device_events(monkeypatch):
# A CPU host has no events and no run-ahead, so the host count IS the progress.
import core.inference.video as video_mod
monkeypatch.setattr(video_mod, "_record_device_event", lambda: None)
ticker = video_mod._CompletedStepTicker(5)
for step in range(1, 6):
ticker.record(step)
assert ticker.completed() == step
assert ticker.event_backed is False
@pytest.mark.parametrize("has_event, mps_available", [(True, True), (False, True), (True, False)])
def test_ticker_follows_mps_events(monkeypatch, has_event, mps_available):
# MPS events back the ticker and boundary; no torch.mps.Event or no MPS keeps the host count.
import core.inference.video as video_mod
events: list = []
class _MpsEvent(_FakeCudaEvent):
def __init__(self) -> None:
super().__init__()
self.recorded = False
events.append(self)
def record(self) -> None:
self.recorded = True
torch = types.ModuleType("torch")
torch.cuda = types.SimpleNamespace(is_available = lambda: False)
torch.backends = types.SimpleNamespace(
mps = types.SimpleNamespace(is_available = lambda: mps_available)
)
torch.mps = types.SimpleNamespace(**({"Event": _MpsEvent} if has_event else {}))
monkeypatch.setitem(sys.modules, "torch", torch)
ticker = video_mod._CompletedStepTicker(3)
for step in range(1, 4):
ticker.record(step)
if not (has_event and mps_available):
assert ticker.completed() == 3
assert ticker.event_backed is False
assert ticker.mark_boundary() is False
return
assert [event.recorded for event in events] == [True] * 3
assert ticker.completed() == 0
events[0].done = True
assert ticker.completed() == 1
assert ticker.mark_boundary() is True
assert ticker.boundary_reached() is False
for event in events:
event.done = True
assert ticker.completed() == 3
assert ticker.boundary_reached() is True
def test_ticker_tracks_real_mps_work(monkeypatch):
# Real Apple Silicon: the host enqueues every step long before the GPU runs them, so the bar
# must follow the events. The CUDA-only helper this replaced reports all steps done at once.
torch = pytest.importorskip("torch")
if not torch.backends.mps.is_available():
pytest.skip("needs an MPS device")
import core.inference.video as video_mod
x = torch.randn(2048, 2048, device = "mps")
torch.mps.synchronize()
def _run(ticker, steps):
y = x
for step in range(1, steps + 1):
for _ in range(12):
y = (y @ x) * 1e-3
ticker.record(step)
sentinel = torch.mps.Event()
sentinel.record()
return y, sentinel
def _cuda_only_event():
if not torch.cuda.is_available():
return None
event = torch.cuda.Event()
event.record()
return event
with monkeypatch.context() as patch:
patch.setattr(video_mod, "_record_device_event", _cuda_only_event)
base = video_mod._CompletedStepTicker(4)
_, sentinel = _run(base, 4)
base_done = base.completed()
base_behind = not sentinel.query()
torch.mps.synchronize()
head = video_mod._CompletedStepTicker(4)
_, sentinel = _run(head, 4)
head_done = head.completed()
head_marked = head.mark_boundary()
head_behind = not sentinel.query()
head_boundary = head.boundary_reached()
torch.mps.synchronize()
if not (base_behind and head_behind):
pytest.skip("the GPU caught up with the host before the probe")
assert base_done == 4 and base.event_backed is False
assert head.event_backed is True
assert head_done < 4
assert head_marked is True and head_boundary is False
assert head.completed() == 4
assert head.boundary_reached() is True
def test_ticker_unmarkable_step_does_not_shift_the_ones_after_it(monkeypatch):
# Unrecordable step: costs only its own tick, as the step number travels with its event.
import core.inference.video as video_mod
events: list = []
refuse = {"step": 2}
def _fake_event():
if len(events) + 1 == refuse["step"]:
refuse["step"] = None
return None
event = _FakeCudaEvent()
events.append(event)
return event
monkeypatch.setattr(video_mod, "_record_device_event", _fake_event)
ticker = video_mod._CompletedStepTicker(4)
for step in range(1, 5):
ticker.record(step)
assert len(events) == 3
events[0].done = True
assert ticker.completed() == 1
events[1].done = True
assert ticker.completed() == 3 # the event carries its own step number, so 3, never 2
def test_completed_step_poller_advances_with_no_host_ticks(monkeypatch):
# The host stops ticking once the last step is enqueued, so a poller must query the GPU.
import core.inference.video as video_mod
ticker, events = _ticker(monkeypatch, 3)
for step in range(1, 4):
ticker.record(step)
seen: list = []
with video_mod._completed_step_poller(lambda: seen.append(ticker.completed()), 0.01):
for event in events:
event.done = True
deadline = time.monotonic() + 5.0
while time.monotonic() < deadline and 3 not in seen:
time.sleep(0.01)
assert 3 in seen
assert not [t for t in threading.enumerate() if t.name == "video-denoise-progress"]
def test_completed_step_poller_stands_back_during_a_graph_capture(monkeypatch):
# cudaEventQuery is prohibited from every thread during a global-mode capture.
import core.inference.video as video_mod
ticker, events = _ticker(monkeypatch, 2)
for step in (1, 2):
ticker.record(step)
for event in events:
event.done = True
from core.inference import diffusion_cuda_graph as cg
seen: list = []
with cg._capturing():
with video_mod._completed_step_poller(lambda: seen.append(ticker.completed()), 0.01):
time.sleep(0.2)
assert seen == []
assert all(event.queries == 0 for event in events)
def test_cuda_graph_capture_flag_tracks_the_recording_window():
from core.inference import diffusion_cuda_graph as cg
assert cg.capture_in_progress() is False
with cg._capturing():
assert cg.capture_in_progress() is True
with cg._capturing(): # nothing says two pipelines cannot capture at once
assert cg.capture_in_progress() is True
assert cg.capture_in_progress() is True
assert cg.capture_in_progress() is False
with pytest.raises(RuntimeError, match = "capture failed"):
with cg._capturing():
raise RuntimeError("capture failed")
assert cg.capture_in_progress() is False
def test_decode_phase_fires_once_and_restores_a_class_decode():
import core.inference.video as video_mod
vae = _ClassDecoder()
pipe = types.SimpleNamespace(vae = vae)
fired: list = []
with video_mod._decode_phase(pipe, lambda: fired.append("decode")):
assert vae.decode(1) == "decoded"
assert vae.decode(2) == "decoded"
assert fired == ["decode"]
assert vae.calls == 2
# Nothing may shadow the class method: a bound method in __dict__ is a cycle back to its owner.
assert "decode" not in vae.__dict__
assert vae.decode(3) == "decoded"
def test_decode_phase_restores_a_compiled_decode_it_found():
# The speed layer puts torch.compile(vae.decode) in the instance __dict__; restore THAT.
import core.inference.video as video_mod
vae = _ClassDecoder()
compiled = lambda *a, **k: "compiled" # noqa: E731 - a stand-in for the compiled callable
vae.decode = compiled
pipe = types.SimpleNamespace(vae = vae)
with video_mod._decode_phase(pipe, lambda: None):
assert vae.decode() == "compiled"
assert vae.decode is compiled
def test_decode_phase_restores_the_wrapper_when_the_decode_raises():
import core.inference.video as video_mod
vae = _ClassDecoder()
pipe = types.SimpleNamespace(vae = vae)
fired: list = []
def _boom(*args, **kwargs):
raise RuntimeError("out of memory in decode")
vae.decode = _boom
with pytest.raises(RuntimeError, match = "out of memory in decode"):
with video_mod._decode_phase(pipe, lambda: fired.append("decode")):
vae.decode()
assert fired == ["decode"]
assert vae.decode is _boom
def test_decode_phase_covers_the_audio_decoder_too():
# MiniMax-H3 decodes video then audio; whichever runs first names the phase.
import core.inference.video as video_mod
audio_vae = _ClassDecoder()
pipe = types.SimpleNamespace(vae = None, audio_vae = audio_vae)
fired: list = []
with video_mod._decode_phase(pipe, lambda: fired.append("decode")):
audio_vae.decode()
assert fired == ["decode"]
assert "decode" not in audio_vae.__dict__
def _patch_events(
monkeypatch,
*,
done: bool = False,
run_ahead: bool = True,
):
"""Hand out fake CUDA events, optionally already complete. Returns the list they land in.
``run_ahead`` lets the host outrun events that never finish, as it does when the hold is skipped."""
import core.inference.video as video_mod
if run_ahead:
monkeypatch.setattr(video_mod, "_hold_for_device", lambda ticker, cancel: None)
events: list = []
def _fake_event():
event = _FakeCudaEvent()
event.done = done
events.append(event)
return event
monkeypatch.setattr(video_mod, "_record_device_event", _fake_event)
return events
def test_step_marker_goes_down_after_the_scheduler_step_not_before(fake_runtime, monkeypatch):
# scheduler.step enqueues the step's update, so the tick must come after it returns.
events = _patch_events(monkeypatch)
backend = VideoBackend()
backend.load_pipeline(
"hunyuanvideo-community/HunyuanVideo-1.5-Diffusers-480p_t2v", model_kind = "pipeline"
)
pipe = _FakeHV15Pipeline.instance
marked_when_step_ran: list = []
# Fires inside the original scheduler.step, while step n's latent update is submitted.
pipe.scheduler.on_step = lambda n: marked_when_step_ran.append((n, len(events)))
backend.generate(prompt = "a fox", steps = 5, num_frames = 9, fps = 24)
# While step n is submitting, only the n-1 steps BEFORE it are marked. The old ordering made
# this (n, n): step n was already marked before its own work was enqueued.
assert marked_when_step_ran == [(1, 0), (2, 1), (3, 2), (4, 3), (5, 4)]
assert len(events) == 6 # five steps plus the end-of-denoise boundary marker
def test_cancellation_is_still_checked_before_the_step_runs(fake_runtime, monkeypatch):
# The cancel check must stay before the next step's work is submitted.
events = _patch_events(monkeypatch)
backend = VideoBackend()
backend.load_pipeline(
"hunyuanvideo-community/HunyuanVideo-1.5-Diffusers-480p_t2v", model_kind = "pipeline"
)
pipe = _FakeHV15Pipeline.instance
pipe.scheduler.on_step = lambda n: backend.cancel_generate() if n == 1 else None
with pytest.raises(RuntimeError, match = VIDEO_CANCELLED_MSG):
backend.generate(prompt = "a fox", steps = 4)
assert pipe.scheduler.calls == 1
assert len(events) == 1
@pytest.mark.parametrize(
"repo",
[
"Wan-AI/Wan2.2-TI2V-5B-Diffusers",
"hunyuanvideo-community/HunyuanVideo-1.5-Diffusers-480p_t2v",
],
)
def test_a_cancel_stops_a_denoise_the_device_has_not_caught_up_with(
fake_runtime, monkeypatch, repo
):
# A step the host has enqueued cannot be cancelled, so the host must not run ahead of the device.
events = _patch_events(monkeypatch, run_ahead = False)
backend = VideoBackend()
backend.load_pipeline(repo, model_kind = "pipeline")
outcome: dict = {}
def _run():
try:
backend.generate(prompt = "a fox", steps = 20, num_frames = 9, fps = 24)
except BaseException as exc: # noqa: BLE001 -- asserted below
outcome["error"] = exc
worker = threading.Thread(target = _run, daemon = True)
worker.start()
worker.join(0.5)
backend.cancel_generate()
worker.join(10)
assert not worker.is_alive()
assert VIDEO_CANCELLED_MSG in str(outcome.get("error"))
assert len(events) <= 3, len(events)
def test_phase_reads_encode_until_the_denoise_loop_starts(fake_runtime, monkeypatch):
# The prompt encode runs inside pipe() before the first step; the bar said "denoise" through it.
_patch_events(monkeypatch)
backend = VideoBackend()
backend.load_pipeline(
"hunyuanvideo-community/HunyuanVideo-1.5-Diffusers-480p_t2v", model_kind = "pipeline"
)
pipe = _FakeHV15Pipeline.instance
phases: list = []
pipe.scheduler.on_step = lambda n: phases.append(backend._gen.get("phase"))
original_call = type(pipe).__call__
def _call(self, *args, **kwargs):
phases.append(("at_call", backend._gen.get("phase")))
return original_call(self, *args, **kwargs)
monkeypatch.setattr(type(pipe), "__call__", _call)
backend.generate(prompt = "a fox", steps = 3, num_frames = 9, fps = 24)
assert phases[0] == ("at_call", "encode")
assert phases[2:] == ["denoise", "denoise"]
def test_hv15_bar_never_outruns_the_gpu_and_holds_the_phase(fake_runtime, monkeypatch):
# Scheduler-wrap path: the host reaches the decoder while the GPU has finished nothing.
events = _patch_events(monkeypatch)
backend = VideoBackend()
backend.load_pipeline(
"hunyuanvideo-community/HunyuanVideo-1.5-Diffusers-480p_t2v", model_kind = "pipeline"
)
pipe = _FakeHV15Pipeline.instance
seen: list = []
def _watch(enqueued):
seen.append((enqueued, int(backend._gen.get("step") or 0), sum(e.done for e in events)))
pipe.scheduler.on_step = _watch
at_decode: dict = {}
pipe.vae.on_decode = lambda: at_decode.update(backend._gen)
backend.generate(prompt = "a fox", steps = 8, num_frames = 9, fps = 24)
assert [enqueued for enqueued, _, _ in seen] == list(range(1, 9))
# The invariant: never more steps reported than the GPU has actually completed.
for enqueued, reported, finished in seen:
assert reported <= finished, (enqueued, reported, finished)
assert {reported for _, reported, _ in seen} == {0}
# The decoder entry must not complete the bar until the boundary marker completes.
assert at_decode.get("phase") == "denoise"
assert at_decode.get("step") == 0
def test_decode_phase_lands_once_the_gpu_reaches_the_boundary(fake_runtime, monkeypatch):
_patch_events(monkeypatch, done = True)
backend = VideoBackend()
backend.load_pipeline(
"hunyuanvideo-community/HunyuanVideo-1.5-Diffusers-480p_t2v", model_kind = "pipeline"
)
pipe = _FakeHV15Pipeline.instance
at_decode: dict = {}
pipe.vae.on_decode = lambda: _settle(backend, at_decode)
backend.generate(prompt = "a fox", steps = 8, num_frames = 9, fps = 24)
assert at_decode.get("phase") == "decode"
assert at_decode.get("step") == 8
assert at_decode.get("total") == 8
assert at_decode.get("eta_seconds") is None
def _settle(
backend,
out,
timeout = 5.0,
):
"""Wait for the poller to publish the decode phase; reading _gen on decoder entry races the poll."""
deadline = time.monotonic() + timeout
while time.monotonic() < deadline:
if backend._gen.get("phase") == "decode":
break
time.sleep(0.01)
out.update(backend._gen)
def test_a_capture_cannot_start_while_an_event_query_is_in_flight(monkeypatch):
# The lock must span the query itself, or a capture can begin between check and query.
import core.inference.video as video_mod
from core.inference import diffusion_cuda_graph as cg
in_query = threading.Event()
finish_query = threading.Event()
class _BlockingEvent:
def query(self):
in_query.set()
finish_query.wait(5.0)
return True
monkeypatch.setattr(video_mod, "_record_device_event", lambda: _BlockingEvent())
ticker = video_mod._CompletedStepTicker(1)
ticker.record(1)
entered_capture = threading.Event()
def _capture():
with cg._capturing():
entered_capture.set()
with video_mod._completed_step_poller(ticker.completed, 0.01):
assert in_query.wait(5.0), "the poller never reached the query"
capturer = threading.Thread(target = _capture, daemon = True)
capturer.start()
assert not entered_capture.wait(0.5)
finish_query.set()
assert entered_capture.wait(5.0)
capturer.join(timeout = 5.0)
assert cg.capture_in_progress() is False
def test_hold_off_capture_yields_false_rather_than_waiting_on_a_capture():
from core.inference import diffusion_cuda_graph as cg
with cg.hold_off_capture() as clear:
assert clear is True
with cg._capturing():
with cg.hold_off_capture() as clear:
assert clear is False
with cg.hold_off_capture() as clear:
assert clear is True
def test_denoise_completes_even_when_the_loop_ticks_fewer_times_than_steps(fake_runtime):
# H3 makes 29 scheduler.step calls for 30 steps; reaching the decode proves completion.
backend = VideoBackend()
pipe = _load_h3_modular(backend)
seen: dict = {}
original_call = pipe.__class__.__call__
def _one_tick_short(
self,
*,
num_inference_steps = None,
**kwargs,
):
out = original_call(self, num_inference_steps = int(num_inference_steps) - 1, **kwargs)
seen["at_end_of_loop"] = int(backend._gen.get("step") or 0)
return out
pipe.__class__.__call__ = _one_tick_short
try:
backend.generate(prompt = "a fox", steps = 30, num_frames = 9, fps = 24)
finally:
pipe.__class__.__call__ = original_call
assert pipe.scheduler.calls == 29
assert seen["at_end_of_loop"] < 30
assert backend._gen == {"active": False}
def test_hv15_cancel_still_unwinds_and_leaves_nothing_installed(fake_runtime):
backend = VideoBackend()
backend.load_pipeline(
"hunyuanvideo-community/HunyuanVideo-1.5-Diffusers-480p_t2v", model_kind = "pipeline"
)
pipe = _FakeHV15Pipeline.instance
pipe.scheduler.on_step = lambda n: backend.cancel_generate() if n == 1 else None
with pytest.raises(RuntimeError, match = VIDEO_CANCELLED_MSG):
backend.generate(prompt = "a fox", steps = 4)
assert pipe.scheduler.calls == 1
assert pipe.scheduler.step.__func__ is _FakeHV15Scheduler.step
assert pipe.vae.decodes == 0
assert "decode" not in pipe.vae.__dict__
assert not [t for t in threading.enumerate() if t.name == "video-denoise-progress"]
def test_decode_failure_surfaces_and_leaves_nothing_installed(fake_runtime):
backend = VideoBackend()
backend.load_pipeline(
"hunyuanvideo-community/HunyuanVideo-1.5-Diffusers-480p_t2v", model_kind = "pipeline"
)
pipe = _FakeHV15Pipeline.instance
pipe.vae.decode_raises = RuntimeError("CUDA out of memory in decode")
with pytest.raises(RuntimeError, match = "CUDA out of memory in decode"):
backend.generate(prompt = "a fox", steps = 4)
assert "decode" not in pipe.vae.__dict__
assert not [t for t in threading.enumerate() if t.name == "video-denoise-progress"]
def test_callback_family_keeps_its_own_callback(fake_runtime, monkeypatch):
# Wan uses callback_on_step_end, so its scheduler is not wrapped.
import core.inference.video as video_mod
events = _patch_events(monkeypatch, done = True)
wrapped: list = []
original_wrap = video_mod._scheduler_step_progress
monkeypatch.setattr(
video_mod,
"_scheduler_step_progress",
lambda *a, **kw: wrapped.append(a[0]) or original_wrap(*a, **kw),
)
backend = VideoBackend()
backend.load_pipeline("Wan-AI/Wan2.2-TI2V-5B-Diffusers", model_kind = "pipeline")
pipe = backend._state.pipe
at_decode: dict = {}
pipe.vae.on_decode = lambda: _settle(backend, at_decode)
backend.generate(prompt = "a sloth", steps = 6, num_frames = 9, fps = 24)
assert wrapped == []
# One marker per callback tick, so the callback really ran, plus the boundary marker.
assert len(events) == 7
assert pipe.vae.decodes == 1
assert at_decode.get("phase") == "decode"
assert at_decode.get("step") == 6
def test_a_capture_in_another_pipeline_stops_the_tick_from_touching_events(
fake_runtime, monkeypatch
):
# Global capture mode bars event calls in every thread, and is_current_stream_capturing
# only sees this pipeline's capture, so tick and marker take the same hold-off.
import core.inference.video as video_mod
events = _patch_events(monkeypatch, done = True)
@contextlib.contextmanager
def _capture_running():
yield False
monkeypatch.setattr(video_mod, "_hold_off_cuda_graph_capture", _capture_running)
backend = VideoBackend()
backend.load_pipeline(
"hunyuanvideo-community/HunyuanVideo-1.5-Diffusers-480p_t2v", model_kind = "pipeline"
)
pipe = _FakeHV15Pipeline.instance
at_decode: dict = {}
pipe.vae.on_decode = lambda: at_decode.update(backend._gen)
backend.generate(prompt = "a fox", steps = 5, num_frames = 9, fps = 24)
assert events == []
# With no marker, the decode flip falls back to the host position.
assert at_decode.get("phase") == "decode"
assert at_decode.get("step") == 5
def test_the_tick_marks_every_step_again_once_the_capture_is_over(fake_runtime, monkeypatch):
# The guard must still mark when no capture runs, or the whole feature quietly turns off.
events = _patch_events(monkeypatch, done = True)
backend = VideoBackend()
backend.load_pipeline(
"hunyuanvideo-community/HunyuanVideo-1.5-Diffusers-480p_t2v", model_kind = "pipeline"
)
backend.generate(prompt = "a fox", steps = 5, num_frames = 9, fps = 24)
assert len(events) == 6 # five steps plus the boundary
def test_the_boundary_marker_waits_out_a_busy_capture_lock(fake_runtime, monkeypatch):
# hold_off_capture is non-blocking; a refusal may just be the poller, so retry.
import core.inference.video as video_mod
_patch_events(monkeypatch, done = True)
# Busy window shorter than the retry budget (20 x 20 ms).
busy_until = {"t": 0.0}
@contextlib.contextmanager
def _busy_window():
yield time.monotonic() >= busy_until["t"]
marks = {"calls": 0, "ok": None}
original_mark = video_mod._CompletedStepTicker.mark_boundary
def _counted(self):
marks["calls"] += 1
marks["ok"] = original_mark(self)
return marks["ok"]
monkeypatch.setattr(video_mod._CompletedStepTicker, "mark_boundary", _counted)
backend = VideoBackend()
backend.load_pipeline(
"hunyuanvideo-community/HunyuanVideo-1.5-Diffusers-480p_t2v", model_kind = "pipeline"
)
pipe = _FakeHV15Pipeline.instance
at_decode: dict = {}
pipe.vae.on_decode = lambda: _settle(backend, at_decode)
def _contend(n):
if n == 5:
busy_until["t"] = time.monotonic() + 0.2
monkeypatch.setattr(video_mod, "_hold_off_cuda_graph_capture", _busy_window)
pipe.scheduler.on_step = _contend
backend.generate(prompt = "a fox", steps = 5, num_frames = 9, fps = 24)
assert marks["calls"] == 1
assert marks["ok"] is True
assert at_decode.get("phase") == "decode"
def test_generate_runs_the_video_pipeline_through_the_render_thread(
fake_runtime, tmp_path, monkeypatch
):
from core.inference import video as video_mod
names = []
def run(name, fn):
names.append(name)
return fn()
monkeypatch.setattr(video_mod.render_thread, "run", run)
backend = _load_ltx23_from_dir(tmp_path)
backend.generate(prompt = "a sloth")
assert names == ["video"]
assert backend._state.pipe.last_kwargs["num_inference_steps"] == 8
@pytest.mark.parametrize("resident", [True, False])
def test_a_failed_replacement_keeps_the_resident_models_nvfp4_state(monkeypatch, resident):
"""A failed replacement keeps the old model, whose CUDA graph still uses the NVFP4 tensors."""
import core.inference.video as vid
from core.inference import diffusion_nvfp4_linear as lin
backend = VideoBackend()
resets: list = []
monkeypatch.setattr(lin, "reset_nvfp4_state", lambda: resets.append(True))
monkeypatch.setattr(vid, "clear_gpu_cache", lambda: None)
def _boom(*_a, **_k):
raise RuntimeError("metadata lookup failed")
monkeypatch.setattr(vid, "_detect_load_family", _boom)
if resident:
backend._state = types.SimpleNamespace(pipe = None)
import core.inference.gpu_arbiter as arbiter
import hub.services.models.account_access as access
monkeypatch.setattr(arbiter, "restore_owner_account", lambda *_a, **_k: None)
monkeypatch.setattr(access, "restore_resident_metadata", lambda *_a, **_k: None)
backend._load_token = 7
backend._run_load(repo_id = "org/model", _load_token = 7)
assert resets == ([] if resident else [True])
class _StopAfterInstallGate(Exception):
"""Raised just past the FlashInfer pre-install hop."""
class _Sibling:
def __init__(
self,
rfilename,
size = 1,
):
self.rfilename = rfilename
self.size = size
def _hub_refusal(cls, repo = "unsloth/Wan2.2-T2V-A14B-NVFP4"):
# response is optional in huggingface_hub 0.x but required in 1.x; a stub works on either.
return cls(
f"401 Client Error. Repository Not Found for url: https://huggingface.co/api/models/{repo}",
response = types.SimpleNamespace(headers = {}, request = None),
)
def _video_install_probe(
monkeypatch,
*,
listing = None,
refusal = None,
cached = False,
free_mib = 180_000,
):
"""Record FlashInfer installs and Hub listings, stopping after the hop."""
import core.inference.video as video_mod
from core.inference import diffusion_nvfp4_install as inst
from core.inference.diffusion import DiffusionBackend
installs: list = []
listed: list = []
dispatched: list = []
def _ensure(device, **kwargs):
installs.append((device, kwargs.get("local_files_only")))
return True, "installed flashinfer for NVFP4"
real_hop = VideoBackend._install_flashinfer_for_seed
def _hop(*args, **kwargs):
real_hop(*args, **kwargs)
raise _StopAfterInstallGate()
class _Api:
def __init__(self, *a, **k):
pass
def model_info(
self,
repo_id,
files_metadata = False,
token = None,
):
listed.append(repo_id)
if refusal is not None:
raise refusal
return types.SimpleNamespace(siblings = [_Sibling(n) for n in (listing or [])])
def _modular(self, **kwargs):
dispatched.append(kwargs.get("_nvfp4_install_outcome"))
raise _StopAfterInstallGate()
monkeypatch.setattr(inst, "ensure_flashinfer_for_nvfp4", _ensure)
monkeypatch.setattr("huggingface_hub.HfApi", _Api)
monkeypatch.setattr(
DiffusionBackend, "_hub_file_is_cached", staticmethod(lambda repo, name, *a, **k: cached)
)
monkeypatch.setattr(
VideoBackend,
"_device_target",
lambda self, ordinal = None: types.SimpleNamespace(device = "cuda", dtype = None, ordinal = 0),
)
from core.inference.diffusion_memory import DeviceMemory
monkeypatch.setattr(
video_mod,
"settled_snapshot_device_memory",
lambda target: DeviceMemory("cuda", "cuda", "discrete_vram", free_mib, 183_000),
)
monkeypatch.setattr(
video_mod,
"_video_auto_denoiser_scheme",
lambda fam, *, requested = None, **kw: "nvfp4" if requested == "nvfp4" else None,
)
monkeypatch.setattr(VideoBackend, "_load_h3_modular_pipeline", _modular)
monkeypatch.setattr(VideoBackend, "_install_flashinfer_for_seed", staticmethod(_hop))
return installs, listed, dispatched
def _video_load_to_the_install_gate(repo_id = "Wan-AI/Wan2.2-T2V-A14B-Diffusers", **overrides):
kwargs = dict(model_kind = "pipeline", transformer_quant = "nvfp4")
kwargs.update(overrides)
with pytest.raises(_StopAfterInstallGate):
VideoBackend().load_pipeline(repo_id, **kwargs)
@pytest.mark.parametrize("error", ["RepositoryNotFoundError", "GatedRepoError"])
@pytest.mark.parametrize(
"repo_id, hosted",
[
("Wan-AI/Wan2.2-T2V-A14B-Diffusers", "unsloth/Wan2.2-T2V-A14B-NVFP4"),
("Wan-AI/Wan2.2-TI2V-5B-Diffusers", "unsloth/Wan2.2-TI2V-5B-NVFP4"),
],
)
def test_an_nvfp4_video_checkpoint_the_hub_refuses_installs_no_flashinfer(
fake_runtime, monkeypatch, error, repo_id, hosted
):
# Private / gated repo: on-the-fly torchao build, FlashInfer unused.
import huggingface_hub.errors as hub_errors
installs, listed, _ = _video_install_probe(
monkeypatch, refusal = _hub_refusal(getattr(hub_errors, error), hosted)
)
_video_load_to_the_install_gate(repo_id)
assert installs == []
assert listed == [hosted]
def test_an_nvfp4_video_repo_missing_a_denoiser_installs_no_flashinfer(fake_runtime, monkeypatch):
# A14B needs BOTH denoisers.
installs, listed, _ = _video_install_probe(
monkeypatch, listing = ["Wan2.2-T2V-A14B-NVFP4.safetensors"]
)
_video_load_to_the_install_gate()
assert installs == []
assert listed == ["unsloth/Wan2.2-T2V-A14B-NVFP4"]
def test_an_nvfp4_video_family_with_no_hosted_checkpoint_installs_no_flashinfer(
fake_runtime, monkeypatch
):
import core.inference.video_denoiser_prequant as dq
installs, listed, _ = _video_install_probe(monkeypatch)
monkeypatch.setattr(dq, "denoiser_prequant_sources", lambda fam, scheme, base, **_: None)
_video_load_to_the_install_gate()
assert installs == []
assert listed == []
def test_a_reachable_nvfp4_video_checkpoint_still_installs_flashinfer(fake_runtime, monkeypatch):
installs, listed, _ = _video_install_probe(
monkeypatch,
listing = [
"Wan2.2-T2V-A14B-NVFP4.safetensors",
"Wan2.2-T2V-A14B-transformer_2-NVFP4.safetensors",
],
)
_video_load_to_the_install_gate()
assert listed == ["unsloth/Wan2.2-T2V-A14B-NVFP4"]
assert installs == [("cuda", False)]
def test_with_the_nvfp4_switch_off_a_reachable_video_checkpoint_installs_nothing(
fake_runtime, monkeypatch
):
monkeypatch.delenv("UNSLOTH_NVFP4_DIFFUSION", raising = False)
installs, listed, _ = _video_install_probe(
monkeypatch,
listing = [
"Wan2.2-T2V-A14B-NVFP4.safetensors",
"Wan2.2-T2V-A14B-transformer_2-NVFP4.safetensors",
],
)
_video_load_to_the_install_gate(transformer_quant = None, _video_auto_denoiser_planned = "nvfp4")
assert installs == []
assert listed == [], "no Hub request to a *-NVFP4 repo while the switch is off"
def test_a_video_plan_that_settled_nvfp4_installs_without_asking_the_hub_again(
fake_runtime, monkeypatch
):
installs, listed, _ = _video_install_probe(
monkeypatch, refusal = RuntimeError("no request expected")
)
_video_load_to_the_install_gate(transformer_quant = None, _video_auto_denoiser_planned = "nvfp4")
assert listed == []
assert installs == [("cuda", False)]
def test_a_video_seed_the_plan_declined_installs_no_flashinfer(fake_runtime, monkeypatch):
from core.inference.video import DENOISER_SEED_DECLINED
installs, listed, _ = _video_install_probe(
monkeypatch,
listing = [
"Wan2.2-T2V-A14B-NVFP4.safetensors",
"Wan2.2-T2V-A14B-transformer_2-NVFP4.safetensors",
],
)
_video_load_to_the_install_gate(_video_auto_denoiser_planned = DENOISER_SEED_DECLINED)
assert installs == []
assert listed == []
def test_a_video_seed_the_live_memory_plan_drops_installs_no_flashinfer(fake_runtime, monkeypatch):
# Live free memory short: the plan offloads and drops the capacity-settled seed, so no install.
installs, listed, _ = _video_install_probe(
monkeypatch, refusal = RuntimeError("no request expected"), free_mib = 4_000
)
monkeypatch.setattr(
VideoBackend,
"_device_target",
lambda self, ordinal = None: types.SimpleNamespace(
device = "cuda", dtype = None, ordinal = 0, supports_model_cpu_offload = True
),
)
_video_load_to_the_install_gate(transformer_quant = None, _video_auto_denoiser_planned = "nvfp4")
assert installs == []
assert listed == []
@pytest.mark.parametrize("cached", [False, True])
def test_an_offline_nvfp4_video_load_asks_only_the_cache(fake_runtime, monkeypatch, cached):
installs, listed, _ = _video_install_probe(
monkeypatch, refusal = RuntimeError("an offline load made a Hub request"), cached = cached
)
_video_load_to_the_install_gate(local_files_only = True)
assert listed == []
assert installs == ([("cuda", True)] if cached else [])
def _stub_h3_nvfp4_checkpoint(monkeypatch):
"""Register a fake hosted NVFP4 MiniMax-H3 denoiser; records each lookup's task."""
import core.inference.diffusion_prequant as prequant_mod
import core.inference.video as video_mod
tasks: list = []
def _available(
fam,
scheme,
task = None,
base_repo = None,
):
tasks.append(task)
return scheme == "nvfp4"
def _resolve(
fam,
scheme,
*,
path_override = None,
base_repo = None,
task = None,
):
return types.SimpleNamespace(
kind = "repo",
location = "unsloth/MiniMax-H3-NVFP4",
filename = f"MiniMax-H3-{task}-NVFP4.safetensors",
fallback_filenames = (),
)
monkeypatch.setattr(video_mod, "video_family_prequant_available", _available)
monkeypatch.setattr(prequant_mod, "resolve_prequant_source", _resolve)
diffusers = sys.modules["diffusers"]
monkeypatch.setattr(diffusers, "ModularPipeline", _FakeModularPipeline, raising = False)
fam = _detect_load_family("MiniMaxAI/MiniMax-H3", None, "minimax-h3")
monkeypatch.setattr(diffusers, fam.transformer_class, _FakeTransformer, raising = False)
return tasks
def test_the_minimax_h3_modular_path_skips_the_install_for_a_refused_checkpoint(
fake_runtime, monkeypatch
):
from huggingface_hub.errors import RepositoryNotFoundError
installs, listed, dispatched = _video_install_probe(
monkeypatch, refusal = _hub_refusal(RepositoryNotFoundError, "unsloth/MiniMax-H3-NVFP4")
)
tasks = _stub_h3_nvfp4_checkpoint(monkeypatch)
_video_load_to_the_install_gate("MiniMaxAI/MiniMax-H3", family_override = "minimax-h3")
assert installs == []
assert listed == ["unsloth/MiniMax-H3-NVFP4"]
assert dispatched == [None], "the modular load was handed an install outcome it never earned"
assert "fl2va" in tasks
def test_the_minimax_h3_modular_path_installs_for_a_reachable_checkpoint(fake_runtime, monkeypatch):
installs, listed, dispatched = _video_install_probe(
monkeypatch, listing = ["MiniMax-H3-ref2va-NVFP4.safetensors"]
)
_stub_h3_nvfp4_checkpoint(monkeypatch)
_video_load_to_the_install_gate(
"MiniMaxAI/MiniMax-H3", family_override = "minimax-h3", h3_task = "ref2va"
)
assert listed == ["unsloth/MiniMax-H3-NVFP4"]
assert installs == [("cuda", False)]
assert dispatched == [(True, "installed flashinfer for NVFP4")]
@pytest.mark.parametrize("scheme", ["int8", "fp8"])
def test_an_explicit_video_scheme_on_amd_runs_weight_only_without_forcing_compile(
fake_runtime, monkeypatch, scheme
):
"""An explicit int8 / fp8 video DiT engages the native branch on AMD, honouring speed=off."""
import core.inference.video as video_mod
from core.inference import diffusion_transformer_quant as tq
monkeypatch.setattr(video_mod, "dense_transformer_supported", lambda target: False)
monkeypatch.setattr(tq, "dense_transformer_supported", lambda target: False)
monkeypatch.setattr(video_mod, "native_quant_host", lambda target: True)
monkeypatch.setattr(tq, "native_quant_host", lambda target: True)
calls: list = []
def _quantize(
view,
target,
*,
mode,
family = None,
**kw,
):
assert tq.native_quant_scheme(target, mode, family = family) == scheme
calls.append(mode)
return scheme
monkeypatch.setattr(video_mod, "quantize_transformer", _quantize)
backend = VideoBackend()
status = backend.load_pipeline(
"Wan-AI/Wan2.2-TI2V-5B-Diffusers",
model_kind = "pipeline",
transformer_quant = scheme,
speed_mode = "off",
)
assert calls and set(calls) == {scheme}
assert status["transformer_quant"] == scheme
assert status["speed_mode"] == "off"
assert "requires compile" not in status["resolved"]["speed_mode"]["reason"]
assert "weight-only" in status["resolved"]["transformer_quant"]["reason"]
backend.unload()
@pytest.mark.parametrize("fallback", ["0", "1"])
def test_a_video_checkpoint_stored_narrow_is_not_quantised_again(
fake_runtime, monkeypatch, fallback
):
"""A bf16-widened fp8 checkpoint is declined without calling the quantiser."""
import core.inference.video as video_mod
from core.inference import diffusion_transformer_quant as tq
monkeypatch.setenv("UNSLOTH_DIFFUSION_ALLOW_PRECISION_FALLBACK", fallback)
monkeypatch.setattr(video_mod, "dense_transformer_supported", lambda target: False)
monkeypatch.setattr(video_mod, "native_quant_host", lambda target: True)
monkeypatch.setattr(tq, "dense_transformer_supported", lambda target: False)
monkeypatch.setattr(tq, "native_quant_host", lambda target: True)
monkeypatch.setattr(video_mod, "stored_denoiser_precision", lambda local_dir: "fp8")
def _quantize(view, target, **kw):
raise AssertionError("a narrow-stored DiT must not be quantised again")
monkeypatch.setattr(video_mod, "quantize_transformer", _quantize)
backend = VideoBackend()
if fallback == "0":
with pytest.raises(RuntimeError, match = "widened to bf16"):
backend.load_pipeline(
"Wan-AI/Wan2.2-TI2V-5B-Diffusers", model_kind = "pipeline", transformer_quant = "int8"
)
return
status = backend.load_pipeline(
"Wan-AI/Wan2.2-TI2V-5B-Diffusers", model_kind = "pipeline", transformer_quant = "int8"
)
resolved = status["resolved"]["transformer_quant"]
assert resolved["status"] == "unsupported" and "widened to bf16" in resolved["reason"]
backend.unload()
@pytest.mark.parametrize("fallback", ["0", "1"])
def test_a_partly_converted_video_denoiser_is_refused_even_with_the_fallback_allowed(
fake_runtime, monkeypatch, fallback
):
"""A part-converted weight-only DiT is refused even with the precision fallback."""
import core.inference.video as video_mod
from core.inference import diffusion_transformer_quant as tq
monkeypatch.setenv("UNSLOTH_DIFFUSION_ALLOW_PRECISION_FALLBACK", fallback)
monkeypatch.setattr(video_mod, "dense_transformer_supported", lambda target: False)
monkeypatch.setattr(video_mod, "native_quant_host", lambda target: True)
monkeypatch.setattr(tq, "dense_transformer_supported", lambda target: False)
monkeypatch.setattr(tq, "native_quant_host", lambda target: True)
monkeypatch.setattr(video_mod, "quantize_transformer", lambda view, target, **kw: None)
monkeypatch.setattr(video_mod, "transformer_is_quantised", lambda view: True)
backend = VideoBackend()
with pytest.raises(RuntimeError, match = "neither dense nor usable"):
backend.load_pipeline(
"Wan-AI/Wan2.2-TI2V-5B-Diffusers", model_kind = "pipeline", transformer_quant = "int8"
)
assert backend._state is None
def test_a_clean_video_decline_under_the_fallback_still_loads_dense(fake_runtime, monkeypatch):
import core.inference.video as video_mod
from core.inference import diffusion_transformer_quant as tq
monkeypatch.setenv("UNSLOTH_DIFFUSION_ALLOW_PRECISION_FALLBACK", "1")
monkeypatch.setattr(video_mod, "dense_transformer_supported", lambda target: False)
monkeypatch.setattr(video_mod, "native_quant_host", lambda target: True)
monkeypatch.setattr(tq, "dense_transformer_supported", lambda target: False)
monkeypatch.setattr(tq, "native_quant_host", lambda target: True)
monkeypatch.setattr(video_mod, "quantize_transformer", lambda view, target, **kw: None)
monkeypatch.setattr(video_mod, "transformer_is_quantised", lambda view: False)
backend = VideoBackend()
status = backend.load_pipeline(
"Wan-AI/Wan2.2-TI2V-5B-Diffusers", model_kind = "pipeline", transformer_quant = "int8"
)
assert status["transformer_quant"] in (None, "none", "off")
def test_video_auto_below_max_names_an_uncacheable_dit(fake_runtime, monkeypatch):
monkeypatch.setattr(
"core.inference.video.step_cache_supported", lambda pipe, logger = None: False
)
backend = VideoBackend()
status = backend.load_pipeline(
"Wan-AI/Wan2.2-TI2V-5B-Diffusers", model_kind = "pipeline", speed_mode = "default"
)
assert status["resolved"]["transformer_cache"]["reason"] == (
"auto: model does not support step caching"
)
backend.unload()
def test_teardown_drains_pinned_host_memory_after_the_pipeline_is_gone(
fake_runtime, tmp_path, monkeypatch
):
from core.inference import video as video_mod
backend = VideoBackend()
_load_gguf(backend, tmp_path)
calls: list = []
monkeypatch.setattr(
video_mod, "clear_gpu_cache", lambda: calls.append(("clear", backend._state))
)
monkeypatch.setattr(
video_mod, "release_pinned_host_memory", lambda: calls.append(("host", backend._state))
)
backend.unload()
assert calls == [("clear", None), ("host", None)]
def test_teardown_drains_pinned_host_memory_even_when_gpu_cleanup_raises(
fake_runtime, tmp_path, monkeypatch
):
from core.inference import video as video_mod
backend = VideoBackend()
_load_gguf(backend, tmp_path)
drained: list = []
def _sticky():
raise RuntimeError("CUDA error: an illegal memory access was encountered")
monkeypatch.setattr(video_mod, "clear_gpu_cache", _sticky)
monkeypatch.setattr(video_mod, "release_pinned_host_memory", lambda: drained.append(True))
with pytest.raises(RuntimeError, match = "illegal memory access"):
backend.unload()
assert drained == [True]
def test_video_status_reports_cuda_graph_off_once_every_armed_step_ran_eager(fake_runtime):
backend = VideoBackend()
backend.load_pipeline("Wan-AI/Wan2.2-TI2V-5B-Diffusers", model_kind = "pipeline")
handle = types.SimpleNamespace(
cache = {},
stats = {"eager_calls": 0, "refused_object": 0},
poisoned = False,
capture_error = None,
)
backend._state.pipe._unsloth_cuda_graphs = [handle]
resolved = {**(backend._state.resolved or {}), "cuda_graph": {"value": "on", "reason": "r"}}
backend._state = replace(
backend._state,
speed_optims = ("compiled", "cuda_graph"),
resolved = resolved,
)
assert backend.status()["resolved"]["cuda_graph"]["value"] == "on"
handle.stats.update(eager_calls = 30, refused_object = 30)
st = backend.status()
assert st["resolved"]["cuda_graph"]["value"] == "off"
assert "all 30 denoiser call(s) so far ran eager" in st["resolved"]["cuda_graph"]["reason"]
assert st["speed_optims"] == ["compiled"]
assert resolved["cuda_graph"]["value"] == "on"
backend.unload()
def _stub_nvidia_video_offload(monkeypatch, *, offload = True):
import dataclasses
import core.inference.video as video_mod
from core.inference import diffusion_transformer_quant as tq
monkeypatch.setattr(video_mod, "dense_transformer_supported", lambda target: True)
monkeypatch.setattr(tq, "native_quant_host", lambda target: False)
monkeypatch.setattr(tq, "native_offload_host", lambda target: True)
monkeypatch.setattr(
video_mod, "select_transformer_quant_scheme", lambda target, mode, family = None: mode
)
monkeypatch.delenv("UNSLOTH_NATIVE_INT8_ACT", raising = False)
if offload:
real_plan = video_mod.plan_diffusion_memory
monkeypatch.setattr(
video_mod,
"plan_diffusion_memory",
lambda **kwargs: dataclasses.replace(real_plan(**kwargs), offload_policy = "model"),
)
_stub_apply_memory_plan(monkeypatch, video_mod, policy = "model" if offload else "none")
calls: list = []
def _quantize(
view,
target,
*,
mode,
family = None,
**kw,
):
calls.append({"view": view, "mode": mode, **kw})
return mode
monkeypatch.setattr(video_mod, "quantize_transformer", _quantize)
monkeypatch.setattr(
video_mod, "native_quant_reason", lambda module, scheme: f"W8A8: {scheme} (stub)"
)
return calls
def test_an_explicit_int8_under_offload_on_nvidia_runs_native_on_both_experts(
fake_runtime, monkeypatch
):
calls = _stub_nvidia_video_offload(monkeypatch)
backend = VideoBackend()
status = backend.load_pipeline(
"Wan-AI/Wan2.2-T2V-A14B-Diffusers", model_kind = "pipeline", transformer_quant = "int8"
)
assert status["offload_policy"] == "model"
assert len(calls) == 2
assert all(c["offload"] is True and c["act_int8"] is True for c in calls)
assert status["transformer_quant"] == "int8"
resolved = status["resolved"]["transformer_quant"]
assert resolved["status"] == "applied" and resolved["reason"].startswith("W8A8")
backend.unload()
def test_the_video_act_kill_switch_keeps_offload_native_weight_only(fake_runtime, monkeypatch):
calls = _stub_nvidia_video_offload(monkeypatch)
monkeypatch.setenv("UNSLOTH_NATIVE_INT8_ACT", "0")
backend = VideoBackend()
status = backend.load_pipeline(
"Wan-AI/Wan2.2-TI2V-5B-Diffusers", model_kind = "pipeline", transformer_quant = "int8"
)
assert calls and all(c["offload"] is True and c["act_int8"] is False for c in calls)
assert status["transformer_quant"] == "int8"
backend.unload()
def test_a_resident_video_int8_on_nvidia_keeps_torchao(fake_runtime, monkeypatch):
calls = _stub_nvidia_video_offload(monkeypatch, offload = False)
backend = VideoBackend()
status = backend.load_pipeline(
"Wan-AI/Wan2.2-TI2V-5B-Diffusers", model_kind = "pipeline", transformer_quant = "int8"
)
assert status["offload_policy"] == "none"
assert calls and all("offload" not in c and "act_int8" not in c for c in calls)
assert "W8A8" not in status["resolved"]["transformer_quant"]["reason"]
backend.unload()
def test_video_auto_under_offload_on_nvidia_takes_the_torchao_free_int8(fake_runtime, monkeypatch):
calls = _stub_nvidia_video_offload(monkeypatch)
backend = VideoBackend()
status = backend.load_pipeline("Wan-AI/Wan2.2-TI2V-5B-Diffusers", model_kind = "pipeline")
assert [(call["mode"], call["offload"]) for call in calls] == [("int8", True)]
assert status["transformer_quant"] == "int8"
backend.unload()
def test_video_auto_under_offload_on_nvidia_keeps_bf16_under_speed_off(fake_runtime, monkeypatch):
calls = _stub_nvidia_video_offload(monkeypatch)
backend = VideoBackend()
status = backend.load_pipeline(
"Wan-AI/Wan2.2-TI2V-5B-Diffusers", model_kind = "pipeline", speed_mode = "off"
)
assert calls == []
assert status["transformer_quant"] is None
backend.unload()
def test_video_auto_quant_on_a_host_without_dense_quant_reports_as_before(fake_runtime):
status = VideoBackend().load_pipeline(
"Wan-AI/Wan2.2-TI2V-5B-Diffusers", model_kind = "pipeline", speed_mode = "default"
)
resolved = status["resolved"]["transformer_quant"]
assert (resolved["value"], resolved["source"]) == ("off", "auto")
assert resolved["reason"] == "not engaged (dense bf16 DiT loaded)"
def test_video_auto_quant_still_engages_when_the_budget_is_unknown(fake_runtime, monkeypatch):
import dataclasses
import core.inference.video as video_mod
calls = _quant_spy(monkeypatch)
real = video_mod.plan_diffusion_memory
monkeypatch.setattr(
video_mod,
"plan_diffusion_memory",
lambda **kw: dataclasses.replace(
real(**kw),
offload_policy = "none",
estimates = {"safe_device_budget_mib": None, "resident_required_mib": None},
),
)
VideoBackend().load_pipeline(
"Wan-AI/Wan2.2-TI2V-5B-Diffusers", model_kind = "pipeline", speed_mode = "default"
)
assert calls == ["auto"]
def _guided_ltx_call(monkeypatch, pipe):
"""Give the fake pipeline the multimodal-guidance kwargs of LTX2Pipeline.__call__ (diffusers main)."""
original = type(pipe).__call__
def __call__(
self,
*,
stg_scale = 1.0,
modality_scale = 3.0,
guidance_rescale = 0.7,
audio_guidance_scale = 7.0,
audio_stg_scale = 1.0,
audio_modality_scale = 3.0,
audio_guidance_rescale = 0.7,
**kwargs,
):
out = original(self, **kwargs)
self.last_kwargs.update(
stg_scale = stg_scale,
modality_scale = modality_scale,
guidance_rescale = guidance_rescale,
audio_guidance_scale = audio_guidance_scale,
audio_stg_scale = audio_stg_scale,
audio_modality_scale = audio_modality_scale,
audio_guidance_rescale = audio_guidance_rescale,
)
return out
__call__.__signature__ = inspect.Signature(
[inspect.Parameter("self", inspect.Parameter.POSITIONAL_OR_KEYWORD)]
+ [
inspect.Parameter(name, inspect.Parameter.KEYWORD_ONLY, default = None)
for name in (
"prompt",
"negative_prompt",
"num_inference_steps",
"guidance_scale",
"width",
"height",
"num_frames",
"frame_rate",
"generator",
"sigmas",
"callback_on_step_end",
"stg_scale",
"modality_scale",
"guidance_rescale",
"audio_guidance_scale",
"audio_stg_scale",
"audio_modality_scale",
"audio_guidance_rescale",
)
]
)
monkeypatch.setattr(type(pipe), "__call__", __call__)
def test_generate_distilled_turns_multimodal_guidance_off(fake_runtime, tmp_path, monkeypatch):
# Distilled DiT: every #14447 guidance term must be off, else four DiT forwards per step.
backend = _load_ltx23_from_dir(tmp_path)
_guided_ltx_call(monkeypatch, backend._state.pipe)
backend.generate(prompt = "a sloth")
call = backend._state.pipe.last_kwargs
assert call["guidance_scale"] == 1.0
assert call["stg_scale"] == 0.0 and call["audio_stg_scale"] == 0.0
assert call["modality_scale"] == 1.0 and call["audio_modality_scale"] == 1.0
assert call["guidance_rescale"] == 0.0 and call["audio_guidance_rescale"] == 0.0
assert call["audio_guidance_scale"] == 1.0
backend.generate(prompt = "a sloth", guidance = 2.5)
assert backend._state.pipe.last_kwargs["audio_guidance_scale"] == 2.5
def test_generate_dev_keeps_pipeline_guidance_defaults(fake_runtime, tmp_path, monkeypatch):
(tmp_path / "ltx-2.3-22b-dev-Q4_K_M.gguf").write_bytes(b"w")
backend = VideoBackend()
backend.load_pipeline(
str(tmp_path),
gguf_filename = "ltx-2.3-22b-dev-Q4_K_M.gguf",
base_repo = "Lightricks/LTX-2",
family_override = "ltx-2",
)
_guided_ltx_call(monkeypatch, backend._state.pipe)
backend.generate(prompt = "a sloth")
call = backend._state.pipe.last_kwargs
assert call["stg_scale"] == 1.0 and call["audio_guidance_scale"] == 7.0
def test_ltx2_distilled_guidance_kwargs_follow_the_signature():
from core.inference.video_ltx2 import ltx2_distilled_guidance_kwargs
assert ltx2_distilled_guidance_kwargs({"prompt": None, "guidance_scale": None}, 1.0) == {}
full = ltx2_distilled_guidance_kwargs(
{"stg_scale": 0, "modality_scale": 0, "audio_guidance_scale": 0, "guidance_rescale": 0},
None,
)
assert full == {
"stg_scale": 0.0,
"modality_scale": 1.0,
"guidance_rescale": 0.0,
"audio_guidance_scale": 1.0,
}
def test_stg_compile_adapter_hands_the_block_a_python_bool():
torch = pytest.importorskip("torch")
if not hasattr(torch, "nn") or not hasattr(torch, "all"):
pytest.skip("real torch required")
from core.inference.video_ltx2 import install_stg_compile_adapter
seen = []
def compiled(*args, **kwargs):
seen.append(kwargs.get("all_perturbed"))
return "out"
compiled._unsloth_compile_guard = "guard"
block = type("LTX2VideoTransformerBlock", (torch.nn.Module,), {})()
block._compiled_call_impl = compiled
other = torch.nn.Linear(1, 1)
other._compiled_call_impl = compiled
root = torch.nn.ModuleList([block, other])
assert install_stg_compile_adapter(root) == 1
assert install_stg_compile_adapter(root) == 0 # idempotent
assert other._compiled_call_impl is compiled # only LTX-2 blocks
wrapped = block._compiled_call_impl
assert wrapped._unsloth_compile_guard == "guard" # guard_compiled_blocks stays idempotent
assert wrapped(all_perturbed = torch.tensor(True)) == "out"
assert wrapped(all_perturbed = False) == "out"
assert seen == [True, False] and type(seen[0]) is bool
def test_stg_compile_adapter_drops_to_eager_past_the_recompile_limit():
# Past the recompile limit fullgraph raises FailOnRecompileLimitHit; the adapter routes it to eager, other errors propagate.
torch = pytest.importorskip("torch")
limit_hit = getattr(
getattr(getattr(torch, "_dynamo", None), "exc", None), "FailOnRecompileLimitHit", None
)
if not hasattr(torch, "nn") or not isinstance(limit_hit, type):
pytest.skip("real torch with FailOnRecompileLimitHit required")
from core.inference.diffusion_speed import compile_fallback_error, guard_compiled_blocks
from core.inference.video_ltx2 import install_stg_compile_adapter
raised = {"exc": limit_hit("Hard failure due to fullgraph=True")}
class LTX2VideoTransformerBlock(torch.nn.Module):
def forward(self, all_perturbed = False):
return "eager"
def compiled(*args, **kwargs):
raise raised["exc"]
block = LTX2VideoTransformerBlock()
block._compiled_call_impl = compiled
root = torch.nn.ModuleList([block])
assert guard_compiled_blocks(root) == 1
assert install_stg_compile_adapter(root) == 1
raised["exc"] = ValueError("a kernel error, not a compile failure")
with pytest.raises(ValueError):
block(all_perturbed = torch.tensor(False))
assert compile_fallback_error(types.SimpleNamespace(transformer = root)) is None
raised["exc"] = limit_hit("Hard failure due to fullgraph=True")
assert block(all_perturbed = torch.tensor(True)) == "eager"
assert "FailOnRecompileLimitHit" in compile_fallback_error(
types.SimpleNamespace(transformer = root)
)
assert block._compiled_call_impl is None # the whole DiT runs eager for the rest of the load
assert block(all_perturbed = False) == "eager"
def test_ltx2_recompile_limit_reaches_the_render_thread():
# torch >= 2.12 keeps dynamo config per thread context; the render copies the caller's context.
pytest.importorskip("torch")
try:
import torch._dynamo.config as dynamo_cfg
except Exception: # noqa: BLE001
pytest.skip("real torch._dynamo required")
import contextvars
from core.inference.video_ltx2 import LTX2_RECOMPILE_LIMIT, ensure_recompile_limit
seen = {}
def caller():
ensure_recompile_limit()
ctx = contextvars.copy_context()
worker = threading.Thread(
target = lambda: ctx.run(lambda: seen.update(limit = dynamo_cfg.recompile_limit))
)
worker.start()
worker.join()
thread = threading.Thread(target = caller)
thread.start()
thread.join()
assert seen["limit"] >= LTX2_RECOMPILE_LIMIT
def test_precision_gate_admits_fp8_only_for_the_ltx23_prequant_file(fake_runtime, monkeypatch):
# #742: explicit fp8 on the distilled file is served by the hosted DiT; other single files / schemes are still refused.
import core.inference.video as video_mod
monkeypatch.setattr(video_mod, "dense_transformer_supported", lambda target: True)
_ltx23_fp8_card(monkeypatch)
fam = types.SimpleNamespace(name = "ltx-2")
video_mod.assert_video_precision_available(
fam,
model_kind = "single_file",
transformer_quant = "fp8",
checkpoint_filename = "ltx-2.3-22b-distilled.safetensors",
checkpoint_repo = "Lightricks/LTX-2.3",
)
for filename, scheme in (
("ltx-2.3-22b-dev.safetensors", "fp8"),
("ltx-2.3-22b-distilled-1.1.safetensors", "fp8"),
("ltx-2.3-22b-distilled.safetensors", "int8"),
(None, "fp8"),
):
with pytest.raises(RuntimeError, match = "full-pipeline loads only"):
video_mod.assert_video_precision_available(
fam,
model_kind = "single_file",
transformer_quant = scheme,
checkpoint_filename = filename,
checkpoint_repo = "Lightricks/LTX-2.3",
)
with pytest.raises(RuntimeError, match = "offload"):
video_mod.assert_video_precision_available(
fam,
model_kind = "single_file",
transformer_quant = "fp8",
memory_mode = "low_vram",
checkpoint_filename = "ltx-2.3-22b-distilled.safetensors",
checkpoint_repo = "Lightricks/LTX-2.3",
)
def test_ltx23_prequant_source_resolves_the_hosted_fp8_only():
from core.inference.diffusion_prequant import resolve_prequant_source
from core.inference.video_families import detect_video_family
from core.inference.video_ltx2 import LTX23_PREQUANT_BASE
fam = detect_video_family("Lightricks/LTX-2.3")
source = resolve_prequant_source(fam, "fp8", base_repo = LTX23_PREQUANT_BASE)
assert source is not None and source.location == "unsloth/LTX-2.3-FP8"
from core.inference.diffusion_prequant import candidate_filenames_of
assert "LTX-2.3-FP8.pt" in candidate_filenames_of(
source
) # the artifact the repo actually hosts
assert resolve_prequant_source(fam, "int8", base_repo = LTX23_PREQUANT_BASE) is None
# LTX-2 (2.0) resolves its own hosted fp8 file, never the 2.3 one.
ltx2 = resolve_prequant_source(fam, "fp8", base_repo = "Lightricks/LTX-2")
assert ltx2 is not None and ltx2.location == "unsloth/LTX-2-FP8"
def _ltx23_fp8_card(monkeypatch, *, fp8 = True):
"""The explicit fp8 scheme check on the card the load uses: sm_89+ runs fp8, Ampere (sm_80/86) only int8."""
from core.inference import video as video_mod
monkeypatch.setattr(
video_mod, "_ltx23_prequant_scheme_supported", lambda fam, target, pinned: fp8
)
def _ltx23_official_file(monkeypatch):
"""Stand-in 1-byte fixtures pass as the official LTX-2.3 distilled file (identity is tested on its own)."""
from core.inference import video_ltx2
monkeypatch.setattr(video_ltx2, "ltx23_source_file_verified", lambda path: True)
def _ampere_or_hopper(monkeypatch, *, fp8):
"""A CUDA bf16 card with the dense torchao path, whose explicit fp8 passes only on sm_89+: patched at the smoke
probe, under the real scheme selector, so the check under test is the one the normal precision path runs."""
from core.inference import diffusion_transformer_quant as tq, video as video_mod
monkeypatch.setattr(video_mod, "dense_transformer_supported", lambda target: True)
monkeypatch.setattr(tq, "dense_transformer_supported", lambda target: True)
monkeypatch.setattr(
tq,
"_scheme_supported",
lambda scheme, device, unproven_ok = False: scheme != "fp8" or fp8,
)
return types.SimpleNamespace(device = "cuda", dtype = "bfloat16")
@pytest.mark.parametrize("fp8", [False, True], ids = ["sm80", "sm90"])
def test_ltx23_hosted_fp8_seed_requires_fp8_on_the_card(fake_runtime, monkeypatch, fp8):
# Ampere runs torchao int8 but not fp8: the preflight must refuse before the eviction and 19 GB pull.
from core.inference import video as video_mod
target = _ampere_or_hopper(monkeypatch, fp8 = fp8)
fam = types.SimpleNamespace(name = "ltx-2")
name = "ltx-2.3-22b-distilled.safetensors"
repo = "Lightricks/LTX-2.3"
assert (
video_mod._ltx23_prequant_serves(
fam, "single_file", name, "fp8", target = target, memory_mode = None, checkpoint_repo = repo
)
is fp8
)
monkeypatch.setattr(video_mod, "resolve_diffusion_device_target", lambda **kw: target)
assert (
video_mod._ltx23_prequant_serves_on_card(
fam,
"single_file",
name,
"fp8",
memory_mode = None,
gpu_ordinal = None,
checkpoint_repo = repo,
)
is fp8
)
kwargs = dict(
model_kind = "single_file",
transformer_quant = "fp8",
checkpoint_filename = name,
checkpoint_repo = repo,
)
if fp8:
video_mod.assert_video_precision_available(fam, **kwargs)
else:
with pytest.raises(RuntimeError, match = "fp8"):
video_mod.assert_video_precision_available(fam, **kwargs)
def _ltx23_verdict_store(monkeypatch, tmp_path):
"""Point the persisted LTX-2.3 identity verdicts at a per-test file and count full hashes."""
from core.inference import video_ltx2
store = tmp_path / "verdicts" / "ltx23-source-verdicts.json"
monkeypatch.setattr(video_ltx2, "_ltx23_verdicts_path", lambda: store)
hashed: list = []
real_hash = video_ltx2.ltx23_source_sha256
def _counting(path):
hashed.append(str(path))
return real_hash(path)
monkeypatch.setattr(video_ltx2, "ltx23_source_sha256", _counting)
return store, hashed
def _ltx23_synthetic_official(monkeypatch, path):
"""Write a small safetensors-shaped file at *path* and pin the official identity (size and sha256) to it, so the
real check runs against bytes the test controls. Returns (size, the four 1 MiB windows a sampled check read)."""
import hashlib
from core.inference import video_ltx2
header = b'{"__metadata__":{"model_version":"2.3.0"}}'
blob = len(header).to_bytes(8, "little") + header + bytes(range(256)) * (4096 * 6)
path.write_bytes(blob)
sample = 1 << 20
data = 8 + len(header)
offsets = [data + (len(blob) - data) * k // 4 for k in (1, 2, 3)] + [len(blob) - sample]
monkeypatch.setattr(video_ltx2, "LTX23_PREQUANT_SOURCE_SIZE", len(blob))
monkeypatch.setattr(
video_ltx2, "LTX23_PREQUANT_SOURCE_SHA256", hashlib.sha256(blob).hexdigest()
)
return len(blob), offsets
def test_ltx23_local_file_is_substituted_only_when_it_is_the_official_one(tmp_path, monkeypatch):
from core.inference import video_ltx2
_ltx23_verdict_store(monkeypatch, tmp_path)
name = "ltx-2.3-22b-distilled.safetensors"
official = tmp_path / "official"
official.mkdir()
size, offsets = _ltx23_synthetic_official(monkeypatch, official / name)
assert video_ltx2.ltx23_prequant_eligible(name, str(official))
assert video_ltx2.ltx23_prequant_eligible(name, str(official / name))
# One tensor byte changed, inside and outside any sampled window: not served.
outside = offsets[0] - 4096
assert all(not (off <= outside < off + (1 << 20)) for off in offsets)
for where in (offsets[1] + 7, outside, 12):
tuned = tmp_path / f"tuned_{where}"
tuned.mkdir()
blob = bytearray((official / name).read_bytes())
blob[where] ^= 0xFF
(tuned / name).write_bytes(bytes(blob))
assert not video_ltx2.ltx23_prequant_eligible(name, str(tuned)), where
assert not video_ltx2.ltx23_source_file_verified(tuned / name), where
short = tmp_path / "short"
short.mkdir()
(short / name).write_bytes(b"w")
assert not video_ltx2.ltx23_prequant_eligible(name, str(short))
assert not video_ltx2.ltx23_prequant_eligible(name, str(tmp_path / "missing"))
assert size == video_ltx2.LTX23_PREQUANT_SOURCE_SIZE
def test_ltx23_local_verdict_is_hashed_once_and_invalidated_by_a_change(tmp_path, monkeypatch):
import os
from core.inference import video_ltx2
store, hashed = _ltx23_verdict_store(monkeypatch, tmp_path)
name = "ltx-2.3-22b-distilled.safetensors"
path = tmp_path / name
_ltx23_synthetic_official(monkeypatch, path)
assert video_ltx2.ltx23_source_file_verified(path)
assert video_ltx2.ltx23_source_file_verified(path)
assert len(hashed) == 1 and store.is_file()
blob = bytearray(path.read_bytes())
blob[-3] ^= 0xFF
stat = path.stat()
path.write_bytes(bytes(blob))
os.utime(path, ns = (stat.st_atime_ns, stat.st_mtime_ns + 1_000_000_000))
assert not video_ltx2.ltx23_source_file_verified(path)
assert not video_ltx2.ltx23_source_file_verified(path)
assert len(hashed) == 2
# Planning never hashes.
other = tmp_path / "other" / name
other.parent.mkdir()
other.write_bytes(bytes(blob))
with video_ltx2.ltx23_identity_without_hashing():
assert not video_ltx2.ltx23_source_file_verified(path)
assert video_ltx2.ltx23_source_file_verified(other)
assert len(hashed) == 2
def _unreadable(p):
raise OSError("EIO")
monkeypatch.setattr(video_ltx2, "ltx23_source_sha256", _unreadable)
assert not video_ltx2.ltx23_source_file_verified(other)
assert str(other.resolve()) not in video_ltx2._ltx23_read_verdicts()
def test_ltx23_hub_pick_is_substituted_only_from_the_official_repo(tmp_path, monkeypatch):
from core.inference import video_ltx2
name = "ltx-2.3-22b-distilled.safetensors"
cached: dict = {"hit": None}
monkeypatch.setattr(video_ltx2, "_ltx23_hub_cached_file", lambda repo, filename: cached["hit"])
assert video_ltx2.ltx23_prequant_eligible(name, "Lightricks/LTX-2.3")
assert video_ltx2.ltx23_prequant_eligible(f"sub/{name}", "lightricks/ltx-2.3")
for repo in ("someone/LTX-2.3-finetune", "unsloth/LTX-2.3-GGUF", "Lightricks/LTX-2"):
assert not video_ltx2.ltx23_prequant_eligible(name, repo), repo
assert not video_ltx2.ltx23_prequant_eligible(name, None)
assert not video_ltx2.ltx23_prequant_eligible(
"ltx-2.3-22b-dev.safetensors", "Lightricks/LTX-2.3"
)
# Cached: an official-size content-addressed blob is the file, no hashing.
_, hashed = _ltx23_verdict_store(monkeypatch, tmp_path)
blobs = tmp_path / "models--Lightricks--LTX-2.3" / "blobs"
blobs.mkdir(parents = True)
import hub.utils.hf_cache_state as hf_cache_state
monkeypatch.setattr(hf_cache_state, "hf_cache_roots", lambda *a, **k: [tmp_path])
good = blobs / video_ltx2.LTX23_PREQUANT_SOURCE_SHA256
with open(good, "wb") as fh:
extend_sparse(fh, video_ltx2.LTX23_PREQUANT_SOURCE_SIZE) # sparse
snap = tmp_path / "snap"
snap.mkdir()
(snap / name).symlink_to(good)
cached["hit"] = snap / name
assert video_ltx2.ltx23_source_file_verified(snap / name)
assert hashed == []
assert video_ltx2.ltx23_prequant_eligible(name, "Lightricks/LTX-2.3")
elsewhere = tmp_path / "mine" / "models--Lightricks--LTX-2.3" / "blobs"
elsewhere.mkdir(parents = True)
fake = elsewhere / video_ltx2.LTX23_PREQUANT_SOURCE_SHA256
with open(fake, "wb") as fh:
extend_sparse(fh, video_ltx2.LTX23_PREQUANT_SOURCE_SIZE)
(snap / name).unlink()
(snap / name).symlink_to(fake)
monkeypatch.setattr(
video_ltx2, "ltx23_source_sha256", lambda path: hashed.append(path) or "1" * 64
)
assert not video_ltx2.ltx23_source_file_verified(snap / name)
assert hashed
(snap / name).unlink()
(snap / name).symlink_to(good)
bad = blobs / ("0" * 64)
with open(bad, "wb") as fh:
extend_sparse(
fh, video_ltx2.LTX23_PREQUANT_SOURCE_SIZE
) # right size, wrong content (zeros)
(snap / name).unlink()
(snap / name).symlink_to(bad)
monkeypatch.setattr(video_ltx2, "ltx23_source_sha256", lambda path: "0" * 64)
assert not video_ltx2.ltx23_prequant_eligible(name, "Lightricks/LTX-2.3")
def test_ltx23_unverified_same_name_pick_is_refused_not_substituted(
fake_runtime, tmp_path, monkeypatch
):
from core.inference import video as video_mod, video_ltx2
target = _ampere_or_hopper(monkeypatch, fp8 = True)
monkeypatch.setattr(video_mod, "resolve_diffusion_device_target", lambda **kw: target)
monkeypatch.setattr(video_ltx2, "_ltx23_hub_cached_file", lambda repo, filename: None)
fam = types.SimpleNamespace(name = "ltx-2")
name = "ltx-2.3-22b-distilled.safetensors"
local = tmp_path / "local"
local.mkdir()
(local / name).write_bytes(b"a fine-tuned DiT under the official name")
def _check(repo):
video_mod.assert_video_precision_available(
fam,
model_kind = "single_file",
transformer_quant = "fp8",
checkpoint_filename = name,
checkpoint_repo = repo,
)
def _serves(repo):
return video_mod._ltx23_prequant_serves(
fam, "single_file", name, "fp8", target = target, memory_mode = None, checkpoint_repo = repo
)
_check("Lightricks/LTX-2.3")
assert _serves("Lightricks/LTX-2.3")
for repo in (str(local), "someone/LTX-2.3-finetune"):
assert not _serves(repo), repo
with pytest.raises(RuntimeError, match = "could not be verified"):
_check(repo)
def test_ltx23_prequant_loader_keeps_an_unverified_files_own_dit(tmp_path, monkeypatch):
from core.inference import diffusion_prequant, video_ltx2
resolved: list = []
monkeypatch.setattr(
diffusion_prequant, "resolve_prequant_source", lambda *a, **k: resolved.append(1)
)
path = tmp_path / "ltx-2.3-22b-distilled.safetensors"
path.write_bytes(b"w")
fam = types.SimpleNamespace(name = "ltx-2")
assert (
video_ltx2.load_ltx23_prequant_transformer(
fam, "fp8", path, config_repo = "Lightricks/LTX-2", device = "cuda", dtype = None
)
is None
)
assert resolved == []
def _load_ltx23_single_file_fp8(
tmp_path,
monkeypatch,
seeded,
memory_mode = None,
):
from core.inference import video as video_mod, video_ltx2
monkeypatch.setattr(video_mod, "dense_transformer_supported", lambda target: True)
_ltx23_fp8_card(monkeypatch)
monkeypatch.setattr(video_ltx2, "is_ltx23_checkpoint", lambda path: True)
_ltx23_official_file(monkeypatch)
calls: dict = {}
def _prequant(fam, scheme, checkpoint_path, **kwargs):
calls["prequant"] = (scheme, str(checkpoint_path), kwargs.get("config_repo"))
return seeded
def _assemble(checkpoint_path, **kwargs):
calls["override"] = kwargs.get("transformer_override")
return _FakePipeline.from_pretrained("Lightricks/LTX-2")
monkeypatch.setattr(video_ltx2, "load_ltx23_prequant_transformer", _prequant)
monkeypatch.setattr(video_ltx2, "load_ltx23_pipeline", _assemble)
(tmp_path / "ltx-2.3-22b-distilled.safetensors").write_bytes(b"w")
backend = VideoBackend()
backend.load_pipeline(
str(tmp_path),
gguf_filename = "ltx-2.3-22b-distilled.safetensors",
base_repo = "Lightricks/LTX-2",
family_override = "ltx-2",
transformer_quant = "fp8",
memory_mode = memory_mode,
)
return backend, calls
def test_ltx23_single_file_fp8_seeds_the_hosted_denoiser(fake_runtime, tmp_path, monkeypatch):
seeded_dit = object()
source = types.SimpleNamespace(
location = "unsloth/LTX-2.3-FP8", kind = "repo", filename = "LTX-2.3-FP8.pt"
)
backend, calls = _load_ltx23_single_file_fp8(tmp_path, monkeypatch, (seeded_dit, source))
assert calls["prequant"][0] == "fp8" and calls["prequant"][2] == "Lightricks/LTX-2"
assert calls["override"] is seeded_dit
status = backend.status()
assert status["transformer_quant"] == "fp8"
assert "unsloth/LTX-2.3-FP8" in str(status["resolved"]["transformer_quant"])
backend.unload()
def test_ltx23_single_file_fp8_without_a_checkpoint_is_refused(fake_runtime, tmp_path, monkeypatch):
# Refused before the dense assembly loads the 44 GB bf16 DiT.
from core.inference import video_ltx2
assembled = []
monkeypatch.setattr(
video_ltx2, "load_ltx23_pipeline", lambda *a, **k: assembled.append(1), raising = False
)
with pytest.raises(RuntimeError, match = "unsloth/LTX-2.3-FP8"):
_load_ltx23_single_file_fp8(tmp_path, monkeypatch, None)
def test_ltx23_hosted_fp8_fallback_rechecks_unified_memory(fake_runtime, tmp_path, monkeypatch):
from core.inference import video as video_mod
priced = _ltx23_fp8_plan_at(monkeypatch, fits_mib = 10**9)
checked: list = []
monkeypatch.setattr(
video_mod,
"raise_on_unified_memory_shortfall",
lambda plan, **k: checked.append(len(priced)),
)
monkeypatch.setenv("UNSLOTH_DIFFUSION_ALLOW_PRECISION_FALLBACK", "1")
backend, calls = _load_ltx23_single_file_fp8(tmp_path, monkeypatch, None)
assert calls["override"] is None
assert priced[-1] > priced[0]
assert checked and checked[-1] == len(priced)
backend.unload()
def _ltx23_fp8_plan_at(monkeypatch, fits_mib):
"""Card where a DiT priced above fits_mib offloads; returns the DiT sizes the plans used."""
import dataclasses
from core.inference import video as video_mod
monkeypatch.setattr(video_mod, "estimate_safetensors_dense_mib", lambda size_mib: 44_000)
real_plan = video_mod.plan_diffusion_memory
priced: list = []
def _plan(**kwargs):
planned = real_plan(**kwargs)
dit_mib = (kwargs.get("model_dense_mib") or 0) - (kwargs.get("companion_dense_mib") or 0)
priced.append(dit_mib)
if dit_mib > fits_mib:
return dataclasses.replace(planned, offload_policy = "model")
return dataclasses.replace(planned, offload_policy = "none")
monkeypatch.setattr(video_mod, "plan_diffusion_memory", _plan)
return priced
def test_ltx23_single_file_fp8_is_planned_at_the_hosted_dit_size(
fake_runtime, tmp_path, monkeypatch
):
priced = _ltx23_fp8_plan_at(monkeypatch, fits_mib = 30_000)
seeded_dit = object()
source = types.SimpleNamespace(
location = "unsloth/LTX-2.3-FP8", kind = "repo", filename = "LTX-2.3-FP8.pt"
)
backend, calls = _load_ltx23_single_file_fp8(tmp_path, monkeypatch, (seeded_dit, source))
assert calls["override"] is seeded_dit
assert priced and all(mib < 30_000 for mib in priced)
assert backend.status()["transformer_quant"] == "fp8"
backend.unload()
def test_ltx23_single_file_fp8_is_priced_at_the_hosted_artifact_not_the_scaled_file(
fake_runtime, tmp_path, monkeypatch
):
# Priced at the hosted DiT (~18,175 MiB), not file x fp8 factor (~24,200 MiB): budget between the two.
priced = _ltx23_fp8_plan_at(monkeypatch, fits_mib = 20_000)
seeded_dit = object()
source = types.SimpleNamespace(
location = "unsloth/LTX-2.3-FP8", kind = "repo", filename = "LTX-2.3-FP8.pt"
)
backend, calls = _load_ltx23_single_file_fp8(tmp_path, monkeypatch, (seeded_dit, source))
assert calls["override"] is seeded_dit
assert priced and all(18_000 < mib < 20_000 for mib in priced), priced
backend.unload()
def test_ltx23_single_file_fp8_just_under_the_hosted_artifact_still_offloads(
fake_runtime, tmp_path, monkeypatch
):
_ltx23_fp8_plan_at(monkeypatch, fits_mib = 18_000)
with pytest.raises(RuntimeError, match = "offloads the DiT even at fp8 size"):
_load_ltx23_single_file_fp8(tmp_path, monkeypatch, (object(), None))
def test_ltx23_single_file_fp8_that_still_offloads_is_refused_before_the_assembly(
fake_runtime, tmp_path, monkeypatch
):
_ltx23_fp8_plan_at(monkeypatch, fits_mib = 1_000)
with pytest.raises(RuntimeError, match = "offloads the DiT even at fp8 size"):
_load_ltx23_single_file_fp8(tmp_path, monkeypatch, (object(), None))
def test_ltx2_distilled_detection_follows_the_selected_checkpoint():
from core.inference.video_families import default_video_generation_params
from core.inference.video_ltx2 import ltx2_distilled_ids
cases = [
(("ltx-2.3-22b-distilled.safetensors", "Lightricks/LTX-2.3", "Lightricks/LTX-2"), True),
(
("distilled-1.1/ltx-2.3-22b-distilled-1.1-Q4_K_M.gguf", "unsloth/LTX-2.3-GGUF", None),
True,
),
((None, "someone/LTX-2.3-distilled-diffusers", None), True),
(("model.safetensors", "/models/ltx-2.3-distilled", "Lightricks/LTX-2"), True),
(
("ltx-2.3-22b-dev.safetensors", "/models/ltx-2.3-distilled-mirror", "Lightricks/LTX-2"),
False,
),
(("ltx-2.3-22b-dev-Q4_K_M.gguf", "me/ltx-distilled-and-dev", None), False),
((None, "Lightricks/LTX-2", None), False),
(("ltx-2-19b-undistilled.safetensors", "org/ltx", None), False),
]
for ids, distilled in cases:
assert ltx2_distilled_ids(*ids) is distilled, ids
assert (default_video_generation_params(*ids) == (8, 1.0)) is distilled, ids
def test_download_plan_stages_the_hosted_fp8_dit_for_the_ltx23_distilled_single_file(monkeypatch):
# The hosted DiT's repo is staged by the plan, not pulled inline by the load.
_plan_api(
monkeypatch,
{
"Lightricks/LTX-2.3": [
_PlanSibling("ltx-2.3-22b-distilled.safetensors", 46_000_000_000),
_PlanSibling("ltx-2.3-22b-dev.safetensors", 46_000_000_000),
],
"unsloth/LTX-2.3-GGUF": _LTX23_REPO_SIBLINGS,
"unsloth/LTX-2.3-FP8": [
_PlanSibling("LTX-2.3-FP8.pt", 19_057_628_489),
_PlanSibling("LTX-2.3-INT8.pt", 19_000_000_000),
],
"Lightricks/LTX-2": _LTX_BASE_SIBLINGS,
},
)
from core.inference import video as video_mod
supported = [True]
monkeypatch.setattr(video_mod, "dense_transformer_supported", lambda target: supported[0])
_ltx23_fp8_card(monkeypatch)
def _plan(
filename,
quant,
memory_mode = None,
):
return VideoBackend().download_plan(
"Lightricks/LTX-2.3",
gguf_filename = filename,
family_override = "ltx-2",
transformer_quant = quant,
memory_mode = memory_mode,
)
by_repo = {
e["repo_id"]: e for e in _plan("ltx-2.3-22b-distilled.safetensors", "fp8")["entries"]
}
assert by_repo["unsloth/LTX-2.3-FP8"]["files"] == ["LTX-2.3-FP8.pt"]
assert "ltx-2.3-22b-distilled.safetensors" in by_repo["Lightricks/LTX-2.3"]["files"]
for filename, quant in (
("ltx-2.3-22b-distilled.safetensors", None),
("ltx-2.3-22b-distilled.safetensors", "off"),
("ltx-2.3-22b-dev.safetensors", "fp8"),
):
repos = {e["repo_id"] for e in _plan(filename, quant)["entries"]}
assert "unsloth/LTX-2.3-FP8" not in repos, (filename, quant)
for memory_mode in ("balanced", "low_vram"):
repos = {
e["repo_id"]
for e in _plan("ltx-2.3-22b-distilled.safetensors", "fp8", memory_mode)["entries"]
}
assert "unsloth/LTX-2.3-FP8" not in repos, memory_mode
supported[0] = False
repos = {e["repo_id"] for e in _plan("ltx-2.3-22b-distilled.safetensors", "fp8")["entries"]}
assert "unsloth/LTX-2.3-FP8" not in repos
@pytest.mark.parametrize("fp8", [False, True], ids = ["sm80", "sm90"])
def test_download_plan_stages_the_hosted_fp8_dit_only_on_an_fp8_card(monkeypatch, fp8):
_plan_api(
monkeypatch,
{
"Lightricks/LTX-2.3": [
_PlanSibling("ltx-2.3-22b-distilled.safetensors", 46_149_345_038)
],
"unsloth/LTX-2.3-GGUF": _LTX23_REPO_SIBLINGS,
"unsloth/LTX-2.3-FP8": [_PlanSibling("LTX-2.3-FP8.pt", 19_057_628_489)],
"Lightricks/LTX-2": _LTX_BASE_SIBLINGS,
},
)
_ampere_or_hopper(monkeypatch, fp8 = fp8)
plan = VideoBackend().download_plan(
"Lightricks/LTX-2.3",
gguf_filename = "ltx-2.3-22b-distilled.safetensors",
family_override = "ltx-2",
transformer_quant = "fp8",
)
assert ("unsloth/LTX-2.3-FP8" in {e["repo_id"] for e in plan["entries"]}) is fp8
class _StopAfterPrefetch(Exception):
pass
def test_the_ltx23_fp8_load_prefetches_the_hosted_dit_under_its_cancel_event(tmp_path, monkeypatch):
from core.inference import video as video_mod, video_ltx2
(tmp_path / "ltx-2.3-22b-distilled.safetensors").write_bytes(b"w")
backend = VideoBackend()
fetched: list = []
def _fetch(
sources,
hf_token,
*,
cancel_event = None,
local_files_only = False,
scheme = None,
):
fetched.append(([src.location for src in sources], cancel_event, local_files_only))
def _stop(*_a, **_k):
raise _StopAfterPrefetch()
monkeypatch.setattr(video_ltx2, "is_ltx23_checkpoint", lambda path: True)
_ltx23_official_file(monkeypatch)
supported = [True]
monkeypatch.setattr(video_mod, "dense_transformer_supported", lambda target: supported[0])
_ltx23_fp8_card(monkeypatch)
monkeypatch.setattr(backend, "_fetch_denoiser_prequant", _fetch)
monkeypatch.setattr(backend, "_estimate_download_bytes", lambda *a, **k: None)
monkeypatch.setattr(backend, "_predownload_base", _stop)
monkeypatch.setattr(video_mod, "clear_gpu_cache", lambda: None)
cancel = threading.Event()
backend._load_token = 7
backend._loading = types.SimpleNamespace(asset_repos = (), base_repo = None, expected_bytes = None)
backend._run_load(
repo_id = str(tmp_path),
gguf_filename = "ltx-2.3-22b-distilled.safetensors",
family_override = "ltx-2",
transformer_quant = "fp8",
local_files_only = True,
_load_token = 7,
_cancel_event = cancel,
)
assert fetched == [(["unsloth/LTX-2.3-FP8"], cancel, True)]
fetched.clear()
backend._load_token = 8
backend._run_load(
repo_id = str(tmp_path),
gguf_filename = "ltx-2.3-22b-distilled.safetensors",
family_override = "ltx-2",
local_files_only = True,
_load_token = 8,
_cancel_event = cancel,
)
assert fetched == []
for token, memory_mode, card_ok in (
(9, "balanced", True),
(10, "low_vram", True),
(11, None, False),
):
supported[0] = card_ok
backend._load_token = token
backend._run_load(
repo_id = str(tmp_path),
gguf_filename = "ltx-2.3-22b-distilled.safetensors",
family_override = "ltx-2",
transformer_quant = "fp8",
memory_mode = memory_mode,
local_files_only = True,
_load_token = token,
_cancel_event = cancel,
)
assert fetched == [], (memory_mode, card_ok)
def test_ltx23_fp8_under_a_forced_offload_prices_and_loads_the_bf16_dit(
fake_runtime, tmp_path, monkeypatch
):
# balanced offloads regardless of size, so fallback runs bf16 and never seeds.
monkeypatch.setenv("UNSLOTH_DIFFUSION_ALLOW_PRECISION_FALLBACK", "1")
priced = _ltx23_fp8_plan_at(monkeypatch, fits_mib = 100_000)
backend, calls = _load_ltx23_single_file_fp8(
tmp_path, monkeypatch, (object(), None), memory_mode = "balanced"
)
assert "prequant" not in calls and calls["override"] is None
assert priced and all(mib >= 40_000 for mib in priced)
backend.unload()
def test_ltx23_selective_read_skips_the_dit(tmp_path):
torch = pytest.importorskip("torch")
safetensors_torch = pytest.importorskip("safetensors.torch")
if not hasattr(torch, "zeros"):
pytest.skip("real torch required")
from core.inference.video_ltx2 import _load_checkpoint_without_dit, _split_checkpoint
state = {
"model.diffusion_model.transformer_blocks.0.attn1.to_q.weight": torch.zeros(2, 2),
"model.diffusion_model.video_embeddings_connector.x": torch.ones(1),
"vae.decoder.conv_in.weight": torch.ones(2),
"audio_vae.decoder.w": torch.ones(3),
"vocoder.w": torch.ones(4),
}
path = tmp_path / "ltx.safetensors"
safetensors_torch.save_file(state, str(path))
partial = _load_checkpoint_without_dit(path)
assert "model.diffusion_model.transformer_blocks.0.attn1.to_q.weight" not in partial
groups = _split_checkpoint(partial)
assert groups["dit"] == {} and set(groups["connectors"]) == {"video_embeddings_connector.x"}
assert list(groups["vae"]) == ["decoder.conv_in.weight"] and list(groups["vocoder"]) == ["w"]
assert _load_checkpoint_without_dit(tmp_path / "ltx.gguf") is None
def test_ltx2_regional_compile_is_static(fake_runtime, tmp_path, monkeypatch):
from core.inference.diffusion_speed import compile_dynamic
dit = types.SimpleNamespace()
monkeypatch.setattr(_FakePipe, "transformer", dit, raising = False)
_load_ltx23_from_dir(tmp_path)
assert getattr(dit, "_unsloth_compile_static", False) is True
assert compile_dynamic(dit, True) is False
assert compile_dynamic(types.SimpleNamespace(), True) is True
def test_ltx2_compiled_load_installs_the_stg_adapter(fake_runtime, tmp_path, monkeypatch):
from core.inference import video as video_mod, video_ltx2
dit = types.SimpleNamespace()
monkeypatch.setattr(_FakePipe, "transformer", dit, raising = False)
adapted = []
monkeypatch.setattr(video_ltx2, "install_stg_compile_adapter", lambda t: adapted.append(t) or 0)
for compiled, expected in ((True, [dit]), (False, [])):
adapted.clear()
monkeypatch.setattr(
video_mod, "apply_speed_optims", lambda *a, _c = compiled, **k: {"compiled": _c}
)
_load_ltx23_from_dir(tmp_path)
assert adapted == expected
def test_ltx2_load_turns_cudnn_benchmark_back_off(fake_runtime, tmp_path, monkeypatch):
from core.inference import video as video_mod, video_ltx2
monkeypatch.setattr(
video_mod,
"apply_speed_optims",
lambda *a, **k: {"cudnn_benchmark": True, "compiled": False},
)
calls = []
monkeypatch.setattr(video_ltx2, "disable_cudnn_benchmark", lambda: calls.append(1) or True)
backend = _load_ltx23_from_dir(tmp_path)
assert calls == [1]
assert "cudnn_benchmark" not in backend.status()["speed_optims"]
def test_wan_load_turns_cudnn_benchmark_back_off(fake_runtime, monkeypatch):
# cudnn.benchmark's per-process conv pick made two servers decode the same Wan latents differently.
from core.inference import video as video_mod, video_ltx2
monkeypatch.setattr(
video_mod,
"apply_speed_optims",
lambda *a, **k: {"cudnn_benchmark": True, "compiled": False},
)
calls = []
monkeypatch.setattr(video_ltx2, "disable_cudnn_benchmark", lambda: calls.append(1) or True)
backend = VideoBackend()
status = backend.load_pipeline("Wan-AI/Wan2.2-TI2V-5B-Diffusers", model_kind = "pipeline")
assert status["family"] == "wan2.2-ti2v-5b"
assert calls == [1]
assert "cudnn_benchmark" not in backend.status()["speed_optims"]
def test_cudnn_benchmark_opt_out_families():
# Every family on the Wan or HunyuanVideo-1.5 VAE opts out (reproducibility), LTX-2 keeps its re-tune opt-out.
from core.inference.video_families import _FAMILIES
off = {fam.name for fam in _FAMILIES if not fam.cudnn_benchmark}
assert {
"wan2.2-ti2v-5b",
"wan2.2-t2v-a14b",
"ltx-2",
"ltx-2.5",
"hunyuanvideo-1.5",
"hunyuanvideo-1.5-720p",
} <= off
assert all(
fam.vae_force_fp32
or fam.name in ("ltx-2", "ltx-2.5")
or fam.name.startswith("hunyuanvideo-1.5")
or fam.name.startswith("cosmos3-")
for fam in _FAMILIES
if not fam.cudnn_benchmark
)
def test_hunyuanvideo15_load_keeps_cudnn_benchmark_off(fake_runtime, monkeypatch):
from core.inference import video as video_mod, video_ltx2
seen = []
def fake_speed(view, target, **kw):
seen.append(getattr(kw.get("family"), "cudnn_benchmark", True))
return {"cudnn_benchmark": True, "compiled": False}
monkeypatch.setattr(video_mod, "apply_speed_optims", fake_speed)
calls = []
monkeypatch.setattr(video_ltx2, "disable_cudnn_benchmark", lambda: calls.append(1) or True)
backend = VideoBackend()
status = backend.load_pipeline(
"hunyuanvideo-community/HunyuanVideo-1.5-Diffusers-480p_t2v", model_kind = "pipeline"
)
assert status["family"] == "hunyuanvideo-1.5"
assert seen and seen[0] is False
assert calls == [1]
assert "cudnn_benchmark" not in backend.status()["speed_optims"]
@pytest.mark.parametrize(
"plan_fields, filename, direct, te_direct",
[
({"offload_policy": "none"}, "ltx-2.3-22b-distilled.safetensors", True, True),
(
{"offload_policy": "group", "stream_transformer": False, "stream_text_encoders": True},
"ltx-2.3-22b-distilled.safetensors",
True,
False,
),
(
{"offload_policy": "group", "stream_transformer": True},
"ltx-2.3-22b-distilled.safetensors",
False,
False,
),
({"offload_policy": "model"}, "ltx-2.3-22b-distilled.safetensors", False, False),
({"offload_policy": "none"}, "ltx-2.3-22b-distilled-1.1-Q4_K_M.gguf", False, False),
],
ids = ["resident", "streamed-encoders", "streamed-dit", "model-offload", "gguf"],
)
def test_ltx23_reads_the_checkpoint_onto_the_card_only_for_a_resident_dit(
fake_runtime, tmp_path, monkeypatch, plan_fields, filename, direct, te_direct
):
# Direct read only for resident DiT plans; moving the DiT or GGUF keeps the host load.
import dataclasses
from core.inference import video as video_mod, video_ltx2
monkeypatch.setattr(video_ltx2, "is_ltx23_checkpoint", lambda path: True)
_ltx23_official_file(monkeypatch)
sentinel = object()
asked: list = []
def _device(device):
asked.append(device)
return sentinel
monkeypatch.setattr(video_ltx2, "direct_load_device", _device)
real_plan = video_mod.plan_diffusion_memory
monkeypatch.setattr(
video_mod,
"plan_diffusion_memory",
lambda **kwargs: dataclasses.replace(real_plan(**kwargs), **plan_fields),
)
seen: dict = {}
def _assemble(checkpoint_path, **kwargs):
seen.update(kwargs)
return _FakePipeline.from_pretrained("Lightricks/LTX-2")
monkeypatch.setattr(video_ltx2, "load_ltx23_pipeline", _assemble)
monkeypatch.setattr(video_mod, "_return_direct_loaded_modules", lambda *a, **k: None)
monkeypatch.setattr(
video_mod, "apply_memory_plan", lambda pipe, plan, **k: (plan.offload_policy, True)
)
(tmp_path / filename).write_bytes(b"w")
backend = VideoBackend()
backend.load_pipeline(
str(tmp_path),
gguf_filename = filename,
base_repo = "Lightricks/LTX-2",
family_override = "ltx-2",
)
assert seen["device"] is (sentinel if direct else None)
assert seen["text_encoder_device"] is (sentinel if te_direct else None)
assert bool(asked) is direct
backend.unload()
def _cuda_wan_load(monkeypatch, *, policy, speed_mode):
"""Load Wan2.2-TI2V-5B on a stubbed CUDA target with ``apply_memory_plan`` returning ``policy``."""
torch = sys.modules["torch"]
monkeypatch.setattr(
torch,
"cuda",
types.SimpleNamespace(is_available = lambda: False, synchronize = lambda: None),
raising = False,
)
monkeypatch.setattr(
"core.inference.video.resolve_diffusion_device_target",
lambda: DiffusionDeviceTarget(
device = "cuda",
dtype = torch.bfloat16,
backend = "cuda",
vendor = None,
supports_model_cpu_offload = False,
supports_default_torch_compile = False,
supports_pinned_transfer = False,
),
)
monkeypatch.setattr(
"core.inference.video.settled_snapshot_device_memory", _fits_in_memory_snapshot("cuda")
)
_stub_apply_memory_plan(monkeypatch, video_module, policy = policy, vae_tiling = True)
backend = VideoBackend()
return backend.load_pipeline(
"Wan-AI/Wan2.2-TI2V-5B-Diffusers", model_kind = "pipeline", speed_mode = speed_mode
)
@pytest.mark.parametrize(
"policy,speed_mode,installed",
[
("none", "default", True),
("model", "default", True),
("group", "default", True),
("streaming", "default", True),
("sequential", "default", False),
("none", "off", False),
("group", "off", False),
],
)
def test_resident_wan_load_decodes_untiled_when_it_fits(
fake_runtime, monkeypatch, policy, speed_mode, installed
):
from core.inference import video_vae_untiled
calls = []
monkeypatch.setattr(
video_vae_untiled,
"install_untiled_decode",
lambda pipe, family, logger = None: calls.append(family) or True,
)
status = _cuda_wan_load(monkeypatch, policy = policy, speed_mode = speed_mode)
assert status["loaded"] is True
assert calls == (["wan2.2-ti2v-5b"] if installed else [])
assert ("vae_untiled_when_fits" in status["speed_optims"]) is installed
def test_previewer_is_finished_when_the_render_fails_before_its_loop(fake_runtime, monkeypatch):
# A raise between creating the previewer thread and the guarded render leaked it.
import core.inference.diffusion_nvfp4_protect as protect_mod
import core.inference.diffusion_preview as preview_mod
_patch_events(monkeypatch)
started: list = []
class _Previewer:
finished = False
def on_step(self, *args, **kwargs):
pass
def finish(self):
self.finished = True
def _create(**kwargs):
started.append(_Previewer())
return started[-1]
def _refuse(*args, **kwargs):
raise RuntimeError("protect refused")
monkeypatch.setattr(preview_mod.LatentPreviewer, "create", staticmethod(_create))
monkeypatch.setattr(protect_mod, "protect_generation", _refuse)
backend = VideoBackend()
backend.load_pipeline(
"hunyuanvideo-community/HunyuanVideo-1.5-Diffusers-480p_t2v", model_kind = "pipeline"
)
with pytest.raises(RuntimeError, match = "protect refused"):
backend.generate(prompt = "a fox", steps = 3, num_frames = 9, fps = 24)
assert all(p.finished for p in started)
def test_h3_modular_single_file_from_an_untrusted_repo_checks_the_header_first(
fake_runtime, tmp_path, monkeypatch
):
# The modular H3 branch returns before the generic single-file check, so it validates the header itself.
import pickle
bogus = tmp_path / "minimax_h3_fp8.safetensors"
bogus.write_bytes(pickle.dumps({"weights": 1}))
reached = []
diffusers = sys.modules["diffusers"]
monkeypatch.setattr(diffusers, "ModularPipeline", _FakeModularPipeline, raising = False)
monkeypatch.setattr(diffusers, "ComponentsManager", _FakeComponentsManager, raising = False)
monkeypatch.setattr(diffusers, "MiniMaxH3Transformer3DModel", _FakeTransformer, raising = False)
monkeypatch.setattr(
VideoBackend, "_resolve_checkpoint_path", lambda self, *args, **kwargs: bogus
)
monkeypatch.setattr(
VideoBackend,
"_load_h3_modular_pipeline",
lambda self, **kwargs: reached.append(kwargs["comfy_checkpoint"]),
)
with pytest.raises(ValueError, match = "not a valid safetensors checkpoint"):
VideoBackend().load_pipeline(
"someone/minimax-h3-repack",
gguf_filename = bogus.name,
family_override = "minimax-h3",
)
assert reached == []
def test_untrusted_a14b_pair_checks_the_partner_files_header_too(
fake_runtime, tmp_path, monkeypatch
):
# Both experts come from the untrusted repo, so the partner is validated like the picked file.
import json
import pickle
high = tmp_path / "wan2.2_t2v_high_noise_14B_fp8_scaled.safetensors"
low = tmp_path / "wan2.2_t2v_low_noise_14B_fp8_scaled.safetensors"
raw = json.dumps({"w": {"dtype": "F32", "shape": [1], "data_offsets": [0, 4]}}).encode()
high.write_bytes(len(raw).to_bytes(8, "little") + raw + b"\x00\x00\x80\x3f")
low.write_bytes(pickle.dumps({"weights": 1}))
monkeypatch.setattr(VideoBackend, "_resolve_checkpoint_path", lambda self, *a, **k: high)
monkeypatch.setattr(VideoBackend, "_resolve_moe_partner_path", lambda self, *a, **k: low)
with pytest.raises(ValueError, match = "not a valid safetensors checkpoint"):
VideoBackend().load_pipeline(
"someone/wan-a14b-repack",
gguf_filename = high.name,
base_repo = "Wan-AI/Wan2.2-T2V-A14B-Diffusers",
family_override = "wan2.2-t2v-a14b",
)
def test_a_diffusers_without_the_i2v_class_reports_no_first_frame(fake_runtime):
# The fake diffusers has WanPipeline but no WanImageToVideoPipeline: the picker must not offer
# a start frame, and a request carrying one is refused before it reserves the backend.
backend = VideoBackend()
status = backend.load_pipeline("Wan-AI/Wan2.2-TI2V-5B-Diffusers", model_kind = "pipeline")
assert status["supports_first_frame"] is False
with pytest.raises(ValueError, match = "WanImageToVideoPipeline"):
backend.begin_generate(prompt = "p", first_frame = _data_url(64, 64))
assert backend.generate_progress()["active"] is False
def test_an_automatic_encoder_pick_that_does_not_engage_loads_dense_without_a_refusal(
fake_runtime, monkeypatch
):
"""Wan's unset request resolves to the hosted fp8 encoder; if nothing engages, the load stays
dense and reports the raw request, but explicit fp8 is still refused."""
import core.inference.diffusion_precision as precision
import core.inference.diffusion_te_prequant as tpq
import core.inference.video as video_mod
monkeypatch.delenv("UNSLOTH_DIFFUSION_ALLOW_PRECISION_FALLBACK", raising = False)
monkeypatch.setattr(precision, "te_quant_supported", lambda target, mode: True)
monkeypatch.setattr(tpq, "te_prequant_pipe_kwargs", lambda *a, **k: {})
seen = []
def _quantize(pipe, target, *, mode, **kw):
seen.append(mode)
return precision.TEQuantOutcome(None, "no text encoder could be cast", "unsupported")
monkeypatch.setattr(video_mod, "quantize_text_encoders", _quantize)
backend = VideoBackend()
status = backend.load_pipeline("Wan-AI/Wan2.2-TI2V-5B-Diffusers", model_kind = "pipeline")
# No hosted file injected: the automatic pick keeps the released encoder instead of casting it at runtime.
assert [precision.normalize_te_quant(m) for m in seen] == [None]
assert status["resolved"]["text_encoder_quant"]["requested"] in (None, "auto")
backend.unload()
seen.clear()
status = VideoBackend().load_pipeline(
"Wan-AI/Wan2.2-TI2V-5B-Diffusers", model_kind = "pipeline", text_encoder_quant = "none"
)
assert [precision.normalize_te_quant(m) for m in seen] == [None]
with pytest.raises(RuntimeError, match = "text_encoder_quant"):
VideoBackend().load_pipeline(
"Wan-AI/Wan2.2-TI2V-5B-Diffusers", model_kind = "pipeline", text_encoder_quant = "fp8"
)
@pytest.mark.parametrize(
"split_expected, hooked, moved",
[
(
True,
True,
True,
), # the split fell back to a hooked one-card placement: the compile moves below the hooks
(True, False, False), # the split landed resident: nothing to move
(
False,
True,
True,
), # planned offloaded: the compile still moves below the hooks (no split at them)
(False, False, False), # planned offloaded but nothing landed hooked: nothing to move
],
)
def test_a_layer_split_fallback_moves_the_compile_below_the_offload_hooks(
fake_runtime, tmp_path, monkeypatch, split_expected, hooked, moved
):
import core.inference.video as video_mod
_shared_setup_7(monkeypatch, video_mod)
_stub_apply_memory_plan(monkeypatch, video_mod, policy = "model")
monkeypatch.setattr(
video_mod, "_layer_split_expected", lambda pipe, plan, refine = None: split_expected
)
monkeypatch.setattr(video_mod, "_video_denoiser_hooked", lambda pipe: hooked)
seen = []
monkeypatch.setattr(
video_mod,
"compile_pipe_below_offload_hooks",
lambda pipe, logger = None: seen.append(pipe) or 0,
)
speed_offload = []
from core.inference import diffusion_autoopt as autoopt
real_speed = autoopt.run_speed_layer
def _speed(view, target, **kw):
speed_offload.append(kw.get("offload_active"))
return real_speed(view, target, **kw)
monkeypatch.setattr(autoopt, "run_speed_layer", _speed)
backend = VideoBackend()
_load_gguf(backend, tmp_path)
assert speed_offload and set(speed_offload) == {not split_expected}
assert (seen == [backend._state.pipe]) if moved else (seen == [])
@pytest.mark.parametrize("te_scheme, encoder_gb", [(None, 66.8), ("int8", 27.2)])
def test_h3_unified_guard_prices_the_hosted_conditioner(
fake_runtime, monkeypatch, te_scheme, encoder_gb
):
import core.inference.video as video_mod
from core.inference.video_families import detect_video_family
seen = {}
def capture(**kwargs):
seen.update(kwargs)
return object()
monkeypatch.setattr(video_mod, "plan_diffusion_memory", capture)
monkeypatch.setattr(video_mod, "settled_snapshot_device_memory", lambda _target: None)
monkeypatch.setattr(video_mod, "raise_on_unified_memory_shortfall", lambda *_a, **_kw: None)
fam = detect_video_family("MiniMaxAI/MiniMax-H3")
VideoBackend._raise_on_modular_unified_shortfall(
fam,
target = None,
dtype = sys.modules["torch"].bfloat16,
device = "cuda",
memory_mode = None,
scheme = "fp8",
te_scheme = te_scheme,
)
assert seen["model_dense_mib"] == int((20.3 + encoder_gb + 11.1) * 1000**3 / 1024**2)
@pytest.mark.parametrize(
"te_request, source, encoder_gb",
[
(None, "MiniMaxAI/MiniMax-H3", 27.2),
("int8", "MiniMaxAI/MiniMax-H3", 27.2),
("none", "MiniMaxAI/MiniMax-H3", 66.8),
("int8", "someone/MiniMax-H3", 66.8),
("int8", None, 66.8),
],
)
def test_h3_unified_preflight_uses_the_seeded_encoder_provenance(
fake_runtime, monkeypatch, te_request, source, encoder_gb
):
import core.inference.video as video_mod
class ReachedPreflight(Exception):
pass
seen = {}
def capture(**kwargs):
seen.update(kwargs)
raise ReachedPreflight
pipe = types.SimpleNamespace(
get_component_spec = lambda _name: types.SimpleNamespace(
pretrained_model_name_or_path = source
),
)
diffusers = types.SimpleNamespace(
ComponentsManager = lambda: object(),
ModularPipeline = types.SimpleNamespace(from_pretrained = lambda *_a, **_kw: pipe),
)
monkeypatch.setattr(video_mod, "_h3_auto_precision_ok", lambda _target: True)
monkeypatch.setattr(video_mod, "plan_diffusion_memory", capture)
monkeypatch.setattr(video_mod, "settled_snapshot_device_memory", lambda _target: None)
fam = _detect_load_family("MiniMaxAI/MiniMax-H3", None, "minimax-h3")
with pytest.raises(ReachedPreflight):
VideoBackend()._load_h3_modular_pipeline(
diffusers = diffusers,
torch = sys.modules["torch"],
fam = fam,
repo_id = fam.base_repo,
base = fam.base_repo,
kind = "pipeline",
dtype = sys.modules["torch"].bfloat16,
device = "cuda",
hf_token = None,
memory_mode = None,
transformer_quant = "fp8",
text_encoder_quant = te_request,
target = types.SimpleNamespace(device = "cuda"),
)
assert seen["model_dense_mib"] == int((20.3 + encoder_gb + 11.1) * 1000**3 / 1024**2)
def test_h3_unified_quantized_components_still_refuse_a_spark_sized_pool(fake_runtime, monkeypatch):
import core.inference.video as video_mod
from core.inference.diffusion_memory import DeviceMemory
fam = _detect_load_family("MiniMaxAI/MiniMax-H3", None, "minimax-h3")
memory = DeviceMemory("cuda", "cuda", "unified_memory", 45 * 1024, 54 * 1024)
monkeypatch.setattr(video_mod, "settled_snapshot_device_memory", lambda _target: memory)
with pytest.raises(RuntimeError, match = "unified memory") as exc:
VideoBackend._raise_on_modular_unified_shortfall(
fam,
target = types.SimpleNamespace(device = "cuda", supports_model_cpu_offload = True),
dtype = sys.modules["torch"].bfloat16,
device = "cuda",
memory_mode = None,
scheme = "fp8",
te_scheme = "int8",
)
assert "57 GB" in str(exc.value)
# A larger unified pool can load the quantized pair even though the old 93 GiB estimate refused it.
monkeypatch.setattr(video_mod, "settled_snapshot_device_memory", _unified_snapshot(128))
VideoBackend._raise_on_modular_unified_shortfall(
fam,
target = types.SimpleNamespace(device = "mps", supports_model_cpu_offload = True),
dtype = sys.modules["torch"].bfloat16,
device = "mps",
memory_mode = None,
scheme = "fp8",
te_scheme = "int8",
)
@pytest.mark.parametrize("total_gib, fallback_fits", [(128, False), (160, True)])
def test_h3_unified_guard_reruns_before_a_failed_hosted_encoder_goes_dense(
fake_runtime, monkeypatch, total_gib, fallback_fits
):
import core.inference.video as video_mod
import core.inference.diffusion_prequant as prequant_mod
import core.inference.video_minimax_h3_te as te_mod
from core.inference.diffusion_memory import DeviceMemory
calls = []
snapshots = []
initial_memory = _unified_snapshot(total_gib)(None)
free_mib = initial_memory.free_mib
def snapshot(_target):
memory = DeviceMemory("mps", "mps", "unified_memory", free_mib, initial_memory.total_mib)
snapshots.append(memory)
return memory
def seed_transformer(*_a, **_kw):
nonlocal free_mib
free_mib -= int(20.3 * 1000**3 / 1024**2)
return object()
class ReachedComponents(Exception):
pass
real = VideoBackend._raise_on_modular_unified_shortfall
def spy(fam, **kwargs):
calls.append((kwargs["scheme"], kwargs["te_scheme"], kwargs["device_memory"]))
return real(fam, **kwargs)
class Pipe:
def get_component_spec(self, _name):
return types.SimpleNamespace(pretrained_model_name_or_path = "MiniMaxAI/MiniMax-H3")
def update_components(self, **kwargs):
for name, value in kwargs.items():
setattr(self, name, value)
def load_components(self, **kwargs):
if not fallback_fits:
pytest.fail("dense components must not be opened before the fallback memory check")
raise ReachedComponents
diffusers = types.SimpleNamespace(
ComponentsManager = lambda: object(),
ModularPipeline = types.SimpleNamespace(from_pretrained = lambda *_a, **_kw: Pipe()),
MiniMaxH3Transformer3DModel = object,
)
monkeypatch.setattr(VideoBackend, "_raise_on_modular_unified_shortfall", staticmethod(spy))
monkeypatch.setattr(video_mod, "settled_snapshot_device_memory", snapshot)
monkeypatch.setattr(video_mod, "precision_fallback_allowed", lambda: True)
monkeypatch.setattr(
prequant_mod,
"resolve_prequant_source",
lambda *_a, **_kw: types.SimpleNamespace(location = "unsloth/MiniMax-H3-FP8"),
)
monkeypatch.setattr(prequant_mod, "load_prequantized_transformer", seed_transformer)
monkeypatch.setattr(te_mod, "load_h3_quantized_text_encoder", lambda *_a, **_kw: None)
fam = _detect_load_family("MiniMaxAI/MiniMax-H3", None, "minimax-h3")
expected = (
pytest.raises(ReachedComponents)
if fallback_fits
else pytest.raises(RuntimeError, match = "unified memory")
)
with expected:
VideoBackend()._load_h3_modular_pipeline(
diffusers = diffusers,
torch = sys.modules["torch"],
fam = fam,
repo_id = fam.base_repo,
base = fam.base_repo,
kind = "pipeline",
dtype = sys.modules["torch"].bfloat16,
device = "mps",
hf_token = None,
memory_mode = None,
transformer_quant = "fp8",
text_encoder_quant = "int8",
target = types.SimpleNamespace(device = "mps", supports_model_cpu_offload = True),
)
# Seeded weights reduce current free RAM, but both checks price the FULL model against the original pool.
assert free_mib < initial_memory.free_mib
assert snapshots == [initial_memory]
assert calls == [("fp8", "int8", initial_memory), ("fp8", None, initial_memory)]
def _png_data_url(width = 64, height = 64):
import base64
import io
from PIL import Image
buffer = io.BytesIO()
Image.new("RGB", (width, height), (10, 20, 30)).save(buffer, "PNG")
return "data:image/png;base64," + base64.b64encode(buffer.getvalue()).decode("ascii")
def test_h3_render_reuses_the_audio_the_route_already_decoded(monkeypatch):
"""The readability check's decode is handed to the render only for the same inputs."""
pytest.importorskip("av")
import numpy as np
from core.inference import video_minimax_h3 as h3
from core.inference.video import VideoBackend
from core.inference.video_families import detect_video_family
from routes.video import _refuse_unreadable_audio
first = _data_url_wav(seconds = 1.0, rate = 32_000)
second = _data_url_wav(seconds = 2.0, rate = 32_000)
real_decode = h3.decode_h3_reference_audio
calls = []
def counting_decode(*args, **kwargs):
calls.append(1)
return real_decode(*args, **kwargs)
monkeypatch.setattr(h3, "decode_h3_reference_audio", counting_decode)
def resolve(audios, decoded):
return VideoBackend._resolve_references(
detect_video_family("MiniMaxAI/MiniMax-H3", None),
"ref2va",
"diffusers",
[_png_data_url()],
None,
audios,
"match",
960,
544,
decoded_audios = decoded,
)
checked = _refuse_unreadable_audio([first])
assert len(calls) == 1
reused = resolve([first], checked)
assert len(calls) == 1
fresh = resolve([first], None)
assert len(calls) == 2
(reused_wave, reused_rate), (fresh_wave, fresh_rate) = reused.audios[0], fresh.audios[0]
assert reused_rate == fresh_rate == 32_000
assert reused_wave.dtype == fresh_wave.dtype
assert np.array_equal(reused_wave, fresh_wave)
# Different inputs than the check saw: decoded afresh, never the stale waveform.
other = resolve([second], checked)
assert len(calls) == 3
assert other.audios[0][0].shape[0] == 64_000
assert _refuse_unreadable_audio(None) is None
def test_h3_reference_video_frames_are_rgb_without_an_extra_copy(monkeypatch):
pytest.importorskip("av")
from PIL import Image
from core.inference import video_minimax_h3 as h3
converts = []
real_convert = Image.Image.convert
def counting_convert(self, *args, **kwargs):
converts.append(self.mode)
return real_convert(self, *args, **kwargs)
monkeypatch.setattr(Image.Image, "convert", counting_convert)
from core.inference.video import _decode_b64_media
blob = _decode_b64_media(_reference_video_data_url(seconds = 3.0, with_audio = False))
frames, _, _ = h3.decode_h3_reference_video(blob, decode_audio = False)
assert frames and all(frame.mode == "RGB" for frame in frames)
assert converts == []
def test_h3_staged_reference_frames_match_one_save_per_frame(tmp_path):
"""Repeated frame objects (24 fps upsampling) and the writer threads leave the files a plain loop writes."""
import hashlib
from PIL import Image
from core.inference import video_minimax_h3 as h3
distinct = [
Image.new("RGB", (64, 48), (index * 9 % 256, index, 255 - index)) for index in range(7)
]
frames = [distinct[index // 2] for index in range(13)] + [distinct[0]]
(tmp_path / "head").mkdir()
staged = h3.stage_h3_references(
h3.MiniMaxH3References(videos = ((frames, None, None),)), tmp_path / "head"
)
expected = tmp_path / "expected"
expected.mkdir()
for frame_index, frame in enumerate(frames):
frame.save(expected / f"{frame_index:05d}.png", format = "PNG", compress_level = 1)
directory = tmp_path / "head" / "ref-video-00"
assert staged.videos == (str(directory),)
names = sorted(path.name for path in directory.iterdir())
assert names == sorted(path.name for path in expected.iterdir())
for name in names:
assert (
hashlib.sha256((directory / name).read_bytes()).digest()
== hashlib.sha256((expected / name).read_bytes()).digest()
)
def test_h3_staged_reference_frames_raise_the_first_failure_in_frame_order(tmp_path, monkeypatch):
from PIL import Image
from core.inference import video_minimax_h3 as h3
frames = [Image.new("RGB", (16, 16), (index, 0, 0)) for index in range(8)]
real_save = Image.Image.save
def failing_save(self, fp, *args, **kwargs):
if self.getpixel((0, 0))[0] in (3, 6):
raise OSError(f"disk full at {self.getpixel((0, 0))[0]}")
return real_save(self, fp, *args, **kwargs)
monkeypatch.setattr(Image.Image, "save", failing_save)
with pytest.raises(OSError, match = "disk full at 3"):
h3.stage_h3_references(h3.MiniMaxH3References(videos = ((frames, None, None),)), tmp_path)