Wan-Video/Wan2.2 · 上手攻略

仓库：Wan-Video/Wan2.2
链接：https://github.com/Wan-Video/Wan2.2
分类：multimodal / 视频生成 · 扩散模型 · 开源权重
作者：spark
更新：2026-11-02

一、它是什么

Wan2.2 是阿里通义万相（Wan）团队开源的大规模视频生成模型（Apache-2.0，Python），论文 Wan: Open and Advanced Large-Scale Video Generative Models（arXiv:2503.20314）。仓库同时提供推理代码 + 模型权重 + ComfyUI 集成 + Diffusers 集成。

相对 Wan2.1 的四个核心变化（README 原文口径）：

MoE 架构：把视频扩散的去噪过程沿时间步切分给多个专职专家模型，在不增加计算量（compute cost）的前提下扩大模型总容量。14B 级的 A14B 模型采用"高活跃参数 + 低活跃参数"的双专家 MoE。
电影级审美：引入带细粒度标注的美学数据（光照、构图、对比度、色调等），让风格更可控。
复杂运动：相对 Wan2.1，训练数据 图像 +65.6%、视频 +83.2%，泛化能力提升。
高压缩率 TI2V-5B：Wan2.2-VAE 压缩比 16×16×4，一个 5B 模型同时支持文生视频与图生视频，720P / 24fps，可在消费级显卡（如 RTX 4090）上跑。

模型矩阵（README 模型下载表）：

模型	类型	分辨率	显存（README 标注）
T2V-A14B	文生视频 MoE	480P & 720P	≥80GB
I2V-A14B	图生视频 MoE	480P & 720P	≥80GB
TI2V-5B	文/图生视频，高压缩 VAE	720P（1280×704）	≥24GB（RTX 4090）
S2V-14B	音频驱动（语音/唱歌）	480P & 720P	≥80GB
Animate-14B	角色动画 / 角色替换	—	多卡路径为主

权重同时发布在 Hugging Face（Wan-AI/...）和 ModelScope（Wan-AI/...），国内下载走 ModelScope 更稳。

二、解决什么问题

视频生成赛道此前存在一个明显断层：闭源模型（Sora / 可灵 / Veo）效果领先但不可用、不可控、不可私有化；开源模型则普遍在运动幅度和长时一致性上差一档，且大多只有单一文生视频能力。

Wan2.2 想同时解决三件事：

既要开源又要质量：用 MoE 把参数容量做大但算力可控，A14B 级模型在开源视频模型里属第一梯队；README 声称在开源与闭源模型中达到 TOP 表现（此为官方自述，非第三方评测结论）。
要覆盖真实业务形态：不再只有 T2V。I2V（首帧控制）、TI2V（一张图 + 文本双输入）、S2V（音频驱动，含唱歌与 pose 驱动）、Animate（用真人视频驱动角色 / 用参考视频替换角色），覆盖了广告、漫剧、数字人、影视预演等常见流水线。
要能被现有工具链吃掉：官方同时做了 ComfyUI 和 Diffusers 两条集成路线，社区还有 LightX2V、FastVideo、Cache-dit、DiffSynth-Studio、Kijai 的 WanVideoWrapper 等一整圈加速与微调方案。

三、快速安装

前置：Linux + NVIDIA GPU，PyTorch ≥ 2.4.0（README 明确要求）。

git clone https://github.com/Wan-Video/Wan2.2.git
cd Wan2.2

# 先装其他包，flash_attn 最后装（README 特别提示）
pip install -r requirements.txt

# 只有跑 Speech-to-Video 的 TTS 功能才需要：
pip install -r requirements_s2v.txt

关于 flash_attn：README 原话是 "If the installation of flash_attn fails, try installing the other packages first and install flash_attn last"。这条提示非常实用——flash-attn 需要本地编译，CUDA / torch / 编译器版本任一不匹配就会失败，放最后装可以避免它与其它包的安装顺序互相干扰。

下载权重

# Hugging Face
pip install "huggingface_hub[cli]"
huggingface-cli download Wan-AI/Wan2.2-T2V-A14B --local-dir ./Wan2.2-T2V-A14B

# ModelScope（国内推荐）
pip install modelscope
modelscope download Wan-AI/Wan2.2-T2V-A14B --local_dir ./Wan2.2-T2V-A14B

把 <模型名> 换成 Wan2.2-I2V-A14B / Wan2.2-TI2V-5B / Wan2.2-S2V-14B / Wan2.2-Animate-14B 即可。

不装代码的快捷路径

