MimicLite 使用指南

MimicLite 是 RoboParty Lab 开源的人形机器人通用动作跟踪系统。给定一段参考动作（来自动捕数据集，或 PICO 实时采集的人体动作），训练出的策略会控制机器人在物理约束下跟上它。同一个策略既能离线回放动作，也能用于实时遥操作。

MimicLite 的重点是训练快：8 张 RTX 4090 约 3 小时即可训练出一个可部署的策略。

资源入口：

本节介绍 MimicLite 的组成、发布的模型和环境配置。完成本节后，你可以在仿真中运行发布的策略，并准备好训练环境。

MimicLite 由四个仓库组成，Roboparty/MimicLite 是项目入口：

三个模型都只需要 0.08 秒的未来参考动作，适合低延迟遥操作。部署用的 ONNX 和 YAML 在共享的 sim2real artifacts 中。各模型的评测结果见跟踪排行榜。

active-adaptation 和 mimic-lite 需要分别克隆，mimic-lite 放在 active-adaptation 的 projects/ 下：

为每种仿真后端建一个独立的环境：

启用 MimicLite 并确认任务已注册：

设置账号：

注意

• mjlab 训练报错缺少 mujoco.mjtEnableBit.mjENBL_MULTICCD 时，说明环境装了 mujoco>=3.8。运行 uv --project venv/mjlab add 'mujoco<3.8' 后重新同步。

• IsaacLab 可能误用 Isaac Sim 自带的 Warp，而不是环境中安装的 warp-lang。出现这种情况时，按 mimic-lite README 的 Troubleshooting 一节清除缓存。

在工作站上：

从共享的 sim2real artifacts 下载 checkpoints/ 和 third_party/，放到仓库根目录：

在 MuJoCo 中运行 MimicLite v1.1。终端 A：

终端 B：

两个进程都启动后，在策略终端按 ] 开始跟踪，再打开 base_sim.py 打印出的 mjviser 网址查看。

检查推理速度：

本节准备训练用的动作数据。MimicLite 使用 any4hdmi 定义的统一格式，数据转换和检查由 any4hdmi 仓库完成。

一个 any4hdmi 数据集包括：

身体各部位的位置和姿态都可以由 qpos 和机器人模型算出，不必重复存储。训练时第一次加载会统一做一次正运动学并缓存。

已转换好的数据集在 any4hdmi Hugging Face 合集 中，包括 LAFAN、100STYLE、AMASS 高难度子集、地面动作、高动态动作、PICO 实采数据等。训练配置可以直接用 hf:// 路径引用它们，不需要下载到本地。

注意 SONIC 使用的 BONES-SEED 数据受许可证限制，不能再分发。需要从原始来源获取，再用 any4hdmi 转换。

在 any4hdmi 仓库中运行：

需要使用其他机器人模型时，用 --mjcf-repo、--mjcf-path、--mjcf-revision 指定 Hugging Face 上的 MJCF。

转换好的数据集可以用 uv run any4hdmi-upload <本地目录> <HF 仓库名> 上传到 Hugging Face。

用 PICO 实时采集并重映射到机器人上的动作，可以直接录成 any4hdmi 数据集（需要先按 5.4 节配置 PICO）：

输出目录形如 <机器人>_motion_YYYYMMDD_HHMMSS/，包含 manifest.json 和 motions/motion.npz。

训练用的数据组合写在 mimic-lite 的 cfg/task/motion/ 下，例如 <机器人>/lafan.yaml、<机器人>/mixture.yaml。每个数据源可以设置：

注意 默认的混合配置中，部分数据源（例如 SONIC、LAFAN）指向 ../any4hdmi/output/ 下的本地目录。使用前请先按 2.3 节转换，或把路径改成对应的 hf:// 数据集。

本节训练跟踪策略。所有命令都在 active-adaptation 仓库根目录运行。命令中的 <机器人> 表示 cfg/task/motion/ 下的机器人目录。

单阶段 PPO，8 卡训练：

launch_ddp.sh 的参数依次为：GPU 编号、训练脚本、仿真后端环境，之后是 Hydra 配置覆盖项。

PPO-ROA 分三个阶段依次运行：先用特权信息和更长的未来参考训练教师，再让只用可部署输入的学生拟合教师，最后用 PPO 直接微调学生。

• +task/patches=teacher_future_t16 让教师看到 16 帧（0.32 秒）的未来参考；学生仍只看 0.08 秒。

• 显存不足时，追加 task.command.diff_future_steps=[0,1]。

• 三个阶段的划分写在 cfg/stages/ 中，默认为 normal；v1.1 使用的是 cfg/stages/v1_1.yaml（4000 / 1000 / 2000 次更新）。

• 运行目录在 ./outputs/<日期>/<时间>-<任务名>-<算法名>/。

• 默认每 500 次更新保存一次模型，并上传到 W&B。

• 之后可以用 checkpoint_path=run:<entity>/mimic_lite/<run_id> 直接引用 W&B 上的模型。

本节在仿真中查看训练好的策略，并导出 sim2real 可以直接使用的 ONNX 和 YAML。

查看一个 PPO 模型：

只查看 PPO-ROA 微调后的学生：

查看时关闭根部漂移截断（root_pos_error.enabled=false），可以连续观察长动作。把 checkpoint_path 中的 <entity> 和 <run_id> 换成自己的 W&B 运行，即可查看自己训练的模型。

在查看命令后追加 export_policy=true；只导出、不打开仿真时，再加 export_only=true。

导出的文件在 mimic-lite 的 scripts/exports/<任务名>/ 下，文件名为 policy-<run_id>-<checkpoint 编号>：

sim2real 会自动加载与 YAML 同名的 ONNX，所以导出的这对文件可以直接作为 --policy-config 使用（见第 5 节）。

