Hugging Face's logo

Diffusers documentation

SanaWMLTX2RefinerTransformer3DModel

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

and get access to the augmented documentation experience

to get started

SanaWMLTX2RefinerTransformer3DModel

SanaWMPipeline'in 2. aşaması olarak kullanılan, SanaWMLTX2Refiner tarafından yönlendirilen parça-nedensel otoregresif iyileştirici DiT.

LTX2VideoTransformer3DModel ile mimari olarak aynıdır — aynı yapılandırma argümanları, aynı alt modüller, aynı parametre adları — bu nedenle yayınlanmış bir LTX-2 kontrol noktası, değişiklik yapılmadan içine yüklenir. İleri geçiş farklıdır:

  • yalnızca video akışı çalıştırılır (ses ve ses/video çapraz dikkat dalları atlanır),
  • self-attention, açık bir kayan pencere KV önbelleği (SanaWMRefinerKVCache) ile çalışır; bu önbellek dikkat çukurunu (attention sink) ve son zamanlardaki rafine edilmiş geçmişi barındırır, böylece blok başına hesaplama sınırlı kalır ve toplam rafine etme maliyeti video uzunluğuyla doğrusal olarak ölçeklenir,
  • çağrıcı, video RoPE'yi sağlar; bu sayede her otoregresif pencere, kaynak videodaki her karenin mutlak indeksini korur (bkz. SanaWMLTX2RefinerTransformer3DModel.build_rotary_emb_for_absolute_positions()).

Model şu şekilde yüklenebilir:

import torch
from diffusers import SanaWMLTX2RefinerTransformer3DModel

transformer = SanaWMLTX2RefinerTransformer3DModel.from_pretrained(
    "Efficient-Large-Model/SANA-WM_bidirectional-diffusers",
    subfolder="refiner/transformer",
    torch_dtype=torch.bfloat16,
)

SanaWMLTX2RefinerTransformer3DModel

sınıf diffusers.SanaWMLTX2RefinerTransformer3DModel

< >

( in_channels: int = 128out_channels: int | None = 128patch_size: int = 1patch_size_t: int = 1num_attention_heads: int = 32attention_head_dim: int = 128cross_attention_dim: int = 4096vae_scale_factors: tuple = (8, 32, 32)pos_embed_max_pos: int = 20base_height: int = 2048base_width: int = 2048gated_attn: bool = Falsecross_attn_mod: bool = Falseaudio_in_channels: int = 128audio_out_channels: int | None = 128audio_patch_size: int = 1audio_patch_size_t: int = 1audio_num_attention_heads: int = 32audio_attention_head_dim: int = 64audio_cross_attention_dim: int = 2048audio_scale_factor: int = 4audio_pos_embed_max_pos: int = 20audio_sampling_rate: int = 16000audio_hop_length: int = 160audio_gated_attn: bool = Falseaudio_cross_attn_mod: bool = Falsenum_layers: int = 48activation_fn: str = 'gelu-approximate'qk_norm: str = 'rms_norm_across_heads'norm_elementwise_affine: bool = Falsenorm_eps: float = 1e-06caption_channels: int = 3840attention_bias: bool = Trueattention_out_bias: bool = Truerope_theta: float = 10000.0rope_double_precision: bool = Truecausal_offset: int = 1timestep_scale_multiplier: int = 1000cross_attn_timestep_scale_multiplier: int = 1000rope_type: str = 'interleaved'use_prompt_embeddings = Trueperturbed_attn: bool = Falseff_bias: bool = Trueaudio_ff_bias: bool = Trueuse_prompt_adaln_single: bool = Trueuse_keyframes_abs_pos_embedding: bool = False )

Parametreler

  • in_channels (int, varsayılan 128) — Girdideki kanal sayısı.
  • out_channels (int, varsayılan 128) — Çıktıdaki kanal sayısı.
  • patch_size (int, varsayılan 1) — Patch gömme katmanında kullanılacak uzamsal yamaların boyutu.
  • patch_size_t (int, varsayılan 1) — Patch gömme katmanında kullanılacak zamansal yamaların boyutu.
  • num_attention_heads (int, varsayılan 32) — Çok başlı dikkat (multi-head attention) için kullanılacak baş sayısı.
  • attention_head_dim (int, varsayılan 128) — Her baştaki kanal sayısı.
  • cross_attention_dim (int, varsayılan 4096) — Çapraz dikkat başlıkları için kanal sayısı.
  • num_layers (int, varsayılan 48) — Kullanılacak Transformer bloklarının katman sayısı.
  • activation_fn (str, varsayılan "gelu-approximate") — İleri beslemeli ağda kullanılacak aktivasyon fonksiyonu.
  • qk_norm (str, varsayılan "rms_norm_across_heads") — Kullanılacak normalizasyon katmanı.
  • rope_type (str, varsayılan "interleaved") — Hangi RoPE uygulamasının kullanılacağı ("interleaved" veya "split").

SANA-WM'nin 2. aşaması olarak kullanılan parça-nedensel otoregresif rafineleyici dönüştürücü.

