示例#

注意

Ray 2.40 默认使用 RLlib 的新 API 栈。Ray 团队已基本完成将算法、示例脚本和文档迁移到新代码库。

如果您仍在使用旧 API 栈，请参阅新 API 栈迁移指南了解如何迁移的详细信息。

本页包含 RLlib examples 文件夹中所有 Python 脚本的索引，展示了该库的不同用例和特性。

注意

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

注意

如果您发现任何新的 API 栈示例已损坏，或者您想向本页添加示例，请在 RLlib GitHub 仓库中创建议题。

文件夹结构#

本页包含 RLlib examples 文件夹中所有 Python 脚本的索引，展示了该库的不同用例和特性。

如何运行示例脚本#

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

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

使用 --help 命令行参数让每个脚本打印出其支持的命令行选项。

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

所有示例子文件夹#

动作#

  • 自回归动作:

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

  • 嵌套动作空间:

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

算法#

检查点#

连接器#

注意

RLlib 的 Connector API 已针对新的 API 栈进行了重写。连接器组件和流水线现在称为 ConnectorV2，以区别于 Connector 类，后者仅在旧 API 栈上继续工作。

  • 展平并进行独热编码观测:

    演示了如何对离散观测空间进行独热编码和/或展平复杂的观测（字典或元组），使 RLlib 能够将任意观测数据作为展平的 1D 向量进行处理。这对于具有复杂、离散或分层观测的环境非常有用。

  • 观测帧堆叠:

    实现帧堆叠，其中 N 个连续帧堆叠在一起，为智能体提供时间上下文。这种技术在具有连续状态变化的环境中很常见，例如 Atari 游戏中的视频帧。使用连接器进行帧堆叠效率更高，因为它避免了通过 Ray 远程调用发送大型观测张量。

  • 均值/标准差滤波:

    为观测添加均值和标准差归一化，通过减去均值并除以标准差进行转换。这种类型的滤波可以通过将观测缩放到归一化范围来提高在状态幅度高度变化的环境中的学习稳定性。

  • 先前动作、先前奖励连接器:

    通过先前的动作和奖励增强观测，使智能体具有对过去事件的短期记忆，这可以在部分可观测或序列依赖的任务中改进决策制定。

好奇心#

  • 基于计数的好奇心:

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

  • 基于欧氏距离的好奇心:

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

  • 基于内在好奇心模型 (ICM) 的好奇心:

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

课程学习#

  • 自定义环境渲染方法:

    演示了课程学习，其中环境难度随着智能体的进步而增加。这种方法可以实现循序渐进的学习，让智能体在进行更具挑战性的任务之前掌握更简单的任务，非常适用于具有分层或分阶段困难的环境。另请参见文档中的课程学习操作指南。

环境#

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

    展示了如果您的 RL 环境很慢并且您使用 num_envs_per_env_runner > 1，gym_env_vectorize_mode 配置设置如何显著加速您的 :py:class`~ray.rllib.env.env_runner.EnvRunner` actor。性能提升的原因是每个子环境都在自己的进程中运行。

  • 自定义环境渲染方法:

    演示了如何向（自定义）环境添加自定义 render() 方法，以可视化智能体交互。

  • 自定义 gymnasium 环境:

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

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

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

  • 环境渲染和记录:

    演示了 RLlib 中的环境渲染和记录设置，捕获视觉输出以供后续审查（例如，在 WandB 上），这对于跟踪训练中的智能体行为至关重要。

  • 具有 Protobuf 观测的环境:

    使用 Protobuf 进行观测，演示了在环境中处理序列化数据的一种高级方法。这种方法对于将复杂的外部数据源作为观测进行集成非常有用。

评估#

  • 自定义评估:

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

  • 与训练并行进行评估:

    与训练并行运行评估 episode，通过将评估分载到单独的进程来减少训练时间。当您需要频繁评估而不想中断学习时，此方法非常有用。

容错#

  • 崩溃和卡住的环境:

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

