Skip to content

README_zh.md

Latest commit

 

History

History
182 lines (142 loc) · 10.1 KB

README_zh.md

File metadata and controls

182 lines (142 loc) · 10.1 KB
Raw

UniLab

面向跨物理后端机器人学习的契约驱动基础设施

语言：简体中文 | English

CI Project Page Paper CoRL 2026 Documentation PyPI Apache-2.0 License

🎉 🎉 UniLab 已被 CoRL 2026 接收！ 🎉 🎉

UniLab 预告图

用同一套任务编排体验覆盖运动、操作与动作跟踪。

UniLab 是面向机器人强化学习的可配置基础设施。使用 Hydra 描述任务， 通过 manager term 组装任务，选择物理后端，再用统一 CLI 完成训练与评估。 同一套面向任务的 contract 可以把 CPU、GPU 和外部 worker 仿真连接到学习器运行时。

同一套框架已提供 Windows、Apple Silicon macOS、Linux CUDA、AMD ROCm 和 Intel XPU 的文档 路径。不同 backend/task 的成熟度按证据分级；请选择支持矩阵 中有测试证据的组合。

可以先在项目主页观看策略运行，或阅读 为什么选择 UniLab？， 了解适用场景、证据和同类方案比较。

亮点

UniLab 的核心理念很简单：将任务语义定义为可复用的配置，然后独立更换仿真器、硬件或 learner，而无需重写任务的 environment 生命周期。

  • 配置而非编码。 action、observation、reward、termination、event、command、 curriculum 和 metrics 都是 manager term，在 Hydra owner YAML 中组装。基于已有 term 的任务变体无需新写 environment class，很多时候完全不需要 Python 代码。
  • 更换后端而不更换工作流。 已注册仿真器遵循公开的 SimBackend contract。 使用 --sim 选择后端；存在匹配 task owner 时，任务编排和训练/评估工作流保持一致， 后端差异仍然显式。
  • 让 solver 与 learner 的设备彼此独立。 CPU 并行、native 或 external-worker 仿真 不必先变成 CUDA-resident simulator，也可以向 accelerator learner 提供数据；learner 可以运行在 CUDA、ROCm、MPS 或 XPU 上。每个 backend/task 组合的证据等级请查看 支持矩阵。
  • 加速 replay-based off-policy 训练。 SAC/FlashSAC 让仿真数据采集与 learner update 重叠。论文在代表性配置上报告了 3–10 倍端到端收益；测量范围和限制见 为什么选择 UniLab。

快速开始

推荐使用 uv 完成源码工作流。以下是运行策略 demo 的 最短路径：

curl -LsSf https://astral.sh/uv/install.sh | sh
git clone https://github.com/unilabsim/UniLab.git
cd UniLab

make setup
# 首次运行会从 Hugging Face 下载 checkpoint 和 asset。
uv run demo dance

Windows、macOS、CUDA、ROCm、XPU、可选后端和无头渲染的说明，请查看 安装指南和 快速演示指南。

训练与评估

# 使用 MuJoCo 训练并回放 g1平地行走 任务
uv run train --algo sac --task g1_walk_flat --sim mujoco
uv run eval --algo sac --task g1_walk_flat --sim mujoco --render-mode viser

# sim2sim
#   motrixsim
uv run --extra motrix eval --algo sac --task g1_walk_flat --sim motrix --render-mode interactive --load-run -1
#   newton
uv run --extra newton eval --algo sac --task g1_walk_flat --sim newton --load-run -1
#   isaacgym
bash scripts/tools/setup_isaacgym_env.sh
uv run eval --algo sac --task g1_walk_flat --sim isaacgym --load-run -1


# 使用 mjwarp 训练并用 genesis 物理 回放 g1动作跟踪 任务
uv run --extra mjwarp train --algo flashsac --task g1_motion_tracking --sim mjwarp
# 双卡
CUDA_VISIBLE_DEVICES=0,1 \
  uv run --extra mjwarp train --algo flashsac --task g1_motion_tracking --sim mjwarp
