optuna.artifacts

The artifacts 模块提供了在 Optuna 中管理工件（输出文件）的方法。请同时查看 Optuna 工件教程和我们的文章。artifacts 涵盖的存储如下：

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

备注

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

备注

由于 ArtifactStore 官方未提供用于删除工件的用户API，请参考如何删除上传到研究中的所有工件？获取相关技巧。

class optuna.artifacts.FileSystemArtifactStore(base_path)[源代码]

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

参数:: 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)[源代码]

一个用于 Boto3 的工件后端。

参数:

bucket_name (str) – 存储工件的桶的名称。
client (S3Client | None) – 用于存储操作的 Boto3 客户端。如果未指定，将创建一个新的客户端。
avoid_buf_copy (bool) – 如果为真，跳过将源文件对象内容复制到缓冲区再上传到S3实例的过程。这是默认设置为假，因为使用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)[源代码]

Google Cloud Storage (GCS) 的制品后端。

参数:

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

示例

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)[源代码]

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

示例

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)[源代码]

工件的元信息。

备注

所有与研究或试验关联的工件元数据可以通过 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)[源代码]

将工件上传到工件存储。

参数:

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)[源代码]

列出所提供试验或研究的关联工件信息。

参数:

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

返回:

试验或研究中的工件元数据列表。每个工件元数据包括 artifact_id、filename、mimetype 和 encoding。请注意，如果提供了 Study，我们返回上传到 study 的工件信息，而不是研究中所有试验的工件信息。

参数:

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

返回类型:

list[ArtifactMeta]

optuna.artifacts.download_artifact(*, artifact_store, file_path, artifact_id)[源代码]

从制品库中下载一个制品。

参数:

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

返回类型:

None