diffusers/main/tr/api/models/ltx2_diffusion_decoder.md

LTX2VideoDiffusionDecoderModel

Lightricks tarafından LTX-2.5'te tanıtılan difüzyon video kodlayıcısı. Mahalle-dikkat (neighborhood-attention) aşamaları, gizli değişkeni (latent) bir bağlam hacmine (context volume) yukarı örnekler (upsample) ve son aşama, bu bağlama koşullu olarak pikselleri gürültüden arındırır (denoise).

Bu bir oto-ansamblör değil, bir çözücüdür: kodlama AutoencoderKLLTX2Video ile birlikte kalır ve bu model, onun gizli uzayını değiştirmeden tüketir; bu nedenle gizli değişkenler, konvolüsyonel çözücü ile bu model arasında değiştirilebilir. Kendi başına bir difüzyon modeli olduğu için, bir hattın vae parametresi olarak geçirilmek yerine LTX2VideoDiffusionDecodePipeline tarafından sürülür: herhangi bir LTX-2 hattını output_type="latent" ile çalıştırın, ardından çözümlen.

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, çözümleme hattında isteğe bağlı bir bileşendir: yalnızca denormalize=True olduğunda gizli değişken istatistikleri için başvurulur ve çözümleyici kendi istatistiklerini taşır, bu nedenle yalnızca çözümleme içeren bir iş akışı ikinci bir oto-kodlayıcı yüklemek zorunda değildir.

Dikkat arka uçları

Mahalle-dikkat penceresi bir BlockMask olarak ifade edilir, bu nedenle decoder varsayılan olarak flex dikkat arka ucunda çalışır ve ek bir bağımlılık gerektirmez. PyTorch, siz istemedikçe flex_attention derlemesini yapmaz ve derlenmemiş hali tam puan matrisini somutlaştırır — bu da tam çözünürlüklü dizi uzunluklarında uygulanabilir değildir. Bu durumlar için ya decoder'ı derleyin ya da orijinal uygulamanın da kullandığı NATTEN çekirdeklerine geçin. İşleyici, NATTEN'i kernels paketi aracılığıyla Hub'dan (shi-labs/natten) alır, bu yüzden yerel bir NATTEN derlemesi yerine pip install kernels gerekir:

from diffusers.models.autoencoders.ltx2_diffusion_decoder import LTX2VideoVaeNeighborhoodNattenProcessor

decoder.set_attn_processor(LTX2VideoVaeNeighborhoodNattenProcessor())

Hub'dan çekirdek indirme kodunu alır, bu nedenle uzaktan kod küresel olarak DIFFUSERS_DISABLE_REMOTE_CODE=true ile devre dışı bırakıldığında işlemci hata fırlatır.

Decoder'daki her dikkat modülü aynı komşuluk dikkatidir (çekirdek boyutu gibi aşama bazlı farklar işlemcide değil, modülde bulunur), bu nedenle set_attn_processor hepsini tek bir paylaşılan örnekle değiştirir.

backend'in (decoder.set_attention_backend(...)) flex dışında herhangi bir değere değiştirilmesi şu hatayı verir: başka hiçbir backend BlockMask'i kabul etmez. Bunun yerine yukarıdaki NATTEN işleyicisini kullanın.

Dolgu

decoder.enable_tiling(), tepe bellek kullanımını video boyutu yerine karoların boyutuyla sınırlamak için üst üste binen karolar halinde çözer ve bu karoları birleştirir. Ucuz erken aşama büyütme (upsampling) aşamaları hâlâ tam latent alanı görür; yalnızca çözüme bellek açısından baskın olan son büyütme aşaması ve difüzyon aşaması karolara göre çalışır — bu nedenle karolama, çıktıyı yalnızca karo sınırlarına yakın bölgelerde değiştirir. Difüzyon aşaması her karoyu ayrı ayrı gürültüden arındırdığı için, karolu bir çözüm, karosuz sonucu tam olarak yeniden üretmez; varsayılan karo ve örtüşme boyutları, referans uygulamanınkilerle eşleşir. Komşuluk dikkati (neighborhood attention), çekirdeğinden daha küçük herhangi bir ızgarayı reddettiğinden, sonundaki artan karo, kendi başına çözülmek yerine komşusuyla birleştirilir.

LTX2VideoDiffusionDecoderModel[[diffusers.LTX2VideoDiffusionDecoderModel]]

diffusers.LTX2VideoDiffusionDecoderModel[[diffusers.LTX2VideoDiffusionDecoderModel]]

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

Kaynak

LTX-2.5'te tanıtılan LTX-2 difüzyon video kodlayıcısı.

Bu bir otoenkoder değil, bir çözücüdür: enkoderi yoktur ve latent üretemez. Kodlama, AutoencoderKLLTX2Video ile kalır; bu bileşen, o bileşenin latent uzayını değiştirmeden kullanır, bu nedenle latentler konvansiyonel çözücü ile bu çözücü arasında değiştirilebilir.

Ayrıca deterministik bir çözücü değil, bir difüzyon modelidir — latentlerden oluşturulan bir bağlam hacmine koşullu olarak pikselleri gürültüden arındırır — bu nedenle bir pipeline'ın vae olarak geçirilmesi yerine LTX2VideoDiffusionDecodePipeline tarafından yönlendirilir.

