Diffusers documentation

SANA-WM

Diffusers

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).

Join the Hugging Face community

and get access to the augmented documentation experience

Collaborate on models, datasets and Spaces

Faster examples with accelerated inference

Switch between documentation themes

to get started

SANA-WM

SANA-WM, SANA üzerine inşa edilmiş, kamera kontrollü görüntüden videoya dünya modelidir. İlk kare görüntüsü, bir metin komutu ve bir kamera yörüngesi (açıkça belirtilmiş c2w pozları veya WASD/IJKL eylem dizesi) verildiğinde, hareketi istenen kamera yolunu izleyen bir video üretir.

Çıkarım iki aşamada çalışır:

Aşama 1 — SANA-WM DiT. GDN-Triton doğrusal dikkat ve UCPE kamera kontrol dalına sahip, 1,6B parametreli çift yönlü bir DiT. Örnekleme, token başına zaman adımları kullanan LTX tarzı bir akış eşleştirme Euler zamanlayıcısı ile yapılır; ilk gizli çerçeve, koşullandırma çapasıdır.
Aşama 2 — LTX-2 iyileştirici (isteğe bağlı). SanaWMLTX2RefinerTransformer3DModel + LTX2TextConnectors ve bir Gemma-3 metin kodlayıcısını saran, 3 damıtılmış sigma adımı için çalıştırılan ayrı bir sink-bidirectional Euler iyileştirici hattı (SanaWMLTX2Refiner).

Her iki aşama da AutoencoderKLLTX2Video VAE üzerinden çözümlenir.

Mevcut modeller:

Model	Önerilen dtype
`Efficient-Large-Model/SANA-WM_bidirectional-diffusers`	`torch.bfloat16`
`Efficient-Large-Model/SANA-WM_bidirectional-diffusers-refiner`	`torch.bfloat16`

SANA-WM, sabit 704×1280 çözünürlükte eğitilmiştir. Transformer ağırlıkları için önerilen dtype — en iyi sayısal sonuçlar için metin kodlayıcıyı torch.bfloat16 ve VAE'yi torch.float32 olarak tutun. Pipeline, kamera içsel parametrelerini [fx, fy, cx, cy] olarak orijinal görüntü piksel koordinatlarında bekler; yeniden boyutlandırma ve merkezden kırpma dönüşümü dahili olarak uygulanır.

Çıkarım

import torch
from PIL import Image

from diffusers import SanaWMPipeline
from diffusers.utils import export_to_video

pipe = SanaWMPipeline.from_pretrained(
    "Efficient-Large-Model/SANA-WM_bidirectional-diffusers",
    torch_dtype=torch.bfloat16,
)
pipe.enable_model_cpu_offload()  # ~45 GB of weights — offload between stages

# SANA-WM was trained on the LTX-2 VAE in framewise mode with tiling enabled. Without these
# settings the VAE encodes the whole (B, C, T, H, W) clip in one shot, which gives subtly
# different numerics from the released checkpoint.
pipe.vae.enable_tiling()
pipe.vae.use_framewise_encoding = True
pipe.vae.use_framewise_decoding = True
pipe.vae.tile_sample_stride_num_frames = 64
pipe.vae.tile_sample_min_num_frames = 96

prompt = "A car driving across a vast desert plain at golden hour."
output = pipe(
    image=Image.open("input.png").convert("RGB"),
    prompt=prompt,
    action="w-80,jw-40,w-40",        # WASD-style action DSL: forward 80f, jump+forward 40f, forward 40f
    intrinsics=[800.0, 800.0, 845.0, 464.0],  # fx, fy, cx, cy in original-image pixels
    num_frames=161,
    num_inference_steps=60,
    guidance_scale=5.0,
    generator=torch.Generator(device="cuda").manual_seed(42),
    output_type="latent",            # hand the latents to the refiner below
)

action=None parametresini geçirin ve kamera yörüngesini açıkça yönlendirmek için kendi c2w pozlarınızı ((F, 4, 4) numpy dizisi) sağlayın. output_type="latent" parametresini kaldırarak videoyu doğrudan 1. aşamadan alın ve iyileştiriciyi (refiner) atlayın.

Aşama 2 — LTX-2 iyileştirici

SanaWMLTX2Refiner, SDXL'in taban ve rafineri modelleri ayırma biçiminde olduğu gibi kendi deposu olarak dağıtılır. Ağırlıkların iki kez yüklenmesi yerine paylaşılması için taban hattın VAE'sini iletin:

from diffusers import SanaWMLTX2Refiner

