optuna.storages.JournalStorage

class optuna.storages.JournalStorage(log_storage)[源代码]

Journal storage 后端的存储类。

请注意，库用户可以实例化此类，但此类提供的属性不应被用户直接访问。

Journal storage 在执行操作时将每个操作的记录写入数据库，同时在内存中保留数据库的最新快照。如果数据库因任何原因崩溃，存储可以通过从头开始重放记录的操作来重新建立内存中的内容。

与传统的价值日志存储相比，Journal storage 具有几个优点。

由于日志粒度更大，可以减少 IO 次数。
Journal storage 比价值日志存储具有更简单的后端 API。
Journal storage 在内存中保留快照，因此无需添加更多缓存。

示例

import optuna

def objective(trial): ...

storage = optuna.storages.JournalStorage(
    optuna.storages.journal.JournalFileBackend("./optuna_journal_storage.log")
)

study = optuna.create_study(storage=storage)
study.optimize(objective)

在 Windows 环境中，可能会出现“客户端未持有所需权限”的错误消息。在这种情况下，您可以通过指定 JournalFileOpenLock 来创建存储，从而解决此问题，如下所示。

file_path = "./optuna_journal_storage.log"
lock_obj = optuna.storages.journal.JournalFileOpenLock(file_path)

storage = optuna.storages.JournalStorage(
    optuna.storages.journal.JournalFileBackend(file_path, lock_obj=lock_obj),
)

方法

`check_trial_is_updatable`(trial_id, trial_state)	检查试验状态是否可更新。
`create_new_study`(directions[, study_name])	从名称创建新试验。
`create_new_trial`(study_id[, template_trial])	为试验创建并添加一个新试验。
`delete_study`(study_id)	删除试验。
`get_all_studies`()	读取 `FrozenStudy` 对象列表。
`get_all_trials`(study_id[, deepcopy, states])	读取试验中的所有试验。
`get_best_trial`(study_id)	返回试验中具有最佳值的试验。
`get_n_trials`(study_id[, state])	计算试验中的试验数量。
`get_study_directions`(study_id)	读取试验是最大化还是最小化目标。
`get_study_id_from_name`(study_name)	读取试验的 ID。
`get_study_name_from_id`(study_id)	读取试验的试验名称。
`get_study_system_attrs`(study_id)	读取试验的 optuna 内部属性。
`get_study_user_attrs`(study_id)	读取试验的用户定义属性。
`get_trial`(trial_id)	读取一个试验。
`get_trial_id_from_study_id_trial_number`(...)	读取试验的试验 ID。
`get_trial_number_from_id`(trial_id)	读取试验的试验编号。
`get_trial_param`(trial_id, param_name)	读取试验的参数。
`get_trial_params`(trial_id)	读取试验的参数字典。
`get_trial_system_attrs`(trial_id)	读取试验的 optuna 内部属性。
`get_trial_user_attrs`(trial_id)	读取试验的用户定义属性。
`remove_session`()	清理到数据库的所有连接。
`restore_replay_result`(snapshot)
`set_study_system_attr`(study_id, key, value)	向试验注册一个 optuna 内部属性。
`set_study_user_attr`(study_id, key, value)	向试验注册一个用户定义的属性。
`set_trial_intermediate_value`(trial_id, step, ...)	报告目标函数的中间值。
`set_trial_param`(trial_id, param_name, ...)	为试验设置一个参数。
`set_trial_state_values`(trial_id, state[, values])	更新试验的状态和值。
`set_trial_system_attr`(trial_id, key, value)	为试验设置一个 optuna 内部属性。
`set_trial_user_attr`(trial_id, key, value)	为试验设置一个用户定义的属性。

参数:: log_storage (BaseJournalBackend)

check_trial_is_updatable(trial_id, trial_state)

检查试验状态是否可更新。

参数:

trial_id (int) – 试验的 ID。仅用于错误消息。
trial_state (TrialState) – 要检查的试验状态。

引发:

UpdateFinishedTrialError – 如果试验已完成。

返回类型:

无

create_new_study(directions, study_name=None)[源代码]

从名称创建新试验。

如果未指定名称，则存储类将生成一个名称。返回的试验 ID 在所有当前和已删除的试验中都是唯一的。

参数:

directions (Sequence[StudyDirection]) – 方向序列，其元素为 MAXIMIZE 或 MINIMIZE。
study_name (str | None) – 要创建的新试验的名称。

返回:

已创建试验的 ID。

引发:

optuna.exceptions.DuplicatedStudyError – 如果已存在同名的试验。

返回类型:

int

create_new_trial(study_id, template_trial=None)[源代码]

