示例#

此页面包含RLlib的examples文件夹中所有Python脚本的索引，演示了该库的不同用例和功能。

注意

RLlib目前正处于从旧API栈到新API栈的过渡状态。Ray团队已将大多数示例脚本转换为新栈，并将仍在使用旧栈的脚本标记为在顶部带有此注释行：# @OldAPIStack。将所有示例脚本迁移到新栈的工作仍在进行中。

注意

如果您发现任何新API栈的示例出现问题，或者您想在此页面上添加一个示例，请在RLlib GitHub仓库中创建一个issue。

文件夹结构#

下面的examples文件夹包含几个子目录，下面将详细介绍。

如何运行示例脚本#

大多数示例脚本都是自可执行的，这意味着您可以cd到相应目录，并直接使用Python运行脚本。

$ cd ray/rllib/examples/multi_agent
$ python multi_agent_pendulum.py --num-agents=2

使用--help命令行参数，每个脚本都会打印出它支持的命令行选项。

大多数脚本共享一组通用的、通常适用的命令行参数，例如--num-env-runners，用于扩展EnvRunner actor的数量；--no-tune，用于关闭与Ray Tune的运行；--wandb-key，用于记录到WandB；或--verbose，用于控制日志的详细程度。

所有示例子文件夹#

动作#

  • 自回归动作:

    配置一个以自回归方式生成动作的RL模块，其中动作的第二个分量取决于同一动作先前采样的第一个分量。

  • 自定义动作分布类:

    演示如何编写一个自定义动作分布类，该类在分类分布的基础上增加了一个温度参数，以及如何在您的RLModule实现中配置此类。进一步解释了在需要更精细粒度的情况下，如何为您的RLModule的不同前向方法定义不同的类。

  • 嵌套动作空间:

    使用自定义的单代理或多代理配置设置具有嵌套动作空间的环境。此示例演示了RLlib如何处理复杂的动作结构，例如多维或分层动作空间。

算法#

检查点#

  • 按自定义标准检查点:

    展示了如何基于自定义标准创建检查点，使用户能够控制模型快照在训练期间的保存时间。

  • 从检查点继续训练:

    演示了从保存的检查点恢复训练，这对于延长训练会话或从中断中恢复非常有用。

  • 从检查点恢复N个代理中的1个:

    从多代理检查点恢复一个特定的代理，允许选择性加载，适用于只需要某些代理恢复训练的环境。

连接器#

注意

RLlib的Connector API已在新API栈中从头开始重写。Connector-pieces和-pipelines现在被称为ConnectorV2，以区别于Connector类，后者仅在旧API栈上继续工作。

  • 展平并one-hot化观测:

    演示了如何对离散观测空间进行one-hot编码和/或展平复杂的观测，如Dict或Tuple，使RLlib能够将任意观测数据处理为展平的1D向量。适用于具有复杂、离散或分层观测的环境。

  • 观测帧堆叠:

    实现帧堆叠，其中N个连续帧堆叠在一起，为代理提供时间上下文。这种技术在状态连续变化的环境中很常见，例如雅达利游戏中的视频帧。使用连接器进行帧堆叠效率更高，因为它避免了将大型观测张量通过ray远程调用传输。

  • 均值/标准差过滤:

    为观测添加均值和标准差归一化，通过均值移位并除以标准差。这种类型的过滤可以通过将观测值缩放到归一化范围来提高具有高度可变状态幅度的环境的学习稳定性。

  • 多代理观测预处理器，增强非马尔可夫观测到马尔可夫观测:

    多代理预处理器增强了多代理环境中每个代理的观测，这些观测本身是非马尔可夫的、部分的观测，并通过添加来自其他代理的信息将其转换为马尔可夫观测。策略只能通过此附加信息才能最优地训练。

  • 前一个动作、前一个奖励连接器:

    用前一个动作和奖励增强观测，为代理提供短期内的历史事件记忆，这可以改善在部分可观察或顺序依赖任务中的决策。

  • 单代理观测预处理器:

    一个连接器将CartPole-v1环境的观测值从马尔可夫的4元组（x位置、角度位置、x速度、角度速度）更改为非马尔可夫的、更简单的2元组（仅x位置和角度位置）。由此产生的问题只能通过具有记忆/状态的模型来解决，例如LSTM。

