optuna.artifacts

The artifacts module provides the way to manage artifacts (output files) in Optuna. Please note that methods defined in each ArtifactStore are not intended to be directly accessed by library users.

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. This argument is required only if study_or_trial is FrozenTrial.

  • 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.

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

List the associated artifact information of the provided trial or study.

Parameters:
Returns:

The list of artifact meta in the trial or study. Each artifact meta includes artifact_id, filename, mimetype, and encoding. Note that If Study is provided, we return the information of the artifacts uploaded to study, but not to all the trials in the study.

Return type:

list[ArtifactMeta]

Note

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

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

Download an artifact from the artifact store.

Parameters:
  • artifact_store (ArtifactStore) – An artifact store.

  • artifact_id (str) – The identifier of the artifact to download.

  • file_path (str) – A path to save the downloaded artifact.

Return type:

None

Note

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