Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.
Python agentaichatgptdeepseekfine-tuninggemmaimage-generationllamallmllmsopenaipythonqwenreinforcement-learningself-hostedstable-diffusiontext-to-speechttsuiunsloth
Studio: load LTX-2 and LTX-2.3 on the pinned transformers 5.5 (#12299)
Daniel Han894fc7ff5de1
diff --git a/studio/backend/core/inference/diffusion_families.py b/studio/backend/core/inference/diffusion_families.pyindex b05a138f057..e1c6c61dcdb 100644--- a/studio/backend/core/inference/diffusion_families.py+++ b/studio/backend/core/inference/diffusion_families.py@@ -1492,7 +1492,13 @@ def assert_pipeline_class_available(passtry:+ # diffusers' LTX-2 modules import a transformers class the pinned transformers lacks; see ltx2_import_compat.+ from .ltx2_import_compat import ensure_ltx2_pipelines_importable, is_ltx2_pipeline_class++ if is_ltx2_pipeline_class(pipeline_class):+ ensure_ltx2_pipelines_importable()import diffusers+present = hasattr(diffusers, pipeline_class)dummy_backends = _dummy_required_backends(getattr(diffusers, pipeline_class, None))except Exception as exc: # noqa: BLE001 -- see below: this check must never raise anything but its own ValueErrordiff --git a/studio/backend/core/inference/ltx2_import_compat.py b/studio/backend/core/inference/ltx2_import_compat.pynew file mode 100644index 00000000000..73405952462--- /dev/null+++ b/studio/backend/core/inference/ltx2_import_compat.py@@ -0,0 +1,183 @@+# SPDX-License-Identifier: AGPL-3.0-only+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0++"""Let the diffusers LTX-2 pipelines import on the transformers Studio pins.++diffusers 0.40 imports ``Gemma4UnifiedForConditionalGeneration`` (transformers >= 5.10) at module level in every+``diffusers.pipelines.ltx2.pipeline_ltx2*`` module, but only uses it in the ``text_encoder`` annotation (huggingface/+diffusers#14773). When transformers lacks it, bind an inert placeholder only while those modules import, then remove+it. Retire once diffusers guards the import or the transformers pin reaches 5.10.+"""++from __future__ import annotations++import importlib+import importlib.util+import pkgutil+import sys+import threading+from typing import Any, Optional++# name -> first transformers release exporting it.+LTX2_OPTIONAL_TRANSFORMERS_NAMES: dict[str, str] = {+ "Gemma4UnifiedForConditionalGeneration": "5.10",+}++_LTX2_PACKAGE = "diffusers.pipelines.ltx2"+_PLACEHOLDER_MARKER = "_unsloth_ltx2_import_placeholder"++_lock = threading.Lock()+_done = False+++def is_ltx2_pipeline_class(name: Optional[str]) -> bool:+ """Whether ``name`` is a diffusers class that lives in the LTX-2 pipeline package."""+ return isinstance(name, str) and name.startswith("LTX2") and name.endswith("Pipeline")+++def _make_placeholder(name: str, min_version: str) -> type:+ message = (+ f"This checkpoint needs transformers' {name}, which this environment's transformers does not "+ f"provide (it needs transformers >= {min_version}). LTX-2 and LTX-2.3 use a Gemma3 text encoder "+ f"and do not need it."+ )++ def _refuse(*_args: Any, **_kwargs: Any) -> Any:+ raise ImportError(message)++ return type(+ name,+ (),+ {+ "__doc__": f"Import-time stand-in for transformers.{name}; see {__name__}.",+ "__module__": __name__,+ _PLACEHOLDER_MARKER: True,+ "__init__": _refuse,+ "from_pretrained": classmethod(_refuse),+ "from_config": classmethod(_refuse),+ },+ )+++def _transformers_has(transformers: Any, name: str) -> bool:+ # Lazy getattr imports the real module; a name that fails to import counts as missing, as diffusers would see it.+ try:+ value = getattr(transformers, name)+ except Exception: # noqa: BLE001 -- AttributeError on an old release, RuntimeError on a broken lazy import+ return False+ return not getattr(value, _PLACEHOLDER_MARKER, False)+++def _modules_naming(package: Any, names: list[str]) -> list[str]:+ """Submodules of ``package`` whose source mentions any of ``names``, in a stable order."""+ found = []+ for info in sorted(pkgutil.iter_modules(package.__path__), key = lambda i: i.name):+ full = f"{package.__name__}.{info.name}"+ try:+ spec = importlib.util.find_spec(full)+ origin = getattr(spec, "origin", None)+ if not origin or not origin.endswith(".py"):+ continue+ with open(origin, encoding = "utf-8") as fh:+ source = fh.read()+ except Exception: # noqa: BLE001 -- unreadable source: leave it to the normal import path+ continue+ if any(name in source for name in names):+ found.append(full)+ return found+++def ensure_ltx2_pipelines_importable(logger: Any = None) -> bool:+ """Idempotent, never raises. False = could not help; the caller's own import then reports the real error."""+ global _done+ if _done:+ return True+ with _lock:+ if _done:+ return True+ try:+ import transformers+ except Exception: # noqa: BLE001 -- no transformers: the caller's import reports it+ return False+ missing = [+ name+ for name in LTX2_OPTIONAL_TRANSFORMERS_NAMES+ if not _transformers_has(transformers, name)+ ]+ if not missing:+ _done = True+ return True+ try:+ # First processing_utils import replaces sys.modules["transformers"] (direct_transformers_import), dropping+ # names bound on the old object: settle the swap first.+ importlib.import_module("transformers.processing_utils")+ except Exception: # noqa: BLE001 -- the pipeline import below reports whatever this was+ pass++ placeholders = {+ name: _make_placeholder(name, LTX2_OPTIONAL_TRANSFORMERS_NAMES[name])+ for name in missing+ }+ touched: list[Any] = []++ def _bind() -> None:+ current = sys.modules.get("transformers", transformers)+ for name, placeholder in placeholders.items():+ if name not in current.__dict__:+ setattr(current, name, placeholder)+ if current not in touched:+ touched.append(current)++ def _import(module_name: str) -> Optional[str]:+ for attempt in (0, 1):+ _bind()+ try:+ importlib.import_module(module_name)+ return None+ except Exception as exc: # noqa: BLE001 -- a different failure: the real import re-raises it+ if attempt == 0 and any(name in str(exc) for name in missing):+ continue+ return f"{type(exc).__name__}: {exc}"+ return None++ failed: list[tuple[str, str]] = []+ try:+ # DIFFUSERS_SLOW_IMPORT makes the package import load the pipeline modules eagerly.+ error = _import(_LTX2_PACKAGE)+ package = sys.modules.get(_LTX2_PACKAGE)+ if error is not None or package is None:+ return False # no diffusers, or one without LTX-2: nothing to shim+ targets = [m for m in _modules_naming(package, missing) if m not in sys.modules]+ for module_name in targets:+ error = _import(module_name)+ if error is not None:+ failed.append((module_name, error))+ finally:+ for module in touched:+ for name, placeholder in placeholders.items():+ if module.__dict__.get(name) is placeholder:+ delattr(module, name)++ if logger is not None:+ try:+ logger.info(+ "ltx2_import_compat: transformers %s lacks %s; imported %d LTX-2 pipeline module(s) "+ "with an inert stand-in",+ getattr(transformers, "__version__", "unknown"),+ ", ".join(missing),+ len(targets) - len(failed),+ )+ for module_name, error in failed:+ logger.warning(+ "ltx2_import_compat: %s still fails to import: %s", module_name, error+ )+ except Exception: # noqa: BLE001, S110 -- logging must never turn this into a failure+ pass+ _done = not failed+ return _done+++def _reset_for_tests() -> None:+ global _done+ with _lock:+ _done = Falsediff --git a/studio/backend/core/inference/video.py b/studio/backend/core/inference/video.pyindex 7d55b206456..1d0af4d89af 100644--- a/studio/backend/core/inference/video.py+++ b/studio/backend/core/inference/video.py@@ -4931,6 +4931,10 @@ class VideoBackend:raise_on_unified_memory_shortfall(plan, family = getattr(fam, "name", None), logger = logger)# ── build the pipeline.+ from .ltx2_import_compat import ensure_ltx2_pipelines_importable, is_ltx2_pipeline_class++ if is_ltx2_pipeline_class(fam.pipeline_class):+ ensure_ltx2_pipelines_importable(logger)pipeline_cls = getattr(diffusers, fam.pipeline_class)# cache_dir pins every loader call to the live cache root, so a mid-session change cannot split one model across# roots.diff --git a/studio/backend/core/inference/video_ltx2.py b/studio/backend/core/inference/video_ltx2.pyindex 6a79a5143e8..8ddb13803ce 100644--- a/studio/backend/core/inference/video_ltx2.py+++ b/studio/backend/core/inference/video_ltx2.py@@ -988,6 +988,10 @@ def load_ltx23_pipeline(scheduler, the tokenizer, the dense Gemma3 encoder and the companion VAE/vocoder artifacts areall fetched by a load that promised to fetch nothing."""import transformers++ from .ltx2_import_compat import ensure_ltx2_pipelines_importable++ ensure_ltx2_pipelines_importable(logger)from diffusers import LTX2Pipelinefrom diffusers.loaders.single_file_utils import load_single_file_checkpointdiff --git a/studio/backend/core/training/diffusion_dit_trainer.py b/studio/backend/core/training/diffusion_dit_trainer.pyindex f8fa252bc4a..2f8ffb14e9e 100644--- a/studio/backend/core/training/diffusion_dit_trainer.py+++ b/studio/backend/core/training/diffusion_dit_trainer.py@@ -1198,9 +1198,19 @@ _LTX2_TARGETS = (_LTX2_TRAIN_FPS = 24.0-def _ltx2_load_conditioners(cfg, device, weight_dtype):+def _ltx2_pipeline_cls():+ """``diffusers.LTX2Pipeline``, importable on the pinned transformers (see ltx2_import_compat)."""+ from core.inference.ltx2_import_compat import ensure_ltx2_pipelines_importable++ ensure_ltx2_pipelines_importable()from diffusers import LTX2Pipeline+ return LTX2Pipeline+++def _ltx2_load_conditioners(cfg, device, weight_dtype):+ LTX2Pipeline = _ltx2_pipeline_cls()+pipe, vae = _load_pipe_without_transformer(LTX2Pipeline, cfg, device)# The connectors are not a text_encoder attribute, so _encoders_to_device never reaches them.if getattr(pipe, "connectors", None) is not None:@@ -1300,13 +1310,13 @@ def _ltx2_audio_token_count(config, num_pixel_frames: int, fps: float) -> int:def _ltx2_pack(latents, conf):"""[B,C,F,H,W] -> [B, F*H*W, C] via the pipeline's own patchifier."""- from diffusers import LTX2Pipeline+ LTX2Pipeline = _ltx2_pipeline_cls()return LTX2Pipeline._pack_latents(latents, conf.patch_size, conf.patch_size_t)def _ltx2_unpack(pred, f, h, w, conf):"""The inverse of ``_ltx2_pack``, back to the 5-D shape ``target = noise - latents`` has."""- from diffusers import LTX2Pipeline+ LTX2Pipeline = _ltx2_pipeline_cls()return LTX2Pipeline._unpack_latents(pred, f, h, w, conf.patch_size, conf.patch_size_t)@@ -1363,7 +1373,7 @@ def _ltx2_forward(transformer, noisy, timesteps, sigmas, embeds_batch, cfg, devidef _ltx2_save(pipe_cls, out_dir, transformer_lora_layers):- from diffusers import LTX2Pipeline+ LTX2Pipeline = _ltx2_pipeline_cls()LTX2Pipeline.save_lora_weights(save_directory = out_dir,transformer_lora_layers = transformer_lora_layers,diff --git a/studio/backend/tests/test_ltx2_import_compat.py b/studio/backend/tests/test_ltx2_import_compat.pynew file mode 100644index 00000000000..18ad6b2e10d--- /dev/null+++ b/studio/backend/tests/test_ltx2_import_compat.py@@ -0,0 +1,295 @@+# SPDX-License-Identifier: AGPL-3.0-only+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0++"""diffusers 0.40 LTX-2 pipelines must import on the pinned transformers 5.5.++diffusers 0.40.0 and main import ``Gemma4UnifiedForConditionalGeneration`` at module level in every+``diffusers.pipelines.ltx2.pipeline_ltx2*`` module, and that class only exists from transformers 5.10. On the Studio+pin every LTX-2 / LTX-2.3 load failed with ``cannot import name 'Gemma4UnifiedForConditionalGeneration' from+'transformers'``. These tests build a fake transformers and a fake lazy diffusers with the same shape (including+transformers replacing its own ``sys.modules`` entry when ``processing_utils`` is first imported) so they run+hermetically on CPU without either package installed.+"""++from __future__ import annotations++import ast+import sys+import textwrap+from pathlib import Path++import pytest++from core.inference import ltx2_import_compat as compat++BACKEND = Path(__file__).resolve().parents[1]+NAME = "Gemma4UnifiedForConditionalGeneration"++_TRANSFORMERS_INIT = """+import sys+import types+++class Gemma3ForConditionalGeneration:+ pass+++class ProcessorMixin:+ pass++{extra}+"""++# Mirrors transformers: the first processing_utils import replaces sys.modules["transformers"].+_PROCESSING_UTILS = """+import importlib.util+import os+import sys++_here = os.path.dirname(os.path.abspath(__file__))+_spec = importlib.util.spec_from_file_location(+ "transformers", os.path.join(_here, "__init__.py"), submodule_search_locations=[_here]+)+_fresh = importlib.util.module_from_spec(_spec)+_spec.loader.exec_module(_fresh)+sys.modules["transformers"] = _fresh+"""++_DIFFUSERS_INIT = """+import importlib++__version__ = "0.40.0"+_LAZY = {+ "LTX2Pipeline": "diffusers.pipelines.ltx2.pipeline_ltx2",+ "LTX2ImageToVideoPipeline": "diffusers.pipelines.ltx2.pipeline_ltx2_image2video",+ "LTX2VideoTransformer3DModel": "diffusers.models_stub",+}+++def __getattr__(name):+ if name not in _LAZY:+ raise AttributeError(name)+ try:+ module = importlib.import_module(_LAZY[name])+ except Exception as exc:+ raise RuntimeError(+ f"Failed to import {_LAZY[name]} because of the following error (look up to see its traceback):\\n{exc}"+ ) from exc+ return getattr(module, name)+"""++# In real transformers the swap fires while `from transformers import (...)` resolves Gemma3 (modeling_gemma3 ->+# modeling_layers -> processing_utils), i.e. before Gemma4Unified is looked up; importing it first mirrors that.+_PIPELINE = """+from transformers import processing_utils # noqa: F401+from transformers import (+ Gemma3ForConditionalGeneration,+ Gemma4UnifiedForConditionalGeneration,+ ProcessorMixin,+)+++class {cls}:+ def __init__(self, text_encoder: Gemma3ForConditionalGeneration | Gemma4UnifiedForConditionalGeneration):+ self.text_encoder = text_encoder+"""+++def _write(path: Path, text: str) -> None:+ path.parent.mkdir(parents = True, exist_ok = True)+ path.write_text(textwrap.dedent(text), encoding = "utf-8")+++def fake_stack(tmp_path, monkeypatch):+ """Build fake transformers + diffusers under tmp_path and isolate sys.modules for them."""++ def build(*, transformers_has_class: bool) -> Path:+ root = tmp_path / "site"+ extra = f"class {NAME}:\n real = True\n" if transformers_has_class else ""+ _write(root / "transformers" / "__init__.py", _TRANSFORMERS_INIT.format(extra = extra))+ _write(root / "transformers" / "processing_utils.py", _PROCESSING_UTILS)+ _write(root / "diffusers" / "__init__.py", _DIFFUSERS_INIT)+ _write(+ root / "diffusers" / "models_stub.py", "class LTX2VideoTransformer3DModel:\n pass\n"+ )+ _write(root / "diffusers" / "pipelines" / "__init__.py", "")+ _write(root / "diffusers" / "pipelines" / "ltx2" / "__init__.py", "")+ _write(+ root / "diffusers" / "pipelines" / "ltx2" / "connectors.py",+ "class LTX2TextConnectors:\n pass\n",+ )+ _write(+ root / "diffusers" / "pipelines" / "ltx2" / "pipeline_ltx2.py",+ _PIPELINE.format(cls = "LTX2Pipeline"),+ )+ _write(+ root / "diffusers" / "pipelines" / "ltx2" / "pipeline_ltx2_image2video.py",+ _PIPELINE.format(cls = "LTX2ImageToVideoPipeline"),+ )+ monkeypatch.syspath_prepend(str(root))+ return root++ saved = {+ k: v+ for k, v in sys.modules.items()+ if k in ("transformers", "diffusers") or k.startswith(("transformers.", "diffusers."))+ }+ for key in saved:+ del sys.modules[key]+ compat._reset_for_tests()+ try:+ yield build+ finally:+ for key in [+ k+ for k in sys.modules+ if k in ("transformers", "diffusers") or k.startswith(("transformers.", "diffusers."))+ ]:+ del sys.modules[key]+ sys.modules.update(saved)+ compat._reset_for_tests()+++def test_fake_stack_reproduces_the_failure(fake_stack):+ """The unpatched import fails the way the Colab run did, so the tests below prove something."""+ fake_stack(transformers_has_class = False)+ import diffusers++ with pytest.raises(RuntimeError, match = NAME):+ diffusers.LTX2Pipeline # noqa: B018+++def test_ensure_makes_every_ltx2_pipeline_importable(fake_stack):+ fake_stack(transformers_has_class = False)+ original = __import__("transformers")++ assert compat.ensure_ltx2_pipelines_importable() is True++ import diffusers++ assert diffusers.LTX2Pipeline.__name__ == "LTX2Pipeline"+ assert diffusers.LTX2ImageToVideoPipeline.__name__ == "LTX2ImageToVideoPipeline"+ # The swap really happened, and neither module object keeps the stand-in afterwards.+ assert sys.modules["transformers"] is not original+ assert NAME not in sys.modules["transformers"].__dict__+ assert NAME not in original.__dict__+ # A Gemma3 encoder still satisfies the annotation the pipeline carries.+ pipe = diffusers.LTX2Pipeline(+ text_encoder = sys.modules["transformers"].Gemma3ForConditionalGeneration()+ )+ assert pipe.text_encoder is not None+ assert compat.ensure_ltx2_pipelines_importable() is True+++def test_slow_import_mode_package_import_is_shimmed_too(fake_stack):+ """With DIFFUSERS_SLOW_IMPORT the ltx2 package __init__ imports the pipelines eagerly, before any target list."""+ import importlib++ root = fake_stack(transformers_has_class = False)+ _write(+ root / "diffusers" / "pipelines" / "ltx2" / "__init__.py",+ "from .pipeline_ltx2 import LTX2Pipeline # noqa: F401\n",+ )+ assert compat.ensure_ltx2_pipelines_importable() is True+ module = importlib.import_module("diffusers.pipelines.ltx2.pipeline_ltx2")+ assert module.LTX2Pipeline is not None+ assert NAME not in sys.modules["transformers"].__dict__+++def test_placeholder_refuses_to_load(fake_stack):+ fake_stack(transformers_has_class = False)+ assert compat.ensure_ltx2_pipelines_importable() is True+ import diffusers.pipelines.ltx2.pipeline_ltx2 as mod++ stand_in = getattr(mod, NAME)+ with pytest.raises(ImportError, match = r"transformers >= 5\.10"):+ stand_in.from_pretrained("any/repo")+ with pytest.raises(ImportError, match = r"transformers >= 5\.10"):+ stand_in()+++def test_new_transformers_is_left_alone(fake_stack):+ fake_stack(transformers_has_class = True)+ assert compat.ensure_ltx2_pipelines_importable() is True+ # Nothing was pre-imported and the real class is the one the pipeline sees.+ assert "diffusers.pipelines.ltx2.pipeline_ltx2" not in sys.modules+ import diffusers.pipelines.ltx2.pipeline_ltx2 as mod++ assert getattr(getattr(mod, NAME), "real", False) is True+++def test_no_diffusers_is_not_an_error(fake_stack):+ """A host without diffusers (sd.cpp-only) gets False, never an exception."""+ fake_stack(transformers_has_class = False)+ sys.modules["diffusers"] = None # blocks the import; the fixture restores sys.modules+ assert compat.ensure_ltx2_pipelines_importable() is False+++def test_studio_availability_check_accepts_ltx2_on_old_transformers(fake_stack):+ """The training preflight (strict) used to refuse LTX-2 outright with 'cannot import'."""+ fake_stack(transformers_has_class = False)+ from core.inference.diffusion_families import assert_pipeline_class_available++ assert_pipeline_class_available("LTX2Pipeline", "ltx-2", strict = True)+++def test_is_ltx2_pipeline_class():+ assert compat.is_ltx2_pipeline_class("LTX2Pipeline")+ assert compat.is_ltx2_pipeline_class("LTX2ImageToVideoPipeline")+ assert not compat.is_ltx2_pipeline_class("LTX2VideoTransformer3DModel")+ assert not compat.is_ltx2_pipeline_class("WanPipeline")+ assert not compat.is_ltx2_pipeline_class(None)+++def _functions_importing_ltx2_pipeline(path: Path) -> dict[str, list[int]]:+ """Function name -> line numbers of ``from diffusers import LTX2*Pipeline`` in it."""+ tree = ast.parse(path.read_text(encoding = "utf-8"))+ hits: dict[str, list[int]] = {}+ for fn in ast.walk(tree):+ if not isinstance(fn, (ast.FunctionDef, ast.AsyncFunctionDef)):+ continue+ for node in ast.walk(fn):+ if (+ isinstance(node, ast.ImportFrom)+ and node.module == "diffusers"+ and any(compat.is_ltx2_pipeline_class(a.name) for a in node.names)+ ):+ hits.setdefault(fn.name, []).append(node.lineno)+ return hits+++def _calls_ensure_before(fn_src: str) -> bool:+ ensure = fn_src.find("ensure_ltx2_pipelines_importable(")+ imp = fn_src.find("from diffusers import LTX2")+ return ensure != -1 and (imp == -1 or ensure < imp)+++ "rel",+ [+ "core/inference/video_ltx2.py",+ "core/inference/video.py",+ "core/training/diffusion_dit_trainer.py",+ ],+)+def test_every_ltx2_pipeline_import_goes_through_the_shim(rel):+ path = BACKEND / rel+ source = path.read_text(encoding = "utf-8")+ tree = ast.parse(source)+ funcs = {+ n.name: ast.get_source_segment(source, n)+ for n in ast.walk(tree)+ if isinstance(n, (ast.FunctionDef, ast.AsyncFunctionDef))+ }+ for name in _functions_importing_ltx2_pipeline(path):+ assert _calls_ensure_before(+ funcs[name]+ ), f"{rel}:{name} imports an LTX-2 pipeline without the shim"+++def test_video_backend_pipeline_getattr_goes_through_the_shim():+ source = (BACKEND / "core/inference/video.py").read_text(encoding = "utf-8")+ anchor = source.index("pipeline_cls = getattr(diffusers, fam.pipeline_class)")+ window = source[max(0, anchor - 400) : anchor]+ assert "ensure_ltx2_pipelines_importable(" in window