ElegantRL “小雅”: 大规模并行深度强化学习

ElegantRL是一个轻量级且结构清晰的强化学习框架，旨在以最小的复杂度和最大的清晰度来表达核心RL算法。

“Elegant”这个名字反映了它的理念：依赖项占用空间小，但代码结构优雅。该框架避免了不必要的第三方库，同时保持模块化设计、数学上的透明性以及工程上的可读性。

ElegantRL专注于以纯粹的形式实现强化学习算法——清晰、可扩展且高效——而不牺牲性能或简洁性。

ElegantRL（官网）专为用户/开发者打造，具有以下优势：

• 云原生：通过微服务架构和容器化遵循云原生范式，并支持ElegantRL-Podracer和FinRL-Podracer。

• 可扩展：充分利用DRL算法的并行性，使其能够轻松扩展到云平台上的数百甚至数千个计算节点，例如拥有数千块GPU的DGX SuperPOD平台。

• 弹性：允许在云端弹性且自动地分配计算资源。

• 轻量级：核心代码少于1,000行（参见Elegantrl_Helloworld）。

• 高效：在许多测试案例中（例如单GPU、多GPU、GPU云），我们发现它比Ray RLlib更高效。

• 稳定：通过利用诸如哈密顿量项等多种方法，其稳定性远超Stable Baselines 3。

• 实用：已被用于多个项目（FinRL、FinRL-Meta等）。

• 大规模并行仿真被广泛应用于多个项目（如FinRL等）；因此，采样速度非常快，因为我们可以构建大量基于GPU的环境。

ElegantRL实现了以下无模型深度强化学习（DRL）算法：

• DDPG、TD3、SAC、PPO、REDQ适用于单智能体环境中的连续动作，
• DQN、Double DQN、D3QN适用于单智能体环境中的离散动作，
• QMIX、VDN、MADDPG、MAPPO、MATD3适用于多智能体环境。

有关DRL算法的更多详细信息，请参阅教育网页OpenAI Spinning Up。

ElegantRL支持以下模拟器：

• Isaac Gym用于大规模并行仿真，
• OpenAI Gym、MuJoCo、PyBullet、FinRL用于基准测试。

目录

• 新闻
• ElegantRL-Helloworld
• 文件结构
• 实验演示
• 要求
• 引用

教程

• [Towardsdatascience] 大规模并行仿真的新时代：使用ElegantRL的实用教程，2022年11月2日。
• [MLearning.ai] ElegantRL：比Stable-Baseline3更稳定的深度强化学习算法，2022年3月3日。
• [Towardsdatascience] ElegantRL-Podracer：面向云原生深度强化学习的可扩展且弹性的库，2021年12月11日。
• [Towardsdatascience] ElegantRL：掌握PPO算法，2021年5月3日。
• [MLearning.ai] ElegantRL演示：使用DDPG进行股票交易（第二部分），2021年4月19日。
• [MLearning.ai] ElegantRL演示：使用DDPG进行股票交易（第一部分），2021年3月28日。
• [Towardsdatascience] ElegantRL-Helloworld：一个轻量级且稳定的深度强化学习库，2021年3月4日。

ElegantRL-HelloWorld

对于初学者，我们维护了 ElegantRL-HelloWorld 作为教程。其目标是帮助用户通过实践掌握 ElegantRL 的使用方法。

• 按照以下顺序运行教程代码并学习强化学习算法：DQN -> DDPG -> PPO
• 在 GitHub 问题中提交对 Eleagant_HelloWorld 的建议 。

一句话总结：一个带有演员-评论家网络（net.py）的智能体（agent.py），通过与环境（env.py）交互进行训练（run.py）。

文件结构

