optuna.trial.Trial

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

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

此对象会传递给目标函数，并提供用于获取参数建议、管理 trial 状态以及设置/获取 trial 用户定义属性的接口。

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

参数:

study (optuna.study.Study) – 一个 Study 对象。
trial_id (int) – 自动生成的 trial ID。

方法

`report`(value, step)	报告给定步数的 objecive 函数值。
`set_system_attr`(key, value)	为 trial 设置系统属性。
`set_user_attr`(key, value)	为 trial 设置用户属性。
`should_prune`()	建议 trial 是否应该被剪枝。
`suggest_categorical`()	为分类参数建议一个值。
`suggest_discrete_uniform`(name, low, high, q)	为离散参数建议一个值。
`suggest_float`(name, low, high, *[, step, log])	为浮点参数建议一个值。
`suggest_int`(name, low, high, *[, step, log])	为整数参数建议一个值。
`suggest_loguniform`(name, low, high)	为连续参数建议一个值。
`suggest_uniform`(name, low, high)	为连续参数建议一个值。

属性

`datetime_start`	返回开始时间。
`distributions`	返回要优化的参数的分布。
`编号`	返回 study 中连续且唯一的 trial 编号。
`参数`	返回要优化的参数。
`relative_params`
`系统属性`	返回系统属性。
`user_attrs`	返回用户属性。

property datetime_start: datetime | None

返回开始时间。

返回:: Trial 开始的日期时间。

property distributions: dict[str, BaseDistribution]

返回要优化的参数的分布。

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

property number: int

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

返回:: Trial 编号。

property params: dict[str, Any]

返回要优化的参数。

返回:: 包含所有参数的字典。

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

报告给定步数的 objecive 函数值。

报告的值由 pruners 用于确定此 trial 是否应被剪枝。

另请参阅

请参阅 BasePruner。

注意

报告的值通过内部调用 float() 函数转换为 float 类型。因此，它接受所有类 float 类型（例如 numpy.float32）。如果转换失败，将引发 TypeError。

注意

如果在 trial 中对同一 step 调用此方法多次，仅存储第一次报告的 value，而忽略后续调用报告的值。

注意

report() 不支持多目标优化。

示例

报告 SGDClassifier 训练的中间分数。

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 (float) – 从目标函数返回的值。
step (int) – Trial 的步数（例如，神经网络训练的 Epoch）。请注意，pruners 假定 step 从零开始。例如，MedianPruner 仅检查 step 是否小于 n_warmup_steps 作为预热机制。step 必须是正整数。

返回类型:

无

set_system_attr(key, value)[源代码]

为 trial 设置系统属性。

请注意，Optuna 内部使用此方法来保存系统消息，例如 trial 的失败原因。请使用 set_user_attr() 来设置用户的属性。

参数:

key (str) – 属性的键字符串。
value (Any) – 属性的值。该值应可 JSON 序列化。

返回类型:

无

警告

在 v3.1.0 中已弃用。此功能将在未来移除。此功能移除的计划是 v5.0.0，但该计划可能会更改。请参阅 https://github.com/optuna/optuna/releases/tag/v3.1.0。

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

为 trial 设置用户属性。

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

另请参阅

请参阅用户属性中的示例。

