Wan

Wan Team 的 Wan-2.1。

本报告介绍了 Wan，这是一套全面且开源的视频基础模型系列，旨在推动视频生成的边界。Wan 基于主流的扩散 Transformer 范式，通过一系列创新实现了生成能力的显著提升，包括我们新颖的 VAE、可扩展的预训练策略、大规模数据筛选以及自动化评估指标。这些贡献共同提升了模型的性能和通用性。具体而言，Wan 具有以下四个关键特性：领先性能：Wan 的 14B 模型在包含数十亿图像和视频的庞大数据集上训练，展示了视频生成在数据规模和模型规模方面的扩展定律。它在多个内部和外部基准测试中持续超越现有的开源模型以及最先进的商业解决方案，展现出明确且显著的性能优势。全面性：Wan 提供了两个强大的模型，即 1.3B 和 14B 参数，分别侧重于效率和效果。它还涵盖了多种下游应用，包括图生视频、指令引导的视频编辑以及个性化视频生成，最多涵盖八项任务。消费级效率：1.3B 模型展现出卓越的资源效率，仅需 8.19 GB 显存，使其兼容广泛的消费级 GPU。开放性：我们开源了 Wan 的整个系列，包括源代码和所有模型，旨在促进视频生成社区的发展。这种开放性旨在显著扩展行业中视频制作的创意可能性，并为学术界提供高质量的视频基础模型。所有代码和模型均可在 this https URL 获取。

您可以在 Wan-AI 组织下找到所有原始的 Wan2.1 检查点。

Diffusers 支持以下 Wan 模型：

点击右侧边栏中的 Wan 模型，以查看更多视频生成示例。

文本到视频生成

下面的示例演示了如何生成针对内存或推理速度进行优化的文本到视频。

T2V 内存

T2V 推理速度

有关各种内存节省技术的详细信息，请参阅减少内存使用指南。

下方的 Wan2.1 文本生成视频模型需要约 13GB 的显存。

# pip install ftfy
import torch
import numpy as np
from diffusers import AutoModel, WanPipeline
from diffusers.quantizers import PipelineQuantizationConfig
from diffusers.hooks.group_offloading import apply_group_offloading
from diffusers.utils import export_to_video, load_image
from transformers import UMT5EncoderModel

text_encoder = UMT5EncoderModel.from_pretrained("Wan-AI/Wan2.1-T2V-14B-Diffusers", subfolder="text_encoder", dtype=torch.bfloat16)
vae = AutoModel.from_pretrained("Wan-AI/Wan2.1-T2V-14B-Diffusers", subfolder="vae", dtype=torch.float32)
transformer = AutoModel.from_pretrained("Wan-AI/Wan2.1-T2V-14B-Diffusers", subfolder="transformer", dtype=torch.bfloat16)

# group-offloading
onload_device = torch.device("cuda")
offload_device = torch.device("cpu")
apply_group_offloading(text_encoder,
    onload_device=onload_device,
    offload_device=offload_device,
    offload_type="block_level",
    num_blocks_per_group=4
)
transformer.enable_group_offload(
    onload_device=onload_device,
    offload_device=offload_device,
    offload_type="leaf_level",
    use_stream=True
)

pipeline = WanPipeline.from_pretrained(
    "Wan-AI/Wan2.1-T2V-14B-Diffusers",
    vae=vae,
    transformer=transformer,
    text_encoder=text_encoder,
    dtype=torch.bfloat16
)
pipeline.to("cuda")  # or "mps", "xpu", "cpu"

