OpenRL-v0.2.1 更新于 2023 年 12 月 20 日
主分支是 OpenRL 的最新版本,正在积极开发中。如果您只是想尝试 OpenRL,您可以切换到稳定分支。
欢迎来到 OpenRL
Documentation | 中文介绍 | 中文文档
OpenRL 是一个开源的通用强化学习研究框架,支持多种任务的训练,如单智能体、多智能体、离线强化学习、自对弈和自然语言处理。 基于 PyTorch 开发,OpenRL 的目标是为强化学习研究社区提供一个易于使用、灵活、高效和可持续的平台。
目前,OpenRL 支持的功能有:
-
易于使用的通用接口,支持所有任务/环境的训练
-
支持单智能体和多智能体任务
-
支持使用专家数据集进行离线强化学习训练
-
支持自对弈训练
-
支持自然语言任务(如对话)的强化学习训练
-
支持 DeepSpeed
-
从 Hugging Face 导入模型和数据集。支持从 Hugging Face 加载 Stable-baselines3 模型 进行测试和训练。
-
教程 教您如何将用户定义的环境集成到 OpenRL 中。
-
支持 LSTM、GRU、Transformer 等模型
-
多种训练加速方法,包括自动混合精度训练和半精度策略网络的数据收集
-
支持用户定义的训练模型、奖励模型、训练数据和环境
-
支持 gymnasium 环境
-
支持 回调函数,可用于实现各种功能,如日志记录、保存和提前停止
-
支持字典观察空间
-
支持流行的可视化工具,如 wandb 和 tensorboardX
-
支持串行或并行环境训练,同时确保两种模式下结果的一致性
-
中文和英文文档
-
提供单元测试和代码覆盖测试
-
符合 Black 代码风格指南和类型检查
OpenRL 当前支持的算法(更多详情请参阅 Gallery):
- Proximal Policy Optimization (PPO)
- Dual-clip PPO
- Multi-agent PPO (MAPPO)
- Joint-ratio Policy Optimization (JRPO)
- Generative Adversarial Imitation Learning (GAIL)
- Behavior Cloning (BC)
- Advantage Actor-Critic (A2C)
- 自对弈
- Deep Q-Network (DQN)
- Multi-Agent Transformer (MAT)
- Value-Decomposition Network (VDN)
- Soft Actor Critic (SAC)
- Deep Deterministic Policy Gradient (DDPG)
OpenRL 当前支持的环境(更多详情请参阅 Gallery):
- Gymnasium
- MuJoCo
- PettingZoo
- MPE
- 聊天机器人
- Atari
- StarCraft II
- SMACv2
- Omniverse Isaac Gym
- DeepMind Control
- Snake
- gym-pybullet-drones
- EnvPool
- GridWorld
- Super Mario Bros
- Gym Retro
- Crafter
此框架已由 OpenRL-Lab 团队多次迭代,并应用于学术研究中。 现已成为一个成熟的强化学习框架。
OpenRL-Lab 将继续维护和更新 OpenRL,我们欢迎大家加入我们的 开源社区, 为强化学习的发展做出贡献。
关于 OpenRL 的更多信息,请参阅 文档。
大纲
为什么选择 OpenRL
在此我们提供了 OpenRL 与现有流行强化学习库的比较表。 OpenRL 采用模块化设计和高级抽象,使用户能够通过统一且用户友好的界面,完成各种任务的训练。
库 | 自然语言处理/强化学习人类反馈 | 多智能体 | 自对弈训练 | 离线强化学习 | DeepSpeed |
---|---|---|---|---|---|
OpenRL | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |
Stable Baselines3 | :x: | :x: | :x: | :x: | :x: |
Ray/RLlib | :x: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :x: |
DI-engine | :x: | :heavy_check_mark: | not fullly supported | :heavy_check_mark: | :x: |
Tianshou | :x: | not fullly supported | not fullly supported | :heavy_check_mark: | :x: |
MARLlib | :x: | :heavy_check_mark: | not fullly supported | :x: | :x: |
MAPPO Benchmark | :x: | :heavy_check_mark: | :x: | :x: | :x: |
RL4LMs | :heavy_check_mark: | :x: | :x: | :x: | :x: |
trlx | :heavy_check_mark: | :x: | :x: | :x: | :heavy_check_mark: |
trl | :heavy_check_mark: | :x: | :x: | :x: | :heavy_check_mark: |
TimeChamber | :x: | :x: | :heavy_check_mark: | :x: | :x: |
安装
用户可以通过 pip 直接安装 OpenRL:
pip install openrl
如果用户使用 Anaconda 或 Miniconda,也可以通过 conda 安装 OpenRL:
conda install -c openrl openrl
想要修改源代码的用户也可以从源代码安装 OpenRL:
git clone https://github.com/OpenRL-Lab/openrl.git && cd openrl
pip install -e .
安装后,用户可以通过命令行检查 OpenRL 的版本:
openrl --version
使用 Docker
OpenRL 目前提供了带有和不带 GPU 支持的 Docker 镜像。 如果用户的电脑没有 NVIDIA GPU,可以使用以下命令获取不带 GPU 插件的镜像:
sudo docker pull openrllab/openrl-cpu
如果用户想要通过 GPU 加速训练,可以使用以下命令获取带 GPU 插件的镜像:
sudo docker pull openrllab/openrl
成功获取镜像后,用户可以使用以下命令运行 OpenRL 的 Docker 镜像:
# 不使用 GPU 加速
sudo docker run -it openrllab/openrl-cpu
# 使用 GPU 加速
sudo docker run -it --gpus all --net host openrllab/openrl
进入 Docker 容器后,用户可以使用以下命令检查 OpenRL 的版本并运行测试用例:
# 在 Docker 容器中检查 OpenRL 版本
openrl --version
# 运行测试用例
openrl --mode train --env CartPole-v1
快速开始
OpenRL 为强化学习的初学者提供了一个简单易用的界面。
下面是一个使用 PPO 算法训练 CartPole
环境的示例:
# train_ppo.py
from openrl.envs.common import make
from openrl.modules.common import PPONet as Net
from openrl.runners.common import PPOAgent as Agent
env = make("CartPole-v1", env_num=9) # 创建环境并将环境并行数设置为 9
net = Net(env) # 创建神经网络
agent = Agent(net) # 初始化智能体
agent.train(
total_time_steps=20000) # 开始训练并将总步数设置为 2 万
使用 OpenRL 训练智能体只需要四个简单步骤: 创建环境 => 初始化模型 => 初始化智能体 => 开始训练!
对于训练好的智能体,用户也可以轻松的进行测试:
# train_ppo.py
from openrl
```xml
agent = Agent(Net(make("CartPole-v1", env_num=9))) # 初始化训练器。
agent.train(total_time_steps=20000)
# 创建一个测试环境,将环境的并行度设置为9,并将渲染模式设置为group_human。
env = make("CartPole-v1", env_num=9, render_mode="group_human")
agent.set_env(env) # 代理需要一个交互式环境。
obs, info = env.reset() # 初始化环境以获得初始观察和环境信息。
while True:
action, _ = agent.act(obs) # 代理根据环境观察预测下一个动作。
# 根据动作,环境执行一步操作,获得下一个观察值、奖励、是否结束和环境信息。
obs, r, done, info = env.step(action)
if any(done): break
env.close() # 关闭测试环境
在普通笔记本电脑上执行上述代码只需几秒钟即可完成训练。以下显示的是代理的可视化效果:
<div align="center">
<img src="https://yellow-cdn.veclightyear.com/2b54e442/ed213645-6bd4-4ba1-85ff-b528feb279ca.gif"></a>
</div>
**提示:** 用户也可以通过在终端执行命令行快速训练`CartPole`环境。
```bash
openrl --mode train --env CartPole-v1
对于多代理和自然语言处理等训练任务,OpenRL还提供了同样简单易用的界面。
有关如何进行多代理训练、设置训练的超参数、加载训练配置、使用wandb、保存GIF动画等信息,请参阅:
有关自然语言任务训练、加载Hugging Face上的模型/数据集、自定义训练模型/奖励模型等信息,请参阅:
更多关于OpenRL的信息,请参阅文档。
Gallery
为了方便用户熟悉框架,我们在 Gallery 中提供了更多使用OpenRL的示例和演示。 也欢迎用户将自己的训练示例和演示贡献到Gallery。
使用OpenRL的项目
我们在 OpenRL Project 中列出了使用OpenRL的研究项目。 如果您在您的研究项目中使用了OpenRL,也欢迎加入这个列表。
反馈和贡献
- 如果您有任何问题或发现错误,您可以在Issues中检查或提问。
- 加入QQ群:OpenRL官方交流QQ群
- 加入slack群组,与我们讨论OpenRL的使用和开发。
- 加入Discord群组,与我们讨论OpenRL的使用和开发。
- 发送电子邮件至:huangsy1314@163.com
- 加入GitHub Discussion。
OpenRL框架仍在持续开发和文档编写中。 我们欢迎您加入我们,共同改进这个项目:
维护者
目前,OpenRL由以下维护者维护:
- 黄世宇(@huangshiyu13)
- 陈文则(@WentseChen)
- 孙怡文(@YiwenAI)
欢迎更多贡献者加入我们的维护团队(发送电子邮件至huangsy1314@163.com申请加入OpenRL团队)。
支持者
↳ 贡献者
↳ Stargazers
↳ Forkers
引用OpenRL
如果我们的工作对您有所帮助,请随意引用我们:
@article{huang2023openrl,
title={OpenRL: A Unified Reinforcement Learning Framework},
author={Huang, Shiyu and Chen, Wentse and Sun, Yiwen and Bie, Fuqing and Tu, Wei-Wei},
journal={arXiv preprint arXiv:2312.16189},
year={2023}
}
Star历史记录
许可
OpenRL采用Apache 2.0许可证。
致谢
OpenRL框架的开发借鉴了其他强化学习框架的优点:
- Stable-baselines3: https://github.com/DLR-RM/stable-baselines3
- pytorch-a2c-ppo-acktr-gail: https://github.com/ikostrikov/pytorch-a2c-ppo-acktr-gail
- MAPPO: https://github.com/marlbenchmark/on-policy
- Gymnasium: https://github.com/Farama-Foundation/Gymnasium
- DI-engine: https://github.com/opendilab/DI-engine/
- Tianshou: https://github.com/thu-ml/tianshou
- RL4LMs: https://github.com/allenai/RL4LMs