optuna.artifacts

该 artifacts 模块提供了管理 Optuna 中工件（输出文件）的方式。请同时参阅 Optuna 工件教程和我们的文章。该 artifacts 模块涵盖的存储包括：

类名	支持的存储
FileSystemArtifactStore	本地文件系统、网络文件系统
Boto3ArtifactStore	Amazon S3 兼容对象存储
GCSArtifactStore	Google Cloud Storage

注意

每个 ArtifactStore 中定义的方法不打算被库用户直接访问。

注意

由于 ArtifactStore 没有正式提供删除工件的用户 API，请参考如何删除上传到 study 的所有工件？来进行处理。

class optuna.artifacts.FileSystemArtifactStore(base_path)[source]

用于文件系统的工件存储。

参数:: base_path (str | Path) – 用于存储工件的目录的基路径。

示例

import os

import optuna
from optuna.artifacts import FileSystemArtifactStore
from optuna.artifacts import upload_artifact


base_path = "./artifacts"
os.makedirs(base_path, exist_ok=True)
artifact_store = FileSystemArtifactStore(base_path=base_path)


def objective(trial: optuna.Trial) -> float:
    ... = trial.suggest_float("x", -10, 10)
    file_path = generate_example(...)
    upload_artifact(
        artifact_store=artifact_store,
        file_path=file_path,
        study_or_trial=trial,
    )
    return ...

class optuna.artifacts.Boto3ArtifactStore(bucket_name, client=None, *, avoid_buf_copy=False)[source]

Boto3 的工件后端。

参数:

bucket_name (str) – 用于存储工件的存储桶名称。
client (S3Client | None) – 用于存储操作的 Boto3 客户端。如果未指定，将创建一个新客户端。
avoid_buf_copy (bool) – 如果为 True，则跳过将源文件对象的内容复制到缓冲区再上传到 S3 的过程。默认值为 False，因为使用 Boto3 客户端的 upload_fileobj() 方法可能会关闭源文件对象。

示例

import optuna
from optuna.artifacts import upload_artifact
from optuna.artifacts import Boto3ArtifactStore


artifact_store = Boto3ArtifactStore("my-bucket")


def objective(trial: optuna.Trial) -> float:
    ... = trial.suggest_float("x", -10, 10)
    file_path = generate_example(...)
    upload_artifact(
        artifact_store=artifact_store,
        file_path=file_path,
        study_or_trial=trial,
    )
    return ...

class optuna.artifacts.GCSArtifactStore(bucket_name, client=None)[source]

Google Cloud Storage (GCS) 的工件后端。

参数:

bucket_name (str) – 用于存储工件的存储桶名称。
client (google.cloud.storage.Client | None) – 用于存储操作的 google-cloud-storage Client。如果未指定，将使用默认设置创建一个新客户端。

示例

import optuna
from optuna.artifacts import GCSArtifactStore, upload_artifact


artifact_backend = GCSArtifactStore("my-bucket")


def objective(trial: optuna.Trial) -> float:
    ... = trial.suggest_float("x", -10, 10)
    file_path = generate_example(...)
    upload_artifact(
        artifact_store=artifact_store,
        file_path=file_path,
        study_or_trial=trial,
    )
    return ...

在运行此代码之前，您需要安装 gcloud 并运行

gcloud auth application-default login

以便 Cloud Storage 库可以自动找到凭据。

注意

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

class optuna.artifacts.Backoff(backend, *, max_retries=10, multiplier=2, min_delay=0.1, max_delay=30)[source]

工件存储的指数退避中间件。

示例

import optuna
from optuna.artifacts import upload_artifact
from optuna.artifacts import Boto3ArtifactStore
from optuna.artifacts import Backoff


artifact_store = Backoff(Boto3ArtifactStore("my-bucket"))


def objective(trial: optuna.Trial) -> float:
    ... = trial.suggest_float("x", -10, 10)
    file_path = generate_example(...)
    upload_artifact(
        artifact_store=artifact_store,
        file_path=file_path,
        study_or_trial=trial,
    )
    return ...

