Hunyuanvideo

🚀 混元視頻（HunyuanVideo）

混元視頻（HunyuanVideo）是一個用於大視頻生成模型訓練的系統框架，它能夠生成高質量的視頻，在視頻生成領域具有卓越的性能，為開源視頻生成模型的發展提供了有力支持。

本倉庫包含用於探索混元視頻（HunyuanVideo）的PyTorch模型定義、預訓練權重以及推理/採樣代碼。你可以在我們的項目頁面上查看更多可視化效果。

HunyuanVideo: A Systematic Framework For Large Video Generation Model Training

✨ 主要特性

統一的圖像和視頻生成架構

混元視頻（HunyuanVideo）引入了Transformer設計，並採用全注意力機制進行統一的圖像和視頻生成。具體而言，我們使用“雙流到單流”的混合模型設計進行視頻生成。在雙流階段，視頻和文本令牌通過多個Transformer塊獨立處理，使每個模態能夠在不干擾的情況下學習自己合適的調製機制。在單流階段，我們將視頻和文本令牌連接起來，並將它們輸入到後續的Transformer塊中，以實現有效的多模態信息融合。這種設計捕捉了視覺和語義信息之間的複雜交互，提高了整體模型性能。

多模態大語言模型（MLLM）文本編碼器

一些先前的文本到視頻模型通常使用預訓練的CLIP和T5 - XXL作為文本編碼器，其中CLIP使用Transformer編碼器，T5使用編碼器 - 解碼器結構。相比之下，我們使用具有僅解碼器結構的預訓練多模態大語言模型（MLLM）作為文本編碼器，這具有以下優點：

1. 與T5相比，經過視覺指令微調的MLLM在特徵空間中具有更好的圖像 - 文本對齊，這減輕了擴散模型中指令遵循的難度。
2. 與CLIP相比，MLLM在圖像細節描述和複雜推理方面表現出更出色的能力。
3. MLLM可以通過遵循用戶提示前的系統指令作為零樣本學習器，幫助文本特徵更加關注關鍵信息。此外，MLLM基於因果注意力，而T5 - XXL使用雙向注意力，這為擴散模型提供了更好的文本指導。因此，我們引入了一個額外的雙向令牌精煉器來增強文本特徵。

3D變分自編碼器（VAE）

混元視頻（HunyuanVideo）使用因果3D卷積（CausalConv3D）訓練了一個3D變分自編碼器（VAE），將像素空間的視頻和圖像壓縮到一個緊湊的潛在空間中。我們分別將視頻長度、空間和通道的壓縮比設置為4、8和16。這可以顯著減少後續擴散Transformer模型的令牌數量，使我們能夠在原始分辨率和幀率下訓練視頻。

提示重寫

