Reaver：模块化深度强化学习框架

项目状态： 已停止维护！
很遗憾，我目前无法继续开发或为该项目提供支持。

简介

Reaver 是一个模块化的深度强化学习框架，专注于各种基于《星际争霸II》的任务。它追随 DeepMind 的脚步，通过模拟人类玩家的操作界面和限制条件来推动该领域的前沿发展。这包括观察与人类玩家相似（尽管不完全相同）的视觉特征，并从与人类玩家类似的可选动作中进行选择。更多细节请参阅论文 《星际争霸II：强化学习的新挑战》。

尽管 Reaver 的开发以研究为导向，但其 API 的设计理念却与《星际争霸II》本身如出一辙——无论你是该领域的初学者还是资深研究人员，都能从中受益。对于业余程序员来说，Reaver 提供了所有必要的工具，只需修改智能体的一小部分（例如超参数）即可训练深度强化学习智能体。而对于经验丰富的研究人员，Reaver 则提供了一个简单但性能优化的模块化代码库：智能体、模型和环境彼此解耦，可以随意互换。

虽然 Reaver 的重点是《星际争霸II》，但它也完全支持其他流行的游戏环境，尤其是 Atari 和 MuJoCo。Reaver 的智能体算法已经过参考结果的验证，例如 PPO 智能体能够达到 近端策略优化算法 的水平。更多详情请参见下文（#but-wait-theres-more）。

安装

PIP 包

安装 Reaver 最简单的方式是通过 PIP 包管理器：

pip install reaver

你还可以通过附加标志安装额外的功能（例如 gym 支持）：

pip install reaver[gym,atari,mujoco]

手动安装

如果你计划修改 Reaver 的代码库，可以通过源码安装来保持其模块功能：

$ git clone https://github.com/inoryy/reaver-pysc2
$ pip install -e reaver-pysc2/

使用 -e 标志安装后，Python 将会在指定的文件夹中查找 reaver，而不是在 site-packages 目录中。

Windows

请参阅 wiki 页面，获取在 Windows 上设置 Reaver 的详细说明。

不过，如果可能的话，请考虑使用 Linux OS —— 这主要是出于性能和稳定性方面的考虑。如果你想让智能体在开启完整图形的情况下运行，可以在 Linux 上保存智能体的回放录像，然后在 Windows 上打开。下面列出的视频录制就是通过这种方式完成的。

需求

• PySC2 >= 3.0.0
• 星际争霸II >= 4.1.2（安装说明）
• gin-config >= 0.3.0
• TensorFlow >= 2.0.0
• TensorFlow Probability >= 0.9

可选扩展

如果你想将 Reaver 与其他支持的环境一起使用，还需要安装相应的包：

• gym >= 0.10.0
• atari-py >= 0.1.5
• mujoco-py >= 1.50.0
  • roboschool >= 1.0（替代方案）

快速入门

只需四行代码，您就可以在多个并行运行的《星际争霸II》环境中训练一个强化学习智能体！

import reaver as rvr

env = rvr.envs.SC2Env(map_name='MoveToBeacon')
agent = rvr.agents.A2C(env.obs_spec(), env.act_spec(), rvr.models.build_fully_conv, rvr.models.SC2MultiPolicy, n_envs=4)
agent.run(env)

此外，Reaver 提供高度可配置的命令行工具，因此这项任务可以简化为一行短命令！

python -m reaver.run --env MoveToBeacon --agent a2c --n_envs 4 2> stderr.log

使用上述命令，Reaver 将以一组预定义的超参数初始化训练过程，这些超参数是专门为给定环境和智能体优化的。过一段时间后，您将在终端屏幕上看到包含各种有用统计信息的日志。