ComfyUI：官方已集成（有中英文教程），适合不想碰命令行的工作流玩家。
Diffusers：T2V / I2V / TI2V / Animate 都已有官方 Diffusers 权重（如 Wan-AI/Wan2.2-T2V-A14B-Diffusers），适合已在 HF 生态里做事的人。
在线试玩：wan.video、ModelScope Studio、HuggingFace Space 都有现成 demo。

四、核心用法

4.1 文生视频（T2V-A14B）

python generate.py --task t2v-A14B --size 1280*720 \
  --ckpt_dir ./Wan2.2-T2V-A14B --offload_model True --convert_model_dtype \
  --prompt "Two anthropomorphic cats in comfy boxing gear and bright gloves fight intensely on a spotlighted stage."

需要 ≥80GB 显存的 GPU。显存不足时加 --t5_cpu（把文本编码器挪到 CPU）。

多卡加速用 PyTorch FSDP + DeepSpeed Ulysses：

torchrun --nproc_per_node=8 generate.py --task t2v-A14B --size 1280*720 \
  --ckpt_dir ./Wan2.2-T2V-A14B --dit_fsdp --t5_fsdp --ulysses_size 8 \
  --prompt "Two anthropomorphic cats in comfy boxing gear and bright gloves fight intensely on a spotlighted stage."

4.2 提示词扩展（强烈建议开）

README 明确建议开启 prompt extension，说它能"丰富细节、进一步提升视频质量"。两条路：

（a）DashScope API（云端）

DASH_API_KEY=your_key torchrun --nproc_per_node=8 generate.py \
  --task t2v-A14B --size 1280*720 --ckpt_dir ./Wan2.2-T2V-A14B \
  --dit_fsdp --t5_fsdp --ulysses_size 8 \
  --prompt "..." --use_prompt_extend --prompt_extend_method 'dashscope' \
  --prompt_extend_target_lang 'zh'

用阿里云国际站还需设 DASH_API_URL=https://dashscope-intl.aliyuncs.com/api/v1。T2V 任务默认走 qwen-plus，I2V 任务走 qwen-vl-max；可用 --prompt_extend_model 换。

（b）本地 Qwen（离线）

torchrun --nproc_per_node=8 generate.py \
  --task t2v-A14B --size 1280*720 --ckpt_dir ./Wan2.2-T2V-A14B \
  --dit_fsdp --t5_fsdp --ulysses_size 8 \
  --prompt "..." --use_prompt_extend --prompt_extend_method 'local_qwen' \
  --prompt_extend_target_lang 'zh'

本地可选 Qwen/Qwen2.5-14B-Instruct、Qwen2.5-7B-Instruct、Qwen2.5-3B-Instruct（I2V 用 Qwen2.5-VL-7B-Instruct / 3B-Instruct）。模型越大扩展效果越好，也越吃显存。

4.3 图生视频（I2V-A14B）

python generate.py --task i2v-A14B --size 1280*720 \
  --ckpt_dir ./Wan2.2-I2V-A14B --offload_model True --convert_model_dtype \
  --image examples/i2v_input.JPG --prompt "Summer beach vacation style, a white cat wearing sunglasses sits on a surfboard. ..."

注意：--size 在 I2V 任务里表示生成画面的面积，宽高比跟随输入图。也可以不给 prompt（--prompt ''），让扩展模型从图片反推提示词。

4.4 文/图生视频一体化（TI2V-5B）—— 消费级显卡的唯一入口

python generate.py --task ti2v-5B --size 1280*704 \
  --ckpt_dir ./Wan2.2-TI2V-5B --offload_model True --convert_model_dtype --t5_cpu \
  --prompt "Two anthropomorphic cats in comfy boxing gear and bright gloves fight intensely on a spotlighted stage"

需要 ≥24GB 显存（例如 RTX 4090）。如果你的卡有 ≥80GB，把 --offload_model True --convert_model_dtype --t5_cpu 全部去掉会更快。

关键差异：TI2V-5B 的 720P 是 1280×704 或 704×1280（不是 720），因为高度需被 16 整除以匹配 VAE 压缩。加 --image 就变图生视频，不加就是文生视频。

4.5 语音/唱歌驱动（S2V-14B）

# 用现成音频
python generate.py --task s2v-14B --size 1024*704 \
  --ckpt_dir ./Wan2.2-S2V-14B/ --offload_model True --convert_model_dtype \
  --prompt "Summer beach vacation style, a white cat wearing sunglasses sits on a surfboard." \
  --image "examples/i2v_input.JPG" --audio "examples/talk.wav"

