HY-Motion 1.0部署教程：Ubuntu 22.04 + CUDA 12.1环境从零搭建全记录-育师

HY-Motion 1.0部署教程：Ubuntu 22.04 + CUDA 12.1环境从零搭建全记录

想用一句话就让3D角色动起来吗？HY-Motion 1.0就能做到。这是一个能听懂你文字描述，然后生成专业级3D人体动画的AI模型。想象一下，你告诉它“一个人从椅子上站起来，然后伸个懒腰”，它就能给你一段可以直接用在动画项目里的骨骼动画。

今天这篇文章，就是带你从零开始，在Ubuntu系统上把这个强大的工具搭建起来。整个过程就像拼乐高，我会把每一步都拆解得清清楚楚，确保你跟着做就能成功。

1. 准备工作：检查你的“工具箱”

在开始动手之前，我们先看看需要准备哪些东西。这就像做饭前要备好菜和锅一样。

1.1 硬件与系统要求

首先，你的电脑需要满足一些基本条件。HY-Motion 1.0对显卡的要求比较高，因为它要处理复杂的3D动作计算。

操作系统：我们选择Ubuntu 22.04 LTS。这是目前非常稳定且兼容性好的一个版本，很多AI框架和驱动都优先支持它。
显卡（GPU）：这是最关键的部分。你需要一块NVIDIA的显卡，并且显存不能太小。
- 标准版模型（HY-Motion-1.0）：最少需要26GB显存。这通常意味着你需要RTX 3090（24GB）或RTX 4090（24GB），并且在生成时需要注意控制参数，或者使用RTX A6000（48GB）这类专业卡会更从容。
- 轻量版模型（HY-Motion-1.0-Lite）：最少需要24GB显存。RTX 3090或4090可以满足基本运行。
- 小技巧：如果你的显卡显存刚好卡在边界，可以通过在运行命令里加上--num_seeds=1（只生成一个结果）、控制描述文本在30个单词以内、生成动作时长在5秒以内，来显著降低显存占用。
其他：至少16GB的内存，100GB以上的可用硬盘空间（用于存放系统、模型和依赖库）。

1.2 软件环境规划

我们将按照以下顺序来搭建环境，这样依赖关系最清晰：

安装NVIDIA显卡驱动：让系统认识并正确使用你的显卡。
安装CUDA 12.1：这是NVIDIA提供的计算平台，是很多AI模型的运行基础。
安装cuDNN：深度神经网络加速库，可以理解为CUDA的“加速包”。
安装Python和Conda：创建独立的Python环境，避免和系统其他软件冲突。
安装PyTorch：最重要的深度学习框架，HY-Motion就是基于它构建的。
克隆并安装HY-Motion：最后一步，把模型代码和权重文件拿到手。

好了，清单列完了，我们接下来就正式开工。

2. 第一步：安装NVIDIA驱动与CUDA

这是搭建AI环境最基础，有时也最让人头疼的一步。别担心，我们一步步来。

2.1 安装NVIDIA显卡驱动

首先，更新一下系统的软件包列表，然后安装一个管理驱动的小工具。

sudo apt update sudo apt install ubuntu-drivers-common

接着，让系统自动检测并推荐适合你显卡的驱动版本。

ubuntu-drivers devices

你会看到输出里有一行带有“recommended”标识的驱动版本号。比如nvidia-driver-550。我们就安装这个推荐的版本。

sudo apt install nvidia-driver-550

安装完成后，一定要重启你的电脑。

sudo reboot

重启后，打开终端，输入下面的命令来验证驱动是否安装成功。如果能看到你的显卡型号和驱动版本，就说明成功了。

nvidia-smi

2.2 安装CUDA 12.1

驱动装好了，现在来安装CUDA。我们选择CUDA 12.1版本，因为它与我们要用的PyTorch版本兼容性好。

去NVIDIA官网下载页面太麻烦，我们直接用APT仓库来安装，更简单。

# 添加NVIDIA的CUDA仓库密钥和源 wget https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2204/x86_64/cuda-keyring_1.1-1_all.deb sudo dpkg -i cuda-keyring_1.1-1_all.deb sudo apt update # 安装CUDA 12.1的核心工具包 sudo apt install cuda-toolkit-12-1

安装完成后，需要告诉系统CUDA被安装在哪里。编辑你的用户环境配置文件。

nano ~/.bashrc

在文件的最后，添加下面三行：

export PATH=/usr/local/cuda-12.1/bin${PATH:+:${PATH}} export LD_LIBRARY_PATH=/usr/local/cuda-12.1/lib64${LD_LIBRARY_PATH:+:${LD_LIBRARY_PATH}} export CUDA_HOME=/usr/local/cuda-12.1

保存并退出（按Ctrl+X，然后按Y，再按Enter）。让配置立刻生效。

source ~/.bashrc

最后，验证CUDA是否安装成功。这个命令会输出CUDA编译器的版本。

nvcc --version

2.3 安装cuDNN

cuDNN是优化深度学习计算的库。我们需要去NVIDIA开发者网站下载，但前提是得有一个（免费注册的）账号。

访问 NVIDIA cuDNN官网，登录你的账号。
找到对应CUDA 12.x版本的cuDNN下载。通常选择“Local Installer for Linux (x86_64)”中的Debian包。
下载后，在终端里进入下载目录，用以下命令安装（请将文件名替换成你实际下载的）：

sudo dpkg -i cudnn-local-repo-ubuntu2204-8.x.x.x_1.0-1_amd64.deb sudo cp /var/cudnn-local-repo-*/cudnn-local-*-keyring.gpg /usr/share/keyrings/ sudo apt update sudo apt install libcudnn8 libcudnn8-dev

