Motif-Video

Báo cáo kỹ thuật

Motif-Video là một diffusion transformer có 2B tham số, được thiết kế cho việc tạo video từ văn bản và tạo video từ hình ảnh. Nó có kiến trúc ba giai đoạn với 12 lớp dual-stream + 16 lớp single-stream + 8 lớp DDT decoder, Shared Cross-Attention để đảm bảo sự căn chỉnh ổn định giữa văn bản và video trong các chuỗi video dài, text encoder T5Gemma2, và rectified flow matching để dự đoán vận tốc.

Motif-Video architecture

Tạo video từ văn bản

Sử dụng MotifVideoPipeline để tạo video từ văn bản:

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)

Tạo video từ ảnh

Sử dụng MotifVideoImage2VideoPipeline để tạo video từ ảnh:

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)

Suy luận tiết kiệm bộ nhớ

Đối với GPU có VRAM dưới 30GB (ví dụ: RTX 4090), hãy sử dụng model CPU offloading:

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

lớp diffusers.MotifVideoPipeline

< source >

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

Tham số

transformer (MotifVideoTransformer3DModel) — Kiến trúc Transformer có điều kiện để khử nhiễu các latents video đã mã hóa.
scheduler (SchedulerMixin) — Một scheduler được sử dụng kết hợp với transformer để khử nhiễu các video latents đã được mã hóa. Phải là một thực thể của một lớp kế thừa từ SchedulerMixin, chẳng hạn như DPMSolverMultistepScheduler. Nếu không được cung cấp, sẽ sử dụng scheduler gắn với mô hình được huấn luyện trước.
vae (AutoencoderKLWan) — Mô hình Variational Auto-Encoder (VAE) để mã hóa và giải mã video từ và sang các biểu diễn ẩn (latent representations).
text_encoder (T5Gemma2Encoder) — Bộ mã hóa văn bản chính để mã hóa các prompt văn bản thành các embedding.
tokenizer (PreTrainedTokenizerBase) — Tokenizer tương ứng với bộ mã hóa văn bản chính.
guider (BaseGuidance) — Phương pháp guidance cần sử dụng. Phải là một instance của một class kế thừa từ BaseGuidance, chẳng hạn như ClassifierFreeGuidance, AdaptiveProjectedGuidance hoặc SkipLayerGuidance. Nếu không được cung cấp, mặc định là ClassifierFreeGuidance.

Pipeline để tạo video từ văn bản sử dụng Motif-Video.

Mô hình này kế thừa từ DiffusionPipeline. Xem tài liệu của lớp cha để biết các phương thức chung được triển khai cho tất cả các pipeline (tải xuống, lưu, chạy trên một thiết bị cụ thể, v.v.).

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

Tham số

