备注

Ray 2.10.0 引入了 RLlib 的“新 API 栈”的 alpha 阶段。Ray 团队计划将算法、示例脚本和文档迁移到新的代码库中，从而在 Ray 3.0 之前的后续小版本中逐步替换“旧 API 栈”（例如，ModelV2、Policy、RolloutWorker）。

然而，请注意，到目前为止，只有 PPO（单代理和多代理）和 SAC（仅单代理）支持“新 API 堆栈”，并且默认情况下继续使用旧 API 运行。您可以继续使用现有的自定义（旧堆栈）类。

请参阅此处 以获取有关如何使用新API堆栈的更多详细信息。

安装 RLlib 用于开发#

你可以使用 setup-dev.py 脚本 在本地开发 RLlib，而无需编译 Ray。这会在你的本地 git 克隆中的 ray/rllib 目录与 pip 安装的 ray 包中的相应目录之间设置符号链接。这样，你在本地 git 克隆的源文件中所做的每一个更改都会立即反映在你安装的 ray 中。

然而，如果你按照 这些说明 从源码安装了 ray，那么请不要使用这个，因为这些步骤应该已经创建了必要的符号链接。

在使用 setup-dev.py 脚本 时，请确保您的 git 分支与已安装的 Ray 二进制文件同步，这意味着您在 master 上是更新的，并且安装了最新的 wheel。

# Clone your fork onto your local machine, e.g.:
git clone https://github.com/[your username]/ray.git
cd ray
# Only enter 'Y' at the first question on linking RLlib.
# This leads to the most stable behavior and you won't have to re-install ray as often.
# If you anticipate making changes to e.g. Tune or Train quite often, consider also symlinking Ray Tune or Train here
# (say 'Y' when asked by the script about creating the Tune or Train symlinks).
python python/ray/setup-dev.py

为 RLlib 做贡献#

贡献修复和增强功能#

欢迎通过 Ray 的 GitHub 仓库 提交新的 RLlib 相关 PR。RLlib 团队非常感谢开源社区提供的任何外部帮助。如果你不确定如何构建你的错误修复或增强 PR，可以先创建一个小 PR，然后在对话部分向我们提问。这里有一个好的社区首次 PR 示例。

贡献算法#

这些是将新算法合并到 RLlib 的指南。我们将贡献分为两个级别：作为 示例脚本 <https://github.com/ray-project/ray/tree/master/rllib/examples>`__（可能在其他文件中有额外的类），或作为完全集成的 RLlib 算法在 `rllib/algorithms 中。

  • 示例算法：

    • 必须子类化 Algorithm 并实现 training_step() 方法

    • 必须在CI测试中包含主要示例脚本，其中演示了算法，这证明了算法正在学习某个任务。

    • 应提供现有算法中不存在的功能

  • 完全集成的算法有以下额外要求：

    • 必须提供其他算法无法添加的实质性新功能

    • 应支持自定义 RLModules

    • 应使用 RLlib 抽象并支持分布式执行

    • 应至少包含一个 调优的超参数示例，其测试是CI的一部分。

集成和贡献的算法都随 ray PyPI 包一起发布，并且作为 Ray 自动化测试的一部分进行测试。

新功能#

新功能的开发、讨论以及即将到来的优先事项都在 GitHub issues 页面 上进行跟踪（请注意，这可能不包括所有开发工作）。

API 稳定性#

新 API 栈 vs 旧 API 栈#

从 Ray 2.10 开始，您可以选择加入“新 API 堆栈”的 alpha 版本，这是对架构、设计原则、代码库和面向用户的 API 进行彻底的重新设计。

有关此努力的更多详情，请参见此处，以及如何通过您的配置激活新的API堆栈。

代码库中的API装饰器#

带有 ``@PublicAPI``（新 API 栈）、``@DeveloperAPI``（新 API 栈）或 ``@OldAPIStack``（旧 API 栈）注释的对象和方法具有以下 API 兼容性保证：

ray.util.annotations.PublicAPI(*args, **kwargs)[源代码]

用于记录公共API的注释。

公共API是Ray向最终用户公开的类和方法。

如果 stability="alpha"，API 可以被能够容忍并预期重大变更的高级用户使用。

如果 stability="beta"，API 仍然是公开的，早期用户可以使用，但可能会发生变化。

如果 stability="stable"，API 将在 Ray 的次要版本之间保持向后兼容（例如，Ray 1.4 -> 1.8）。

有关稳定性级别的完整定义，请参阅 Ray API 稳定性定义。

参数:

  • stability – {“稳定版”, “测试版”, “内测版”} 之一。

  • api_group – 可选。仅用于文档渲染目的。同一组的API将在API文档页面中分组显示。

示例

>>> from ray.util.annotations import PublicAPI
>>> @PublicAPI
... def func(x):
...     return x

>>> @PublicAPI(stability="beta")
... def func(y):
...     return y
ray.util.annotations.DeveloperAPI(*args, **kwargs)[源代码]

用于记录开发者API的注释。

开发者API是显式暴露给高级Ray用户和库开发者的低级方法。它们的接口可能会在Ray的次要版本之间发生变化。

示例

>>> from ray.util.annotations import DeveloperAPI
>>> @DeveloperAPI
... def func(x):
...     return x
ray.rllib.utils.annotations.OldAPIStack(obj)[源代码]

用于属于旧API堆栈的类/方法/函数的装饰器。

这些内容应在 Ray 3.0（RLlib GA）之后的某个时间点被弃用。建议用户开始探索（并针对）新的 API 栈进行编码。

基准测试#

在 rl-experiments 仓库 中可以找到许多训练运行的结果，并且在 tuned_examples 中还有一个按算法排序的有效超参数配置列表。基准测试结果对社区极其有价值，因此如果你碰巧有可能会引起兴趣的结果，请考虑向任一仓库提交拉取请求。

调试 RLlib#

在 Workers 中查找内存泄漏#

保持长时间运行的工作者的内存使用稳定可能具有挑战性。可以使用 MemoryTrackingCallbacks 类来跟踪工作者的内存使用情况。

class ray.rllib.algorithms.callbacks.MemoryTrackingCallbacks[源代码]#

MemoryTrackingCallbacks 可用于跟踪和监控回放工作者的内存使用情况。

内存跟踪回调使用 tracemalloc 和 psutil 在训练或评估期间的回放过程中跟踪 Python 分配。

跟踪数据被记录到一个剧集的 custom_metrics 中，因此可以在 tensorboard（或在 WandB 等中）查看。

将 MemoryTrackingCallbacks 回调添加到调优配置中，例如 { …’callbacks’: MemoryTrackingCallbacks …}

备注

此类用于调试，不应在生产代码中使用，因为 tracemalloc 会导致执行速度显著减慢。

在workers中内存使用量前20的对象被添加为自定义指标。这些指标可以使用tensorboard或其他类似Weights & Biases的指标集成进行监控：

../_images/MemoryTrackingCallbacks.png

故障排除#

如果在使用多个工作线程时遇到类似 blas_thread_init: pthread_create: 资源暂时不可用 的错误，尝试设置 OMP_NUM_THREADS=1。同样，使用 ulimit -a 检查系统配置的限制，以排查其他资源限制错误。

对于调试意外挂起或性能问题，您可以运行 ray stack 来转储当前节点上所有 Ray 工作者的堆栈跟踪，运行 ray timeline 来将任务的时间线可视化转储到文件中，以及运行 ray memory 来列出集群中的所有对象引用。