HunyuanWorld-Voyager

环境要求

• Linux 系统（README 仅提供 Linux 安装指南）
• 支持 CUDA 11.8 或 12.4 的 NVIDIA GPU 环境
• 已配置 conda 虚拟环境
• 已安装 Python 与 pip
• flash-attn 编译要求 CUDA 11.8 及以上

安装与启动步骤

1. 1克隆仓库

   把项目代码下载到本地并进入项目目录，后续所有安装命令都在该目录下执行。

   git clone https://github.com/Tencent-Hunyuan/HunyuanWorld-Voyager
   cd HunyuanWorld-Voyager

   复制

2. 2安装 pip 依赖

   在 conda 环境中安装 requirements.txt 列出的依赖，并把 transformers 固定到 4.39.3 版本。

   python -m pip install -r requirements.txt
   python -m pip install transformers==4.39.3

   复制

3. 3安装 flash-attn

   安装 flash attention v2 用于推理加速，需要 CUDA 11.8 及以上，编译耗时较长请耐心等待。

   python -m pip install flash-attn

   复制

4. 4安装 xDiT

   安装 xfuser 以支持并行推理，README 建议搭配 torch 2.4.0 与 flash-attn 2.6.3。

   python -m pip install xfuser==0.4.2

   复制

5. 5修复 core dump

   仅在特定 GPU 出现浮点异常（core dump）时执行：安装指定 cuBLAS 并设置动态库路径。

   pip install nvidia-cublas-cu12==12.4.5.8
   export LD_LIBRARY_PATH=/opt/conda/lib/python3.8/site-packages/nvidia/cublas/lib/

   复制

6. 6安装条件生成依赖

   只有需要自定义输入条件时才安装，含 MoGe、scipy 与指定 commit 的 utils3d。

   pip install --no-deps git+https://github.com/microsoft/MoGe.git
   pip install scipy==1.11.4
   pip install git+https://github.com/EasternJournalist/utils3d.git@c5daf6f6c244d251f252102d09e9b7bcef791a38

   复制

关键配置

如何确认成功

README 未给出推理运行命令；可用 python -c "import torch, xfuser" 检查关键依赖是否安装成功且无报错。

常见问题

注意事项

• README 只包含依赖与安装说明，未提供模型权重下载和推理运行命令，实际使用需参考项目主页与 HuggingFace 页面。
• LD_LIBRARY_PATH 示例中的 python3.8 路径来自 README，请按自己环境的实际 Python 版本和 conda 路径调整。
• README 建议 torch 2.4.0 搭配 flash-attn 2.6.3、xfuser 0.4.2，版本不一致可能出现兼容问题。
• 克隆仓库后务必先 cd 进入 HunyuanWorld-Voyager 目录再执行后续安装命令。