好奇心#

  • 基于计数的探索:

    实现基于计数的内在动机，以鼓励探索访问较少的状态。在稀疏奖励环境中，探索好奇心是有益的，因为代理可能难以找到奖励路径。然而，基于计数的方法仅适用于观测空间较小的环境。

  • 基于欧几里得距离的好奇心:

    使用状态与初始状态之间的欧几里得距离来衡量新颖性，通过奖励代理到达环境的“遥远”区域来鼓励探索。适用于稀疏奖励任务，其中多样化探索是成功的关键。

  • 基于内在好奇心模型（ICM）的好奇心:

    添加了一个内在好奇心模型（ICM），该模型学习预测下一个状态以及两个状态之间的动作，以衡量新颖性。ICM的损失越高，“新颖性”就越高，内在奖励也越高。适用于观测空间大且奖励信号稀疏的复杂环境。

课程学习#

  • 自定义环境渲染方法:

    演示课程学习，其中环境难度随着代理的改进而增加。这种方法实现了渐进式学习，允许代理在掌握更简单的任务后再学习更具挑战性的任务，适用于具有分层或分阶段难度的环境。另请参阅文档中的课程学习指南。

  • 雅达利Pong的课程学习:

    演示使用frameskip为雅达利Pong进行课程学习，以增加任务的难度。这种方法实现了渐进式学习，允许代理在掌握更慢的反应（较低的frameskip）后再学习更快的反应（较高的frameskip）。另请参阅文档中的课程学习指南。

调试#

  • 确定性采样和训练:

    演示通过算法配置为实验设置种子（seed）的可能性。RLlib将种子传递给所有拥有RL环境和RLModule副本的所有组件，从而确保这些组件的行为是确定性的。使用种子后，训练结果应该是可重复的。请注意，某些算法，如APPO，依赖于异步采样与Ray网络通信相结合，无论是否设置了种子，其行为总是具有随机性。

环境#

  • 异步gym向量化，并行化子环境:

    展示了如果您的RL环境速度较慢且您使用了num_envs_per_env_runner > 1，gym_env_vectorize_mode配置设置如何显著加速您的EnvRunner actor。性能提升的原因是每个子环境都在自己的进程中运行。

  • 自定义环境渲染方法:

    演示了如何为（自定义）环境添加自定义的render()方法，允许可视化代理交互。

  • 自定义 gymnasium 环境:

    从头开始实现自定义的gymnasium环境，展示了如何定义观测和动作空间、任意奖励函数以及step和reset逻辑。

  • 环境通过tcp客户端连接到RLlib:

    一个外部环境，在RLlib之外运行并充当客户端，连接到RLlib作为服务器。外部环境使用ONNX模型执行自己的动作推理，将收集到的数据发送回RLlib进行训练，并偶尔从RLlib接收模型更新。

  • 环境渲染和录制:

    说明了RLlib中的环境渲染和录制设置，捕获视觉输出来供以后查看（例如在WandB上），这对于跟踪训练中的代理行为至关重要。

  • 具有protobuf观测的环境:

    使用Protobuf进行观测，演示了处理环境中的序列化数据的先进方法。此方法对于集成复杂的外部数据源作为观测值非常有用。

评估#

  • 自定义评估:

    配置代理性能的自定义评估指标，允许用户定义超出标准RLlib评估指标的特定成功标准。

  • 与训练并行评估:

    在训练的同时运行评估回合，通过将评估卸载到单独的进程来减少训练时间。当您需要频繁评估而不中断学习时，此方法很有益。

