omnisafe

<div align="center"> <img src="https://yellow-cdn.veclightyear.com/835a84d5/22ef185b-2408-4df6-b579-c6fe4bbdbdbd.png" width="75%"/> </div> <div align="center">

</div> <p align="center"> <a href="https://omnisafe.readthedocs.io">文档</a> | <a href="https://github.com/PKU-Alignment/omnisafe#implemented-algorithms">已实现算法</a> | <a href="https://github.com/PKU-Alignment/omnisafe#installation">安装</a> | <a href="https://github.com/PKU-Alignment/omnisafe#getting-started">入门</a> | <a href="https://github.com/PKU-Alignment/omnisafe#license">许可证</a> </p>

OmniSafe 是一个旨在加速安全强化学习（RL）研究的基础框架。它为安全 RL 算法提供了全面可靠的基准，同时也为研究人员提供了即用型的模块化工具包。SafeRL 旨在开发能够最小化意外伤害或不安全行为风险的算法。

OmniSafe 是安全强化学习领域首个统一学习框架，旨在促进 SafeRL 学习社区的成长。OmniSafe 的主要特点：

高度模块化框架。 OmniSafe 提供了一个高度模块化的框架，包含了数十种针对不同领域安全强化学习的算法。该框架由于抽象了各种算法类型并设计了良好的 API，使用了适配器和包装器设计组件来弥合差距并实现不同组件之间的无缝交互，因此具有很强的versatility。这种设计允许轻松扩展和定制，使其成为开发人员处理不同类型算法的强大工具。
高性能并行计算加速。 通过利用 torch.distributed 的功能，OmniSafe 使用进程并行加速算法学习过程。这使得 OmniSafe 不仅支持环境级异步并行，还包含了agent异步学习。这种方法通过部署并行探索机制增强了训练稳定性并加快了训练过程。OmniSafe 中集成的 agent 异步学习凸显了其致力于为推进 SafeRL 研究提供通用和强大平台的承诺。
即用型工具包。 OmniSafe 为训练、基准测试、分析和渲染等任务提供可定制的工具包。教程和用户友好的 API 使初学者和普通用户易于使用，而高级研究人员则可以在无需复杂代码的情况下提高效率。

训练视频

目录

快速开始
- 安装
已实现算法
- 示例
入门
- 重要提示
- 快速入门：云端 Colab
更新日志
引用 OmniSafe
使用 OmniSafe 的出版物
OmniSafe 团队
许可证

快速开始

安装

前提条件

OmniSafe 需要 Python 3.8+ 和 PyTorch 1.10+。

我们支持并测试 Linux 上的 Python 3.8、3.9、3.10。同时，我们还支持 macOS 的 M1 和 M2 版本。我们会接受与 Windows 相关的 PR，但不正式支持它。

从源代码安装

# 克隆仓库
git clone https://github.com/PKU-Alignment/omnisafe.git
cd omnisafe

# 创建 conda 环境
conda env create --file conda-recipe.yaml
conda activate omnisafe

# 安装 omnisafe
pip install -e .

从 PyPI 安装

OmniSafe 托管在 / 。

pip install omnisafe

已实现算法

<details> <summary><b><big>最新 SafeRL 论文</big></b></summary>

[AAAI 2023] 用于安全强化学习的增强型近端策略优化 (APPO)
[NeurIPS 2022] 约束更新投影方法用于安全策略优化 (CUP)
[NeurIPS 2022] 安全状态增强对安全探索的影响 (Simmer)
[NeurIPS 2022] 基于约束近端策略优化算法的模型安全深度强化学习
[ICML 2022] Sauté RL：使用状态增强的几乎确定安全的强化学习 (SauteRL)
[IJCAI 2022] 用于安全强化学习的惩罚近端策略优化
[AAAI 2022] 用于基于模型安全强化学习的保守自适应惩罚 (CAP)

</details> <details> <summary><b><big>算法列表</big></b></summary> <summary><b><big>在策略 SafeRL</big></b></summary> <summary><b><big>离策略 SafeRL</big></b></summary>

[预印本 2019] DDPG 的拉格朗日版本 (DDPGLag)
[预印本 2019] TD3 的拉格朗日版本 (TD3Lag)
[预印本 2019] SAC 的拉格朗日版本 (SACLag)
[ICML 2020] 通过 PID 拉格朗日方法实现强化学习中的响应式安全 (DDPGPID)
[ICML 2020] 通过 PID 拉格朗日方法实现强化学习中的响应式安全 (TD3PID)
[ICML 2020] 通过 PID 拉格朗日方法实现强化学习中的响应式安全 (SACPID)