为试验创建并添加一个新试验。

返回的试验 ID 在所有当前和已删除的试验中都是唯一的。

参数:

study_id (int) – 试验的 ID。
template_trial (FrozenTrial | None) – 具有默认用户属性、系统属性、中间值和状态的模板 FrozenTrial。

返回:

已创建试验的 ID。

引发:

KeyError – 如果不存在匹配 study_id 的试验。

返回类型:

int

delete_study(study_id)[源代码]

删除试验。

参数:: study_id (int) – 试验的 ID。
引发:: KeyError – 如果不存在匹配 study_id 的试验。
返回类型:: 无

get_all_studies()[源代码]

读取 FrozenStudy 对象列表。

返回:: 按 study_id 排序的 FrozenStudy 对象列表。
返回类型:: list[FrozenStudy]

get_all_trials(study_id, deepcopy=True, states=None)[源代码]

读取试验中的所有试验。

参数:

study_id (int) – 试验的 ID。
deepcopy (bool) – 在返回之前是否复制试验列表。如果您打算更新列表或列表中的元素，请设置为 True。
states (Container[TrialState] | None) – 要过滤的试验状态。如果为 None，则包含所有状态。

返回:

试验中的试验列表，按 trial_id 排序。

引发:

KeyError – 如果不存在匹配 study_id 的试验。

返回类型:

list[FrozenTrial]

get_best_trial(study_id)

返回试验中具有最佳值的试验。

此方法仅在单目标优化期间有效。

参数:

study_id (int) – 试验的 ID。

返回:

试验在所有已完成的试验中具有最佳目标值。

引发:

KeyError – 如果不存在匹配 study_id 的试验。
RuntimeError – 如果试验具有多个方向。
ValueError – 如果没有已完成的试验。

返回类型:

FrozenTrial

get_n_trials(study_id, state=None)

计算试验中的试验数量。

参数:

study_id (int) – 试验的 ID。
state (tuple[TrialState, ...] | TrialState | None) – 要过滤的试验状态。如果为 None，则包含所有状态。

返回:

试验中的试验数量。

引发:

KeyError – 如果不存在匹配 study_id 的试验。

返回类型:

int

get_study_directions(study_id)[源代码]

读取试验是最大化还是最小化目标。

参数:: study_id (int) – 试验的 ID。
返回:: 试验的优化方向列表。
引发:: KeyError – 如果不存在匹配 study_id 的试验。
返回类型:: list[StudyDirection]

get_study_id_from_name(study_name)[源代码]

读取试验的 ID。

参数:: study_name (str) – 试验的名称。
返回:: 试验的 ID。
引发:: KeyError – 如果不存在匹配 study_name 的试验。
返回类型:: int

get_study_name_from_id(study_id)[源代码]

读取试验的试验名称。

参数:: study_id (int) – 试验的 ID。
返回:: 试验的名称。
引发:: KeyError – 如果不存在匹配 study_id 的试验。
返回类型:: str

get_study_system_attrs(study_id)[源代码]

读取试验的 optuna 内部属性。

参数:: study_id (int) – 试验的 ID。
返回:: 包含试验 optuna 内部属性的字典。
引发:: KeyError – 如果不存在匹配 study_id 的试验。
返回类型:: dict[str, Any]

get_study_user_attrs(study_id)[源代码]

读取试验的用户定义属性。

参数:: study_id (int) – 试验的 ID。
返回:: 包含试验用户属性的字典。
引发:: KeyError – 如果不存在匹配 study_id 的试验。
返回类型:: dict[str, Any]

get_trial(trial_id)[源代码]

读取一个试验。

参数:: trial_id (int) – 试验的 ID。
返回:: 具有匹配试验 ID 的试验。
引发:: KeyError – 如果不存在匹配 trial_id 的试验。
返回类型:: FrozenTrial

get_trial_id_from_study_id_trial_number(study_id, trial_number)[源代码]

读取试验的试验 ID。

参数:

study_id (int) – 试验的 ID。
trial_number (int) – 试验的编号。

返回:

试验的 ID。

引发:

KeyError – 如果不存在匹配 study_id 和 trial_number 的试验。

返回类型:

int

get_trial_number_from_id(trial_id)

读取试验的试验编号。

注意

试验编号仅在试验内部是唯一的，并且是顺序的。

参数:: trial_id (int) – 试验的 ID。
返回:: 试验的编号。
引发:: KeyError – 如果不存在匹配 trial_id 的试验。
返回类型:: int

get_trial_param(trial_id, param_name)

读取试验的参数。

参数:

trial_id (int) – 试验的 ID。
param_name (str) – 参数的名称。

