Hunyuanvideo I2V

🚀 混元視頻圖像轉視頻模型（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倉庫的貢獻者，感謝他們的開放研究和探索。此外，也感謝騰訊混元多模態團隊在文本編碼器方面的幫助。