• elegantrl # 主文件夹

  • agents # 强化学习算法集合
    • AgentXXX.py # 一类强化学习算法的实现
    • net.py # 网络架构集合
  • envs # 环境集合
    • XxxEnv.py # 用于强化学习训练的环境
  • train # 训练程序集合 - demo.py # 示例集合
    • config.py # 配置文件（超参数）
    • run.py # 训练循环
    • worker.py # 工作者类（探索环境，将数据保存到回放缓冲区）
    • learner.py # 学习者类（利用回放缓冲区中的数据更新网络）
    • evaluator.py # 评估者类（评估策略网络的累积奖励）
    • replay_buffer.py # 缓冲区类（保存用于训练的状态转移序列）

• elegantrl_helloworld # 教程版本

  • config.py # 配置文件（超参数）
  • agent.py # 强化学习算法
  • net.py # 网络架构
  • run.py # 训练循环
  • env.py # 用于强化学习训练的环境

• examples # 示例代码集合

• 可直接运行的 Google Colab 笔记本

  • quickstart_Pendulum_v1.ipynb
  • tutorial_BipedalWalker_v3.ipynb
  • tutorial_Creating_ChasingVecEnv.ipynb
  • tutorial_LunarLanderContinuous_v2.ipynb

• unit_tests # 测试集合

实验演示

效率高于 Ray RLlib

在 Ant (MuJoCo)、Humanoid (MuJoCo)、Ant (Isaac Gym) 和 Humanoid (Isaac Gym) 上的实验 # 从左至右

ElegantRL 完全支持 Isaac Gym，能够在单个 GPU 上运行大规模并行仿真（例如 4096 个子环境）。

稳定性优于 Stable-baseline 3

Hopper-v2 上的实验 # ElegantRL 的方差要小得多（8 次运行的平均值）。此外，ElegantRL 中的 PPO+H 在训练 500 万步时，速度比 Stable-Baseline3 快约 6 倍。

测试与贡献

我们的测试使用 Python 内置的 unittest 模块编写，便于访问。要运行特定的测试文件（例如 test_training_agents.py），请从根目录运行以下命令：

python -m unittest unit_tests/test_training_agents.py

要按顺序运行所有测试，可以使用以下命令：

python -m unittest discover

请注意，部分测试需要在系统上安装 Isaac Gym。如果未安装，与 Isaac Gym 相关的所有测试都将失败。

我们欢迎任何对代码库的贡献，但请务必 不要 提交或推送会破坏测试的代码。同时，请避免仅仅为了让您的更改通过测试而修改测试本身。目前，这些测试本身非常简单（实例化环境、让智能体训练一步等），因此如果测试失败，几乎可以肯定问题出在您的代码上，而不是测试本身。

我们正在积极重构代码，努力使整个代码库更加整洁和高效。如果您愿意帮助我们清理代码，强烈建议您观看 Uncle Bob 的清洁编码课程，如果您尚未观看的话。

系统要求

必需：
| Python 3.6+     |
| PyTorch 1.6+    |

非必需：
| Numpy 1.18+     | 用于 ReplayBuffer。Numpy 将随 PyTorch 一起安装。
| gym 0.17.0      | 用于环境。Gym 提供用于强化学习训练的示例环境。（gym==0.18 时 pyglet==1.6 存在 env.render() 错误，改为 gym==0.17.0, pyglet==1.5）
| pybullet 2.7+   | 用于环境。我们使用免费的 PyBullet 作为 MuJoCo（非免费）的替代品。
| box2d-py 2.3.8  | 用于 gym。请使用 pip install Box2D（而非 box2d-py）
| matplotlib 3.2  | 用于绘图。

pip3 install gym==0.17.0 pybullet Box2D matplotlib # 或者 pip install -r requirements.txt

要安装 StarCraftII 环境，
bash ./elegantrl/envs/installsc2.sh
pip install -r sc2_requirements.txt

引用：

引用本仓库时：

