调研报告：RoboVerse / MetaSim 如何实现统一物理后端

[TATP-233]

调研日期：2026-08-17
代码基线：RoboVerse e9b5c6e、MetaSim 6947e35、UniLab 21dbe46
调研方式：静态追踪配置、handler、状态/动作、并行、hybrid、task lifecycle、query、资产和测试；未运行需要各模拟器商业/重型依赖的全量测试。

TL;DR

RoboVerse 当前并不直接拥有“统一物理后端”内核：它已经变成任务、机器人、场景、资产和学习代码的 content pack，真正的 simulator core 位于独立的 MetaSim 仓库。两者组成的设计可以概括为：

RoboVerse content pack
  └─ entry point / metasim.toml 注入 tasks、robots、scenes、grounds
                         │
                         ▼
MetaSim ScenarioCfg ── get_handler() ── lazy dispatcher
                         │
                         ▼
                   BaseSimHandler
                  /       |        \
       原生向量 backend  进程并行包装  physics/render hybrid
                  \       |        /
                         ▼
 TensorState(objects / robots / cameras / extras)
                         │
                         ▼
 BaseTaskEnv: action → simulate → state → reward/termination/observation

我的核心判断是：

1. 它统一得最好的是调用协议和内容接入，不是物理行为。 ScenarioCfg → BaseSimHandler → TensorState 让任务可以共享启动、状态、动作和 step 入口。
2. TensorState 既是公共状态模型，也是并行进程聚合和 physics/render 同步总线。 这是 MetaSim 最有辨识度的设计。
3. 能力边界仍弱于类型表面。 完整 state 可读不代表完整 state 可写；position/velocity/effort action 的支持不对称；query 仍直接分支并访问 backend 私有对象。
4. 资产多格式和同名 API 不保证跨引擎物理等价。 现有 parity 工作主要验证对上游原生环境的复现，常常复用同一引擎/模型/控制序列，不能推导为 PhysX、MuJoCo、SAPIEN、Newton 之间一致。
5. UniLab 不宜照搬 MetaSim 的大一统 state/config。 更值得吸收的是外部 content pack discovery，以及用 decorator/compositor 保持 contract 的组合思路；UniLab 现有 capability-first、明确 frame/quaternion 和 backend isolation 应继续保留。

1. 双仓边界：MetaSim 是内核，RoboVerse 是内容层

RoboVerse 的包描述直接写明它是 “content, learning, and examples built on MetaSim”，依赖 MetaSim，并把各 simulator extra 转发给 metasim[...]；同时通过 metasim.packages entry point 注册 roboverse_pack（证据）。源码树旁的 metasim.toml 也声明同一 root。

MetaSim 的发现器按 tasks / robots / scenes / grounds 四种角色聚合候选包，来源包括默认值、Python entry point、最近的 metasim.toml/pyproject.toml、显式配置和环境变量（角色与配置、entry point 与 TOML 查找）。

这条边界的价值很明确：core 不需要 import RoboVerse 的全部任务和资产；第三方可以新增一个安装包来提供内容，不必修改 simulator core。对 UniLab 而言，这是本次调研中最直接可复用的一点。

2. 后端选择：统一构造入口，具体 registry 仍是硬编码路由

ScenarioCfg 把 robots、objects、cameras、lights、scene、ground、render、sim params、num_envs、decimation、gravity 和 simulator 名称集中在一个配置中（定义）。get_handler() 做三件事：把字符串转为 SimType、取得 handler class、构造并 launch()（调用链）。

dispatcher 采用 lazy import，避免未选中的重依赖被提前导入；但 registry 本质仍是一组 if/elif。MuJoCo、PyBullet、SAPIEN2/3 会在这里被 ParallelSimWrapper 装饰，其他后端返回原生 handler（完整路由）。测试会静态检查 SimType、ScenarioCfg Literal 和 dispatcher 没有漂移（一致性测试）。

这里统一的是“选择和启动方式”。文档自己也把后端分为 active、inactive、experimental 三档（support levels），所以出现在 enum/dispatcher 中不应被理解为能力等价。

3. BaseSimHandler：所有后端的统一前门

每个 backend 必须实现的最小核心是：

_set_states(...)
_set_dof_targets(...)
_get_states(...)
_simulate(...)

