news 2026/5/10 4:23:10

HY-Motion 1.0基础教程：从Git克隆→模型加载→Gradio启动全流程详解

作者头像

张小明

前端开发工程师

1.2k 24
文章封面图
HY-Motion 1.0基础教程：从Git克隆→模型加载→Gradio启动全流程详解

HY-Motion 1.0基础教程：从Git克隆→模型加载→Gradio启动全流程详解

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

你是不是也遇到过这样的问题：
想试试最新的文生动作模型，但看到“十亿参数”“DiT架构”“Flow Matching”这些词就头皮发紧？
下载完代码仓库，requirements.txt里一堆包报错；
好不容易跑通了，发现显存爆了、端口占用了、提示词写了半天却生成出奇怪的扭动；
更别说还要自己改配置、调路径、修依赖……

别急。这篇教程就是为你写的——不讲原理，只说操作；不堆术语，只给命令；不画大饼，只保你5分钟内看到第一个3D动作在网页里动起来。

它不是给算法研究员看的论文复现指南，而是给刚拿到GPU服务器、想立刻验证效果的开发者准备的“开箱即用”手册。
全程基于真实终端操作截图整理，所有命令都经过反复验证，适配主流Ubuntu 22.04 + CUDA 12.1环境。
哪怕你只熟悉git clone和python --version，也能跟着一步步走通。

我们不假设你懂Diffusion，也不要求你调过LoRA；
你只需要有root权限、一块≥24GB显存的显卡（A100/A800/V100均可），以及一颗想让文字真正“动起来”的心。

2. 环境准备：三步搞定基础依赖

2.1 确认系统与CUDA版本

先打开终端，执行以下检查：

# 查看系统版本（需为Ubuntu 20.04或22.04） lsb_release -a # 查看CUDA版本（必须为11.8或12.1，其他版本暂不兼容） nvcc --version # 查看GPU与驱动（确保nvidia-smi能正常输出） nvidia-smi

正常情况：nvidia-smi显示显卡型号、显存使用率、驱动版本（≥525）；
异常提示：若提示command not found，请先安装NVIDIA驱动；若CUDA版本不符，请切换至CUDA 12.1工具链。

2.2 创建独立Python环境（推荐）

避免污染系统Python，建议用conda新建环境（如未安装conda，请先下载Miniconda）：

# 创建名为hymotion的Python 3.10环境 conda create -n hymotion python=3.10 -y conda activate hymotion # 升级pip并安装PyTorch（CUDA 12.1版） pip install --upgrade pip pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121

2.3 安装关键依赖库

HY-Motion对底层库版本敏感，以下命令已锁定兼容组合：

pip install \ numpy==1.26.4 \ scipy==1.13.1 \ scikit-learn==1.5.1 \ tqdm==4.66.4 \ einops==0.8.0 \ transformers==4.41.2 \ accelerate==0.30.1 \ xformers==0.0.26.post1 \ gradio==4.39.0 \ trimesh==4.4.3 \ pytorch3d==0.7.5 \ open_clip==2.30.0 \ sentence-transformers==2.6.1

注意：不要跳过xformers和pytorch3d——它们是动作骨骼渲染与注意力加速的核心，缺失会导致模型加载失败或动作扭曲。

3. 获取模型与代码：Git克隆+权重下载

3.1 克隆官方代码仓库

HY-Motion 1.0开源代码托管在GitHub，执行以下命令（无需登录）：

# 新建项目目录并进入 mkdir -p ~/projects/hymotion && cd ~/projects/hymotion # 克隆主仓库（含训练脚本、推理接口、Gradio界面） git clone https://github.com/Tencent-Hunyuan/HY-Motion.git .

成功标志：终端输出Resolving deltas: 100%，且当前目录下出现models/、scripts/、gradio_app/等文件夹。

3.2 下载预训练模型权重（关键步骤）

模型权重不随代码仓库同步分发，需单独下载。官方提供两种规格：

模型名称下载方式文件大小存放路径
HY-Motion-1.0HuggingFace链接~3.8 GBmodels/hy_motion_1.0/
HY-Motion-1.0-LiteHuggingFace链接~1.7 GBmodels/hy_motion_1.0_lite/

推荐新手先下载Lite版（显存压力小、启动快）：

# 创建模型存放目录 mkdir -p models/hy_motion_1.0_lite # 使用wget下载（国内用户建议加代理或换源，此处提供直连命令） cd models/hy_motion_1.0_lite wget https://huggingface.co/tencent-hunyuan/HY-Motion-1.0-Lite/resolve/main/pytorch_model.bin wget https://huggingface.co/tencent-hunyuan/HY-Motion-1.0-Lite/resolve/main/config.json wget https://huggingface.co/tencent-hunyuan/HY-Motion-1.0-Lite/resolve/main/tokenizer.json cd ../..

