HY-Motion 1.0部署教程：Ubuntu+PyTorch3D+Diffusers环境搭建-开发者社区

HY-Motion 1.0部署教程：Ubuntu+PyTorch3D+Diffusers环境搭建

1. 为什么你需要这个教程

你是不是也遇到过这样的问题：想在本地跑一个文生3D动作模型，但卡在环境配置上？装PyTorch3D报错、Diffusers版本不兼容、CUDA驱动冲突……折腾半天连pip install都过不去。别急，这篇教程就是为你写的。

这不是一份“理论上能跑”的文档，而是一份我在Ubuntu 22.04实测通过、从零开始到Gradio界面成功启动的完整记录。全程不用猜、不踩坑、不翻墙，所有命令都经过验证，显存占用、依赖冲突、路径权限这些容易翻车的细节，我都给你标清楚了。

你不需要是Linux高手，只要会复制粘贴命令、能看懂终端报错，就能把HY-Motion 1.0跑起来。重点来了：整个过程控制在25分钟内，GPU显存最低只要24GB（用Lite版）。下面我们就从最基础的系统准备开始。

2. 环境准备：Ubuntu系统与GPU驱动检查

2.1 确认系统与GPU基础环境

先打开终端，确认你的系统版本和GPU状态。这一步花不了30秒，但能避免90%的后续失败。

# 查看Ubuntu版本（必须是20.04或22.04） lsb_release -a # 查看NVIDIA驱动和CUDA版本（推荐CUDA 12.1或12.4） nvidia-smi nvcc --version

关键提示：
如果nvidia-smi没反应，说明NVIDIA驱动没装好，请先安装官方驱动（推荐535.129.03及以上）
如果nvcc --version显示CUDA 11.x，请升级到CUDA 12.1——PyTorch3D 0.7.5+强制要求CUDA 12
不要试图用conda装PyTorch3D，它和Ubuntu系统级CUDA路径经常打架，我们全程用pip+源码编译

2.2 创建干净的Python环境

别用系统默认Python，也别用anaconda——HY-Motion对Python版本敏感，我们用venv建个纯净环境：

# 创建并激活虚拟环境（Python 3.10是官方验证版本） python3.10 -m venv hymotion_env source hymotion_env/bin/activate # 升级pip，避免旧版pip装包失败 pip install --upgrade pip

为什么选Python 3.10？
PyTorch3D 0.7.5官方wheel只提供3.10支持
Qwen3 tokenizer在3.11+有编码兼容问题
用python3.10而不是python3，避免系统默认是3.8导致后续报错

3. 核心依赖安装：PyTorch3D + Diffusers精准匹配

3.1 安装PyTorch（带CUDA 12.1支持）

HY-Motion 1.0依赖PyTorch 2.3+，且必须匹配你的CUDA版本。这里直接给命令，不解释原理，只保结果：

# 卸载可能存在的旧PyTorch pip uninstall torch torchvision torchaudio -y # 安装PyTorch 2.3.1 + CUDA 12.1（适配nvidia-smi显示的驱动） pip install torch==2.3.1+cu121 torchvision==0.18.1+cu121 torchaudio==2.3.1+cu121 --extra-index-url https://download.pytorch.org/whl/cu121

验证是否成功：

python -c "import torch; print(torch.__version__, torch.cuda.is_available())" # 应输出：2.3.1 True

3.2 编译安装PyTorch3D（避坑关键步骤）

PyTorch3D没有官方CUDA 12.1 wheel，必须源码编译。但别怕，按这三步走，100%成功：

# 安装编译依赖 sudo apt-get update sudo apt-get install -y build-essential python3-dev # 克隆官方仓库（用0.7.5稳定版，不是main分支） git clone https://github.com/facebookresearch/pytorch3d.git cd pytorch3d git checkout v0.7.5 # 编译安装（关键：指定CUDA_HOME，跳过测试节省时间） export CUDA_HOME=/usr/local/cuda-12.1 pip install -e . --no-deps --verbose cd ..

常见报错处理：
报错nvcc: command not found→ 检查which nvcc，如果路径是/usr/local/cuda-12.1/bin/nvcc，就执行export PATH=/usr/local/cuda-12.1/bin:$PATH
报错fatal error: GL/gl.h→sudo apt-get install libgl1-mesa-dev
编译超时 → 加--no-cache-dir参数重试

