Motif-Video

기술 보고서

Motif-Video는 텍스트-비디오 및 이미지-비디오 생성을 위해 설계된 2B 파라미터의 diffusion transformer입니다. 12개의 dual-stream + 16개의 single-stream + 8개의 DDT decoder 레이어로 구성된 3단계 아키텍처, 긴 비디오 시퀀스에서 안정적인 텍스트-비디오 정렬을 위한 Shared Cross-Attention, T5Gemma2 텍스트 인코더, 그리고 속도 예측을 위한 rectified flow matching을 특징으로 합니다.

Motif-Video architecture

텍스트-투-비디오 생성

텍스트에서 비디오로 생성하는 데 MotifVideoPipeline을 사용하세요:

import torch
from diffusers import MotifVideoPipeline
from diffusers.utils import export_to_video


pipe = MotifVideoPipeline.from_pretrained(
    "Motif-Technologies/Motif-Video-2B",
    dtype=torch.bfloat16,
)
pipe.to("cuda")  # or "mps", "xpu", "cpu"

prompt = "A woman with long brown hair and light skin smiles at another woman with long blonde hair."
negative_prompt = "worst quality, inconsistent motion, blurry, jittery, distorted"

video = pipe(
    prompt=prompt,
    negative_prompt=negative_prompt,
    width=1280,
    height=736,
    num_frames=121,
    num_inference_steps=50,
).frames[0]
export_to_video(video, "output.mp4", fps=24)

이미지-비디오 생성

이미지에서 영상으로 생성하는 작업에는 MotifVideoImage2VideoPipeline를 사용하세요:

import torch
from diffusers import MotifVideoImage2VideoPipeline
from diffusers.utils import export_to_video, load_image


pipe = MotifVideoImage2VideoPipeline.from_pretrained(
    "Motif-Technologies/Motif-Video-2B",
    dtype=torch.bfloat16,
)
pipe.to("cuda")  # or "mps", "xpu", "cpu"

image = load_image("input_image.png")
prompt = "A cinematic scene with vivid colors."
negative_prompt = "worst quality, blurry, jittery, distorted"

video = pipe(
    image=image,
    prompt=prompt,
    negative_prompt=negative_prompt,
    width=1280,
    height=736,
    num_frames=121,
    num_inference_steps=50,
).frames[0]
export_to_video(video, "i2v_output.mp4", fps=24)

메모리 효율적 추론

VRAM이 30GB 미만인 GPU(예: RTX 4090)의 경우 모델 CPU 오프로딩을 사용하세요:

export PYTORCH_CUDA_ALLOC_CONF=expandable_segments:True

import torch
from diffusers import MotifVideoPipeline
from diffusers.utils import export_to_video


pipe = MotifVideoPipeline.from_pretrained(
    "Motif-Technologies/Motif-Video-2B",
    dtype=torch.bfloat16,
)
pipe.enable_model_cpu_offload()

prompt = "A woman with long brown hair and light skin smiles at another woman with long blonde hair."
negative_prompt = "worst quality, inconsistent motion, blurry, jittery, distorted"

video = pipe(
    prompt=prompt,
    negative_prompt=negative_prompt,
    width=1280,
    height=736,
    num_frames=121,
    num_inference_steps=50,
).frames[0]
export_to_video(video, "output.mp4", fps=24)

MotifVideoPipeline

클래스 diffusers.MotifVideoPipeline

< source >

( scheduler: SchedulerMixinvae: AutoencoderKLWantext_encoder: T5Gemma2Encodertokenizer: PreTrainedTokenizerBasetransformer: MotifVideoTransformer3DModelguider: BaseGuidancefeature_extractor: typing.Optional[transformers.models.siglip.image_processing_pil_siglip.SiglipImageProcessorPil] = None )

매개변수

