整体说明
- 在 Ray 框架中，
.option()是用于配置 Actor 或远程函数（Task） 运行时属性的方法，其参数主要围绕资源分配、调度策略、容错机制等核心功能 - 注意事项
- 所有参数均需符合 Ray 框架的预定义类型，传入未支持的参数会抛出错误
- 不同 Ray 版本可能新增或调整参数，建议结合官方文档（对应版本）查阅细节
- 这些参数仅用于配置运行时属性，自定义业务参数需通过 Actor 初始化或 Task 函数参数传递（见前文说明）
Actor 配置示例（Task 类似）
- Actor 使用
.option()函数的示例1
2
3
4
5
6
7
8
9
10
11
12
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()
- 指定运行该 Actor/Task 所需的 CPU 核心数（支持小数，如
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)
- 指定 Actor 崩溃后的最大重启次数（默认
max_task_retries参数（类型：int）- 指定 Actor 处理单个任务时的最大重试次数（任务失败后重试）
- 示例：
options(max_task_retries=2)
lifetime参数（类型：str（可选值："detached"或"non_detached"））- 设置 Actor 生命周期。
"detached"表示 Actor 可脱离创建它的进程独立存在（进程退出后不销毁） - 示例：
options(lifetime="detached")
- 设置 Actor 生命周期。
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
- 指定 Task 返回值的数量（默认
其他实用参数
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 在该隔离环境中启动，确保环境一致性
- 1）在 提交任务的节点 上收集
更多讨论
- 在分布式计算中，集群节点的环境可能存在差异（如依赖库版本、环境变量、工作目录等）
runtime_env通过预先定义环境配置，让 Ray 自动在所有执行任务的节点上同步这些配置，确保任务/Actor 在 完全一致的环境 中运行，避免因环境差异导致的错误（如“ModuleNotFoundError”“版本不兼容”等）- 适用场景
- 确保所有 worker 节点使用相同版本的框架（如 PyTorch、TensorFlow）和依赖库
- 同步本地自定义模块或配置文件到集群，避免手动在每个节点部署代码
- 不同任务/Actor 可使用独立的依赖环境，避免版本冲突
- 其他问题
- 初次加载的性能开销：首次使用
runtime_env时，同步依赖和文件可能需要时间（尤其是大文件或复杂依赖），后续任务会复用缓存 - 确保输入路径可读：
working_dir、wheel等路径需确保提交节点和集群节点均可访问（本地路径需为集群共享存储路径，如 NFS） - 至少要提前安装
conda等包：部分配置（如conda）需集群节点预先安装 Conda，否则会失效
- 初次加载的性能开销：首次使用
依赖库管理（确保三方库版本一致）
pip：指定需要安装的 Python 依赖包及版本，支持通过列表或requirements.txt路径配置，示例如下：1
2
3
4
5# 直接指定依赖
runtime_env={"pip": ["numpy==1.24.3", "pandas==2.0.3"]}
# 通过 requirements.txt 配置
runtime_env={"pip": "requirements.txt"}conda：指定 Conda 环境配置，支持通过environment.yml路径或字典定义环境，示例如下：1
2
3
4
5
6
7
8
9# 通过 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 运行时的环境变量，键值对形式传递，示例如下：1
2
3
4
5
6runtime_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使用，指定同步时需要排除的文件/目录（如日志、缓存文件），避免冗余同步，示例如下：1
2
3
4runtime_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，最终环境会同时包含这两者） - 当两者配置冲突时（如同一环境变量在两处被设置为不同值），局部配置会覆盖全局配置
- 局部配置（代码中
