Python——Ray-option函数讲解

整体说明

在 Ray 框架中，.option() 是用于配置 Actor 或远程函数（Task） 运行时属性的方法，其参数主要围绕资源分配、调度策略、容错机制等核心功能
注意事项
- 所有参数均需符合 Ray 框架的预定义类型，传入未支持的参数会抛出错误
- 不同 Ray 版本可能新增或调整参数，建议结合官方文档（对应版本）查阅细节
- 这些参数仅用于配置运行时属性，自定义业务参数需通过 Actor 初始化或 Task 函数参数传递（见前文说明）

Actor 配置示例（Task 类似）

Actor 使用 .option() 函数的示例

@ray.remote
class MyActor:
    pass

# 配置 Actor 资源、名称和重启策略
actor = MyActor.options(
    num_cpus=1,
    num_gpus=0.5,
    name="my_actor",
    max_restarts=2,
    runtime_env={"env_vars": {"LOG_LEVEL": "INFO"}}
).remote()

通用核心参数（Actor 和 Task 均支持）

num_cpus 参数（类型：int 或 float）
- 指定运行该 Actor/Task 所需的 CPU 核心数（支持小数，如 0.5 表示半核）
- 示例：MyActor.options(num_cpus=2).remote()
num_gpus 参数（类型：int 或 float）
- 指定所需的 GPU 数量（需集群实际有 GPU 资源）
- 示例：my_task.options(num_gpus=1).remote()
resources 参数（类型：dict（键为资源名称，值为数量））
- 指定自定义资源需求（如特定硬件、加速器等）
- 示例：options(resources={"custom_accelerator": 1})
runtime_env 参数（类型：dict）
- 配置运行环境（如依赖库、环境变量、工作目录等），确保 Actor/Task 在一致的环境中运行
- 示例：options(runtime_env={"pip": ["numpy==1.21.0"]})
name 参数（类型：str）
- 为 Actor/Task 指定名称，用于日志追踪或通过名称查找 Actor（仅 Actor 有效）
- 示例：MyActor.options(name="worker-1").remote()

Actor 专属参数（仅 Actor 支持）

max_restarts 参数（类型：int）
- 指定 Actor 崩溃后的最大重启次数（默认 -1 表示无限重启，0 表示不重启）
- 示例：options(max_restarts=3)
max_task_retries 参数（类型：int）
- 指定 Actor 处理单个任务时的最大重试次数（任务失败后重试）
- 示例：options(max_task_retries=2)
lifetime 参数（类型：str（可选值："detached" 或 "non_detached"））
- 设置 Actor 生命周期。"detached" 表示 Actor 可脱离创建它的进程独立存在（进程退出后不销毁）
- 示例：options(lifetime="detached")
placement_group 参数（类型：PlacementGroup 实例）
- 将 Actor 绑定到特定的 放置组（Placement Group），优化资源 locality（本地性）

Task 专属参数（仅远程函数支持）

retry_exceptions 参数（类型：bool 或 tuple）
- 指定 Task 失败时是否重试，或仅对特定异常重试
- 示例：options(retry_exceptions=(ConnectionError,))
num_returns 参数（类型：int）
- 指定 Task 返回值的数量（默认 1，用于多返回值场景）
- 示例：@ray.remote(num_returns=2) def f(): return 1, 2

其他实用参数

priority 参数（类型：int）
- 设置 Task/Actor 任务的调度优先级（数值越高越优先，仅部分调度器支持）
memory 参数（类型：int）
- 指定所需的内存量（字节），超过会被终止（需集群启用内存限制）
object_store_memory 参数（类型：int）
- 指定 Task 可使用的对象存储内存量（字节）

附录：runtime_env 参数的详细说明

在 Ray 框架中，runtime_env 是 option() 方法中用于配置 运行时环境 的核心参数
runtime_env 参数的作用是确保远程任务（Task）或 Actor 在分布式集群中运行时，拥有一致的依赖环境、配置和资源，解决“本地能跑，集群跑不通”的环境一致性问题
runtime_env 接收一个字典作为参数，支持多种环境配置项，覆盖依赖管理、环境变量、文件同步等核心场景：
工作原理：当通过 option(runtime_env=...) 配置环境后，Ray 会在任务/Actor 启动前执行以下操作：
- 1）在 提交任务的节点 上收集 runtime_env 定义的依赖、文件和配置
- 2）将这些资源同步到 集群中的目标节点（通过 Ray 的对象存储或分布式文件系统）
- 3）在目标节点上自动创建隔离的运行环境（如虚拟环境、Conda 环境），安装依赖并注入环境变量
- 4）任务/Actor 在该隔离环境中启动，确保环境一致性

