&color=red)
继我们成功开源HunyuanVideo后，我们很高兴推出HunyuanVideo-I2V，一个新的图像到视频生成框架，加速开源社区的探索！
本仓库包含官方PyTorch模型定义、预训练权重及推理/采样代码。更多可视化效果请访问项目主页。同时，我们发布了LoRA训练代码，用于定制化特效生成，可创建更有趣的视频效果。
HunyuanVideo: A Systematic Framework For Large Video Generation Model
- 2025年03月13日: 🚀 开源 HunyuanVideo-I2V 多卡并行推理代码，由xDiT提供。
- 2025年03月11日: 🎉 在修复bug后我们更新了lora的训练和推理代码。
- 2025年03月07日: 🔥 我们已经修复了开源版本中导致ID变化的bug，请尝试HunyuanVideo-I2V新的模型权重，以确保首帧完全视觉一致性，并制作更高质量的视频。
- 2025年03月06日: 👋 发布HunyuanVideo-I2V的推理代码和模型权重。下载地址
3.5.2.mp4
联合创作 @D-aiY 导演 丁一
| 参考图 | 生成视频 |
|---|---|
 |
1019.mp4 |
｜  |
1-4.mp4 |
｜  |
demo_2.mp4 |
| 特效类型 | 参考图像 | 生成视频 |
|---|---|---|
| 头发生长 |  |
hair_growth.mp4 |
| 拥抱 |  |
embrace.mp4 |
如果您的项目中有开发或使用 HunyuanVideo-I2V，欢迎告知我们。
- ComfyUI (支持FP8推理、V2V和IP2V生成): ComfyUI-HunyuanVideoWrapper by Kijai
- HunyuanVideoGP (针对低性能GPU的版本): HunyuanVideoGP by DeepBeepMeep
- xDiT 兼容性改进: 兼容性改进 by pftq
- HunyuanVideo-I2V（图像到视频模型）
- 推理代码
- 模型权重
- ComfyUI支持
- LoRA训练脚本
- 多GPU序列并行推理（提升多卡推理速度）
- Diffusers集成
基于HunyuanVideo强大的视频生成能力，我们将其扩展至图像到视频生成任务。为此，我们采用首帧Token替换方案，有效重构并融合参考图像信息至视频生成流程中。
由于我们使用预训练的Decoder-Only架构多模态大语言模型（MLLM）作为文本编码器，可用于显著增强模型对输入图像语义内容的理解能力，并实现图像与文本描述信息的深度融合。具体而言，输入图像经MLLM处理后生成语义图像tokens，这些tokens与视频隐空间tokens拼接，实现跨模态的全注意力计算。
我们的系统架构旨在最大化图像与文本模态的协同效应，确保从静态图像生成连贯的视频内容。该集成不仅提升了生成视频的保真度，还增强了模型对复杂多模态输入的解析能力。整体架构如下图所示：
下表展示了运行HunyuanVideo-I2V模型（batch size=1）生成视频的硬件要求：
| 模型 | 分辨率 | GPU显存峰值 |
|---|---|---|
| HunyuanVideo-I2V | 720p | 60GB |
- 需配备支持CUDA的NVIDIA GPU
- 测试环境为单卡80G GPU
- 最低要求: 720p分辨率需至少60GB显存
- 推荐配置: 建议使用80GB显存GPU以获得更佳生成质量
- 测试操作系统：Linux
首先克隆仓库：
git clone https://github.com/tencent/HunyuanVideo-I2V
cd HunyuanVideo-I2V我们推荐使用 CUDA 12.4 或 11.8 的版本。
Conda 的安装指南可以参考这里。
# 1. 创建conda环境
conda create -n HunyuanVideo-I2V python==3.11.9
# 2. 激活环境
conda activate HunyuanVideo-I2V
# 3. 通过conda安装PyTorch等依赖
# CUDA 12.4版本
conda install pytorch==2.4.0 torchvision==0.19.0 torchaudio==2.4.0 pytorch-cuda=12.4 -c pytorch -c nvidia
# 4. 安装pip依赖
python -m pip install -r requirements.txt
# 5. 安装flash attention v2加速（需CUDA 11.8及以上）
python -m pip install ninja
python -m pip install git+https://github.com/Dao-AILab/[email protected]
# 6. Install xDiT for parallel inference (It is recommended to use torch 2.4.0 and flash-attn 2.6.3)
python -m pip install xfuser==0.4.0如果在特定 GPU 型号上遭遇 float point exception(core dump) 问题，可尝试以下方案修复：
# 确保已安装CUDA 12.4、CUBLAS>=12.4.5.8和CUDNN>=9.00（或直接使用我们的CUDA 12 docker镜像）
pip install nvidia-cublas-cu12==12.4.5.8
export LD_LIBRARY_PATH=/opt/conda/lib/python3.8/site-packages/nvidia/cublas/lib/另外，我们提供了一个预构建的 Docker 镜像，可以使用如下命令进行拉取和运行。
# CUDA 12.4镜像（避免浮点异常）
docker pull hunyuanvideo/hunyuanvideo-i2v:cuda12
docker run -itd --gpus all --init --net=host --uts=host --ipc=host --name hunyuanvideo-i2v --security-opt=seccomp=unconfined --ulimit=stack=67108864 --ulimit=memlock=-1 --privileged hunyuanvideo/hunyuanvideo-i2v:cuda12下载预训练模型的详细信息请参见 here。
类似于 HunyuanVideo，HunyuanVideo-I2V 支持高分辨率视频生成，分辨率最高可达 720P，视频长度最高可达 129 帧（5 秒）。
- 使用简短的提示：为了有效地引导模型的生成，请保持提示简短且直截了当。
- 包含关键元素：一个结构良好的提示应包括：
- 主体：指定视频的主要焦点。
- 动作：描述正在发生的运动或活动。
- 背景（可选）：设置视频的场景。
- 镜头（可选）：指示视角或视点。
- 避免过于详细的提示：冗长或高度详细的提示可能会导致视频输出中出现不必要的转场。
如果想生成更稳定的视频，可以设置--i2v-stability和--flow-shift 7.0。执行命令如下
cd HunyuanVideo-I2V
python3 sample_image2video.py \
--model HYVideo-T/2 \
--prompt "An Asian man with short hair in black tactical uniform and white clothes waves a firework stick." \
--i2v-mode \
--i2v-image-path ./assets/demo/i2v/imgs/0.jpg \
--i2v-resolution 720p \
--i2v-stability \
--infer-steps 50 \
--video-length 129 \
--flow-reverse \
--flow-shift 7.0 \
--seed 0 \
--embedded-cfg-scale 6.0 \
--use-cpu-offload \
--save-path ./results如果想要生成更高动态的视频，可以取消设置--i2v-stability和--flow-shift 17.0。执行命令如下
cd HunyuanVideo-I2V
python3 sample_image2video.py \
--model HYVideo-T/2 \
--prompt "An Asian man with short hair in black tactical uniform and white clothes waves a firework stick." \
--i2v-mode \
--i2v-image-path ./assets/demo/i2v/imgs/0.jpg \
--i2v-resolution 720p \
--infer-steps 50 \
--video-length 129 \
--flow-reverse \
--flow-shift 17.0 \
--embedded-cfg-scale 6.0 \
--seed 0 \
--use-cpu-offload \
--save-path ./results我们列出了一些常用的配置以方便使用：
| 参数 | 默认 | 描述 |
|---|---|---|
--prompt |
None | 用于视频生成的文本提示。 |
--model |
HYVideo-T/2-cfgdistill | 这里我们使用 HYVideo-T/2 用于 I2V，HYVideo-T/2-cfgdistill 用于 T2V 模式。 |
--i2v-mode |
False | 是否开启 I2V 模式。 |
--i2v-image-path |
./assets/demo/i2v/imgs/0.png | 用于视频生成的参考图像。 |
--i2v-resolution |
720p | 生成视频的分辨率。 |
--i2v-stability |
False | 是否使用稳定模式进行 i2v 推理。 |
--video-length |
129 | 生成视频的长度。 |
--infer-steps |
50 | 采样步骤的数量。 |
--flow-shift |
7.0 | 流匹配调度器的偏移因子。我们建议将--i2v-stability设置为 7，以获得更稳定的视频；将--i2v-stability设置为 17，以获得更动态的视频 |
--flow-reverse |
False | 如果反转，从 t=1 学习/采样到 t=0。 |
--seed |
None | 生成视频的随机种子，如果为 None，则初始化一个随机种子。 |
--use-cpu-offload |
False | 使用 CPU 卸载模型加载以节省更多内存，对于高分辨率视频生成是必要的。 |
--save-path |
./results | 保存生成视频的路径。 |
下表显示了训练 HunyuanVideo-I2V lora 模型（批量大小 = 1）以生成视频的要求：
| 模型 | 分辨率 | GPU 峰值内存 |
|---|---|---|
| HunyuanVideo-I2V | 360p | 79GB |
- 需要支持 CUDA 的 NVIDIA GPU。
- 该模型在单个 80G GPU 上进行了测试。
- 最低要求: 生成 360p 视频所需的最小 GPU 内存为 79GB。
- 推荐: 建议使用 80GB 内存的 GPU 以获得更好的生成质量。
- 测试操作系统: Linux
- 注意: 您可以使用 360p 数据进行训练，并直接推理 720p 视频
pip install -r requirements.txt
提示描述：触发词直接写在视频说明中。建议使用短语或简短句子。
例如，AI 头发生长效果（触发词）：rapid_hair_growth, The hair of the characters in the video is growing rapidly. + 原始提示
准备好训练视频和提示对后，参考 这里 进行训练数据构建。
cd HunyuanVideo-I2V
sh scripts/run_train_image2video_lora.sh
我们列出了一些训练特定配置以方便使用：
| 参数 | 默认 | 描述 |
|---|---|---|
SAVE_BASE |
. | 保存实验结果的根路径。 |
EXP_NAME |
i2v_lora | 保存实验结果的路径后缀。 |
DATA_JSONS_DIR |
./assets/demo/i2v_lora/train_dataset/processed_data/json_path | 由 hyvideo/hyvae_extract/start.sh 生成的数据 jsons 目录。 |
CHIEF_IP |
127.0.0.1 | 主节点 IP 地址。 |
cd HunyuanVideo-I2V
python3 sample_image2video.py \
--model HYVideo-T/2 \
--prompt "Two people hugged tightly, In the video, two people are standing apart from each other. They then move closer to each other and begin to hug tightly. The hug is very affectionate, with the two people holding each other tightly and looking into each other's eyes. The interaction is very emotional and heartwarming, with the two people expressing their love and affection for each other." \
--i2v-mode \
--i2v-image-path ./assets/demo/i2v_lora/imgs/embrace.png \
--i2v-resolution 720p \
--i2v-stability \
--infer-steps 50 \
--video-length 129 \
--flow-reverse \
--flow-shift 5.0 \
--embedded-cfg-scale 6.0 \
--seed 0 \
--use-cpu-offload \
--save-path ./results \
--use-lora \
--lora-scale 1.0 \
--lora-path ./ckpts/hunyuan-video-i2v-720p/lora/embrace_kohaya_weights.safetensors我们列出了一些 LoRA 特定配置以方便使用：
| 参数 | 默认 | 描述 |
|---|---|---|
--use-lora |
None | 是否开启 LoRA 模式。 |
--lora-scale |
1.0 | LoRA 模型的融合比例。 |
--lora-path |
"" | LoRA 模型的权重路径。 |
xDiT 是一个针对多 GPU 集群的扩展推理引擎，用于扩展 Transformers（DiTs）。 它成功为各种 DiT 模型（包括 mochi-1、CogVideoX、Flux.1、SD3 等）提供了低延迟的并行推理解决方案。该存储库采用了 Unified Sequence Parallelism (USP) API 用于混元视频模型的并行推理。
例如，可用如下命令使用8张GPU卡完成推理
cd HunyuanVideo-I2V
torchrun --nproc_per_node=8 sample_image2video.py \
--model HYVideo-T/2 \
--prompt "An Asian man with short hair in black tactical uniform and white clothes waves a firework stick." \
--i2v-mode \
--i2v-image-path ./assets/demo/i2v/imgs/0.jpg \
--i2v-resolution 720p \
--i2v-stability \
--infer-steps 50 \
--video-length 129 \
--flow-reverse \
--flow-shift 7.0 \
--seed 0 \
--embedded-cfg-scale 6.0 \
--save-path ./results \
--ulysses-degree 8 \
--ring-degree 1 \
--video-size 1280 720 \
--xdit-adaptive-size可以配置--ulysses-degree和--ring-degree来控制并行配置，
注意，你需要设置 --video-size，因为 xDiT 的加速机制对要生成的视频的长宽有要求。
为了防止将原始图像高度/宽度转换为目标高度/宽度后出现黑色填充，你可以使用 --xdit-adaptive-size。
具体的可选参数如下。
支持的并行配置 (点击查看详情)
| --video-size | --video-length | --ulysses-degree x --ring-degree | --nproc_per_node |
|---|---|---|---|
| 1280 720 或 720 1280 | 129 | 8x1,4x2,2x4,1x8 | 8 |
| 1280 720 或 720 1280 | 129 | 1x5 | 5 |
| 1280 720 或 720 1280 | 129 | 4x1,2x2,1x4 | 4 |
| 1280 720 或 720 1280 | 129 | 3x1,1x3 | 3 |
| 1280 720 或 720 1280 | 129 | 2x1,1x2 | 2 |
| 1104 832 或 832 1104 | 129 | 4x1,2x2,1x4 | 4 |
| 1104 832 或 832 1104 | 129 | 3x1,1x3 | 3 |
| 1104 832 或 832 1104 | 129 | 2x1,1x2 | 2 |
| 960 960 | 129 | 6x1,3x2,2x3,1x6 | 6 |
| 960 960 | 129 | 4x1,2x2,1x4 | 4 |
| 960 960 | 129 | 3x1,1x3 | 3 |
| 960 960 | 129 | 1x2,2x1 | 2 |
| 960 544 或 544 960 | 129 | 6x1,3x2,2x3,1x6 | 6 |
| 960 544 或 544 960 | 129 | 4x1,2x2,1x4 | 4 |
| 960 544 或 544 960 | 129 | 3x1,1x3 | 3 |
| 960 544 或 544 960 | 129 | 1x2,2x1 | 2 |
| 832 624 或 624 832 | 129 | 4x1,2x2,1x4 | 4 |
| 624 832 或 624 832 | 129 | 3x1,1x3 | 3 |
| 832 624 或 624 832 | 129 | 2x1,1x2 | 2 |
| 720 720 | 129 | 1x5 | 5 |
| 720 720 | 129 | 3x1,1x3 | 3 |
| 在 8xGPU上生成1280x720 (129 帧 50 步)的时耗 (秒) | |||
|---|---|---|---|
| 1 | 2 | 4 | 8 |
| 1904.08 | 934.09 (2.04x) | 514.08 (3.70x) | 337.58 (5.64x) |
如果您发现 HunyuanVideo 对您的研究和应用有所帮助，请使用以下 BibTeX 引用：
@misc{kong2024hunyuanvideo,
title={HunyuanVideo: A Systematic Framework For Large Video Generative Models},
author={Weijie Kong, Qi Tian, Zijian Zhang, Rox Min, Zuozhuo Dai, Jin Zhou, Jiangfeng Xiong, Xin Li, Bo Wu, Jianwei Zhang, Kathrina Wu, Qin Lin, Aladdin Wang, Andong Wang, Changlin Li, Duojun Huang, Fang Yang, Hao Tan, Hongmei Wang, Jacob Song, Jiawang Bai, Jianbing Wu, Jinbao Xue, Joey Wang, Junkun Yuan, Kai Wang, Mengyang Liu, Pengyu Li, Shuai Li, Weiyan Wang, Wenqing Yu, Xinchi Deng, Yang Li, Yanxin Long, Yi Chen, Yutao Cui, Yuanbo Peng, Zhentao Yu, Zhiyu He, Zhiyong Xu, Zixiang Zhou, Zunnan Xu, Yangyu Tao, Qinglin Lu, Songtao Liu, Dax Zhou, Hongfa Wang, Yong Yang, Di Wang, Yuhong Liu, and Jie Jiang, along with Caesar Zhong},
year={2024},
archivePrefix={arXiv preprint arXiv:2412.03603},
primaryClass={cs.CV},
url={https://arxiv.org/abs/2412.03603},
}HunyuanVideo 的开源离不开诸多开源工作，这里我们特别感谢 SD3, FLUX, Llama, LLaVA, Xtuner, diffusers and HuggingFace 的开源工作和探索。另外，我们也感谢腾讯混元多模态团队对 HunyuanVideo 适配多种文本编码器的支持。