@misc{erl,
  author = {Liu, Xiao-Yang and Li, Zechu and Zhu, Ming and Wang, Zhaoran and Zheng, Jiahao},
  title = {{ElegantRL}: 大规模并行的云原生深度强化学习框架},
  year = {2021},
  publisher = {GitHub},
  journal = {GitHub 仓库},
  howpublished = {\url{https://github.com/AI4Finance-Foundation/ElegantRL}},
}

@article{liu2021elegantrl,
  title={ElegantRL-Podracer: 可扩展且弹性的云原生深度强化学习库},
  author={Liu, Xiao-Yang and Li, Zechu and Yang, Zhuoran and Zheng, Jiahao and Wang, Zhaoran and Walid, Anwar and Guo, Jian and Jordan, Michael I},
  journal={NeurIPS 深度强化学习研讨会},
  year={2021}
}

ElegantRL 快速上手指南

ElegantRL（小雅）是一个轻量级、结构清晰的深度强化学习框架，专为大规模并行仿真和云原生架构设计。它支持多种主流 DRL 算法（如 PPO, SAC, DDPG, DQN 等），在单卡或多卡环境下均表现出高效与稳定的特性。

1. 环境准备

系统要求

• 操作系统: Linux (推荐), macOS, Windows
• Python 版本: 3.6 或更高
• GPU: 可选（用于加速训练，支持 CUDA）

前置依赖

核心依赖仅需 Python 和 PyTorch。其他库可根据具体任务按需安装。

依赖项	版本要求	说明
Python	3.6+	必需
PyTorch	1.6+	必需
NumPy	1.18+	通常随 PyTorch 自动安装
gym	0.17.0	推荐（避免 0.18+ 的渲染 bug）
pybullet	2.7+	免费物理引擎，替代 MuJoCo
Box2D	-	需安装 Box2D 包
matplotlib	3.2+	用于绘图

注意：若使用 gym，建议指定版本 0.17.0 并搭配 pyglet==1.5 以避免渲染错误。

2. 安装步骤

基础安装

通过 pip 直接安装核心库：

pip3 install elegantrl

完整环境安装（推荐）

若需运行官方示例及基准测试，建议安装完整依赖：

# 安装核心依赖及常用环境库
pip3 install gym==0.17.0 pybullet Box2D matplotlib

# 或者直接使用项目提供的 requirements 文件
git clone https://github.com/AI4Finance-Foundation/ElegantRL.git
cd ElegantRL
pip install -r requirements.txt

特殊环境安装（可选）

如需使用 StarCraft II 环境：

bash ./elegantrl/envs/installsc2.sh
pip install -r sc2_requirements.txt

国内加速提示：若下载缓慢，可使用清华或阿里镜像源加速安装：

pip3 install elegantrl -i https://pypi.tuna.tsinghua.edu.cn/simple

3. 基本使用

ElegantRL 提供了极简的 helloworld 教程，帮助初学者快速理解“代理 (Agent) + 网络 (Net) + 环境 (Env) + 训练循环 (Run)"的核心架构。

方式一：运行官方 Hello World 示例

克隆仓库后，进入 helloworld 目录依次体验 DQN -> DDPG -> PPO 算法：

git clone https://github.com/AI4Finance-Foundation/ElegantRL.git
cd ElegantRL/elegantrl_helloworld

# 运行示例 (以 DQN 为例，具体文件名请参考目录内容)
python run.py

该目录包含四个核心文件，结构清晰：

• env.py: 定义强化学习环境
• net.py: 定义 Actor-Critic 网络结构
• agent.py: 封装 DRL 算法逻辑
• run.py: 执行训练循环

方式二：使用 Google Colab 快速体验

无需本地配置，直接在云端运行 Notebook 示例：

• Pendulum 控制: quickstart_Pendulum_v1.ipynb
• 双足行走机器人: tutorial_BipedalWalker_v3.ipynb
• 月球着陆器: tutorial_LunarLanderContinuous_v2.ipynb

代码逻辑简述

一个典型的训练流程可以概括为：

一个智能体 (agent.py) 包含演员 - 评论家网络 (net.py)，通过与环境 (env.py) 交互，由训练脚本 (run.py) 驱动完成学习。

运行单元测试

验证安装是否成功：

# 运行特定测试
python -m unittest unit_tests/test_training_agents.py

# 运行所有测试
python -m unittest discover