Trial¶

class optuna.trial.Trial(study, trial_id)[源代码]¶

一个 Trial 是一个评估目标函数的过程。

该对象被传递给目标函数，并提供接口以获取 parameter suggestion, 管理 trial 状态以及设置/获取 trial 的用户定义属性。

请注意，我们不建议直接使用此构造函数。该对象被无缝实例化，并传递给 optuna.study.Study.optimize() 方法后面的目标函数；因此，库用户并不关心该对象的实例化。

参数

study -- A Study object.
trial_id -- A trial ID that is automatically generated.

property datetime_start¶

返回开始日期时间

返回: Datetime where the Trial started.

property distributions¶

返回待优化参数的分布。

返回: 一个包含所有分布的字典。

property number¶

返回 trial 的连续且唯一的编号。

返回: A trial number.

property params¶

Return parameters to be optimized.

返回: 一个包含所有参数的字典.

report(value, step)[源代码]¶

报告给定的步骤下目标函数值。

Pruner 使用报告的值来确定是否应对该 trial 剪枝。

参见

参见 BasePruner.

注解

报告值在内部被 float() 函数转换成 float 类型。因此，它接受所有类似float的类型（例如 numpy.float32'' ）。如果转换失败，则会引发 ``TypeError.

示例

报告 SGDClassifier <https://scikit-learn.org/stable/modules/generated/sklearn.linear_model.SGDClassifier.html> 在训练中的中间值。

import numpy as np
from sklearn.datasets import load_iris
from sklearn.linear_model import SGDClassifier
from sklearn.model_selection import train_test_split

import optuna

X, y = load_iris(return_X_y=True)
X_train, X_valid, y_train, y_valid = train_test_split(X, y)

def objective(trial):
    clf = SGDClassifier(random_state=0)
    for step in range(100):
        clf.partial_fit(X_train, y_train, np.unique(y))
        intermediate_value = clf.score(X_valid, y_valid)
        trial.report(intermediate_value, step=step)
        if trial.should_prune():
            raise optuna.TrialPruned()

    return clf.score(X_valid, y_valid)

study = optuna.create_study(direction='maximize')
study.optimize(objective, n_trials=3)

参数

value -- 从目标函数返回的值。
step -- Trial 步骤（例如，神经网络训练的 epoch）。

set_user_attr(key, value)[源代码]¶

将用户属性设置到 trial中。

可以通过 optuna.trial.Trial.user_attrs() 访问试 trial 中的用户属性。

示例

保存神经网络训练的固定超参数。

import numpy as np
from sklearn.datasets import load_iris
from sklearn.model_selection import train_test_split
from sklearn.neural_network import MLPClassifier

import optuna

X, y = load_iris(return_X_y=True)
X_train, X_valid, y_train, y_valid = train_test_split(X, y, random_state=0)

def objective(trial):
    trial.set_user_attr('BATCHSIZE', 128)
    momentum = trial.suggest_uniform('momentum', 0, 1.0)
    clf = MLPClassifier(hidden_layer_sizes=(100, 50),
                        batch_size=trial.user_attrs['BATCHSIZE'],
                        momentum=momentum, solver='sgd', random_state=0)
    clf.fit(X_train, y_train)

    return clf.score(X_valid, y_valid)

study = optuna.create_study(direction='maximize')
study.optimize(objective, n_trials=3)
assert 'BATCHSIZE' in study.best_trial.user_attrs.keys()
assert study.best_trial.user_attrs['BATCHSIZE'] == 128

参数

key -- A key string of the attribute.
value -- 属性的值。该值应为JSON可序列化的。

should_prune() → bool [源代码]¶

建议是否应修剪该 trial.

该 suggestion 是基于先前报告的值并通过与试验相关的 pruning 算法提出的。可以在构造一个 Study 时指定该算法。

注解

如果未报告任何值，则该算法无法提出有意义的 suggestion。同样，如果使用完全相同的一组报告值多次调用此方法，则 suggestion 也将相同。

参见

请参考 optuna.trial.Trial.report() 的示例代码。