示例

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

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_float("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 (str) – 属性的键字符串。
value (Any) – 属性的值。该值应可 JSON 序列化。

返回类型:

无

should_prune()[源代码]

建议 trial 是否应该被剪枝。

建议由 trial 关联的剪枝算法做出，并基于先前报告的值。构建 Study 时可以指定算法。

注意

如果没有报告任何值，算法将无法做出有意义的建议。同样，如果使用完全相同的报告值集多次调用此方法，建议将保持不变。

另请参阅

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

注意

should_prune() 不支持多目标优化。

返回:: 一个布尔值。如果为 True，则 trial 应根据配置的剪枝算法进行剪枝。否则，trial 应继续。
返回类型:: bool

suggest_categorical(name: str, choices: Sequence[None]) → None[源代码]

suggest_categorical(name: str, choices: Sequence[bool]) → bool

suggest_categorical(name: str, choices: Sequence[int]) → int

suggest_categorical(name: str, choices: Sequence[float]) → float

suggest_categorical(name: str, choices: Sequence[str]) → str

为分类参数建议一个值。

该值从 choices 中采样。

示例

为 SVC 的核函数建议一个值。

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 – 参数名称。
choices – 参数值候选。

另请参阅

CategoricalDistribution.

返回:: 建议值。

另请参阅

Pythonic 搜索空间教程描述了更多细节和灵活用法。

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

为离散参数建议一个值。

该值从范围 \([\mathsf{low}, \mathsf{high}]\) 中采样，离散化步长为 \(q\)。更具体地说，此方法返回序列 \(\mathsf{low}, \mathsf{low} + q, \mathsf{low} + 2 q, \dots, \mathsf{low} + k q \le \mathsf{high}\) 中的一个值，其中 \(k\) 表示一个整数。请注意，如果 \(q\) 不是整数，则 \(high\) 可能由于舍入误差而更改。请检查警告消息以查找已更改的值。

参数:

name (str) – 参数名称。
low (float) – 建议值范围的下限。 low 包含在范围内。
high (float) – 建议值范围的上限。 high 包含在范围内。
q (float) – 离散化的步长。

返回:

建议的浮点值。

返回类型:

float

警告

v3.0.0 中已弃用。此功能将在未来版本中移除。此功能当前的移除计划是 v6.0.0，但此计划可能会更改。请参阅 https://github.com/optuna/optuna/releases/tag/v3.0.0。

请改用 suggest_float(…, step=…)。

suggest_float(name, low, high, *, step=None, log=False)[源代码]

为浮点参数建议一个值。

示例

建议神经网络训练的动量、学习率和学习率缩放因子。

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 (str) – 参数名称。
low (float) – 建议值范围的下限。 low 包含在范围内。 low 必须小于或等于 high。如果 log 为 True，则 low 必须大于 0。
high (float) – 建议值范围的上限。 high 包含在范围内。 high 必须大于或等于 low。
step (float | None) –
离散化的步长。

注意

不能同时使用 step 和 log 参数。要将 step 参数设置为浮点数，请将 log 参数设置为 False。
log (bool) –
一个标志，用于指示是否从对数域采样值。如果 log 为 true，则值从对数域的范围内采样。否则，值从线性域的范围内采样。

注意

不能同时使用 step 和 log 参数。要将 log 参数设置为 True，请将 step 参数设置为 None。

返回:

建议的浮点值。

返回类型:

float

另请参阅

Pythonic 搜索空间教程描述了更多细节和灵活用法。

suggest_int(name, low, high, *, step=1, log=False)[源代码]

为整数参数建议一个值。

该值从 \([\mathsf{low}, \mathsf{high}]\) 中的整数范围内采样。

示例

建议 RandomForestClassifier 的树数量。

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 (str) – 参数名称。
low (int) – 建议值范围的下限。 low 包含在范围内。 low 必须小于或等于 high。如果 log 为 True，则 low 必须大于 0。
high (int) – 建议值范围的上限。 high 包含在范围内。 high 必须大于或等于 low。
step (int) –
离散化的步长。

注意

注意，如果范围不能被 \(\mathsf{step}\) 整除，则 \(\mathsf{high}\) 会被修改。请检查警告消息以查找已更改的值。

注意

该方法返回序列 \(\mathsf{low}, \mathsf{low} + \mathsf{step}, \mathsf{low} + 2 * \mathsf{step}, \dots, \mathsf{low} + k * \mathsf{step} \le \mathsf{high}\) 中的一个值，其中 \(k\) 表示一个整数。

注意

不能同时使用 step != 1 和 log 参数。要将 step 参数设置为 \(\mathsf{step} \ge 2\)，请将 log 参数设置为 False。
log (bool) –
一个标志，用于指示是否从对数域采样值。

注意

如果 log 为 true，首先将建议值范围划分为宽度为 1 的网格点。然后将建议值范围转换为对数域，并从中采样一个值。将均匀采样的值重新转换为原始域，并四舍五入到我们刚刚划分的最近的网格点，然后确定建议值。例如，如果 low = 2 且 high = 8，则建议值范围为 [2, 3, 4, 5, 6, 7, 8]，并且较低的值比较高的值更有可能被采样。

注意

不能同时使用 step != 1 和 log 参数。要将 log 参数设置为 True，请将 step 参数设置为 1。

返回类型:

int

另请参阅

Pythonic 搜索空间教程描述了更多细节和灵活用法。

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

为连续参数建议一个值。

该值从对数域中的范围 \([\mathsf{low}, \mathsf{high})\) 中采样。当 \(\mathsf{low} = \mathsf{high}\) 时，将返回 \(\mathsf{low}\) 的值。

参数:

name (str) – 参数名称。
low (float) – 建议值范围的下限。 low 包含在范围内。
high (float) – 建议值范围的上限。 high 包含在范围内。

返回:

建议的浮点值。

返回类型:

float

警告

v3.0.0 中已弃用。此功能将在未来版本中移除。此功能当前的移除计划是 v6.0.0，但此计划可能会更改。请参阅 https://github.com/optuna/optuna/releases/tag/v3.0.0。

请改用 suggest_float(…, log=True)。

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

为连续参数建议一个值。

该值从线性域中的范围 \([\mathsf{low}, \mathsf{high})\) 中采样。当 \(\mathsf{low} = \mathsf{high}\) 时，将返回 \(\mathsf{low}\) 的值。

参数:

name (str) – 参数名称。
low (float) – 建议值范围的下限。 low 包含在范围内。
high (float) – 建议值范围的上限。 high 包含在范围内。

返回:

建议的浮点值。

返回类型:

float

警告

v3.0.0 中已弃用。此功能将在未来版本中移除。此功能当前的移除计划是 v6.0.0，但此计划可能会更改。请参阅 https://github.com/optuna/optuna/releases/tag/v3.0.0。

请改用 suggest_float。

property system_attrs: dict[str, Any]

返回系统属性。

返回:: 包含所有系统属性的字典。

警告

在 v3.1.0 中已弃用。此功能将在未来移除。此功能移除的计划是 v5.0.0，但该计划可能会更改。请参阅 https://github.com/optuna/optuna/releases/tag/v3.1.0。

property user_attrs: dict[str, Any]

返回用户属性。

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