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