参数:

backend (ArtifactStore)
max_retries (int)
multiplier (float)
min_delay (float)
max_delay (float)

class optuna.artifacts.ArtifactMeta(artifact_id, filename, mimetype, encoding)[source]

工件的元信息。

注意

可以通过 get_all_artifact_meta() 列出与 study 或 trial 相关的所有工件元信息。工件元信息可用于 download_artifact()。

参数:

artifact_id (str) – 工件的标识符。
filename (str) – 上传时使用的工件文件名。
mimetype (str) – 工件的 MIME 类型。如果未指定，将从文件扩展名猜测 MIME 类型。
encoding (str | None) – 工件的编码，适用于作为 Content-Encoding 头部，例如 gzip。如果未指定，将从文件扩展名猜测编码。

optuna.artifacts.upload_artifact(*, artifact_store, file_path, study_or_trial, storage=None, mimetype=None, encoding=None)[source]

将工件上传到工件存储。

参数:

artifact_store (ArtifactStore) – 工件存储。
file_path (str) – 要上传的文件的路径。
study_or_trial (Trial | FrozenTrial | Study) – 一个 Trial 对象、一个 FrozenTrial，或者一个 Study 对象。
storage (BaseStorage | None) – 存储对象。仅当 study_or_trial 为 FrozenTrial 时才需要此参数。
mimetype (str | None) – 工件的 MIME 类型。如果未指定，将从文件扩展名猜测 MIME 类型。
encoding (str | None) – 工件的编码，适用于作为 Content-Encoding 头部（例如 gzip）。如果未指定，将从文件扩展名猜测编码。

返回:

工件 ID。

返回类型:

str

optuna.artifacts.get_all_artifact_meta(study_or_trial, *, storage=None)[source]

列出提供的 trial 或 study 的关联工件信息。

参数:

study_or_trial (Trial | FrozenTrial | Study) – 一个 Trial 对象、一个 FrozenTrial，或者一个 Study 对象。
storage (BaseStorage | None) – 存储对象。仅当 study_or_trial 为 FrozenTrial 时才需要此参数。

返回类型:

list[ArtifactMeta]

示例

此函数有用的示例

import os

import optuna


# Get the storage that contains the study of interest.
storage = optuna.storages.get_storage(storage=...)

# Instantiate the artifact store used for the study.
# Optuna does not provide the API that stores the used artifact store information, so
# please manage the information in the user side.
artifact_store = ...

# Load study that contains the artifacts of interest.
study = optuna.load_study(study_name=..., storage=storage)

# Fetch the best trial.
best_trial = study.best_trial

# Fetch all the artifact meta connected to the best trial.
artifact_metas = optuna.artifacts.get_all_artifact_meta(best_trial, storage=storage)

download_dir_path = "./best_trial_artifacts/"
os.makedirs(download_dir_path, exist_ok=True)

for artifact_meta in artifact_metas:
    download_file_path = os.path.join(download_dir_path, artifact_meta.filename)
    # Download the artifacts to ``download_file_path``.
    optuna.artifacts.download_artifact(
        artifact_store=artifact_store,
        artifact_id=artifact_meta.artifact_id,
        file_path=download_file_path,
    )

返回:

Trial 或 study 中的工件元信息列表。每个工件元信息包含 artifact_id、filename、mimetype 和 encoding。请注意，如果提供了 Study，我们将返回上传到 study（而不是 study 中所有 trial）的工件信息。

参数:

study_or_trial (Trial | FrozenTrial | Study)
storage (BaseStorage | None)

返回类型:

list[ArtifactMeta]

optuna.artifacts.download_artifact(*, artifact_store, file_path, artifact_id)[source]

从工件存储下载工件。

参数:

artifact_store (ArtifactStore) – 工件存储。
file_path (str) – 保存下载的工件的路径。
artifact_id (str) – 要下载的工件的标识符。

返回类型:

无