optuna.artifacts

artifacts モジュールは、Optuna におけるアーティファクト（出力ファイル）の管理方法を提供します。 Optuna Artifacts チュートリアルおよび当社の記事も参照してください。 artifacts がサポートするストレージは以下の通りです：

クラス名	対応ストレージ
FileSystemArtifactStore	ローカルファイルシステム、ネットワークファイルシステム
Boto3ArtifactStore	Amazon S3 互換オブジェクトストレージ
GCSArtifactStore	Google Cloud Storage

Note

各 ArtifactStore で定義されているメソッドは、ライブラリ利用者が直接アクセスすることを想定していません。

Note

ArtifactStore はアーティファクト削除用の公式 API を提供していないため、スタディにアップロードされたすべてのアーティファクトを削除するにはどうすればよいですか？を参照してください。

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

ファイルシステム用のアーティファクトストア。

Parameters:: 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 用のアーティファクトバックエンドです。

Parameters:

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) 用のアーティファクトバックエンド。

Parameters:

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ライブラリが自動的に認証情報を取得できるようになります。

Note

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

Parameters:

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

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

アーティファクトのメタ情報

Note

スタディやトライアルに関連付けられたすべてのアーティファクトメタ情報は get_all_artifact_meta() で一覧表示できます。アーティファクトメタ情報は download_artifact() で使用できます。

Parameters:

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]

アーティファクトをアーティファクトストアにアップロードします。

Parameters:

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 タイプ。指定しない場合、ファイル拡張子から推測されます
encoding (str | None) – アーティファクトのエンコーディング (Content-Encoding ヘッダーとして使用可能なもの、例: gzip)。指定しない場合、ファイル拡張子から推測されます

Returns:

アーティファクト ID

Return type:

str

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

指定されたトライアルまたはスタディに関連するアーティファクト情報を一覧表示します。

Parameters:

study_or_trial (Trial | FrozenTrial | Study) – Trial オブジェクト、FrozenTrial オブジェクト、または Study オブジェクトを指定します。
storage (BaseStorage | None) – ストレージオブジェクト。 study_or_trial が FrozenTrial の場合のみ必須です。

Return type:

list[ArtifactMeta]

使用例

この関数の使用例:

import os

import optuna


# 対象スタディが格納されているストレージを取得します。
storage = optuna.storages.get_storage(storage=...)

# スタディで使用するアーティファクトストアを初期化します。
# アーティファクトストアの情報は Optuna 側で管理されないため、
# ユーザー側で管理してください。
artifact_store = ...

# 対象アーティファクトを含むスタディを読み込みます。
study = optuna.load_study(study_name=..., storage=storage)

# 最良のトライアルを取得します。
best_trial = study.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_file_path`` にダウンロードします。
    optuna.artifacts.download_artifact(
        artifact_store=artifact_store,
        artifact_id=artifact_meta.artifact_id,
        file_path=download_file_path,
    )

Returns:

トライアルまたはスタディ内のアーティファクトメタのリスト。各アーティファクトメタには artifact_id、filename、mimetype、encoding が含まれます。 Study が指定された場合、スタディにアップロードされたアーティファクトの情報が返されますが、スタディ内のすべてのトライアルの情報が返されるわけではありません。

Parameters:

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

Return type:

list[ArtifactMeta]

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

アーティファクトストアからアーティファクトをダウンロードします。

Parameters:

artifact_store (ArtifactStore) – アーティファクトストア
file_path (str) – ダウンロードしたアーティファクトを保存するパス
artifact_id (str) – ダウンロードするアーティファクトの識別子

Return type:

None