omnisafe

文档 | 已实现算法 | 安装 | 入门 | 许可证

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

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

• 高度模块化框架。 OmniSafe 提供了一个高度模块化的框架，包含了数十种针对不同领域安全强化学习的算法。该框架由于抽象了各种算法类型并设计了良好的 API，使用了适配器和包装器设计组件来弥合差距并实现不同组件之间的无缝交互，因此具有很强的versatility。这种设计允许轻松扩展和定制，使其成为开发人员处理不同类型算法的强大工具。

• 高性能并行计算加速。 通过利用 torch.distributed 的功能，OmniSafe 使用进程并行加速算法学习过程。这使得 OmniSafe 不仅支持环境级异步并行，还包含了agent异步学习。这种方法通过部署并行探索机制增强了训练稳定性并加快了训练过程。OmniSafe 中集成的 agent 异步学习凸显了其致力于为推进 SafeRL 研究提供通用和强大平台的承诺。

• 即用型工具包。 OmniSafe 为训练、基准测试、分析和渲染等任务提供可定制的工具包。教程和用户友好的 API 使初学者和普通用户易于使用，而高级研究人员则可以在无需复杂代码的情况下提高效率。

目录

• 快速开始
  • 安装
    • 前提条件
    • 从源代码安装
    • 从 PyPI 安装
• 已实现算法
  • 示例
    • 算法注册表
    • 支持的环境
    • 自定义环境
    • 使用命令行界面尝试
• 入门
  • 重要提示
  • 快速入门：云端 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

已实现算法

示例

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

算法注册表

支持的环境

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

有关环境的更多信息，请参阅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中，请随时联系我们。

OmniSafe团队

OmniSafe主要由杨耀东教授指导的SafeRL研究团队开发。我们的SafeRL研究团队成员包括张博荣、周嘉仪、戴俊涛、黄伟东、孙瑞阳、潘雪海和纪佳铭。如果您在使用OmniSafe的过程中有任何问题，请随时在GitHub问题页面上提出问题，我们会在2-3个工作日内回复您。

许可证

OmniSafe基于Apache License 2.0发布。