用于训练和采样的 GPU#

  • Float16 训练和推理:

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

  • 每个学习器的部分 GPU:

    演示了为单个学习器分配部分 GPU，从而可以在多模型设置中实现更精细的资源分配。在训练较小模型时节省资源非常有用，因为许多较小模型可以放在单个 GPU 上。

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

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

  • 在 EnvRunner 上使用 GPU:

    演示了如何通过 config.env_runners(num_gpus_per_env_runner=..) 设置来请求 GPU 的 EnvRunner 实例，无论是单智能体还是多智能体。

分层训练#

  • 分层强化学习训练:

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

模型或策略推理#

  • 训练后的策略推理:

    演示了使用训练过的策略执行推理，展示了如何加载训练过的模型并将其用于在模拟环境中做出决策。

  • 使用 ConnectorV2 进行训练后的策略推理:

    使用连接器（Connector）运行经过训练的、基于 LSTM 的策略推理，连接器可以预处理观测和动作，从而实现更模块化和灵活的推理设置。

学习器#

指标#

多智能体强化学习#

  • 自定义启发式策略:

    在 MultiAgentCartPole 环境中演示了混合策略设置，其中一个智能体遵循手写随机策略，而另一个智能体使用 PPO 进行训练。该示例突出了集成静态和动态策略的优势，适用于混合了固定策略和自适应智能体的环境。

  • 不同智能体的不同空间:

    在同一环境中为智能体配置不同的观测空间和动作空间，展示了 RLlib 支持在单个多智能体环境中具有不同空间需求的异构智能体。

  • 分组智能体，两步游戏:

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

  • 多智能体 CartPole:

    运行 CartPole 环境的多智能体版本，每个智能体独立学习平衡自己的杆子。该示例作为简单、独立任务中多智能体强化学习场景的基础测试。

  • 多智能体 Pendulum:

    将经典的 Pendulum 环境扩展到多智能体设置，其中多个智能体试图平衡各自的摆锤。该示例突出了 RLlib 支持具有重复动力学但不同智能体策略的环境。

  • PettingZoo 独立学习:

    将 RLlib 与 PettingZoo 集成，以便多个智能体进行独立学习。每个智能体在共享环境中独立优化其策略。

  • PettingZoo 参数共享:

    使用 PettingZoo 创建一个所有智能体共享一个策略的环境。

  • PettingZoo 共享价值函数:

    该示例也使用了 PettingZoo，探讨了智能体之间的共享价值函数。它演示了协作学习场景，其中智能体共同估计价值函数，而不是单独的策略。

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

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

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

    设置一个石头剪刀布游戏，训练两个智能体学习如何相互对抗的策略。对于评估简单对抗性设置中的性能很有用。

  • 自一对弈，基于联盟，使用 OpenSpiel:

    使用 OpenSpiel 演示基于联盟的自一对弈，其中智能体与自己不同的版本（冻结或训练中）对战，通过竞争性互动进行提升。

  • 使用 OpenSpiel 进行自一对弈:

    类似于基于联盟的自一对弈，但更简单。此脚本利用 OpenSpiel 进行双人游戏，允许智能体通过直接自一对弈进行提升，而无需构建复杂的结构化联盟。

离线强化学习#

Ray Serve 和 RLlib#

Ray Tune 和 RLlib#

  • 自定义实验:

    配置了使用 Ray Tune 的自定义实验，演示了自定义训练和评估阶段的高级选项。

  • 自定义日志记录器:

    展示了如何在 Ray Tune 中实现自定义日志记录器，允许用户在训练期间定义特定的日志记录行为和输出。

  • 自定义进度报告器:

    在 Ray Tune 中演示了自定义进度报告器，该报告器能够以自定义格式跟踪和显示特定的训练指标或状态更新。

RLModules#

调优示例#

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

例如，请参阅这个针对 PPO 的调优 Atari 示例，它在大约 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 多智能体强化学习的示例笔记本。

  • Neural MMO:

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

  • NeuroCuts:

    在类似于 bandit 的设置中，使用 RLlib / 多智能体构建数据包分类树的示例。

  • NeuroVectorizer:

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

  • Roboschool / SageMaker:

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

  • 序列社会困境游戏:

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

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

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

  • 星际争霸2:

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

  • 交通流:

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

博客文章#

注意

此处列出的博客文章均指 RLlib 的旧 API 栈。