| T    118 | Fr     51200 | Ep    212 | Up    100 | RMe    0.14 | RSd    0.49 | RMa    3.00 | RMi    0.00 | Pl    0.017 | Vl    0.008 | El 0.0225 | Gr    3.493 | Fps   433 |
| T    238 | Fr    102400 | Ep    424 | Up    200 | RMe    0.92 | RSd    0.97 | RMa    4.00 | RMi    0.00 | Pl   -0.196 | Vl    0.012 | El 0.0249 | Gr    1.791 | Fps   430 |
| T    359 | Fr    153600 | Ep    640 | Up    300 | RMe    1.80 | RSd    1.30 | RMa    6.00 | RMi    0.00 | Pl   -0.035 | Vl    0.041 | El 0.0253 | Gr    1.832 | Fps   427 |
...
| T   1578 | Fr    665600 | Ep   2772 | Up   1300 | RMe   24.26 | RSd    3.19 | RMa   29.00 | RMi    0.00 | Pl    0.050 | Vl    1.242 | El 0.0174 | Gr    4.814 | Fps   421 |
| T   1695 | Fr    716800 | Ep   2984 | Up   1400 | RMe   24.31 | RSd    2.55 | RMa   30.00 | RMi   16.00 | Pl    0.005 | Vl    0.202 | El 0.0178 | Gr   56.385 | Fps   422 |
| T   1812 | Fr    768000 | Ep   3200 | Up   1500 | RMe   24.97 | RSd    1.89 | RMa   31.00 | RMi   21.00 | Pl   -0.075 | Vl    1.385 | El 0.0176 | Gr   17.619 | Fps   423 |

Reaver 应该会迅速收敛到大约 25-26 的 RMe（每集平均奖励），这与 DeepMind 在该环境下的结果一致。具体的训练时间取决于您的硬件。以上日志是在一台配备 Intel i5-7300HQ CPU（4 核）和 GTX 1050 GPU 的笔记本电脑上生成的，训练耗时约 30 分钟。

当 Reaver 完成训练后，您可以通过在单行命令中添加 --test 和 --render 标志来查看其表现。

python -m reaver.run --env MoveToBeacon --agent a2c --test --render 2> stderr.log

Google Colab

我们提供了一个配套的 Google Colab 笔记本，您可以在网上试用 Reaver。

核心特性

性能

许多现代强化学习算法依赖于同时在多个环境中并行执行。由于 Python 具有 GIL，这一功能必须通过多进程实现。大多数开源实现采用基于消息的方法（例如 Python 的 multiprocessing.Pipe 或 MPI），其中各个进程通过 IPC 发送数据进行通信。对于像 DeepMind 和 OpenAI 这样的公司在大规模分布式系统上开展的工作来说，这是一种合理且可能是唯一可行的方式。

然而，对于一般的科研人员或爱好者来说，更常见的情况是只能访问单机环境，无论是笔记本电脑还是 HPC 集群上的节点。Reaver 专门针对这种情况进行了优化，通过无锁方式利用共享内存。这种方法显著提升了性能，使《星际争霸II》的采样率最高可提升 1.5 倍（在一般情况下甚至可提升至 100 倍），几乎完全消除了 GPU 输入/输出管道的瓶颈。

扩展性

Reaver 的三个核心模块——envs、models 和 agents——几乎完全相互独立。这确保了在一个模块中扩展功能时，能够无缝地集成到其他模块中。

可配置性

所有配置都通过 gin-config 处理，并且可以轻松地以 .gin 文件的形式共享。这包括所有的超参数、环境参数以及模型定义。

已实现的智能体

• 优势演员-评论家（A2C）
• 局部策略优化（PPO）

其他强化学习特性

• 广义优势估计（GAE）
• 奖励裁剪
• 梯度范数裁剪
• 优势归一化
• 基线（评论家）自举
• 独立的基线网络

还不止这些！

在尝试新想法时，快速获得反馈非常重要，而这一点在像《星际争霸II》这样复杂的环境中往往难以实现。由于 Reaver 采用了模块化架构，其智能体实现实际上并不局限于《星际争霸II》。您可以直接替换为许多流行的游戏环境（例如 openAI gym），并先验证实现是否有效：

python -m reaver.run --env CartPole-v0 --agent a2c 2> stderr.log

import reaver as rvr

env = rvr.envs.GymEnv('CartPole-v0')
agent = rvr.agents.A2C(env.obs_spec(), env.act_spec())
agent.run(env)

支持的环境

目前 Reaver 支持以下环境：

• 《星际争霸II》通过 PySC2（已在所有小游戏上测试）
• openAI Gym（已在 CartPole-v0 上测试）
• Atari（已在 PongNoFrameskip-v0 上测试）
• Mujoco（已在 InvertedPendulum-v2 和 HalfCheetah-v2 上测试）

结果

地图	Reaver (A2C)	DeepMind SC2LE	DeepMind ReDRL	人类专家
前往信标	26.3 (1.8) [21, 31]	26	27	28
收集矿物碎片	102.8 (10.8) [81, 135]	103	196	177
击败蟑螂	72.5 (43.5) [21, 283]	100	303	215
找到并击败泽格幼虫	22.1 (3.6) [12, 40]	45	62	61
击败泽格幼虫和狂暴者	56.8 (20.8) [21, 154]	62	736	727
收集矿物和气体	2267.5 (488.8) [0, 3320]	3,978	5,055	7,566
建造陆战队员	--	3	123	133