LTX2VideoTransformer3DModel ile mimari olarak aynıdır — aynı yapılandırma argümanları, aynı alt modüller, aynı parametre adları — bu nedenle yayınlanmış bir LTX-2 kontrol noktası, değişiklik yapılmadan içine yüklenir. Farklı olan ileri geçiştir:

  • yalnızca video akışı çalıştırılır (ses ve ses/video çapraz dikkat dalları atlanır),
  • self-attention, açık bir kayan pencere KV önbelleği (SanaWMRefinerKVCache) ile çalışır; bu önbellek dikkat çukurunu (attention sink) ve son zamanlardaki rafine edilmiş geçmişi barındırır, böylece rafine etme maliyeti AR blok başına sınırlı kalır ve video uzunluğuyla doğrusal olarak ölçeklenir,
  • çağrıcı, video RoPE'yi sağlar; bu sayede her AR penceresi, kaynak videodaki her karenin mutlak indeksini koruyabilir (bkz. build_rotary_emb_for_absolute_positions()).

Kalan argümanlar LTX2VideoTransformer3DModel ile birebir örtüşür. Ses tarafındaki argümanlar ve alt modüller, yalnızca kontrol noktasındaki ses ağırlıklarının geri dönüşümünü sağlamak için korunur; refiner ileri geçişinde kullanılmazlar.

build_rotary_emb_for_absolute_positions

< >

( batch_size: intframe_positions: listheight: intwidth: intdevice: devicefps: float ) → tuple[torch.Tensor, torch.Tensor]

Parametreler

  • batch_size (int) — Koordinatların yayınlanacağı batch boyutu.
  • frame_positions (list[int]) — Bu pencere tarafından kapsanan mutlak latent kare indeksleri.
  • height (int), width (int) — Gizli uzamsal çözünürlük.
  • device (torch.device) — Koordinatların oluşturulacağı cihaz.
  • fps (float) — LTX-2'nin zamansal RoPE ölçeklemesini belirleyen video kare hızı.

Dönüş değeri

tuple[torch.Tensor, torch.Tensor]

(cos, sin) RoPE demeti.

Belirli bir mutlak gizli çerçeve indeksi listesi için video RoPE'yi oluşturun.

SanaWMLTX2AudioVideoRotaryPosEmbed.prepare_video_coords, ardışık bir torch.arange(num_frames) dizisi varsayar; bu, çift yönlü çıkarım için uygundur. Kayan pencere AR iyileştiricisi ise her karenin kaynak videodaki mutlak indeksini korumalıdır, böylece RoPE, [sink + recent + active] penceresi boyunca doğru zaman fazını yakalar.

forward

< >

( hidden_states: Tensorencoder_hidden_states: Tensortimestep: Tensorvideo_rotary_emb: tupleencoder_attention_mask: typing.Optional[torch.Tensor] = Nonekv_cache: diffusers.models.transformers.transformer_sana_wm_refiner.SanaWMRefinerKVCache | None = Nonekv_cache_mode: str | None = Noneattention_kwargs: dict | None = Nonereturn_dict: bool = True ) → Transformer2DModelOutput or tuple

Parametreler

  • hidden_states (torch.Tensor) — Aktif bloğun patchlenmiş video latentleri, şekli (batch_size, num_video_tokens, in_channels).
  • encoder_hidden_states (torch.Tensor) — (batch_size, text_seq_len, caption_channels) biçiminde metin gömme değerleri.
  • timestep (torch.Tensor) — (batch_size, num_video_tokens) biçiminde, self.config.timestep_scale_multiplier ile ölçeklenmiş zaman adımı.
  • video_rotary_emb (tuple[torch.Tensor, torch.Tensor]) — Aktif bloğun mutlak çerçeve konumları için (cos, sin) RoPE, build_rotary_emb_for_absolute_positions() tarafından döndürüldüğü gibi.
  • encoder_attention_mask (torch.Tensor, isteğe bağlı) — (batch_size, text_seq_len) biçiminde çarpımsal metin dikkat maskesi.
  • kv_cache (SanaWMRefinerKVCache, isteğe bağlı) — Katman başına dikkat çukuru (attention sink) ve son zamanlarda rafine edilmiş geçmişi, ayrıca paylaşılan sink_pe RoPE'yi içeren kayan pencere KV önbelleği. kv_cache_mode ayarlandığında her zaman gereklidir.
  • kv_cache_mode (str, isteğe bağlı) — Şunlardan biri:
    • "inject": [sink + history + current] K/V'lerine dikkat et (gürültü azaltma adımları).
    • "capture_pre_rope": önek yok; bu ileri geçişin RoPE öncesi K/V değerlerini önbelleğe kaydet (dikkat çukurunu ham 1. aşama latentlerinden tohumlamak için bir kez kullanılır).
    • "inject_and_capture_post_rope": [sink + history + current] K/V'lerine dikkat edin ve bu bloğun post-RoPE K/V'sini geçmişe eklenebilmesi için önbelleğe kaydedin.

    None olduğunda, blok yalnızca geçerli jetonlar üzerinde düz tam öz-dikkat çalıştırır.

  • attention_kwargs (dict, isteğe bağlı) — LoRA ölçek işleme iletilen isteğe bağlı kwargs.
  • return_dict (bool, isteğe bağlı, varsayılan True) — Düz bir tuple yerine Transformer2DModelOutput döndürülüp döndürülmemesi.

