超参数优化器

class automation.HyperParameterOptimizer()

超参数搜索控制器。克隆基础实验，更改参数并尝试最大化/最小化定义的目标。

创建一个新的超参数控制器。新创建的对象将启动并监控新的实验。

参数
- base_task_id (str ) – 用作模板实验以进行优化的任务ID。
- hyper_parameters (list ) – 要优化的参数对象列表。
- Sequence [ str ] **] ** objective_metric_title (Union [ str , ) – 要最大化/最小化的目标指标标题（例如，validation, ["validation", "loss"]）。如果 objective_metric_title 是一个序列（用于同时优化多个目标），那么 objective_metric_series 和 objective_metric_sign 必须是相同长度的序列。每个标题将与相应的系列和符号匹配
- Sequence [ str ] **] ** objective_metric_series (Union [ str , ) – 要最大化/最小化的目标指标序列（例如，loss_series, ["validation_series", "loss_series"]）。
- Sequence [ str ] **] ** objective_metric_sign (Union [ str , ) – 要最大化/最小化的目标。
  
  值为：
  - min - 最小化指定标题/系列标量的最后报告值。
  - max - 最大化指定标题/系列标量的最后报告值。
  - min_global - 最小化特定标题/系列标量的所有报告值的最小值。
  - max_global - 最大化特定标题/系列标量的所有报告值的最大值。
- optimizer_class (class.SearchStrategy ) – 用于超参数搜索的SearchStrategy优化器
- max_number_of_concurrent_tasks (int ) – 同时运行的最大并发任务（实验）数量。
- execution_queue (str ) – 用于启动任务（实验）的执行队列。
- optimization_time_limit (float ) – 整个优化过程的最大时间（分钟）。默认值为 None，表示没有时间限制。
- compute_time_limit (float ) – 最大计算时间，单位为分钟。当超过时间限制时，所有作业将被中止。（可选）
- auto_connect_task (bool ) – 在任务中存储优化参数和配置。
  
  值为：
  - True - The optimization argument and configuration will be stored in the Task. All arguments will
  位于超参数部分 opt 下，优化超参数空间将存储在任务配置对象部分中。
  - False - 不与任务一起存储。
  - Task - 一个特定的任务对象，用于将优化过程与之连接。
- always_create_task (bool ) – 总是创建一个新的任务。
  
  值为：
  - True - No current Task initialized. Create a new task named optimization in the base_task_id
  项目。
  - False - Use the task.Task.current_task (if exists) to report statistics.
- spawn_project (str ) – 如果指定了项目名称，则在指定的项目中创建所有优化作业（任务），而不是在原始的 base_task_id 项目中。
- save_top_k_tasks_only (int ) – 如果指定且大于0，仅保留表现最好的top_k个任务，并将其余创建的任务存档。默认值：-1 保留所有内容，不会存档任何内容。
- optimizer_kwargs (** ) – 直接传递给优化器构造函数的参数。
示例：
```
:linenos:
:caption: Example

from clearml import Task
from clearml.automation import UniformParameterRange, DiscreteParameterRange
from clearml.automation import GridSearch, RandomSearch, HyperParameterOptimizer

task = Task.init('examples', 'HyperParameterOptimizer example')
an_optimizer = HyperParameterOptimizer(
    base_task_id='fa30fa45d95d4927b87c323b5b04dc44',
    hyper_parameters=[
        UniformParameterRange('lr', min_value=0.01, max_value=0.3, step_size=0.05),
        DiscreteParameterRange('network', values=['ResNet18', 'ResNet50', 'ResNet101']),
    ],
    objective_metric_title='title',
    objective_metric_series='series',
    objective_metric_sign='min',
    max_number_of_concurrent_tasks=5,
    optimizer_class=RandomSearch,
    execution_queue='workers', time_limit_per_job=120, pool_period_min=0.2)

# This will automatically create and print the optimizer new task id
# for later use. if a Task was already created, it will use it.
an_optimizer.set_time_limit(in_minutes=10.)
an_optimizer.start()
# we can create a pooling loop if we like
while not an_optimizer.reached_time_limit():
    top_exp = an_optimizer.get_top_experiments(top_k=3)
    print(top_exp)
# wait until optimization completed or timed-out
an_optimizer.wait()
# make sure we stop all jobs
an_optimizer.stop()
```

已用时间

elapsed()

返回从控制器启动时间戳开始经过的分钟数。

返回类型

float
返回

控制器启动时间的分钟数。负值表示进程尚未启动。

获取活动实验

get_active_experiments()

返回当前活动实验的任务列表。

返回类型

Sequence[Task]
返回

一个任务对象列表，代表当前活跃的实验。

获取活动实验数量

get_num_active_experiments()

返回当前活跃实验的数量。

返回类型

int
返回

活跃实验的数量。

get_optimizer

get_optimizer()

返回当前使用的优化器对象。

返回类型

SearchStrategy
返回

使用的SearchStrategy对象。

HyperParameterOptimizer.get_optimizer_top_experiments

classmethod get_optimizer_top_experiments(objective_metric_title, objective_metric_series, objective_metric_sign, optimizer_task_id, top_k)

返回基于标题/系列目标的特定超参数优化会话（即任务ID）中表现最佳实验的任务列表。

参数
- objective_metric_title (str ) – 要最大化/最小化的目标指标标题（例如， validation）。
- objective_metric_series (str ) – 要最大化/最小化的目标指标系列（例如，loss）。
- objective_metric_sign (str ) – 要最大化/最小化的目标。
  
  值为：
  - min - 最小化指定标题/系列标量的最后报告值。
  - max - 最大化指定标题/系列标量的最后报告值。
  - min_global - 最小化特定标题/系列标量的所有报告值的最小值。
  - max_global - 最大化特定标题/系列标量的所有报告值的最大值。
- optimizer_task_id (str ) – 父优化器任务ID
- top_k (int) – 返回的任务（实验）数量。
返回类型

Sequence[Task]
返回

一个按性能排序的任务对象列表，其中索引0是性能最佳的任务。

获取时间限制

get_time_limit()

返回控制器优化时间限制。

返回类型

datetime
返回

控制器优化过程的绝对日期时间限制。

获取顶级实验

获取前k个实验(top_k)

返回基于控制器Objective对象的顶级实验任务的列表。

参数

top_k (int ) – 返回的任务（实验）数量。
返回类型

Sequence[Task]
返回

一个按性能排序的任务对象列表，其中索引0是性能最佳的任务。

获取顶级实验详情

获取顶级实验详情(top_k, all_metrics=False, all_hyper_parameters=False, only_completed=False)

返回表现最佳实验的字典列表。示例：[{'task_id': Task-ID, 'metrics': scalar-metric-dict, 'hyper_parameters': Hyper-Parameters},]

订单基于控制器Objective对象。

参数
- top_k (int ) – 返回的任务（实验）数量。
- all_metrics (bool ) – 默认值为 False，仅在指标字典中返回目标指标。如果为 True，则返回实验的所有标量指标
- all_hyper_parameters (bool ) – 默认值为 False。如果为 True，则返回所有部分的所有超参数。
- only_completed (bool ) – 仅返回已完成的任务。默认值为 False。
返回类型

序列[(字符串, 字典)]

一个字典列表 ({task_id: '', hyper_parameters: {}, metrics: {}})，按性能排序，其中索引0是表现最好的任务。示例 w/ all_metrics=False:

[
    {
        task_id: '0593b76dc7234c65a13a301f731958fa',
        hyper_parameters: {'General/lr': '0.03', 'General/batch_size': '32'},
        metrics: {
            'accuracy per class/cat': {
                'metric': 'accuracy per class',
                'variant': 'cat',
                'value': 0.119,
                'min_value': 0.119,
                'max_value': 0.782
            },
        }
    },
]

示例 w/ all_metrics=True:

[
    {
        task_id: '0593b76dc7234c65a13a301f731958fa',
        hyper_parameters: {'General/lr': '0.03', 'General/batch_size': '32'},
        metrics: {
            'accuracy per class/cat': {
                'metric': 'accuracy per class',
                'variant': 'cat',
                'value': 0.119,
                'min_value': 0.119,
                'max_value': 0.782
            },
            'accuracy per class/deer': {
                'metric': 'accuracy per class',
                'variant': 'deer',
                'value': 0.219,
                'min_value': 0.219,
                'max_value': 0.282
            },
        }
    },
]

is_active

is_active()

优化程序是否处于活动状态（仍在运行）

值为：

True - 优化程序处于活动状态（仍在运行）。
False - 优化程序未激活（尚未运行）。

info

如果守护线程尚未启动，is_active 返回 True。

返回类型

bool
返回

一个布尔值，指示优化过程是否处于活动状态（仍在运行）或已停止。

is_running

is_running()

优化控制器是否正在运行

值为：

True - 优化程序正在运行。
False - 优化程序正在运行。

返回类型

bool
返回

一个布尔值，指示优化过程是否处于活动状态（仍在运行）或已停止。

达到时间限制

reached_time_limit()

优化器是否达到了时间限制

值为：

True - 时间限制已过。
False - 时间限制未通过。

此方法立即返回，它不会等待优化器。

返回类型

bool
返回

如果优化器正在运行并且我们超过了时间限制，则返回True，否则返回False。

设置默认作业类

设置默认作业类别(job_class)

设置优化器生成新作业时要使用的作业类。

参数

job_class (ClearmlJob ) – 作业类类型。
返回类型

()

设置报告周期

设置报告周期(report_period_minutes)

设置累积目标报告的报告周期（分钟）。此报告在优化器任务上发送，并从所有正在运行的作业中收集目标指标。

参数

report_period_minutes (float ) – 报告周期（分钟）。默认值为每10分钟一次。
返回类型

()

设置时间限制

set_time_limit(in_minutes=None, specific_time=None)

为HyperParameterOptimizer控制器设置时间限制。如果我们达到了时间限制，停止优化过程。如果提供了specific_time，则使用它；否则，使用in_minutes。

参数
- in_minutes (float ) – 从当前时间开始的最大处理时间（分钟）。
- specific_time (datetime ) – 特定的日期/时间限制。
返回类型

()

开始

start(job_complete_callback=None)

启动HyperParameterOptimizer控制器。如果调用进程停止，则控制器也会停止。

参数

job_complete_callback (Callable ) – 回调函数，当作业完成时调用。

def job_complete_callback(
    job_id,                 # type: str
    objective_value,        # type: float
    objective_iteration,    # type: int
    job_parameters,         # type: dict
    top_performance_job_id  # type: str
):
    pass

返回类型

bool
返回

如果控制器启动，则为True。如果控制器未启动，则为False。

本地启动

start_locally(job_complete_callback=None)

完全在本地启动HyperParameterOptimizer控制器。优化器任务和所有生成的子任务都在本地机器上使用当前环境运行。如果调用进程停止，控制器也会停止。

参数

job_complete_callback (Callable ) – 回调函数，当作业完成时调用。

def job_complete_callback(
    job_id,                 # type: str
    objective_value,        # type: float
    objective_iteration,    # type: int
    job_parameters,         # type: dict
    top_performance_job_id  # type: str
):
    pass

返回类型

bool
返回

如果控制器启动，则为True。如果控制器未启动，则为False。

停止

stop(timeout=None, wait_for_reporter=True)

停止HyperParameterOptimizer控制器和优化线程。

参数
- timeout (float ) – 等待优化线程退出的超时时间（分钟）。默认值为 None，表示不等待立即终止。
- wait_for_reporter (可选 [ bool ] ) – 等待报告器刷新数据。
返回类型

()

等待

wait(timeout=None)

等待优化器完成。

info

此方法不会停止优化器。调用stop以终止优化器。

参数

timeout (float ) – 等待优化完成的超时时间（分钟）。如果为 None，则等待直到达到超时时间或优化完成。
返回类型

bool
返回

如果优化完成，则为True。如果优化超时，则为False。

class automation.HyperParameterOptimizer()​

已用时间​

获取活动实验​

获取活动实验数量​

get_optimizer​

HyperParameterOptimizer.get_optimizer_top_experiments​

获取时间限制​

获取顶级实验​

获取顶级实验详情​

is_active​

is_running​

达到时间限制​

设置默认作业类​

设置报告周期​

设置时间限制​

开始​

本地启动​

停止​

等待​