diffusers/main/ko/api/models/kandinsky6_transformer.md

Kandinsky 6 Transformers

Kandinsky 6은 텍스트/이미지에서 비디오 및 오디오를 생성하기 위해 비디오와 오디오 잠재를 함께 노이즈 제거하는 멀티모달 diffusion transformer와, 비디오 초해상도를 위한 텍스트 없는 diffusion transformer를 사용합니다.

Kandinsky6Transformer3DModel[[diffusers.Kandinsky6Transformer3DModel]]

Kandinsky6TI2VAPipeline에서 사용하는 멀티모달 트랜스포머입니다.

import torch
from diffusers import Kandinsky6Transformer3DModel

transformer = Kandinsky6Transformer3DModel.from_pretrained(
    "kandinskylab/Kandinsky-6.0-Pro-distill-5s-Diffusers", subfolder="transformer", torch_dtype=torch.bfloat16
)

diffusers.Kandinsky6Transformer3DModel[[diffusers.Kandinsky6Transformer3DModel]]

diffusers.Kandinsky6Transformer3DModel(in_visual_dim: int = 16, out_visual_dim: int = 16, in_text_dim: int = 3584, in_text_dim2: int = 768, time_dim: int = 1024, patch_size: tuple = (1, 2, 2), model_dim: int = 4096, ff_dim: int = 16384, num_text_blocks: int = 4, num_visual_blocks: int = 60, axes_dims: tuple = (32, 48, 48), visual_cond: bool = True, in_audio_dim: int = 20, out_audio_dim: int = 20, model_dim_a: int | None = None, time_dim_a: int | None = None, ff_dim_a: int | None = None, axes_dims_a: tuple | None = None, audio_freqs_scaling: float = 1.0, scale_factor: tuple | list[float] = (1.0, 2.0, 2.0), text_token_padding: bool = False, ca_rope: bool = False, cross_gates: bool = False, fix_modulation: bool = False, visual_token_type_num_embeddings: int = 0)

소스

매개변수:

in_visual_dim (int, optional, 기본값 16) : 입력 비디오 잠재 채널의 수.

out_visual_dim (int, optional, 기본값 16) : 출력 비디오 잠재 채널의 수.

in_text_dim (int, optional, 기본값 3584) : 텍스트 토큰 임베딩 차원.

in_text_dim2 (int, optional, 기본값 768) : 풀링된 텍스트 임베딩 차원.

time_dim (int, optional, 기본값 1024) : 시간 임베딩 차원.

patch_size (tuple[int, int, int], optional, 기본값 (1, 2, 2)) : 비디오 패치 크기.

model_dim (int, optional, 기본값 4096) : 비디오 transformer의 hidden dimension입니다.

ff_dim (int, optional, 기본값 16384) : 비디오 피드포워드 은닉 차원.

num_text_blocks (int, optional, 기본값 4) : 각 모달리티당 텍스트 블록의 수.

num_visual_blocks (int, optional, 기본값 60) : 병합된 비디오/오디오 블록의 수.

axes_dims (tuple[int, int, int], 선택 사항, 기본값 (32, 48, 48)) : 비디오용 RoPE 차원입니다.

visual_cond (bool, optional, 기본값 True) : 비디오 조건 채널이 존재하는지 여부.

in_audio_dim (int, optional, 기본값 20) : 입력 오디오 잠재 채널의 수.

out_audio_dim (int, optional, 기본값 20) : 출력 오디오 잠재 채널의 수.

model_dim_a (int, optional) : 오디오 transformer 은닉 차원. 기본값은 model_dim입니다.

time_dim_a (int, optional) : 오디오 시간 임베딩 차원. 기본값은 time_dim입니다.

ff_dim_a (int, optional) : 오디오 피드포워드 은닉 차원. 기본값은 ff_dim입니다.

axes_dims_a (tuple[int, int, int], optional) : 오디오 RoPE 차원. 기본값은 axes_dims입니다.

audio_freqs_scaling (float, optional, 기본값 1.0) : 오디오 RoPE 주파수 스케일링.

scale_factor (tuple[float, float, float], optional, 기본값 (1.0, 2.0, 2.0)) : 비디오 위치에 적용되는 축별 (t, h, w) RoPE 주파수 스케일링입니다.

text_token_padding (bool, optional, 기본값 False) : 참조 모델의 텍스트 시퀀스가 패딩되었는지 여부를 기록하는 체크포인트 메타데이터입니다. forward는 이 플래그와 관계없이 항상 선택적인 encoder_attention_mask를 받습니다. 실제로 전달되는지는 호출자에 따라 완전히 결정됩니다.

