Phantom：通过跨模态对齐实现主体一致性视频生成

Phantom：通过跨模态对齐实现主体一致性视频生成
刘立杰 ^* , 马天翔 ^* , 李炳川 ^{* †}, 陈卓伟 ^* , 刘嘉伟, 李根, 周思宇, 何茜, 吴兴龙
^* 同等贡献, ^† 项目负责人
字节跳动智能创作团队

🔥 最新消息！

• 2025年9月10日：🔥 HuMo 来了！我们发布了一款以人为本的视频生成模型，支持文本、参考图像和音频等多种输入方式。HuMo 具有强大的文本指令遵循能力、稳定的主体保持以及同步的音频驱动动作。该模型已开源，欢迎大家使用！
• 2025年6月26日：🎉 恭喜！Phantom 已被 ICCV 2025 接收！
• 2025年6月24日：📊 我们发布了 Phantom-Data，这是首个通用的大规模跨配对数据集，提出了一种用于主体一致性视频生成任务的核心跨配对数据构建方法。
• 2025年5月27日：🎉 我们发布了 Phantom-Wan-14B 模型，这是一款更强大的主体到视频生成模型。
• 2025年4月23日：😊 感谢 ComfyUI-WanVideoWrapper 将 ComfyUI 适配至 Phantom-Wan-1.3B（5月27日，14B 模型也已完成适配）。欢迎大家使用！
• 2025年4月21日：👋 Phantom-Wan 即将到来！我们将 Phantom 框架适配到了 Wan2.1 视频生成模型中。推理代码和检查点现已发布。
• 2025年4月10日：我们更新了 Phantom 论文的完整版本，其中包含了对模型架构和数据流水线更为详细的描述。
• 2025年2月16日：我们提出了一种新颖的主体一致性视频生成模型——Phantom，并公开发布了报告。更多视频演示请访问项目页面。

📑 待办事项

• Phantom-Wan-1.3B 的推理代码和检查点
• Phantom-Wan-14B 的检查点
• Phantom-Wan-14B Pro 的检查点
• 开源 Phantom-Data 数据集
• Phantom-Wan 的训练代码

📖 概述

Phantom 是一个基于现有文本到视频和图像到视频架构构建的统一视频生成框架，适用于单主体和多主体参考场景。它通过重新设计联合文本-图像注入模型，利用文本-图像-视频三元组数据实现跨模态对齐。此外，它在人像生成中强调主体一致性，同时提升了身份保留型视频生成的效果。

⚡️ 快速入门

安装

克隆仓库：

git clone https://github.com/Phantom-video/Phantom.git
cd Phantom

安装依赖：

# 确保 torch >= 2.4.0
pip install -r requirements.txt

模型下载

模型	下载链接	备注
Phantom-Wan-1.3B	🤗 Huggingface	支持 480P 和 720P
Phantom-Wan-14B	🤗 Huggingface	支持 480P 和 720P

首先需要下载 Wan2.1 的 1.3B 原始模型，因为我们的 Phantom-Wan 模型依赖于 Wan2.1 的 VAE 和文本编码器模型。使用 huggingface-cli 下载 Wan2.1-1.3B：

pip install "huggingface_hub[cli]"
huggingface-cli download Wan-AI/Wan2.1-T2V-1.3B --local-dir ./Wan2.1-T2V-1.3B

然后下载 Phantom-Wan-1.3B 和 Phantom-Wan-14B 模型：

huggingface-cli download bytedance-research/Phantom --local-dir ./Phantom-Wan-Models

或者，您也可以手动下载所需模型，并将其放置在 Phantom-Wan-Models 文件夹中。

运行主体到视频生成

Phantom-Wan-1.3B

• 单GPU推理

python generate.py --task s2v-1.3B --size 832*480 --ckpt_dir ./Wan2.1-T2V-1.3B --phantom_ckpt ./Phantom-Wan-Models/Phantom-Wan-1.3B.pth  --ref_image "https://oss.gittoolsai.com/images/Phantom-video_Phantom_readme_86c99e8bc9e4.png,https://oss.gittoolsai.com/images/Phantom-video_Phantom_readme_9796a5ded4e6.png" --prompt "暖阳漫过草地，扎着双马尾、头戴绿色蝴蝶结、身穿浅绿色连衣裙的小女孩蹲在盛开的雏菊旁。她身旁一只棕白相间的狗狗吐着舌头，毛茸茸尾巴欢快摇晃。小女孩笑着举起黄红配色、带有蓝色按钮的玩具相机，将和狗狗的欢乐瞬间定格。" --base_seed 42

