Wan2.2-Animate-2-14B 实战指南：Wan-Animate-2 端到端角色动画模型的架构解析与推理部署

• 人工智能
• 大模型
• 计算机视觉
• 媒体生成

Wan-Animate-2 是万兴科技 Wan-AI 团队提出的端到端角色动画（Character Animation）框架，其核心思路是在重新设计的 Diffusion Transformer 中直接消费驱动视频（driving video），从而彻底消除传统方案中中间运动提取器（intermediate motion extractor）带来的信息损失，兼顾高保真动作生成与强身份保持（identity preservation）。本指南以仓库根目录的 README.md 为骨架，结合仓库内的模型文件与组件目录，系统讲解 Wan2.2-Animate-2-14B 的环境搭建、权重下载、CLI 推理、Diffusers 集成与 Gradio 演示，帮助你从零开始跑通 Base 与 Distillation 两套模型的完整推理流程。

模型概览：端到端角色动画的核心设计

Wan-Animate-2 通过重构 Diffusion Transformer 的输入与条件注入方式，实现了两项关键能力：

• 直接消费驱动视频：不再依赖姿态估计、关键点提取等中间模块，驱动视频以原始形式进入网络，由模型端到端学习动作与外观的耦合关系，从而获得高保真运动生成和更强的身份保持能力；
• 文本驱动的视角控制（text-driven viewpoint control）：新增文本驱动的镜头视角控制，使输出画面的相机视角与驱动视频解耦，创作者可以通过文本描述独立指定生成画面的拍摄角度。

此外，官方还发布了Wan-Animate-2-Lite高效变体，据 README 官方表述，其将推理延迟降低到实时门槛（real-time thresholds），面向流式角色动画场景。

Release Notes 与完成度

README 中的发布记录显示，本项目在 2026 年 8 月 7 日一次性发布了：

• Wan-Animate-2 推理脚本；
• Wan-Animate-2 Base 模型权重；
• Wan-Animate-2 Distillation 模型权重。

在 Todo List 中，推理代码、模型 Checkpoints、Diffusers 集成、DiffSynth-Studio 集成与 ComfyUI 集成均标记为已完成（[x]），说明该镜像仓库对应的开源实现已具备从原生脚本到主流生态的全链路使用能力。

仓库构成与模型文件说明

当前镜像仓库的文件布局与官方 README 的推理流程一一对应，主要包括三部分：

从videomodel/Wan-AI/目录中的文件名可以推断，推理时加载的辅助组件包括：

• models_t5_umt5-xxl-enc-bf16.pth：UMT5-XXL 文本编码器（bf16 精度），负责将中文提示词编码为文本条件；
• models_clip_open-clip-xlm-roberta-large-vit-huge-14.pth：基于 OpenCLIP 的 XLM-RoBERTa-large + ViT-huge-14 文本编码器，用于图像/文本对齐的 CLIP 条件；
• vae.pth：视频/图像变分自编码器，负责像素空间与潜空间的双向转换；
• umt5-xxl/与xlm-roberta-large/：两个文本编码器对应的分词器目录。

分词器目录中的配置文件提供了可确认的细节：xlm-roberta-large/tokenizer_config.json声明其tokenizer_class为XLMRobertaTokenizer、model_max_length为 512；umt5-xxl/special_tokens_map.json声明了<pad>、<s>、</s>、<unk>四个特殊 token，以及 300 个<extra_id_0>至<extra_id_299>的扩展 token。这些组件在原生脚本中会被按路径逐一加载，组装成完整的文生视频/角色动画模型。

环境安装：从零搭建推理环境

1. 克隆仓库

git clone --recursive https://github.com/Wan-Video/Wan-Animate-2.git

--recursive用于同步拉取仓库引用的子模块（例如依赖的第三方组件）。

2. 创建 Python 环境并安装 PyTorch

官方默认使用 Python 3.11 与 CUDA 12.6 的 PyTorch 2.7 组合：

conda create -n wan_animate_2 python==3.11 -y pip install torch==2.7.0 torchvision==0.22.0 torchaudio==2.7.0 --index-url https://download.pytorch.org/whl/cu126

--index-url指定了 CUDA 12.6 专属的 wheel 源，这是保证后续flash_attn与算子兼容性的关键前提。如果你的 GPU 驱动支持的 CUDA 版本不同，需替换为对应的 wheel 源。

3. 安装依赖

依赖清单以仓库根目录的 requirements.txt 为准：

pip install -r requirements.txt

4. 安装 flash_attn

Wan-Animate-2 的 Transformer 结构依赖 Flash Attention 加速注意力计算、降低显存占用：

pip install flash-attn --no-build-isolation

--no-build-isolation让编译复用当前环境中已有的构建依赖，避免重复下载编译工具链。