注意 ONNX 和 YAML 必须来自同一次导出，配套使用。

scripts/eval.py 用于定量评估：默认无界面运行 512 个并行环境、1000 步，输出可供后续统计的 TensorDict。跨代码库的统一评测见第 6 节。

本节使用 sim2real 仓库，在 MuJoCo 中验证策略，部署到实机，并用 PICO 遥操作。

sim2real 把策略和执行端分开：策略进程读取机器人状态、运行 ONNX、发出关节指令；执行端在仿真中是 MuJoCo，在实机上是机器人本体。

支持两种硬件布局：工作站通过网线控制机器人，或全部程序在机器人的机载计算单元上运行。

控制方式：

控制方式由 --controller keyboard|joystick|pico 选择，默认键盘。joystick 为机器人遥控器，按键映射见 sim2real 文档。

终端 A，启动 MuJoCo，它会打印 mjviser 网址：

终端 B，启动策略：

<动作路径> 是 any4hdmi 数据集中的一段动作，可以是本地 .npz，也可以是 hf:// 路径。

在策略终端按 ] 开始。可以在 mjviser 界面中开关虚拟吊架（Elastic Band）并调整长度。

单进程运行： 策略和 MuJoCo 也可以在同一个进程中运行。它会把机器人放到动作第一帧，等待 5 秒后开始跟踪，结束后保持最后一帧：

加 --headless 可以无界面运行；加 --trajectory-output <路径>.npz 可以保存轨迹，再用 scripts/tracking_experiment/ 下的脚本计算跟踪指标。

安装机器人依赖：

<机器人通信 extra> 的名称见 sim2real 文档的 Root Project 一节。

如果安装时报 Could not locate cyclonedds，需要先编译安装 CycloneDDS（0.10.x），并设置 CYCLONEDDS_HOME，步骤见 sim2real 文档的 Root Project 一节。

选择机器人通信方式：

两种桥接脚本见 sim2real 文档的 Robot I/O 一节。

推荐的 inline 方式：

机器人网卡不是 eth0 时，加 --robot-interface <网卡名>。

提示 实机上如果关节剧烈抖动，或高动态动作的效果明显变差，先怀疑 ZMQ 通信延迟不稳定，改用 --robot-io inline 再试，不要急着调策略或增益。

网络布局：

• 网线连接： 程序都在笔记本上运行，笔记本通过网线连机器人，通过实验室 Wi-Fi 连 PICO。

• 机载运行： 程序都在机器人的机载计算单元上运行，机器人、笔记本和 PICO 都连实验室 Wi-Fi，笔记本只用于 SSH 操作。

在机器人上运行时，建议设置 HF_HUB_OFFLINE=1 和 HF_HUB_DISABLE_TELEMETRY=1，避免程序尝试联网。

准备遥操作环境（工作站）：

1. 安装 venv/pico：uv sync --project venv/pico

2. 安装 XRoboToolkit PC Service 的 .deb，并编译安装 xrobotoolkit_sdk（步骤见 sim2real 文档的 Teleop Project 一节）。

3. 戴上腿部追踪器，完成全身追踪校准，在 XRoboToolkit 中连接工作站并开启全身数据流。

在机器人的机载计算单元上运行遥操作的配置，见 sim2real 文档 Teleop Project 中的机载（Onboard）部分。

运行：

先在终端 A 的 mjviser 中确认重映射后的机器人动作正常。实机上，去掉终端 B，并按 5.3 节加上 --robot-io inline。

PICO 上的操作：按 A 进入初始姿态，按 A + B 启用策略，按 X 开始跟随动作流。重映射和策略在不同电脑上运行时，给策略加 --motion-zmq-connect tcp://<重映射电脑 IP>:28701。

提示 sim2real 还支持用 PICO 扳机控制 DH116S 灵巧手，详见 sim2real 文档。

本节在统一协议下评测策略，并介绍如何运行或接入其他代码库训练的策略。

跟踪排行榜 使用 ChingMu 的 MotionDecode 数据中冻结的四个子集，所有策略在同一套 MuJoCo 环境中、用 CPU ONNX Runtime 运行：

评测自己的策略：

• 默认评测 Locomotion-80 和 Manipulation-48；加 --splits locomotion manipulation ground dance 评测全部四个子集。

• 重复 --policy 名称=路径 可以一次比较多个策略。

• 数据缓存在 datasets/motiondecode，脚本会校验每个文件；--dry-run 只下载和校验数据，不运行仿真。

• 每个子集输出轨迹、runs.csv、tracking_metrics.csv/json 和 summary.json。

评测协议要点：

• 骨盆高度误差超过 0.3 m，或重力方向误差超过 0.8，判为失败；不按根部位置判失败。

• 完成度（Progress）和跟踪回报（Tracking Return）都在失败帧截止；误差只统计失败前的帧，所以要和完成度一起看。

• 全局根部误差只在 Locomotion 上报告。

• 这些数据只用于评测，不要重新采样，也不要用于其他机器人。

sim2real 已把多种外部策略转换成同样的部署格式，只需替换 --policy-config：

完整列表和各策略的特殊要求（例如 SONIC SMPL 模式需要单独的动作源），见 sim2real 文档的 Run External Policies 一节。

只有一个 ONNX 文件是不够的：观测的构造、关节顺序、PD 增益和动作缩放都必须与训练时一致。接入新策略需要：

1. 导出 ONNX；

2. 实现对应的观测类，并编写部署 YAML；

3. 在 Sim2Sim 中验证。

sim2real 仓库内置了一个 Codex skill（.agents/skills/adapt-policy-to-sim2real），可以按步骤完成以上工作。MimicLite 自己训练的模型用 4.2 节导出即可，不需要这一步。