transformer (MotifVideoTransformer3DModel) — 인코딩된 비디오 잠재 변수를 디노이즈하기 위한 조건부 Transformer 아키텍처.
scheduler (SchedulerMixin) — transformer와 함께 사용되어 인코딩된 비디오 latents의 노이즈를 제거하는 스케줄러입니다. SchedulerMixin을 상속하는 클래스의 인스턴스여야 하며, 예를 들어 DPMSolverMultistepScheduler가 해당됩니다. 제공되지 않으면 사전 학습된 모델에 연결된 스케줄러를 사용합니다.
vae (AutoencoderKLWan) — 잠재 표현으로 비디오를 인코딩 및 디코딩하는 Variational Auto-Encoder (VAE) 모델.
text_encoder (T5Gemma2Encoder) — 임베딩으로 텍스트 프롬프트를 인코딩하는 주요 텍스트 인코더입니다.
tokenizer (PreTrainedTokenizerBase) — 주요 텍스트 인코더에 해당하는 토크나이저.
guider (BaseGuidance) — 사용할 guidance 방법입니다. ClassifierFreeGuidance, AdaptiveProjectedGuidance, 또는 SkipLayerGuidance와 같이 BaseGuidance를 상속하는 클래스의 인스턴스여야 합니다. 제공되지 않으면 기본값으로 ClassifierFreeGuidance가 사용됩니다.

Motif-Video를 사용한 텍스트-비디오 생성을 위한 Pipeline

이 모델은 DiffusionPipeline에서 상속됩니다. 모든 파이프라인에 대해 구현된 일반적 메서드(다운로드, 저장, 특정 디바이스에서 실행 등)에 대해서는 상위 클래스 문서를 확인하세요.

call

< source >

( prompt: typing.Union[str, typing.List[str], NoneType] = Nonenegative_prompt: typing.Union[str, typing.List[str], NoneType] = Noneheight: int = 736width: int = 1280num_frames: int = 121num_inference_steps: int = 50timesteps: typing.Optional[typing.List[int]] = Nonenum_videos_per_prompt: typing.Optional[int] = 1generator: typing.Union[torch.Generator, typing.List[torch.Generator], NoneType] = Nonelatents: typing.Optional[torch.Tensor] = Noneprompt_embeds: typing.Optional[torch.Tensor] = Noneprompt_attention_mask: typing.Optional[torch.Tensor] = Nonenegative_prompt_embeds: typing.Optional[torch.Tensor] = Nonenegative_prompt_attention_mask: typing.Optional[torch.Tensor] = Noneoutput_type: typing.Optional[str] = 'pil'return_dict: bool = Trueattention_kwargs: typing.Optional[typing.Dict[str, typing.Any]] = Nonecallback_on_step_end: typing.Union[typing.Callable[[int, int, typing.Dict], NoneType], diffusers.callbacks.PipelineCallback, diffusers.callbacks.MultiPipelineCallbacks, NoneType] = Nonecallback_on_step_end_tensor_inputs: typing.List[str] = ['latents']max_sequence_length: int = 512vae_batch_size: int | None = None ) → ~MotifVideoPipelineOutput or tuple

매개변수

