目录

• 目录
• 概述
• 更新
• 要求
• 安装
• 模型检查点
• 数据格式
• 运行推理
• 训练
• 故障排除
• 引用

概述

Motus 是一种 统一的潜在动作世界模型，它利用现有的预训练模型和丰富、可共享的动作信息。Motus 引入了 Transformer 混合体（MoT） 架构，以整合三个专家（理解、动作和视频生成），并采用 UniDiffuser 风格调度器，实现不同建模模式之间的灵活切换（世界模型、视觉-语言-动作模型、逆动力学模型、视频生成模型以及视频-动作联合预测模型）。Motus 进一步利用 光流 来学习 潜在动作，并采用 三阶段训练流程 和 六层数据金字塔，从而提取像素级的“动作增量”，并支持大规模动作预训练。

组件	基础模型	参数量
VGM（视频生成模型）	Wan2.2-5B	~5.00B
VLM（视觉-语言模型）	Qwen3-VL-2B	~2.13B
动作专家	-	~641.5M
理解专家	-	~253.5M
总计	-	~8B

关键结果（RoboTwin 2.0 模拟。 在每个任务中使用 50 个干净数据和 500 个随机化数据条目，我们将所有 50 个任务的数据合并进行多任务训练。）：

• 87.02% 的平均成功率（比 X-VLA 高 15%，比 π₀.₅ 高 45%）

更新

• [2025-12-16] Motus 初始发布，包含预训练检查点和训练代码。
• [2025-12-20] 简单的 RoboTwin 推理
• [2025-12-24] 支持 LeRobotDataset 格式
• [2025-12-24] 优化的训练脚本
• [2025-12-26] 支持 MultiLeRobotDataset 格式
• [2025-12-27] RoboTwin 原始数据转换
• [2025-12-27] 三视角图像拼接脚本

我们欢迎社区成员帮助维护和扩展 Motus。欢迎加入 Motus 社区，共同贡献！

要求

模式	显存	推荐显卡
推理（使用预编码 T5）	> 24 GB	RTX 5090
推理（不使用预编码 T5）	~ 41 GB	A100 (40GB) / A100 (80GB) / H100 / B200
训练	> 80 GB	A100 (80GB) / H100 / B200

安装

# 克隆仓库
git clone https://github.com/thu-ml/Motus.git
cd Motus

# 创建 conda 环境
conda create -n motus python=3.10 -y
conda activate motus

# 安装 torch（cuda12.8）
pip install torch==2.7.1 torchvision==0.22.1 --index-url https://download.pytorch.org/whl/cu128

# 安装 flash 
pip install flash-attn --no-build-isolation

# 安装 Motus 依赖
pip install -r requirements.txt

# （可选）安装 lerobot 依赖
pip install --no-deps lerobot==0.3.2
pip install -r requirements/lerobot.txt

模型检查点

我们为不同的用例提供了多个检查点：

模型	用例	描述	检查点路径
Motus_Wan2_2_5B_pretrain	预训练 / VGM 主干	第一阶段 VGM 预训练检查点	motus-robotics/Motus_Wan2_2_5B_pretrain
Motus	微调	第二阶段潜在动作预训练检查点	motus-robotics/Motus
Motus_robotwin2	推理 / 微调	第三阶段 RoboTwin2 微调检查点	motus-robotics/Motus_robotwin2

下载检查点：

# 创建预训练模型目录
mkdir -p pretrained_models

# 下载 Motus 检查点
huggingface-cli download motus-robotics/Motus_Wan2_2_5B_pretrain --local-dir ./pretrained_models/Motus_Wan2_2_5B_pretrain
huggingface-cli download motus-robotics/Motus --local-dir ./pretrained_models/Motus
huggingface-cli download motus-robotics/Motus_robotwin2 --local-dir ./pretrained_models/Motus_robotwin2

# 下载基础模型
huggingface-cli download Qwen/Qwen3-VL-2B-Instruct --local-dir ./pretrained_models/Qwen3-VL-2B-Instruct
huggingface-cli download Wan-AI/Wan2.2-TI2V-5B --local-dir ./pretrained_models/Wan2.2-TI2V-5B

在您的特定机器人配置文件中更新配置路径（例如 configs/robotwin.yaml、configs/ac_one.yaml 或其他机器人配置文件）：

model:
  wan:
    checkpoint_path: "./pretrained_models/Motus_Wan2_2_5B_pretrain"
    config_path: "./pretrained_models/Motus_Wan2_2_5B_pretrain"
    vae_path: "./pretrained_models/Wan2.2-TI2V-5B/Wan2.2_VAE.pth"
  vlm:
    checkpoint_path: "./pretrained_models/Qwen3-VL-2B-Instruct"
    config_path: "./pretrained_models/Qwen3-VL-2B-Instruct"

数据格式

Motus 支持三种类型的数据集，并具有特定的目录结构，以实现最佳的训练和推理效果。

📖 查看详细指南： 数据格式指南

快速概览：

• RoboTwin 2.0：带有干净/随机化划分的模拟数据
• 真实世界：AC-One、Aloha-Agilex-2 机器人数据

数据转换工具：

• RoboTwin 数据转换器
• 多摄像头拼接

运行推理

📖 查看详细指南： 推理指南

• RoboTwin 2.0：评估设置
• 真实世界：无需机器人环境的最小化推理