ca_rope (bool, optional, 기본값 False) : 크로스 모달 오디오 RoPE를 사용할지 여부.

cross_gates (bool, optional, 기본값 False) : 크로스 모달 잔차 게이트를 사용할지 여부.

fix_modulation (bool, optional, 기본값 False) : 고정 변조 변형을 사용할지 여부.

visual_token_type_num_embeddings (int, optional, 기본값 0) : 시각 토큰 타입 임베딩의 개수.

텍스트/이미지에서 비디오 및 오디오를 생성하는 Kandinsky 6 멀티모달 트랜스포머.

Video와 audio는 각자의 text branch(Qwen2.5-VL tokens + CLIP pooled embedding)에 조건부인 fused, cross-modal transformer blocks를 통해 함께 denoise됩니다. audio_hidden_states를 전달하지 않으면 fused block의 video self-attention, cross-attention, feed-forward 단계는 여전히 실행되지만 video만 denoise됩니다. Rotary embeddings은 forward 내부에서 token grid를 기반으로 계산됩니다.

공개된 체크포인트는 text_token_padding, ca_rope, cross_gates, fix_modulation을 True로 설정합니다(각 체크포인트의 transformer/config.json 참조). False 기본값은 이 저장소에서 가중치를 제공하지 않는 아키텍처 변형만 설명합니다.

forward[[diffusers.Kandinsky6Transformer3DModel.forward]]

forward(hidden_states: Tensor, encoder_hidden_states: Tensor, pooled_projections: Tensor, timestep: Tensor, audio_hidden_states: Tensor | None = None, visual_rope_pos: tuple[Tensor, Tensor, Tensor] | None = None, encoder_attention_mask: Tensor | None = None, visual_token_type_ids: Tensor | None = None, return_dict: bool = True)

소스

매개변수:

hidden_states (torch.Tensor, shape (batch_size, num_frames, height, width, in_channels)) : (B, T, H, W, C) 레이아웃의 비디오 latents입니다. visual_cond=True인 경우, in_channels는 2 * in_visual_dim + 1입니다: 노이즈 latent, conditioning latent, conditioning mask입니다.

encoder_hidden_states (torch.Tensor, shape (batch_size, sequence_length, in_text_dim)) : 비디오 및 오디오 텍스트 브랜치가 공유하는 텍스트 토큰 임베딩

pooled_projections (torch.Tensor, shape (batch_size, in_text_dim2)) : 두 가지 브랜치의 timestep embedding에 추가되는 풀링된 텍스트 임베딩.

timestep (torch.Tensor, shape (batch_size,)) : 두 모달리티가 공유하는 [0, num_train_timesteps] 스케일의 Diffusion timestep.

audio_hidden_states (torch.Tensor, shape (batch_size, audio_length, in_audio_dim), 선택 사항) : 오디오 잠재 변수(latents). 생략할 경우, 융합된 블록은 비디오 경로만 실행합니다.

visual_rope_pos (tuple[torch.Tensor, torch.Tensor, torch.Tensor], 선택 사항) : 패치화된 비디오 토큰의 축별 (t, h, w) 회전 위치 인덱스입니다. 기본값은 각 축에 대한 arange입니다. 파이프라인은 위치 0를 재사용하는 참조 프레임을 추가할 때 명시적인 시간 인덱스를 전달합니다.

encoder_attention_mask (torch.Tensor, shape (batch_size, sequence_length), 선택 사항) : encoder_hidden_states에 대한 Boolean 패딩 마스크입니다. 프롬프트가 패딩되지 않은 경우 None을(를) 전달하세요.

visual_token_type_ids (torch.Tensor, shape (batch_size, num_frames), 선택 사항) : 프레임별 토큰 타입 ID로, visual_token_type_embeddings를 통해 임베딩됩니다. visual_token_type_num_embeddings > 0이 필요합니다.

return_dict (bool, 기본값 True) : 일반 튜플 대신 Kandinsky6TransformerOutput를 반환할지 여부.

반환값: Kandinsky6TransformerOutput 또는 tuple

(B, T, H, W, out_visual_dim) 레이아웃의 예측된 비디오 속도 및 audio_hidden_states가 제공된 경우 (B, audio_length, out_audio_dim) 모양의 예측된 오디오 속도.

Kandinsky6SRTransformer3DModel[[diffusers.Kandinsky6SRTransformer3DModel]]

The text-free transformer used by Kandinsky6SRPipeline to refine one tile of the upscaled video at a time.

import torch
from diffusers import Kandinsky6SRTransformer3DModel

