Public

Code Issues Pull requests Events Packages Insights

main

HunyuanCustom/README_zh.md

天宇

docs: 更新首页文档，增加 AI 翻译的中文文档

314c7681

PreviewCode viewBlame

Raw

HunyuanCustom 🌅

HunyuanCustom: 一种基于多模态驱动的定制化视频生成架构

🔥🔥🔥 新闻!!

2025年5月8日: 👋 我们发布了HunyuanCustom的推理代码和模型权重。下载。

📑 开源计划

HunyuanCustom
- 单主体视频定制化
  - 推理
  - 检查点
  - ComfyUI
- 音频驱动的视频定制化
- 视频驱动的视频定制化
- 多主体视频定制化

摘要

定制化视频生成旨在在灵活的用户定义条件下生成特定主体的视频，但现有方法通常难以保持身份一致性并受限于有限的输入模态。在本文中，我们提出了HunyuanCustom，一个多模态定制化视频生成框架，强调主体一致性，同时支持图像、音频、视频和文本条件。基于HunyuanVideo，我们的模型首先通过引入基于LLaVA的文本-图像融合模块来增强多模态理解，并通过利用时间连接来增强跨帧身份特征的图像ID增强模块，解决了图像-文本条件生成任务。为了实现音频和视频条件生成，我们进一步提出了特定模态的条件注入机制：通过空间交叉注意力实现层次对齐的AudioNet模块，以及通过基于分块的特征对齐网络集成潜在压缩条件视频的视频驱动注入模块。在单主体和多主体场景的广泛实验表明，HunyuanCustom在ID一致性、真实性和文本-视频对齐方面显著优于最先进的开源和闭源方法。此外，我们验证了它在下游任务中的鲁棒性，包括音频和视频驱动的定制化视频生成。我们的结果突显了多模态条件和身份保持策略在推进可控视频生成方面的有效性。

HunyuanCustom整体架构

我们提出了HunyuanCustom，一个以主体一致性为中心的多模态、条件化和可控生成模型，建立在混元视频生成框架之上。它能够生成以文本、图像、音频和视频输入为条件的主体一致性视频。

🎉 HunyuanCustom关键特性

多模态视频定制化

HunyuanCustom支持文本、图像、音频和视频形式的输入。具体来说，它可以处理单个或多个图像输入，以实现一个或多个主体的定制化视频生成。此外，它可以整合额外的音频输入，驱动主体说出相应的音频内容。最后，HunyuanCustom支持视频输入，允许用给定图像中的主体替换视频中指定的对象。

多种应用场景

借助HunyuanCustom的多模态能力，可以完成众多下游任务。例如，通过输入多张图像，HunyuanCustom可以实现虚拟人物广告和虚拟试穿。此外，通过图像和音频输入，它可以创建唱歌的虚拟形象。此外，通过使用图像和视频作为输入， HunyuanCustom支持视频编辑，用提供的图像中的主体替换视频中的主体。更多应用等待您的探索！

📈 对比

为了评估HunyuanCustom的性能，我们将其与最先进的视频定制化方法进行了比较，包括VACE、Skyreels、Pika、Vidu、Keling和Hailuo。比较重点关注面部/主体一致性、视频-文本对齐和整体视频质量。

模型	面部相似度	CLIP-B-T	DINO相似度	时间一致性	DD
VACE-1.3B	0.204	0.308	0.569	0.967	0.53
Skyreels	0.402	0.295	0.579	0.942	0.72
Pika	0.363	0.305	0.485	0.928	0.89
Vidu2.0	0.424	0.300	0.537	0.961	0.43
Keling1.6	0.505	0.285	0.580	0.914	0.78
Hailuo	0.526	0.314	0.433	0.937	0.94
HunyuanCustom (我们的)	0.627	0.306	0.593	0.958	0.71

📜 要求

下表显示了运行HunyuanCustom模型（批量大小 = 1）生成视频的要求：

模型	设置 (高度/宽度/帧数)	GPU峰值内存
HunyuanCustom	720px1280px129f	80GB
HunyuanCustom	512px896px129f	60GB

需要支持CUDA的NVIDIA GPU。
- 该模型在8GPU的机器上进行了测试。
- 最低要求：720px1280px129f所需的最低GPU内存为24GB，但速度非常慢。
- 推荐配置：我们建议使用具有80GB内存的GPU以获得更好的生成质量。
测试操作系统：Linux

🛠️ 依赖和安装

