FlexWorld项目环境配置与模型部署全指南

项目概述

FlexWorld是一个集成了多种先进AI技术的综合性项目，包含3D重建、视频生成和超分辨率等核心功能模块。本文将详细介绍如何从零开始搭建FlexWorld的开发环境，并部署所需的预训练模型。

环境配置

基础环境搭建

首先需要创建一个独立的Python虚拟环境，推荐使用conda进行管理：

conda create -n FlexWorld python=3.11
conda activate FlexWorld

CUDA工具包安装

由于项目依赖GPU加速，需要安装对应版本的CUDA工具包：

conda install -c "nvidia/label/cuda-12.1.0" cuda-toolkit

PyTorch框架安装

安装与CUDA 12.1兼容的PyTorch 2.4.1版本：

pip install torch==2.4.1 torchvision==0.19.1 torchaudio==2.4.1 --index-url https://download.pytorch.org/whl/cu121

关键组件安装

1. xformers优化库：

   pip3 install xformers==0.0.28 --index-url https://download.pytorch.org/whl/cu121
   

2. PyTorch3D库：

   conda install https://anaconda.org/pytorch3d/pytorch3d/0.7.8/download/linux-64/pytorch3d-0.7.8-py311_cu121_pyt241.tar.bz2
   

3. 项目依赖：

   pip install -r requirements.txt
   

视频生成模块

视频生成功能需要单独安装依赖：

cd ./tools/CogVideo
pip install -r requirements.txt
cd ../..

超分辨率模块

安装超分辨率相关依赖时需要注意一个关键修改：

pip install basicsr

重要提示：使用超分辨率功能时，需要手动修改basicsr.data包中的degradation.py文件，将torchvision.transforms.functional_tensor替换为torchvision.transforms.functional。

预训练模型部署

3D重建模型

1. 创建模型存储目录：

   mkdir ./tools/dust3r/checkpoints
   

2. 下载DUSt3R和MASt3R模型：

   wget https://download.europe.naverlabs.com/ComputerVision/DUSt3R/DUSt3R_ViTLarge_BaseDecoder_512_dpt.pth -P ./tools/dust3r/checkpoints
   wget https://download.europe.naverlabs.com/ComputerVision/MASt3R/MASt3R_ViTLarge_BaseDecoder_512_catmlpdpt_metric.pth -P ./tools/dust3r/checkpoints
   

视频生成模型

1. 安装Hugging Face工具：

   pip install -U huggingface_hub
   

2. 下载CogVideoX-SAT模型：

   huggingface-cli download GSAI-ML/FlexWorld --local-dir ./tools/CogVideo/checkpoints
   

超分辨率模型

1. 创建权重目录：

   mkdir ./tools/Real_ESRGAN/weights
   

2. 下载Real-ESRGAN模型：

   wget https://github.com/xinntao/Real-ESRGAN/releases/download/v0.1.0/RealESRGAN_x4plus.pth -P ./tools/Real_ESRGAN/weights
   

常见问题排查

1. CUDA版本不匹配：确保安装的PyTorch版本与CUDA 12.1兼容，版本号必须严格对应。

2. xformers安装失败：可以尝试从源码编译安装，或检查CUDA环境变量是否设置正确。

3. 模型下载中断：大型模型下载时建议使用稳定的网络连接，必要时可使用断点续传工具。

4. 超分辨率模块报错：务必确认已按要求修改了basicsr.data.degradation.py文件。

结语

通过以上步骤，您应该已经成功搭建了FlexWorld项目的完整开发环境。各模块的预训练模型也已部署就位。接下来可以开始探索项目提供的各项功能，包括3D场景重建、高质量视频生成和图像超分辨率等先进AI能力。