refiner = SanaWMLTX2Refiner.from_pretrained(
    "Efficient-Large-Model/SANA-WM_bidirectional-diffusers-refiner",
    vae=pipe.vae,
    torch_dtype=torch.bfloat16,
)
refiner.enable_model_cpu_offload()

frames = refiner(output.latent, prompt, fps=16)
export_to_video(list(frames), "sana_wm.mp4", fps=16)

vae olmadan refiner, video yerine rafine edilmiş latents döndürür; bu, kendiniz decode etmek istiyorsanız faydalıdır.

Her iki pipeline için de offloading'i etkinleştirin veya 2. aşamadan önce 1. aşamayı serbest bırakın (pipe.transformer.to("cpu")). İki aşama birlikte torch.bfloat16 ile yaklaşık 45 GB tutar ve her ikisinin de tek bir 80 GB kartta aktif kalması, aktivasyonlar için yeterince yer bırakmaz. Ayrıca 2. aşamanın torch_dtype parametresine uyduğunu da not edelim: refiner'ı torch.float32 ile yüklemek bellek kullanımını yaklaşık ikiye katlar ve çıktıyı hafifçe değiştirir.

Kamera içsel parametreleriniz yoksa, barındırılan bir modüler blok bunları tek bir kareden tahmin edebilir. diffusers dışında tutulmasının nedeni, Pi3X’i çekmesidir — bu da ek bir bağımlılık ve ikinci bir checkpoint demektir — bu yüzden siz talep edene kadar hiçbir şey indirilmez:

from diffusers import ModularPipeline

# One-time per image. Requires `pip install pi3-vision`.
estimator = ModularPipeline.from_pretrained(
    "Efficient-Large-Model/pi3x-intrinsics-estimator", trust_remote_code=True
)
estimator.load_components(dtype=torch.bfloat16)
intrinsics = estimator(image=Image.open("input.png").convert("RGB"), output="intrinsics")

Yayınlanan kontrol noktasını dönüştürme

SANA-WM kaynak sürümüne (ön dönüştürülmüş diffusers anlık görüntüsüne değil) sahipseniz, dönüştürme betiğini bir kez çalıştırın:

python scripts/convert_sana_wm_to_diffusers.py \
    --src Efficient-Large-Model/SANA-WM_bidirectional \
    --dst ./SANA-WM_bidirectional-diffusers

Bu işlem iki dizin yazar: temel hattı --dst konumuna ve 2. aşama iyileştiricisini yanına ./SANA-WM_bidirectional-diffusers-refiner konumuna (--dst-refiner ile geçersiz kılınabilir). Ardından her birini yerel yolundan normal şekilde yükleyin.

Bileşenler

tokenizer — GemmaTokenizerFast
text_encoder — Gemma-2 (decoder gizli durumlarını döndürür)
vae — AutoencoderKLLTX2Video (LTX-2, uzamsal ×32 / zamansal ×8)
transformer — SanaWMTransformer3DModel, 1,6B parametreli çift yönlü DiT
scheduler — FlowMatchEulerDiscreteScheduler

Stage-2 refiner, kendi transformer (SanaWMLTX2RefinerTransformer3DModel), connectors (LTX2TextConnectors), tokenizer, Gemma-3 text_encoder ve scheduler bileşenlerine sahip ayrı bir depodur. Kendine ait bir vae yoktur — temel pipeline'ınkini iletin.

SanaWMPipeline

sınıf diffusers.SanaWMPipeline

< source >

( tokenizer: GemmaTokenizer | GemmaTokenizerFasttext_encoder: Gemma2PreTrainedModelvae: AutoencoderKLLTX2Videotransformer: SanaWMTransformer3DModelscheduler: FlowMatchEulerDiscreteScheduler )

Parametreler

tokenizer ([GemmaTokenizer] veya [GemmaTokenizerFast]) — Gemma-2 tokenizer'ı.
text_encoder ([Gemma2PreTrainedModel]) — Gemma-2 metin kodlayıcısı.
vae ([AutoencoderKLLTX2Video]) — LTX-2 VAE'si.
transformer ([SanaWMTransformer3DModel]) — 1600M parametreli çift yönlü SANA-WM DiT.
scheduler ([FlowMatchEulerDiscreteScheduler]) — Flow-matching Euler zamanlayıcısı (LTX tarzı token başına zaman adımları). latents doğrudan.

SANA-WM kamera kontrollü görüntüden videoya dönüştürme hattı.

