本库包含一系列基于 Gymnasium API 的强化学习机器人环境。这些环境运行在 MuJoCo 物理引擎上，并使用由官方维护的 mujoco python 绑定。

文档网站位于 robotics.farama.org。我们还有一个公开的 Discord 服务器（也用于协调开发工作），你可在此加入：https://discord.gg/YymmHrvS

安装

要安装 Gymnasium-Robotics 环境，请使用 pip install gymnasium-robotics。

这些环境还需要安装 DeepMind 提供的 MuJoCo 引擎。物理引擎的安装说明可在 MuJoCo 官网 和 MuJoCo GitHub 仓库 中找到。

请注意，最新版本的环境使用的是 MuJoCo 团队维护的最新 mujoco python 绑定。如果你希望使用依赖于 mujoco-py 的旧版本环境，请通过 pip install gymnasium-robotics[mujoco-py] 来安装该库。

我们支持并测试 Linux 和 macOS 系统。对于 Windows 平台的相关 Pull Request 我们会予以接受，但并不正式支持。

环境

Gymnasium-Robotics 包含以下几类环境：

• Fetch - 一组配备 7 自由度机械臂的环境，要求完成诸如到达目标位置、推动、滑动或抓取放置等操作任务。
• Shadow Dexterous Hand - 一组使用 24 自由度拟人化机械手的环境，需执行与立方体、鸡蛋状物体或笔相关的操作任务。部分变体还在观测空间中加入了来自 92 个触觉传感器的数据。
• MaMuJoCo - 一系列对 Gymnasium/MuJoCo 环境进行多智能体分解后的版本，同时提供一个用于机器人环境分解的框架，采用 pettingzoo.ParallelEnv API。

D4RL 环境现已可用。这些环境经过重构，可能与原始版本的动作和观测空间有所不同，请务必阅读其文档：

• 迷宫环境 - 智能体需要穿越迷宫以到达指定目标位置。可供选择的智能体有两种：一种是受力控制的 2 自由度小球，另一种则是来自 Gymnasium MuJoCo 环境 的经典“蚂蚁”智能体。该环境可初始化为多种不同形状的迷宫，难度逐级递增。
• Adroit 手臂 - 一组使用 Shadow Dexterous Hand 机械手的环境，额外增加了手臂运动的自由度。不同的任务包括敲钉子、开门、转笔以及拾起并移动小球。
• Franka 厨房 - 多任务环境，其中一台 9 自由度的 Franka 机器人被放置在一个包含多种常见家用物品的厨房内。每个任务的目标都是通过与这些物品互动，达到期望的目标状态。

开发中：利用 Minari 生成新的 D4RL 环境数据集。

多目标 API

机器人环境通过继承 GoalEnv 类，扩展了核心 Gymnasium API。新 API 要求环境的观测空间必须是一个包含三个键的字典：

• observation - 环境的实际观测值
• desired_goal - 智能体需要达成的目标
• achieved_goal - 智能体当前实际达成的目标。环境的设计目标是使这个值尽可能接近 desired_goal

此 API 还暴露了奖励函数以及终止和截断信号，以便能够根据不同的目标重新计算其值。这一功能对于使用 hindsight experience replay (HER) 算法非常有用。

以下示例展示了如何利用暴露的奖励、终止和截断函数，通过替换目标来重新计算这些值。info 字典可用于存储重新计算奖励时可能需要的、但与目标无关的信息，例如从模拟中派生的状态。

import gymnasium as gym

env = gym.make("FetchReach-v3")
env.reset()
obs, reward, terminated, truncated, info = env.step(env.action_space.sample())

# 以下条件始终成立：
assert reward == env.compute_reward(obs["achieved_goal"], obs["desired_goal"], info)
assert truncated == env.compute_truncated(obs["achieved_goal"], obs["desired_goal"], info)
assert terminated == env.compute_terminated(obs["achieved_goal"], obs["desired_goal"], info)

# 然而，目标也可以被替换：
substitute_goal = obs["achieved_goal"].copy()
substitute_reward = env.compute_reward(obs["achieved_goal"], substitute_goal，info)
substitute_terminated = env.compute_terminated(obs["achieved_goal"], substitute_goal，info)
substitute_truncated = env.compute_truncated(obs["achieved_goal"], substitute_goal，info)

