UniLab 开源机器人强化学习框架学习笔记一、UniLab 框架概述UniLab 是一个用于机器人控制的开源强化学习框架它打破了传统上由 GPU 主导的仿真范式。UniLab 不再在单个 GPU 上同时运行物理仿真和策略训练而是采用了一种异构架构由 CPU 并行执行物理仿真并通过共享内存将经验数据流式传输给常驻于 GPU 的策略训练模块。这种设计将仿真与学习过程解耦支持跨 LinuxCUDA、ROCm、XPU和 Apple SiliconMPS平台灵活部署且完全不需要依赖基于 GPU 的物理引擎。无需 GPU 仿真后端即可训练机器人 RL。演示动画使用 MotrixSim 渲染。信息来源README.md, pyproject.toml二、UniLab 解决了什么行业痛点大多数现代机器人 RL 框架如 IsaacGym、IsaacLab都假设物理仿真和神经网络训练在同一个 GPU 上运行。这种耦合架构存在三大核心限制必须配备昂贵高端 GPU 才能执行仿真步进绑定单一厂商软硬件生态迁移成本极高GPU 资源同时供给仿真与梯度训练资源竞争导致仿真吞吐量瓶颈。UniLab 通过硬件域分离拆分工作负载彻底规避上述问题硬件域核心职责运行硬件物理仿真域推进环境步长、计算观测值、收集状态转移样本多核 CPU策略训练域梯度更新、反向传播、模型保存加载GPU (CUDA / MPS / ROCm / XPU)两个硬件域通过**共享内存 IPC进程间通信**层打通CPU 采集器进程直接将交互状态数据写入张量GPU 学习器直接采样无额外数据拷贝、无序列化开销。信息来源README.md, shared_buffer.py, replay_buffer.py三、核心架构概览3.1 顶层数据流逻辑采集器子进程在数千个向量化并行环境中运行 CPU 物理仿真交互产生的状态转移样本推送至共享经验回放池学习器进程从缓冲区采样数据在 GPU 完成梯度更新更新后的 Actor 网络权重通过共享内存同步回所有采集器进程。3.2 核心 IPC 组件设计SharedReplayBuffer将全部状态转移数据存储在紧凑 CPU 张量中按观测、动作、奖励、Critic 特征列切分存储该内存布局大幅降低跨进程写入时缓存行失效损耗。SharedWeightSync引入版本计数器机制采集器读取网络权重时无需全局加锁即可自动识别过期权重兼顾异步性能与训练一致性。信息来源replay_buffer.py, weight_sync.py, async_runner.py四、项目完整目录结构UniLab 整体封装为 Python 包unilab模块职责边界清晰分层管理环境、物理后端、跨进程通信、算法、配置、训练工具unilab/ ├── base/ ← 抽象环境契约与后端接口 │ ├── base.py ← ABEnv核心环境抽象基类 (ABC) │ ├── registry.py ← 任务注册与工厂函数 │ └── backend/ ← SimBackend 抽象基类 MuJoCo/MotrixSim 适配器 ├── envs/ ← 具体机器人任务环境 │ ├── locomotion/ ← Go1, Go2, Go2-arm, G1 四足/双足机器人运动任务 │ ├── manipulation/ ← Allegro Sharpa 灵巧手抓取操作任务 │ └── motion_tracking/ ← G1 人形动作复刻跳舞、后空翻、物体追踪 ├── ipc/ ← 异构训练专用共享内存 IPC 原语 │ ├── replay_buffer.py │ ├── weight_sync.py │ ├── async_runner.py │ └── rollout_ring_buffer.py ├── algos/ ← 强化学习算法实现层 │ ├── torch/ ← PPO (RSL-RL), APPO, SAC, TD3, FlashSAC, HORA │ └── mlx/ ← Apple MLX 框架专属 PPO 变体 ├── training/ ← 训练循环、模型保存、实验日志工具 ├── dr/ ← 域随机化管理模块 ├── terrains/ ← 程序化随机地形生成工具 ├── conf/ ← Hydra YAML 配置文件按算法、任务分组 └── scripts/ ← 训练、评估、演示入口脚本信息来源init.py, registry.py, base.py五、支持算法与物理仿真后端5.1 内置强化学习算法库覆盖在线、离线、异步三大学习范式全部配套独立训练脚本与 Hydra 配置组统一 CLI 命令uv run train调度执行算法名称学习范式启动脚本核心特性PPOOn-policytrain_rsl_rl.py兼容 RSL-RL支持对称性感知 MLPMLX PPOOn-policytrain_mlx_ppo.pyApple Silicon 原生 MLX 加速训练APPO异步 On-policytrain_appo.pyV-trace 重要性权重校正采集器与训练完全解耦SACOff-policytrain_offpolicy.py分布式熵自适应调节、层归一化优化TD3Off-policytrain_offpolicy.py双 Q 网络截断、目标策略平滑降噪FlashSACOff-policytrain_offpolicy.py轻量化网络结构、余弦退火学习率5.2 物理仿真后端抽象层通过统一SimBackend抽象接口封装两种物理引擎切换仿真后端仅需修改命令行参数无需改动业务代码仿真后端依赖包版本核心优势MuJoComujoco-uni3.8.0高精度接触物理求解支持 GPU 向量化步进MotrixSimmotrixsim-core0.8.2 (可选)内置原生渲染器、备选物理求解器macOS 原生适配信息来源cli.py, structured_configs.py, registry.py, pyproject.toml六、完整训练运行机制6.1 命令行路由逻辑示例执行命令uv run train--algoappo--taskgo2_joystick_flat--simmotrixCLI 执行流程解析入参算法appo、任务go2_joystick_flat、仿真后端motrix自动匹配对应训练脚本 任务专属 Hydra YAML 配置文件后端切换零侵入仅需将--sim motrix修改为--sim mujoco代码无需改动。6.2 环境注册表实例化流程核心函数registry.make()基于任务名后端组合实例化对应环境类。采用装饰器注册机制完成环境绑定envcfg(go2_joystick)env(go2_joystick,motrix)内部生成(task_name, sim_backend) → 环境类映射查找表实现环境动态加载。信息来源cli.py, registry.py七、统一 CLI 命令大全项目在pyproject.toml中预定义 3 条全局 CLI 指令覆盖训练、评估、预演全流程执行前自动校验参数合法性平台、依赖、任务名校验命令功能说明使用示例train启动机器人强化学习训练uv run train --algo sac --task g1_walk_flat --sim mujocoeval加载保存模型离线评估uv run eval --algo appo --task go2_joystick_flat --sim motrix --load-run -1demo一键回放官方预训练模型uv run demo danceCLI 内置校验规则mlx_ppo算法仅允许在 macOS arm64 执行指定--sim motrix时校验 MotrixSim 依赖是否安装校验输入任务名是否存在于环境注册表。信息来源cli.py, pyproject.toml八、环境与任务双层注册表系统8.1 两层抽象契约ABEnv 顶层抽象定义所有机器人环境强制实现基础接口step()、init_state()、观测/动作空间、并行环境数量num_envsSimBackend 底层物理抽象统一物理引擎接口执行器控制范围、自由度速度、高度场地形采样scan()等通用方法。8.2 三大任务领域划分任务领域适配机器人典型任务场景Locomotion运动控制Go1、Go2、Go2-arm、Go2-wheel、G1人形平地行走、崎岖地形导航、摇杆实时控制Manipulation操作抓取Allegro灵巧手、Sharpa灵巧手、Stewart平台手指重定向、多物体抓取生成Motion Tracking动作复刻G1 人形机器人舞蹈复刻、墙面后空翻、动态物体追踪8.3 注册表自动发现机制每个任务域包的__init__.py通过__unilab_registry_modules__声明模块框架启动时自动导入全部环境填充全局查找表无需手动注册。信息来源base.py, backend/base.py, locomotion/init.py九、全平台异构硬件支持UniLab 原生面向跨平台、异构计算硬件设计pyproject.toml区分darwin/arm64、linux/x86_64两套依赖自动适配平台计算后端操作系统训练计算后端支持仿真后端补充说明Linux x86_64CUDA(默认)、ROCm(AMD显卡)、XPU(Intel核显)MuJoCo、MotrixSim全部功能无阉割性能对等macOS arm64 (M系列芯片)MPS、MLXMuJoCo、MotrixSim提供 MLX 加速 PPO渲染异常自动切换 mxpython 原生调用 MotrixSim无头训练避坑方案macOS 使用 MotrixSim 回放渲染报错、服务器无显示器训练场景启动命令增加参数关闭渲染training.no_playtrue完全跳过渲染器初始化仅执行仿真与训练逻辑。信息来源pyproject.toml, cli.py