Hunyuanvideo I2V

🚀 混元ビデオ画像からビデオへの変換モデル（HunyuanVideo - I2V）🌅

このプロジェクトは画像からビデオへの生成フレームワークです。混元ビデオの高度なビデオ生成能力を活用し、画像からビデオへの生成タスクに応用しています。トークン置換技術を採用することで、参照画像情報を効果的に再構築し、ビデオ生成プロセスに統合し、静止画像から高品質なビデオを生成することができます。プロジェクトでは、公式の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 \
    --seed 0 \
    --embedded-cfg-scale 6.0 \
    --use-cpu-offload \
    --save-path ./results

その他の設定

✨ 主な機能

• 画像からビデオへの生成：高度なビデオ生成能力を基に、画像情報をビデオ生成プロセスに効果的に統合し、静止画像から高品質なビデオを生成します。
• マルチモーダル融合：事前学習済みのマルチモーダル大規模言語モデル（MLLM）をテキストエンコーダとして利用し、入力画像の意味内容の理解とマルチモーダル情報の統合能力を強化します。
• カスタマイズ可能な特殊効果：LoRAトレーニングコードを公開しており、ユーザーが特殊効果をカスタマイズし、より面白いビデオ効果を創り出すことをサポートしています。
• 高解像度ビデオ生成：最大720P解像度、最大129フレーム（5秒）のビデオ生成をサポートしています。
• 並列推論：xDiTを採用して多GPU並列推論を実現し、推論速度を向上させます。

📦 インストール

システム要件

HunyuanVideo - I2Vモデル（バッチサイズ = 1）でビデオを生成するための要件は以下の通りです。

• 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）でビデオを生成するための要件は以下の通りです。

• 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}/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を使用します。

サポートされている並列設定は以下の通りです。

異なるGPU数での1280x720（129フレーム、50ステップ）の遅延（秒）は以下の通りです。

📚 ドキュメント

全体アーキテクチャ

混元ビデオの高度なビデオ生成能力を活用し、画像からビデオへの生成タスクに応用しています。トークン置換技術を採用することで、参照画像情報を効果的に再構築し、ビデオ生成プロセスに統合します。

事前学習済みのマルチモーダル大規模言語モデル（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](https://huggingface.co/tencent/HunyuanVideo - I2V)の新しいモデル重みを試してみてください。これにより、最初のフレームの視覚的な一貫性が保証され、より高品質なビデオが生成されます。
• 2025年3月6日：👋 HunyuanVideo - I2Vの推論コードとモデル重みを公開しました。[ダウンロード](https://github.com/Tencent/HunyuanVideo - I2V/blob/main/ckpts/README.md)

🔧 技術詳細

マルチモーダル情報の統合

事前学習済みのマルチモーダル大規模言語モデル（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](https://huggingface.co/stabilityai/stable - diffusion - 3 - medium)、[FLUX](https://github.com/black - forest - labs/flux)、[Llama](https://github.com/meta - llama/llama)、[LLaVA](https://github.com/haotian - liu/LLaVA)、Xtuner、diffusers、HuggingFaceリポジトリの貢献者の皆様に感謝します。彼らのオープンな研究と探求に感謝いたします。また、テキストエンコーダに関する支援を行ってくれた騰訊混元マルチモーダルチームにも感謝いたします。