prompt = """
The camera rushes from far to near in a low-angle shot,
revealing a white ferret on a log. It plays, leaps into the water, and emerges, as the camera zooms in
for a close-up. Water splashes berry bushes nearby, while moss, snow, and leaves blanket the ground.
Birch trees and a light blue sky frame the scene, with ferns in the foreground. Side lighting casts dynamic
shadows and warm highlights. Medium composition, front view, low angle, with depth of field.
"""
negative_prompt = """
Bright tones, overexposed, static, blurred details, subtitles, style, works, paintings, images, static, overall gray, worst quality,
low quality, JPEG compression residue, ugly, incomplete, extra fingers, poorly drawn hands, poorly drawn faces, deformed, disfigured,
misshapen limbs, fused fingers, still picture, messy background, three legs, many people in the background, walking backwards
"""

output = pipeline(
    prompt=prompt,
    negative_prompt=negative_prompt,
    num_frames=81,
    guidance_scale=5.0,
).frames[0]
export_to_video(output, "output.mp4", fps=16)

编译在首次执行时较慢，但后续对 pipeline 的调用会更快。缓存也可以通过存储并复用中间输出来加速推理。

# pip install ftfy
import torch
import numpy as np
from diffusers import AutoModel, WanPipeline
from diffusers.hooks.group_offloading import apply_group_offloading
from diffusers.utils import export_to_video, load_image
from transformers import UMT5EncoderModel

text_encoder = UMT5EncoderModel.from_pretrained("Wan-AI/Wan2.1-T2V-14B-Diffusers", subfolder="text_encoder", dtype=torch.bfloat16)
vae = AutoModel.from_pretrained("Wan-AI/Wan2.1-T2V-14B-Diffusers", subfolder="vae", dtype=torch.float32)
transformer = AutoModel.from_pretrained("Wan-AI/Wan2.1-T2V-14B-Diffusers", subfolder="transformer", dtype=torch.bfloat16)

pipeline = WanPipeline.from_pretrained(
    "Wan-AI/Wan2.1-T2V-14B-Diffusers",
    vae=vae,
    transformer=transformer,
    text_encoder=text_encoder,
    dtype=torch.bfloat16
)
pipeline.to("cuda")  # or "mps", "xpu", "cpu"

# torch.compile
pipeline.transformer.to(memory_format=torch.channels_last)
pipeline.transformer = torch.compile(
    pipeline.transformer, mode="max-autotune", fullgraph=True
)

prompt = """
The camera rushes from far to near in a low-angle shot,
revealing a white ferret on a log. It plays, leaps into the water, and emerges, as the camera zooms in
for a close-up. Water splashes berry bushes nearby, while moss, snow, and leaves blanket the ground.
Birch trees and a light blue sky frame the scene, with ferns in the foreground. Side lighting casts dynamic
shadows and warm highlights. Medium composition, front view, low angle, with depth of field.
"""
negative_prompt = """
Bright tones, overexposed, static, blurred details, subtitles, style, works, paintings, images, static, overall gray, worst quality,
low quality, JPEG compression residue, ugly, incomplete, extra fingers, poorly drawn hands, poorly drawn faces, deformed, disfigured,
misshapen limbs, fused fingers, still picture, messy background, three legs, many people in the background, walking backwards
"""

output = pipeline(
    prompt=prompt,
    negative_prompt=negative_prompt,
    num_frames=81,
    guidance_scale=5.0,
).frames[0]
export_to_video(output, "output.mp4", fps=16)

首尾帧到视频生成

下面的示例演示了如何使用图像到视频流水线，根据文本描述、起始帧和结束帧生成视频。

用法

任意到视频的可控生成

Wan VACE 支持多种生成技术，可实现可控的视频生成。部分功能包括：

控制到视频（深度、姿态、草图、光流、灰度、涂鸦、布局、边界框等）。推荐用于预处理视频以获取控制视频的库：huggingface/controlnet_aux
图像/视频到视频（首帧、尾帧、起始片段、结束片段、随机片段）
图像修复与外扩绘制
受视频约束（人脸、物体、角色等）
组合到视频（参考任意内容、动画化任意内容、替换任意内容、扩展任意内容、移动任意内容等）

此拉取请求中可用的代码片段展示了如何使用可控性信号生成视频的一些示例。