İlk kare görüntüsünden, bir metin komutundan ve bir kamera yörüngesinden (açık c2w pozları veya bir WASD/IJKL eylem dizesi) video üretir. 1. aşama örneklemesi için 1600M çift yönlü SANA DiT'yi, 2. aşama cilası için LTX-2 sink-bidirectional Euler iyileştiricisini kullanır; her ikisi de LTX-2 VAE üzerinden çözümlenir.

call

< source >

( image: PIL.Image.Image | str | Pathprompt: strc2w: np.ndarray | None = Noneaction: str | None = Noneintrinsics: np.ndarray | list[float] | None = Noneheight: int = 704width: int = 1280num_frames: int = 161fps: int = 16num_inference_steps: int = 60guidance_scale: float = 5.0negative_prompt: str = ''generator: torch.Generator | list[torch.Generator] | None = Noneprompt_embeds: torch.Tensor | None = Noneprompt_attention_mask: torch.Tensor | None = Nonenegative_prompt_embeds: torch.Tensor | None = Nonenegative_prompt_attention_mask: torch.Tensor | None = Nonemax_sequence_length: int = 300chi_prompt: list[str] | None = Noneoutput_type: Literal['np', 'pil', 'pt', 'latent'] = 'np'callback_on_step_end: Callable[[DiffusionPipeline, int, int, dict], dict] | None = Nonecallback_on_step_end_tensor_inputs: list[str] = ['latents']return_dict: bool = True )

Parametreler

image (PIL.Image.Image veya str) — İlk kare görüntüsü (PIL veya yol).
prompt (str) — Metin istemi.
c2w (np.ndarray, opsiyonel) — (F, 4, 4) kamera-dünya pozları. action ile karşılıklı dışlayıcıdır.
action (str, isteğe bağlı) — Action-DSL dizesi, örn. "w-80,jw-40,w-40". c2w ile birbirini dışlar.
intrinsics (np.ndarray veya list[float]) — [fx, fy, cx, cy], orijinal görüntü piksel koordinatlarında. Pipeline, yeniden boyutlandırma + kırpma dönüşümünü içsel olarak uygular.
height (int, varsayılan 704) — Çıktı kare yüksekliği (halka açık model için sabittir).
width (int, varsayılan 1280) — Çıktı kare genişliği (halka açık model için sabittir).
num_frames (int, varsayılan 161) — Hedef kare sayısı; 8k+1 değerine ayarlanır (LTX-2 VAE kısıtı).
fps (int, varsayılan 16) — Çıktı kare hızı (aynı zamanda refine ediciye de iletilir).
num_inference_steps (int, varsayılan 60) — 1. aşama DiT örneklemesi için adım sayısı.
guidance_scale (float, varsayılan 5.0) — Sınıflandırıcı-ücretsiz yönlendirme ölçeği.
negative_prompt (str, varsayılan "") — İsteğe bağlı negatif istem.
generator (torch.Generator veya list[torch.Generator], isteğe bağlı) — Gürültü örneklemesini deterministik hale getirmek için bir veya daha fazla torch üreteci. None ise, örneklemeler deterministik değildir.
prompt_embeds (torch.Tensor, opsiyonel) — Metin kodlayıcısını atlamak için önceden hesaplanmış metin gömme değerleri. prompt_attention_mask ile birlikte geçirilmelidir.
prompt_attention_mask (torch.Tensor, isteğe bağlı) — prompt_embeds için dikkat maskesi.
negative_prompt_embeds (torch.Tensor, isteğe bağlı) — Önceden hesaplanmış negatif metin gömme değerleri. negative_prompt_attention_mask ile birlikte geçirilmelidir.
negative_prompt_attention_mask (torch.Tensor, isteğe bağlı) — negative_prompt_embeds için dikkat maskesi.
max_sequence_length (int, varsayılan 300) — Maksimum istem jetonları.
chi_prompt (list[str], optional) — Chi-prompt önekini geçersiz kılar (varsayılan, herkese açık sürümle aynıdır).
output_type (“np”, “pil”, “pt” veya “latent”, varsayılan “np”) — Çıktı biçimi.
callback_on_step_end (Callable, isteğe bağlı) — Her gürültü azaltma adımının sonunda callback_on_step_end(self, step, timestep, callback_kwargs) olarak çağrılır; burada callback_kwargs, callback_on_step_end_tensor_inputs içinde adları belirtilen tensörleri içerir. Dönen sözlükteki tensörler, hattınkileri değiştirir.
callback_on_step_end_tensor_inputs (list[str], varsayılan [“latents”]) — callback_on_step_end işlevine iletilecek tensörler; ._callback_tensor_inputs kümesinin bir alt kümesi olmalıdır.
return_dict (bool, varsayılan True) — [tuple yerine SanaWMPipelineOutput döndür.

SANA-WM kamera kontrollü video oluşturun.

Örnekler:

>>> import torch
>>> from PIL import Image
>>> from diffusers import SanaWMPipeline

>>> pipe = SanaWMPipeline.from_pretrained(
...     "Efficient-Large-Model/SANA-WM_bidirectional-diffusers", torch_dtype=torch.bfloat16
... ).to("cuda")

>>> output = pipe(
...     image=Image.open("input.png").convert("RGB"),
...     prompt="A car driving across a vast desert plain at golden hour.",
...     action="w-80,jw-40,w-40",
...     intrinsics=[800.0, 800.0, 845.0, 464.0],  # fx, fy, cx, cy in original-image pixels
...     num_inference_steps=60,
... )
>>> # output.frames is (T, H, W, 3) float np.ndarray in [0, 1] (diffusers convention).

check_inputs

< source >

__call__ girdilerini doğrular. Geçersiz girdide hata fırlatır ve hiçbir şey döndürmez.

encode_prompt

< source >

( prompt: strnegative_prompt: str = ''device: torch.device | None = Nonemax_sequence_length: int = 300chi_prompt: list[str] | None = Noneprompt_embeds: torch.Tensor | None = Noneprompt_attention_mask: torch.Tensor | None = Nonenegative_prompt_embeds: torch.Tensor | None = Nonenegative_prompt_attention_mask: torch.Tensor | None = None )

Gemma-2 üzerinden prompt + negatif prompt'u kodlayın.

SANA chi-prompt-prefix hilesini yansıtır: chi prompt, kullanıcı promptunun başına eklenir, ardından select_index = [0, -L+1, ..., -1] dilimi BOS token'ını ve son max_sequence_length - 1 token'ı alır.

prepare_camera_trajectory

< source >

( c2w: np.ndarray | Noneaction: str | Noneintrinsics: np.ndarray | list[float]num_frames: int )

Kamera girdilerini (c2w_(F, 4, 4), intrinsics_(F, 4)) olarak normalize edin.

Ayrıca num_frames değerini VAE uyumlu 8k+1 değerine yuvarlar ve her iki diziyi buna göre kırpıp eşitler. Kırpılmış görüntü ve yeniden ölçeklenmiş içsel parametreler, hedef çözünürlük bilindiğinde daha sonra gelir.

prepare_latents

< source >

( first_latent: torch.Tensornum_frames: intheight: intwidth: intdtype: torch.dtypedevice: torch.devicegenerator: torch.Generator )

Başlangıç latenslerini örnekleyin ve ilk kareyi koşullama çapası olarak sabitleyin.

(latents, condition_mask) döndürür; burada condition_mask, ilk karedeki tokenlarda (örnekleme boyunca temiz tutulurlar) bir, diğer yerlerde sıfır içerir.

SanaWMLTX2Refiner

LTX-2 stage-2 refiner, stage-1 latents alan bağımsız bir DiffusionPipeline'dir. Videoya decode etmesi için ona bir vae (ağırlıkların paylaşılması için temel pipeline'ınki) verin; yoksa rafine edilmiş latents döndürür.