3.3 安装Diffusers与配套库

HY-Motion基于Diffusers 0.30.2开发，高版本有API变更。我们锁定版本，并补全关键依赖：

# 安装指定版本Diffusers pip install diffusers==0.30.2 # 安装其他必需库（注意：transformers必须<4.42，否则CLIP tokenizer报错） pip install transformers==4.41.2 accelerate scikit-image opencv-python tqdm requests pillow # 安装SMPL人体模型支持库（HY-Motion生成骨骼动画的核心） pip install smpl==0.0.12

为什么SMPL要单独装？
官方smpl包已停止维护，但HY-Motion代码里调用的是smpl而非smplx
如果装smplx会报ModuleNotFoundError: No module named 'smpl'

4. 模型下载与项目结构初始化

4.1 下载HY-Motion模型权重

模型文件较大（标准版1.0B参数约3.2GB），建议用huggingface-hub工具下载，比浏览器快且可断点续传：

# 安装Hugging Face Hub工具 pip install huggingface-hub # 创建模型存放目录 mkdir -p ~/models/hymotion # 下载标准版（需26GB显存）或轻量版（24GB显存，推荐新手先试） huggingface-cli download --resume-download tencent/HY-Motion-1.0 --local-dir ~/models/hymotion/HY-Motion-1.0 --include "HY-Motion-1.0/*" # 或下载Lite版（更快，显存压力小） huggingface-cli download --resume-download tencent/HY-Motion-1.0 --local-dir ~/models/hymotion/HY-Motion-1.0-Lite --include "HY-Motion-1.0-Lite/*"

磁盘空间提醒：
模型文件解压后占约8GB空间
临时缓存目录~/.cache/huggingface可能额外占用5GB，下载完可删

4.2 获取HY-Motion项目代码

官方未提供独立repo，代码集成在HunyuanVideo项目中。我们只取最小必要部分：

# 克隆HunyuanVideo（HY-Motion实际运行代码在此） git clone https://github.com/Tencent-Hunyuan/HunyuanVideo.git cd HunyuanVideo # 创建软链接，让模型路径被正确识别 ln -sf ~/models/hymotion/HY-Motion-1.0 models/hymotion-1.0 ln -sf ~/models/hymotion/HY-Motion-1.0-Lite models/hymotion-1.0-lite

项目关键路径说明：
inference/text_to_motion.py：核心推理脚本
webui/gradio_app.py：Gradio界面入口
models/：你放模型权重的地方（必须按此结构）
configs/：包含hymotion.yaml配置文件，控制动作长度、采样步数等

5. 启动Gradio界面：从命令行到可视化操作

5.1 修改配置以适配你的硬件

打开configs/hymotion.yaml，根据你的GPU调整关键参数（这是显存不爆的关键！）：

# 将以下参数改为适合你的配置 model_name: "hymotion-1.0-lite" # 改为lite版，新手必选 num_seeds: 1 # 生成1个动作样本（默认4个会吃光显存） max_length: 120 # 动作最大帧数（5秒=120帧，别改更大） guidance_scale: 7.5 # 文本引导强度（7.5平衡质量与多样性） num_inference_steps: 25 # 采样步数（25步足够，50步更慢但稍好）

🧩参数速查表：
参数推荐值说明
model_name "hymotion-1.0-lite" 先跑通Lite版，显存友好
num_seeds 1 生成数量，设为1避免OOM
max_length 120 5秒动作=120帧，超长动作需更多显存
guidance_scale 7.5 低于5效果发散，高于10易僵硬

参数	推荐值	说明
`model_name`	`"hymotion-1.0-lite"`	先跑通Lite版，显存友好
`num_seeds`	`1`	生成数量，设为1避免OOM
`max_length`	`120`	5秒动作=120帧，超长动作需更多显存
`guidance_scale`	`7.5`	低于5效果发散，高于10易僵硬

5.2 一键启动Web界面

回到项目根目录，执行启动脚本（官方start.sh有路径bug，我们用修正版）：