為了解決用戶提供提示的語言風格和長度的可變性問題，我們對[混元大模型（Hunyuan - Large）](https://github.com/Tencent/Tencent - Hunyuan - Large)進行微調，作為提示重寫模型，以將原始用戶提示調整為模型偏好的提示。

我們提供兩種重寫模式：普通模式和專家模式，可以使用不同的提示調用。提示信息見此處。普通模式旨在增強視頻生成模型對用戶意圖的理解，便於更準確地解釋提供的指令。專家模式增強了對構圖、照明和相機運動等方面的描述，傾向於生成具有更高視覺質量的視頻。然而，這種強調有時可能會導致一些語義細節的丟失。

提示重寫模型可以使用[混元大模型（Hunyuan - Large）的原始代碼](https://github.com/Tencent/Tencent - Hunyuan - Large)直接部署和推理。我們在[此處](https://huggingface.co/Tencent/HunyuanVideo - PromptRewrite)發佈了提示重寫模型的權重。

📦 安裝指南

克隆倉庫

首先，克隆本倉庫：

git clone https://github.com/tencent/HunyuanVideo
cd HunyuanVideo

Linux安裝指南

我們建議手動安裝時使用CUDA 12.4或11.8版本。Conda的安裝說明見此處。

# 1. 創建conda環境
conda create -n HunyuanVideo python==3.10.9

# 2. 激活環境
conda activate HunyuanVideo

# 3. 使用conda安裝PyTorch和其他依賴項
# 對於CUDA 11.8
conda install pytorch==2.4.0 torchvision==0.19.0 torchaudio==2.4.0 pytorch - cuda=11.8 - c pytorch - c nvidia
# 對於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類型上遇到浮點異常（核心轉儲），可以嘗試以下解決方案：

# 選項1：確保已安裝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/

# 選項2：強制顯式使用CUDA 11.8編譯版本的Pytorch和所有其他包
pip uninstall -r requirements.txt  # 卸載所有包
pip uninstall -y xfuser
pip install torch==2.4.0 --index - url https://download.pytorch.org/whl/cu118
pip install -r requirements.txt
pip install ninja
pip install git+https://github.com/Dao - AILab/flash - attention.git@v2.6.3
pip install xfuser==0.4.0

此外，混元視頻（HunyuanVideo）還提供了預構建的Docker鏡像。使用以下命令拉取並運行Docker鏡像：

# 對於CUDA 12.4（更新以避免浮點異常）
docker pull hunyuanvideo/hunyuanvideo:cuda_12
docker run -itd --gpus all --init --net=host --uts=host --ipc=host --name hunyuanvideo --security - opt=seccomp=unconfined --ulimit=stack=67108864 --ulimit=memlock=-1 --privileged hunyuanvideo/hunyuanvideo:cuda_12

# 對於CUDA 11.8
docker pull hunyuanvideo/hunyuanvideo:cuda_11
docker run -itd --gpus all --init --net=host --uts=host --ipc=host --name hunyuanvideo --security - opt=seccomp=unconfined --ulimit=stack=67108864 --ulimit=memlock=-1 --privileged hunyuanvideo/hunyuanvideo:cuda_11

💻 使用示例

單GPU推理

支持的分辨率設置

我們支持的高度/寬度/幀數設置如下表所示：

使用命令行

cd HunyuanVideo

python3 sample_video.py \
    --video - size 720 1280 \
    --video - length 129 \
    --infer - steps 50 \
    --prompt "A cat walks on the grass, realistic style." \
    --flow - reverse \
    --use - cpu - offload \
    --save - path ./results

運行Gradio服務器

python3 gradio_server.py --flow - reverse

# 手動設置SERVER_NAME和SERVER_PORT
# SERVER_NAME=0.0.0.0 SERVER_PORT=8081 python3 gradio_server.py --flow - reverse

更多配置

我們列出了一些更有用的配置，方便使用：

多GPU並行推理（使用xDiT）

[xDiT](https://github.com/xdit - project/xDiT)是一個用於多GPU集群上擴散Transformer（DiTs）的可擴展推理引擎。它已成功為多種DiTs模型提供了低延遲並行推理解決方案，包括mochi - 1、CogVideoX、Flux.1、SD3等。本倉庫採用了統一序列並行性（USP） API進行混元視頻（HunyuanVideo）模型的並行推理。

使用命令行

例如，使用8個GPU生成視頻，可以使用以下命令：

cd HunyuanVideo

torchrun --nproc_per_node=8 sample_video.py \
    --video - size 1280 720 \
    --video - length 129 \
    --infer - steps 50 \
    --prompt "A cat walks on the grass, realistic style." \
    --flow - reverse \
    --seed 42 \
    --ulysses - degree 8 \
    --ring - degree 1 \
    --save - path ./results

你可以更改--ulysses - degree和--ring - degree來控制並行配置，以獲得最佳性能。支持的並行配置如下表所示：

FP8推理

使用具有FP8量化權重的混元視頻（HunyuanVideo），可以節省約10GB的GPU內存。你可以從Huggingface下載[權重](https://huggingface.co/tencent/HunyuanVideo/blob/main/hunyuan - video - t2v - 720p/transformers/mp_rank_00_model_states_fp8.pt)和[權重縮放](https://huggingface.co/tencent/HunyuanVideo/blob/main/hunyuan - video - t2v - 720p/transformers/mp_rank_00_model_states_fp8_map.pt)。

使用命令行

這裡，你必須顯式指定FP8權重路徑。例如，使用FP8權重生成視頻，可以使用以下命令：

cd HunyuanVideo

DIT_CKPT_PATH={PATH_TO_FP8_WEIGHTS}/{WEIGHT_NAME}_fp8.pt

python3 sample_video.py \
    --dit - weight ${DIT_CKPT_PATH} \
    --video - size 1280 720 \
    --video - length 129 \
    --infer - steps 50 \
    --prompt "A cat walks on the grass, realistic style." \
    --seed 42 \
    --embedded - cfg - scale 6.0 \
    --flow - shift 7.0 \
    --flow - reverse \
    --use - cpu - offload \
    --use - fp8 \
    --save - path ./results

📚 詳細文檔

摘要

我們推出了混元視頻（HunyuanVideo），這是一個新穎的開源視頻基礎模型，在視頻生成方面的性能與領先的閉源模型相當，甚至更優。為了訓練混元視頻（HunyuanVideo）模型，我們採用了幾種關鍵技術進行模型學習，包括數據整理、圖像 - 視頻聯合模型訓練，以及旨在促進大規模模型訓練和推理的高效基礎設施。此外，通過有效的模型架構和數據集擴展策略，我們成功訓練了一個參數超過130億的視頻生成模型，使其成為所有開源模型中規模最大的模型。

我們進行了廣泛的實驗，並實施了一系列有針對性的設計，以確保高視覺質量、運動多樣性、文本 - 視頻對齊和生成穩定性。根據專業人工評估結果，混元視頻（HunyuanVideo）優於之前的最先進模型，包括Runway Gen - 3、Luma 1.6和3個表現出色的中文視頻生成模型。通過發佈基礎模型及其應用的代碼和權重，我們旨在縮小閉源和開源視頻基礎模型之間的差距。這一舉措將使社區中的每個人都能夠嘗試他們的想法，促進一個更加動態和活躍的視頻生成生態系統。

混元視頻（HunyuanVideo）整體架構

混元視頻（HunyuanVideo）在時空壓縮的潛在空間中進行訓練，該空間通過因果3D變分自編碼器（VAE）進行壓縮。文本提示使用大語言模型進行編碼，並用作條件。以高斯噪聲和條件作為輸入，我們的生成模型產生一個輸出潛在表示，然後通過3D變分自編碼器（VAE）解碼器解碼為圖像或視頻。

比較

為了評估混元視頻（HunyuanVideo）的性能，我們從閉源視頻生成模型中選擇了五個強大的基線模型。總共使用了1533個文本提示，一次運行中使用混元視頻（HunyuanVideo）生成了相同數量的視頻樣本。為了進行公平比較，我們只進行了一次推理，避免挑選結果。與基線方法比較時，我們對所有選定模型保持默認設置，確保視頻分辨率一致。根據三個標準評估視頻：文本對齊、運動質量和視覺質量。超過60名專業評估人員進行了評估。值得注意的是，混元視頻（HunyuanVideo）表現出最佳的整體性能，尤其在運動質量方面表現出色。請注意，評估基於混元視頻（HunyuanVideo）的高質量版本，這與當前發佈的快速版本不同。

要求

以下表格顯示了運行混元視頻（HunyuanVideo）模型（批量大小 = 1）生成視頻的要求：

• 需要支持CUDA的NVIDIA GPU。
  • 該模型在單個80G GPU上進行了測試。
  • 最低要求：720px1280px129f分辨率下，最低需要60GB的GPU內存；544px960px129f分辨率下，最低需要45GB的GPU內存。
  • 推薦配置：為了獲得更好的生成質量，建議使用80GB內存的GPU。
• 測試的操作系統：Linux

下載預訓練模型

下載預訓練模型的詳細信息見此處。

🔧 技術細節

新聞動態

• 2025年1月13日：📈 我們發佈了企鵝視頻基準測試（Penguin Video Benchmark）。
• 2024年12月18日：🏃‍♂️ 我們發佈了混元視頻（HunyuanVideo）的[FP8模型權重](https://huggingface.co/tencent/HunyuanVideo/blob/main/hunyuan - video - t2v - 720p/transformers/mp_rank_00_model_states_fp8.pt)，以節省更多的GPU內存。
• 2024年12月17日：🤗 混元視頻（HunyuanVideo）已集成到Diffusers中。
• 2024年12月7日：🚀 我們發佈了由[xDiT](https://github.com/xdit - project/xDiT)支持的混元視頻（HunyuanVideo）並行推理代碼。
• 2024年12月3日：👋 我們發佈了混元視頻（HunyuanVideo）的推理代碼和模型權重。下載

開源計劃

• 混元視頻（文本到視頻模型）
  • [x] 推理
  • [x] 檢查點
  • [x] 多GPU序列並行推理（在更多GPU上實現更快的推理速度）
  • [x] Web演示（Gradio）
  • [x] Diffusers
  • [x] FP8量化權重
  • [x] 企鵝視頻基準測試
  • [x] ComfyUI
• [混元視頻（圖像到視頻模型）](https://github.com/Tencent/HunyuanVideo - I2V)
  • [x] 推理
  • [x] 檢查點

📄 許可證

本項目採用騰訊混元社區許可證（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倉庫的貢獻者，感謝他們的開放研究和探索。此外，我們也感謝騰訊混元多模態團隊在文本編碼器方面提供的幫助。