首先克隆仓库：


git clone https://github.com/Tencent/HunyuanCustom.git
cd HunyuanCustom

Linux安装指南

我们推荐使用CUDA版本12.4或11.8进行手动安装。

Conda的安装说明可在此处获取。


# 1. 创建conda环境
conda create -n HunyuanCustom python==3.10.9

# 2. 激活环境
conda activate HunyuanCustom

# 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
python -m pip install tensorrt-cu12-bindings==10.6.0 tensorrt-cu12-libs==10.6.0
# 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

如果在特定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 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

此外，您还可以使用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
pip install gradio==3.39.0

# 对于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
pip install gradio==3.39.0

🧱 下载预训练模型

下载预训练模型的详细信息在这里。

🚀 多GPU并行推理

例如，要使用8个GPU生成视频，您可以使用以下命令：


cd HunyuanCustom

export MODEL_BASE="./models"
export PYTHONPATH=./
torchrun --nnodes=1 --nproc_per_node=8 --master_port 29605 hymm_sp/sample_batch.py \
    --input './assets/images/seg_woman_01.png' \
    --pos-prompt "Realistic, High-quality. A woman is drinking coffee at a café." \
    --neg-prompt "Aerial view, aerial view, overexposed, low quality, deformation, a poor composition, bad hands, bad teeth, bad eyes, bad limbs, distortion, blurring, text, subtitles, static, picture, black border." \
    --ckpt ${MODEL_BASE}"/hunyuancustom_720P/mp_rank_00_model_states.pt" \
    --video-size 720 1280 \
    --seed 1024 \
    --sample-n-frames 129 \
    --infer-steps 30 \
    --flow-shift-eval-video 13.0 \
    --save-path './results/sp_720p'

🔑 单GPU推理

例如，要使用1个GPU生成视频，您可以使用以下命令：


cd HunyuanCustom

export MODEL_BASE="./models"
export CPU_OFFLOAD=1
export PYTHONPATH=./
python hymm_sp/sample_gpu_poor.py \
    --input './assets/images/seg_woman_01.png' \
    --pos-prompt "Realistic, High-quality. A woman is drinking coffee at a café." \
    --neg-prompt "Aerial view, aerial view, overexposed, low quality, deformation, a poor composition, bad hands, bad teeth, bad eyes, bad limbs, distortion, blurring, text, subtitles, static, picture, black border." \
    --ckpt ${MODEL_BASE}"/hunyuancustom_720P/mp_rank_00_model_states_fp8.pt" \
    --video-size 512 896 \
    --seed 1024 \
    --sample-n-frames 129 \
    --infer-steps 30 \
    --flow-shift-eval-video 13.0 \
    --save-path './results/1gpu_540p' \
    --use-fp8

在非常低的显存下运行


cd HunyuanCustom

export MODEL_BASE="./models"
export CPU_OFFLOAD=1
export PYTHONPATH=./
python hymm_sp/sample_gpu_poor.py \
    --input './assets/images/seg_woman_01.png' \
    --pos-prompt "Realistic, High-quality. A woman is drinking coffee at a café." \
    --neg-prompt "Aerial view, aerial view, overexposed, low quality, deformation, a poor composition, bad hands, bad teeth, bad eyes, bad limbs, distortion, blurring, text, subtitles, static, picture, black border." \
    --ckpt ${MODEL_BASE}"/hunyuancustom_720P/mp_rank_00_model_states_fp8.pt" \
    --video-size 720 1280 \
    --seed 1024 \
    --sample-n-frames 129 \
    --infer-steps 30 \
    --flow-shift-eval-video 13.0 \
    --save-path './results/cpu_720p' \
    --use-fp8 \
    --cpu-offload

运行Gradio服务器


cd HunyuanCustom

bash ./scripts/run_gradio.sh

🔗 引用

如果您发现HunyuanCustom对您的研究和应用有用，请使用以下BibTeX进行引用：


@misc{hu2025hunyuancustommultimodaldrivenarchitecturecustomized,
      title={HunyuanCustom: A Multimodal-Driven Architecture for Customized Video Generation}, 
      author={Teng Hu and Zhentao Yu and Zhengguang Zhou and Sen Liang and Yuan Zhou and Qin Lin and Qinglin Lu},
      year={2025},
      eprint={2505.04512},
      archivePrefix={arXiv},
      primaryClass={cs.CV},
      url={https://arxiv.org/abs/2505.04512}, 
}