API 稳定性#

Ray 为其 Ray Core 和库中的公共 API 提供稳定性保证，这些 API 已相应地进行了装饰/标记。

API 可以标记为

  • PublicAPI，表示该 API 对最终用户公开。PublicAPI 有三个子级别（alpha, beta, stable），如下所述。

  • DeveloperAPI，表示该 API 明确对 Ray 的高级用户和库开发者公开

  • Deprecated，表示该 API 可能会在 Ray 的未来版本中移除。

Ray 的 PublicAPI 稳定性定义基于 Google 稳定性级别指南，并有一些微小差异

Alpha#

Alpha 组件会与已知的一组用户进行快速迭代，这些用户必须能容忍变化。用户数量应该是一个经过筛选、可管理的集合，以便能够与他们所有人单独沟通。

在 Alpha 组件中，破坏性变更必须是被允许且预期的，并且用户必须不能期望其稳定性。

Beta#

Beta 组件必须被视为完整且准备好声明为稳定版，但需要进行公共测试。

由于 Beta 组件的用户通常对变化的容忍度较低，Beta 组件应该尽可能稳定；但是，Beta 组件必须允许随时间推移而改变。这些变化应该是最小的，但可能包含对 Beta 组件的向后不兼容的更改。

向后不兼容的更改必须仅在合理的弃用期后进行，以便为用户提供迁移其代码的机会。

Stable#

Stable 组件在主要 API 版本生命周期内必须得到完全支持。由于用户期望标记为 Stable 的组件具有这种稳定性，因此在主要版本内不得对这些组件进行破坏性更改（异常情况除外）。

Docstrings#

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.util.annotations.Deprecated(*args, **kwargs)[source]#

用于标记已弃用 API 的注解。

已弃用 API 可能在 Ray 的未来版本中移除。

参数:

message – 帮助用户理解弃用原因并提供迁移路径的消息。

示例

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

>>> @Deprecated(message="g() is deprecated because the API is error "
...   "prone. Please call h() instead.")
... def g(y):
...     return y

未装饰的函数通常可以假定不属于 Ray 公共 API 的一部分。