5. 以可编辑模式安装本仓库

pip install -e .

这样可以将仓库内的 Python 包注册进当前环境，便于后续在任意位置 import 相关模块，也方便跟随源码改动即时生效。

模型下载：两种渠道任选

使用huggingface-cli下载（建议先安装 CLI 工具）：

pip install "huggingface_hub[cli]" huggingface-cli download Wan-AI/Wan2.2-Animate-2-14B --local-dir ./ckpts/

使用modelscopeCLI 下载：

pip install modelscope modelscope download --model Wan-AI/Wan2.2-Animate-2-14B --local_dir ./ckpts/

下载完成后，./ckpts/中应包含与当前镜像仓库一致的主模型权重（wan_animate_2/下的两个.safetensors）与videomodel/辅助组件。注意：仓库内的权重文件以 Git LFS 指针形式托管，实际权重需通过上述 CLI 拉取完整内容。

推理前置步骤：用 LLM 生成结构化的中文图像描述

Wan-Animate-2 的提示词并非自由发挥的文本，而是需要遵循固定范式的结构化中文描述——它被拆分为"人物外观描述"与"背景描述"两部分，且明确"不描述动作行为"。官方建议先用一个 LLM（例如 Qwen3.7-Plus）配合以下 Prompt 生成图像 caption，再将其作为 Wan-Animate-2 的输入：

用中文客观描述图片中的内容，包括以下要点：人物外观描述，不描述动作行为。 背景描述，忽略主观评价和情绪推测。 下面给出描述范例，必须遵循这个范式，不要输出额外的符号： 人物外观描述：穿着一件浅蓝色的校服衬衫，领口和袖口有白色边饰。胸前有一个圆形徽章。 背景描述：背景为明亮、整洁的教室或办公室，氛围安静有序。

这一步骤的意义在于：人物外观描述驱动模型的身份保持模块，而背景描述则为视角控制与背景重建提供条件。官方 Demo 中使用的提示词模板可以直接复用（见下文示例），它同时覆盖了服装细节、配饰、发型等外观要素与场景要素。

CLI 推理：Base 与 Distillation 两套命令

推理脚本位于infer/wan_animate_2_demo.py，配置文件为infer/wan_animate_2.yaml（Base）与infer/wan_animate_2_distillation.yaml（Distillation）。执行前需先将仓库根目录加入PYTHONPATH：

Wan-Animate-2 Base

export PYTHONPATH="$(pwd)" cd infer python wan_animate_2_demo.py \ --prompt "人物外观描述：一只银灰色虎斑纹的小猫，拥有圆润的脸庞、竖立的耳朵和巨大的圆形眼睛。它身穿一套深蓝色的制服套装，包括一件带有金色纽扣的西装外套和一条百褶裙。外套里面搭配着白色衬衫，领口处系着一个红色的蝴蝶结，袖口露出白色的衬衫边缘。背景描述：背景为纯白色，光线均匀明亮，无其他杂物或装饰。" \ --refer-img-file ../examples/demo1/reference.png \ --refer-video-file ../examples/demo1/template.mp4 \ --config ./wan_animate_2.yaml

Wan-Animate-2 Distillation（10 步，无 CFG）

export PYTHONPATH="$(pwd)" cd infer python wan_animate_2_demo.py \ --prompt "人物外观描述：一只银灰色虎斑纹的小猫，拥有圆润的脸庞、竖立的耳朵和巨大的圆形眼睛。它身穿一套深蓝色的制服套装，包括一件带有金色纽扣的西装外套和一条百褶裙。外套里面搭配着白色衬衫，领口处系着一个红色的蝴蝶结，袖口露出白色的衬衫边缘。背景描述：背景为纯白色，光线均匀明亮，无其他杂物或装饰。" \ --refer-img-file ../examples/demo1/reference.png \ --refer-video-file ../examples/demo1/template.mp4 \ --config ./wan_animate_2_distillation.yaml \ --sample_guide_scale 1.0 \ --step 10

说明：--sample_guide_scale 1.0表示关闭 classifier-free guidance（CFG=1 即不放大无条件/有条件差值），--step 10将采样步数压缩到 10 步，这是蒸馏模型的核心加速设定。注意原文档中--step 10一行缺少续行符\，实际粘贴运行时应补齐（如上所示）。

关键命令行参数速查

硬件与并行配置注意事项

README 明确说明：仓库默认配置针对8× A800 GPU调优，支持720P视频生成；官方同时测试过2× A800 GPU上的480P生成。如果你的硬件配置不同，需要相应调整 YAML 文件中的并行配置（parallel configs）。这一点在部署到更小显存或不同卡型的集群时尤为关键。

Diffusers 集成：三行代码跑通推理