transformer = Kandinsky6SRTransformer3DModel.from_pretrained(
    "kandinskylab/Kandinsky-6.0-VSR-distilled2steps-5s-Diffusers", subfolder="transformer", torch_dtype=torch.bfloat16
)
# The transformer always runs NABLA sparse attention (`nabla_threshold`, 0.8 by default) on the `flex` backend.
# Compile it, otherwise flex falls back to an eager implementation that needs far more memory at video resolutions.
transformer.compile_repeated_blocks(fullgraph=True)

diffusers.Kandinsky6SRTransformer3DModel[[diffusers.Kandinsky6SRTransformer3DModel]]

diffusers.Kandinsky6SRTransformer3DModel(in_visual_dim: int = 64, out_visual_dim: int = 640, time_dim: int = 512, patch_size: tuple[int, int, int] = (1, 1, 1), model_dim: int = 1792, ff_dim: int = 7168, num_visual_blocks: int = 32, axes_dims: tuple[int, int, int] = (16, 24, 24), scale_factor: tuple[float, float, float] = (1.0, 2.0, 2.0), nabla_threshold: float = 0.8, nabla_window: tuple[int, int, int] = (11, 7, 7), tile_sizes: tuple[tuple[int, int], ...] = ((512, 512), (512, 768), (768, 512)))

소스

매개변수:

in_visual_dim (int, 기본값 64) : K-VAE의 잠재 채널 수.

out_visual_dim (int, 기본값 640) : 출력 채널 수.

time_dim (int, 기본값 512) : timestep 임베딩의 차원.

patch_size (tuple[int, int, int], 기본값 (1, 1, 1)) : (temporal, height, width) 형식의 패치 크기.

model_dim (int, 기본값 1792) : Transformer의 숨겨진 차원(hidden dimension)입니다.

ff_dim (int, 기본값 7168) : 피드포워드 네트워크의 내부 차원입니다.

num_visual_blocks (int, 기본값 32) : Transformer 블록의 수.

axes_dims (tuple[int, int, int], 기본값 (16, 24, 24)) : (t, h, w) 축별 RoPE 차원; 이들의 합은 어텐션 헤드 차원입니다.

scale_factor (tuple[float, float, float], 기본값 (1.0, 2.0, 2.0)) : 토큰 위치에 적용되는 축별 RoPE 주파수 스케일링입니다.

nabla_threshold (float, 기본값 0.8) : NABLA 블록 선택의 누적 어텐션 임계값.

nabla_window (tuple[int, int, int], 기본값 (11, 7, 7)) : 모든 8x8 토크 블록이 항상 주의를 기울이는 슬라이딩 타일 사전의 홀수 (t, h, w) 범위입니다.

tile_sizes (tuple[tuple[int, int], ...], 기본값은 ((512, 512), (512, 768), (768, 512))) : 모델이 학습된 비디오 타일의 픽셀 (height, width) 크기입니다. Kandinsky6SRPipeline는 입력 비디오의 종횡비와 가장 가까운 크기로 모든 타일을 정제합니다.

Kandinsky 6 비디오 초해상도를 위한 텍스트 없는 diffusion transformer.

모델은 K-VAE 잠재 공간 비디오의 타일을 노이즈 제거합니다. 입력은 노이즈 잠재 변수, 앵커 잠재 변수, 그리고 슈퍼 레졸루션을 조건부화하는 앵커 마스크를 연결하여 구성되며(2 * in_visual_dim + 1 채널), 출력은 out_visual_dim 채널을 가집니다: 일반 velocity 체크포인트의 경우 in_visual_dim, PiflowScheduler 증류 체크포인트의 경우 확장된 n_grid * in_visual_dim입니다. 비디오 셀프 어텐션은 flex 어텐션 백엔드에서 NABLA 희소 블록 패턴을 통해 실행되며, 이는 patch_size 적용 후 토큰 그리드(height 및 width)가 8로 나누어떨어져야 합니다.

forward[[diffusers.Kandinsky6SRTransformer3DModel.forward]]

forward(hidden_states: Tensor, timestep: Tensor, return_dict: bool = True)

소스

매개변수:

hidden_states (torch.Tensor, shape (batch_size, num_frames, height, width, 2 * in_visual_dim + 1)) : (B, T, H, W, C) 레이아웃의 Latent tiles: 채널 축을 따라 연결된 노이저드 latent, 앵커 latent, 앵커 마스크.

timestep (torch.Tensor, shape (batch_size,)) : [0, num_train_timesteps] 스케일의 Diffusion timestep입니다.

return_dict (bool, 기본값 True) : 일반 튜플 대신 Transformer2DModelOutput를 반환할지 여부.

반환값: Transformer2DModelOutput 또는 tuple

(batch_size, num_frames, height, width, out_visual_dim) 형태의 예측 결과.