返回: 一个布尔值。如果为 True, 则应根据配置的 pruning 算法对 trial 进行修剪。否则， trial 应继续进行。

suggest_categorical(name, choices)[源代码]¶

为分类参数提供一个 suggestion.

这个值是用 choices 进行采样的。

示例

为 SVC 提供一个 suggestion.

import numpy as np
from sklearn.datasets import load_iris
from sklearn.model_selection import train_test_split
from sklearn.svm import SVC

import optuna

X, y = load_iris(return_X_y=True)
X_train, X_valid, y_train, y_valid = train_test_split(X, y)

def objective(trial):
    kernel = trial.suggest_categorical('kernel', ['linear', 'poly', 'rbf'])
    clf = SVC(kernel=kernel, gamma='scale', random_state=0)
    clf.fit(X_train, y_train)
    return clf.score(X_valid, y_valid)

study = optuna.create_study(direction='maximize')
study.optimize(objective, n_trials=3)

参数

name -- A parameter name.
choices -- Parameter value candidates.

参见

CategoricalDistribution.

返回: A suggested value.

suggest_discrete_uniform(name, low, high, q)[源代码]¶

提供离散参数的 suggestion.

该值是从 \([\mathsf{low}, \mathsf{high}]\) 中采样的，并且其离散化的步数是:math:q. 更具体地说，该方法返回 \(\mathsf{low}, \mathsf{low} + q, \mathsf{low} + 2 q, \dots, \mathsf{low} + k q \le \mathsf{high}\) 序列中的一个值，其中:math:k 代表一个整数。注意，如果 \(q\) 不是整数的话，\(high\) 可能因为舍入误差而不同。请通过检查 warning 信息来找到改变的值。

示例

为拟合 GradientBoostingClassifier 的各个 learner 所需的样本个数提供一个 suggestion.

import numpy as np
from sklearn.datasets import load_iris
from sklearn.ensemble import GradientBoostingClassifier
from sklearn.model_selection import train_test_split

import optuna

X, y = load_iris(return_X_y=True)
X_train, X_valid, y_train, y_valid = train_test_split(X, y)

def objective(trial):
    subsample = trial.suggest_discrete_uniform('subsample', 0.1, 1.0, 0.1)
    clf = GradientBoostingClassifier(subsample=subsample, random_state=0)
    clf.fit(X_train, y_train)
    return clf.score(X_valid, y_valid)

study = optuna.create_study(direction='maximize')
study.optimize(objective, n_trials=3)

参数

name -- A parameter name.
low -- Suggestion 值范围的下限。 low 包含在范围内。
high -- Suggestion 值范围的上限。 high 包含在范围内。
q -- 一个离散化步骤

返回

A suggested float value.

suggest_float(name: str, low: float, high: float, *, step: Optional[float] = None, log: bool = False) → float [源代码]¶

提供一个浮点数的 suggestion.

注意，这事一个用于 suggest_uniform(), suggest_loguniform() 和 suggest_discrete_uniform() 的 wrapper 方法。

1.3.0 新版功能.

参见

参见 suggest_uniform(), suggest_loguniform() 和 suggest_discrete_uniform().

示例

为神经网络训练提供 momentum，learning rate 和 learning rate 的比例因子的suggestion 值。

import numpy as np
from sklearn.datasets import load_iris
from sklearn.model_selection import train_test_split
from sklearn.neural_network import MLPClassifier

import optuna

X, y = load_iris(return_X_y=True)
X_train, X_valid, y_train, y_valid = train_test_split(X, y, random_state=0)

def objective(trial):
    momentum = trial.suggest_float('momentum', 0.0, 1.0)
    learning_rate_init = trial.suggest_float('learning_rate_init',
                                             1e-5, 1e-3, log=True)
    power_t = trial.suggest_float('power_t', 0.2, 0.8, step=0.1)
    clf = MLPClassifier(hidden_layer_sizes=(100, 50), momentum=momentum,
                        learning_rate_init=learning_rate_init,
                        solver='sgd', random_state=0, power_t=power_t)
    clf.fit(X_train, y_train)

    return clf.score(X_valid, y_valid)