prompt (str 또는 List[str], 선택 사항) — 비디오 생성을 안내할 프롬프트입니다. 정의되지 않은 경우 prompt_embeds를 전달해야 합니다.
negative_prompt (str 또는 List[str], 선택 사항) — 비디오 생성을 안내하지 않을 프롬프트입니다. 정의되지 않은 경우, 대신 negative_prompt_embeds를 전달해야 합니다. 가이던스를 사용하지 않는 경우 무시됩니다.
height (int, 기본값 736) — 생성된 비디오의 픽셀 단위 높이입니다.
width (int, 기본값 1280) — 생성된 비디오의 픽셀 단위 너비입니다.
num_frames (int, 기본값 121) — 생성할 비디오 프레임 수입니다.
num_inference_steps (int, 선택 사항, 기본값 50) — 디노이징 단계의 수입니다. 디노이징 단계를 늘리면 일반적으로 더 높은 품질의 비디오를 얻을 수 있지만, 추론 속도가 느려집니다.
timesteps (List[int], 선택 사항) — 노이즈 제거 과정에 사용할 커스텀 timesteps입니다.
num_videos_per_prompt (int, 선택 사항, 기본값 1) — 프롬프트당 생성할 비디오의 수입니다.
generator (torch.Generator 또는 List[torch.Generator], 선택 사항) — 결정론적 생성을 위한 PyTorch Generator 객체입니다.
latents (torch.Tensor, 선택 사항) — 미리 생성된 노이즈가 포함된 latents.
prompt_embeds (torch.Tensor, 선택 사항) — 미리 생성된 텍스트 임베딩입니다.
prompt_attention_mask (torch.Tensor, 선택 사항) — 텍스트 임베딩을 위한 사전 생성된 어텐션 마스크입니다.
negative_prompt_embeds (torch.FloatTensor, 선택 사항) — 미리 생성된 부정 텍스트 임베딩입니다.
negative_prompt_attention_mask (torch.FloatTensor, 선택 사항) — 부정 텍스트 임베딩을 위한 사전 생성된 어텐션 마스크입니다.
output_type (str, 선택 사항, 기본값 "pil") — 생성된 비디오의 출력 형식입니다. "pil", "np", 또는 "latent" 중 하나를 선택합니다.
return_dict (bool, 선택 사항, 기본값 True) — 단순 튜플 대신 ~MotifVideoPipelineOutput를 반환할지 여부.
attention_kwargs (dict, 선택 사항) — attention processor에 전달되는 인자.
callback_on_step_end (Callable, 선택 사항) — 각 denoising 단계의 끝에서 호출되는 함수 또는 PipelineCallback 또는 MultiPipelineCallbacks의 하위 클래스.
callback_on_step_end_tensor_inputs (List, 선택 사항) — callback_on_step_end 함수의 텐서 입력 목록입니다.
max_sequence_length (int, 기본값 512) — 토크나이저의 최대 시퀀스 길이입니다.
vae_batch_size (int, 선택 사항) — VAE 디코딩에 사용할 배치 크기입니다. 이 값이 지정되어 있고 latents 배치 크기가 이 값보다 크면, VAE 디코딩은 청크 단위로 수행됩니다.

반환값

~MotifVideoPipelineOutput 또는 tuple

return_dict가 True인 경우 ~MotifVideoPipelineOutput가 반환되고, 그렇지 않으면 첫 번째 요소가 생성된 비디오 프레임 목록인 tuple이 반환됩니다.

텍스트-비디오 생성을 위한 pipeline의 호출 함수입니다.

예:

>>> import torch
>>> from diffusers import MotifVideoPipeline
>>> from diffusers.utils import export_to_video

>>> # Load the Motif-Video pipeline
>>> motif_video_model_id = "Motif-Technologies/Motif-Video-2B"
>>> pipe = MotifVideoPipeline.from_pretrained(motif_video_model_id, torch_dtype=torch.bfloat16)
>>> pipe.to("cuda")

>>> prompt = "A woman with long brown hair and light skin smiles at another woman with long blonde hair. The woman with brown hair wears a black jacket and has a small, barely noticeable mole on her right cheek. The camera angle is a close-up, focused on the woman with brown hair's face. The lighting is warm and natural, likely from the setting sun, casting a soft glow on the scene. The scene appears to be real-life footage"
>>> negative_prompt = "worst quality, inconsistent motion, blurry, jittery, distorted"

>>> video = pipe(
...     prompt=prompt,
...     negative_prompt=negative_prompt,
...     width=1280,
...     height=736,
...     num_frames=121,
...     num_inference_steps=50,
... ).frames[0]
>>> export_to_video(video, "output.mp4", fps=24)

encode_prompt

< source >

( prompt: typing.Union[str, typing.List[str]]negative_prompt: typing.Union[str, typing.List[str], NoneType] = Nonenum_videos_per_prompt: int = 1prompt_embeds: typing.Optional[torch.Tensor] = Nonenegative_prompt_embeds: typing.Optional[torch.Tensor] = Noneprompt_attention_mask: typing.Optional[torch.Tensor] = Nonenegative_prompt_attention_mask: typing.Optional[torch.Tensor] = Nonemax_sequence_length: int = 512device: typing.Optional[torch.device] = Nonedtype: typing.Optional[torch.dtype] = None ) → tuple[torch.Tensor, torch.Tensor, torch.Tensor, torch.Tensor]

매개변수