• 使用FSDP + xDiT USP的多GPU推理

pip install "xfuser>=0.4.1"
torchrun --nproc_per_node=8 generate.py --task s2v-1.3B --size 832*480 --ckpt_dir ./Wan2.1-T2V-1.3B --phantom_ckpt ./Phantom-Wan-Models/Phantom-Wan-1.3B.pth  --ref_image "https://oss.gittoolsai.com/images/Phantom-video_Phantom_readme_316664b1f2fd.png,https://oss.gittoolsai.com/images/Phantom-video_Phantom_readme_8bde9f1bd08c.png" --dit_fsdp --t5_fsdp --ulysses_size 4 --ring_size 2 --prompt "夕阳下，一位有着小麦色肌肤、留着乌黑长发的女人穿上有着大朵立体花朵装饰、肩袖处带有飘逸纱带的红色纱裙，漫步在金色的海滩上，海风轻拂她的长发，画面唯美动人。" --base_seed 42

💡注意：

• 更改--ref_image可以实现单参考主体到视频生成或多参考主体到视频生成。参考图片的数量应不超过4张。
• 为了获得最佳生成效果，建议在编写--prompt时尽可能准确地描述参考图片的视觉内容。例如，“https://oss.gittoolsai.com/images/Phantom-video_Phantom_readme_86c99e8bc9e4.png”可以描述为“一个黄红相间、带有蓝色按钮的玩具相机”。
• 当生成的视频不理想时，最直接的解决方法是尝试更改--base_seed并修改--prompt中的描述。

更多推理示例，请参阅“infer.sh”。您将得到以下生成结果：

参考图片	生成视频（480P）

Phantom-Wan-14B

• 单GPU推理

python generate.py --task s2v-14B --size 832*480 --frame_num 121 --sample_fps 24 --ckpt_dir ./Wan2.1-T2V-1.3B --phantom_ckpt ./Phantom-Wan-Models --ref_image "https://oss.gittoolsai.com/images/Phantom-video_Phantom_readme_a0a85c5e1127.png,https://oss.gittoolsai.com/images/Phantom-video_Phantom_readme_de825ecbb687.png" --prompt "扎着双丸子头，身着红黑配色并带有火焰纹饰服饰，颈戴金项圈、臂缠金护腕的哪吒，和有着一头淡蓝色头发，额间有蓝色印记，身着一袭白色长袍的敖丙，并肩坐在教室的座位上，他们专注地讨论着书本内容。背景为柔和的灯光和窗外微风拂过的树叶，营造出安静又充满活力的学习氛围。"

• 使用FSDP + xDiT USP的多GPU推理

pip install "xfuser>=0.4.1"
torchrun --nproc_per_node=8 generate.py --task s2v-14B --size 832*480 --frame_num 121 --sample_fps 24 --ckpt_dir ./Wan2.1-T2V-1.3B --phantom_ckpt ./Phantom-Wan-Models  --ref_image "https://oss.gittoolsai.com/images/Phantom-video_Phantom_readme_7f859ebddbd3.png,https://oss.gittoolsai.com/images/Phantom-video_Phantom_readme_158618635290.png,https://oss.gittoolsai.com/images/Phantom-video_Phantom_readme_feb8de187b11.png" --dit_fsdp --t5_fsdp --ulysses_size 8 --ring_size 1 --prompt "一位戴着黄色帽子、身穿黄色上衣配棕色背带的卡通老爷爷，在装饰有粉色和蓝色桌椅、悬挂着彩色吊灯且摆满彩色圆球装饰的清新卡通风格咖啡馆里，端起一只蓝色且冒着热气的咖啡杯，画面风格卡通、清新。"

💡注意：

• 目前发布的Phantom-Wan-14B模型是在480P数据上训练的，但也可以用于生成720P及更高分辨率的视频，尽管效果可能不太稳定。我们计划在未来发布一个在720P数据上进一步训练的版本。
• Phantom-Wan-14B模型是在24fps数据上训练的，但它也可以生成16fps的视频，类似于原版的Wan2.1。不过，画质可能会略有下降。
• 建议生成横屏视频，因为相比竖屏视频，横屏视频通常能产生更稳定的效果。

更多推理示例，请参阅“infer.sh”。您将得到以下生成结果：

参考图片	生成视频（720P）

GIF视频已压缩。

致谢

