ray.tune.run#

执行训练。

当接收到SIGINT信号时（例如通过Ctrl+C），调优运行将优雅地关闭并检查点最新的实验状态。再次发送SIGINT（或改为SIGKILL/SIGTERM）将跳过此步骤。

Tune 的许多方面，例如全局检查点的频率、最大待处理的放置组试验以及结果目录的路径，都可以通过环境变量进行配置。有关可用环境变量的列表，请参阅 Ray Tune 使用的环境变量。

示例：

# Run 10 trials (each trial is one instance of a Trainable). Tune runs
# in parallel and automatically determines concurrency.
tune.run(trainable, num_samples=10)

# Run 1 trial, stop when trial has reached 10 iterations
tune.run(my_trainable, stop={"training_iteration": 10})

# automatically retry failed trials up to 3 times
tune.run(my_trainable, stop={"training_iteration": 10}, max_failures=3)

# Run 1 trial, search over hyperparameters, stop after 10 iterations.
space = {"lr": tune.uniform(0, 1), "momentum": tune.uniform(0, 1)}
tune.run(my_trainable, config=space, stop={"training_iteration": 10})

# Resumes training if a previous machine crashed
tune.run(
    my_trainable, config=space,
    storage_path=<path/to/dir>, name=<exp_name>, resume=True
)

参数:

run_or_experiment – 如果是函数|类|字符串，这是要训练的算法或模型。这可能指的是内置算法的名称（例如 RLlib 的 DQN 或 PPO）、用户定义的可训练函数或类，或者是注册在 tune 注册表中的可训练函数或类的字符串标识符。如果是 Experiment，那么 Tune 将基于 Experiment.spec 执行训练。如果你想传递一个 Python lambda，你需要先注册该函数：tune.register_trainable("lambda_id", lambda x: ...)。然后你可以使用 tune.run("lambda_id")。
metric – 要优化的指标。此指标应通过 tune.report() 报告。如果设置，将传递给搜索算法和调度器。
mode – 必须是 [min, max] 之一。确定目标是最小化还是最大化指标属性。如果设置，将传递给搜索算法和调度器。
name – 实验名称。
stop – 停止标准。如果是字典，键可以是 ‘train()’ 返回结果中的任何字段，以先达到的为准。如果是函数，它必须接受 (trial_id, result) 作为参数并返回一个布尔值（如果试验应停止则为 True，否则为 False）。这也可以是 ray.tune.Stopper 的子类，允许用户实现自定义的实验范围停止（即，基于某些时间约束停止整个 Tune 运行）。
time_budget_s – 全局时间预算，单位为秒，超过此时间后所有试验将被停止。也可以是一个 datetime.timedelta 对象。
config – Tune 变体生成的特定算法配置（例如，环境、超参数）。默认为空字典。自定义搜索算法可能会忽略此项。
resources_per_trial – 每个试验分配的机器资源，例如 {"cpu": 64, "gpu": 8}。请注意，除非您在此处指定，否则不会分配GPU。默认情况下，在 Trainable.default_resource_request() 中为1个CPU和0个GPU。这也可以是一个PlacementGroupFactory对象，包装参数以创建每个试验的放置组。
num_samples – 从超参数空间采样的次数。默认为1。如果提供了 grid_search 作为参数，网格将被重复 num_samples 次。如果此值为 -1，则（实际上）无限生成样本，直到满足停止条件。
storage_path – 存储结果的路径。可以是本地目录或云存储上的目标位置。默认为本地的 ~/ray_results 目录。
search_alg – 优化搜索算法。您也可以使用算法的名称。
scheduler – 用于执行实验的调度器。可以选择 FIFO（默认）、MedianStopping、AsyncHyperBand、HyperBand 和 PopulationBasedTraining。更多选项请参考 ray.tune.schedulers。您也可以使用调度器的名称。
verbose – 0, 1, 或 2。详细模式。0 = 静默，1 = 默认，2 = 详细。默认为 1。如果设置了 RAY_AIR_NEW_OUTPUT=1 环境变量，则使用旧的详细设置：0 = 静默，1 = 仅状态更新，2 = 状态和简要结果，3 = 状态和详细结果。
progress_reporter – 用于报告实验进度的进度报告器。如果在命令行中运行，默认为 CLIReporter；如果在 Jupyter 笔记本中运行，默认为 JupyterNotebookReporter。
log_to_file – 将标准输出和标准错误记录到 Tune 的试验目录中的文件。如果这是 False`（默认），则不会写入任何文件。如果为 `true，输出将分别写入 trialdir/stdout 和 trialdir/stderr。如果这是一个字符串，则将其解释为相对于试验目录的文件，两个流都将写入该文件。如果这是一个序列（例如元组），它必须有长度为 2，元素分别指示 stdout 和 stderr 写入的文件。
trial_name_creator – 可选函数，接受一个 Trial 并返回其名称（即其字符串表示）。请确保在每个试验的名称中包含一些唯一标识符（如 Trial.trial_id）。
trial_dirname_creator – 可选函数，接收一个试验并生成其试验目录名称作为字符串。确保在每个试验的目录名称中包含一些唯一标识符（如 Trial.trial_id）。否则，试验可能会覆盖其他试验的工件和检查点。返回值不能是一个路径。
chdir_to_trial_dir – 已弃用。请设置 RAY_CHDIR_TO_TRIAL_DIR 环境变量代替。
sync_config – 用于同步的配置对象。参见 train.SyncConfig。
export_formats – 实验结束时导出的格式列表。默认值为 None。
max_failures – 尝试至少恢复试用次数。如果存在最新检查点，Ray 将从该检查点恢复。设置为 -1 将导致无限次恢复重试。设置为 0 将禁用重试。默认为 0。
fail_fast – 是否在第一次错误时失败。如果提供了 fail_fast=’raise’，Tune 将自动引发 Trainable 接收到的异常。fail_fast=’raise’ 可能会轻易泄露资源，应谨慎使用（最好与 ray.init(local_mode=True) 一起使用）。
restore – 检查点路径。仅在运行1个试验时设置才有意义。默认为None。
resume – [True, False, “AUTO”] 之一。可以附加一个或多个 [“+ERRORED”, “+ERRORED_ONLY”, “+RESTART_ERRORED”, “+RESTART_ERRORED_ONLY”]（例如 AUTO+ERRORED）。resume=True 和 resume="AUTO" 将尝试从检查点恢复，否则将开始一个新的实验。后缀 “+ERRORED” 在恢复时重置并重新运行出错的试验 - 之前的试验工件将保持不变。它将尝试从最后一个观察到的检查点继续。后缀 “+RESTART_ERRORED” 将从头开始出错的试验。”+ERRORED_ONLY” 和 “+RESTART_ERRORED_ONLY” 将禁用恢复非出错的试验 - 它们将被添加为已完成。搜索算法仍然可以生成新的试验。
resume_config – [实验性] 控制如何恢复不同状态试验的配置对象。可以用作上述 resume 后缀的替代品。
reuse_actors – 是否在不同试验之间尽可能重复使用演员。这可以大幅加快经常启动和停止演员的实验（例如，时间复用模式下的PBT）。这要求试验具有相同的资源需求。默认为 False。
raise_on_failed_trial – 如果在实验完成时存在失败的试验（处于ERROR状态），则引发TuneError。
callbacks – 在训练循环的不同时间点将被调用的回调函数列表。必须是 ray.tune.callback.Callback 类的实例。如果没有传递，`LoggerCallback`（json/csv/tensorboard）回调会自动添加。
max_concurrent_trials – 最大并发运行试验次数。必须为非负数。如果为 None 或 0，则不会应用限制。这是通过将 search_alg 包装在 ConcurrencyLimiter 中实现的，因此如果 search_alg 已经是 ConcurrencyLimiter，则设置此参数将引发异常。默认为 None。
_remote – 是否在远程函数中运行 Tune 驱动程序。如果传入了自定义的试验执行器，则会自动禁用此功能。在 Ray 客户端模式下，此功能默认启用。
local_dir – 已弃用。请改用 storage_path。
keep_checkpoints_num – 已弃用。请改用 checkpoint_config。
checkpoint_score_attr – 已弃用。请改用 checkpoint_config。
checkpoint_freq – 已弃用。请改用 checkpoint_config。
checkpoint_at_end – 已弃用。请改用 checkpoint_config。
checkpoint_keep_all_ranks – 已弃用。请改用 checkpoint_config。
checkpoint_upload_from_workers – 已弃用。请改用 checkpoint_config。

返回:

实验分析的对象。

返回类型:

ExperimentAnalysis

抛出:

TuneError – 任何试验失败且 raise_on_failed_trial 为 True。