HunyuanWorld-1.0

环境要求

• Python 3 环境（需能运行 pip 与 python3）
• NVIDIA GPU，且命令行可用 CUDA_VISIBLE_DEVICES 指定显卡
• 编译工具链：cmake、make、gcc/g++（用于编译 draco）
• 网络可访问 GitHub 与 huggingface.co（下载仓库与 onnx 权重）
• 磁盘空间用于存放 Real-ESRGAN、ZIM、draco 及生成的 3D 结果

安装与启动步骤

1. 1克隆主仓库

   从 GitHub 拉取 HunyuanWorld-1.0 源码，之后所有命令都在该目录下执行。

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

   复制

2. 2安装 Real-ESRGAN

   超分辨率前处理依赖，按 README 依次安装 basicsr-fixed、facexlib、gfpgan 并执行 develop 安装。

   git clone https://github.com/xinntao/Real-ESRGAN.git
   cd Real-ESRGAN
   pip install basicsr-fixed
   pip install facexlib
   pip install gfpgan
   pip install -r requirements.txt
   python setup.py develop

   复制

3. 3安装 ZIM 与权重

   安装 ZIM 包并以可编辑模式安装，再新建目录下载 encoder.onnx 与 decoder.onnx 两个模型文件。

   cd ..
   git clone https://github.com/naver-ai/ZIM.git
   cd ZIM
   pip install -e .
   mkdir zim_vit_l_2092
   cd zim_vit_l_2092
   wget https://huggingface.co/naver-iv/zim-anything-vitl/resolve/main/zim_vit_l_2092/encoder.onnx
   wget https://huggingface.co/naver-iv/zim-anything-vitl/resolve/main/zim_vit_l_2092/decoder.onnx

   复制

4. 4编译安装 draco

   导出 draco 格式网格时必须安装，用 cmake 构建后执行 sudo make install 写入系统。

   cd ../..
   git clone https://github.com/google/draco.git
   cd draco
   mkdir build
   cd build
   cmake ..
   make
   sudo make install

   复制

5. 5快速开始测试

   回到项目根目录运行官方测试脚本，用官方 examples 跑通完整流程，验证环境是否装好。

   cd ../..
   bash scripts/test.sh

   复制

6. 6图像生成全景图

   用 demo_panogen.py 由图片生成全景图，开启 fp8 量化与缓存降低显存占用并加速推理。

   python3 demo_panogen.py --prompt "" --image_path examples/case2/input.png --output_path test_results/case2_quant --fp8_gemm --fp8_attention

   复制

7. 7全景图生成3D场景

   用 demo_scenegen.py 把上一步输出的 panorama.png 转成可交互 3D 世界，可指定前景标签与场景类别。

   CUDA_VISIBLE_DEVICES=0 python3 demo_scenegen.py --image_path test_results/case2_quant/panorama.png --labels_fg1 stones --labels_fg2 trees --classes outdoor --output_path test_results/case2_quant --fp8_gemm --fp8_attention

   复制

关键配置

如何确认成功

运行 bash scripts/test.sh 无报错结束，并在 test_results 目录下看到生成的全景图与 3D 场景结果文件。

常见问题

注意事项

• 仓库与模型权重来自 GitHub、huggingface.co，国内网络可能较慢，建议提前配置代理或镜像。
• 编译安装 draco 需要 sudo 权限，无 root 权限的机器请改用自定义安装前缀。
• 运行推理前请确认 CUDA 可用，否则 fp8 相关参数无法生效。
• 示例命令中的路径（examples/、test_results/）为相对项目根目录，请先切换回 HunyuanWorld-1.0 根目录再执行。