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.10PyTorch 2.5.1 CUDA 12.4conda create -n unimate python3.10 -y conda activate unimate pip install setuptools81 pip install -r requirements.txt --no-build-isolationrequirements.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 四足机器人、鹰、鲨鱼直接驱动 Go2python -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 同时开五样能力——除核心的文本生成动作外还有三个免额外训练的「替换式采样」进阶功能约束帧在每步去噪时被精确固定而不是靠损失函数软约束。能力一句话定位触发方式文本生成动作一句提示词 → 60 帧动作--prompt/--test_cases_json驱动自定义资产自己的 GLB / FBX 同样文生动作--asset rig_preprocess动作补间固定首尾关键帧自动补中间过渡--inbetween --keep_frames文本引导动作编辑锁定部分关节其余按新提示词重生成--motion_edit --keep_joints动作扩展多条提示词拼成一条长动画--motion_expand文本生成动作核心能力写「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_FRAMES0,-1 bash scripts/run_sample_motion_inbetween.sh \ outputs/unimate_uniml3d_f60_v3 cases.json--keep_frames收带符号帧号负数从窗口末尾倒数0,-1即首尾帧全锁、中间全生成。文本引导动作编辑想让角色换动作但躯干保持原样--keep_joints把指定关节匹配骨架自身骨骼名或清洗后词表不区分大小写在每一帧锁在原轨迹上换句提示词重新生成其余部分KEEP_JOINTSNeck,Head bash scripts/run_sample_motion_edit.sh \ outputs/unimate_uniml3d_f60_v3 cases.json动作扩展测试用例的值从单条提示词变成提示词列表模型逐段生成并自动衔接接缝帧--expand_overlap控制相邻段共享的帧数默认建议 10 左右把站起来 → 向前走 → 原地转身串成一条长序列EXPAND_OVERLAP10 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项目内容规模13,769 条带文本配对的运动片段覆盖 7,430 个骨架来源Mixamo人形、Truebones ZOO动物商业授权不可再分发、Objaverse-XL绑定资产骨架拓扑双足、四足、鸟类、海洋生物、昆虫、蛇形、铰接刚体处理流水线下载 → 导出 → 渲染 → VLM 字幕 → 关节标注 → 特征提取 → 网格驱动详见 data_process/README.md模型与训练技术路线模块选择训练范式Flow matching网络预测噪声与数据间线性插值的速度场另加测地线旋转损失与速度平滑损失两个辅助项文本编码google/flan-t5-base提示词经 adaLN 调制或 cross-attention 注入注意力变体graph帧内空间/ 关节间时间分解带图距离、边类型与深度偏置full展平 joint×time token 做整体注意力采样规格每片段 60 帧关节数 5–70训练上限最多接受 71引导机制classifier-free guidance默认cfg_scale3.0推理时可自由调节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仓库目录速览目录作用unimate/models/去噪网络graph / full 两种注意力变体、扩散与流匹配核心、T5 文本编码器unimate/dataset/数据加载、在线拓扑增强与条件构造unimate/training/训练循环、EMA、TensorBoard 日志入口 train.pyunimate/inference/采样入口 sample.py 及补间 / 编辑 / 扩展三应用unimate/tools/文本嵌入预计算把 T5 移出训练主循环data_process/UniML3D 全流水线导出、渲染、VLM 字幕、关节标注、特征提取、网格驱动data_process/rig_preprocess/自带资产预处理工具导出 → 标注 → 审阅 → 构建configs/8 份训练配置 JSONscripts/自动选卡、封装训练与各类采样的一键脚本assets/examples/Go2 / 鹰 / 鲨鱼三个开箱即用的示例资产许可方面注意区分代码是MIT见 LICENSE但发布的 checkpoint 是 CC BY-NC 4.0仅限非商业用途数据集仍受各自源许可约束Mixamo 的 Adobe 条款、Objaverse-XL 各对象许可、Truebones 商业授权。⚠️ 边界与坑它还做不到的事官方团队坦承这是任意骨架文生动画的早期探索不少骨架 × 动作组合仍会失败。踩坑前先看这张清单坑影响应对骨架超过 70 个关节模型最多接受 71 个关节先删掉手指、面部、配饰类骨骼再采样骨骼命名不规范机器人最常见自动关节标签 / facing pair 可能标错动作朝向全乱走 rig_preprocess 的审阅步骤核对annotation.jsonrest pose 躺平或倒立不会自动扶正--rest_rotation x180之类参数手动旋转资产没有蒙皮网格采样可用但无规范化 GLB驱动不了网格summary.json会说明原因只生成关节旋转 根轨迹滑动 / 拉伸类骨骼保持静止长度预期行为summary.json会报告提示词写成角色描述模型遵循度差用 An object 单一动作 风格cfg_scale升到 5–7多采几条挑另有几条文档里明确写了的限制补间与动作编辑依赖磁盘上的真实 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考