Diffusers documentation

Wan-Animate-2

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v0.43.0).
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Wan-Animate-2

阿里巴巴 Wan 团队的 Wan-Animate-2 利用驱动视频的动作来为参考角色图像生成动画。驱动视频会被处理为固定长度的片段:每个片段都会执行一次参考提取流程,将驱动片段的 K/V 缓存在每个 transformer 层中,并基于该缓存进行去噪;由于下一个片段依赖于前一个片段的解码尾部帧,因此解码操作在循环内部进行。

提供两种预设:基础检查点使用无分类器引导进行采样,而蒸馏检查点则无需引导即可在少量步骤内完成采样(其引导器固定为 guidance_scale=1.0)。

import torch
from diffusers import ModularPipeline
from diffusers.utils import export_to_video, load_image, load_video

pipe = ModularPipeline.from_pretrained("Wan-AI/Wan2.2-Animate-2-14B-Diffusers")
pipe.load_components(dtype=torch.bfloat16)

# The transformer weights and the per-segment reference KV cache do not co-reside on one 80 GB
# card at the default resolution, so stream the transformer's blocks. Compiling the blocks is
# required as the in-context attention runs on the flex backend
pipe.transformer.enable_group_offload(
    onload_device=torch.device("cuda"),
    offload_device=torch.device("cpu"),
    offload_type="block_level",
    use_stream=True,
)
pipe.text_encoder.to("cuda")  # or "mps", "xpu", "cpu"
pipe.image_encoder.to("cuda")
pipe.vae.to("cuda")
pipe.transformer.compile_repeated_blocks(fullgraph=False)

# The first demo from the official repository: https://github.com/Wan-Video/Wan-Animate-2
demo = "https://raw.githubusercontent.com/Wan-Video/Wan-Animate-2/main/examples/demo1"
image = load_image(f"{demo}/reference.png")
driving_video, driving_video_fps = load_video(f"{demo}/template.mp4", return_fps=True)
prompt = "人物外观描述:一只银灰色虎斑纹的小猫,拥有圆润的脸庞、竖立的耳朵和巨大的圆形眼睛。它身穿一套深蓝色的制服套装,包括一件带有金色纽扣的西装外套和一条百褶裙。外套里面搭配着白色衬衫,领口处系着一个红色的蝴蝶结,袖口露出白色的衬衫边缘。背景描述:背景为纯白色,光线均匀明亮,无其他杂物或装饰。"

videos = pipe(
    image=image,
    driving_video=driving_video,
    driving_video_fps=driving_video_fps,
    prompt=prompt,
    output="videos",
)
export_to_video(videos[0], "output.mp4", fps=24)

对于蒸馏检查点,以相同方式加载 Wan-AI/Wan2.2-Animate-2-14B-Distilled-Diffusers 即可,其余部分无需更改。每个预设都带有各自的采样默认值(基础检查点为 40 步,蒸馏检查点为 10 步),并且任何地方都不存在 guidance_scale 参数:引导由 pipeline 的 guider 组件负责(基础预设使用 3.0 的无分类器引导,蒸馏预设则禁用引导)。

height 和 width(默认值为 800 和 640)用于设置生成视频的 目标区域;实际帧尺寸会保持参考图像的宽高比,驱动帧会被添加黑边以适配该尺寸。如果输入已经处于目标黑边尺寸,则会原样通过预处理,因此也可以完全在流水线外部完成预处理。

WanAnimate2ModularPipeline

类 diffusers.WanAnimate2ModularPipeline

< >

( blocks: diffusers.modular_pipelines.modular_pipeline.ModularPipelineBlocks | None = Nonepretrained_model_name_or_path: str | os.PathLike | None = Nonecomponents_manager: diffusers.modular_pipelines.components_manager.ComponentsManager | None = Nonecollection: str | None = Noneworkflow: str | None = Nonemodular_config_dict: dict[str, typing.Any] | None = Noneconfig_dict: dict[str, typing.Any] | None = None**kwargs )

用于 Wan-Animate-2 角色动画的 ModularPipeline。

WanAnimate2DistilledModularPipeline

类 diffusers.WanAnimate2DistilledModularPipeline

< >

( blocks: diffusers.modular_pipelines.modular_pipeline.ModularPipelineBlocks | None = Nonepretrained_model_name_or_path: str | os.PathLike | None = Nonecomponents_manager: diffusers.modular_pipelines.components_manager.ComponentsManager | None = Nonecollection: str | None = Noneworkflow: str | None = Nonemodular_config_dict: dict[str, typing.Any] | None = Noneconfig_dict: dict[str, typing.Any] | None = None**kwargs )

用于蒸馏版 Wan-Animate-2 模型的 ModularPipeline,可在无分类器自由引导的情况下以少量步长完成采样。

