optuna.storages.GrpcStorageProxy

class optuna.storages.GrpcStorageProxy(*, host='localhost', port=13000)[source]

run_grpc_proxy_server() 的 gRPC 客户端。

示例

这是一个使用 GrpcStorageProxy 和 run_grpc_proxy_server() 的简单示例。

import optuna
from optuna.storages import GrpcStorageProxy

storage = GrpcStorageProxy(host="localhost", port=13000)
study = optuna.create_study(storage=storage)

服务器端代码请参考 run_grpc_proxy_server() 中的示例。

参数：

  • host (str) – gRPC 服务器的主机名。

  • port (int) – gRPC 服务器的端口。

警告

当前，gRPC 存储代理与 SQLite3 数据库结合使用时，在调用 optuna.delete_study() 时可能会由于非失效缓存导致意外行为。

注意

在 v4.2.0 中作为实验性功能添加。接口在未来版本中可能会更改，恕不另行通知。参见 https://github.com/optuna/optuna/releases/tag/v4.2.0。

方法

check_trial_is_updatable(trial_id, trial_state)

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

close()

关闭 gRPC 通道。

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()

清理数据库的所有连接。

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])

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

set_trial_system_attr(trial_id, key, value)

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

set_trial_user_attr(trial_id, key, value)

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

wait_server_ready([timeout])

等待 gRPC 服务器准备就绪。
check_trial_is_updatable(trial_id, trial_state)

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

参数：

  • trial_id (int) – 试验的 ID。仅用于错误消息。

  • trial_state (TrialState) – 要检查的试验状态。

引发：

UpdateFinishedTrialError – 如果试验已完成。

返回类型：

None

close()[source]

关闭 gRPC 通道。

返回类型：

None

create_new_study(directions, study_name=None)[source]

通过名称创建一个新的研究。

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

参数：
返回：

创建的研究的 ID。

引发：

optuna.exceptions.DuplicatedStudyError – 如果已存在同名 study_name 的研究。

返回类型：

int

create_new_trial(study_id, template_trial=None)[source]

创建并添加一个新试验到研究中。

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

参数：

  • study_id (int) – 研究的 ID。

  • template_trial (FrozenTrial | None) – 带有默认用户属性、系统属性、中间值和状态的 FrozenTrial 模板。

返回：

创建的试验的 ID。

引发：

KeyError – 如果不存在匹配 study_id 的研究。

返回类型：

int

delete_study(study_id)[source]

删除一个研究。

参数：

study_id (int) – 研究的 ID。

引发：

KeyError – 如果不存在匹配 study_id 的研究。

返回类型：

None

get_all_studies()[source]

读取 FrozenStudy 对象的列表。

返回：

按 study_id 排序的 FrozenStudy 对象列表。

返回类型：

list[FrozenStudy]

get_all_trials(study_id, deepcopy=True, states=None)[source]

读取研究中的所有试验。

参数：

  • 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)[source]

读取研究是最大化还是最小化一个目标。

参数：

study_id (int) – 研究的 ID。

返回：

研究的优化方向列表。

引发：

KeyError – 如果不存在匹配 study_id 的研究。

返回类型：

list[StudyDirection]

get_study_id_from_name(study_name)[source]

读取研究的 ID。

参数：

study_name (str) – 研究的名称。

返回：

研究的 ID。

引发：

KeyError – 如果不存在匹配 study_name 的研究。

返回类型：

int

get_study_name_from_id(study_id)[source]

读取研究的名称。

参数：

study_id (int) – 研究的 ID。

返回：

研究的名称。

引发：

KeyError – 如果不存在匹配 study_id 的研究。

返回类型：

str

get_study_system_attrs(study_id)[source]

读取研究的 optuna-内部属性。

参数：

study_id (int) – 研究的 ID。

返回：

包含研究 optuna-内部属性的字典。

引发：

KeyError – 如果不存在匹配 study_id 的研究。

返回类型：

dict[str, Any]

get_study_user_attrs(study_id)[source]

读取研究的用户定义属性。

参数：

study_id (int) – 研究的 ID。

返回：

包含研究用户属性的字典。

引发：

KeyError – 如果不存在匹配 study_id 的研究。

返回类型：

dict[str, Any]

get_trial(trial_id)[source]

读取一个试验。

参数：

trial_id (int) – 试验的 ID。

返回：

具有匹配试验 ID 的试验。

引发：

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

返回类型：

FrozenTrial

get_trial_id_from_study_id_trial_number(study_id, trial_number)[source]

读取试验的 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()

清理数据库的所有连接。

返回类型：

None

set_study_system_attr(study_id, key, value)[source]

为研究注册一个 optuna-内部属性。

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

参数：

  • study_id (int) – 研究的 ID。

  • key (str) – 属性键。

  • value (Any) – 属性值。它应该是 JSON 可序列化的。

引发：

KeyError – 如果不存在匹配 study_id 的研究。

返回类型：

None

set_study_user_attr(study_id, key, value)[source]

为研究注册一个用户定义属性。

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

参数：

  • study_id (int) – 研究的 ID。

  • key (str) – 属性键。

  • value (Any) – 属性值。它应该是 JSON 可序列化的。

引发：

KeyError – 如果不存在匹配 study_id 的研究。

返回类型：

None

set_trial_intermediate_value(trial_id, step, intermediate_value)[source]

报告目标函数的中间值。

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

参数：

  • trial_id (int) – 试验的 ID。

  • step (int) – 试验的步骤（例如，训练神经网络时的 epoch）。

  • intermediate_value (float) – 对应于步骤的中间值。

引发：
返回类型：

None

set_trial_param(trial_id, param_name, param_value_internal, distribution)[source]

为试验设置一个参数。

参数：

  • trial_id (int) – 试验的 ID。

  • param_name (str) – 参数的名称。

  • param_value_internal (float) – 参数值的内部表示。

  • distribution (BaseDistribution) – 参数的采样分布。

引发：
返回类型：

None

set_trial_state_values(trial_id, state, values=None)[source]

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

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

参数：

  • trial_id (int) – 试验的 ID。

  • state (TrialState) – 试验的新状态。

  • values (Sequence[float] | None) – 目标函数的值。

返回：

如果状态成功更新，则为 True。如果状态保持不变，则为 False。后一种情况发生在此方法尝试将 RUNNING 试验的状态更新为 RUNNING 时。

引发：
返回类型：

bool

set_trial_system_attr(trial_id, key, value)[source]

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

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

参数：

  • trial_id (int) – 试验的 ID。

  • key (str) – 属性键。

  • value (Any) – 属性值。它应该是 JSON 可序列化的。

引发：
返回类型：

None

set_trial_user_attr(trial_id, key, value)[source]

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

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

参数：

  • trial_id (int) – 试验的 ID。

  • key (str) – 属性键。

  • value (Any) – 属性值。它应该是 JSON 可序列化的。

引发：
返回类型：

None

wait_server_ready(timeout=None)[source]

等待 gRPC 服务器准备就绪。

参数：

timeout (float | None) – 最大等待时间（秒）。如果为 None，则无限期等待。

返回类型：

None