Diffusers documentation
WanAnimate2Transformer3DModel
WanAnimate2Transformer3DModel
Alibaba Wan Team의 Wan-Animate-2에 사용되는 3D 비디오 유사 데이터용 Diffusion Transformer 모델입니다. 인-컨텍스트 참조 메커니즘을 통해 구동 비디오의 움직임으로 캐릭터 이미지를 애니메이션화합니다. 각 세그먼트는 먼저 모든 레이어의 참조 K/V를 캐시하는 참조 패스(kv_cache_mode="extract")를 실행한 후, 디노이징 패스(kv_cache_mode="cached")에서 생성 토큰과 캐시된 참조 토큰을 flex BlockMask를 통해 함께 어텐션합니다.
다음 코드 스니펫으로 모델을 로드할 수 있습니다.
from diffusers import WanAnimate2Transformer3DModel
transformer = WanAnimate2Transformer3DModel.from_pretrained("Wan-AI/Wan2.2-Animate-2-14B-Diffusers", subfolder="transformer", dtype=torch.bfloat16)WanAnimate2Transformer3DModel
class diffusers.WanAnimate2Transformer3DModel
< source >( patch_size: tuple = (1, 2, 2)text_len: int = 512in_dim: int = 36dim: int = 5120ffn_dim: int = 13824freq_dim: int = 256text_dim: int = 4096out_dim: int = 16num_heads: int = 40num_layers: int = 40cross_attn_norm: bool = Trueeps: float = 1e-06use_img_emb: bool = Truerefer_offset_t: int = 1refer_offset_h: int = 0refer_offset_w: int = -1refer_stride: int = 1 )
매개변수
- patch_size (tuple[int], 기본값 (1, 2, 2)) — 비디오 임베딩을 위한 3D 패치 차원 (t_patch, h_patch, w_patch).
- text_len (int, 기본값 512) — 텍스트 임베딩의 고정 길이입니다.
- in_dim (int, 기본값 36) — 입력의 채널 수 (마스크 채널을 위한 2 * latent_channels + 4).
- dim (int, 기본값 5120) — transformer의 채널 수입니다.
- ffn_dim (int, 기본값 13824) — 피드포워드 네트워크의 중간 차원입니다.
- freq_dim (int, 기본값 256) — 사인 파 시간 임베딩에 사용되는 차원입니다.
- text_dim (int, 기본값 4096) — 텍스트 임베딩의 입력 차원입니다.
- out_dim (int, 기본값 16) — 출력의 채널 수입니다.
- num_heads (int, 기본값 40) — Attention head의 수입니다.
- num_layers (int, 기본값 40) — 사용할 transformer 블록의 레이어 수입니다.
- cross_attn_norm (bool, 기본값 True) — 크로스 어텐션 정규화를 활성화합니다.
- eps (float, 기본값 1e-6) — 정규화 레이어에 사용되는 Epsilon 값입니다.
- use_img_emb (bool, 기본값 True) — CLIP 이미지 임베딩을 사용할지 여부.
- refer_offset_t (int, 기본값 1) — 참조(reference)의 시간(temporal) 차원에 대한 RoPE 오프셋입니다.
- refer_offset_h (int, 기본값 0) — 참조(reference)의 높이 차원에 대한 RoPE 오프셋입니다.
- refer_offset_w (int, 기본값 -1) — 참조 이미지의 가로 차원에 대한 RoPE 오프셋입니다. -1은 생성 그리드 크기를 사용함을 의미합니다.
- refer_stride (int, 기본값 1) — 참조(reference)에 RoPE를 적용할 때 사용할 스트라이드입니다.
Wan-Animate-2 모델에서 사용되는 비디오 유사 데이터용 Transformer 모델입니다.
Wan-Animate-2는 KV 캐시를 사용하는 인-컨텍스트 어텐션 메커니즘을 사용합니다. 먼저 참조 비디오를 인코딩(kv_cache_mode="extract")하여 [WanAnimate2KVCache]를 채운 후, 각 디노이징 단계(kv_cache_mode="cached")에서 생성 토큰과 캐시된 참조 K/V에 대해 flex BlockMask를 통해 함께 어텐션을 수행합니다. 따라서 생성 셀프-어텐션은 flex 어텐션 백엔드에서만 실행되며, 모델의 나머지 모든 어텐션은 어떤 백엔드에서도 작동합니다.
forward
< source >( hidden_states: list[torch.Tensor]timestep: Tensorencoder_hidden_states: list[torch.Tensor]condition_latents: list[torch.Tensor]kv_cache: WanAnimate2KVCachekv_cache_mode: strseq_len: intencoder_hidden_states_image: typing.Optional[torch.Tensor] = Noneoffset_grid_sizes: typing.Optional[torch.Tensor] = Nonereference_grid_sizes: typing.Optional[torch.Tensor] = Noneorigin_len: int | None = Noneorigin_area: list[int] | None = Noneis_uncondtion: bool = Falsereturn_dict: bool = True ) → Transformer2DModelOutput or tuple(list[torch.Tensor])
매개변수
- hidden_states (
list[torch.Tensor]) — 이 패스의 Latents —kv_cache_mode="extract"인 경우 참조 latents,kv_cache_mode="cached"인 경우 노이즈 생성 latents. - timestep (
torch.Tensor) — Denoising timestep입니다.kv_cache_mode="extract"에서는 무시되며, 이 모드에서는 고정 timestep 1을 사용합니다. - encoder_hidden_states (
list[torch.Tensor]) — 이 패스에 대한 텍스트 임베딩. - condition_latents (
list[torch.Tensor]) — 패치 임베딩 전에hidden_states에 연결되는 조건부 잠재 변수입니다. - kv_cache (
WanAnimate2KVCache) —kv_cache_mode="extract"아래에서 작성되고"cached"아래에서 읽힙니다. - kv_cache_mode (
str) —"extract"는 reference pass를 실행하여kv_cache를 채웁니다."cached"는 캐시된 reference token에 대해 denoising step을 실행합니다. - seq_len (
int) — 패치 임베딩 이후 각 샘플이 가져야 하는 토큰 수. - encoder_hidden_states_image (
torch.Tensor, 선택 사항) — 모델이use_img_emb로 구성된 경우 사용되는 CLIP 이미지 임베딩입니다. - offset_grid_sizes (
torch.Tensor, 선택 사항) — 참조 latents의 patch grid으로, -1로 설정된refer_offset_*값을 해석하는 데 사용됩니다.kv_cache_mode="extract"인 경우 필수이며,"cached"인 경우reference_grid_sizes가 동일한 grid를 설명하므로 대신 사용됩니다. - reference_grid_sizes (
torch.Tensor, 선택 사항) — 참조 latent의 패치 그리드로, 참조 rotary embeddings에 사용됩니다.kv_cache_mode="cached"인 경우 필수입니다. - origin_len (
int, 선택 사항) — 인컨텍스트 블록 마스크가 구축되는 전체 비디오의 프레임 수입니다.kv_cache_mode="cached"인 경우 필수입니다. - origin_area (
list[int], 선택 사항) — 인컨텍스트 블록 마스크가 구축되는 전체 비디오의 공간 크기[height, width]입니다.kv_cache_mode="cached"인 경우 필수입니다. - is_uncondtion (
bool, 선택 사항) — classifier-free guidance의 unconditional branch인지 여부입니다. - return_dict (
bool, 선택 사항, 기본값True) — 일반 튜플 대신~models.transformer_2d.Transformer2DModelOutput를 반환할지 여부.
반환값
Transformer2DModelOutput 또는 tuple(list[torch.Tensor])
return_dict가 False인 경우, 패치화되지 않은 각 입력 잠재 변수당 예측 샘플.
Transformer2DModelOutput
클래스 diffusers.models.modeling_outputs.Transformer2DModelOutput
< source >( sample: torch.Tensor )
매개변수
- sample (
torch.Tensor, shape(batch_size, num_channels, height, width)또는 Transformer2DModel이 discrete인 경우(batch size, num_vector_embeds - 1, num_latent_pixels)) —encoder_hidden_states입력에 조건부인 hidden states 출력입니다. discrete인 경우, 노이즈가 제거된 latent 픽셀에 대한 확률 분포를 반환합니다.
Transformer2DModel의 출력입니다.