# 内置 CosyVoice TTS：先合成语音再驱动
python generate.py --task s2v-14B --size 1024*704 \
  --ckpt_dir ./Wan2.2-S2V-14B/ --offload_model True --convert_model_dtype \
  --prompt "..." --image "examples/i2v_input.JPG" \
  --enable_tts --tts_prompt_audio "examples/zero_shot_prompt.wav" \
  --tts_prompt_text "希望你以后能够做的比我还好呦。" \
  --tts_text "收到好友从远方寄来的生日礼物，..."

额外参数：--pose_video 启用 pose 驱动（按指定姿态序列生成并与音频同步）；--num_clip 控制生成片段数，适合快速预览。

4.6 角色动画 / 角色替换（Animate-14B）

Animate 有两种模式：

animation 模式：输入视频 + 角色图 → 生成模仿该视频动作的角色视频；
replacement 模式：把角色图替换成输入视频里的表演。

需要先做预处理：

# animation
python ./wan/modules/animate/preprocess/preprocess_data.py \
  --ckpt_path ./Wan2.2-Animate-14B/process_checkpoint \
  --video_path ./examples/wan_animate/animate/video.mp4 \
  --refer_path ./examples/wan_animate/animate/image.jpeg \
  --save_path ./examples/wan_animate/animate/process_results \
  --resolution_area 1280 720 --retarget_flag --use_flux

# replacement
python ./wan/modules/animate/preprocess/preprocess_data.py \
  --ckpt_path ./Wan2.2-Animate-14B/process_checkpoint \
  --video_path ./examples/wan_animate/replace/video.mp4 \
  --refer_path ./examples/wan_animate/replace/image.jpeg \
  --save_path ./examples/wan_animate/replace/process_results \
  --resolution_area 1280 720 --iterations 3 --k 7 --w_len 1 --h_len 1 --replace_flag

再推理：

python generate.py --task animate-14B --ckpt_dir ./Wan2.2-Animate-14B/ \
  --src_root_path ./examples/wan_animate/animate/process_results/ --refert_num 1

# 多卡
python -m torch.distributed.run --nnodes 1 --nproc_per_node 8 generate.py \
  --task animate-14B --ckpt_dir ./Wan2.2-Animate-14B/ \
  --src_root_path ./examples/wan_animate/animate/process_results/ --refert_num 1 \
  --dit_fsdp --t5_fsdp --ulysses_size 8

replacement 模式加 --replace_flag，若还要匹配原视频的光照可加 --use_relighting_lora。

五、典型适用场景

24GB 单卡的创作者：TI2V-5B 是目前最省显存的 720P/24fps 开源选择，4090 即可出片。
私有化部署的内容工厂：品牌方不能让素材出内网，Apache-2.0 权重 + 自建推理是可行的合规路径。
数字人 / 漫剧流水线：S2V-14B（音频驱动）+ Animate-14B（动作迁移）能覆盖"配音 + 表演"这两段。
广告分镜预演：I2V 从一张分镜图出动态稿，比纯 T2V 更可控。
研究与二次开发：MoE 时间步专家结构、VAE 压缩比设计都是研究素材；DiffSynth-Studio 支持 FP8 量化、逐层 offload、LoRA 训练与全量训练。
已有工作流的增量升级：已经在用 ComfyUI 的团队，直接换 WanVideoWrapper / 官方 Wan2.2 节点即可。

六、坑与注意

