为什么选择安全体育馆？ | 文档 | 安装指南 | 自定义 | 视频

安全体育馆是一个高度可扩展和可定制的安全强化学习（SafeRL）库。它旨在提供一个良好的视角来对比SafeRL算法，并提供一套标准化的环境。我们提供了一组与约束信息兼容的标准API。用户可以通过优雅的代码框架和精心设计的环境探索新的见解。

引用安全体育馆

如果您发现安全体育馆对您有用，请在您的出版物中引用它。

@inproceedings{ji2023safety,
  title={Safety Gymnasium: 一个统一的安全强化学习基准},
  author={季家明 and 张博荣 and 周佳怡 and 潘雪海 and 黄伟东 and 孙瑞阳 and 耿一然 and 钟一帆 and 戴约瑟夫 and 杨耀东},
  booktitle={第三十七届神经信息处理系统会议数据集与基准跟踪},
  year={2023},
  url={https://openreview.net/forum?id=WZmlxIuIGR}
}

v1.1.0和v1.2.0版本注意事项❗️❗️❗️

我们已经更新了Safe Vision系列和Safe Isaac Gym系列的环境。但是，由于包大小限制，我们尚未将版本v1.1.0和v1.2.0上传到PyPI。因此，用户需要手动下载和安装。我们目前建议使用GitHub的Download zip功能来获取我们的包并访问最新环境。未来，我们计划将资源分别部署到云服务，以适应PyPI。请继续关注后续更新。

目前不支持Python 3.11，因为与pygame不兼容。

conda create -n example python=3.8
conda activate example
wget https://github.com/PKU-Alignment/safety-gymnasium/archive/refs/heads/main.zip
unzip main.zip
cd safety-gymnasium-main
pip install -e .

为什么选择Safety-Gymnasium?

这里我们提供了Safety-Gymnasium与现有SafeRL环境库的比较表格。

SafeRL 环境	引擎	向量化 环境	新版Gym API(3)	视觉输入
Safety-Gym	mujoco-py(1)	❌	❌	最小程度支持
safe-control-gym	PyBullet	❌	❌	❌
速度约束(2)	不适用	❌	❌	❌
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。}

环境

我们设计了各种安全增强学习任务，并整合了RL社区的贡献：safety-velocity、safety-run、safety-circle、safety-goal、safety-button等。 我们引入了一个名为Safety-Gymnasium的统一安全增强学习基准环境库。

此外，为了促进社区研究的进展，我们重新设计了Safety-Gym并移除了对mujoco-py的依赖。 我们在MuJoCo的基础上构建了它，并修复了一些错误，更具体的错误报告可以参考Safety-Gym的错误报告。

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

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

代理

点

汽车

赛车

四足机器人

蚂蚁

任务

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

基于视觉的安全强化学习

基于视觉的安全强化学习缺乏真实场景。 尽管原始的Safety-Gym可以最低限度地支持视觉输入，但场景过于相似。 为了便于验证基于视觉的安全强化学习算法，我们开发了一系列真实的基于视觉的安全强化学习任务，目前正在对基准进行验证。

作为开胃菜，图像如下所示：

Race0	Race1	Race2
FormulaOne0	FormulaOne1	FormulaOne2

环境使用

注意： 我们支持基于 Gymnasium APIs 明确表达 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 在 `info` 字典中与字符串键 `'cost'` 关联

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 发布。