Hugging Face's logo

Diffusers documentation

LTX2VideoDiffusionDecoderModel

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v0.43.0).
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

LTX2VideoDiffusionDecoderModel

Lightricks が LTX-2.5 で導入した拡散型ビデオデコーダーです。近傍アテンションの各ステージが潜在変数をコンテキストボリュームにアップサンプリングし、最終ステージがそのコンテキストを条件としてピクセルのノイズ除去を行います。

これはデコーダーであり、オートエンコーダーではありません。エンコーディングはAutoencoderKLLTX2Videoに留まり、その潜在空間をこのモデルは変更なしで消費するため、潜在変数は畳み込みデコーダーとこのデコーダーの間で相互に交換可能です。それ自体が拡散モデルであるため、パイプラインのvaeとして渡されるのではなく、LTX2VideoDiffusionDecodePipelineによって駆動されます。output_type="latent"を指定して任意のLTX-2パイプラインを実行し、その後デコードしてください。

import torch
from diffusers import LTX2Pipeline, LTX2VideoDiffusionDecodePipeline, LTX2VideoDiffusionDecoderModel

pipe = LTX2Pipeline.from_pretrained("Lightricks/LTX-2.5-Diffusers", dtype=torch.bfloat16).to("cuda")  # or "mps", "xpu", "cpu"
latents = pipe(prompt="a potter shaping a clay vase", output_type="latent").frames

decoder = LTX2VideoDiffusionDecoderModel.from_pretrained(
    "Lightricks/LTX-2.5-Diffusers", subfolder="diffusion_decoder", dtype=torch.bfloat16
).to("cuda")
decode_pipe = LTX2VideoDiffusionDecodePipeline(diffusion_decoder=decoder, scheduler=pipe.scheduler)

# `denormalize=False`: `output_type="latent"` already applied the latent statistics, so applying them
# again here would scale every channel by its std a second time.
# The decoder also draws the noise it denoises, so decoding is only reproducible with a generator.
video = decode_pipe(
    latents, generator=torch.Generator("cuda").manual_seed(0), denormalize=False
).frames[0]

vae はデコードパイプラインにおける任意のコンポーネントです。denormalize=True の場合のみ潜在変数の統計量のために参照され、デコーダー自体がそれを持ち合わせているため、デコード専用のワークフローでは第 2 のオートエンコーダーを読み込む必要はありません。

アテンションのバックエンド

近傍アテンションのウィンドウはBlockMaskとして表現されるため、デコーダーはデフォルトでflexアテンションバックエンドで実行され、追加の依存関係は不要です。PyTorch は明示的に要求しない限りflex_attentionをコンパイルせず、コンパイルされていない状態ではスコア行列全体がマテリアライズされるため、フル解像度のシーケンス長では実用的ではありません。そのような場合は、デコーダーをコンパイルするか、NATTENのカーネルに切り替えてください。元の実装でもこれらが使用されています。プロセッサはkernelsパッケージを介して Hub から NATTEN（shi-labs/natten）を取得するため、ローカルでの NATTEN ビルドではなくpip install kernelsが必要です。

from diffusers.models.autoencoders.ltx2_diffusion_decoder import LTX2VideoVaeNeighborhoodNattenProcessor

decoder.set_attn_processor(LTX2VideoVaeNeighborhoodNattenProcessor())

Hub からカーネルのダウンロードコードを取得するため、DIFFUSERS_DISABLE_REMOTE_CODE=true でリモートコードがグローバルに無効化されている場合、プロセッサは例外を送出します。

デコーダーのすべてのアテンションモジュールは同じ近傍アテンション（カーネルサイズなどのステージごとの違いはモジュール側にあり、プロセッサー側にはない）であるため、set_attn_processor はこれらをすべて1つの共有インスタンスに置き換えます。

backendをflex以外に切り替えた場合(decoder.set_attention_backend(...))、BlockMaskを受け入れるバックエンドが存在しないため、例外が発生します。代わりに、上記のNATTENプロセッサーを使用してください。

タイル分割

decoder.enable_tiling() は、オーバーラップするタイル単位でデコードし、それらをブレンドして結合します。これにより、ピークメモリは動画サイズではなくタイルサイズによって上限が設定されます。低コストな初期アップサンプリング段階では依然として完全な潜在変数が参照されますが、デコード時のメモリ使用量を支配する最後のアップサンプリング段階と拡散段階のみがタイル単位で実行されるため、タイル化による出力への影響はタイル境界付近に限られます。拡散段階では各タイルが個別にデノイズされるため、タイル化されたデコードは非タイル化の結果を厳密には再現しません。デフォルトのタイルサイズとオーバーラップサイズは、参照実装のものと一致しています。近傍アテンションはカーネルより小さいグリッドを拒否するため、末尾の残りのタイルは単独でデコードされるのではなく、隣接するタイルにマージされます。

LTX2VideoDiffusionDecoderModel

クラス diffusers.LTX2VideoDiffusionDecoderModel

< >

