![License](https://img.shields.io/github/license/PKU-Alignment/safety-gymnasium?label=license&logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCIgd2lkdGg9IjI0IiBoZWlnaHQ9IjI0IiBmaWxsPSIjZmZmZmZmIj48cGF0aCBmaWxsLXJ1bGU9ImV2ZW5vZGQiIGQ9Ik0xMi43NSAyLjc1YS43NS43NSAwIDAwLTEuNSAwVjQuNUg5LjI3NmExLjc1IDEuNzUgMCAwMC0uOTg1LjMwM0w2LjU5NiA1Ljk1N7EuMjUuMjUgMCAwMTYuNDU1IDZIMi4zNTNhLjc1Ljc1IDAgMTAwIDEuNUHzLjkzTC41NjMgMTUuMThhLjc2Mi43NjIgMCAwMC4yMS44OGMuMDguODU0LjE2MS4xMjUuMzA9LjIy1eu1ODYuMTIxLjQ5Mi4yNugtujY9LjQz3Lj6OCuMzMTEgMS42NjIuNjIgMi44N7YuNj2a6i9gLS9uOS4tujY9Lj62a6i9Lj62a6i9Lj62a6i9Lj62a6i9Lj62a6i9Lj62a6i9Lj62a6i9Lj62a6i9Lj62a6i9Lj62a6i9Lj62a6i9Lj62a6i9Lj62a6i9Lj62a6i9Lj62a6i9Lj62a6i9Lj62a6i9Lj62a6i9Lj62a6i9Lj62a6i9Lj62a6i9Lj62a6i9Lj62a6i9Lj62a6i9Lj62a6i9Lj62a6i9Lj62a6i9Lj62a6i9Lj62a6i9Lj62a6i9Lj62a6i9Lj62a6i9Lj62a6i9Lj62a6i9Lj62a6i9Lj62a6i9Lj62a6i9Lj62a6i9Lj62a6i9Lj62a6i9Lj62a6i9Lj62a6i9Lj62a6i9Lj62a6i9Lj62a6i......

为什么选择 Safety-Gymnasium？

在这里，我们提供一张表格，用于比较 Safety-Gymnasium 和现有的 SafeRL 环境库。

SafeRL Envs	引擎	向量化 环境	新 Gym API(3)	视觉输入
Safety-Gym	mujoco-py(1)	❌	❌	极少支持
safe-control-gym	PyBullet	❌	❌	❌
速度约束(2)	N/A	❌	❌	❌
mujoco-circle	PyTorch	❌	❌	❌
Safety-Gymnasium	MuJoCo 2.3.0+	✅	✅	✅

^{(1): 维护状态（仅限于错误修复和小更新）；最后一次提交是在 2021 年 11 月 19 日。Safety-Gym 依赖于 mujoco-py 2.0.2.7，该版本于 2019 年 10 月 12 日更新。
(2): 目前没有官方的速度相关环境库，其相关的成本约束是根据现有信息构建的。然而，这一任务在 SafeRL 的研究中被广泛使用，因此我们在 Safety-Gymnasium 中将其封装起来。
(3): 在 gym 0.26.0 版本的更新中，重新定义了新的交互 API。}

---

环境

我们设计了多种增强安全性的学习任务，并整合了强化学习社区的贡献：safety-velocity、safety-run、safety-circle、safety-goal、safety-button 等。我们推出了一套统一的安全增强型学习基准环境库，名为 Safety-Gymnasium。

此外，为了促进社区研究的发展，我们对 Safety-Gym 进行了重新设计，并去除了对 mujoco-py 的依赖。我们基于 MuJoCo 构建了它，并修复了一些 bug。更详细的 bug 报告可以参考 Safety-Gym 的 BUG 报告。

以下是我们目前支持的所有环境列表：

类别	任务	智能体	示例
安全导航	Button[012]	Point, Car, Doggo, Racecar, Ant	SafetyPointGoal1-v0
	Goal[012]
	Push[012]
	Circle[012]
安全速度	Velocity	HalfCheetah, Hopper, Swimmer, Walker2d, Ant, Humanoid	SafetyAntVelocity-v1
安全视觉	BuildingButton[012]	Point, Car, Doggo, Racecar, Ant	SafetyFormulaOne1-v0
	BuildingGoal[012]
	BuildingPush[012]
	FadingEasy[012]
	FadingHard[012]
	Race[012]
	FormulaOne[012]
安全多智能体	MultiGoal[012]	Multi-Point, Multi-Ant	SafetyAntMultiGoal1-v0
	多智能体速度	6x1HalfCheetah, 2x3HalfCheetah, 3x1Hopper, 2x1Swimmer, 2x3Walker2d, 2x4Ant, 4x2Ant, 9|8Humanoid	Safety2x4AntVelocity-v0
	FreightFrankaCloseDrawer(多智能体)	FreightFranka	FreightFrankaCloseDrawer(多智能体)
	FreightFrankaPickAndPlace(多智能体)
	ShadowHandCatchOver2UnderarmSafeFinger(多智能体)	ShadowHands	ShadowHandCatchOver2UnderarmSafeJoint(多智能体)
	ShadowHandCatchOver2UnderarmSafeJoint(多智能体)
	ShadowHandOverSafeFinger(多智能体)
	ShadowHandOverSafeJoint(多智能体)
安全 Isaac Gym	FreightFrankaCloseDrawer	FreightFranka	FreightFrankaCloseDrawer
	FreightFrankaPickAndPlace
	ShadowHandCatchOver2UnderarmSafeFinger	ShadowHands	ShadowHandCatchOver2UnderarmSafeJoint
	ShadowHandCatchOver2UnderarmSafeJoint
	ShadowHandOverSafeFinger
	ShadowHandOverSafeJoint

以下是一些 安全导航 任务的截图。

智能体

点

汽车

赛车

小狗

蚂蚁

任务

目标0	目标1	目标2
按钮0	按钮1	按钮2
推动0	推动1	推动2
圆圈0	圆圈1	圆圈2

基于视觉的安全强化学习

基于视觉的安全强化学习缺乏真实的场景。尽管最初的 Safety-Gym 能够勉强支持视觉输入，但其场景过于相似。为了便于验证基于视觉的安全强化学习算法，我们开发了一组真实的基于视觉的安全强化学习任务，目前这些任务正在基准测试中进行验证。

作为开胃菜，以下是相关图片：

Race0	Race1	Race2
FormulaOne0	FormulaOne1	FormulaOne2

环境使用

注： 我们支持基于 Gymnasium API 显式地表达 cost。step 方法会返回 6 个值 (next_obervation, reward, cost, terminated, truncated, info)，其中多了一个 cost 字段。

import safety_gymnasium

env_id = 'SafetyPointGoal1-v0'
env = safety_gymnasium.make(env_id)

obs, info = env.reset()
while True:
    act = env.action_space.sample()
    obs, reward, cost, terminated, truncated, info = env.step(act)
    if terminated or truncated:
        break
    env.render()

我们还提供了两个便捷的包装器，用于在 Safety-Gymnasium 环境与标准 Gymnasium API 之间进行转换。

# Safety-Gymnasium API：step 返回 (next_obervation, reward, cost, terminated, truncated, info)
# Gymnasium API：       step 返回 (next_obervation, reward, terminated, truncated, info)，而 cost 则包含在与字符串键 `'cost'` 关联的 `info` 字典中。

safety_gymnasium_env = safety_gymnasium.make(env_id)
gymnasium_env = safety_gymnasium.wrappers.SafetyGymnasium2Gymnasium(safety_gymnasium_env)

safety_gymnasium_env = safety_gymnasium.wrappers.Gymnasium2SafetyGymnasium(gymnasium_env)

用户可以轻松地应用 Gymnasium 包装器，如下所示：

import gymnasium
import safety_gymnasium

def make_safe_env(env_id):
    safe_env = safety_gymnasium.make(env_id)
    env = safety_gymnasium.wrappers.SafetyGymnasium2Gymnasium(safe_env)
    env = gymnasium.wrappers.SomeWrapper1(env)
    env = gymnasium.wrappers.SomeWrapper2(env, argname1=arg1, argname2=arg2)
    ...
    env = gymnasium.wrappers.SomeWrapperN(env)
    safe_env = safety_gymnasium.wrappers.Gymnasium2SafetyGymnasium(env)
    return safe_env

或者：

import functools

import gymnasium
import safety_gymnasium

def make_safe_env(env_id):
    return safety_gymnasium.wrappers.with_gymnasium_wrappers(
        safety_gymnasium.make(env_id),
        gymnasium.wrappers.SomeWrapper1,
        functools.partial(gymnasium.wrappers.SomeWrapper2, argname1=arg1, argname2=arg2),
        ...,
        gymnasium.wrappers.SomeWrapperN,
    )

此外，对于所有 Safety-Gymnasium 环境，我们还提供了对应的 Gymnasium 环境，其环境 ID 中带有后缀 Gymnasium。例如：

import gymnasium
import safety_gymnasium

safety_gymnasium.make('SafetyPointGoal1-v0')    # step 返回 (next_obervation, reward, cost, terminated, truncated, info)
gymnasium.make('SafetyPointGoal1Gymnasium-v0')  # step 返回 (next_obervation, reward, terminated, truncated, info)

---

安装

从 PyPI 安装

pip install safety-gymnasium

从源码安装

conda create -n <envname> python=3.8
conda activate <envname>

git clone https://github.com/PKU-Alignment/safety-gymnasium.git
cd safety-gymnasium
pip install -e .

重要提示

如果您在服务器上无法成功渲染，可以尝试以下步骤：

echo "export MUJOCO_GL=osmesa" >> ~/.bashrc
source ~/.bashrc
apt-get install libosmesa6-dev
apt-get install python3-opengl

---

使用键盘进行调试

对于简单的智能体，我们提供了通过键盘控制机器人运动的功能，以方便调试。只需在任务名称后添加 Debug 后缀，例如 SafetyCarGoal2Debug-v0，然后使用 I、K、J 和 L 键来引导机器人的移动。

对于更复杂的智能体，您还可以根据特定的输入设备编写自定义的控制逻辑。为此，只需为指定的智能体实现 BaseAgent 中的 debug 方法即可。

自定义您的环境

我们构建了一个高度可扩展的代码框架，便于您理解和掌握，并且平均只需不到 100 行代码即可设计出适合您研究的环境。

有关详细信息，请参阅我们的文档。以下是一个最小示例：

# 导入您想要使用的对象
# 或者您也可以自行定义特定的对象，只要符合我们的规范即可
from safety_gymnasium.assets.geoms import Apples
from safety_gymnasium.bases import BaseTask

# 继承 BaseTask 类
class MytaskLevel0(BaseTask):
    def __init__(self, config):
        super().__init__(config=config)
        # 定义一些属性
        self.num_steps = 500
        self.agent.placements = [(-0.8, -0.8, 0.8, 0.8)]
        self.agent.keepout = 0
        self.lidar_conf.max_dist = 6
        # 将对象添加到环境中
        self.add_geoms(Apples(num=2, size=0.3))

    def calculate_reward(self):
        # 实现您的奖励函数
        # 注意：成本计算是基于对象的，因此会自动完成
        reward = 1
        return reward

    def specific_reset(self):
        # 根据您的任务需求

    def specific_step(self):
        # 根据您的任务需求

    def update_world(self):
        # 根据您的任务需求

    @property
    def goal_achieved(self):
        # 根据您的任务需求

许可证

Safety-Gymnasium 采用 Apache License 2.0 许可证发布。

conda create -n safety-gym python=3.8
conda activate safety-gym

wget https://github.com/PKU-Alignment/safety-gymnasium/archive/refs/heads/main.zip
unzip main.zip
cd safety-gymnasium-main

pip install -e .

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

import safety_gymnasium as sg

# 1. 创建环境
# 示例：安全导航任务，智能体为 Point，任务为 Goal1
env = sg.make("SafetyPointGoal1-v0")

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

# 3. 运行一步
action = env.action_space.sample()  # 随机采样动作
next_obs, reward, terminated, truncated, info = env.step(action)

# 4. 获取关键安全指标
# cost: 当前步的约束代价 (例如碰撞惩罚)
# cost_rate: 累积代价率 (部分环境支持)
current_cost = info.get('cost', 0)

print(f"Observation shape: {next_obs.shape}")
print(f"Reward: {reward}, Cost: {current_cost}")
print(f"Done: {terminated or truncated}")

# 5. 关闭环境
env.close()

import safety_gymnasium as sg

# 打印所有注册的环境 ID
for env_id in sorted(sg.envs.registry.keys()):
    if env_id.startswith("Safety"):
        print(env_id)