VACE Wan2.1 1.3B Preview

🚀 VACE：一体化视频创作与编辑

VACE 是一款专为视频创作与编辑设计的一体化模型。它涵盖了参考视频生成、视频到视频编辑、基于参考内容生成视频等多种任务，用户可以自由组合这些任务，探索多样化的创作可能，有效简化工作流程。

🚀 快速开始

VACE 支持用户输入文本提示，以及可选的视频、掩码和图像，用于视频生成或编辑。详细的使用说明可查看用户指南。

✨ 主要特性

• 多任务支持：涵盖参考视频生成（R2V）、视频到视频编辑（V2V）、掩码视频到视频编辑（MV2V）等多种任务。
• 灵活创作：用户可自由组合任务，探索多样化的创作可能。
• 多模型选择：提供多种不同规模和特性的模型供用户选择。

📦 安装指南

代码库在 Python 3.10.13、CUDA 12.4 版本和 PyTorch >= 2.5.1 环境下进行了测试。

模型推理设置

你可以通过以下命令为 VACE 模型推理进行设置：

git clone https://github.com/ali-vilab/VACE.git && cd VACE
pip install torch==2.5.1 torchvision==0.20.1 --index-url https://download.pytorch.org/whl/cu124  # 如果未安装 PyTorch
pip install -r requirements.txt
pip install wan@git+https://github.com/Wan-Video/Wan2.1  # 如果你想使用基于 Wan2.1 的 VACE
pip install ltx-video@git+https://github.com/Lightricks/LTX-Video@ltx-video-0.9.1 sentencepiece --no-deps # 如果你想使用基于 LTX-Video-0.9 的 VACE，可能会与 Wan 冲突

请将你选择的基础模型下载到 <repo-root>/models/ 目录下。

预处理工具设置

如果你需要预处理工具，请安装：

pip install -r requirements/annotator.txt

请将 VACE-Annotators 下载到 <repo-root>/models/ 目录下。

本地目录设置

建议将 VACE-Benchmark 下载到 <repo-root>/benchmarks/ 目录下，作为 run_vace_xxx.sh 中的示例。

我们建议按以下方式组织本地目录：

VACE
├── ...
├── benchmarks
│   └── VACE-Benchmark
│       └── assets
│           └── examples
│               ├── animate_anything
│               │   └── ...
│               └── ...
├── models
│   ├── VACE-Annotators
│   │   └── ...
│   ├── VACE-LTX-Video-0.9
│   │   └── ...
│   └── VACE-Wan2.1-1.3B-Preview
│       └── ...
└── ...

💻 使用示例

基础用法

命令行推理

1) 端到端运行

若想简单运行 VACE 而不深入了解实现细节，我们推荐使用端到端管道。例如：

# 运行 V2V 深度任务
python vace/vace_pipeline.py --base wan --task depth --video assets/videos/test.mp4 --prompt 'xxx'

# 通过提供边界框运行 MV2V 图像修复任务
python vace/vace_pipeline.py --base wan --task inpainting --mode bbox --bbox 50,50,550,700 --video assets/videos/test.mp4 --prompt 'xxx'

此脚本将按顺序运行视频预处理和模型推理，你需要指定预处理（--task、--mode、--bbox、--video 等）和推理（--prompt 等）所需的所有参数。默认情况下，输出视频以及中间视频、掩码和图像将保存到 ./results/ 目录下。

💡 使用建议： 不同任务管道的使用示例请参考 run_vace_pipeline.sh。

2) 预处理

为了更灵活地控制输入，在进行 VACE 模型推理之前，需要先将用户输入预处理为 src_video、src_mask 和 src_ref_images。 我们为每个预处理器分配了一个任务名称，因此只需调用 vace_preprocess.py 并指定任务名称和任务参数即可。例如：

# 处理视频深度
python vace/vace_preproccess.py --task depth --video assets/videos/test.mp4

# 通过提供边界框处理视频图像修复
python vace/vace_preproccess.py --task inpainting --mode bbox --bbox 50,50,550,700 --video assets/videos/test.mp4

默认情况下，输出将保存到 ./proccessed/ 目录下。

💡 使用建议： 不同任务的预处理方法请参考 run_vace_pipeline.sh。此外，所有预定义的任务和所需参数请参考 vace/configs/。你也可以通过在 annotators 中实现并在 configs 中注册来自定义预处理器。

3) 模型推理

使用从预处理中获得的输入数据，可以按以下方式进行模型推理：

# 单 GPU 推理 Wan2.1
python vace/vace_wan_inference.py --ckpt_dir <path-to-model> --src_video <path-to-src-video> --src_mask <path-to-src-mask> --src_ref_images <paths-to-src-ref-images> --prompt "xxx"

# 多 GPU 加速推理 Wan2.1
pip install "xfuser>=0.4.1"
torchrun --nproc_per_node=8 vace/vace_wan_inference.py --dit_fsdp --t5_fsdp --ulysses_size 1 --ring_size 8 --ckpt_dir <path-to-model> --src_video <path-to-src-video> --src_mask <path-to-src-mask> --src_ref_images <paths-to-src-ref-images> --prompt "xxx"

# 推理 LTX
python vace/vace_ltx_inference.py --ckpt_path <path-to-model> --text_encoder_path <path-to-model> --src_video <path-to-src-video> --src_mask <path-to-src-mask> --src_ref_images <paths-to-src-ref-images> --prompt "xxx"

默认情况下，输出视频以及中间视频、掩码和图像将保存到 ./results/ 目录下。

💡 使用建议： (1) 推理参数请参考 vace/vace_wan_inference.py 和 vace/vace_ltx_inference.py。 (2) 对于 LTX-Video 和使用英文的 Wan2.1 用户，需要使用提示扩展来解锁模型的全部性能。请遵循 Wan2.1 的说明，并在运行推理时设置 --use_prompt_extend。

高级用法

Gradio 推理

对于预处理器，运行：

python vace/gradios/preprocess_demo.py

对于模型推理，运行：

# Wan2.1 的 Gradio 推理
python vace/gradios/vace_wan_demo.py

# LTX 的 Gradio 推理
python vace/gradios/vace_ltx_demo.py

📚 详细文档

更多详细信息可参考以下链接：

• 用户指南

🔧 技术细节

• 输入支持：输入支持任意分辨率，但为达到最佳效果，视频尺寸应在特定范围内。
• 模型许可证：所有模型继承原始模型的许可证。

📄 许可证

本项目采用 Apache-2.0 许可证。部分模型采用 RAIL-M 许可证。

致谢

我们感谢以下优秀的项目，包括 Scepter、Wan 和 LTX-Video。

引用格式

@article{vace,
    title = {VACE: All-in-One Video Creation and Editing},
    author = {Jiang, Zeyinzi and Han, Zhen and Mao, Chaojie and Zhang, Jingfeng and Pan, Yulin and Liu, Yu},
    journal = {arXiv preprint arXiv:2503.07598},
    year = {2025}
}