#
# 根据 Apache 许可证 2.0 版本（“许可证”）授权
# 您只能在遵守许可证的情况下使用本文件。
# 您可以在以下位置获取许可证副本
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# 除非适用法律要求或双方书面同意，软件
# 根据许可证分发，本软件按“原样”
# 不附带任何明示或暗示的保证或条件。
# 请参阅许可证中关于权限的具体语言
# 许可证下的限制。-->

# Wan-Animate-2

[Wan-Animate-2](https://github.com/Wan-Video/Wan2.2) 由阿里巴巴 Wan 团队开发，能够利用驱动视频中的动作来为参考角色图像生成动画。驱动视频会被处理为固定长度的片段：每个片段都会执行一次参考提取过程，将驱动片段的 K/V 缓存在每个 transformer 层中，并基于该缓存进行去噪；由于下一个片段依赖于前一个片段的解码尾部帧，因此解码操作在循环内部完成。

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

```python
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` 参数：引导由流水线的 guider 组件负责（基础预设使用 3.0 的无分类器引导，蒸馏预设则禁用引导）。

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

## WanAnimate2ModularPipeline[[diffusers.WanAnimate2ModularPipeline]]

#### diffusers.WanAnimate2ModularPipeline[[diffusers.WanAnimate2ModularPipeline]]

```python
diffusers.WanAnimate2ModularPipeline(blocks: diffusers.modular_pipelines.modular_pipeline.ModularPipelineBlocks | None = None, pretrained_model_name_or_path: str | os.PathLike | None = None, components_manager: diffusers.modular_pipelines.components_manager.ComponentsManager | None = None, collection: str | None = None, workflow: str | None = None, modular_config_dict: dict[str, typing.Any] | None = None, config_dict: dict[str, typing.Any] | None = None, **kwargs)
```

[源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/modular_pipelines/wan_animate_2/modular_pipeline.py#L23)

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

## WanAnimate2DistilledModularPipeline[[diffusers.WanAnimate2DistilledModularPipeline]]

#### diffusers.WanAnimate2DistilledModularPipeline[[diffusers.WanAnimate2DistilledModularPipeline]]

```python
diffusers.WanAnimate2DistilledModularPipeline(blocks: diffusers.modular_pipelines.modular_pipeline.ModularPipelineBlocks | None = None, pretrained_model_name_or_path: str | os.PathLike | None = None, components_manager: diffusers.modular_pipelines.components_manager.ComponentsManager | None = None, collection: str | None = None, workflow: str | None = None, modular_config_dict: dict[str, typing.Any] | None = None, config_dict: dict[str, typing.Any] | None = None, **kwargs)
```

[源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/modular_pipelines/wan_animate_2/modular_pipeline.py#L62)

用于蒸馏版 Wan-Animate-2 模型的 ModularPipeline，可在无需 classifier-free guidance 的情况下通过少量步骤完成采样。

## WanAnimate2Blocks[[diffusers.WanAnimate2Blocks]]

#### diffusers.WanAnimate2Blocks[[diffusers.WanAnimate2Blocks]]

```python
diffusers.WanAnimate2Blocks()
```

[源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/modular_pipelines/wan_animate_2/modular_blocks_wan_animate_2.py#L252)

用于 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`)

Inputs: 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`, *可选*): 去噪器的条件模型输入：例如 prompt_embeds、negative_prompt_embeds 等。 output_type (`str`, *可选*, 默认值为 np): 解码后视频的输出类型

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

## WanAnimate2DistilledBlocks[[diffusers.WanAnimate2DistilledBlocks]]

#### diffusers.WanAnimate2DistilledBlocks[[diffusers.WanAnimate2DistilledBlocks]]

```python
diffusers.WanAnimate2DistilledBlocks()
```

[源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/modular_pipelines/wan_animate_2/modular_blocks_wan_animate_2_distilled.py#L254)

用于蒸馏版 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`)

Inputs: 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`, *可选*): 去噪器的条件模型输入：例如 prompt_embeds、negative_prompt_embeds 等。 output_type (`str`, *可选*, 默认值为 np): 解码后视频的输出类型

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