在为 VACE 流水线准备输入时，需要牢记的一般原则是：用于条件控制的输入图像或视频帧，应配有一个黑色的掩码。黑色掩码表示模型不会在该区域生成新内容，而仅将这些部分用于条件控制生成过程。对于应由模型生成的部分/帧，掩码应为白色。

Wan-Animate：通过整体复制实现统一的角色动画与替换

Wan 团队的 Wan-Animate。

我们推出了 Wan-Animate，一个用于角色动画生成与角色替换的统一框架。给定一张角色图像和一段参考视频，Wan-Animate 可以通过精确复刻视频中角色的表情和动作来驱动该角色，从而生成高保真的角色视频。或者，它可以将动画角色融入参考视频中以替换原始角色，通过复刻场景的光照和色调来实现无缝的环境融合。Wan-Animate 基于 Wan 模型构建。为了使其适应角色动画任务，我们采用了一种改进的输入范式，以区分参考条件和生成区域。这一设计将多种任务统一为一种通用的符号表示。我们使用空间对齐的骨骼信号来复刻身体运动，并使用从源图像中提取的隐式面部特征来重现表情，从而生成具有高可控性和表现力的角色视频。此外，为了增强角色替换过程中的环境融合效果，我们开发了一个辅助的 Relighting LoRA 模块。该模块在保持角色外观一致性的同时，应用适当的环境光照和色调。实验结果表明，Wan-Animate 达到了最先进的性能。我们致力于开源该模型的权重及其源代码。

项目页面：https://humanaigc.github.io/wan-animate

该模型主要由 M. Tolga Cangöz 贡献。

用法

Wan-Animate 流水线支持两种运行模式：

动画模式（默认）：根据参考视频中的动作和表情，对角色图像进行动画处理
替换模式：在保留场景的同时，将背景视频中的角色替换为新角色

先决条件

在使用 pipeline 之前，您需要对参考视频进行预处理，以提取：

姿态视频：包含表示身体运动的骨骼关键点
面部视频：包含用于表情控制的面部特征表示

对于替换模式，您还需要：

背景视频：包含该场景的原始视频
遮罩视频：一个遮罩，指示在哪里生成内容（白色）与保留原始内容（黑色）

原始视频不应直接用作诸如 pose_video 之类的输入，因为该流水线期望输入已预先处理以提取所需信息。用于准备这些输入的预处理脚本可在原始 Wan-Animate 仓库中找到。将这些预处理步骤集成到 Diffusers 中的工作已计划在后续版本中实现。

以下示例演示了如何使用 Wan-Animate 流水线：

动画模式

替换模式

高级选项

import numpy as np
import torch
from diffusers import AutoencoderKLWan, WanAnimatePipeline
from diffusers.utils import export_to_video, load_image, load_video

model_id = "Wan-AI/Wan2.2-Animate-14B-Diffusers"
vae = AutoencoderKLWan.from_pretrained(model_id, subfolder="vae", dtype=torch.float32)
pipe = WanAnimatePipeline.from_pretrained(model_id, vae=vae, dtype=torch.bfloat16)
pipe.to("cuda")  # or "mps", "xpu", "cpu"

# Load character image and preprocessed videos
image = load_image("path/to/character.jpg")
pose_video = load_video("path/to/pose_video.mp4")  # Preprocessed skeletal keypoints
face_video = load_video("path/to/face_video.mp4")  # Preprocessed facial features

# Resize image to match VAE constraints
def aspect_ratio_resize(image, pipe, max_area=720 * 1280):
    aspect_ratio = image.height / image.width
    mod_value = pipe.vae_scale_factor_spatial * pipe.transformer.config.patch_size[1]
    height = round(np.sqrt(max_area * aspect_ratio)) // mod_value * mod_value
    width = round(np.sqrt(max_area / aspect_ratio)) // mod_value * mod_value
    image = image.resize((width, height))
    return image, height, width

