模型简介
模型特点
模型能力
使用案例
🚀 混元视频图像转视频模型(HunyuanVideo-I2V)🌅
本项目是一个图像转视频生成框架,基于混元视频(HunyuanVideo)的先进视频生成能力,将其应用拓展到图像转视频生成任务。通过采用令牌替换技术,有效重构并整合参考图像信息到视频生成过程中,实现从静态图像生成高质量视频。项目提供了官方的PyTorch模型定义、预训练权重和推理/采样代码,还发布了LoRA训练代码以实现可定制的特效。
🚀 快速开始
克隆仓库
git clone https://github.com/tencent/HunyuanVideo-I2V
cd HunyuanVideo-I2V
安装依赖
Linux安装指南
推荐使用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/flash-attention.git@v2.6.3
# 6. 安装xDiT以进行并行推理(建议使用torch 2.4.0和flash-attn 2.6.3)
python -m pip install xfuser==0.4.0
下载预训练模型
预训练模型的下载详情请参考此处。
单GPU推理
使用提示
- 使用简洁提示:保持提示简短明了,以有效引导模型生成。
- 包含关键元素:一个结构良好的提示应涵盖主要主题、动作、背景(可选)和相机角度(可选)。
- 避免过于详细的提示:过长或过于详细的提示可能导致视频输出中出现不必要的过渡。
使用命令行
如果你想生成更稳定的视频,可以设置--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 | 此处I2V模式使用HYVideo-T/2,T2V模式使用HYVideo-T/2-cfgdistill |
--i2v-mode |
False | 是否开启i2v模式 |
--i2v-image-path |
./assets/demo/i2v/imgs/0.jpg | 视频生成的参考图像路径 |
--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 | 保存生成视频的路径 |
✨ 主要特性
- 图像转视频生成:基于先进的视频生成能力,将图像信息有效整合到视频生成过程中,实现从静态图像生成高质量视频。
- 多模态融合:利用预训练的多模态大语言模型(MLLM)作为文本编码器,增强模型对输入图像语义内容的理解和多模态信息的整合能力。
- 可定制特效:发布了LoRA训练代码,支持用户定制特殊效果,创造更有趣的视频效果。
- 高分辨率视频生成:支持生成最高720P分辨率、最长129帧(5秒)的视频。
- 并行推理:采用xDiT实现多GPU并行推理,提高推理速度。
📦 安装指南
系统要求
运行HunyuanVideo-I2V模型(批量大小 = 1)生成视频的要求如下:
模型 | 分辨率 | GPU峰值内存 |
---|---|---|
HunyuanVideo-I2V | 720p | 60GB |
- 需要支持CUDA的NVIDIA GPU。
- 模型在单个80G GPU上进行了测试。
- 最低要求:720p分辨率下,最低需要60GB的GPU内存。
- 推荐配置:建议使用80GB内存的GPU以获得更好的生成质量。
- 测试操作系统:Linux
安装步骤
请参考上述快速开始部分的克隆仓库和安装依赖步骤。
💻 使用示例
基础用法
# 单GPU推理示例
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 LoRA效果训练
要求
训练HunyuanVideo-I2V LoRA模型(批量大小 = 1)生成视频的要求如下:
模型 | 分辨率 | GPU峰值内存 |
---|---|---|
HunyuanVideo-I2V | 360p | 79GB |
- 需要支持CUDA的NVIDIA GPU。
- 模型在单个80G GPU上进行了测试。
- 最低要求:360p分辨率下,最低需要79GB的GPU内存。
- 推荐配置:建议使用80GB内存的GPU以获得更好的生成质量。
- 测试操作系统:Linux
- 注意:可以使用360p数据进行训练并直接推理720p视频
环境
pip install -r requirements.txt
训练数据构建
提示描述:触发词直接写在视频字幕中,建议使用短语或短句。
例如,AI头发生长效果(触发词):rapid_hair_growth,视频中人物的头发正在快速生长。 + 原始提示
有了训练视频和提示对后,参考此处进行训练数据构建。
训练
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生成的数据json目录 |
CHIEF_IP |
127.0.0.1 | 机器的主节点IP |
训练完成后,可以在{SAVE_BASE}/log_EXP/*_{EXP_NAME}/checkpoints/global_step{*}/pytorch_lora_kohaya_weights.safetensors
中找到pytorch_lora_kohaya_weights.safetensors
,并在--lora-path
中设置它以进行推理。
推理
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
多GPU并行推理
使用xDiT在多个GPU上进行并行推理。
使用命令行
例如,使用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
来控制并行配置以获得最佳性能。注意,由于xDiT的加速机制对生成视频的大小有要求,需要设置--video-size
。为了防止将原始图像高度/宽度转换为目标高度/宽度后出现黑色填充,可以使用--xdit-adaptive-size
。
支持的并行配置如下:
支持的并行配置(点击展开)
--video-size |
--video-length |
--ulysses-degree x --ring-degree |
--nproc_per_node |
---|---|---|---|
1280 720 or 720 1280 | 129 | 8x1,4x2,2x4,1x8 | 8 |
1280 720 or 720 1280 | 129 | 1x5 | 5 |
1280 720 or 720 1280 | 129 | 4x1,2x2,1x4 | 4 |
1280 720 or 720 1280 | 129 | 3x1,1x3 | 3 |
1280 720 or 720 1280 | 129 | 2x1,1x2 | 2 |
1104 832 or 832 1104 | 129 | 4x1,2x2,1x4 | 4 |
1104 832 or 832 1104 | 129 | 3x1,1x3 | 3 |
1104 832 or 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 or 544 960 | 129 | 6x1,3x2,2x3,1x6 | 6 |
960 544 or 544 960 | 129 | 4x1,2x2,1x4 | 4 |
960 544 or 544 960 | 129 | 3x1,1x3 | 3 |
960 544 or 544 960 | 129 | 1x2,2x1 | 2 |
832 624 or 624 832 | 129 | 4x1,2x2,1x4 | 4 |
624 832 or 624 832 | 129 | 3x1,1x3 | 3 |
832 624 or 624 832 | 129 | 2x1,1x2 | 2 |
720 720 | 129 | 1x5 | 5 |
720 720 | 129 | 3x1,1x3 | 3 |
不同GPU数量下1280x720(129帧,50步)的延迟(秒)如下:
GPU数量 | 延迟(秒) | 加速比 |
---|---|---|
1 | 1904.08 | - |
2 | 934.09 | 2.04x |
4 | 514.08 | 3.70x |
8 | 337.58 | 5.64x |
📚 详细文档
整体架构
利用混元视频的先进视频生成能力,将其应用拓展到图像转视频生成任务。采用令牌替换技术,有效重构并整合参考图像信息到视频生成过程中。
使用预训练的多模态大语言模型(MLLM)作为文本编码器,增强模型对输入图像语义内容的理解和多模态信息的整合能力。具体来说,输入图像由MLLM处理生成语义图像令牌,这些令牌与视频潜在令牌连接,实现对组合数据的全面全注意力计算。
系统的整体架构旨在最大化图像和文本模态之间的协同作用,确保从静态图像生成稳健且连贯的视频内容。这种整合不仅提高了生成视频的保真度,还增强了模型对复杂多模态输入的解释和利用能力。整体架构如下:
开源计划
- HunyuanVideo-I2V(图像转视频模型)
- [x] 推理
- [x] 检查点
- [x] ComfyUI
- [x] Lora训练脚本
- [x] 多GPU序列并行推理(在更多GPU上实现更快的推理速度)
- [ ] Diffusers
新闻动态
- 2025年3月13日:🚀 发布由xDiT支持的HunyuanVideo-I2V并行推理代码。
- 2025年3月7日:🔥 修复了开源版本中导致ID更改的错误。请尝试使用HunyuanVideo-I2V的新模型权重,以确保第一帧的视觉一致性并生成更高质量的视频。
- 2025年3月6日:👋 发布HunyuanVideo-I2V的推理代码和模型权重。下载。
🔧 技术细节
多模态信息整合
使用预训练的多模态大语言模型(MLLM)作为文本编码器,将输入图像和相关文本信息进行整合。输入图像由MLLM处理生成语义图像令牌,这些令牌与视频潜在令牌连接,实现对组合数据的全面全注意力计算。
令牌替换技术
采用令牌替换技术,有效重构并整合参考图像信息到视频生成过程中。通过将图像信息与视频生成过程相结合,提高生成视频的质量和连贯性。
并行推理
采用xDiT实现多GPU并行推理,提高推理速度。通过统一序列并行性(USP)API,实现HunyuanVideo-I2V模型的并行推理。
📄 许可证
本项目采用tencent-hunyuan-community许可证。
🔗 BibTeX
如果你发现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},
}
致谢
感谢SD3、FLUX、Llama、LLaVA、Xtuner、diffusers和HuggingFace仓库的贡献者,感谢他们的开放研究和探索。此外,也感谢腾讯混元多模态团队在文本编码器方面的帮助。