sınıf diffusers.SanaWMLTX2Refiner

< source >

( transformer: SanaWMLTX2RefinerTransformer3DModelconnectors: LTX2TextConnectorstokenizer: GemmaTokenizer | GemmaTokenizerFasttext_encoder: Gemma3ForConditionalGenerationscheduler: FlowMatchEulerDiscreteSchedulervae: AutoencoderKLLTX2Video | None = Nonetext_max_sequence_length: int = 1024 )

Parametreler

transformer ([SanaWMLTX2RefinerTransformer3DModel]) — Parça-nedensel kayan pencere KV önbelleğine sahip LTX-2 video DiT'si.
connectors ([LTX2TextConnectors]) — LTX-2 metin konnektörleri.
tokenizer — Gemma-3 tokenizer'ı.
text_encoder — Gemma-3 metin kodlayıcısı.
scheduler ([FlowMatchEulerDiscreteScheduler]) — Flow-matching Euler zamanlayıcısı. Damıtılmış sigmaların değiştirilmeden geçmesi için shift=1.0 ile oluşturulur.
vae ([AutoencoderKLLTX2Video], isteğe bağlı) — [SanaWMPipeline] tarafından kullanılan aynı VAE; ağırlıkları paylaşmak için vae=pipe.vae parametresini iletin. Verildiğinde, iyileştirici videoya çözümlenir, aksi halde iyileştirilmiş latentler döndürülür.
text_max_sequence_length (int, varsayılan 1024) — Gemma-3 tokenizer'ına iletilen maksimum token sayısı.

