注意

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

如果您仍在使用旧的 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 中的指南。我们区分两种级别的贡献：作为示例脚本（可能包含其他文件中的附加类）或作为rllib/algorithms中的完全集成 RLlib 算法。

  • 示例算法

    • 必须继承 Algorithm 并实现 training_step() 方法

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

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

  • 完全集成的算法具有以下附加要求

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

    • 应支持自定义 RLModules

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

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

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

新功能#

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

API 稳定性#

代码库中的 API 修饰符#

使用 @PublicAPI (新 API 栈)、@DeveloperAPI (新 API 栈) 或 @OldAPIStack (旧 API 栈) 注释的对象和方法具有以下 API 兼容性保证

ray.util.annotations.PublicAPI(*args, **kwargs)[source]

用于记录公共 API 的注释。

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

如果 stability="alpha"，则 API 可供能够容忍并预期破坏性更改的高级用户使用。

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

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

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

参数:

  • stability – 以下之一：{“stable”, “beta”, “alpha”}。

  • 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)[source]

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

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

示例

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

用于属于旧 API 栈的类/方法/函数的修饰符。

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

基准测试#

rl-experiments 仓库中提供了许多训练运行结果，tuned_examples 中还有一个按算法排序的可行超参数配置列表。基准测试结果对社区非常有价值，因此如果您恰好有感兴趣的结果，请考虑向任一仓库提交拉取请求。

调试 RLlib#

查找 Workers 中的内存泄漏#

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

class ray.rllib.callbacks.callbacks.MemoryTrackingCallbacks[source]#

MemoryTrackingCallbacks 可用于跟踪 rollout workers 的内存使用情况。

Memory Tracking Callbacks 使用 tracemalloc 和 psutil 跟踪 rollout 期间、训练或评估中的 Python 分配。

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

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

注意

此类仅用于调试，不应用于生产代码，因为 tracemalloc 会显著降低执行速度。

worker 中内存使用排名前 20 的对象作为自定义指标添加。然后可以使用 tensorboard 或其他指标集成（如 Weights & Biases）来监控这些指标。

../_images/MemoryTrackingCallbacks.png

故障排除#

如果您在使用许多 worker 时遇到类似 blas_thread_init: pthread_create: Resource temporarily unavailable 的错误，请尝试设置 OMP_NUM_THREADS=1。类似地，对于其他资源限制错误，使用 ulimit -a 检查配置的系统限制。

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