容错#

  • 崩溃和停止的环境:

    模拟一个随机崩溃或停止的环境，允许用户测试RLlib的容错机制。此脚本对于评估RLlib如何处理中断和从训练中的意外故障中恢复非常有用。

用于训练和采样的GPU#

  • Float16训练和推理:

    配置用于float16训练和推理的设置，通过减少内存使用量和加速计算来优化性能。这对于兼容GPU上的大规模模型尤其有用。

  • 每个Learner的Fractional GPU:

    演示为单个Learner分配Fractional GPU，从而在多模型设置中实现更精细的资源分配。当训练许多可以安装在单个GPU上的小型模型时，有助于节省资源。

  • 混合精度训练和float16推理:

    在训练时使用混合精度（float32和float16），在推理时切换到float16精度，平衡了训练期间的稳定性和评估期间的性能改进。

  • 在EnvRunners上使用GPU:

    演示了EnvRunner实例（单代理或多代理）如何通过config.env_runners(num_gpus_per_env_runner=..)设置请求GPU。

分层训练#

  • 分层RL训练:

    展示了一个受自动子目标发现和子策略专业化启发的层次化RL设置。一个高级策略在时间限制内选择子目标并将三个专业化的低级策略之一分配给它们，以实现这些子目标，从而鼓励专业化和高效的任务解决。代理需要导航一个复杂网格世界的环境。该示例通过在具有挑战性的、面向目标任务中展示显著提高的学习性能，突出了分层学习相对于扁平化方法的优势。

模型或策略的推理#

学习器#

指标#

多代理RL#

  • 自定义启发式策略:

    在MultiAgentCartPole环境中演示了混合策略设置，其中一个代理遵循手工编写的随机策略，而另一个代理使用PPO进行训练。此示例突出了集成静态和动态策略，适用于具有固定策略和自适应代理混合的环境。

  • 不同代理的不同观测和动作空间:

    在同一个环境中配置具有不同观测和动作空间的代理，展示了RLlib在单个多代理环境中对具有不同空间需求的异构代理的支持。另一个示例也利用了连接器，并且涵盖了相同的主题（代理具有不同的空间），可以在这里找到。

  • 分组代理，两步游戏:

    在QMIX论文的两步游戏环境中实现了多代理、分组设置。N个代理总共组成M个团队，其中N>=M，每个团队中的代理共享奖励和策略。此示例演示了RLlib管理分组代理之间集体目标和交互的能力。

  • 多代理CartPole:

    运行CartPole环境的多代理版本，每个代理独立学习平衡其杆。此示例作为简单、独立任务中多代理强化学习场景的基础测试。

  • 多代理Pendulum:

    将经典的Pendulum环境扩展为多代理设置，其中多个代理尝试平衡各自的Pendulum。此示例突出了RLlib对具有复制动态但不同代理策略的环境的支持。

  • PettingZoo独立学习:

    将RLlib与PettingZoo集成，以促进多个代理之间的独立学习。每个代理在共享环境中独立优化其策略。

  • PettingZoo参数共享:

    使用PettingZoo用于所有代理共享单个策略的环境。

  • PettingZoo共享值函数:

    同样使用PettingZoo，此示例探索了代理之间的共享值函数。它演示了协作学习场景，其中代理集体估计一个值函数，而不是单独的策略。

  • 石头剪刀布启发式 vs 学习:

    模拟一个石头剪刀布游戏，其中一个代理由启发式驱动，另一个代理由学习驱动。它提供了在对抗性游戏中结合固定和自适应策略时的性能洞察。

  • 石头剪刀布学习 vs 学习:

    设置一个石头剪刀布游戏，您可以在其中训练两个代理学习如何相互对抗的策略。这对于评估简单对抗性设置中的性能非常有用。

  • 自我对抗，基于联盟，使用OpenSpiel:

    使用OpenSpiel演示基于联盟的自我对抗，代理与各种版本的自己（冻结的或正在训练的）进行对抗，通过竞争性互动来提高。

  • 使用Footsies和PPO算法的自对抗:

    使用Footsies环境（两人零和游戏）实现自对抗。此示例突出了RLlib连接到运行游戏引擎的外部二进制文件的能力，以及设置多代理自对抗训练场景。

  • 使用OpenSpiel的自对抗:

    与基于联盟的自对抗类似，但更简单。此脚本利用OpenSpiel进行两人游戏，允许代理在不构建复杂、结构化联盟的情况下通过直接的自我对抗来提高。