训练

Motus 遵循 三阶段训练流程：

阶段	数据	训练
预训练基础模型	第1层：网络数据	VGM 和 VLM
第1阶段（VGM 训练）	第2层：第一人称视角的人类视频 第3层：合成数据 第5层：多机器人任务轨迹	仅 VGM
第2阶段（Motus 预训练）	第2层：第一人称视角的人类视频 第3层：合成数据 第4层：与任务无关的数据 第5层：多机器人任务轨迹	Motus（所有3个专家，使用潜在动作）
第3阶段（Motus SFT）	第6层：目标机器人任务轨迹	Motus（所有3个专家，使用动作）

六层数据金字塔如图所示：

📖 查看详细指南： 训练指南

数据准备：

• RoboTwin 数据集转换器
• 多摄像头拼接

故障排除

📖 详细指南：

• 推理问题
• 训练问题
• 数据格式问题

引用

如果您觉得我们的工作有所帮助，请引用我们：

@misc{bi2025motusunifiedlatentaction,
      title={Motus: 统一潜在动作世界模型}, 
      author={Hongzhe Bi 和 Hengkai Tan 和 Shenghao Xie 和 Zeyuan Wang 和 Shuhe Huang 和 Haitian Liu 和 Ruowen Zhao 和 Yao Feng 和 Chendong Xiang 和 Yinze Rong 和 Hongyan Zhao 和 Hanyu Liu 和 Zhizhong Su 和 Lei Ma 和 Hang Su 和 Jun Zhu},
      year={2025},
      eprint={2512.13030},
      archivePrefix={arXiv},
      primaryClass={cs.CV},
      url={https://arxiv.org/abs/2512.13030}, 
}

谢谢！

Motus 快速上手指南

Motus 是一个统一的潜在动作世界模型（Unified Latent Action World Model），集成了理解、动作和视频生成三大专家模块，支持多种机器人任务建模。

环境准备

系统要求

• 操作系统: Linux (推荐 Ubuntu 20.04+)
• Python 版本: 3.10
• CUDA 版本: 12.8

硬件要求

根据使用场景不同，显存需求如下：

模式	显存需求	推荐显卡
推理 (预编码 T5)	> 24 GB	RTX 5090
推理 (无预编码 T5)	~ 41 GB	A100 (40GB/80GB) / H100 / B200
训练	> 80 GB	A100 (80GB) / H100 / B200

安装步骤

1. 克隆仓库

git clone https://github.com/thu-ml/Motus.git
cd Motus

2. 创建并激活 Conda 环境

conda create -n motus python=3.10 -y
conda activate motus

3. 安装 PyTorch (CUDA 12.8)

建议使用清华镜像源加速下载：

pip install torch==2.7.1 torchvision==0.22.1 --index-url https://download.pytorch.org/whl/cu128

4. 安装 Flash Attention

pip install flash-attn --no-build-isolation

5. 安装项目依赖

pip install -r requirements.txt

6. (可选) 安装 LeRobot 支持

如需处理特定机器人数据集，可安装此依赖：

pip install --no-deps lerobot==0.3.2
pip install -r requirements/lerobot.txt

基本使用

1. 下载模型权重

使用 huggingface-cli 下载预训练模型和基础模型到本地 pretrained_models 目录：

mkdir -p pretrained_models

# 下载 Motus 系列检查点
huggingface-cli download motus-robotics/Motus_Wan2_2_5B_pretrain --local-dir ./pretrained_models/Motus_Wan2_2_5B_pretrain
huggingface-cli download motus-robotics/Motus --local-dir ./pretrained_models/Motus
huggingface-cli download motus-robotics/Motus_robotwin2 --local-dir ./pretrained_models/Motus_robotwin2

# 下载基础模型 (VLM & VGM Backbone)
huggingface-cli download Qwen/Qwen3-VL-2B-Instruct --local-dir ./pretrained_models/Qwen3-VL-2B-Instruct
huggingface-cli download Wan-AI/Wan2.2-TI2V-5B --local-dir ./pretrained_models/Wan2.2-TI2V-5B

提示: 国内用户若访问 Hugging Face 较慢，可设置镜像环境变量： export HF_ENDPOINT=https://hf-mirror.com

2. 配置模型路径

修改对应的配置文件（例如 configs/robotwin.yaml），确保路径指向刚才下载的模型目录：

model:
  wan:
    checkpoint_path: "./pretrained_models/Motus_Wan2_2_5B_pretrain"
    config_path: "./pretrained_models/Motus_Wan2_2_5B_pretrain"
    vae_path: "./pretrained_models/Wan2.2-TI2V-5B/Wan2.2_VAE.pth"
  vlm:
    checkpoint_path: "./pretrained_models/Qwen3-VL-2B-Instruct"
    config_path: "./pretrained_models/Qwen3-VL-2B-Instruct"

3. 运行推理

以最简单的 RoboTwin 2.0 仿真环境推理为例（具体脚本参数请参考 inference/robotwin/Motus/README.md）：

python inference/robotwin/run_inference.py \
    --config configs/robotwin.yaml \
    --checkpoint ./pretrained_models/Motus_robotwin2 \
    --task <your_task_name>

对于真实世界机器人或无需机器人环境的极简推理，请参考 INFERENCE.md 中的详细指令调整输入数据格式。