optuna.artifacts

The artifacts module provides the way to manage artifacts (output files) in Optuna.

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

An artifact store for file systems.

Parameters:: base_path (str | Path) – The base path to a directory to store artifacts.

Example

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(trial, file_path, artifact_store)
    return ...

Note

Added in v3.3.0 as an experimental feature. The interface may change in newer versions without prior notice. See https://github.com/optuna/optuna/releases/tag/v3.3.0.

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

An artifact backend for Boto3.

Parameters:

bucket_name (str) – The name of the bucket to store artifacts.
client (S3Client | None) – A Boto3 client to use for storage operations. If not specified, a new client will be created.
avoid_buf_copy (bool) – If True, skip procedure to copy the content of the source file object to a buffer before uploading it to S3 ins. This is default to False because using upload_fileobj() method of Boto3 client might close the source file object.

Example

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(trial, file_path, artifact_store)
    return ...

Note

Added in v3.3.0 as an experimental feature. The interface may change in newer versions without prior notice. See https://github.com/optuna/optuna/releases/tag/v3.3.0.

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

An artifact backend for Google Cloud Storage (GCS).

Parameters:

bucket_name (str) – The name of the bucket to store artifacts.
client (google.cloud.storage.Client | None) – A google-cloud-storage Client to use for storage operations. If not specified, a new client will be created with default settings.

Example

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(trial, file_path, artifact_backend)
    return ...

Before running this code, you will have to install gcloud and run

gcloud auth application-default login

so that the Cloud Storage library can automatically find the credential.

Note

Added in v3.4.0 as an experimental feature. The interface may change in newer versions without prior notice. See 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]

An artifact store’s middleware for exponential backoff.

Example

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(trial, file_path, artifact_store)
    return ...

Parameters:

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

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

Upload an artifact to the artifact store.

Parameters:

study_or_trial (Trial | FrozenTrial | Study) – A Trial object, a FrozenTrial, or a Study object.
file_path (str) – A path to the file to be uploaded.
artifact_store (ArtifactStore) – An artifact store.
storage (BaseStorage | None) – A storage object. If trial is not a Trial object, this argument is required.
mimetype (str | None) – A MIME type of the artifact. If not specified, the MIME type is guessed from the file extension.
encoding (str | None) – An encoding of the artifact, which is suitable for use as a Content-Encoding header (e.g. gzip). If not specified, the encoding is guessed from the file extension.

Returns:

An artifact ID.

Return type:

str

Note

Added in v3.3.0 as an experimental feature. The interface may change in newer versions without prior notice. See https://github.com/optuna/optuna/releases/tag/v3.3.0.