prompt (str 또는 List[str], 선택 사항) — 인코딩할 프롬프트입니다.
negative_prompt (str 또는 List[str], 선택 사항) — 이미지 생성을 안내하지 않을 프롬프트입니다. 정의되지 않은 경우 대신 negative_prompt_embeds를 전달해야 합니다. 가이던스를 사용하지 않을 때 무시됩니다(즉, guidance_scale이 1보다 작으면 무시됩니다).
num_videos_per_prompt (int, 선택 사항, 기본값 1) — 프롬프트당 생성할 비디오의 수.
prompt_embeds (torch.Tensor, 선택 사항) — 미리 생성된 텍스트 임베딩입니다.
negative_prompt_embeds (torch.Tensor, 선택 사항) — 미리 생성된 negative text embeddings입니다. 텍스트 입력을 쉽게 조정하는 데 사용할 수 있으며, 예를 들어 프롬프트 가중치 설정에 활용할 수 있습니다. 제공되지 않으면 negative_prompt 입력 인자로부터 negative_prompt_embeds가 생성됩니다.
prompt_attention_mask (torch.Tensor, 선택 사항) — 텍스트 임베딩을 위한 사전 생성된 어텐션 마스크입니다.
negative_prompt_attention_mask (torch.Tensor, 선택 사항) — 음성 텍스트 임베딩에 사용할 사전 생성된 어텐션 마스크입니다.
max_sequence_length (int, 기본값 512) — 토크나이저의 최대 시퀀스 길이입니다.
device (torch.device, 선택 사항) — 텐서를 배치할 장치.
dtype (torch.dtype, 선택 사항) — 텐서의 데이터 유형입니다.

반환값

tuple[torch.Tensor, torch.Tensor, torch.Tensor, torch.Tensor]

다음 항목을 포함하는 튜플:

prompt_embeds: 긍정 프롬프트의 텍스트 임베딩
negative_prompt_embeds: negative prompt에 대한 텍스트 임베딩(guidance를 사용하지 않는 경우 None)
prompt_attention_mask: 양의 프롬프트에 대한 어텐션 마스크
negative_prompt_attention_mask: negative prompt에 대한 attention mask (guidance를 사용하지 않는 경우 None)

프롬프트를 텍스트 인코더의 히든 상태로 인코딩합니다.

MotifVideoImage2VideoPipeline

class diffusers.MotifVideoImage2VideoPipeline

< source >

매개변수

transformer (MotifVideoTransformer3DModel) — 인코딩된 비디오 잠재 변수를 디노이즈하기 위한 조건부 Transformer 아키텍처.
scheduler (SchedulerMixin) — transformer와 함께 사용되어 인코딩된 비디오 latents의 노이즈를 제거하는 스케줄러입니다. SchedulerMixin을 상속하는 클래스의 인스턴스여야 하며, 예를 들어 DPMSolverMultistepScheduler가 해당됩니다. 제공되지 않으면 사전 학습된 모델에 연결된 스케줄러를 사용합니다.
vae (AutoencoderKLWan) — 잠재 표현으로 비디오를 인코딩 및 디코딩하는 Variational Auto-Encoder (VAE) 모델.
text_encoder (T5Gemma2Encoder) — 임베딩으로 텍스트 프롬프트를 인코딩하는 주요 텍스트 인코더입니다.
tokenizer (PreTrainedTokenizerBase) — 주요 텍스트 인코더에 해당하는 토크나이저.
feature_extractor (SiglipImageProcessor) — SigLIP 비전 인코더용 이미지 프로세서입니다.
guider (BaseGuidance) — 사용할 guidance 방법입니다. ClassifierFreeGuidance, AdaptiveProjectedGuidance, 또는 SkipLayerGuidance와 같이 BaseGuidance를 상속하는 클래스의 인스턴스여야 합니다. 제공되지 않으면 기본값으로 ClassifierFreeGuidance가 사용됩니다.

첫 프레임 조건부 Motif-Video를 사용한 이미지-비디오 생성을 위한 Pipeline

call

< source >

