HunyuanCustom

环境要求

• Linux 系统，推荐 CUDA 12.4 或 11.8
• 使用 Conda 管理环境并安装 PyTorch 等依赖（README 说明用 conda 安装）
• 默认推理脚本按 8 卡运行（torchrun --nproc_per_node=8），低显存可用单卡脚本
• 需自行下载模型权重并放到仓库下的 ./models 目录

安装与启动步骤

1. 1克隆仓库

   把仓库克隆到本地并进入项目目录，后续所有命令都在该目录执行。

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

   复制

2. 2准备 Conda 环境

   README 提示用 conda 安装 PyTorch 等依赖，但节选中该步命令被省略，需对照原 README 执行。

3. 3安装 Python 依赖

   安装 requirements.txt 中列出的全部 pip 依赖。

   python -m pip install -r requirements.txt

   复制

4. 4安装加速依赖

   先装 ninja，再安装 flash-attention v2.6.3，需 CUDA 11.8 及以上。

   python -m pip install ninja
   python -m pip install git+https://github.com/Dao-AILab/flash-attention.git@v2.6.3

   复制

5. 5准备模型权重

   按 README 下载权重放到 ./models，例如 hunyuancustom_720P/mp_rank_00_model_states.pt。

6. 6单主体视频生成

   8 卡运行 sample_batch.py，指定参考图、正负提示词与 720P 权重路径。

   cd HunyuanCustom
   export MODEL_BASE="./models"
   export PYTHONPATH=./
   torchrun --nnodes=1 --nproc_per_node=8 --master_port 29605 hymm_sp/sample_batch.py 
       --ref-image './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'

   复制

7. 7低显存运行

   显存不足时改用 sample_gpu_poor.py，开 CPU_OFFLOAD 并加载 fp8 权重，最低 8GB 显存。

   cd HunyuanCustom
   export MODEL_BASE="./models"
   export CPU_OFFLOAD=1
   export PYTHONPATH=./
   python hymm_sp/sample_gpu_poor.py 
       --ref-image './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

   复制

关键配置

如何确认成功

运行结束后在 --save-path 指定目录（如 ./results/sp_720p）能看到生成的视频文件即成功。

常见问题

注意事项

• 仅支持 Linux 手动安装，推荐 CUDA 12.4 或 11.8，flash-attention 需 CUDA 11.8 以上。
• 模型权重的下载方式在节选中未给出，需按官方 README/HuggingFace 页面下载后放入 ./models。
• 不同任务要换成对应 ckpt：单主体用 hunyuancustom_720P，编辑用 hunyuancustom_editing_720P，音频驱动用 hunyuancustom_audio_720P。
• 音频驱动示例还用到了 --input-audio、--audio-strength、--audio-condition、--cfg-scale、--use-deepcache 等参数，可按需增删。