基类在它们之上统一提供 launch/close、device、seed、公开的 get/set state、action、render refresh、joint/body name ordering、optional query 和缓存管理（基类入口、状态写入、动作入口）。

这里有两个重要设计细节：

• backend 只负责 native ↔ canonical 的转换，joint/body 在 API 侧按名称排序，并缓存 reindex（name ordering）。因此 tensor action/state 不依赖各引擎内部 ID 顺序。
• public method 负责 mutation 后统一失效 state cache；tensor 表示和 dict 表示互相惰性转换，避免同一步重复读取模拟器（cache path）。带 env_ids 的 subset read 则绕过全量缓存。

4. TensorState：语义对象树，而不是一个扁平 qpos/qvel

统一状态按场景语义分组：

TensorState
├─ objects[name] -> ObjectState
├─ robots[name]  -> RobotState
├─ cameras[name] -> CameraState
└─ extras

root/body state 都采用 [pos(3), quat(4), lin_vel(3), ang_vel(3)]，shape 分别是 (num_envs, 13) 与 (num_envs, num_bodies, 13)；robot 还带 joint position/velocity/targets，camera 带 RGB、depth、segmentation、pose 和 intrinsics（shape annotations、ObjectState/RobotState、CameraState/TensorState）。同一个 contract 同时支持高效 tensor 和易用的 list[DictEnvState]，并规定 action 的 robot/joint 名称顺序（action normalization）。

这个模型比单纯 get_qpos() 更适合多机器人、多物体、视觉和数据集回放，也使并行聚合与 hybrid 同步可以复用同一格式。

但 schema 目前比语义 contract 更完整：

• root/body 文档没有在类型定义处写清所有 frame；四元数顺序也没有直接写入该字段文档。实现中的实际惯例是 wxyz：object 默认姿态明确为 wxyz（配置），各 adapter 再转换 native 顺序。
• get_states 能返回 velocity/target，不等于 set_states 能做完整 snapshot restore。基类明确警告目前跨后端可靠写入的主要是 pose 与 DOF position，velocity/DOF velocity 并未获得对称保证，control target 需要走 set_dof_targets（限制说明）。
• RobotAction 类型包含 position/velocity/effort，但共享的 tensor normalization 是 position-target 协议；非 position key 会被丢弃并告警，backend 若要支持必须绕开该 helper（实现说明）。

因此，MetaSim 更准确的说法是拥有统一的 read model + 部分统一 mutation model，而不是完全可逆的 simulator snapshot。

5. 多环境：把并行做成保持 contract 的 decorator

对原生支持 batch 的后端，handler 直接返回 batched tensor；对单环境 CPU 后端，ParallelSimWrapper 在 num_envs > 1 时每个 env 启一个进程，通过 pipe 转发 handler 命令，num_envs == 1 时直接返回原 class（worker protocol、构造与错误传播、state/action/step）。

这使任务不需要知道后端是否原生 vectorized，是一个值得借鉴的结构。不过 IPC 协议是固定 command list；每增加一种公共能力，都要同步扩展 worker 和 wrapper。它解决的是统一表面下的执行策略替换，还不是 capability-driven 的通用代理。

6. Hybrid：状态协议同时充当 physics/render 总线

HybridSimHandler 组合一个 physics handler 和一个 render handler：action、step、device、joint/body names 来自 physics；每步取 physics state 写入 renderer；读取时 robots/objects 取 physics，cameras 取 renderer，extras 合并且 physics 优先（组合入口、同步与合并）。RoboVerse 也提供了 physics 与 renderer 分离的示例（示例）。

亮点在于 composition 仍暴露同一个 handler contract。风险在于当前 compositor 直接调用子 handler 的 _get_states/_set_states/_simulate 私有方法，并用 try TypeError → tensor 转 dict 推断兼容性。这绕过了部分 public cache/validation，也说明“能否接收完整 TensorState”还没有被建模成 typed capability。

7. Task lifecycle：共享主循环，但扩展点仍较松

BaseTaskEnv.step() 固定执行：

_process_action
→ pre callbacks
→ handler.set_dof_targets
→ handler.simulate
→ handler.get_states("tensor")
→ post callbacks
→ reward / terminated / timeout / observation

reset 则是 seed、reset callback、set state、refresh render、重新取 state（step、reset/close）。其中 _process_action 是合理的 sanctioned hook，任务不必重写整个 step。