uv run --extra genesis eval --algo flashsac --task g1_motion_tracking --sim genesis --load-run -1

使用 MPS 时，先为每张选中的 GPU 手动启动服务，在训练命令后追加 training.cuda_process_sharing=mps，训练结束后再手动关闭。例如 GPU 0、1：

uv run uni-cumps start --gpus 0 --name train-gpu0 --daemon
uv run uni-cumps start --gpus 1 --name train-gpu1 --daemon
CUDA_VISIBLE_DEVICES=0,1 \
  uv run --extra mjwarp train --algo flashsac --task g1_motion_tracking --sim mjwarp \
  training.cuda_process_sharing=mps
# 执行训练，等训练进程退出后，仅关闭上述服务。
uv run uni-cumps stop --name train-gpu0
uv run uni-cumps stop --name train-gpu1

请求 mps 后，每个 rank 会自动绑定本 GPU 已登记的服务（索引形式的 CUDA_VISIBLE_DEVICES 会在 CUDA 初始化前被规范为 per-GPU MPS 服务要求的 GPU UUID）；uni-cumps env 仅供外部启动器使用——训练前不要 eval 它，它会把可见性 钉到单张卡上。管理命令应在没有冲突的 GPU mask 时执行。更多选项见 uv run uni-cumps --help。执行约定见运行指南。

这些 flag 会让 algorithm、task 和 simulator 选择保持可见。续训、W&B、Hydra override、 回放、后端安装和完整命令矩阵属于 训练指南、 后端指南和 支持矩阵。

生态

UniLab 被设计为机器人专属仓库共享的任务与训练界面。下游仓库可以独立发布机器人 recipe，同时消费同一套 task、backend 和 RL contract。目前的下游示例：

文档

开发与贡献工作流请参阅贡献指南。

社区

UniLab 社区二维码

添加 UniLab 小助手微信，加入社区。

引用

@article{jia2026unilab,
  title         = {UniLab: A Heterogeneous Architecture for Robot RL Beyond GPU-Dominant Paradigms},
  author        = {Jia, Yufei and Cao, Zhanxiang and Yu, Mingrui and Zhang, Heng and Chen, Shenyu and Jiang, Dixuan and Li, Meng and Li, Xiaofan and Liu, Yiyang and Wu, Junzhe and Li, Zheng and Fang, XiLin and Cui, Tingyu and Fu, Shengcheng and Li, Haoyang and Wang, Anqi and Wang, Zifan and Zhu, Dongjie and Cao, Chenyu and Huang, Zhenbiao and Zheng, Ziang and Lu, Jie and Ma, Xin and Wei, Zhengyang and Zhao, Xiang and Zhan, Tianyue and He, Ye and Chen, Yuxiang and Jiang, Yizhou and Li, Yue and Ge, Haizhou and Dong, Yuhang and Jia, Fan and Zhang, Ziheng and Zhang, Meng and Deng, Xiwa and Chen, Zhixing and Shao, Hanyang and Dong, Chenxin and Li, Yixuan and Chen, Yizhi and Chen, Bokui and Zhang, Kaifeng and Cui, Hanqing and Qin, Yusen and Huang, Ruqi and Han, Lei and Wang, Tiancai and Li, Xiang and Gao, Yue and Zhou, Guyue},
  journal       = {arXiv preprint arXiv:2605.30313},
  year          = {2026},
  url           = {https://arxiv.org/abs/2605.30313}
}

UniLab 以 Apache License 2.0 发布。独立的 UniSim 仓库包含各自的发布和引用信息。 RL 栈（算法、异步 runtime、训练日志）内置在本仓库的 src/unilab/rl/ 中；它并自原 unilab_rl 仓库，该仓库保留为历史出处。

致谢

如果没有 Isaac Lab 团队以及 mjlab 开发团队和贡献者的出色工作，UniLab 不会 成为今天的样子。Isaac Lab 在 manager-based API 设计和抽象方面的工作，以及 mjlab 清晰、轻量的参考实现，共同塑造了 UniLab 的 Hydra + NumPy 任务编排体验。衷心感谢两个 社区分享他们的工作与想法。