( image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]]prompt: typing.Union[str, typing.List[str]]negative_prompt: typing.Union[str, typing.List[str], NoneType] = Noneheight: int = 736width: int = 1280num_frames: int = 121num_inference_steps: int = 50timesteps: typing.Optional[typing.List[int]] = Nonenum_videos_per_prompt: typing.Optional[int] = 1generator: typing.Union[torch.Generator, typing.List[torch.Generator], NoneType] = Nonelatents: typing.Optional[torch.Tensor] = Noneprompt_embeds: typing.Optional[torch.Tensor] = Noneprompt_attention_mask: typing.Optional[torch.Tensor] = Nonenegative_prompt_embeds: typing.Optional[torch.Tensor] = Nonenegative_prompt_attention_mask: typing.Optional[torch.Tensor] = Noneoutput_type: typing.Optional[str] = 'pil'return_dict: bool = Trueattention_kwargs: typing.Optional[typing.Dict[str, typing.Any]] = Nonecallback_on_step_end: typing.Union[typing.Callable[[int, int, typing.Dict], NoneType], diffusers.callbacks.PipelineCallback, diffusers.callbacks.MultiPipelineCallbacks, NoneType] = Nonecallback_on_step_end_tensor_inputs: typing.List[str] = ['latents']max_sequence_length: int = 512 ) → ~MotifVideoPipelineOutput or tuple

매개변수

image (PipelineImageInput) — 비디오 생성의 첫 번째 프레임으로 사용할 입력 이미지.
prompt (str 또는 List[str]) — 비디오 생성을 안내하는 프롬프트입니다.
negative_prompt (str 또는 List[str], 선택 사항) — 비디오 생성을 안내하지 않을 프롬프트입니다.
height (int, 기본값 736) — 생성된 비디오의 픽셀 단위 높이입니다.
width (int, 기본값 1280) — 생성된 비디오의 픽셀 단위 너비입니다.
num_frames (int, 기본값 121) — 생성할 비디오 프레임 수입니다.
num_inference_steps (int, 선택 사항, 기본값 50) — 디노이징 단계 수입니다.
timesteps (List[int], 선택 사항) — 노이즈 제거 과정에 사용할 커스텀 timesteps입니다.
num_videos_per_prompt (int, 선택 사항, 기본값 1) — 프롬프트당 생성할 비디오의 수입니다.
generator (torch.Generator 또는 List[torch.Generator], 선택 사항) — 결정론적 생성을 위한 PyTorch Generator 객체입니다.
latents (torch.Tensor, 선택 사항) — 미리 생성된 노이즈가 포함된 latents.
prompt_embeds (torch.Tensor, 선택 사항) — 미리 생성된 텍스트 임베딩입니다.
prompt_attention_mask (torch.Tensor, 선택 사항) — 텍스트 임베딩을 위한 사전 생성된 어텐션 마스크입니다.
negative_prompt_embeds (torch.FloatTensor, 선택 사항) — 미리 생성된 부정 텍스트 임베딩입니다.
negative_prompt_attention_mask (torch.FloatTensor, 선택 사항) — 부정 텍스트 임베딩을 위한 사전 생성된 어텐션 마스크입니다.
output_type (str, 선택 사항, 기본값 "pil") — 생성된 비디오의 출력 형식입니다.
return_dict (bool, 선택 사항, 기본값 True) — 단순 튜플 대신 ~MotifVideoPipelineOutput를 반환할지 여부.
attention_kwargs (dict, 선택 사항) — attention processor에 전달되는 인자.
callback_on_step_end (Callable, 선택 사항) — 각 디노이징 단계의 끝에서 호출되는 함수 또는 PipelineCallback의 하위 클래스입니다.
callback_on_step_end_tensor_inputs (List, 선택 사항) — callback_on_step_end 함수의 텐서 입력 목록입니다.
max_sequence_length (int, 기본값 512) — 토크나이저의 최대 시퀀스 길이입니다.

반환값

~MotifVideoPipelineOutput 또는 tuple

return_dict가 True인 경우 ~MotifVideoPipelineOutput가 반환되고, 그렇지 않으면 첫 번째 요소가 생성된 비디오 프레임 목록인 tuple이 반환됩니다.

이미지-비디오 생성을 위한 pipeline의 호출 함수입니다.

예:

>>> import torch
>>> from PIL import Image
>>> from diffusers import MotifVideoImage2VideoPipeline
>>> from diffusers.utils import export_to_video, load_image