GoalEnv 类也可用于自定义环境。

项目维护者

主要贡献者：Rodrigo Perez-Vicente、Kallinteris Andreas、Jet Tai

此外，本项目的维护工作也得到了 Farama 团队的广泛支持：farama.org/team。

引用

如果您在研究中使用本项目，请引用以下文献：

@software{gymnasium_robotics2023github,
  author = {罗德里戈·德·拉兹卡诺、安德烈亚斯·卡林特里斯、泰俊杰、李承宰瑞恩、乔丹·特里},
  title = {Gymnasium Robotics},
  url = {http://github.com/Farama-Foundation/Gymnasium-Robotics},
  version = {1.4.0},
  year = {2024},
}

Gymnasium-Robotics 快速上手指南

Gymnasium-Robotics 是一个基于 Gymnasium API 的强化学习机器人环境集合，底层使用 MuJoCo 物理引擎。它提供了包括机械臂抓取、灵巧手操作及多智能体协作等多种经典机器人任务环境。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统：官方支持并测试 Linux 和 macOS。Windows 社区可提交 PR，但非官方正式支持。
• Python 版本：兼容主流 Python 3.x 版本（具体见 PyPI 徽章）。
• 核心依赖：必须安装 DeepMind 开发的 MuJoCo 物理引擎。
  • 请访问 MuJoCo 官网 或 GitHub 仓库 下载并安装对应系统的 MuJoCo 引擎及许可证文件。
  • 确保系统环境变量已正确配置，以便 Python 能够调用 MuJoCo。

安装步骤

1. 安装基础包

使用 pip 安装最新版本的 Gymnasium-Robotics（默认使用官方维护的最新 mujoco Python 绑定）：

pip install gymnasium-robotics

提示：国内用户若遇到下载缓慢问题，可使用清华或阿里镜像源加速：

pip install gymnasium-robotics -i https://pypi.tuna.tsinghua.edu.cn/simple

2. 可选：使用旧版绑定

如果您需要运行依赖旧版 mujoco-py 的环境，请使用以下命令安装：

pip install gymnasium-robotics[mujoco-py]

基本使用

Gymnasium-Robotics 扩展了标准的 Gymnasium API，引入了 GoalEnv 类。环境的观测空间（observation space）是一个字典，包含以下三个关键键：

• observation: 环境的实际观测值。
• desired_goal: 代理需要达成的目标。
• achieved_goal: 代理当前已达成的状态（目标是使其接近 desired_goal）。

这种设计原生支持 Hindsight Experience Replay (HER) 等算法，允许动态重计算奖励和终止信号。

代码示例

以下示例展示了如何加载 FetchReach-v3 环境并执行一步交互：

import gymnasium as gym

# 创建环境
env = gym.make("FetchReach-v3")

# 重置环境
obs, info = env.reset()

# 执行随机动作
action = env.action_space.sample()
obs, reward, terminated, truncated, info = env.step(action)

# 验证奖励计算逻辑（标准流程）
assert reward == env.compute_reward(obs["achieved_goal"], obs["desired_goal"], info)
assert truncated == env.compute_truncated(obs["achieved_goal"], obs["desired_goal"], info)
assert terminated == env.compute_terminated(obs["achieved_goal"], obs["desired_goal"], info)

# HER 示例：替换目标并重新计算奖励
substitute_goal = obs["achieved_goal"].copy()
substitute_reward = env.compute_reward(obs["achieved_goal"], substitute_goal, info)
substitute_terminated = env.compute_terminated(obs["achieved_goal"], substitute_goal, info)
substitute_truncated = env.compute_truncated(obs["achieved_goal"], substitute_goal, info)

print(f"原始奖励：{reward}, 替换目标后奖励：{substitute_reward}")

env.close()

可用环境组

安装成功后，您可以探索以下几类主要环境：

• Fetch: 7 自由度机械臂任务（到达、推、滑、拾取放置）。
• Shadow Dexterous Hand: 24 自由度仿生灵巧手任务（操作立方体、鸡蛋、笔等），部分包含触觉传感器数据。
• MaMuJoCo: 基于 PettingZoo API 的多智能体分解环境。
• D4RL 系列: 包含迷宫导航 (Maze)、Adroit 机械臂及 Franka 厨房多任务环境。