Skip to content

vllm_omni.diffusion.models.ltx2.ltx2_components

Shared component construction helpers for the LTX model family.

LTX23_COMPONENT_PROFILE module-attribute 

LTX23_COMPONENT_PROFILE = LTXComponentProfile(
    name="ltx2_3",
    dit_modules=("transformer",),
    encoder_modules=("text_encoder", "connectors"),
    vae_modules=("vae", "audio_vae"),
    resident_modules=("vocoder",),
    video_vae_cls=DistributedAutoencoderKLLTX2Video,
    vocoder_cls=LTX2VocoderWithBWE or LTX2Vocoder,
    vocoder_fallback_cls=LTX2Vocoder,
)

LTX23_DISTILLED_COMPONENT_PROFILE module-attribute 

LTX23_DISTILLED_COMPONENT_PROFILE = replace(
    LTX23_COMPONENT_PROFILE,
    name="ltx2_3_distilled",
    resident_modules=(
        *LTX23_COMPONENT_PROFILE.resident_modules,
        "latent_upsampler",
    ),
    artifact_repo_id="Lightricks/LTX-2.3",
    latent_upsampler_filename="ltx-2.3-spatial-upscaler-x2-1.1.safetensors",
)

LTX23_DISTILLED_ONE_STAGE_COMPONENT_PROFILE module-attribute 

LTX23_DISTILLED_ONE_STAGE_COMPONENT_PROFILE = replace(
    LTX23_DISTILLED_COMPONENT_PROFILE,
    name="ltx2_3_distilled_one_stage",
    resident_modules=LTX23_COMPONENT_PROFILE.resident_modules,
)

LTX23_TWO_STAGE_COMPONENT_PROFILE module-attribute 

LTX23_TWO_STAGE_COMPONENT_PROFILE = replace(
    LTX23_COMPONENT_PROFILE,
    name="ltx2_3_two_stage",
    resident_modules=(
        *LTX23_COMPONENT_PROFILE.resident_modules,
        "latent_upsampler",
    ),
    artifact_repo_id="Lightricks/LTX-2.3",
    latent_upsampler_filename="ltx-2.3-spatial-upscaler-x2-1.1.safetensors",
    distilled_lora_filename="ltx-2.3-22b-distilled-lora-384-1.1.safetensors",
)

LTX25_DISTILLED_COMPONENT_PROFILE module-attribute 

LTX25_DISTILLED_COMPONENT_PROFILE = LTXComponentProfile(
    name="ltx2_5_distilled",
    dit_modules=("transformer",),
    encoder_modules=("text_encoder", "connectors"),
    vae_modules=("vae", "audio_vae"),
    resident_modules=("vocoder", "latent_upsampler"),
    video_vae_cls=DistributedAutoencoderKLLTX2Video,
    vocoder_cls=LTX2VocoderWithBWE or LTX2Vocoder,
    vocoder_fallback_cls=LTX2Vocoder,
    text_encoder_cls=_LTX25_TEXT_ENCODER_CLS,
    preserve_connector_attention_mask=True,
)

LTX25_DISTILLED_ONE_STAGE_COMPONENT_PROFILE module-attribute 

LTX25_DISTILLED_ONE_STAGE_COMPONENT_PROFILE = replace(
    LTX25_DISTILLED_COMPONENT_PROFILE,
    name="ltx2_5_distilled_one_stage",
    resident_modules=LTX25_FULL_COMPONENT_PROFILE.resident_modules,
)

LTX25_FULL_COMPONENT_PROFILE module-attribute 

LTX25_FULL_COMPONENT_PROFILE = LTXComponentProfile(
    name="ltx2_5_full",
    dit_modules=("transformer",),
    encoder_modules=("text_encoder", "connectors"),
    vae_modules=("vae", "audio_vae"),
    resident_modules=("vocoder",),
    video_vae_cls=DistributedAutoencoderKLLTX2Video,
    vocoder_cls=LTX2VocoderWithBWE or LTX2Vocoder,
    vocoder_fallback_cls=LTX2Vocoder,
    text_encoder_cls=_LTX25_TEXT_ENCODER_CLS,
    transformer_subfolder="transformer_full",
    scheduler_use_dynamic_shifting=True,
    scheduler_shift_terminal=0.1,
    preserve_connector_attention_mask=True,
)

LTX25_TWO_STAGE_COMPONENT_PROFILE module-attribute 

LTX25_TWO_STAGE_COMPONENT_PROFILE = replace(
    LTX25_FULL_COMPONENT_PROFILE,
    name="ltx2_5_two_stage",
    resident_modules=(
        *LTX25_FULL_COMPONENT_PROFILE.resident_modules,
        "latent_upsampler",
    ),
    artifact_repo_id="Lightricks/LTX-2.5",
    artifact_revision=LTX25_NATIVE_ARTIFACT_REVISION,
    latent_upsampler_filename="latent_upscale_models/ltx-2.5-latent-spatial-upscaler-x2-bf16-1.0.safetensors",
    distilled_lora_filename="loras/ltx-2.5-22b-distilled-lora-450-bf16.safetensors",
)

LTX2_COMPONENT_PROFILE module-attribute 

LTX2_COMPONENT_PROFILE = LTXComponentProfile(
    name="ltx2",
    dit_modules=("transformer",),
    encoder_modules=("text_encoder", "connectors"),
    vae_modules=("vae", "audio_vae"),
    resident_modules=("vocoder",),
    video_vae_cls=DistributedAutoencoderKLLTX2Video,
)