WanAnimate2Blocks

class diffusers.WanAnimate2Blocks

< >

( )

Wan-Animate-2 角色动画的模块化流水线组件:输入一张参考角色图像和一段驱动视频,即可生成角色跟随驱动动作的视频。

组件: text_encoder (UMT5EncoderModel) tokenizer (AutoTokenizer) image_processor (WanAnimate2VideoProcessor) image_encoder (CLIPVisionModel) video_processor (WanAnimate2VideoProcessor) vae (AutoencoderKLWan) transformer (WanAnimate2Transformer3DModel) scheduler (SchedulerMixin) guider (ClassifierFreeGuidance)

输入: prompt (str): 用于引导图像生成的提示词或提示词列表。 negative_prompt (str,可选): 用于排除的提示词或提示词列表,即不希望引导图像生成的内容。 prompt_ref (str,可选,默认为 人物动作的参考视频): 用于驱动视频上下文的参考提示词 max_sequence_length (int,可选,默认为 512): 提示词编码的最大序列长度。 image (Image | list): 包含待动画化角色的参考图像。 height (int,可选,默认为 800): 与 width 一起,指定生成视频的 面积;宽高比来自 image。 会被解析后的帧高度覆盖。 width (int,可选,默认为 640): 参见 height。会被解析后的帧宽度覆盖。 driving_video (list): 提供运动信息的驱动视频,格式可以是 VideoProcessor.preprocess_video 接受的任意格式。 driving_video_fps (float,可选): driving_video 的拍摄帧率 —— load_video(..., return_fps=True) 会报告该值。如果设置了此参数, 驱动帧将从该帧率重采样到 fps;如果为 None,则按原样使用。 fps (int,可选,默认为 24): 模型生成视频时的帧率 segment_frame_length (int,可选,默认为 81): 每个推理段中的帧数 prev_segment_conditioning_frames (int,可选,默认为 1): 从上一段携带过来的条件帧数量 generator (Generator,可选): 用于确定性生成的 Torch 生成器。 num_inference_steps (int,可选,默认为 40): 去噪步数。 *denoiser_input_fields (None,optional): 去噪器的条件模型输入:例如 prompt_embeds、negative_prompt_embeds 等。 output_type (str,optional*,默认为 np): 解码后视频的输出类型

输出: videos (list): 生成的视频。

WanAnimate2DistilledBlocks

class diffusers.WanAnimate2DistilledBlocks

< >

( )

用于蒸馏版 Wan-Animate-2 角色动画的模块化流水线模块,可在无需分类器自由引导的情况下,通过少量采样步骤完成生成。

组件: text_encoder (UMT5EncoderModel) tokenizer (AutoTokenizer) image_processor (WanAnimate2VideoProcessor) image_encoder (CLIPVisionModel) video_processor (WanAnimate2VideoProcessor) vae (AutoencoderKLWan) transformer (WanAnimate2Transformer3DModel) scheduler (SchedulerMixin) guider (ClassifierFreeGuidance)

输入: prompt (str): 用于引导图像生成的提示词或提示词列表。 negative_prompt (str,可选): 用于排除的提示词或提示词列表,即不希望引导图像生成的内容。 prompt_ref (str,可选,默认值为 人物动作的参考视频): 用于驱动视频上下文的参考提示词 max_sequence_length (int,可选,默认值为 512): 提示词编码的最大序列长度。 image (Image | list): 包含待动画化角色的参考图像。 height (int,可选,默认值为 800): 与 width 一起,指定生成视频的 面积;宽高比来自 image。 将被解析后的帧高度覆盖。 width (int,可选,默认值为 640): 参见 height。将被解析后的帧宽度覆盖。 driving_video (list): 提供运动信息的驱动视频,格式可以是 VideoProcessor.preprocess_video 接受的任意格式。 driving_video_fps (float,可选): driving_video 的拍摄帧率 —— load_video(..., return_fps=True) 会报告该值。如果已设置, 驱动帧将从该帧率重采样到 fps;如果为 None,则按原样使用。 fps (int,可选,默认值为 24): 模型生成视频时的帧率 segment_frame_length (int,可选,默认值为 81): 每个推理段中的帧数 prev_segment_conditioning_frames (int,可选,默认值为 1): 从上一段携带过来的条件帧数量 generator (Generator,可选): 用于确定性生成的 Torch 生成器。 num_inference_steps (int,可选,默认值为 10): 去噪步数。 *denoiser_input_fields (None,optional): 去噪器的条件模型输入:例如 prompt_embeds、negative_prompt_embeds 等。 output_type (str,optional*,默认值为 np): 解码后视频的输出类型

输出: videos (list): 生成的视频。

Update on GitHub