Latent istatistikler, decode hattının ikinci bir otoenkoder yüklemesine gerek kalmadan, yalnızca iki vektör için denormalizasyon yapabildiği için burada tamponlar olarak taşınır.

Bu model ModelMixin sınıfından devralır. Tüm modeller için uygulanan genel yöntemlerini (indirme veya kaydetme gibi) görmek için üst sınıfın belgelendirmesine bakın.

decode[[diffusers.LTX2VideoDiffusionDecoderModel.decode]]

decode(z: Tensor, generator: typing.Optional[torch.Generator] = None, num_inference_steps: int | None = None, return_dict: bool = True)

Kaynak

Bir latent grubunu çözümlenir.

z'in zaten normalleştirilmemiş olması beklenir (pipeline latents_mean / latents_std uygular), bu da AutoencoderKLLTX2Video ile uyumludur. Bu decoder gürültü temizler, bu nedenle yeniden üretilebilirlik için generator parametresini iletin.

enable_tiling[[diffusers.LTX2VideoDiffusionDecoderModel.enable_tiling]]

enable_tiling(tile_sample_min_height: int | None = None, tile_sample_min_width: int | None = None, tile_sample_min_num_frames: int | None = None, tile_sample_stride_height: int | None = None, tile_sample_stride_width: int | None = None, tile_sample_stride_num_frames: int | None = None)

Kaynak

Parametreler:

tile_sample_min_height (int, isteğe bağlı) : Piksel cinsinden, çözümlenmiş bir karoyun yüksekliği.

tile_sample_min_width (int, isteğe bağlı) : Piksel cinsinden, çözümlenmiş bir karoyun genişliği.

tile_sample_min_num_frames (int, isteğe bağlı) : Çözümlenmiş bir karoyun kare sayısı.

tile_sample_stride_height (int, isteğe bağlı) : İki ardışık dikey karonun üstleri arasındaki piksel cinsinden mesafe; tile_sample_min_height ile farkı, karışık örtüşmeyi ifade eder.

tile_sample_stride_width (int, isteğe bağlı) : İki ardışık yatay karonun sol kenarları arasındaki piksel cinsinden mesafe.

tile_sample_stride_num_frames (int, isteğe bağlı) : Ardışık iki zaman diliminin başlangıçları arasındaki kare cinsinden mesafe.

Döşemeli çözmeyi etkinleştirir. Son aşamadan önceki deterministik yukarı örneklemeye aşamaları her zaman tam latent'i işler (düşük çözünürlükte çalışırlar ve maliyetleri düşüktür); çözmeyi bellek açısından baskın kılan son aşama ve 5. aşama difüzyon blokları ise dikişleri doğrusal olarak karıştırılan örtüşen döşemeler üzerinde çalışır.

disable_tiling[[diffusers.LTX2VideoDiffusionDecoderModel.disable_tiling]]

disable_tiling()

Kaynak

Döşemeli çözmeyi devre dışı bırakın ve tüm videoyu tek geçişte çözmeye geri dönün.

forward[[diffusers.LTX2VideoDiffusionDecoderModel.forward]]

forward(z: Tensor, generator: typing.Optional[torch.Generator] = None, num_inference_steps: int | None = None, return_dict: bool = True)

Kaynak

Parametreler:

z (torch.Tensor) : (B, C, F, H, W) boyutunda, zaten normalizasyonu kaldırılmış (pipeline latents_mean / latents_std uygular) ve AutoencoderKLLTX2Video ile eşleşen latentler.

generator (torch.Generator, isteğe bağlı) : Bu decoder gürültü azaltma işlemini gerçekleştirdiğinden, çözümlemeyi tekrarlanabilir kılmak için bir üreteç (generator) iletin.

num_inference_steps (int, isteğe bağlı) : Gürültü azaltma adım sayısı. Varsayılan olarak decoder'ın decoder_num_inference_steps yapılandırma değerine ayarlanır.

return_dict (bool, isteğe bağlı, varsayılan True) : Düz bir tuple yerine DecoderOutput döndürülüp döndürülmemesi.

Dönüş: DecoderOutput veya tuple

tiled_decode[[diffusers.LTX2VideoDiffusionDecoderModel.tiled_decode]]

tiled_decode(z: Tensor, generator: typing.Optional[torch.Generator] = None, num_inference_steps: int | None = None)

Kaynak

Bir latent grubunu, son deterministik aşama ve her karoyu (tile) için ayrı ayrı çalışan difüzyon aşamasıyla çözümlendirin.

Tiles, son deterministik aşamaya giren ızgarada yaşar; bu aşamada bir hücre, sabit bir çıktı piksel bloğuna eşlenir. tile_sample_* boyutları bu ızgaraya dönüştürülür, bu nedenle hücre boyutunun katları olmalıdır (üretim yapılandırması için uzaysal olarak 8 px ve zamansal olarak 2 kare). Zamansal tiles, nedensel kare eşlemesini izler: t=0 içeren tile, zamansal yukarı örneklemenin kopya başlangıç karesini atar ve yalnızca video sonunu içeren tile NATTEN sınır dolgusunu taşır.