prompt (str hoặc List[str], tùy chọn) — Prompt hoặc các prompt để định hướng việc tạo video. Nếu không được định nghĩa, bạn phải truyền prompt_embeds.
negative_prompt (str hoặc List[str], tùy chọn) — Prompt hoặc các prompt không dùng để định hướng việc tạo video. Nếu không được định nghĩa, cần truyền negative_prompt_embeds thay thế. Bỏ qua khi không sử dụng guidance.
height (int, mặc định là 736) — Chiều cao của video được tạo ra, tính bằng pixel.
width (int, mặc định là 1280) — Chiều rộng của video được tạo ra, tính bằng pixel.
num_frames (int, mặc định là 121) — Số lượng khung hình video cần tạo.
num_inference_steps (int, tùy chọn, mặc định là 50) — Số bước khử nhiễu. Số bước khử nhiễu nhiều hơn thường dẫn đến video có chất lượng cao hơn, với cái giá là suy luận chậm hơn.
timesteps (List[int], tùy chọn) — Các bước thời gian tùy chỉnh để sử dụng cho quá trình khử nhiễu.
num_videos_per_prompt (int, tùy chọn, mặc định là 1) — Số lượng video cần tạo cho mỗi prompt.
generator (torch.Generator hoặc List[torch.Generator], tùy chọn) — Đối tượng PyTorch Generator để tạo ra kết quả xác định.
latents (torch.Tensor, tùy chọn) — Các latents nhiễu đã được tạo trước.
prompt_embeds (torch.Tensor, tùy chọn) — Các vector nhúng văn bản đã được tạo trước.
prompt_attention_mask (torch.Tensor, tùy chọn) — Mặt nạ chú ý (attention mask) được tạo trước cho các vector nhúng văn bản.
negative_prompt_embeds (torch.FloatTensor, tùy chọn) — Các embedding văn bản âm đã được tạo trước.
negative_prompt_attention_mask (torch.FloatTensor, tùy chọn) — Mặt nạ chú ý (attention mask) được tạo trước cho các vector nhúng văn bản âm (negative text embeddings).
output_type (str, tùy chọn, mặc định là "pil") — Định dạng đầu ra của video được tạo. Chọn giữa "pil", "np" hoặc "latent".
return_dict (bool, tùy chọn, mặc định là True) — Có nên trả về một ~MotifVideoPipelineOutput thay vì một tuple thông thường hay không.
attention_kwargs (dict, tùy chọn) — Các đối số được truyền cho bộ xử lý chú ý.
callback_on_step_end (Callable, tùy chọn) — Một hàm hoặc lớp con của PipelineCallback hoặc MultiPipelineCallbacks được gọi vào cuối mỗi bước khử nhiễu.
callback_on_step_end_tensor_inputs (List, tùy chọn) — Danh sách các đầu vào tensor cho hàm callback_on_step_end.
max_sequence_length (int, mặc định là 512) — Chiều dài tối đa của chuỗi cho tokenizer.
vae_batch_size (int, tùy chọn) — Kích thước batch cho việc giải mã VAE. Nếu được cung cấp và kích thước batch của latents lớn hơn, quá trình giải mã VAE sẽ được thực hiện theo từng phần.

Trả về

~MotifVideoPipelineOutput hoặc tuple

Nếu return_dict là True, ~MotifVideoPipelineOutput sẽ được trả về, ngược lại một tuple sẽ được trả về, trong đó phần tử đầu tiên là một danh sách các khung hình video đã được tạo.

Hàm gọi call của pipeline để tạo video từ văn bản.

Ví dụ:

>>> 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]

Tham số

prompt (str hoặc List[str], tùy chọn) — Prompt hoặc các prompt cần được mã hóa.
negative_prompt (str hoặc List[str], tùy chọn) — Prompt hoặc các prompt không dùng để định hướng việc tạo ảnh. Nếu không được định nghĩa, cần truyền negative_prompt_embeds thay thế. Bỏ qua khi không sử dụng guidance (tức là bị bỏ qua nếu guidance_scale nhỏ hơn 1).
num_videos_per_prompt (int, tùy chọn, mặc định là 1) — Số lượng video cần tạo cho mỗi prompt.
prompt_embeds (torch.Tensor, tùy chọn) — Các vector nhúng văn bản đã được tạo trước.
negative_prompt_embeds (torch.Tensor, tùy chọn) — Các embedding văn bản âm đã được tạo trước. Có thể dùng để dễ dàng điều chỉnh đầu vào văn bản, vd. trọng số prompt. Nếu không được cung cấp, negative_prompt_embeds sẽ được tạo từ đối số đầu vào negative_prompt.
prompt_attention_mask (torch.Tensor, tùy chọn) — Mặt nạ chú ý (attention mask) được tạo trước cho các vector nhúng văn bản.
negative_prompt_attention_mask (torch.Tensor, tùy chọn) — Mặt nạ chú ý (attention mask) được tạo sẵn cho các vector nhúng văn bản âm (negative text embeddings).
max_sequence_length (int, mặc định là 512) — Chiều dài tối đa của chuỗi cho tokenizer.
device (torch.device, tùy chọn) — Thiết bị để đặt các tensor lên.
dtype (torch.dtype, tùy chọn) — Kiểu dữ liệu cho các tensor.

Trả về

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

Một tuple chứa:

prompt_embeds: Các vector nhúng văn bản cho prompt tích cực
negative_prompt_embeds: Các vector nhúng văn bản cho prompt tiêu cực (None nếu không sử dụng guidance)
prompt_attention_mask: Mặt nạ chú ý (attention mask) cho prompt tích cực
negative_prompt_attention_mask: Mặt nạ chú ý cho prompt âm (None nếu không sử dụng guidance)

Mã hóa prompt thành các trạng thái ẩn của text encoder.

MotifVideoImage2VideoPipeline

lớp diffusers.MotifVideoImage2VideoPipeline

< source >

Tham số

transformer (MotifVideoTransformer3DModel) — Kiến trúc Transformer có điều kiện để khử nhiễu các latents video đã mã hóa.
scheduler (SchedulerMixin) — Một scheduler được sử dụng kết hợp với transformer để khử nhiễu các video latents đã được mã hóa. Phải là một thực thể của một lớp kế thừa từ SchedulerMixin, chẳng hạn như DPMSolverMultistepScheduler. Nếu không được cung cấp, sẽ sử dụng scheduler gắn với mô hình được huấn luyện trước.
vae (AutoencoderKLWan) — Mô hình Variational Auto-Encoder (VAE) để mã hóa và giải mã video từ và sang các biểu diễn ẩn (latent representations).
text_encoder (T5Gemma2Encoder) — Bộ mã hóa văn bản chính để mã hóa các prompt văn bản thành các embedding.
tokenizer (PreTrainedTokenizerBase) — Tokenizer tương ứng với bộ mã hóa văn bản chính.
feature_extractor (SiglipImageProcessor) — Bộ xử lý ảnh cho bộ mã hóa thị giác SigLIP.
guider (BaseGuidance) — Phương pháp guidance cần sử dụng. Phải là một instance của một class kế thừa từ BaseGuidance, chẳng hạn như ClassifierFreeGuidance, AdaptiveProjectedGuidance hoặc SkipLayerGuidance. Nếu không được cung cấp, mặc định là ClassifierFreeGuidance.

Pipeline để tạo video từ hình ảnh sử dụng Motif-Video với điều kiện khung hình đầu tiên.

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

Tham số

image (PipelineImageInput) — Hình ảnh đầu vào được sử dụng làm khung hình đầu tiên cho việc tạo video.
prompt (str hoặc List[str]) — Prompt hoặc các prompt để định hướng việc tạo video.
negative_prompt (str hoặc List[str], tùy chọn) — Prompt hoặc các prompt không dùng để định hướng việc tạo video.
height (int, mặc định là 736) — Chiều cao của video được tạo ra, tính bằng pixel.
width (int, mặc định là 1280) — Chiều rộng của video được tạo ra, tính bằng pixel.
num_frames (int, mặc định là 121) — Số lượng khung hình video cần tạo.
num_inference_steps (int, tùy chọn, mặc định là 50) — Số bước khử nhiễu.
timesteps (List[int], tùy chọn) — Các bước thời gian tùy chỉnh để sử dụng cho quá trình khử nhiễu.
num_videos_per_prompt (int, tùy chọn, mặc định là 1) — Số lượng video cần tạo cho mỗi prompt.
generator (torch.Generator hoặc List[torch.Generator], tùy chọn) — Đối tượng PyTorch Generator để tạo ra kết quả xác định.
latents (torch.Tensor, tùy chọn) — Các latents nhiễu đã được tạo trước.
prompt_embeds (torch.Tensor, tùy chọn) — Các vector nhúng văn bản đã được tạo trước.
prompt_attention_mask (torch.Tensor, tùy chọn) — Mặt nạ chú ý (attention mask) được tạo trước cho các vector nhúng văn bản.
negative_prompt_embeds (torch.FloatTensor, tùy chọn) — Các embedding văn bản âm đã được tạo trước.
negative_prompt_attention_mask (torch.FloatTensor, tùy chọn) — Mặt nạ chú ý (attention mask) được tạo trước cho các vector nhúng văn bản âm (negative text embeddings).
output_type (str, tùy chọn, mặc định là "pil") — Định dạng đầu ra của video được tạo.
return_dict (bool, tùy chọn, mặc định là True) — Có nên trả về một ~MotifVideoPipelineOutput thay vì một tuple thông thường hay không.
attention_kwargs (dict, tùy chọn) — Các đối số được truyền cho bộ xử lý chú ý.
callback_on_step_end (Callable, tùy chọn) — Một hàm hoặc lớp con của PipelineCallback được gọi vào cuối mỗi bước khử nhiễu.
callback_on_step_end_tensor_inputs (List, tùy chọn) — Danh sách các đầu vào tensor cho hàm callback_on_step_end.
max_sequence_length (int, mặc định là 512) — Chiều dài tối đa của chuỗi cho tokenizer.

