UniMate 完整教程：一个统一模型让任意骨架动起来，3D 骨骼动画生成指南

UniMate 完整教程：一个统一模型让任意骨架动起来，3D 骨骼动画生成指南

【免费下载链接】UniMate[SIGGRAPH Asia 2026] UniMate: One Unified Model to Animate Diverse Skeletons项目地址: https://gitcode.com/GitHub_Trending/un/UniMate

想给绑定好骨骼的机器人、动物甚至一朵花写一句文字、不重训模型就生成动画？UniMate 是 SIGGRAPH Asia 2026 接收的统一 3D 骨骼动画生成模型，对任意骨架拓扑都能从一句文本实时生成动作。本文把安装、首次推理、进阶用法与已知坑一次讲清。

🚀 先跑起来：环境配置与首次推理命令

整个项目共用一个 conda 环境，最短推理路径是「官方 checkpoint + 仓库自带示例资产」，四条命令即可看到结果。

第 1 步，拿到代码：

git clone https://gitcode.com/GitHub_Trending/un/UniMate cd UniMate

第 2 步，装环境（Python 3.10，PyTorch 2.5.1 + CUDA 12.4）：

conda create -n unimate python=3.10 -y && conda activate unimate pip install "setuptools<81" pip install -r requirements.txt --no-build-isolation

requirements.txt 里把训练、推理、数据处理全部依赖钉死在同一个版本组合里，--no-build-isolation是必需的，否则 git 依赖会构建失败。

第 3 步，下载官方 checkpoint（约几百 MB，只需 json、npy 和一个 150k 步的权重）：

hf download Linzhan/UniMate --repo-type model --local-dir outputs \ --include "unimate_uniml3d_f60_v3/*.json" --include "unimate_uniml3d_f60_v3/*.npy" \ --include "unimate_uniml3d_f60_v3/checkpoints/checkpoint_step_150000.pt"

第 4 步，首次采样。仓库自带三个处理好的示例资产（Unitree Go2 四足机器人、鹰、鲨鱼），直接驱动 Go2：

python -m unimate.inference.sample --exp_dir outputs/unimate_uniml3d_f60_v3 \ --asset assets/examples/unitree_go2 --prompt "An object trots forward." --output_dir outputs/samples/custom

跑完后你会在outputs/samples/custom/里看到：每条动作的.npy运动文件、渲染好的预览 mp4 / PNG，以及记录资产来源的manifest.json。想直接把动作贴回网格、导出带动画的 GLB / FBX，再加一条：

bash scripts/run_animate_motion.sh outputs/samples/custom

几个实用细节：推理是实时的，给定资产 + 提示词即出 60 帧动作，无逐骨架重训、无测试时优化；scripts/ 下的封装脚本（如 run_sample_motion_text.sh）会自动挑显存最空的 GPU 并激活 conda 环境，新手优先用它们；如果想驱动数据集里的骨架（如truebones:Raindeer、objaverse:<uid>），需要先把 UniML3D 数据集下载到dataset/（约 88 GB，数据集卡片里有更小的部分下载方案）。

🧩 能力全景：UniMate 文本驱动动画的五种用法

一个 checkpoint 同时开五样能力——除核心的文本生成动作外，还有三个免额外训练的「替换式采样」进阶功能，约束帧在每步去噪时被精确固定，而不是靠损失函数软约束。

文本生成动作（核心能力）

写「a dog walks forward」，对应骨架就走起来；同一个模型生成上图里从鸟类、机器人到花朵的全部动作，零针对性训练。关键是提示词风格：照训练字幕的写法，以 "An object" 开头、只描述一个动作（"An object flaps its wings."，而不是 "A blue parrot flaps its wings in the sky."）。两个核心参数：--cfg_scale（默认 3，提示词被无视时升到 5–7，想要更平缓则调低）与--num_repetitions（同一提示词采样多条挑好的）。想批量跑仓库给的完整示例，用--test_cases_json assets/examples/examples.json指向 examples.json。

驱动自己的绑定资产

上面 Go2 的预览图就是 rig_preprocess 的产物：它把你的 GLB / glTF / FBX（有无动画都行）走一遍与训练数据相同的导出 → 关节标注 → 规范化 → 烘焙流程，产出采样器直接可用的资产目录。流程里有个重要的人工审阅停顿：LLM 给每个关节打标并选出定义朝向的 facing pair 后会停下来，让你核对annotation.json再构建——因为这两个条件直接决定生成方向对不对。

python -m data_process.rig_preprocess run --input robot.glb --output_dir outputs/rig/robot # 审阅 REVIEW.md、修正 annotation.json 后： python -m data_process.rig_preprocess run --input robot.glb --output_dir outputs/rig/robot \ --annotation outputs/rig/robot/annotation.json

之后把--asset outputs/rig/robot传给采样器即可。CPU 就能跑，单个资产几秒到一分钟。