study = optuna.create_study(direction='maximize')
study.optimize(objective, n_trials=3)

参数

name -- A parameter name.
low -- Suggestion 值范围的下限。 low 包含在范围内。
high -- Suggestion 值范围的上限。 high 不包含在范围内。
step -- 一个离散化步骤 .. note:: step 和 log 参数不能同时使用。要把 step 设置成浮点数的话，请先把 log 参数设置成 False.
log -- 是否从对数域采样值的设置选项。如果 log 是 true，则从对数域中的范围采样该值，否则将从线性域中的范围采样。参见 suggest_uniform() 和 suggest_loguniform()... note:: step 和 log 参数不能同时使用。要把 step 设置成浮点数的话，请先把 log 参数设置成 False.

引发

ValueError -- 如果 step is not None 并且制定了 log = True.

返回

A suggested float value.

suggest_int(name: str, low: int, high: int, step: int = 1, log: bool = False) → int [源代码]¶

提供一个整数 suggestion.

该值是从 \([\mathsf{low}, \mathsf{high}]\) 中采样的。

示例

为 RandomForestClassifier 提供一个关于树个数的 suggestion.

import numpy as np
from sklearn.datasets import load_iris
from sklearn.ensemble import RandomForestClassifier
from sklearn.model_selection import train_test_split

import optuna

X, y = load_iris(return_X_y=True)
X_train, X_valid, y_train, y_valid = train_test_split(X, y)

def objective(trial):
    n_estimators = trial.suggest_int('n_estimators', 50, 400)
    clf = RandomForestClassifier(n_estimators=n_estimators, random_state=0)
    clf.fit(X_train, y_train)
    return clf.score(X_valid, y_valid)

study = optuna.create_study(direction='maximize')
study.optimize(objective, n_trials=3)

参数

name -- A parameter name.
low -- Suggestion 值范围的下限。 low 包含在范围内。
high -- Suggestion 值范围的上限。 high 包含在范围内。
step -- 一个离散化步骤。 .. note:: 注意， \(\mathsf{high}\) 会被改变，如果该范围无法被 \(\mathsf{step}\) 整除的话。请通过检查 warning 信息来找出改变了的值。 .. note:: 该方法返回序列 \(\mathsf{low}, \mathsf{low} + \mathsf{step}, \mathsf{low} + 2 * \mathsf{step}, \dots, \mathsf{low} + k * \mathsf{step} \le \mathsf{high}\) 中的一个值，其中 \(k\) 代表一个整数. .. note:: 参数 step != 1 and log 不能同时使用。要把 step 设置成 \(\mathsf{step} \ge 2\) 的话，先把 log 设置成 False.
log -- 是否从对数域采样值的设置选项。.. note:: 如果``log`` 是 true，则在一开始的时候， suggestion 值的范围会被分成宽度为 1 的网格点。然后 suggestion 值会被转化到对数域，并在该域上进行采样。这些均匀采样的值会被重新转换到原来的线性域上，并且被舍入到最近的网格点中。这就是确定采样值的过程。比如，如果 low = 2 且 high = 8 的话， suggestion 值的范围就是 [2, 3, 4, 5, 6, 7, 8] 而且较小的值有更大的概率被采样到。step != 1 和 log 参数不能同时使用要把 log 设置成 True 的话，请先把 step 设置成 1.

引发

ValueError -- 如果 step != 1 and log = True 被确定了

suggest_loguniform(name, low, high)[源代码]¶

从连续参数值中提供 suggestion.