image, height, width = aspect_ratio_resize(image, pipe)

prompt = "A person dancing energetically in a studio with dynamic lighting and professional camera work"
negative_prompt = "blurry, low quality, distorted, deformed, static, poorly drawn"

# Generate animated video
output = pipe(
    image=image,
    pose_video=pose_video,
    face_video=face_video,
    prompt=prompt,
    negative_prompt=negative_prompt,
    height=height,
    width=width,
    segment_frame_length=77,
    guidance_scale=1.0,
    mode="animate",  # Animation mode (default)
).frames[0]
export_to_video(output, "animated_character.mp4", fps=30)

import numpy as np
import torch
from diffusers import AutoencoderKLWan, WanAnimatePipeline
from diffusers.utils import export_to_video, load_image, load_video

model_id = "Wan-AI/Wan2.2-Animate-14B-Diffusers"
vae = AutoencoderKLWan.from_pretrained(model_id, subfolder="vae", dtype=torch.float32)
pipe = WanAnimatePipeline.from_pretrained(model_id, vae=vae, dtype=torch.bfloat16)
pipe.to("cuda")  # or "mps", "xpu", "cpu"

# Load all required inputs for replacement mode
image = load_image("path/to/new_character.jpg")
pose_video = load_video("path/to/pose_video.mp4")  # Preprocessed skeletal keypoints
face_video = load_video("path/to/face_video.mp4")  # Preprocessed facial features
background_video = load_video("path/to/background_video.mp4")  # Original scene
mask_video = load_video("path/to/mask_video.mp4")  # Black: preserve, White: generate

# Resize image to match video dimensions
def aspect_ratio_resize(image, pipe, max_area=720 * 1280):
    aspect_ratio = image.height / image.width
    mod_value = pipe.vae_scale_factor_spatial * pipe.transformer.config.patch_size[1]
    height = round(np.sqrt(max_area * aspect_ratio)) // mod_value * mod_value
    width = round(np.sqrt(max_area / aspect_ratio)) // mod_value * mod_value
    image = image.resize((width, height))
    return image, height, width

image, height, width = aspect_ratio_resize(image, pipe)

prompt = "A person seamlessly integrated into the scene with consistent lighting and environment"
negative_prompt = "blurry, low quality, inconsistent lighting, floating, disconnected from scene"

# Replace character in background video
output = pipe(
    image=image,
    pose_video=pose_video,
    face_video=face_video,
    background_video=background_video,
    mask_video=mask_video,
    prompt=prompt,
    negative_prompt=negative_prompt,
    height=height,
    width=width,
    segment_frame_lengths=77,
    guidance_scale=1.0,
    mode="replace",  # Replacement mode
).frames[0]
export_to_video(output, "character_replaced.mp4", fps=30)

关键参数

mode：在 "animate"（默认）或 "replace" 之间进行选择
prev_segment_conditioning_frames：用于时间引导的帧数（推荐值为 1 或 5）。使用 5 可提供更好的时间一致性，但需要更多内存
guidance_scale：控制输出结果对文本提示词的遵循程度。较高的值（5-7）会使生成结果更贴合提示词。对于 Wan-Animate，默认情况下 CFG 处于禁用状态（guidance_scale=1.0），但您可以启用它以支持负面提示词，并对面部表情进行更精细的控制。（请注意，CFG 仅针对文本提示词和面部条件。）

备注

Wan2.1 支持通过 load_lora_weights() 加载 LoRA。

查看示例代码

# pip install ftfy
import torch
from diffusers import AutoModel, WanPipeline
from diffusers.schedulers.scheduling_unipc_multistep import UniPCMultistepScheduler
from diffusers.utils import export_to_video

