SuperMimic-Repro-Sim2Real

中文 | English

这个仓库教 Unitree G1 人形机器人模仿人的动作。先在仿真里训练，让机器人学会跟着一段参考动作做；训练好的策略再导出，放到真机上跑。我们用它让一台 G1 完整跳完了一段约 46 秒的舞蹈。

方法来自论文 SuperMimic（Liao 等，CoRL 2026）：它先训练一个神经网络代替物理仿真器，预测机器人下一步怎么动（论文叫"世界模型"）。这个网络能求导，所以可以像训练普通网络一样，直接用反向传播优化控制策略，不用靠强化学习反复试错。

_{左：人类原视频；右：G1 真机。点击看带声音的完整视频（约 46 秒）。}

_{闪身步 Pro（v1.1，模型 e24_0355000）：带两次快速转体和单脚落地的跳跃。左：人类原视频；右：G1 真机。点击看带声音的视频（约 15 秒）。详见 docs/REAL_ROBOT_LEAN35KFS.md。}

实机演示视频和预训练模型在 GitHub Release。

安全警告：真机代码会直接控制 G1 的电机。模型、参数或操作出错，机器人可能摔倒、损坏或伤人。请只在吊架保护下运行，并且始终有人拿着遥控器，随时准备按 L2+B 让机器人进入阻尼（软急停）。上机前完整读一遍 docs/DEPLOY_G1.md。本项目按原样提供，使用风险自负。

• 代码不是从零写的。训练算法部分基于 Yuxi Liu 的开源复现 CuboiLeo/SuperMimic-Reproduced（MIT 许可证）。
• 我们在它上面加了：大数据集训练、自定义舞蹈动作、从视频提取动作的工具，以及整套上真机的部署代码。
• 这是非官方复现，与论文作者和 Unitree 都没有关系。论文没写清楚的细节是我们自己定的，所以数字不一定和论文一致。

得分 1.0 表示完全跟上参考动作，越高越好。

• 严格按论文设置，LAFAN1 得分明显低于论文。加上这个位置输入就能追上，但真机测不到自己在房间里的位置，所以这种模型上不了真机。
• 真机：G1 完整跳完了 4 段舞蹈连起来的约 46 秒动作，身体倾斜和参考动作最多差 16.3°（超过 20° 程序会自动停止）。
• v1.1 新增（2026-10）：G1 连续两次从头到尾跳完了约 22 秒的 shanshen_duosuomao_lean35kfs_pad2。这段舞有两次快速转体和一次单脚落地的跳跃，用的模型是 e24_0355000，两次都挂着保护绳，但绳是松的。这只是同一个模型跑了两次，也没有做消融实验。在它之前，9 个模型在这段舞上的真机尝试全部失败。失败原因、我们改了什么、哪些仿真测试能预测真机结果，见 docs/REAL_ROBOT_LEAN35KFS.md（英文）。
• 详细数字和原因见 docs/METHOD.md。

训练需要 Linux 和 NVIDIA 显卡（驱动 ≥ 580）；真机那一侧只要 numpy、onnxruntime 和 Unitree SDK。依赖用 uv 管理。

git clone https://github.com/NJU-R-L-Group-Embodied-Lab/SuperMimic-Repro-Sim2Real.git && cd SuperMimic-Repro-Sim2Real
uv sync --group dev
uv run pytest tests -q          # 部分测试需要 GPU 或已转换的数据

数据集不随仓库分发，请自己下载并遵守它们的许可证。最小的例子是 LAFAN1，下载后转成训练用的格式：

uv run hf download lvhaidong/LAFAN1_Retargeting_Dataset --repo-type dataset --local-dir data/raw/lafan1
uv run python scripts/data/csv_to_npz_batch.py --input-dir data/raw/lafan1/g1 --output-dir data/npz/lafan1 --input-fps 30 --workers 16

大数据集 BONES-SEED 的下载、筛选和打包见 docs/METHOD.md。

uv run sm-train --run-name lafan1_paper --data.npz-dir data/npz/lafan1 \
  --env.num-envs 4096 --policy-trainer.batch-size 4096 --schedule.max-hours 3

• 默认参数按论文设置。所有选项用 uv run sm-train --help 查看。
• 模型每隔一段时间存到 logs/<run>/ckpt_XXXXXXX.pt，训练曲线用 TensorBoard 看。
• 用 BONES-SEED 或多卡训练，见 docs/METHOD.md。

# 对每段动作从头到尾跑一遍，算得分和失败数
uv run python scripts/eval_benchmark.py --ckpt logs/lafan1_paper/ckpt_XXXXXXX.pt --npz-dir data/npz/lafan1
# 打开窗口回放（没有显示器时会改用浏览器 http://localhost:8080）
uv run python scripts/play.py --ckpt logs/lafan1_paper/ckpt_XXXXXXX.pt --clips dance1_subject1
# 不开窗口直接渲染 mp4（实体 = 策略，半透明蓝 = 参考动作）
MUJOCO_GL=egl uv run --with imageio --with imageio-ffmpeg python scripts/render_video.py \
  --ckpt <ckpt> --clips dance1_subject1 --seconds 30 --tag demo

流程分三步：

1. 把训练好的模型导出成 ONNX 文件。
2. 在仿真里用 Unitree 官方的机器人模型反复测试，加上延迟、负重、摩擦变化等干扰，全部通过才算合格（见 docs/SIM2SIM.md）。
3. 在机器人自带的电脑上运行控制程序。先让机器人吊在空中，再逐步放到地面上。

