我们发布了Wuji MJLab，一个用于灵巧手操作的开放源码MuJoCo环境。它包含立方体重定向任务、sim2real流水线以及复现系统所需的设置。我们将在ICRA展位121进行现场演示，并欢迎讨论灵巧操作。代码: https://github.com/wuji-technology/wuji-mjlab… 贡献者: Jielin Wu, @yaoshzh, @BergerHunger, Li Chengmeng。该项目基于@kevin_zakka的mjlab项目。

wuji-technology/wuji-mjlab

来源: https://github.com/wuji-technology/wuji-mjlab

wuji-mjlab

中文版 许可证: Apache 2.0 (https://opensource.org/licenses/Apache-2.0) 发布版 (https://github.com/wuji-technology/wuji-mjlab/releases) CI (https://github.com/wuji-technology/wuji-mjlab/actions/workflows/ci.yml) Python (https://www.python.org/downloads/) PyTorch (https://pytorch.org/) CUDA (https://developer.nvidia.com/cuda-toolkit) Ruff (https://github.com/astral-sh/ruff) pre-commit (https://github.com/pre-commit/pre-commit) Stars (https://github.com/wuji-technology/wuji-mjlab/stargazers)

在Wuji手上进行立方体手中重定向: 在mjlab中训练的PPO策略（通过mujoco-warp实现GPU批处理物理），覆盖完整的SO(3)目标空间，并带有用于在实体手上闭环部署的sim2real桥接。

任务

从最新发布版拉取检查点和CAD包:

# 需要gh CLI (https://cli.github.com)；通配符确保此命令
# 在未来的发布标签下也能工作。如果你没有安装gh，请参考docs/sim2real/setup.md §3中的手动回退方法。
gh release download --repo wuji-technology/wuji-mjlab --pattern '*-assets.zip'
unzip wuji-mjlab-*-assets.zip
mv wuji-mjlab-*-assets release-assets

仓库布局

wuji-mjlab/
├── src/
│   ├── wuji_mjlab/          # 任务包 (tasks/reorient/, assets/, utils/, rl/)
│   └── wuji_rl_libs/        # 内嵌的rsl-rl (5.0.1+wuji1, min_std clamp)
├── deploy/reorient/         # sim2real桥接 (视觉, ZMQ, 手驱动)
├── scripts/                 # 训练/运行/工具入口
├── docs/                    # 架构 + sim2real设置
├── pixi.toml                # 规范安装 + 任务运行器
└── pyproject.toml           # 包元数据

要求

• Linux x86_64
• NVIDIA GPU, CUDA 12.8 (支持Blackwell sm_120 / RTX 50系列)
• pixi (https://pixi.sh) ≥ 0.66 (CI使用的版本) — 唯一支持的安装方式
• 对于sim2real: Wuji Hand硬件 + 海康USB-3相机 + 海康MVS SDK + 3D打印ArUco标记立方体 + 腕部AprilTag — 参见docs/sim2real/setup.md

⚠️ 注意: 此仓库仅支持pixi。未测试且不支持的conda + pip install -e .方式。

安装

# 1. 安装pixi（一次性）
curl -fsSL https://pixi.sh/install.sh | bash

# 2. 克隆 + 解析环境
git clone https://github.com/wuji-technology/wuji-mjlab
cd wuji-mjlab
pixi install

这将生成一个用于训练/评估的default环境，以及一个可选的用于sim2real桥接的deploy环境 (pixi install -e deploy)。验证环境: pixi run list-envs (列出注册的任务并确认mjlab + tyro栈可以干净导入)。

训练

pixi run train --task WujiHand_Reorient --agent.upload-model False

--agent.upload-model False使检查点仅保存在本地。去掉该标志（并设置WANDB_API_KEY）也会将最终迭代的检查点作为模型工件推送到W&B — 本地.pt文件仍会在每个save_interval边界写入。

如果pixi run train出现OOM，请切换到低VRAM的变体:

pixi run train --task WujiHand_Reorient_Light

WujiHand_Reorient近似复现发布的检查点，使用num_envs=8192, max_iterations=5000，需要约20 GB GPU内存。WujiHand_Reorient_Light使用num_envs=4096, max_iterations=7500 — 轻松适应约12 GB，但收敛到明显较弱的策略（偶尔掉落立方体，在更难的重定向上出现手指卡住行为）。

检查点和W&B日志位于logs/rsl_rl/<task_id>/下。任务MDP、奖励塑造以及接触参数领域随机化（分为两个解剖学组：手掌+拇指顺应区 vs 手指2-5）在下面的架构部分中记录。

运行与评估

# 使用训练好的检查点启动交互式查看器
pixi run play --task WujiHand_Reorient --checkpoint-file <path>

# 在N次试验中评估成功率（需要ONNX）
pixi run python -m wuji_mjlab.tasks.reorient.scripts.eval_success_rate <onnx-path>

# 导出PPO检查点 → ONNX（附带action_scale / ema_alpha / ctrl_dt的sidecar JSON）
pixi run python -m wuji_mjlab.tasks.reorient.scripts.export_onnx <checkpoint.pth> <output.onnx>

其他开发工具:

pixi run list-envs                               # 列出已注册的任务
pixi run python -m wuji_mjlab.tasks.reorient.scripts.view_task WujiHand_Reorient  # 使用伪策略查看任务

模拟到现实

部署桥接器在真实的Wuji手上运行导出的ONNX策略。视觉模块通过USB相机跟踪带有ArUco标记的立方体（锚定在腕部AprilTag世界坐标系中），并通过ZMQ发布位姿；play_real订阅该位姿，运行ONNX推理，并通过向手驱动发送命令来闭环。

部署不需要训练。 从Releases (https://github.com/wuji-technology/wuji-mjlab/releases) 下载预训练的policy.onnx和policy_config.json，并将policy.onnx路径作为下面的--ckpt传入。发布的策略就是产生上面演示GIF的策略。

# 完成docs/sim2real/setup.md中的硬件设置后：
pixi run -e deploy home                        # 将手重置到初始位姿
pixi run -e deploy vision                      # 启动立方体观察器（OpenCV预览）
pixi run -e deploy play-real --ckpt <path>     # 闭环控制 + 镜像查看器

• 软件管道与配置: deploy/reorient/README.md
• 硬件设置、3D打印立方体、相机安装、标定: docs/sim2real/setup.md

架构

三层栈：此仓库（任务+部署）→ mjlab (https://github.com/mujocolab/mjlab) → MuJoCo (https://mujoco.org) + mujoco-warp (https://github.com/google-deepmind/mujoco_warp)。PPO通过内嵌的rsl-rl (https://github.com/leggedrobotics/rsl_rl) 后端实现，位于src/wuji_rl_libs/rsl_rl/下。

深入探讨 — 三层图、MDP规范、领域随机化、添加新任务

+--------------------------------------------------------+
| wuji-mjlab (此仓库)                                     |
| +----------------------+  +-------------------------+   |
| | tasks/reorient/      |  | deploy/reorient/      |   |
| | - env cfg + MDP      |  | - real-hand env       |   |
| | - 2组DR              |  | - 视觉管道           |   |
| | - 评估 + 导出       |  | - 闭环控制           |   |
| +----------------------+  +-------------------------+   |
| +----------------------+                                 |
| | utils/               | <- 共享构建块                  |
| +----------------------+                                 |
| +----------------------+                                 |
| | rl/                  | <- 薄RL后端适配器               |
| +----------------------+                                 |
|                                                           |
| src/wuji_rl_libs/rsl_rl/ <- 内嵌的PPO后端               |
+--------------------------------------------------------+
       |                                               |
       v                                               v
+-----------------------+        +---------------------------+
| mjlab (pip / pixi)   |        | torch + onnxruntime      |
| + mujoco-warp        |        | (训练 + 推理)             |
| + mujoco             |        |                           |
+-----------------------+        +---------------------------+

重定向任务 (src/wuji_mjlab/tasks/reorient/)

使用Wuji手进行完整的SO(3)手中重定向。

文件:

任务设计（MDP项、奖励塑造、解剖学分离的接触参数DR组）位于reorient_terms.py中。详见src/wuji_mjlab/tasks/reorient/README.md了解架构不变量的说明，以及deploy/reorient/README.md了解sim2real桥接 — RealHandEnv逐字重用模拟观测和动作管理器，没有并行管道。

添加新任务

1. 创建src/wuji_mjlab/tasks/<new_task>/，包含env cfg工厂。
2. 将所有MDP设计（事件、奖励、终止）放在_terms.py中。config/<robot>/中的机器人特定配置层应该只是薄绑定。
3. 通过register_mjlab_task()在config/<robot>/__init__.py中注册。
4. 在提交前添加一个快速的pixi run train --task <new_task>冒烟测试（规范训练入口是scripts/train/train_rsl_rl.py，通过pixi任务train暴露）。

开发

克隆后，安装pre-commit钩子:

pixi run pre-commit install

每个git commit都会运行ruff、codespell以及.pre-commit-config.yaml中定义的YAML/TOML/大文件检查 — 在CI看到更改之前本地运行。手动运行整个树: pixi run pre-commit run --all-files。

⚠️ 不要pip install包到pixi环境中 — pip依赖不会被pixi.toml / pixi.lock跟踪，并且在下次解析时会消失。编辑pixi.toml并运行pixi install。

相关项目

• wujihandpy (https://github.com/wuji-technology/wujihandpy) — Wuji手SDK（C++核心，带Python绑定）
• wuji-retargeting (https://github.com/wuji-technology/wuji-retargeting) — 手部姿态重定向（Vision Pro / 手套 / 视频 → 机器人关节）
• wujihandros2 (https://github.com/wuji-technology/wujihandros2) — Wuji手的ROS 2驱动
• docs.wuji.tech (https://docs.wuji.tech) — Wuji官方文档门户

致谢

本项目基于以下开源项目构建:

• mjlab (https://github.com/mujocolab/mjlab) — 基于管理器的RL框架
• mujoco-warp (https://github.com/google-deepmind/mujoco_warp) — GPU批处理的MuJoCo物理
• MuJoCo (https://mujoco.org/) — 底层物理引擎
• rsl_rl (https://github.com/leggedrobotics/rsl_rl) — PPO实现（内嵌在src/wuji_rl_libs/下）
• pupil-apriltags (https://github.com/pupil-labs/apriltags) — 部署视觉模块的AprilTag检测器

贡献者

• Jielin Wu (https://github.com/AIRJASON50)
• Shenzhe Yao (https://github.com/LeopoldYao)
• Han Yang (https://github.com/yanghan-a)
• Li Chengmeng (https://github.com/AsahelLee)

引用

如果你发现此项目有用，请考虑引用:

@software{wuji2026mjlab,
  title={Wuji-MJLab: RL Training for Wuji Hand Dexterous Manipulation},
  author={{Wuji Technology}},
  year={2026},
  url={https://github.com/wuji-technology/wuji-mjlab}
}

许可证

Apache 2.0。第三方归因详见LICENSE和NOTICE。