VACE

环境要求

• Python 3.10.13
• CUDA 12.4（GPU 环境）
• PyTorch >= 2.5.1
• 磁盘空间用于存放基础模型到 <repo-root>/models/
• 已安装 git 与 pip

安装与启动步骤

1. 1克隆仓库

   把 VACE 源码拉到本地并进入项目根目录，后续所有命令都在该目录下执行。

   git clone https://github.com/ali-vilab/VACE.git && cd VACE

   复制

2. 2安装 PyTorch

   若本机还没装 PyTorch，按 README 指定版本与 cu124 源安装，CUDA 版本需为 12.4。

   pip install torch==2.5.1 torchvision==0.20.1 --index-url https://download.pytorch.org/whl/cu124

   复制

3. 3安装项目依赖

   安装仓库根目录 requirements.txt 中的推理依赖，建议使用虚拟环境隔离。

   pip install -r requirements.txt

   复制

4. 4安装 Wan2.1 支持

   如果要使用基于 Wan2.1 的 VACE，需要额外安装 wan 包；不使用可跳过。

   pip install wan@git+https://github.com/Wan-Video/Wan2.1

   复制

5. 5安装 LTX-Video 支持

   使用 LTX-Video-0.9 版 VACE 时安装，注意它可能与 Wan 依赖冲突。

   pip install ltx-video@git+https://github.com/Lightricks/LTX-Video@ltx-video-0.9.1 sentencepiece --no-deps

   复制

6. 6下载基础模型

   把所选基础模型放到 <repo-root>/models/，并按下文推荐目录结构组织文件夹。

7. 7安装预处理工具

   需要预处理（深度、边缘、姿态等）时安装 annotator 依赖，并下载 VACE-Annotators 到 models/。

   pip install -r requirements/annotator.txt

   复制

8. 8运行端到端推理

   一条命令串联预处理与推理，输出默认写入 ./results/，示例为 V2V depth 任务。

   python vace/vace_pipeline.py --base wan --task depth --video assets/videos/test.mp4 --prompt 'xxx'

   复制

关键配置

如何确认成功

命令执行完成后，输出视频及中间视频、mask、图片会默认保存在项目根目录的 ./results/ 下，检查该目录即可确认成功。

常见问题

注意事项

• README 未给出显式端口或服务启动方式，本项目以命令行脚本方式运行，不涉及 Web 服务部署。
• 文件下载（基础模型、VACE-Annotators、VACE-Benchmark）需手动进行，README 只给出目标目录。
• 进行 prompt extension 时，编辑任务可能因扩展文本与输入视觉信息不匹配而影响最终效果，需谨慎使用。
• 建议下载 VACE-Benchmark 到 <repo-root>/benchmarks/，与 run_vace_xxx.sh 中的示例路径保持一致。