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}
}