vae = AutoModel.from_pretrained(
    "Wan-AI/Wan2.1-T2V-1.3B-Diffusers", subfolder="vae", dtype=torch.float32
)
pipeline = WanPipeline.from_pretrained(
    "Wan-AI/Wan2.1-T2V-1.3B-Diffusers", vae=vae, dtype=torch.bfloat16
)
pipeline.scheduler = UniPCMultistepScheduler.from_config(
    pipeline.scheduler.config, flow_shift=5.0
)
pipeline.to("cuda")  # or "mps", "xpu", "cpu"

pipeline.load_lora_weights("benjamin-paine/steamboat-willie-1.3b", adapter_name="steamboat-willie")
pipeline.set_adapters("steamboat-willie")

pipeline.enable_model_cpu_offload()

# use "steamboat willie style" to trigger the LoRA
prompt = """
steamboat willie style, golden era animation, The camera rushes from far to near in a low-angle shot,
revealing a white ferret on a log. It plays, leaps into the water, and emerges, as the camera zooms in
for a close-up. Water splashes berry bushes nearby, while moss, snow, and leaves blanket the ground.
Birch trees and a light blue sky frame the scene, with ferns in the foreground. Side lighting casts dynamic
shadows and warm highlights. Medium composition, front view, low angle, with depth of field.
"""

output = pipeline(
    prompt=prompt,
    num_frames=81,
    guidance_scale=5.0,
).frames[0]
export_to_video(output, "output.mp4", fps=16)

WanTransformer3DModel and AutoencoderKLWan supports loading from single files with from_single_file().

显示示例代码

# pip install ftfy
import torch
from diffusers import WanPipeline, WanTransformer3DModel, AutoencoderKLWan

vae = AutoencoderKLWan.from_single_file(
    "https://huggingface.co/Comfy-Org/Wan_2.1_ComfyUI_repackaged/blob/main/split_files/vae/wan_2.1_vae.safetensors"
)
transformer = WanTransformer3DModel.from_single_file(
    "https://huggingface.co/Comfy-Org/Wan_2.1_ComfyUI_repackaged/blob/main/split_files/diffusion_models/wan2.1_t2v_1.3B_bf16.safetensors",
    dtype=torch.bfloat16
)
pipeline = WanPipeline.from_pretrained(
    "Wan-AI/Wan2.1-T2V-1.3B-Diffusers",
    vae=vae,
    transformer=transformer,
    dtype=torch.bfloat16
)

将 AutoencoderKLWan 的 dtype 设置为 torch.float32，以获得更好的解码质量。
每秒帧数 (fps) 或 k 应通过 4 * k + 1 进行计算。
对于低分辨率视频，尝试使用较低的 shift 值（2.0 到 5.0）；对于高分辨率图像，则使用较高的 shift 值（7.0 到 12.0）。
Wan 2.1 和 2.2 支持使用 LightX2V LoRAs 来加速推理。在 Wan 2.2 上使用它们的操作会稍微复杂一些。请参阅此代码片段以了解更多信息。
Wan 2.2 包含两个去噪器。默认情况下，LoRA 仅加载到第一个去噪器中。可以设置 load_into_transformer_2=True 将 LoRA 加载到第二个去噪器中。请参阅此和此示例以了解更多信息。

Diffusers

Wan

文本到视频生成

首尾帧到视频生成

任意到视频的可控生成

Wan-Animate：通过整体复制实现统一的角色动画与替换

用法

先决条件

关键参数

备注

WanPipeline

类 diffusers.WanPipeline

__call__

encode_prompt

WanImageToVideoPipeline

class diffusers.WanImageToVideoPipeline

__call__

encode_prompt

WanVACEPipeline

class diffusers.WanVACEPipeline

__call__

encode_prompt

WanVideoToVideoPipeline

class diffusers.WanVideoToVideoPipeline

__call__

encode_prompt

WanAnimatePipeline

类 diffusers.WanAnimatePipeline

__call__

encode_prompt

pad_video_frames

WanPipelineOutput

class diffusers.pipelines.wan.pipeline_output.WanPipelineOutput

call

call

call

call

call