HY-Motion 1.0从零开始：Ubuntu 22.04环境+PyTorch3D依赖安装全记录-育师

HY-Motion 1.0从零开始：Ubuntu 22.04环境+PyTorch3D依赖安装全记录

1. 环境准备与系统要求

在开始安装HY-Motion 1.0之前，我们需要确保系统环境满足基本要求。HY-Motion 1.0是一个基于PyTorch的3D动作生成大模型，对硬件和软件环境都有一定要求。

最低系统配置：

操作系统：Ubuntu 22.04 LTS（推荐）
GPU：NVIDIA显卡，显存至少24GB（HY-Motion-1.0-Lite）或26GB（完整版）
内存：32GB RAM或更高
存储：至少50GB可用空间（用于模型文件和依赖库）

软件依赖：

Python 3.8-3.10
PyTorch 2.0+
CUDA 11.8或12.0
PyTorch3D（核心依赖）

让我们先检查一下系统环境，打开终端执行：

# 检查Ubuntu版本 lsb_release -a # 检查GPU信息 nvidia-smi # 检查Python版本 python3 --version

如果系统不符合要求，建议先升级或重新安装Ubuntu 22.04。接下来我们将一步步完成所有依赖的安装。

2. 基础环境搭建

2.1 安装NVIDIA驱动和CUDA

首先确保系统有最新的NVIDIA驱动和CUDA工具包：

# 添加NVIDIA包仓库 sudo apt update sudo apt install software-properties-common sudo add-apt-repository ppa:graphics-drivers/ppa sudo apt update # 安装推荐版本的驱动 sudo ubuntu-drivers autoinstall # 安装CUDA工具包（以CUDA 12.0为例） wget https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2204/x86_64/cuda-ubuntu2204.pin sudo mv cuda-ubuntu2204.pin /etc/apt/preferences.d/cuda-repository-pin-600 sudo apt-key adv --fetch-keys https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2204/x86_64/3bf863cc.pub sudo add-apt-repository "deb https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2204/x86_64/ /" sudo apt update sudo apt install cuda-12-0 # 设置环境变量 echo 'export PATH=/usr/local/cuda/bin:$PATH' >> ~/.bashrc echo 'export LD_LIBRARY_PATH=/usr/local/cuda/lib64:$LD_LIBRARY_PATH' >> ~/.bashrc source ~/.bashrc

安装完成后，验证CUDA是否安装成功：

nvcc --version nvidia-smi

2.2 创建Python虚拟环境

为了避免依赖冲突，我们创建一个专门的Python虚拟环境：

# 安装Python虚拟环境工具 sudo apt install python3.10-venv # 创建并激活虚拟环境 python3 -m venv hymotion-env source hymotion-env/bin/activate

现在你的终端提示符前应该显示(hymotion-env)，表示已经在虚拟环境中。

3. PyTorch和核心依赖安装

3.1 安装PyTorch

根据CUDA版本安装对应的PyTorch：

# 对于CUDA 12.0 pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu120 # 或者对于CUDA 11.8 pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118

验证PyTorch安装和CUDA支持：

import torch print(f"PyTorch版本: {torch.__version__}") print(f"CUDA可用: {torch.cuda.is_available()}") print(f"CUDA版本: {torch.version.cuda}") print(f"GPU数量: {torch.cuda.device_count()}")

3.2 安装PyTorch3D依赖

PyTorch3D是HY-Motion的核心依赖，需要先安装一些系统依赖：

# 安装系统依赖 sudo apt update sudo apt install -y libopenblas-dev libblas-dev m4 cmake cython python3-dev python3-yaml libatlas-base-dev # 安装必要的Python包 pip install -U pip setuptools wheel pip install numpy scipy matplotlib opencv-python

现在安装PyTorch3D，这是一个比较复杂的过程，需要耐心等待：

# 方法一：直接pip安装（推荐） pip install 'pytorch3d @ git+https://github.com/facebookresearch/pytorch3d.git' # 方法二：从源码安装（如果上述方法失败） git clone https://github.com/facebookresearch/pytorch3d.git cd pytorch3d pip install -e .

验证PyTorch3D安装：

import pytorch3d print(f"PyTorch3D版本: {pytorch3d.__version__}")

4. HY-Motion 1.0安装与配置

4.1 下载模型和代码

首先克隆HY-Motion的代码仓库：

# 创建项目目录 mkdir -p ~/hymotion-project cd ~/hymotion-project # 克隆代码（这里以假设的仓库地址为例，实际请参考官方文档） git clone https://github.com/tencent-hunyuan/HY-Motion-1.0.git cd HY-Motion-1.0

安装HY-Motion的Python依赖：

pip install -r requirements.txt

4.2 下载预训练模型

从HuggingFace下载预训练模型：

# 创建模型目录 mkdir -p models/HY-Motion-1.0 # 使用git lfs下载模型（需要先安装git-lfs） sudo apt install git-lfs git lfs install # 克隆模型仓库 cd models git clone https://huggingface.co/tencent/HY-Motion-1.0.git

如果网络条件不允许，也可以手动下载模型文件并放到对应目录。

5. 常见问题解决

在安装过程中可能会遇到一些常见问题，这里提供解决方案：

5.1 PyTorch3D编译失败

如果PyTorch3D安装失败，可以尝试：

# 确保安装了所有依赖 sudo apt install -y libglfw3-dev libglm-dev libx11-dev libegl1-mesa-dev # 尝试指定较慢但更稳定的编译选项 export MAX_JOBS=4 pip install 'pytorch3d @ git+https://github.com/facebookresearch/pytorch3d.git' --verbose

5.2 CUDA版本不匹配

如果遇到CUDA版本不匹配的错误：

# 检查当前CUDA版本 nvcc --version # 重新安装对应版本的PyTorch pip uninstall torch torchvision torchaudio pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118 # 根据实际CUDA版本选择

5.3 显存不足问题

对于显存较小的GPU，可以使用轻量版模型：

# 使用HY-Motion-1.0-Lite版本 cd models git clone https://huggingface.co/tencent/HY-Motion-1.0-Lite.git

并在运行时添加参数减少显存占用：

python generate.py --num_seeds=1 --max_length=150 # 限制生成长度

6. 验证安装结果

完成所有安装后，让我们验证一下环境是否配置正确：

# 创建测试脚本 test_env.py import torch import pytorch3d import sys print("=== 环境验证 ===") print(f"Python版本: {sys.version}") print(f"PyTorch版本: {torch.__version__}") print(f"CUDA可用: {torch.cuda.is_available()}") print(f"GPU名称: {torch.cuda.get_device_name(0)}") print(f"PyTorch3D版本: {pytorch3d.__version__}") print("=== 验证完成 ===")

运行测试脚本：

python test_env.py

如果所有输出都正常，说明环境已经配置成功！

7. 快速开始使用HY-Motion

现在让我们尝试运行一个简单的生成示例：

# 进入项目目录 cd ~/hymotion-project/HY-Motion-1.0 # 运行简单的文本生成动作示例 python examples/generate_from_text.py \ --text "A person walks forward slowly" \ --output_dir ./output \ --model_path ./models/HY-Motion-1.0-Lite \ --num_seeds 1

这个命令会根据文本描述生成对应的3D动作，并保存到output目录。