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]

制品的元信息。

注意

所有链接到 Study 或 Trial 的制品元信息可以通过 get_all_artifact_meta() 列出。制品元信息可用于 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 的相关制品信息。

参数:
返回类型:

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 的制品信息。

参数:
返回类型:

list[ArtifactMeta]

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

从制品存储后端下载制品。

参数:

  • artifact_store (ArtifactStore) – 制品存储后端。

  • file_path (str) – 保存下载的制品的文件路径。

  • artifact_id (str) – 要下载的制品的标识符。

返回类型:

None