( out_channels: int = 3latent_channels: int = 128patch_size: int = 4scaling_factor: float = 1.0decoder_head_dim: int = 64decoder_stage_channels: tuple[int, ...] = (2048, 1024, 512, 512, 256)decoder_stage_depths: tuple[int, ...] = (4, 6, 4, 2, 8)decoder_stage_kernels: tuple[tuple[int, int, int], ...] = ((3, 7, 7), (3, 7, 7), (3, 5, 5), (3, 5, 5))decoder_upsample_strides: tuple[tuple[int, int, int], ...] = ((1, 2, 2), (2, 1, 1), (2, 2, 2), (2, 2, 2))decoder_upsample_channel_reductions: tuple[int, ...] = (2, 2, 1, 2)decoder_stage5_kernel: tuple[int, int, int] = (11, 11, 11)decoder_t_emb_dim: int = 384decoder_timestep_scale_multiplier: float = 1000.0decoder_model_output_type: str = 'x0'decoder_num_inference_steps: int = 1spatial_compression_ratio: int = 32temporal_compression_ratio: int = 8 )

LTX-2.5 で導入された LTX-2 の拡散型動画デコーダー。

これはデコーダーであり、オートエンコーダーではありません。エンコーダーを持たず、潜在変数（latents）を生成することはできません。エンコーディングはAutoencoderKLLTX2Videoで行われ、その潜在空間をこのデコーダーはそのまま消費するため、畳み込みデコーダーとこのデコーダーの間で潜在変数は相互に交換可能です。

また、これは決定論的なデコーダーではなく拡散モデルであり、潜在変数から構築されたコンテキストボリュームに条件付けられてピクセルのノイズ除去を行うため、パイプラインのvaeとして渡されるのではなく、LTX2VideoDiffusionDecodePipelineによって駆動されます。

潜在統計はバッファとして保持されており、2つのベクトルのために2番目のオートエンコーダーを読み込むことなく、デコードパイプラインでデノーマライズ処理を実行できるようにしています。

このモデルは ModelMixin を継承しています。すべてのモデルに実装されている汎用的なメソッド（ダウンロードや保存など）については、スーパークラスのドキュメントを参照してください。

decode

< >

( z: Tensorgenerator: typing.Optional[torch.Generator] = Nonenum_inference_steps: int | None = Nonereturn_dict: bool = True )

バッチの潜在変数をデコードします。

z はすでに正規化解除済みであることが前提です（パイプラインが latents_mean / latents_std を適用するため）。これは AutoencoderKLLTX2Video と一致します。このデコーダーはノイズ除去を行うため、再現性を確保するには generator を渡してください。

enable_tiling

< >

( tile_sample_min_height: int | None = Nonetile_sample_min_width: int | None = Nonetile_sample_min_num_frames: int | None = Nonetile_sample_stride_height: int | None = Nonetile_sample_stride_width: int | None = Nonetile_sample_stride_num_frames: int | None = None )

パラメータ

  • tile_sample_min_height (int, 省略可) — デコードされた1つのタイルの高さ(ピクセル単位)。
  • tile_sample_min_width (int, 省略可) — デコードされた1つのタイルの幅（ピクセル単位）。
  • tile_sample_min_num_frames (int, 省略可) — 1つのデコード済みタイルのフレーム数です。
  • tile_sample_stride_height (int, 省略可) — 2つの連続する垂直タイルの上端間のピクセル距離。tile_sample_min_heightとの差が、ブレンドされたオーバーラップ部分です。
  • tile_sample_stride_width (int, 省略可) — 連続する2つの水平タイルの左端間のピクセル距離です。
  • tile_sample_stride_num_frames (int, 省略可) — 連続する2つの時間方向のタイルの開始位置間のフレーム数です。

タイル化デコーディングを有効にします。最後のステージを除く決定論的なアップサンプリングステージは、常に完全な潜在変数を処理します（低解像度で実行され、計算コストが低い）。デコード時のメモリ使用量を支配する最後のステージおよびステージ5の拡散ブロックは、シームが線形にブレンドされる重複するタイル上で実行されます。

disable_tiling

< >

( )

タイル化デコーディングを無効にし、一度のパスで動画全体をデコードするようにします。

forward

< >

( z: Tensorgenerator: typing.Optional[torch.Generator] = Nonenum_inference_steps: int | None = Nonereturn_dict: bool = True ) → DecoderOutput or tuple

パラメータ

  • z (torch.Tensor) — (B, C, F, H, W) の形状を持つ潜在変数。すでに非正規化されていることが前提です（パイプラインは latents_mean / latents_std を適用します）。AutoencoderKLLTX2Video と一致します。
  • generator (torch.Generator、省略可) — このデコーダーはノイズ除去を行うため、デコードを再現可能にするにはジェネレーターを渡してください。
  • num_inference_steps (int, 任意) — デノイジングのステップ数。デコーダーの decoder_num_inference_steps 設定値がデフォルトです。
  • return_dict (bool、任意、デフォルトは True) — プレーンなタプルではなく DecoderOutput を返すかどうか。

戻り値

DecoderOutput または tuple

tiled_decode

< >

( z: Tensorgenerator: typing.Optional[torch.Generator] = Nonenum_inference_steps: int | None = None )

最後の決定論的ステージと、タイルごとに実行される拡散ステージを使用して、潜変数（latents）のバッチをデコードします。

Tiles は、最後の決定論的段階に入るグリッド上に存在します。この段階では、1 つのセルが出力ピクセルの固定ブロックに対応します。tile_sample_* のサイズは、このグリッドに変換されるため、セルサイズ（本番設定では空間的に 8 px、時間的に 2 フレーム）の倍数である必要があります。時間方向の Tiles は、因果的なフレームマッピングに従います。t=0 を含む Tile は、時間方向アップサンプルによる先頭の重複フレームを削除し、動画の末尾を含む Tile のみ NATTEN の境界パディングを持ちます。

Update on GitHub

←Kandinsky 6 VAE Oobleck AutoEncoder→