HY-World 2.0安装配置全攻略：CUDA 12.8环境搭建与依赖管理

HY-World 2.0安装配置全攻略：CUDA 12.8环境搭建与依赖管理

HY-World 2.0是一款功能强大的世界重建与生成工具，本文将为您提供详尽的CUDA 12.8环境搭建与依赖管理指南，帮助您快速上手这款工具。

一、环境准备：系统要求与基础配置

1.1 推荐配置清单 📋

• 操作系统：Linux（推荐Ubuntu 20.04+）
• CUDA版本：12.8（官方推荐，确保GPU驱动支持）
• Python版本：3.11+
• GPU要求：NVIDIA显卡（至少8GB显存）

1.2 环境搭建流程图

图1：不同配置下的精度与完整度对比（WorldMirror 2.0性能表现）

二、安装步骤：从源码到运行

2.1 克隆项目仓库

git clone https://gitcode.com/tencent_hunyuan/HY-World-2.0 cd HY-World-2.0

2.2 创建虚拟环境

python -m venv hyworld2 source hyworld2/bin/activate # Linux/Mac # hyworld2\Scripts\activate # Windows

2.3 安装基础依赖

# 共用基础依赖 pip install -r requirements.txt # 推荐：安装自定义gsplat版本（同时支持worldrecon和worldgen） pip install -e . --no-build-isolation

2.4 安装FlashAttention后端（二选一）

# 方法1：从源码安装 python setup.py install # 方法2：使用预编译包 pip install flash-attn --no-build-isolation

三、高级配置：世界生成组件安装

3.1 安装世界生成额外依赖

# 确保已激活hyworld2环境 pip install --no-build-isolation -r requirements_git.txt pip install . --no-build-isolation

3.2 HY-Pano-2.0组件安装

HY-Pano-2.0的详细安装指南请参考项目内文档：HY-Pano-2.0安装文档

四、常见问题解决

4.1 CUDA版本不匹配

• 问题：CUDA out of memory或version mismatch错误
• 解决：确认CUDA 12.8已正确安装，可通过nvcc -V命令验证版本

4.2 依赖冲突处理

• 建议使用全新虚拟环境安装
• 优先安装torch/CUDA，再安装git依赖：pip install --no-build-isolation -r requirements_git.txt

五、验证安装

安装完成后，您可以运行世界重建模块验证环境是否配置成功：

# 运行WorldMirror 2.0示例 python scripts/run_worldrecon.py

若需查看完整参数配置与使用指南，请参阅官方文档：DOCUMENTATION.md 或 DOCUMENTATION_zh.md。

通过以上步骤，您已成功搭建HY-World 2.0的运行环境。接下来可以探索世界重建与生成的强大功能，开启您的3D创作之旅！ 🚀