我们谨向 SEED 团队表示诚挚的感谢，感谢他们的支持。特别感谢 Lu Jiang、Haoyuan Guo、Zhibei Ma 和 Sen Wang 在模型和数据方面提供的帮助。此外，我们也非常感激 Siying Chen、Qingyang Li 和 Wei Han 在评估工作中的协助。

⭐ 引用

如果 Phantom 对您有所帮助，请为本仓库点赞（⭐）。

如果您认为本项目对您的研究有帮助，请考虑引用我们的论文：paper。

BibTeX

@article{liu2025phantom,
  title={Phantom: 基于跨模态对齐的主体一致性视频生成},
  author={Liu, Lijie and Ma, Tianxiang and Li, Bingchuan and Chen, Zhuowei and Liu, Jiawei and Li, Gen and Zhou, Siyu and He, Qian and Wu, Xinglong},
  journal={arXiv 预印本 arXiv:2502.11079},
  year={2025}
}

📧 联系方式

如果您对本开源项目有任何意见或疑问，请新建一个 issue，或联系 Tianxiang Ma。

Phantom 快速上手指南

Phantom 是一个基于跨模态对齐的主体一致性视频生成框架，支持单主体或多主体参考图像生成视频。本指南将帮助您快速在本地部署并运行 Phantom-Wan 模型。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统: Linux (推荐 Ubuntu 20.04+)
• Python: 3.8 或更高版本
• PyTorch: 版本需 >= 2.4.0
• GPU: 推荐使用 NVIDIA GPU，显存建议 16GB 以上（1.3B 模型），多卡环境可运行 14B 模型。
• 网络: 需要能够访问 Hugging Face 下载模型权重（如访问受限，请配置代理或使用镜像站）。

安装步骤

1. 克隆代码仓库

git clone https://github.com/Phantom-video/Phantom.git
cd Phantom

2. 安装依赖

确保已安装符合要求的 PyTorch 版本，然后安装项目依赖：

pip install -r requirements.txt

提示: 如果需要加速下载，可在 pip 命令后添加国内源，例如：-i https://pypi.tuna.tsinghua.edu.cn/simple

3. 下载模型权重

Phantom 依赖 Wan2.1 的基础组件（VAE 和 Text Encoder）以及 Phantom 自身的微调权重。

第一步：下载 Wan2.1-1.3B 基础模型

pip install "huggingface_hub[cli]"
huggingface-cli download Wan-AI/Wan2.1-T2V-1.3B --local-dir ./Wan2.1-T2V-1.3B

第二步：下载 Phantom-Wan 模型权重 支持 1.3B 和 14B 两个版本，按需下载：

huggingface-cli download bytedance-research/Phantom --local-dir ./Phantom-Wan-Models

注：若网络受限，可手动从 Hugging Face 下载文件并放入 ./Phantom-Wan-Models 目录。

基本使用

以下示例展示如何使用 Phantom-Wan-1.3B 模型进行单卡推理，实现“图生视频”（Subject-to-Video）。

单主体/多主体视频生成示例

该命令将读取参考图片，并根据提示词生成一段 480P 的视频。

python generate.py \
  --task s2v-1.3B \
  --size 832*480 \
  --ckpt_dir ./Wan2.1-T2V-1.3B \
  --phantom_ckpt ./Phantom-Wan-Models/Phantom-Wan-1.3B.pth \
  --ref_image "examples/ref1.png,examples/ref2.png" \
  --prompt "暖阳漫过草地，扎着双马尾、头戴绿色蝴蝶结、身穿浅绿色连衣裙的小女孩蹲在盛开的雏菊旁。她身旁一只棕白相间的狗狗吐着舌头，毛茸茸尾巴欢快摇晃。小女孩笑着举起黄红配色、带有蓝色按钮的玩具相机，将和狗狗的欢乐瞬间定格。" \
  --base_seed 42

参数说明与技巧

• --ref_image: 支持传入单张或多张参考图路径（用逗号分隔），数量建议在 4 张以内。
• --prompt: 为了获得最佳效果，请尽可能详细地描述参考图中的视觉内容（如颜色、物体细节、人物特征等）。
• --base_seed: 如果生成结果不理想，尝试修改此随机种子值或调整提示词描述。
• 多卡加速: 如需使用多显卡运行，可安装 xfuser (pip install "xfuser>=0.4.1") 并使用 torchrun 启动（参考官方 README 中的 FSDP 示例）。

生成完成后，视频文件将保存在输出目录中。更多用例请参考项目根目录下的 infer.sh 脚本。