logo
copilot-demo/HunyuanVideo-I2V-720p
Public
0
0
Login
CodeIssuesPull requestsEventsPackagesInsights
main
HunyuanVideo-I2V-720p/README_zh.md
Xibo Sun<xibosun@tencent.com>
fix: dimension conflict in xDiT
fc9829f2
Raw

English Version

HunyuanVideo-I2V 🌅

   
 
 

👋 加入我们的微信社区和Discord

继我们成功开源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的推理代码和模型权重。下载地址

🎥 演示

I2V 示例

联合创作 @D-aiY 导演 丁一

首帧一致性示例

参考图生成视频
｜
｜

定制化I2V LoRA效果演示

特效类型参考图像生成视频
头发生长
拥抱

🧩 社区贡献

如果您的项目中有开发或使用 HunyuanVideo-I2V，欢迎告知我们。

📑 开源计划

  • HunyuanVideo-I2V（图像到视频模型）
    • 推理代码
    • 模型权重
    • ComfyUI支持
    • LoRA训练脚本
    • 多GPU序列并行推理（提升多卡推理速度）
    • Diffusers集成

目录

HunyuanVideo-I2V 整体架构

基于HunyuanVideo强大的视频生成能力，我们将其扩展至图像到视频生成任务。为此，我们采用首帧Token替换方案，有效重构并融合参考图像信息至视频生成流程中。

由于我们使用预训练的Decoder-Only架构多模态大语言模型（MLLM）作为文本编码器，可用于显著增强模型对输入图像语义内容的理解能力，并实现图像与文本描述信息的深度融合。具体而言，输入图像经MLLM处理后生成语义图像tokens，这些tokens与视频隐空间tokens拼接，实现跨模态的全注意力计算。

我们的系统架构旨在最大化图像与文本模态的协同效应，确保从静态图像生成连贯的视频内容。该集成不仅提升了生成视频的保真度，还增强了模型对复杂多模态输入的解析能力。整体架构如下图所示：

📜 运行要求

下表展示了运行HunyuanVideo-I2V模型（batch size=1）生成视频的硬件要求：

模型分辨率GPU显存峰值
HunyuanVideo-I2V720p60GB
  • 需配备支持CUDA的NVIDIA GPU
    • 测试环境为单卡80G GPU
    • 最低要求: 720p分辨率需至少60GB显存
    • 推荐配置: 建议使用80GB显存GPU以获得更佳生成质量
  • 测试操作系统：Linux

🛠️ 依赖安装

首先克隆仓库：

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. 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。

🔑 单 GPU 推理

类似于 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

更多配置

我们列出了一些常用的配置以方便使用：

参数默认描述
--promptNone用于视频生成的文本提示。
--modelHYVideo-T/2-cfgdistill这里我们使用 HYVideo-T/2 用于 I2V，HYVideo-T/2-cfgdistill 用于 T2V 模式。
--i2v-modeFalse是否开启 I2V 模式。
--i2v-image-path./assets/demo/i2v/imgs/0.png用于视频生成的参考图像。
--i2v-resolution720p生成视频的分辨率。
--i2v-stabilityFalse是否使用稳定模式进行 i2v 推理。
--video-length129生成视频的长度。
--infer-steps50采样步骤的数量。
--flow-shift7.0流匹配调度器的偏移因子。我们建议将--i2v-stability设置为 7，以获得更稳定的视频；将--i2v-stability设置为 17，以获得更动态的视频
--flow-reverseFalse如果反转，从 t=1 学习/采样到 t=0。
--seedNone生成视频的随机种子，如果为 None，则初始化一个随机种子。
--use-cpu-offloadFalse使用 CPU 卸载模型加载以节省更多内存，对于高分辨率视频生成是必要的。
--save-path./results保存生成视频的路径。

🎉自定义 I2V LoRA 效果训练

要求

下表显示了训练 HunyuanVideo-I2V lora 模型（批量大小 = 1）以生成视频的要求：

模型分辨率GPU 峰值内存
HunyuanVideo-I2V360p79GB
  • 需要支持 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_NAMEi2v_lora保存实验结果的路径后缀。
DATA_JSONS_DIR./assets/demo/i2v_lora/train_dataset/processed_data/json_path由 hyvideo/hyvae_extract/start.sh 生成的数据 jsons 目录。
CHIEF_IP127.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-loraNone是否开启 LoRA 模式。
--lora-scale1.0LoRA 模型的融合比例。
--lora-path""LoRA 模型的权重路径。

🚀 使用 xDiT 实现多卡并行推理

xDiT 是一个针对多 GPU 集群的扩展推理引擎，用于扩展 Transformers（DiTs）。 它成功为各种 DiT 模型（包括 mochi-1、CogVideoX、Flux.1、SD3 等）提供了低延迟的并行推理解决方案。该存储库采用了 Unified Sequence Parallelism (USP) API 用于混元视频模型的并行推理。

使用命令行

例如，可用如下命令使用8张GPU卡完成推理

cd HunyuanVideo-I2V

ALLOW_RESIZE_FOR_SP=1 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

GPU 的数量等于 --ulysses-degree 与 --ring-degree 的乘积。您可以更改这些并行配置以获得最佳性能。

xDiT 在潜在空间中根据高度或宽度维度对视频进行分割，具体取决于哪个维度可以被 GPU 数量整除。设置 ALLOW_RESIZE_FOR_SP=1 允许 xDiT 稍微调整输入图像的大小，以使高度或宽度可以被GPU数量整除。

xDiT 并行推理加速如下表所示。

在 8xGPU上生成1280x720 (129 帧 50 步)的时耗 (秒)
1248
1904.08934.09 (2.04x)514.08 (3.70x)337.58 (5.64x)

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

致谢

HunyuanVideo 的开源离不开诸多开源工作，这里我们特别感谢 SD3, FLUX, Llama, LLaVA, Xtuner, diffusers and HuggingFace 的开源工作和探索。另外，我们也感谢腾讯混元多模态团队对 HunyuanVideo 适配多种文本编码器的支持。

© 2025 Tencent, Inc. Supported by Tencent Cloud
About Us
Privacy Policy
Terms of Service
SLA
API
Docs
Showcase
Feedback
35/F,Tencent Building,Kejizhongyi Avenue,Nanshan District,Shenzhen
京ICP备11018762号-111
粤公网安备44030002006058号粤公网安备44030002006058号