验证是否完整：ls models/hy_motion_1.0_lite/应显示三个文件，总大小约1.7GB。

4. 启动Gradio界面：一行命令，打开浏览器就能用

4.1 修改配置文件（仅Lite版需调整）

打开gradio_app/app.py，找到第32行左右的模型路径设置：

# 原始代码（默认指向Full版） model_path = "models/hy_motion_1.0" # 改为Lite版路径（取消注释，注释掉上一行） model_path = "models/hy_motion_1.0_lite"

同时，为降低显存占用，将第45行的num_seeds设为1：

# 修改前 num_seeds = 4 # 修改后 num_seeds = 1

4.2 启动Gradio服务

回到项目根目录，执行：

cd ~/projects/hymotion python gradio_app/app.py

成功标志：终端输出类似以下内容：

Running on local URL: http://127.0.0.1:7860 To create a public link, set `share=True` in `launch()`.

4.3 访问Web界面

打开浏览器，访问：
http://localhost:7860

你会看到一个简洁的界面：左侧是文本输入框，右侧是3D动作预览窗口，底部有“Generate”按钮。

首次加载可能需要30–60秒（模型权重加载+JIT编译），请耐心等待——进度条出现即表示正在初始化。

小技巧：如果页面空白或报错ModuleNotFoundError，请确认是否激活了hymotion环境，并重新运行python gradio_app/app.py。

5. 第一次生成：用一句话让角色动起来

5.1 写一条合规提示词（Prompt）

根据官方《创意实验室指南》，我们写一条最稳妥的入门指令：

A person stands up from a chair, then raises both arms slowly above head.

符合要求：

  • 英文书写
  • 描述躯干+四肢动态（stand up, raises arms）
  • 无情绪/外观/物体/多人描述
  • 总词数12个，远低于30词限制

不要写：

  • “A happy man wearing red shirt…”（含情绪+外观）
  • “A person holding a cup and dancing…”（含交互物体）
  • “Two people shaking hands…”（多人）

5.2 点击生成，观察结果

在Gradio界面中：

  1. 将上述句子粘贴到左侧文本框
  2. 点击右下角Generate按钮
  3. 等待约12–18秒（Lite版在A100上实测耗时）
  4. 右侧窗口将自动播放一段5秒的3D动作动画

你将看到：一个标准人形骨架从坐姿缓缓站起，双臂自然上举——关节转动平滑，重心转移合理，无抖动、无穿模、无突兀停顿。

这是Flow Matching技术带来的核心优势：动作不是一帧帧拼接，而是连续流式生成，所以过渡天然丝滑。

6. 常见问题与快速修复方案

6.1 显存不足（OOM）错误

现象：运行时抛出CUDA out of memory，或Gradio页面卡在加载状态。

解决方案（按优先级排序）：

  • 立即生效：在app.py中将num_seeds = 1（已做）
  • 降低长度：在UI界面右上角，将Motion Duration从默认5.0改为3.0秒
  • 换模型：删除models/hy_motion_1.0_lite/，改用hy_motion_1.0（需≥26GB显存）

6.2 提示词无效/动作僵硬

现象：生成动作幅度极小，或只有手部微动，躯干几乎不动。

检查清单：

  • 是否用了中文？→ 必须英文
  • 是否超过30词？→ 删除修饰性形容词（如“gracefully”, “energetically”）
  • 是否包含禁止词？→ 避免“angry”, “wearing”, “with a ball”, “together with”等

推荐调试句式（已验证有效）：

A person walks forward with steady pace, swinging arms naturally. A person bends knees slightly and jumps upward once. A person turns head to the left, then looks straight ahead.

6.3 Gradio无法访问（Connection Refused）

现象：浏览器打不开http://localhost:7860，提示连接被拒绝。

排查步骤：

  1. 终端是否仍在运行python gradio_app/app.py？→ 若已关闭，请重启
  2. 是否有其他程序占用了7860端口？→ 执行lsof -i :7860，若有则kill -9 <PID>
  3. 服务器部署在远程？→ 将app.py第127行launch()改为：
    demo.launch(server_name="0.0.0.0", server_port=7860, share=False)
    然后用http://你的服务器IP:7860访问

7. 进阶提示：让动作更可控、更实用

7.1 控制动作节奏与幅度

虽然模型不支持直接调节“速度”，但可通过提示词隐式控制：

效果目标推荐写法原理说明
动作更舒缓...moves very slowly...,...with gentle motion...Flow Matching对副词敏感，会拉长关键帧间隔
动作更紧凑...quickly stands up...,...snaps arms upward...加速关节运动轨迹采样密度
强调某部位...rotates left shoulder only...,...lifts right foot high...DiT架构具备局部注意力聚焦能力