Trả về

~MotifVideoPipelineOutput hoặc tuple

Hàm gọi của pipeline để tạo video từ ảnh.

Ví dụ:

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

Tham số

prompt (str hoặc List[str], tùy chọn) — Prompt hoặc các prompt cần được mã hóa.
negative_prompt (str hoặc List[str], tùy chọn) — Prompt hoặc các prompt không dùng để định hướng việc tạo ảnh. Nếu không được định nghĩa, cần truyền negative_prompt_embeds thay thế. Bỏ qua khi không sử dụng guidance (tức là bị bỏ qua nếu guidance_scale nhỏ hơn 1).
num_videos_per_prompt (int, tùy chọn, mặc định là 1) — Số lượng video cần tạo cho mỗi prompt.
prompt_embeds (torch.Tensor, tùy chọn) — Các vector nhúng văn bản đã được tạo trước.
negative_prompt_embeds (torch.Tensor, tùy chọn) — Các embedding văn bản âm đã được tạo trước. Có thể dùng để dễ dàng điều chỉnh đầu vào văn bản, vd. trọng số prompt. Nếu không được cung cấp, negative_prompt_embeds sẽ được tạo từ đối số đầu vào negative_prompt.
prompt_attention_mask (torch.Tensor, tùy chọn) — Mặt nạ chú ý (attention mask) được tạo trước cho các vector nhúng văn bản.
negative_prompt_attention_mask (torch.Tensor, tùy chọn) — Mặt nạ chú ý (attention mask) được tạo sẵn cho các vector nhúng văn bản âm (negative text embeddings).
max_sequence_length (int, mặc định là 512) — Chiều dài tối đa của chuỗi cho tokenizer.
device (torch.device, tùy chọn) — Thiết bị để đặt các tensor lên.
dtype (torch.dtype, tùy chọn) — Kiểu dữ liệu cho các tensor.

Trả về

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

Một tuple chứa:

prompt_embeds: Các vector nhúng văn bản cho prompt tích cực
negative_prompt_embeds: Các vector nhúng văn bản cho prompt tiêu cực (None nếu không sử dụng guidance)
prompt_attention_mask: Mặt nạ chú ý (attention mask) cho prompt tích cực
negative_prompt_attention_mask: Mặt nạ chú ý cho prompt âm (None nếu không sử dụng guidance)

Mã hóa prompt thành các trạng thái ẩn của text encoder.

MotifVideoPipelineOutput

lớp diffusers.MotifVideoPipelineOutput

< source >

( frames: Tensor )

Tham số

frames (torch.Tensor, np.ndarray, hoặc List[List[PIL.Image.Image]]) — Danh sách các đầu ra video - Có thể là một danh sách lồng nhau có độ dài batch_size, trong đó mỗi danh sách con chứa các chuỗi hình ảnh PIL đã khử nhiễu có độ dài num_frames. Nó cũng có thể là một mảng NumPy hoặc tensor Torch có hình dạng (batch_size, num_frames, channels, height, width).

Lớp đầu ra cho các pipeline Motif-Video.

Update on GitHub

Diffusers

Motif-Video

Tạo video từ văn bản

Tạo video từ ảnh

Suy luận tiết kiệm bộ nhớ

MotifVideoPipeline

lớp diffusers.MotifVideoPipeline

__call__

encode_prompt

MotifVideoImage2VideoPipeline

lớp diffusers.MotifVideoImage2VideoPipeline

__call__

encode_prompt

MotifVideoPipelineOutput

lớp diffusers.MotifVideoPipelineOutput

call

call