LTX-2 sink-bidirectional Euler refiner — SANA-WM 2. aşama, bağımsız bir pipeline olarak.

LTX-2 bileşenlerini (refiner transformer + metin bağlayıcıları + Gemma-3 metin kodlayıcı + tokenizer) ve damıtılmış sigma zamanlamasını taşıyıp Euler adımlarını gerçekleştiren [FlowMatchEulerDiscreteScheduler] bileşenini sarar. [SanaWMPipeline] içinde isteğe bağlı bir bileşen olarak kayıtlıdır ve ayrıca 1. aşama latentlerini rafine etmek için tek başına da kullanılabilir.

call

< source >

( sana_latent: torch.Tensorprompt: strfps: floatsink_size: int = 1generator: torch.Generator | None = Noneblock_size: int = 3kv_max_frames: int = 11sigmas: tuple[float, ...] = (0.909375, 0.725, 0.421875, 0.0)output_type: str = 'np' ) → torch.Tensor

Parametreler

sana_latent — (B, C, F, H, W) 1. aşama latent.
prompt — metin komutu.
fps — video kare hızı (LTX-2 RoPE zaman ölçeklemesini belirler).
sink_size — dikkat çapası olarak sabitlenecek baştaki ham z_sana karelerinin sayısı (standart: 1).
generator — FM uç noktası gürültüsü için torch.Generator. Varsayılan olarak, sonuçların kutudan çıktığı gibi tekrarlanabilir olmasını sağlamak için 42 ile tohumlanmış bir üreteçtir.
block_size — AR bloğu başına latent kare sayısı (standart: 3).
kv_max_frames — kayan pencerede tutulan maksimum bağlam+aktif kare sayısı (standart: 11 = 1 çapa + 10 son kare).
sigmas — 0.0'da sonlanan azalan Euler zamanlaması (standart 3 adımlık damıtılmış: (0.909375, 0.725, 0.421875, 0.0)). self.scheduler'a iletilir (sonundaki 0.0 hariçtir; zamanlayıcı bunu kendisi ekler).
output_type — “latent”, rafine edilmiş latentleri döndürür. Diğer tüm değerler, self.vae üzerinden çözümlenir ve ilgili tipe (“np”, “pt”, “pil”) göre son işleme tabi tutulur; vae yoksa latentler her durumda döndürülür.

Dönüş değeri

torch.Tensor

(B, C, F, H, W) biçiminde rafine edilmiş VAE latents — ilk sink_size kare, ham 1. aşama sink latents'ini değiştirilmeden taşır, geri kalanı ise rafine edilmiş çıktıyı taşır.

LTX-2 iyileştiricisini çalıştırın ve iyileştirilmiş VAE latentlerini döndürün.

Modelin eğitiminde kullanılan chunk-causal AR tarifini kullanır (block_size=3, kv_max_frames=11): [source_sink + recent_history + active_block] K/V'lerinden oluşan kayan pencere, transformer'a blok blok beslenir; böylece blok başına hesaplama sınırlı kalır ve toplam iyileştirme maliyeti video uzunluğuyla doğrusal olarak ölçeklenir.

SanaWMPipelineOutput

sınıf diffusers.SanaWMPipelineOutput

< source >

( frames: typing.Union[torch.Tensor, numpy.ndarray, list[list[PIL.Image.Image]]]c2w: numpy.ndarray | None = Nonelatent: typing.Optional[torch.Tensor] = None )

Parametreler

frames (torch.Tensor, np.ndarray veya list[PIL.Image.Image]) — Oluşturulan video: output_type="np" için [0, 1] aralığında (T, H, W, 3) biçiminde bir float np.ndarray, "pt" için (T, 3, H, W) biçiminde bir tensör, "pil" için T adet `PIL.Image` içeren bir liste veya "latent" için (B, C, T_lat, H_lat, W_lat) biçiminde latent tensör.
c2w (np.ndarray) — frames ile hizalı kamera-dünya pozları (T, 4, 4) (refiner, çapa çerçevesini düşürür; refiner çalıştıysa bu dizi buna göre yeniden hizalanır).
latent (torch.Tensor, isteğe bağlı) — LTX-2 VAE uzayındaki gizli tensör, şekli (B, C, T_lat, H_lat, W_lat). `output_type=“latent”“` olduğunda döndürülür.

SANA-WM görüntüden videoya hattı için çıktı sınıfı.

Update on GitHub

←Sana Video Shap-E→