LTX2_DISTILLED_COMPONENT_PROFILE module-attribute 

LTX2_DISTILLED_COMPONENT_PROFILE = LTXComponentProfile(
    name="ltx2_distilled",
    dit_modules=("transformer",),
    encoder_modules=("text_encoder", "connectors"),
    vae_modules=("vae", "audio_vae"),
    resident_modules=("vocoder", "latent_upsampler"),
    video_vae_cls=DistributedAutoencoderKLLTX2Video,
)

LTX2_DISTILLED_ONE_STAGE_COMPONENT_PROFILE module-attribute 

LTX2_DISTILLED_ONE_STAGE_COMPONENT_PROFILE = replace(
    LTX2_DISTILLED_COMPONENT_PROFILE,
    name="ltx2_distilled_one_stage",
    resident_modules=LTX2_COMPONENT_PROFILE.resident_modules,
)

LTX2_TWO_STAGE_COMPONENT_PROFILE module-attribute 

LTX2_TWO_STAGE_COMPONENT_PROFILE = replace(
    LTX2_COMPONENT_PROFILE,
    name="ltx2_two_stage",
    resident_modules=(
        *LTX2_COMPONENT_PROFILE.resident_modules,
        "latent_upsampler",
    ),
    artifact_repo_id="Lightricks/LTX-2",
    latent_upsampler_filename="ltx-2-spatial-upscaler-x2-1.0.safetensors",
    distilled_lora_filename="ltx-2-19b-distilled-lora-384.safetensors",
)

logger module-attribute 

logger = logging.getLogger(__name__)

LTXComponentProfile dataclass

Component construction and discovery contract for an LTX variant.

artifact_repo_id class-attribute instance-attribute 

artifact_repo_id: str | None = None

artifact_revision class-attribute instance-attribute 

artifact_revision: str | None = None

distilled_lora_filename class-attribute instance-attribute 

distilled_lora_filename: str | None = None

dit_modules instance-attribute 

dit_modules: tuple[str, ...]

encoder_modules instance-attribute 

encoder_modules: tuple[str, ...]

latent_upsampler_filename class-attribute instance-attribute 

latent_upsampler_filename: str | None = None

name instance-attribute 

name: str

preserve_connector_attention_mask class-attribute instance-attribute 

preserve_connector_attention_mask: bool = False

resident_modules class-attribute instance-attribute 

resident_modules: tuple[str, ...] = ()

scheduler_shift_terminal class-attribute instance-attribute 

scheduler_shift_terminal: float | None = None

scheduler_use_dynamic_shifting class-attribute instance-attribute 

scheduler_use_dynamic_shifting: bool = False

text_encoder_cls class-attribute instance-attribute 

text_encoder_cls: type | None = (
    Gemma3ForConditionalGeneration
)

transformer_subfolder class-attribute instance-attribute 

transformer_subfolder: str = 'transformer'

vae_modules instance-attribute 

vae_modules: tuple[str, ...]

video_vae_cls class-attribute instance-attribute 

video_vae_cls: type = AutoencoderKLLTX2Video

vocoder_cls class-attribute instance-attribute 

vocoder_cls: type = LTX2Vocoder

vocoder_fallback_cls class-attribute instance-attribute 

vocoder_fallback_cls: type | None = None

create_transformer_from_config 

create_transformer_from_config(
    config: dict,
    quant_config: QuantizationConfig | None = None,
) -> LTX2VideoTransformer3DModel

Construct the shared LTX transformer from a Diffusers config.

detect_ltx_model_version 

detect_ltx_model_version(
    model: str, revision: str | None = None
) -> str

Detect the LTX model version from checkpoint component metadata.

get_ltx2_post_process_func 

get_ltx2_post_process_func(od_config: Any)

Build the common LTX engine-output adapter.

initialize_pipeline_components 

initialize_pipeline_components(
    pipeline: Any, od_config: Any
) -> None

Build the common LTX component graph selected by component_profile.

load_transformer_config 

load_transformer_config(
    model_path: str,
    subfolder: str = "transformer",
    local_files_only: bool = True,
    *,
    revision: str | None = None,
) -> dict

Load an LTX transformer config from a local model or the HF Hub.

preserves_reference_image_size 

preserves_reference_image_size(
    *, model: str | None, revision: str | None = None
) -> bool

Preserve source geometry only for the LTX-2.5 CRF-18 I2V path.

resolve_ltx_artifact 

resolve_ltx_artifact(
    model: str,
    repo_id: str,
    filename: str,
    *,
    model_revision: str | None,
    artifact_revision: str | None,
) -> str

Resolve an official LTX sidecar without crossing repository revisions.

A local model path selects where the primary components are loaded from; it does not imply that independently hosted sidecars must be offline. Hub offline behavior remains controlled by huggingface_hub itself.

resolve_ltx_checkpoint_kind 

resolve_ltx_checkpoint_kind(
    pipeline_kind: str,
) -> LTXCheckpointKind | None

Derive checkpoint requirements from the execution contract.

resolve_ltx_component_profile 

resolve_ltx_component_profile(
    pipeline_kind: str, model_version: str
) -> LTXComponentProfile

Resolve component construction independently from execution recipes.