使用标签控制调度#

在 Ray 2.49.0 及更高版本中，您可以使用标签来控制 KubeRay 的调度。标签是一项 Beta 功能。

本页提供了标签的概念性概述和使用说明。标签是键值对，为用户提供易于理解的配置，用于控制 Ray 如何将任务、Actor 和 Placement Group Bundle 调度到特定节点。

注意

Ray 标签的语法和格式限制与 Kubernetes 标签相同，但在概念上有所区别。请参阅 Kubernetes 关于标签和选择器的文档。

标签如何工作？#

以下是您如何使用标签控制调度的总体概述

  • Ray 设置了描述底层计算的默认标签。请参阅 默认节点标签。

  • 您将自定义标签定义为键值对。请参阅 定义自定义标签。

  • 您在 Ray 代码中指定标签选择器来定义标签要求。您可以在任务、Actor 或 Placement Group Bundle 级别指定这些要求。请参阅 指定标签选择器。

  • Ray 根据指定的标签选择器调度任务、Actor 或 Placement Group Bundle。

  • 在 Ray 2.50.0 及更高版本中，如果您使用的是启用了 V2 自动扩缩器的动态集群，则集群会扩容以添加来自指定工作节点组的新节点，以满足标签要求。

默认节点标签#

注意

Ray 保留 ray.io 命名空间下的所有标签。

在集群初始化期间或自动扩缩事件将节点添加到集群时，Ray 会为每个节点分配以下默认标签

标签

描述

ray.io/node-id

为节点生成的唯一 ID。

ray.io/accelerator-type

节点的加速器类型，例如 L4。纯 CPU 机器没有此标签。有关值的映射，请参阅 加速器类型。

注意

您可以使用 ray start 参数覆盖默认值。

以下是默认标签的示例

"ray.io/accelerator-type": "L4" # Default label indicating the machine has Nvidia L4 GPU

定义自定义标签#

在运行 ray start 时，您可以使用 --labels 或 --labels-file 参数为节点添加自定义标签。

# Examples 1: Start a head node with cpu-family and test-label labels
ray start --head --labels="cpu-family=amd,test-label=test-value"

# Example 2: Start a head node with labels from a label file
ray start --head --labels-files='./test-labels-file'

# The file content can be the following (should be a valid YAML file):
# "test-label": "test-value"
# "test-label-2": "test-value-2"

注意

您无法使用 ray.init() 设置标签。本地 Ray 集群不支持标签。

指定标签选择器#

在定义 Ray 任务、Actor 或 Placement Group Bundle 时，您可以将标签选择器逻辑添加到 Ray 代码中。标签选择器定义了将您的 Ray 代码与 Ray 集群中的节点进行匹配的标签要求。

标签选择器指定以下内容

  • 标签的键。

  • 用于匹配的操作符逻辑。

  • 要匹配的值或值。

下表显示了标签选择器操作符逻辑的基本语法

操作符

描述

示例语法

等于

标签精确匹配一个值。

{“key”: “value”}

不等于

标签匹配除一个值以外的所有值。

{“key”: “!value”}

在

标签匹配提供的值中的一个。

{“key”: “in(val1,val2)”}

不在

标签不匹配提供的任何值。

{“key”: “!in(val1,val2)”}

您可以将一个或多个标签选择器指定为字典。指定多个标签选择器时，候选节点必须满足所有要求。以下示例配置使用自定义标签要求 m5.16xlarge EC2 实例，并使用默认标签要求节点 ID 为 123

label_selector={"instance_type": "m5.16xlarge", "ray.io/node-id": "123"}

为任务和 Actor 指定标签要求#

使用以下语法将标签选择器添加到任务和 Actor

# An example for specifing label_selector in task's @ray.remote annotation
@ray.remote(label_selector={"label_name":"label_value"})
def f():
    pass

# An example of specifying label_selector in actor's @ray.remote annotation
@ray.remote(label_selector={"ray.io/accelerator-type": "H100"})
class Actor:
    pass

# An example of specifying label_selector in task's options
@ray.remote
def test_task_label_in_options():
    pass

test_task_label_in_options.options(label_selector={"test-lable-key": "test-label-value"}).remote()

# An example of specifying label_selector in actor's options
@ray.remote
class Actor:
    pass

actor_1 = Actor.options(
    label_selector={"ray.io/accelerator-type": "H100"},
).remote()

为 Placement Group Bundle 指定标签要求#

使用 bundle_label_selector 选项将标签选择器添加到 Placement Group Bundle。请参阅以下示例

# All bundles require the same labels:
ray.util.placement_group(
    bundles=[{"GPU": 1}, {"GPU": 1}],
    bundle_label_selector=[{"ray.io/accelerator-type": "H100"}] * 2,
)

# Bundles require different labels:
ray.util.placement_group(
    bundles=[{"CPU": 1}] + [{"GPU": 1}] * 2,
    bundle_label_selector=[{"ray.io/market-type": "spot"}] + [{"ray.io/accelerator-type": "H100"}] * 2
)

将标签与自动扩缩器结合使用#

自动扩缩器 V2 支持基于标签的调度。要使自动扩缩器能够扩容节点以满足标签要求，您需要为不同的标签要求组合创建多个工作节点组，并在 Ray 集群配置的 rayStartParams 字段中指定所有相应的标签。例如

    rayStartParams: {
      labels: "region=me-central1,ray.io/accelerator-type=H100"
    }

使用标签监控节点#

Ray Dashboard 会自动显示以下信息

在任务中，您可以使用 `ray.get_runtime_context().get_node_labels()` 以编程方式从 RuntimeContextAPI 获取节点标签。这将返回一个 Python 字典。请参阅以下示例

@ray.remote
def test_task_label():
   node_labels = ray.get_runtime_context().get_node_labels()
   print(f"[test_task_label] node labels: {node_labels}")

"""
Example output:
(test_task_label pid=68487) [test_task_label] node labels: {'test-label-1': 'test-value-1', 'test-label-key': 'test-label-value', 'test-label-2': 'test-value-2'}
"""

您还可以使用 state API 和 state CLI 访问有关节点标签和标签选择器信息的信息。