动作补间

只给首尾关键帧，模型自动补全中间平滑过渡——动画师"中间帧"工作的自动化版。测试用例的 key 必须是磁盘上真实存在的 clip（格式<object_type>-<clip_id>），命令：

KEEP_FRAMES="0,-1" bash scripts/run_sample_motion_inbetween.sh \ outputs/unimate_uniml3d_f60_v3 cases.json

--keep_frames收带符号帧号，负数从窗口末尾倒数，"0,-1"即首尾帧全锁、中间全生成。

文本引导动作编辑

想让角色换动作但躯干保持原样？--keep_joints把指定关节（匹配骨架自身骨骼名或清洗后词表，不区分大小写）在每一帧锁在原轨迹上，换句提示词重新生成其余部分：

KEEP_JOINTS="Neck,Head" bash scripts/run_sample_motion_edit.sh \ outputs/unimate_uniml3d_f60_v3 cases.json

动作扩展

测试用例的值从单条提示词变成提示词列表，模型逐段生成并自动衔接接缝帧（--expand_overlap控制相邻段共享的帧数，默认建议 10 左右），把"站起来 → 向前走 → 原地转身"串成一条长序列：

EXPAND_OVERLAP=10 bash scripts/run_sample_motion_expand.sh \ outputs/unimate_uniml3d_f60_v3 cases.json

三种模式共用同一套替换式采样机制，各写入--output_dir下的inbetween/、motion_edit/、motion_expand/子目录并附记录约束的 JSON；注意它们互相排斥、都要求--cfg_scale > 1.0，且补间与编辑需要真实 clip 在盘上（数据集 clip，或自定义资产用--save_clips保留的 clip）。

🏗️ 仓库结构速览：UniML3D 数据集与模型架构

模型的"全骨架通吃"来自三件事：一个把 7000 多骨架统一到同一规范下的动作数据集、拓扑感知的注意力结构、流匹配训练范式。

训练数据 UniML3D：

模型与训练技术路线：

configs/ 下 8 份 JSON = 4 种数据组合（全量 UniML3D / Truebones / Mixamo / Objaverse）× 2 种模型变体（graph_adaln/full_cross_attn），改 JSON 即可切换实验。训练一条命令启动（多卡加--num_processes 8），前提是已下载数据集特征到dataset/features/：

accelerate launch -m unimate.training.train --config configs/uniml3d_60frames_graph_adaln.json

仓库目录速览：

许可方面注意区分：代码是MIT（见 LICENSE），但发布的 checkpoint 是 CC BY-NC 4.0，仅限非商业用途；数据集仍受各自源许可约束（Mixamo 的 Adobe 条款、Objaverse-XL 各对象许可、Truebones 商业授权）。

⚠️ 边界与坑：它还做不到的事

官方团队坦承这是"任意骨架文生动画的早期探索"，不少骨架 × 动作组合仍会失败。踩坑前先看这张清单：

另有几条文档里明确写了的限制：

• 补间与动作编辑依赖磁盘上的真实 clip，纯自定义资产没存 clip 就玩不了这两个功能（记得--save_clips）；三种进阶模式互相排斥。
• Objaverse 数据质量参差：不少绑定有 rest pose 颠倒、拼接多段动作等缺陷，直接全量训练可能不稳定，README 专门给了排查方法（先只用 Mixamo + Truebones 对照）。
• 发布版 UniML3D 的字幕经过重处理，不一定与论文和项目页展示的提示词一致。
• Truebones 动作文件因商业授权不随仓库再分发，想完整复现训练数据需自行购买原包。
• 生成结果有随机性，同一条提示词不同噪声结果差异不小——挑样本是日常工作的一部分。

📌 写在最后：谁该把它加进工具箱

三类人用 UniMate 的收益差别很大，对号入座：

• 🎨3D 内容创作者：用它给绑定好的角色批量出初稿动画，再用 run_animate_motion.sh 一行命令烘焙成 GLB / FBX 进交付流程。注意官方 checkpoint 是 CC BY-NC 4.0，商业项目请走 data_process/ 的general数据槽位自训模型。
• 🤖游戏 / 机器人研发：四足机器人、机械臂这类非人形骨架正是它的主场。流程上先rig_preprocess处理自有资产，重点人工核对 facing pair——朝向标错，动作方向必错。
• 🔬研究者：统一骨架建模 + 流匹配范式 + 图注意力变体对比，是一个完整可复现的开源参考实现，8 份 config 即论文实验矩阵。

如果你跑出了失败案例，别只默默绕过——官方团队明确要求提 issue 反馈，这些失败案例正是这个"早期"模型走向下一代的主要输入。

【免费下载链接】UniMate[SIGGRAPH Asia 2026] UniMate: One Unified Model to Animate Diverse Skeletons项目地址: https://gitcode.com/GitHub_Trending/un/UniMate