<summary><b><big>基于模型的 SafeRL</big></b></summary> - [ ] **[NeurIPS 2021]** [通过想象近期未来实现安全强化学习 (SMBPO)](https://arxiv.org/abs/2202.07789) - [x] **[CoRL 2021 (口头报告)]** [使用在线规划进行离策略学习 (SafeLOOP)](https://arxiv.org/abs/2008.10066) - [x] **[AAAI 2022]** [基于模型的安全强化学习的保守和自适应惩罚 (CAP)](https://arxiv.org/abs/2112.07701) - [x] **[NeurIPS 2022]** [基于约束近端策略优化算法的模型安全深度强化学习](https://arxiv.org/abs/2210.07573) - [ ] **[ICLR 2022]** [基于贝叶斯世界模型的约束策略优化 (LA-MBDA)](https://arxiv.org/abs/2201.09802) - [x] **[ICML 2022 研讨会]** [使用鲁棒交叉熵方法的约束模型强化学习 (RCE)](https://arxiv.org/abs/2010.07968) - [x] **[NeurIPS 2018]** [用于安全强化学习的约束交叉熵方法 (CCE)](https://proceedings.neurips.cc/paper/2018/hash/34ffeb359a192eb8174b6854643cc046-Abstract.html) <summary><b><big>离线安全强化学习</big></b></summary>

BCQ的拉格朗日版本 (BCQ-Lag)
CRR的约束版本 (C-CRR)
[AAAI 2022] 用于安全离线强化学习的约束惩罚Q学习 CPQ
[ICLR 2022 (聚焦)] COptiDICE：通过平稳分布校正估计的离线约束强化学习
[ICML 2022] 约束离线策略优化 (COPO)

[RA-L 2021] Recovery RL：使用学习恢复区域的安全强化学习
[ICML 2022] Sauté RL：使用状态增强几乎肯定安全的强化学习 (SauteRL)
[NeurIPS 2022] 安全状态增强对安全探索的影响

</details>

示例

cd examples
python train_policy.py --algo PPOLag --env-id SafetyPointGoal1-v0 --parallel 1 --total-steps 10000000 --device cpu --vector-env-nums 1 --torch-threads 1

算法注册表

<table> <thead> <tr> <th>领域</th> <th>类型</th> <th>算法注册表</th> </tr> </thead> <tbody> <tr> <td rowspan="5">在线策略</td> <td rowspan="2">原始-对偶</td> <td>TRPOLag; PPOLag; PDO; RCPO</td> </tr> <tr> <td>TRPOPID; CPPOPID</td> </tr> <tr> <td>凸优化</td> <td><span style="font-weight:400;font-style:normal">CPO; PCPO; </span>FOCOPS; CUP</td> </tr> <tr> <td>惩罚函数</td> <td>IPO; P3O</td> </tr> <tr> <td>原始</td> <td>OnCRPO</td> </tr> <tr> <td rowspan="2">离线策略</td> <td rowspan="2">原始-对偶</td> <td>DDPGLag; TD3Lag; SACLag</td> </tr> <tr> <td><span style="font-weight:400;font-style:normal">DDPGPID; TD3PID; SACPID</span></td> </tr> <tr> <td rowspan="2">基于模型</td> <td>在线规划</td> <td>SafeLOOP; CCEPETS; RCEPETS</td> </tr> <tr> <td><span style="font-weight:400;font-style:normal">悲观估计</span></td> <td>CAPPETS</td> </tr> <td rowspan="2">离线</td> <td>基于Q学习</td> <td>BCQLag; C-CRR</td> </tr> <tr> <td>基于DICE</td> <td>COptDICE</td> </tr> <tr> <td rowspan="3">其他MDP公式</td> <td>ET-MDP</td> <td><span style="font-weight:400;font-style:normal">PPO</span>EarlyTerminated; TRPOEarlyTerminated</td> </tr> <tr> <td>SauteRL</td> <td>PPOSaute; TRPOSaute</td> </tr> <tr> <td>SimmerRL</td> <td><span style="font-weight:400;font-style:normal">PPOSimmerPID; TRPOSimmerPID</span></td> </tr> </tbody> </table>

支持的环境

以下是Safety-Gymnasium支持的环境列表：

<table border="1"> <thead> <tr> <th>类别</th> <th>任务</th> <th>智能体</th> <th>示例</th> </tr> </thead> <tbody> <tr> <td rowspan="4">安全导航</td> <td>Goal[012]</td> <td rowspan="4">Point, Car, Racecar, Ant</td> <td rowspan="4">SafetyPointGoal1-v0</td> </tr> <tr> <td>Button[012]</td> </tr> <tr> <td>Push[012]</td> </tr> <tr> <td>Circle[012]</td> </tr> <tr> <td>安全速度</td> <td>Velocity</td> <td>HalfCheetah, Hopper, Swimmer, Walker2d, Ant, Humanoid</td> <td>SafetyHumanoidVelocity-v1</td> </tr> <tr> <td rowspan="4">Safe Isaac Gym</td> <td>OverSafeFinger</td> <td rowspan="4">ShadowHand</td> <td rowspan="4">ShadowHandOverSafeFinger</td> </tr> <tr> <td>OverSafeJoint</td> </tr> <tr> <td>CatchOver2UnderarmSafeFinger</td> </tr> <tr> <td>CatchOver2UnderarmSafeJoint</td> </tr> </tbody> </table>

有关环境的更多信息，请参阅Safety-Gymnasium。

自定义环境

我们提供了一个灵活的自定义环境接口，允许用户在不修改OmniSafe源代码的情况下实现以下功能：

使用OmniSafe在自定义环境上训练算法。
使用指定的个性化参数创建环境。
在Logger中完成环境特定信息的记录。

我们提供了关于从头开始自定义环境和从社区自定义环境的分步教程，为您详细介绍如何使用OmniSafe的这一出色功能。

注意：如果您在自定义环境时遇到困难，请随时开启issue或discussion。如果您愿意贡献环境接口的实现，我们也欢迎Pull requests。

使用命令行界面

pip install omnisafe

omnisafe --help  # 寻求帮助

omnisafe benchmark --help  # benchmark也可以替换为'eval'、'train'、'train-config'

# 快速为您的研究进行基准测试，只需指定：
# 1. exp_name
# 2. num_pool（并发进程数）
# 3. 配置文件路径（格式参考omnisafe/examples/benchmarks）

# 这里我们在./tests/saved_source中提供了一个示例。
# 您可以按照它来设置您的benchmark_config.yaml
omnisafe benchmark test_benchmark 2 ./tests/saved_source/benchmark_config.yaml

# 快速评估和渲染您训练的策略，只需指定：
# 1. 您训练的算法路径
omnisafe eval ./tests/saved_source/PPO-{SafetyPointGoal1-v0} --num-episode 1

# 快速训练一些算法以验证您的想法
# 注意：使用`key1:key2`，您可以递归选择超参数的键，使用`--custom-cfgs`，您可以通过命令行添加自定义配置
omnisafe train --algo PPO --total-steps 2048 --vector-env-nums 1 --custom-cfgs algo_cfgs:steps_per_epoch --custom-cfgs 1024

# 通过保存的配置文件快速训练一些算法，格式与默认格式相同
omnisafe train-config ./tests/saved_source/train_config.yaml

入门指南

重要提示

我们已经提供了各种算法的基准测试结果，包括在线策略、离线策略、基于模型和离线方法，以及参数调优分析。请参考以下内容：

快速开始：云端Colab

通过一系列Google Colab笔记本轻松快速地探索OmniSafe：

入门指南介绍OmniSafe的基本用法，让用户能够快速上手。
CLI命令介绍如何使用OmniSafe的命令行工具。

我们非常乐意与用户合作，创建各种语言的教程。请参考我们当前支持的语言列表。如果您有兴趣将教程翻译成新的语言或改进现有版本，请向我们提交PR。

更新日志

请查看CHANGELOG.md。

引用OmniSafe

如果您觉得OmniSafe有用或在研究中使用了OmniSafe，请在您的出版物中引用它。

@article{omnisafe,
  title   = {OmniSafe: An Infrastructure for Accelerating Safe Reinforcement Learning Research},
  author  = {Jiaming Ji, Jiayi Zhou, Borong Zhang, Juntao Dai, Xuehai Pan, Ruiyang Sun, Weidong Huang, Yiran Geng, Mickel Liu, Yaodong Yang},
  journal = {arXiv preprint arXiv:2305.09304},
  year    = {2023}
}

使用OmniSafe的出版物

我们列出了一份使用OmniSafe进行算法实现或实验的论文清单。如果您愿意将您的工作列入此清单，或者希望将您的实现正式整合到OmniSafe中，请随时联系我们。

论文	发表方
Off-Policy Primal-Dual Safe Reinforcement Learning	ICLR 2024
Safe Offline Reinforcement Learning with Feasibility-Guided Diffusion Model	ICLR 2024
Iterative Reachability Estimation for Safe Reinforcement Learning	NeurIPS 2023
Balance Reward and Safety Optimization for Safe Reinforcement Learning: A Perspective of Gradient Manipulation	AAAI 2024
Learning Safety Constraints From Demonstration Using One-Class Decision Trees	AAAI 2024 WorkShops