Diffusers documentation
Wan-Animate-2
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
< source >( 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
< source >( 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
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
用于蒸馏版 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)：
生成的视频。