# 仿真测试（Release 模型）
python scripts/deploy/sim2sim.py --cmd g2,g3,report --clips combo_c4_full_vc_b15f20 --tag combo --ckpt e13i_0291000 --workers 16
# 真机第一步：吊在空中
python scripts/deploy/bridge/g1_runner_bridge.py --iface <nic> --domain 0 --stage air \
  --artifacts deploy_artifacts/<ckpt> \
  --clip deploy_artifacts/clips/<clip>.npz \
  --log-dir deploy_logs/real

这些命令在部署环境里跑，环境配置见 docs/SIM2SIM.md 和 docs/DEPLOY_G1.md。程序在倾斜过大、关节太快或电机过热时会自己停下，但吊架和遥控器仍然必须有（见上面的安全警告）。

在 GitHub Release 下载。每个模型都带训练存档和可直接部署的 ONNX 文件。

• e11c_0220000：在 BONES-SEED 上训练的基础模型。
• e13i_0291000：在基础模型上继续训练，训练数据是 BONES-SEED 加 4 段自定义舞蹈（不是只有这 4 段），Release 里有它在真机上跳舞的视频。
• e24_0355000（v1.1，文件 e24_0355000_lean35kfs.tar.gz）：只在 shanshen_duosuomao_lean35kfs_pad2 这一段舞上微调出来的模型。它不是通用的动作跟踪模型，只能配这段动作用。压缩包里还有这段动作（训练用的 npz 和部署用的目标表）、只含这一段的训练数据包和真机状态重置文件，要在仓库根目录解压。训练命令见 scripts/train/train_lean35kfs_e24.sh（它的父模型没有发布），仿真测试见 scripts/train/gate_lean35kfs.sh。它用到的新训练选项默认全部关闭，包括：腰部耦合和腰部 roll 范围，指令延迟、推力和腰部 roll 的随机化，会饱和的 IMU 观测，膝速度和偏航角速度惩罚，以及真机状态重置。说明见 docs/METHOD.md。

用法：解压到 deploy_artifacts/，然后按 docs/SIM2SIM.md 重新跑一遍仿真测试，再按 docs/DEPLOY_G1.md 上机。脚本默认用的是没发布的旧模型，所以要手动加 --ckpt e13i_0291000（仿真测试）或 --artifacts deploy_artifacts/e13i_0291000（真机程序）。两个模型都用 BONES-SEED 训练，使用前请确认它的数据条款。

Release 里没有动作目标表 deploy_artifacts/clips/<clip>.npz，要按 docs/SIM2SIM.md 用 --cmd clips 自己生成。机器人自带电脑（PC2）上的 onnxruntime 较旧，要把包里的 policy_ir9.onnx 复制成 policy.onnx。

mkdir -p deploy_artifacts
tar -xzf /path/to/e13i_0291000.tar.gz -C deploy_artifacts/   # -> deploy_artifacts/e13i_0291000/
tar -xzf /path/to/e24_0355000_lean35kfs.tar.gz -C .            # v1.1，在仓库根目录解压：deploy_artifacts/e24_0355000/、deploy_artifacts/clips/、data/...

v1.1 包里的 policy.onnx 已经是 ONNX IR 9，可以直接在 PC2 上用；policy_ir10.onnx 是原始导出的版本。e24_0355000 的 Release 已经带了动作目标表 deploy_artifacts/clips/shanshen_duosuomao_lean35kfs_pad2.npz。

本项目采用 MIT 许可证，见 LICENSE，其中同时保留了上游作者 Yuxi Liu 和本仓库作者 Hongyu Ding 的版权声明。第三方软件和数据集的声明见 LICENSES/。

如果这个仓库对你有帮助，请先引用原论文，也请引用上游复现代码：

@inproceedings{liao2026supermimic,
  title         = {SuperMimic: Scaling Humanoid Whole-Body Control with One Differentiable World Model},
  author        = {Liao, Qiayuan and Shao, Yiyang and Long, Junfeng and Zakka, Kevin and Horowitz, Roberto and Abbeel, Pieter and Sreenath, Koushil},
  booktitle     = {Conference on Robot Learning (CoRL)},
  year          = {2026},
  eprint        = {2610.28480},
  archivePrefix = {arXiv},
  primaryClass  = {cs.RO},
  url           = {https://arxiv.org/abs/2610.28480}
}

@misc{liu2026supermimicreproduced,
  title        = {SuperMimic-Reproduced: Reproduction of SuperMimic (arXiv:2610.28480) on mjlab/MuJoCo Warp},
  author       = {Liu, Yuxi},
  year         = {2026},
  howpublished = {\url{https://github.com/CuboiLeo/SuperMimic-Reproduced}},
  note         = {GitHub repository, MIT License}
}

感谢以下项目，所有 BibTeX 见 docs/REFERENCES.md：

• mjlab：仿真训练框架
• BeyondMimic：动作跟踪任务的设计
• MuJoCo / MuJoCo Warp：物理引擎
• Unitree SDK / Unitree MuJoCo 模型：真机通信和官方机器人模型
• GVHMR / GMR / SMPL-X：从视频提取动作（GVHMR 和 SMPL-X 仅限非商业用途）
• LAFAN1 / BONES-SEED：动作数据集

"Unitree" 和 "G1" 是 Unitree Robotics 的商标。