离线RL#

Ray Serve和RLlib#

  • 使用Ray Serve和RLlib:

    将RLlib与Ray Serve集成，展示如何将训练好的RLModule实例部署为RESTful服务。此设置非常适合在生产环境中以基于API的交互方式部署模型。

Ray Tune和RLlib#

RLModules#

调优示例#

包含tuned_examples文件夹中的Python配置文件，您可以像这里描述的所有其他示例脚本一样运行它们，以运行不同算法和环境类型的调优学习实验。

例如，请看这个PPO的调优雅达利示例，它在大约5分钟内学会了解决Pong环境。您可以在一台拥有4个GPU和96个CPU的g5.24xlarge或g6.24xlarge机器上按如下方式运行它。

$ cd ray/rllib/tuned_examples/ppo
$ python atari_ppo.py --env=ale_py:ALE/Pong-v5 --num-learners=4 --num-env-runners=95

请注意，RLlib的每日或每周发布测试也使用此文件夹中的一些文件。

社区示例#

注意

此处列出的社区示例均指RLlib的旧API栈。

  • Arena AI:

    一个用于单/多代理智能的通用评估平台和构建工具包，具有RLlib生成的基线。

  • CARLA:

    使用RLlib和CARLA模拟器训练自动驾驶汽车的示例。

  • 多代理强化学习中对抗性通信的出现:

    使用图神经网络和RLlib训练多个合作和对抗性代理来解决“覆盖区域”问题，从而学会如何最好地通信或（在对抗性情况下）如何干扰通信（代码）。

  • Flatland:

    一个密集的交通模拟环境，包含 RLlib 生成的基线。

  • GFootball:

    使用 RLlib 设置 GFootball 多智能体版本的示例。

  • mobile-env:

    一个开放、极简的 Gymnasium 环境，用于无线移动网络中的自主协调。包含一个使用 Ray RLlib 进行 mobile-env 多智能体 RL 的示例笔记本。

  • Neural MMO:

    一个受大型多人在线 (MMO) 角色扮演游戏启发的**多智能体 AI 研究环境**——具有数千个智能体、多样化的技能系统、本地和全球经济、复杂的涌现社会结构以及临时性的高风险单人和团队冲突的自包含世界。

  • NeuroCuts:

    在类似 Bandit 的环境中，使用 RLlib / 多智能体构建数据包分类树的示例。

  • NeuroVectorizer:

    使用 RLlib 学习 C 和 C++ 代码中循环的最优 LLVM 向量化编译器指令的示例。

  • Roboschool / SageMaker:

    在 SageMaker 中使用 RLlib 训练机器人控制策略的示例。

  • Sequential Social Dilemma Games:

    使用多智能体 API 对几个**社会困境游戏**进行建模的示例。

  • 用于 Ray 和 RLlib 单智能体 RL 的简单自定义环境:

    使用 Ray 2.0 和 Tune 创建自定义环境并训练单智能体 RL。

  • StarCraft2:

    使用 RLlib / 多智能体在 StarCraft2 地图中进行训练的示例。

  • Traffic Flow:

    使用 RLlib / 多智能体优化混合自主交通模拟的示例。

博客文章#

注意

此处列出的博客文章均引用了 RLlib 旧的 API 堆栈。