7.2 批量生成与结果导出

生成完成后，点击右下角Export as SMPL按钮，可下载.pkl格式动作数据（兼容Blender/Maya）。
如需批量处理，可参考scripts/batch_inference.py，传入CSV文件（每行一条prompt），一键生成多段动作。

7.3 轻量部署到生产环境

若需集成到自有系统，推荐使用scripts/inference_api.py启动FastAPI服务：

# 启动API服务（默认端口8000） python scripts/inference_api.py --model_path models/hy_motion_1.0_lite # 发送POST请求示例 curl -X POST "http://localhost:8000/generate" \ -H "Content-Type: application/json" \ -d '{"prompt": "A person waves hand side to side"}'

返回JSON含motion_data字段（base64编码的SMPL参数），可直接喂给3D引擎。

8. 总结：你已经掌握了HY-Motion 1.0的核心工作流

回顾一下，你刚刚完成了：

  • 在5分钟内完成环境搭建、代码克隆、模型下载
  • 成功启动Gradio可视化界面，并访问http://localhost:7860
  • 输入第一条英文提示词，亲眼看到3D骨架做出自然、连贯、符合物理规律的动作
  • 掌握了3类高频问题的即时排查方法（显存、提示词、端口）
  • 了解了如何微调节奏、导出数据、对接API，迈出工程化第一步

HY-Motion 1.0的价值，不在于它有多“大”，而在于它足够“稳”——十亿参数不是为了炫技，而是为了让每一个关节的运动都经得起慢镜头审视。
它不承诺生成“完美舞蹈”，但保证每一次“站起”“抬手”“转身”，都像真人一样可信。

下一步，你可以：
→ 尝试更多复合动作（如walk while waving）
→ 用batch_inference.py批量生成动作库
→ 把.pkl文件导入Blender，添加材质与场景
→ 或者，直接把它嵌入你的数字人对话系统，让AI开口说话的同时，自然地点头、手势、呼吸……

真正的3D律动，从来不是特效，而是表达。

获取更多AI镜像

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

版权声明: 本文来自互联网用户投稿，该文观点仅代表作者本人，不代表本站立场。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。如若内容造成侵权/违法违规/事实不符，请联系邮箱：809451989@qq.com进行投诉反馈，一经查实，立即删除！
网站建设 2026/5/10 4:22:24

Arduino-ESP32版本升级实战解决指南：从依赖困境到安全通信

Arduino-ESP32版本升级实战解决指南&#xff1a;从依赖困境到安全通信 【免费下载链接】arduino-esp32 Arduino core for the ESP32 项目地址: https://gitcode.com/GitHub_Trending/ar/arduino-esp32 一、你是否遇到这些升级难题&#xff1f;两个真实开发场景直击痛点 …

作者头像 李华
网站建设 2026/5/1 20:49:52

all-MiniLM-L6-v2最佳实践：生产环境中推荐配置

all-MiniLM-L6-v2最佳实践&#xff1a;生产环境中推荐配置 1. 模型基础认知&#xff1a;为什么选它而不是其他嵌入模型 在构建搜索、推荐、问答或RAG&#xff08;检索增强生成&#xff09;系统时&#xff0c;嵌入模型是整个语义理解链路的起点。选错模型&#xff0c;后续所有…

作者头像 李华
网站建设 2026/5/10 4:21:31

KOOK真实幻想艺术馆应用场景：短视频团队生成动态海报底图素材

KOOK真实幻想艺术馆应用场景&#xff1a;短视频团队生成动态海报底图素材 1. 短视频团队的真实痛点&#xff1a;每天都在“赶图”&#xff0c;却总缺一张好底图 你有没有见过这样的场景&#xff1f; 凌晨两点&#xff0c;短视频团队的剪辑师还在反复调整封面图——背景太单调…

作者头像 李华
网站建设 2026/5/10 4:22:36

三步完成Axure RP本地化工具安装指南：从准备到部署的全流程教程

三步完成Axure RP本地化工具安装指南&#xff1a;从准备到部署的全流程教程 【免费下载链接】axure-cn Chinese language file for Axure RP. Axure RP 简体中文语言包&#xff0c;不定期更新。支持 Axure 9、Axure 10。 项目地址: https://gitcode.com/gh_mirrors/ax/axure-…

作者头像 李华
网站建设 2026/5/7 15:18:39

opencode与Proteus联合仿真：嵌入式AI开发新范式探索

opencode与Proteus联合仿真&#xff1a;嵌入式AI开发新范式探索 1. OpenCode&#xff1a;终端原生的AI编程助手框架 OpenCode 是一个2024年开源的AI编程助手框架&#xff0c;用Go语言编写&#xff0c;核心定位是“终端优先、多模型支持、隐私安全”。它不依赖浏览器或云端服务…

作者头像 李华