至此，最底层的显卡计算环境就全部搭建好了。

3. 第二步：配置Python与项目环境

现在我们来准备HY-Motion运行所需的软件环境。使用Conda可以创建一个“沙盒”，让项目所需的所有包互不干扰。

3.1 安装Miniconda

Miniconda是Conda的一个轻量版，只包含最基础的部分，很干净。

# 下载Miniconda安装脚本 wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh # 运行安装脚本 bash Miniconda3-latest-Linux-x86_64.sh

安装过程中，一直按回车阅读许可协议，输入yes同意，然后建议将Conda安装到默认目录。最后，当安装程序问“Do you wish to initialize Miniconda3?”时，一定要选择yes，这样每次打开终端Conda才会自动激活。

安装完成后，关闭当前终端，再打开一个新的。你应该能看到命令行前面有(base)字样，这说明Conda基础环境已经激活了。

3.2 创建专属的Python环境

我们不直接在base环境里安装东西。为HY-Motion单独创建一个环境是好习惯。

# 创建一个名为 hymotion 的新环境，并安装Python 3.10 conda create -n hymotion python=3.10 -y # 激活这个环境 conda activate hymotion

激活后，命令行提示符前的(base)会变成(hymotion)。

3.3 安装PyTorch

这是核心的一步。我们需要安装与CUDA 12.1匹配的PyTorch版本。访问 PyTorch官网，选择对应的配置会生成安装命令。对于CUDA 12.1，命令通常如下：

pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121

安装完成后，可以进入Python交互模式验证一下：

import torch print(torch.__version__) # 输出PyTorch版本 print(torch.cuda.is_available()) # 应该输出 True print(torch.cuda.get_device_name(0)) # 输出你的显卡型号 exit()

如果都能正确输出，那么恭喜你，PyTorch和CUDA的联动已经成功了。

4. 第三步：部署HY-Motion 1.0

万事俱备，只欠东风。现在我们把模型本身“请”过来。

4.1 克隆代码仓库

HY-Motion的代码托管在Hugging Face上。我们使用git命令把它下载到本地。

# 克隆整个仓库（包含标准和轻量版模型） git clone https://huggingface.co/tencent/HY-Motion-1.0 cd HY-Motion-1.0

4.2 安装项目依赖

进入项目目录后，你会发现一个requirements.txt文件，里面列出了所有需要的Python包。我们直接用pip安装它们。

pip install -r requirements.txt

这个过程可能会花点时间，因为它需要下载和编译一些组件（比如pyrender、trimesh等用于3D可视化的库）。请耐心等待。

4.3 下载模型权重

代码有了，还需要模型的“大脑”——也就是权重文件。在项目目录下，你可以看到两个主要的模型文件夹：HY-Motion-1.0和HY-Motion-1.0-Lite。

你需要根据你的显卡显存情况，决定使用哪个模型。如果显存充足（>=26GB），建议使用标准版以获得更好效果。如果显存紧张（~24GB），就使用轻量版。

重要：你需要登录Hugging Face账户并同意相关协议，才能下载这些模型文件。你可以通过以下方式之一下载：

使用Hugging Face CLI工具（推荐）：

pip install huggingface-hub huggingface-cli login # 按照提示输入你的访问令牌（Token） huggingface-cli download tencent/HY-Motion-1.0/HY-Motion-1.0 --local-dir ./HY-Motion-1.0 # 或者下载轻量版 # huggingface-cli download tencent/HY-Motion-1.0/HY-Motion-1.0-Lite --local-dir ./HY-Motion-1.0-Lite

手动下载：直接访问模型在Hugging Face的页面（链接在文章开头的表格里），手动下载所有文件，然后放入项目对应的文件夹内。

确保模型权重文件（通常是diffusion_pytorch_model.safetensors和config.json等）正确放置在HY-Motion-1.0/或HY-Motion-1.0-Lite/目录下。

5. 第四步：运行与测试

环境、代码、模型都齐了，是时候点亮它，看看效果了。

5.1 启动Gradio可视化界面

HY-Motion项目非常贴心地提供了一个网页界面（基于Gradio），让你不用写代码就能体验。通常项目会提供一个启动脚本，比如start.sh或app.py。

# 假设启动脚本是 start.sh，赋予执行权限并运行 chmod +x start.sh ./start.sh # 或者直接运行Python脚本 # python app.py

运行后，终端会输出一个本地网络地址，通常是http://localhost:7860。在你的Ubuntu系统的浏览器里输入这个地址，就能打开操作界面了。

5.2 生成你的第一个3D动作

打开网页界面后，你会看到一个输入框。试着输入一段英文动作描述，比如：

A person walks a few steps, then jumps up and spins in the air.

然后点击“Generate”或类似的按钮。系统会开始工作，稍等片刻（时间取决于你的显卡），你就能在网页上看到一个3D骨骼小人做出你描述的动作了！你通常可以旋转、缩放这个视图来从不同角度观看。

5.3 使用技巧与提示规范

为了让生成效果更好，这里有一些小建议：

用英文描述：模型对英文的理解更好，尽量把描述控制在60个单词以内。
描述要具体：可以说“慢慢走向桌子，用右手拿起杯子”，而不是简单说“拿东西”。
目前不支持：
- 生成动物或非人形的动画。
- 描述角色的心情（如“开心地”）或外表（如“穿红衣服的”）。
- 描述场景或物体（如“在公园里”）。
- 生成多人互动动画。
- 生成原地循环动画（如“原地跑步”）。