依赖库管理（确保三方库版本一致）

pip ：指定需要安装的 Python 依赖包及版本，支持通过列表或 requirements.txt 路径配置，示例如下：

# 直接指定依赖
runtime_env={"pip": ["numpy==1.24.3", "pandas==2.0.3"]}

# 通过 requirements.txt 配置
runtime_env={"pip": "requirements.txt"}

conda ：指定 Conda 环境配置，支持通过 environment.yml 路径或字典定义环境，示例如下：

# 通过 environment.yml 配置
runtime_env={"conda": "environment.yml"}

# 直接定义 Conda 环境
runtime_env={
    "conda": {
        "dependencies": ["python=3.9", "numpy=1.24.3"]
    }
}

wheel ：指定本地 Wheel 包路径，用于安装自定义或私有库（需确保集群节点可访问路径），示例如下：
1
runtime_env={"wheel": "./my_custom_lib-0.1.0-py3-none-any.whl"}

环境变量与配置注入

env_vars ：定义任务/Actor 运行时的环境变量，键值对形式传递，示例如下：

runtime_env={
    "env_vars": {
        "LOG_LEVEL": "INFO",  # 日志级别
        "DATA_PATH": "/data/training"  # 数据路径
    }
}

config ：传递自定义配置字典，可在任务/Actor 中通过 ray.get_runtime_context().runtime_env.get("config") 获取，用于业务参数传递，示例如下：
1
runtime_env={"config": {"batch_size": 32, "epochs": 10}}

文件与目录同步（确保资源可访问）

working_dir ：指定工作目录，Ray 会将该目录下的所有文件同步到执行任务的节点，确保代码、配置文件等资源可访问。支持本地路径或 Git 仓库 URL，示例如下：
1
2
3
4
5
# 同步本地目录
runtime_env={"working_dir": "./my_project"}

# 同步 Git 仓库（支持分支/标签）
runtime_env={"working_dir": "https://github.com/my_repo.git#branch=main"}

excludes ：配合 working_dir 使用，指定同步时需要排除的文件/目录（如日志、缓存文件），避免冗余同步，示例如下：

runtime_env={
    "working_dir": "./my_project",
    "excludes": ["*.log", "venv/", "data/*"]  # 排除日志、虚拟环境和数据目录
}

其他高级配置

py_modules ：指定需要导入的自定义 Python 模块路径，支持将本地模块添加到 Python 路径（sys.path），示例如下：
1
runtime_env={"py_modules": ["./my_utils"]} # 同步 my_utils 模块并添加到路径
env ：指定预定义的环境名称（如 Ray 集群中已配置的共享环境），避免重复配置，示例如下：
1
runtime_env={"env": "shared-training-env"} # 使用集群中预定义的环境

附录：option 中使用 runtime_env 和启动参数传入 yaml 文件的区别

在 Ray 中，可以使用 ray job submit 命令提交任务到已经启动的 Ray 集群中
ray job submit 命令的 --runtime-env 参数也可以通过传入 yaml 文件（或 JSON 格式的字符串）指定 runtime-env 参数
至此，我们有了两种指定方式：
- 在代码中通过 option 函数（如 @ray.remote 的 runtime_env 参数）指定运行时环境
- 在 ray job submit 命令中通过 --runtime-env 参数传入 yaml 文件指定运行时环境
两者的生效级别不同：
- --runtime-env=./runtime_env.yaml 是 全局级别的配置 ，会为整个 Ray Job 中的所有任务（包括所有 Actor、任务函数）设置默认的运行时环境
  - 适用于需要为整个作业统一配置环境的场景（如统一的工作目录、环境变量等）
- 代码中 option 函数指定（如 @ray.remote(runtime_env=...)）是局部级别的配置 ，仅对当前修饰的 Actor 或任务生效
  - 适用于为特定任务/Actor 单独设置差异化环境的场景（如某个任务需要额外的依赖包，而其他任务不需要）
两者的优先级不同：
- 局部配置（代码中 option 函数）的优先级高于全局配置（命令行 --runtime-env）
- 当两者配置不冲突时，会进行合并（例如全局配置了 env_vars，局部配置了 pip，最终环境会同时包含这两者）
- 当两者配置冲突时（如同一环境变量在两处被设置为不同值），局部配置会覆盖全局配置