显存是最大门槛。A14B / S2V / Animate 都要 80GB 起步（单卡），单张消费卡只能跑 TI2V-5B。4090 用户应直接选 TI2V-5B，别去折腾 A14B。
--size 语义随任务变化。T2V-A14B 用 1280*720，而 TI2V-5B 的 720P 是 1280*704，S2V-14B 是 1024*704。写成 1280*720 给 5B 模型会因高度不被 16 整除而对不齐 VAE 压缩网格。I2V 任务里 --size 是"面积"、宽高比跟输入图走，不是绝对宽高。
flash_attn 装不上是头号环境问题。按 README 提示把其它包装完最后再装它；若仍失败，需要检查 torch / CUDA / nvcc 三者版本匹配，通常编译报错信息里就写明了不匹配点。
提示词扩展依赖外部服务或额外显存。dashscope 模式要把 prompt 发到阿里云服务（跨境团队注意数据合规），local_qwen 模式则要额外装 3B～14B 的 Qwen，显存更紧张。两者都加 --use_prompt_extend 才生效——不显式加这个 flag，扩展根本不会跑。
MoE 权重体积大、下载慢。A14B / 14B 级别权重动辄数十 GB，加上 Animate 的 process_checkpoint，磁盘与带宽要提前算。
Animate 必须先预处理，且预处理本身要单独下 process_checkpoint 并跑 preprocess_data.py。直接跳到 generate.py 会因为缺 process_results 而失败。--use_flux 依赖外部 FLUX 模型做重定向。
TTS 路径有额外依赖。--enable_tts 依赖 CosyVoice，需要额外 pip install -r requirements_s2v.txt，且要提供一段 tts_prompt_audio + 对应文本做音色克隆。
huggingface-cli 命令已过时。当前 HuggingFace 官方推荐 hf download；README 里的 huggingface-cli download 在新版 hub 上仍可用但会提示弃用。国内建议直接用 ModelScope。
多卡参数是成组的。--dit_fsdp --t5_fsdp --ulysses_size 8 中 --ulysses_size 必须 ≤ GPU 卡数，8 卡写 8。漏掉任一个会退化到与单卡不同的路径。
社区加速方案要单独评估。README 列了 LightX2V、FastVideo、Cache-dit、FastVideo、DiffSynth-Studio 等一长串第三方项目，它们并非官方发布，质量与安全各不相同；生产使用请单独审计权重来源与许可。
官方自评不等于第三方结论。README 说 "achieving TOP performance among all-sourced and closed-sourced models" 是团队自述，缺少具体榜单与基线数字；选型前请用自有 prompt 集做 A/B。

七、与同类对比

维度	Wan2.2	Wan2.1	HunyuanVideo	CogVideoX	闭源（Sora / 可灵 / Veo）
架构	视频扩散 + 时间步 MoE + 16×16×4 VAE	视频扩散	视频扩散（大模型）	视频扩散	各家闭源
权重许可	Apache-2.0	Apache-2.0	社区许可（商用需查条款）	Apache-2.0	不可得
任务覆盖	T2V / I2V / TI2V / S2V / Animate	T2V / I2V	T2V（I2V 等扩展另计）	T2V / I2V	全
消费级显卡	TI2V-5B：24GB（4090）	I2V-14B 约 80GB	需大显存	I2V-5B 约 16GB（社区口径）	闭源托管
多卡并行	FSDP + DeepSpeed Ulysses	支持	支持	支持	闭源托管
生态成熟度	ComfyUI + Diffusers 双官方集成，社区丰富	成熟	较成熟	成熟	N/A
私有化部署	可以	可以	可以	可以	通常不行

在"开源 + 可私有化 + 有消费级档位 + 任务类型全"这四个维度同时满足的，目前 Wan2.2 是最完整的一个。代价是官方自研推理代码对硬件门槛偏高，A14B 级别实际是数据中心显卡的活。

八、一句话推荐

Wan2.2 是开源视频生成里少见的"全家桶"：MoE 架构压住了算力、T2V/I2V/TI2V/S2V/Animate 五条业务线齐全、ComfyUI 与 Diffusers 双集成省心——但只有 TI2V-5B 是消费级显卡能碰的，24GB 起步的 720P/24fps 就是它的真实起点，A14B 及以上请按多卡数据中心方案来规划。

附：来源与核验说明

已 fetch：https://github.com/Wan-Video/Wan2.2（README 网页版）
已 fetch：https://raw.githubusercontent.com/Wan-Video/Wan2.2/main/README.md（全文，35,804 字节，逐段核对命令）
仓库卡片 organized/repo_cards/4811-wan-video-wan2-2.md：Stars 18304、语言 Python、许可 Apache-2.0、最近提交 2026-09-21、成熟度 production

不确定处（已在上文标注） - 精确生成耗时、显存峰值实测值 README 未给出，本文只引用了 README 的最低显存标注（80GB / 24GB）→ 未核实实测。 - "TOP performance" 为官方自述，无第三方榜单数字 → 已按自述处理。 - CogVideoX 的 16GB 显存、HunyuanVideo 的商用许可条款来自通用认知，未在本次 fetch 中核实 → 相关对比行仅供参考。 - TI2V-5B 单卡 4090 的实际吞吐（分钟/条）README 未提供 → 未核实。 - Animate 预处理中 --use_flux 所需的外部 FLUX 权重来源与体积未核实。 - 仓库 requirements.txt 未逐项展开核对；torch ≥ 2.4.0 与 flash_attn 安装顺序均引自 README 原文。