不过 lifecycle 只是若干普通 callback list，没有声明 phase payload、执行频率、依赖顺序或逆序 teardown。RoboVerse 中也仍存在 ManiSkill/SAPIEN、LIBERO/MuJoCo、BeyondMimic/IsaacSim 等 native integration；所以应把“多数共享任务可复用 handler”与“所有任务 backend-agnostic”区分开。

8. Query 和配置暴露了 abstraction leak

optional query 本意是扩展公共 state 的 extras，但 ContactForces 会根据 scenario.simulator 分支，并直接访问 IsaacGym、IsaacSim、MuJoCo、Newton 的 native/private 对象（bind 与分支、MuJoCo native API）。SitePos 甚至通过 handler class 的 module string 判断后端（实现）。

同样，SimParamCfg 把通用字段、PhysX/SAPIEN recipe、MJX/Newton solver 字段放在一个大配置里（字段）。这对复现实验方便，但 ownership 和能力验证较弱。

对 UniLab 的启示是：query 的底层数据源应先进入 SimBackend contract/capability，上层 query 只做语义组合；backend-specific config 继续由 owner/backend 自己消费，不进入共享 env 热路径的 type switch。

9. 资产统一是“多格式候选”，不是 canonical conversion

MetaSim 的 object config 同时容纳 USD、URDF、MJCF、MJX-MJCF 等路径，再按 backend 选择文件类型和 fallback（映射）。RoboVerse 的 Franka 配置就是同一语义 robot 指向多个资产文件（示例）。

这解决了“每个引擎加载什么”，没有自动证明这些文件的 link/joint、collision、inertia、material、actuator 完全等价。Newton handler 还会主动调整摩擦、接触 margin 等默认值来缩小跨 simulator 差异（Newton defaults）。因此建议把 asset provenance/parity level 作为独立元数据，而不是从同一个 config 名字推断物理等价。

10. 测试与 parity：覆盖了 contract，但跨引擎行为矩阵仍不完整

MetaSim 已有值得肯定的共享测试方式：同一 scenario fixture 按 backend 参数化，验证 state shape/roundtrip、joint ordering、dict/tensor mode、cache invalidation、per-env action 和 DOF control；也有静态测试检查 concrete handler 是否覆盖必选方法（state consistency、state modes、DOF control、handler contract）。已知差异常用 xfail 明示，而不是假装一致。

需要谨慎解释 RoboVerse 的 parity：

• ManiSkill 测试比较 native physx_cpu 与用同一 SAPIEN/PhysX recipe 重建的场景，目标是复现上游环境（测试声明、rollout 比较）。
• robosuite parity 把 native 环境编译出的同一 MJCF、初态和每个 substep control 交给 MetaSim MuJoCo handler，再比较 qpos/reward/success（方法、实现）。

这些是很有价值的 upstream reproduction tests，但由于常常是同一 physics engine + 同一 model + 同一低层 control，它们不是 cross-engine physics parity tests。当前共享 suite 也没有形成所有 active backend 上统一的 gravity、contact、friction、restitution、sensor timing、reset determinism 和 per-env independence 行为矩阵。MJX 自身还明确限制为单机器人建模、camera 只渲染 env 0（限制）。

11. 与 UniLab 当前设计对照

维度	RoboVerse / MetaSim	UniLab 当前方案	判断
仓库/内容边界	MetaSim core + 可发现的 RoboVerse content pack	单仓内 backend/env/task/asset	pack discovery 值得借鉴；是否拆仓是另一项决策
后端前门	BaseSimHandler	SimBackend ABC	两者目标相同；UniLab 的方法语义更细
构造	SimType + lazy if/elif dispatcher	create_backend + owner config	都是集中路由；无需为了插件复制 enum
状态	多 actor TensorState 语义树	按需 base/body/sensor methods + set_state	MetaSim 适合数据集/多物体；UniLab 更适合 RL 热路径和精确契约
frame/quaternion	实现惯例存在，类型文档不完整	world/baselink 和 wxyz 明写在 contract（证据）	保持 UniLab 现状
多环境	native batch 或 process decorator	backend-native vectorization / pool	decorator 可作为未来 CPU fallback，但先定义 IPC capability
physics/render	handler compositor + full state bus	SceneCfg.visual_model_file 与 playback capabilities	可借鉴职责拆分，不应调用子 backend 私有方法
capabilities	None / NotImplemented / 手工 support matrix / query 分支	play、height scan、DR 等显式 capability（证据）	UniLab 路线更严格，应继续 capability-first
测试	shared scenario + 部分 backend 矩阵 + upstream parity	public factory 驱动的 conformance suite（证据）	两边都应再补行为级矩阵