• 人类专家的结果由DeepMind从一位大师级玩家那里收集而来。
• DeepMind ReDRL指的是当前最先进的结果，详见论文《关系型深度强化学习》（https://arxiv.org/abs/1806.01830）。
• DeepMind SC2LE是发表在论文《星际争霸II：强化学习的新挑战》（https://arxiv.org/abs/1708.04782）中的结果。
• Reaver (A2C)是在现有硬件上尽可能复现SC2LE架构，训练reaver.agents.A2C智能体所得到的结果。 结果通过让训练好的智能体以--test模式运行100个episode，并计算每个episode的总奖励来获得。列出的是平均值、标准差（括号内）以及最小值和最大值（方括号内）。

训练详情

地图	样本数	episode数	大约时间（小时）
前往信标	563,200	2,304	0.5
收集矿物碎片	74,752,000	311,426	50
击败蟑螂	172,800,000	1,609,211	150
找到并击败泽格幼虫	29,760,000	89,654	20
击败泽格幼虫和狂暴者	10,496,000	273,463	15
收集矿物和气体	16,864,000	20,544	10
建造陆战队员	-	-	-

• 样本数指在一个环境中observe -> step -> reward链条的总数。
• episode数指PySC2返回的StepType.LAST标志的总数。
• 大约时间是在配备Intel i5-7300HQ四核CPU和GTX 1050显卡的笔记本电脑上的大致训练时间。

需要注意的是，我没有花太多时间进行超参数调优，而是主要关注验证智能体是否能够学习，而不是最大化样本效率。例如，在MoveToBeacon任务上，最初的尝试大约需要400万个样本，但经过一些调整后，我最终使用PPO智能体将所需样本数减少到10.2万个左右（约40倍的减少）。

带标准差填充的平均episode奖励。点击可放大。

视频记录

智能体在所有六个小游戏上表现的视频录制已在线发布：https://youtu.be/gEyBzcPU5-w。视频左侧显示的是智能体在随机初始化权重且未经过训练时的表现，而右侧则是经过训练达到目标分数后的表现。

可重复性

近年来，研究的可重复性问题已成为科学界广泛讨论的话题，总体而言，强化学习也不例外，如这篇论文所述。作为一项科学项目，Reaver的目标之一就是促进可重复性研究。为此，Reaver附带了多种简化流程的工具：

• 所有实验都会保存到独立的文件夹中，默认启用自动模型检查点功能。
• 所有配置都通过Python库gin-config管理，并保存到实验结果目录中。
• 在训练过程中，各种统计指标会被复制到实验结果目录中。
• 结果目录的结构便于分享包含完整信息的单个实验。

预训练权重与摘要日志

为推动可重复性研究，Reaver附带了所有六个小游戏的预训练权重和完整的TensorBoard摘要日志。只需从release页面下载实验存档，并解压到results/目录即可。

你可以通过在reaver.run命令中添加--experiment标志来使用预训练权重：

python reaver.run --map <map_name> --experiment <map_name>_reaver --test 2> stderr.log

TensorBoard日志可以通过运行tensorboard --logdir=results/summaries查看。你也可以通过Aughie Boards直接在线查看这些日志：https://boards.aughie.org/board/HWi4xmuvuOSuw09QBfyDD-oNF1U。

为什么叫“Reaver”？

Reaver是星际争霸游戏宇宙中一种非常特别且颇具萌感的星灵单位。在《星际争霸：母巢之战》版本中，Reaver因行动迟缓、笨拙，且由于游戏内AI存在诸多漏洞，单独使用时往往几乎毫无用处而闻名。然而，对于那些愿意投入时间掌握该单位的资深玩家来说，Reaver却成为了游戏中最强大的资产之一，常常在锦标赛冠军比赛中发挥关键作用。

致谢

Reaver的前身名为pysc2-rl-agent，它是塔尔图大学一篇学士论文的实践部分，由Ilya Kuzovkin和Tambet Matiisen指导完成。你仍然可以在v1.0分支中找到它。

支持

如果你遇到与代码库相关的问题，请在GitHub上提交一个issue，并尽可能详细地描述问题。如果你有更一般性的疑问或只是想寻求建议，欢迎随时给我发送电子邮件。