>>> # Load the Motif-Video image-to-video pipeline
>>> motif_video_model_id = "Motif-Technologies/Motif-Video-2B"
>>> pipe = MotifVideoImage2VideoPipeline.from_pretrained(motif_video_model_id, torch_dtype=torch.bfloat16)
>>> pipe.to("cuda")

>>> # Load an image
>>> image = load_image(
...     "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/astronaut.png"
... )

>>> prompt = "An astronaut is walking on the moon surface, kicking up dust with each step"
>>> negative_prompt = "worst quality, inconsistent motion, blurry, jittery, distorted"

>>> video = pipe(
...     image=image,
...     prompt=prompt,
...     negative_prompt=negative_prompt,
...     width=1280,
...     height=736,
...     num_frames=121,
...     num_inference_steps=50,
... ).frames[0]
>>> export_to_video(video, "output.mp4", fps=24)

encode_prompt

< source >

매개변수

prompt (str 또는 List[str], 선택 사항) — 인코딩할 프롬프트입니다.
negative_prompt (str 또는 List[str], 선택 사항) — 이미지 생성을 안내하지 않을 프롬프트입니다. 정의되지 않은 경우 대신 negative_prompt_embeds를 전달해야 합니다. 가이던스를 사용하지 않을 때 무시됩니다(즉, guidance_scale이 1보다 작으면 무시됩니다).
num_videos_per_prompt (int, 선택 사항, 기본값 1) — 프롬프트당 생성할 비디오의 수.
prompt_embeds (torch.Tensor, 선택 사항) — 미리 생성된 텍스트 임베딩입니다.
negative_prompt_embeds (torch.Tensor, 선택 사항) — 미리 생성된 negative text embeddings입니다. 텍스트 입력을 쉽게 조정하는 데 사용할 수 있으며, 예를 들어 프롬프트 가중치 설정에 활용할 수 있습니다. 제공되지 않으면 negative_prompt 입력 인자로부터 negative_prompt_embeds가 생성됩니다.
prompt_attention_mask (torch.Tensor, 선택 사항) — 텍스트 임베딩을 위한 사전 생성된 어텐션 마스크입니다.
negative_prompt_attention_mask (torch.Tensor, 선택 사항) — 음성 텍스트 임베딩에 사용할 사전 생성된 어텐션 마스크입니다.
max_sequence_length (int, 기본값 512) — 토크나이저의 최대 시퀀스 길이입니다.
device (torch.device, 선택 사항) — 텐서를 배치할 장치.
dtype (torch.dtype, 선택 사항) — 텐서의 데이터 유형입니다.

반환값

tuple[torch.Tensor, torch.Tensor, torch.Tensor, torch.Tensor]

다음 항목을 포함하는 튜플:

prompt_embeds: 긍정 프롬프트의 텍스트 임베딩
negative_prompt_embeds: negative prompt에 대한 텍스트 임베딩(guidance를 사용하지 않는 경우 None)
prompt_attention_mask: 양의 프롬프트에 대한 어텐션 마스크
negative_prompt_attention_mask: negative prompt에 대한 attention mask (guidance를 사용하지 않는 경우 None)

프롬프트를 텍스트 인코더의 히든 상태로 인코딩합니다.

MotifVideoPipelineOutput

클래스 diffusers.MotifVideoPipelineOutput

< source >

( frames: Tensor )

매개변수

frames (torch.Tensor, np.ndarray, 또는 List[List[PIL.Image.Image]]) — 비디오 출력 목록 - batch_size, 길이의 중첩 목록일 수 있으며, 각 하위 목록에는 num_frames. 길이의 노이즈 제거된 PIL 이미지 시퀀스가 포함됩니다. 또한 (batch_size, num_frames, channels, height, width) 형상의 NumPy 배열 또는 Torch 텐서일 수도 있습니다.

Motif-Video 파이프라인의 출력 클래스입니다.

Update on GitHub

Diffusers

Motif-Video

텍스트-투-비디오 생성

이미지-비디오 생성

메모리 효율적 추론

MotifVideoPipeline

클래스 diffusers.MotifVideoPipeline

__call__

encode_prompt

MotifVideoImage2VideoPipeline

class diffusers.MotifVideoImage2VideoPipeline

__call__

encode_prompt

MotifVideoPipelineOutput

클래스 diffusers.MotifVideoPipelineOutput

call

call