UniLab 已有 ADR 明确“能力边界不是所有后端行为完全一致”，并禁止脚本层散落 backend 判断（ADR-0002）。本次调研支持继续坚持这一方向。

12. 对 UniLab 的落地建议

P0：先补“行为契约矩阵”，不要把接口通过当作 physics parity

为每个正式 backend 建一份 capability × behavior matrix，至少覆盖：

• reset 后 position 与 velocity 是否对称写入；subset reset 是否互不干扰；
• gravity/free-fall、joint limit、actuator saturation；
• contact existence、normal direction、force aggregation 口径；
• friction/restitution 的定性与容差行为；
• control/physics/sensor 的时序；
• seed determinism、batch env independence；
• unsupported 能力必须显式 skip/reject，不能返回“看起来合法”的零值。

验收分层建议：schema/shape conformance、semantic conformance、numerical tolerance、bitwise reproduction。只有最后一层且前提相同，才使用 “1:1 parity” 表述。

P1：引入可选的 content pack discovery，但不让插件注册 backend 私有 API

可以仿照 MetaSim 通过 Python entry point 或项目 TOML 发现 task/robot/scene/terrain pack；插件输出 UniLab 的正式配置/registry descriptor，core 负责校验、去重和错误报告。建议先覆盖内容扩展，不急于开放第三方 backend 注册，以免 ABI、依赖和 capability 版本变成隐式约定。

P1：若确有多 actor / dataset snapshot 需求，再增加规范化语义状态

不要直接用一个可选字段很多的 TensorState 替换现有热路径 getter。可以拆成三个明确概念：

1. ReadableSceneState：观测/导出允许读取什么；
2. ResetState：跨 backend 保证可写回什么；
3. PlaybackSnapshot：仅由声明 snapshot capability 的 backend 支持。

每个字段必须注明 shape、dtype、device、frame、quaternion order、单位、name order、subset semantics，并让 read/write symmetry 由 conformance test 锁定。

P1：query 采用 backend data-source contract，上层只做语义组合

例如 contact history 可以由上层维护，但“当前各 body 的 net contact force”的来源必须是 public backend method/capability；禁止 query 按 class/module 名称分支或访问 native model/data。冷路径完成 name → id 和 format/capability cache，热路径只消费稳定 handle/buffer。

P2：并行与 hybrid 可做 contract-preserving composition

• CPU 多进程 wrapper 只有在 public contract、异常传播、seed、close、subset env、可选 capability 都能完整代理时才启用；
• physics/render 分离通过公开 snapshot/pose-sync contract，并显式声明 renderer 接受的 state level；
• compositor 自身也参加同一 conformance suite，不能用调用私有 _method 或捕获 TypeError 来探测能力。

不建议照搬

• 不把所有 backend-specific solver/renderer 参数塞入一个共享大 config；
• 不用 simulator == ... 或 class/module string 作为 capability 判断；
• 不从“同名 robot config 指向多个格式文件”推断资产物理等价；
• 不把 optional field 返回 None/零 tensor 当成完整能力声明；
• 不为了统一表面牺牲 UniLab 现有的 frame、wxyz、owner config 和 public-contract isolation。

结论

RoboVerse / MetaSim 的方案不是“用一个引擎模拟所有后端”，而是把 内容发现、场景配置、handler 生命周期、状态/动作协议和 task 主循环 固定下来，再由 adapter、并行 decorator 与 hybrid compositor 吸收不同引擎的差异。它证明了统一后端最有价值的部分是稳定边界和可组合性。

同时它也清楚展示了统一抽象的常见陷阱：schema 比 mutation 能力宽、query 穿透 backend、配置混入实现细节、多格式资产被误解为物理等价、upstream reproduction 被误读为 cross-engine parity。

因此对 UniLab 的推荐路线是：保留现有严格 SimBackend contract 与 capability-first 边界；优先建设行为契约矩阵；按需吸收 content pack discovery、语义 snapshot 和 contract-preserving composition，而不是整体复制 MetaSim 的 state/config 形态。