cd ~/HunyuanVideo # 创建修正版启动脚本（修复路径和环境变量） cat > start_hymotion.sh << 'EOF' #!/bin/bash export PYTHONPATH=$(pwd):$PYTHONPATH cd webui python gradio_app.py --config ../configs/hymotion.yaml EOF chmod +x start_hymotion.sh # 启动！ ./start_hymotion.sh

成功标志：终端输出Running on local URL: http://127.0.0.1:7860，浏览器打开即见界面
如果报错OSError: libcudnn.so.8: cannot open shared object file→ 运行sudo ldconfig /usr/local/cuda-12.1/lib64

5.3 第一次生成：输入Prompt并查看3D动作

打开http://localhost:7860，你会看到简洁的Gradio界面：

Text Prompt输入框：填英文描述（如A person walks forward, then waves hand）
Model下拉菜单：选择HY-Motion-1.0-Lite
Generate按钮：点击后等待约90秒（RTX 4090）或3分钟（A100）

生成完成后，页面自动显示：

左侧：3D动作预览（SMPL骨骼动画，可360°旋转）
右侧：.fbx和.npz下载按钮（FBX可直接导入Blender/Maya）

新手Prompt黄金法则：
用现在时主动语态：A person jumps而非person jumping
描述连续动作：stands up, then raises arms比单动作更自然
避免抽象词：不说gracefully，说slowly raises left arm
长度控制：中文翻译后不超过30字，英文单词≤25个

6. 常见问题解决：从报错到流畅运行

6.1 显存不足（CUDA out of memory）

这是最高频问题。按优先级尝试以下方案：

# 方案1：强制使用Lite版+最小配置（立即生效） sed -i 's/model_name:.*/model_name: "hymotion-1.0-lite"/' configs/hymotion.yaml sed -i 's/num_seeds:.*/num_seeds: 1/' configs/hymotion.yaml # 方案2：启用梯度检查点（降低30%显存） # 在inference/text_to_motion.py开头添加： # torch.backends.cuda.enable_mem_efficient_sdp(False) # torch.backends.cuda.enable_flash_sdp(False) # 方案3：降分辨率（修改configs/hymotion.yaml） # motion_resolution: 64 # 默认128，改为64省显存

6.2 Web界面打不开或报错

报错ModuleNotFoundError: No module named 'gradio'→pip install gradio==4.39.0（新版Gradio 4.40+有兼容问题）
界面空白 → 检查浏览器控制台（F12），若报Failed to load resource: net::ERR_CONNECTION_REFUSED，说明Python进程已退出，回看终端报错
生成后无动画 → 检查webui/static/目录是否有生成的.glb文件，没有则修改gradio_app.py中output_dir路径为绝对路径

6.3 动作扭曲或肢体穿模

这不是环境问题，而是Prompt或模型限制：

正确做法：用A person squats slowly, keeping back straight（强调姿态）
错误做法：A person does exercise（太模糊，模型无法理解）
若仍穿模：在configs/hymotion.yaml中增加use_smplh: true（启用更精细的手部模型）

7. 总结：你已经掌握了HY-Motion 1.0的本地化能力

到这里，你已经完成了从零环境搭建到生成首个3D动作的全流程。回顾一下你掌握的关键能力：

环境可控：Ubuntu下PyTorch3D+Diffusers的精准版本组合，再不怕依赖冲突
资源精打细算：用Lite版+单样本生成，在24GB显存GPU上稳定运行
开箱即用：Gradio界面无需写代码，拖拽式生成SMPL骨骼动画
生产就绪：生成的.fbx可直接导入主流3D软件，.npz含完整关节旋转数据

下一步，你可以：
→ 尝试用text_to_motion.py脚本批量生成动作，接入自己的动画管线
→ 把生成的FBX导入Blender，加材质、打光、渲染成短视频
→ 基于hymotion.yaml微调参数，探索不同动作风格的边界

记住，所有技术的价值不在“能跑”，而在“能用”。你现在拥有的，不是一个玩具模型，而是一个可嵌入工作流的3D动作生成引擎。

获取更多AI镜像
想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。

HY-Motion 1.0部署教程：Ubuntu+PyTorch3D+Diffusers环境搭建