我也是活跃友好的SC2AI在线社区的一员，我们主要使用Discord进行交流。欢迎来自不同背景和具有不同专业水平的人加入！

引用

如果您在研究中使用了 Reaver，请考虑使用以下 BibTeX 格式对其进行引用：

@misc{reaver,
  author = {Ring, Roman},
  title = {Reaver：模块化的深度强化学习框架},
  year = {2018},
  publisher = {GitHub},
  journal = {GitHub 代码库},
  howpublished = {\url{https://github.com/inoryy/reaver}},
}

Reaver 快速上手指南

Reaver 是一个模块化的深度强化学习框架，专注于《星际争霸 II》（StarCraft II）任务，同时也支持 Atari 和 MuJoCo 等环境。它采用无锁共享内存机制，在单机环境下能显著提升采样速度。

注意：该项目目前不再维护（No longer maintained），但代码仍可用于学习和研究参考。

1. 环境准备

在开始之前，请确保您的系统满足以下要求：

系统建议

• 操作系统：推荐使用 Linux 以获得最佳性能和稳定性。
  • Windows 用户：虽可运行，但建议参考官方 Wiki 配置。若需查看带画面的回放，可在 Linux 训练保存回放后，移至 Windows 播放。
• 硬件：多核 CPU 和 NVIDIA GPU（用于加速训练）。

前置依赖

您需要预先安装以下软件：

• StarCraft II: 版本 >= 4.1.2
  • 下载及配置说明：Blizzard s2client-proto
• Python 环境: 建议 Python 3.6+
• 核心库:
  • PySC2 >= 3.0.0
  • TensorFlow >= 2.0.0
  • TensorFlow Probability >= 0.9
  • gin-config >= 0.3.0

(可选) 若需运行其他环境（如 Gym/Atari/MuJoCo），还需安装对应库：gym, atari-py, mujoco-py 等。

2. 安装步骤

方式一：通过 PIP 安装（推荐）

这是最简单的安装方式。国内用户建议使用清华或阿里镜像源加速安装。

# 基础安装
pip install reaver -i https://pypi.tuna.tsinghua.edu.cn/simple

# 若需要支持 Gym, Atari 或 MuJoCo 环境，可使用 extras 安装
pip install "reaver[gym,atari,mujoco]" -i https://pypi.tuna.tsinghua.edu.cn/simple

方式二：源码安装（适合开发者）

如果您计划修改 Reaver 源代码，请使用此方式：

git clone https://github.com/inoryy/reaver-pysc2
cd reaver-pysc2
pip install -e . -i https://pypi.tuna.tsinghua.edu.cn/simple

注：-e 参数将使 Python 直接读取当前文件夹的代码，便于开发调试。

3. 基本使用

Reaver 提供了极高的易用性，既可以通过命令行一键启动，也可以通过 Python 代码灵活控制。

方法 A：命令行一键训练（最简单）

以下命令将启动一个 A2C 代理，在 MoveToBeacon 地图上利用 4 个并行环境进行训练：

python -m reaver.run --env MoveToBeacon --agent a2c --n_envs 4 2> stderr.log

运行后，终端将实时输出训练统计信息（如奖励均值 RMe、帧率 Fps 等）。当 RMe 收敛至 25-26 左右时，表示训练达到预期效果（与 DeepMind 基准相当）。

测试与可视化： 训练完成后，添加 --test 和 --render 参数即可观察代理表现：

python -m reaver.run --env MoveToBeacon --agent a2c --test --render 2> stderr.log

方法 B：Python 代码调用

如果您需要在脚本中集成或自定义逻辑，仅需四行代码即可启动训练：

import reaver as rvr

# 初始化环境
env = rvr.envs.SC2Env(map_name='MoveToBeacon')

# 初始化代理 (A2C 算法)
agent = rvr.agents.A2C(env.obs_spec(), env.act_spec(), rvr.models.build_fully_conv, rvr.models.SC2MultiPolicy, n_envs=4)

# 开始训练
agent.run(env)

其他支持的环境

Reaver 的架构是解耦的，您可以轻松切换至其他环境进行快速验证（无需启动庞大的星际争霸）：

# 示例：在 CartPole 环境中运行
python -m reaver.run --env CartPole-v0 --agent a2c 2> stderr.log

目前支持的环境包括：

• StarCraft II (via PySC2)
• OpenAI Gym
• Atari
• MuJoCo