Wan-Animate-2 已被 diffusers 库官方支持（README 中标注的 PR #14412）。在下一个正式 release 之前，需要从源码安装最新版 diffusers：

pip install git+https://github.com/huggingface/diffusers.git pip install flash-attn --no-build-isolation

Wan-Animate-2 Base

import torch from diffusers import WanAnimate2Pipeline from diffusers.utils import export_to_video, load_image pipe = WanAnimate2Pipeline.from_pretrained( "Wan-AI/Wan2.2-Animate-2-14B-Diffusers", torch_dtype=torch.bfloat16 ).to("cuda") output = pipe( image=load_image("../examples/demo1/reference.png"), driving_video="../examples/demo1/template.mp4", prompt="人物外观描述：一只银灰色虎斑纹的小猫，拥有圆润的脸庞、竖立的耳朵和巨大的圆形眼睛。它身穿一套深蓝色的制服套装，包括一件带有金色纽扣的西装外套和一条百褶裙。外套里面搭配着白色衬衫，领口处系着一个红色的蝴蝶结，袖口露出白色的衬衫边缘。背景描述：背景为纯白色，光线均匀明亮，无其他杂物或装饰。", height=800, width=640, num_inference_steps=40, ) export_to_video(output.frames[0], "output.mp4", fps=24)

Wan-Animate-2 Distillation（10 步、无 CFG、Euler 求解器）

pipe = WanAnimate2Pipeline.from_pretrained( "Wan-AI/Wan2.2-Animate-2-14B-Distilled-Diffusers", torch_dtype=torch.bfloat16 ).to("cuda") output = pipe( image=load_image("../examples/demo1/reference.png"), driving_video="../examples/demo1/template.mp4", prompt="人物外观描述：一只银灰色虎斑纹的小猫，拥有圆润的脸庞、竖立的耳朵和巨大的圆形眼睛。它身穿一套深蓝色的制服套装，包括一件带有金色纽扣的西装外套和一条百褶裙。外套里面搭配着白色衬衫，领口处系着一个红色的蝴蝶结，袖口露出白色的衬衫边缘。背景描述：背景为纯白色，光线均匀明亮，无其他杂物或装饰。", num_inference_steps=10, guidance_scale=1.0, # no classifier-free guidance flow_solver="euler", # Euler scheduler for distilled model ) export_to_video(output.frames[0], "output.mp4", fps=24)

关键参数对照

export_to_video以指定fps将帧序列导出为output.mp4（示例为 24 fps）。需要注意的是，load_image中的路径是相对脚本执行目录的，请按实际文件位置调整。

Gradio 本地演示

官方在 ModelScope Studio 提供了在线 Demo，也可以本地一键启动 WebUI：

• Wan-Animate-2 Base：

cd infer python wan_animate_2_gradio.py

• Wan-Animate-2 Distillation：

cd infer python wan_animate_2_gradio_distillation.py

两套脚本分别封装了上文 CLI 推理的核心逻辑，适合快速验证效果或做交互式参数调试。

引用与许可

如果本工作对你的研究或产品有帮助，建议引用官方论文（README 中给出的 BibTeX 如下，其中 arXiv 编号目前仍是占位符TODO，正式版本请以官方公开发布为准）：

@article{wang2026wananimate2, title = {Wan-Animate-2: Real-Time End-to-End Character Animation via Diffusion Transformer}, author = {Wang, Guangyuan and Hu, Li and Meng, Dechao and Zhang, Zhongyi and Zhang, Peng and Huang, Mingyang and Zhang, Ruoshi and Sun, Ke and Zhang, Zhe and Wang, Xingjun and Cheng, Gang and Zhang, Bang}, journal = {arXiv preprint arXiv:TODO.06009}, year = {2026}, url = {https://arxiv.org/abs/TODO.06009} }

本项目基于 Apache License 2.0 开源，允许商用与自由分发，具体权利义务以许可证原文为准。

小结

围绕 README.md 提供的完整链路，你可以依次完成：环境搭建（Python 3.11 + PyTorch 2.7 cu126 + flash_attn）→ 权重下载（huggingface-cli / modelscope）→ LLM 生成结构化提示词 → 原生 CLI 推理（Base 40 步 / Distillation 10 步）→ Diffusers 或 Gradio 集成。其中蒸馏模型的"10 步采样 + CFG=1 + Euler 求解器"是一组关键的加速组合，而 720P/8×A800 与 480P/2×A800 的官方默认配置则提示我们：不同分辨率需要按硬件调整 YAML 并行参数。结合仓库内wan_animate_2/与videomodel/Wan-AI/的文件布局，可以清晰地看到 bf16 主模型与 UMT5-XXL、XLM-RoBERTa CLIP 文本编码器、VAE 组成的完整多模态推理链路。

• 人工智能
• 大模型
• 计算机视觉
• 媒体生成