Dönüş değeri

Transformer2DModelOutput veya tuple

aktif blok için tahmini hız, şekli (batch_size, num_video_tokens, out_channels).

Tek bir AR bloğu üzerinde yalnızca video ileri geçişi.

SanaWMRefinerKVCache

sınıf diffusers.models.transformers.transformer_sana_wm_refiner.SanaWMRefinerKVCache

< >

( num_layers: int )

Parametreler

  • num_layers (int) — Katman başına bir önbellek ayırmak için tahsis edilecek dönüştürücü bloklarının sayısı.

Her dönüştürücü bloğu için bir [SanaWMRefinerKVLayerCache] ve paylaşılan sink RoPE içeren konteyner.

Bu, SANA-WM 2. aşama iyileştiricisinin eğitildiği rf_shifted_sink KV önbellek sözleşmesini uygular. İyileştirme parça-nedenseldir: block_size gizli çerçeve bir anda gürültüden arındırılırken, [dikkat çukuru + yakın geçmiş + aktif blok] sınırlı penceresindeki K/V'lerine dikkat edilir.

  • sink_pe: (cos, sin) RoPE demeti, kayan sink_rope_offset üzerinde her AR penceresi için yeniden oluşturulur; böylece sink, sınırlı çalışma önbelleğinin hemen öncesinde konumlanır. RoPE katmana bağlı olmadığı için katmanlar arasında paylaşıldır.

SanaWMRefinerKVLayerCache

sınıf diffusers.models.transformers.transformer_sana_wm_refiner.SanaWMRefinerKVLayerCache

< >

( )

SANA-WM stage-2 chunk-causal AR refiner için katman başına KV önbelleği.

Refiner'in kendine dikkat (self-attention) mekanizmasının odaklandığı kayan pencere önekinin iki yarısını ve son ileri geçişin yakaladığı K/V değerlerini geri okumak için bir yuva tutar. Tüm tensörler (batch_size, num_tokens, inner_dim) biçimindedir (yani baş başına unflatten işleminden önce) ve refiner'in kendine dikkat mekanizmasının birleştirdiği yerleşimle eşleşir.

  • sink_k_pre / sink_v: pre-RoPE K/V, dikkat çukur (attention-sink) karelerine ait, ham 1. aşama latentlerinden bir kez yakalanan değerler. RoPE uygulanmadan önce saklanırlar; böylece her AR penceresi, kendi kaydırılmış çukur ofsetinde RoPE'yi yeniden uygulayabilir (SanaWMRefinerKVCache.sink_pe).
  • history_k / history_v: post-RoPE K/V, zaten iyileştirilmiş son karelerin, olduğu gibi birleştirilmeye hazır hali.
  • captured_k_pre / captured_v_pre ve captured_k_post / captured_v_post: yakalama kv_cache_modeleri tarafından yazılan geri okuma yuvaları.

get_captured_post_rope

< >

( )

Son ileri geçişte yakalanan RoPE sonrası K/V'yi çıkarın.

get_captured_pre_rope

< >

( )

Son ileri geçişte yakalanan RoPE öncesi K/V değerlerini çıkarın.

get_history

< >

( )

RoPE sonrası son tarihli K/V'yi döndürür, boşsa None.

get_sink

< >

( )

Pre-RoPE sink K/V'yi döndürür, yakalanmamışsa (veya boşsa) None döndürür.

store_captured_post_rope

< >

( key: Tensorvalue: Tensor )

Mevcut ileri geçiş tarafından üretilen RoPE sonrası K/V'yi saklayın.

store_captured_pre_rope

< >

( key: Tensorvalue: Tensor )

Mevcut ileri yayılım tarafından üretilen RoPE öncesi K/V değerlerini saklayın.

store_history

< >

( history_k: Tensorhistory_v: Tensor )

RoPE sonrası son tarihli K/V'yi saklayın.

store_sink

< >

( sink_k_pre: Tensorsink_v: Tensor )

RoPE öncesi sink K/V'lerini saklayın.

Transformer2DModelOutput

sınıf diffusers.models.modeling_outputs.Transformer2DModelOutput

< >

( sample: torch.Tensor )

Parametreler

  • sample (torch.Tensor, şekli (batch_size, num_channels, height, width) veya Transformer2DModel ayrık (discrete) ise (batch size, num_vector_embeds - 1, num_latent_pixels)) — encoder_hidden_states girdisine koşullu gizli durum (hidden states) çıktısı. Ayrık (discrete) ise, gürültüsü kaldırılmış (unnoised) gizli (latent) pikseller için olasılık dağıtımlarını döndürür.

Transformer2DModel'nin çıktısı.

Update on GitHub

←SanaVideoTransformer3DModel SanaWMTransformer3DModel→