返回:

参数的内部表示。

引发:

KeyError – 如果不存在匹配 trial_id 的试验。如果不存在该参数。

返回类型:

float

get_trial_params(trial_id)

读取试验的参数字典。

参数:: trial_id (int) – 试验的 ID。
返回:: 参数字典。键是参数名称，值是参数值的外部表示。
引发:: KeyError – 如果不存在匹配 trial_id 的试验。
返回类型:: dict[str, Any]

get_trial_system_attrs(trial_id)

读取试验的 optuna 内部属性。

参数:: trial_id (int) – 试验的 ID。
返回:: 包含试验 optuna 内部属性的字典。
引发:: KeyError – 如果不存在匹配 trial_id 的试验。
返回类型:: dict[str, Any]

get_trial_user_attrs(trial_id)

读取试验的用户定义属性。

参数:: trial_id (int) – 试验的 ID。
返回:: 包含试验用户定义属性的字典。
引发:: KeyError – 如果不存在匹配 trial_id 的试验。
返回类型:: dict[str, Any]

remove_session()

清理到数据库的所有连接。

返回类型:: 无

set_study_system_attr(study_id, key, value)[源代码]

向试验注册一个 optuna 内部属性。

此方法将覆盖任何现有属性。

参数:

study_id (int) – 试验的 ID。
key (str) – 属性键。
value (Mapping[str, JSONSerializable] | Sequence[JSONSerializable] | str | int | float | bool | None) – 属性值。它应该是 JSON 可序列化的。

引发:

KeyError – 如果不存在匹配 study_id 的试验。

返回类型:

无

set_study_user_attr(study_id, key, value)[源代码]

向试验注册一个用户定义的属性。

此方法将覆盖任何现有属性。

参数:

study_id (int) – 试验的 ID。
key (str) – 属性键。
value (Any) – 属性值。它应该是 JSON 可序列化的。

引发:

KeyError – 如果不存在匹配 study_id 的试验。

返回类型:

无

set_trial_intermediate_value(trial_id, step, intermediate_value)[源代码]

报告目标函数的中间值。

此方法将覆盖与给定步长关联的任何现有中间值。

参数:

trial_id (int) – 试验的 ID。
step (int) – 试验的步长（例如，训练神经网络时的周期）。
intermediate_value (float) – 与步长对应的中间值。

引发:

KeyError – 如果不存在匹配 trial_id 的试验。
UpdateFinishedTrialError – 如果试验已完成。

返回类型:

无

set_trial_param(trial_id, param_name, param_value_internal, distribution)[源代码]

为试验设置一个参数。

参数:

trial_id (int) – 试验的 ID。
param_name (str) – 参数的名称。
param_value_internal (float) – 参数值的内部表示。
distribution (BaseDistribution) – 参数的采样分布。

引发:

KeyError – 如果不存在匹配 trial_id 的试验。
UpdateFinishedTrialError – 如果试验已完成。

返回类型:

无

set_trial_state_values(trial_id, state, values=None)[源代码]

更新试验的状态和值。

将目标函数的返回值设置为 values 参数。如果 values 参数不是 None，此方法将覆盖任何现有试验值。

参数:

trial_id (int) – 试验的 ID。
state (TrialState) – 试验的新状态。
values (Sequence[float] | None) – 目标函数的返回值。

返回:

如果状态已成功更新，则返回 True。如果状态保持不变，则返回 False。后者发生在当此方法尝试将 RUNNING 状态的 trial 更新为 RUNNING 状态时。

引发:

KeyError – 如果不存在匹配 trial_id 的试验。
UpdateFinishedTrialError – 如果试验已完成。

返回类型:

bool

set_trial_system_attr(trial_id, key, value)[源代码]

为试验设置一个 optuna 内部属性。

此方法将覆盖任何现有属性。

参数:

trial_id (int) – 试验的 ID。
key (str) – 属性键。
value (Mapping[str, JSONSerializable] | Sequence[JSONSerializable] | str | int | float | bool | None) – 属性值。它应该是 JSON 可序列化的。

引发:

KeyError – 如果不存在匹配 trial_id 的试验。
UpdateFinishedTrialError – 如果试验已完成。

返回类型:

无

set_trial_user_attr(trial_id, key, value)[源代码]

为试验设置一个用户定义的属性。

此方法将覆盖任何现有属性。

参数:

trial_id (int) – 试验的 ID。
key (str) – 属性键。
value (Any) – 属性值。它应该是 JSON 可序列化的。

引发:

KeyError – 如果不存在匹配 trial_id 的试验。
UpdateFinishedTrialError – 如果试验已完成。

返回类型:

无