该值是从对数域的 \([\mathsf{low}, \mathsf{high}]\) 中采样的。当 mathsf{low} = mathsf{high}` 时，返回结果是 \(\mathsf{low}\).

示例

为 SVC. 的罚参数 C 提供一个 suggestion 值。

import numpy as np
from sklearn.datasets import load_iris
from sklearn.model_selection import train_test_split
from sklearn.svm import SVC

import optuna

X, y = load_iris(return_X_y=True)
X_train, X_valid, y_train, y_valid = train_test_split(X, y)

def objective(trial):
    c = trial.suggest_loguniform('c', 1e-5, 1e2)
    clf = SVC(C=c, gamma='scale', random_state=0)
    clf.fit(X_train, y_train)
    return clf.score(X_valid, y_valid)

study = optuna.create_study(direction='maximize')
study.optimize(objective, n_trials=3)

参数

name -- A parameter name.
low -- Suggestion 值范围的下限。 low 包含在范围内。
high -- Suggestion 值范围的上限。 high 不包含在范围内。

返回

A suggested float value.

suggest_uniform(name, low, high)[源代码]¶

从连续参数值中提供 suggestion.

该值是从线性域的 \([\mathsf{low}, \mathsf{high}]\) 中采样的。当 mathsf{low} = mathsf{high}` 时，返回结果是 \(\mathsf{low}\).

示例

为神经网络训练提出 momentum 的suggestion 值。

import numpy as np
from sklearn.datasets import load_iris
from sklearn.model_selection import train_test_split
from sklearn.neural_network import MLPClassifier

import optuna

X, y = load_iris(return_X_y=True)
X_train, X_valid, y_train, y_valid = train_test_split(X, y)

def objective(trial):
    momentum = trial.suggest_uniform('momentum', 0.0, 1.0)
    clf = MLPClassifier(hidden_layer_sizes=(100, 50), momentum=momentum,
                        solver='sgd', random_state=0)
    clf.fit(X_train, y_train)

    return clf.score(X_valid, y_valid)

study = optuna.create_study(direction='maximize')
study.optimize(objective, n_trials=3)

参数

name -- A parameter name.
low -- Suggestion 值范围的下限。 low 包含在范围内。
high -- Suggestion 值范围的上限。 high 不包含在范围内。

返回

A suggested float value.

property user_attrs¶

返回用户属性

返回: 包含所有用户属性的字典。

class optuna.trial.FixedTrial(params, number=0)[源代码]¶

一个始终为每个参数提供固定 suggestion 值的 trial 类。

该对象和 Trial 有着一样的方法。它提供预定义的参数值 suggestion. 这些参数值可以通过构造 FixedTrial 来决定。和 Trial 不同，FixedTrial 并不依赖 Study, 这对于部署优化过程很有用。

示例

根据用户给定的参数值对一个目标函数求解。

import optuna

def objective(trial):
    x = trial.suggest_uniform('x', -100, 100)
    y = trial.suggest_categorical('y', [-1, 0, 1])
    return x ** 2 + y

assert objective(optuna.trial.FixedTrial({'x': 1, 'y': 0})) == 1

注解

关于方法和属性的细节请参考 Trial.

参数

params -- 一个包含所有参数的字典.
number -- Trial 编号，默认是 0.

class optuna.trial.FrozenTrial(number, state, value, datetime_start, datetime_complete, params, distributions, user_attrs, system_attrs, intermediate_values, trial_id)[源代码]¶

一个 Trial 的状态和结果。

number¶: 每个 Study 中 Trial 的连续且唯一的编号。注意这是从 0 开始计数的。

state¶: TrialState of the Trial.

value¶: Trial 的目标函数值。

datetime_start¶: Datetime where the Trial started.

datetime_complete¶: Trial 的完成时间。

params¶: 包含参数 suggestion 值的字典。

user_attrs¶: 通过 optuna.trial.Trial.set_user_attr() 设置的、包含了 Trial 属性的字典。

intermediate_values¶: 通过 optuna.trial.Trial.report() 来设定的中间目标函数值。

property distributions¶: 包含了 params 分布的字典。

property duration¶

返回完成该 trial 耗费的时间。

返回: 持续时间。

class optuna.trial.TrialState[源代码]¶

State of a Trial.

RUNNING¶: 该 Trial 处于运行中状态。

COMPLETE¶: 该 Trial 已完成，且未触发任何错误。

PRUNED¶: 该 Trial 已经被 TrialPruned 剪枝。

FAIL¶: 由于未捕获的错误，该 Trial 已经失败。