データのインポートとエクスポート

MLFlow からデータをインポートし、W&B に保存したデータをエクスポートまたは更新する

W&B Public API を使用して、データをエクスポートまたはインポートします。

この機能を使用するには python>=3.8 が必要です

​

MLFlow からデータをインポートする

W&B では、Experiments、Runs、アーティファクト、メトリクス、その他のメタデータなど、MLFlow のデータをインポートできます。

依存関係をインストールします:

# 注意: py38以上が必要です
pip install wandb[importers]

W&B にログインします。初めてログインする場合は、表示される案内に従ってください。

wandb login

既存のMLFlowサーバーから、すべてのrunをインポートします：

from wandb.apis.importers.mlflow import MlflowImporter

importer = MlflowImporter(mlflow_tracking_uri="...")

runs = importer.collect_runs()
importer.import_runs(runs)

デフォルトでは、importer.collect_runs() は MLFlow サーバー上のすべての run を収集します。特定のサブセットだけを upload したい場合は、独自の run の iterable を作成して importer に渡すこともできます。

import mlflow
from wandb.apis.importers.mlflow import MlflowRun

client = mlflow.tracking.MlflowClient(mlflow_tracking_uri)

runs: Iterable[MlflowRun] = []
for run in mlflow_client.search_runs(...):
    runs.append(MlflowRun(run, client))

importer.import_runs(runs)

Databricks MLflow からインポートする場合は、最初に Databricks CLI を設定する必要があることがあります。

前の手順で mlflow-tracking-uri="databricks" を設定してください。

アーティファクトのインポートをスキップするには、artifacts=False を渡します。

importer.import_runs(runs, artifacts=False)

特定の W&B entity と project にインポートするには、Namespace を渡します:

from wandb.apis.importers import Namespace

importer.import_runs(runs, namespace=Namespace(entity, project))

​

データをエクスポートする

Public API を使用して、W&B に保存したデータをエクスポートまたは更新できます。この API を使用する前に、スクリプトからデータをログしてください。詳細は クイックスタート を参照してください。

Public API のユースケース

• データをエクスポートする: Jupyter Notebook でカスタム分析を行うために、データフレーム を取得します。データを分析したら、新しい分析 run を作成して結果をログすることで、分析結果を Sync できます。例: wandb.init(job_type="analysis")
• 既存の Runs を更新する: W&B run に関連付けられてログされたデータを更新できます。たとえば、一連の Runs の設定を更新して、アーキテクチャや、元はログされていなかったハイパーパラメーターなどの追加情報を含めることができます。

利用可能な関数の詳細は、Generated Reference Docs を参照してください。

​

APIキーを作成する

APIキーは、マシンをW&Bに認証するために使用します。

APIキーを作成するには、Personal API key または Service Account API key タブを選択して詳細を確認してください。

Personal API key

あなたのユーザー ID に紐づく個人用 APIキーを作成するには、次の手順に従います。

1. W&B にログインし、ユーザープロフィールアイコン > User Settings をクリックします。
2. Create new API key をクリックします。
3. APIキーにわかりやすい名を付けます。
4. Create をクリックします。
5. 表示された APIキーをすぐにコピーし、安全な場所に保管してください。

Service account API key

サービスアカウントに紐づくAPIキーを作成するには、次の手順に従います。

1. チームまたは組織の設定で、Service Accounts タブに移動します。
2. 一覧からサービスアカウントを検索します。
3. action () メニューをクリックし、Create API key をクリックします。
4. APIキーの名を入力し、Create をクリックします。
5. 表示されたAPIキーをすぐにコピーして、安全な場所に保管します。
6. Done をクリックします。

異なる環境やワークフローに対応するため、1つのサービスアカウントに対して複数のAPIキーを作成できます。

W&B がAPIキー全体を表示するのは、作成時の一度だけです。ダイアログを閉じた後は、APIキー全体を再度表示できません。Settings に表示されるのはキーID (キーの先頭部分) のみです。APIキー全体を紛失した場合は、新しいAPIキーを作成する必要があります。

安全な保管方法については、APIキーを安全に保管するを参照してください。

​

APIキーを安全に保管・管理する

APIキーを使うとW&Bアカウントにアクセスできるため、パスワードと同様に厳重に保護する必要があります。以下のセクションでは、推奨される保管方法、避けるべき運用、コードにキーを渡す方法、新しいキーに必要なSDKバージョン要件について説明します。

​

推奨される保管方法

次のいずれかの方法を使用して、APIキーを安全に保管してください。

• シークレットマネージャー: AWS Secrets Manager、HashiCorp Vault、Azure Key Vault、Google Secret Manager などの専用のシークレット管理システムを使用してください。
• パスワードマネージャー: 信頼できるパスワードマネージャーアプリを使用してください。
• OS レベルのキーチェーン: macOS Keychain、Windows Credential Manager、または Linux Secret Service にキーを保存します。本番環境での使用は推奨されません。

​

避けるべきこと

次のような行為は APIキーの漏えいにつながるおそれがあるため、避けてください。

• APIキーを Git などのバージョン管理システムにコミットしないでください。
• APIキーを平文の設定ファイルに保存しないでください。
• APIキーをコマンドライン引数として渡さないでください。ps のような OS コマンドの出力に表示されるためです。
• APIキーをメール、チャット、その他の暗号化されていないチャネルで共有しないでください。
• APIキーをソースコードにハードコードしないでください。

APIキーが漏えいした場合は、ただちに W&B アカウントから該当の APIキーを削除し、サポート または担当の AISE に連絡してください。

​

環境変数

コード内でAPIキーを使用する場合は、環境変数経由で渡します。

export WANDB_API_KEY="[YOUR-API-KEY]"

この方法では、キーをソースコードに含めずに済み、必要に応じてローテーションしやすくなります。

ps などの OS コマンドの出力に表示される可能性があるため、環境変数を コマンド と同じ行で設定するのは避けてください。

# APIキーがプロセスマネージャーに露出するおそれがあるため、このパターンは避けてください
export WANDB_API_KEY="[YOUR-API-KEY]" ./my-script.sh

​

SDKのバージョン互換性

新しいAPIキーを使用する場合は、お使いのSDKバージョンがそのAPIキーをサポートしていることを確認してください。新しいAPIキーは、従来のキーより長くなっています。古いバージョンのwandbまたはweave SDKで認証すると、APIキーの長さに関するエラーが発生することがあります。

解決策: より新しいバージョンのSDKに更新してください。

• wandb SDK v0.22.3+

  pip install --upgrade wandb==0.22.3
  

• weave SDK v0.52.17+

  pip install --upgrade weave==0.52.17
  

すぐにSDKをアップグレードできない場合は、回避策としてWANDB_API_KEY環境変数でAPIキーを設定してください。

​

run パスを検索する

Public APIを使用するには、多くの場合、<entity>/<project>/<run_id> 形式の run パスが必要です。アプリのUIで run のページを開き、Overview タブ をクリックすると、run パスを確認できます。

​

run データをエクスポート

完了済みまたは実行中の run からデータをダウンロードします。一般的な用途としては、Jupyter Notebook で独自の分析を行うためにデータフレームをダウンロードしたり、自動化された環境で独自のロジックを使用したりすることが挙げられます。

import wandb

api = wandb.Api()
run = api.run("<entity>/<project>/<run_id>")

run オブジェクトで最もよく使用される属性は次のとおりです。

Attribute	Meaning
run.config	トレーニング run のハイパーパラメーターや、データセット Artifact を作成する run の前処理 method など、run の設定情報を格納した辞書です。これらは run の入力と考えてください。
run.history()	モデルのトレーニング中に変化する損失などの値を保存するための、辞書の list です。command run.log() はこの object に値を追加します。
run.summary	run の結果を要約した情報を格納する辞書です。accuracy や損失のようなスカラー値の場合もあれば、大きなファイルの場合もあります。デフォルトでは、run.log() はログした時系列の最終値を summary に設定します。summary の内容は直接設定することもできます。summary は run の出力と考えてください。

過去の run のデータを変更または更新することもできます。デフォルトでは、api object の単一インスタンスがすべてのネットワーク request をキャッシュします。実行中のスクリプトでリアルタイムの情報が必要な場合は、api.flush() を呼び出して更新された値を取得してください。

​

さまざまなrunの属性を理解する

次のコードスニペットは、runを作成し、いくつかのデータをログした後、runの属性にアクセスする方法を示しています。

import wandb
import random

with wandb.init(project="public-api-example") as run:
    n_epochs = 5
    config = {"n_epochs": n_epochs}
    run.config.update(config)
    for n in range(run.config.get("n_epochs")):
        run.log(
            {"val": random.randint(0, 1000), "loss": (random.randint(0, 1000) / 1000.00)}
        )

以下のセクションでは、上記のrunオブジェクトの属性ごとのさまざまな出力について説明します

run.config

{"n_epochs": 5}

​

run.summary

{
    "_step": 4,
    "_timestamp": 1644345412,
    "_wandb": {"runtime": 3},
    "loss": 0.041,
    "val": 525,
}

​

サンプリング

デフォルトのhistory methodでは、メトリクスが固定数のサンプルにサンプリングされます (デフォルトは500で、samples __ 引数で変更できます) 。大規模なrunのすべてのデータをエクスポートする場合は、run.scan_history() methodを使用できます。詳細は、API Referenceを参照してください。

​

複数の Runs をクエリする

DataFrame と CSV

このスクリプト例では、project を検索し、名前、設定、summary 統計を含む Runs の CSV を出力します。<entity> と <project> は、それぞれお使いの W&B entity と project 名に置き換えてください。

import pandas as pd
import wandb

api = wandb.Api()
entity, project = "<entity>", "<project>"
runs = api.runs(entity + "/" + project)

summary_list, config_list, name_list = [], [], []
for run in runs:
    # .summary には、
    # accuracy などのメトリクスの出力キー/値が含まれます。
    # 大きなファイルを除外するために ._json_dict を呼び出します
    summary_list.append(run.summary._json_dict)

    # .config にはハイパーパラメーターが含まれます。
    # _ で始まる特殊な値は削除します。
    config_list.append({k: v for k, v in run.config.items() if not k.startswith("_")})

    # .name は run の人間が読める名前です。
    name_list.append(run.name)

runs_df = pd.DataFrame(
    {"summary": summary_list, "config": config_list, "name": name_list}
)

runs_df.to_csv("project.csv")

run.finish()

MongoDB スタイル

W&B API では、api.runs() を使って project 内の複数の Runs をまたいでクエリすることもできます。最も一般的な用途は、カスタム分析のために Runs データをエクスポートすることです。クエリインターフェースは、MongoDB が使用しているものと同じです。

runs = api.runs(
    "username/project",
    {"$or": [{"config.experiment_name": "foo"}, {"config.experiment_name": "bar"}]},
)
print(f"Found {len(runs)} runs")

api.runs を呼び出すと、反復可能でリストのように振る舞う Runs オブジェクトが返されます。デフォルトでは、このオブジェクトは必要に応じて一度に 50 件の Runs を順次読み込みますが、per_page キーワード引数で 1 ページあたりの読み込み件数を変更できます。

api.runs は order キーワード引数も受け取ります。デフォルトの並び順は -created_at です。結果を昇順にするには、+created_at を指定します。設定や summary の値でソートすることもできます。たとえば、summary.val_acc や config.experiment_name です。

​

エラー処理

W&B サーバーとの通信中にエラーが発生すると、wandb.CommError が送出されます。元の例外は exc 属性から確認できます。

​

API を使って最新の git コミットを取得する

UI で run をクリックし、続けて run ページの Overview タブをクリックすると、最新の git コミットを確認できます。これは wandb-metadata.json ファイルにも含まれています。Public API を使用すると、run.commit で git ハッシュを取得できます。

​

run の実行中に run 名と ID を取得する

wandb.init() を呼び出すと、スクリプトからランダムな run ID や人が読める run 名に次のようにアクセスできます。

• 一意の run ID (8 文字のハッシュ) : run.id
• ランダムな run 名 (人が読める名前) : run.name

run に役立つ識別子を設定する方法を検討している場合は、次の設定をおすすめします。

• Run ID: 生成されたハッシュのままにしてください。これはプロジェクト内のすべての run で一意である必要があります。
• Run name: 短く、わかりやすく、できれば一意なものにしてください。そうすることで、チャート上の異なる線を見分けやすくなります。
• Run notes: run で何をしているかを簡単に説明するのに最適です。wandb.init(notes="your notes here") で設定できます。
• Run tags: run tags で項目を動的にトラッキングし、UI のフィルターを使用して表を必要な run だけに絞り込めます。タグはスクリプトから設定でき、Runs table と run ページの Overview タブの両方で UI から編集できます。詳しい手順はこちらを参照してください。

​

Public APIの例

​

matplotlib または seaborn で可視化するためにデータをエクスポートする

一般的なエクスポート方法については、API examplesを参照してください。カスタムプロットまたは展開したRuns tableのダウンロードボタンをクリックすると、ブラウザからCSVをダウンロードすることもできます。

​

run のメトリクスを読み取る

この例では、"<entity>/<project>/<run_id>" に保存された run から、run.log({"accuracy": acc}) で保存したタイムスタンプと accuracy を出力します。

import wandb

api = wandb.Api()

run = api.run("<entity>/<project>/<run_id>")
if run.state == "finished":
    for i, row in run.history().iterrows():
        print(row["_timestamp"], row["accuracy"])

​

Runs をフィルタリングする

MongoDB Query Language を使用してフィルタリングできます。

​

日付

runs = api.runs(
    "<entity>/<project>",
    {"$and": [{"created_at": {"$lt": "YYYY-MM-DDT##", "$gt": "YYYY-MM-DDT##"}}]},
)

​

run から特定のメトリクスを読み取る

run から特定のメトリクスを取得するには、keys 引数を使用します。run.history() を使用する場合のデフォルトのサンプル数は 500 です。特定のメトリクスを含まないログ済みの step は、出力データフレームでは NaN として表示されます。keys 引数を指定すると、API は一覧にあるメトリクス key を含む step をより高い頻度でサンプリングします。

import wandb

api = wandb.Api()

run = api.run("<entity>/<project>/<run_id>")
if run.state == "finished":
    for i, row in run.history(keys=["accuracy"]).iterrows():
        print(row["_timestamp"], row["accuracy"])

​

2 つの run を比較する

これにより、run1 と run2 で異なる設定パラメーターが出力されます。

import pandas as pd
import wandb

api = wandb.Api()

# <entity>、<project>、<run_id> を実際の値に置き換えてください
run1 = api.run("<entity>/<project>/<run_id>")
run2 = api.run("<entity>/<project>/<run_id>")


df = pd.DataFrame([run1.config, run2.config]).transpose()

df.columns = [run1.name, run2.name]
print(df[df[run1.name] != df[run2.name]])

出力:

              c_10_sgd_0.025_0.01_long_switch base_adam_4_conv_2fc
batch_size                                 32                   16
n_conv_layers                               5                    4
optimizer                             rmsprop                 adam

​

完了した run のメトリクスを更新する

この例では、以前の run の精度を 0.9 に設定します。また、以前の run の精度ヒストグラムを numpy_array のヒストグラムに置き換えます。

import wandb

api = wandb.Api()

run = api.run("<entity>/<project>/<run_id>")
run.summary["accuracy"] = 0.9
run.summary["accuracy_histogram"] = wandb.Histogram(numpy_array)
run.summary.update()

​

完了したrun内のメトリクス名を変更する

この例では、表内のsummary列の名前を変更します。

import wandb

api = wandb.Api()

run = api.run("<entity>/<project>/<run_id>")
run.summary["new_name"] = run.summary["old_name"]
del run.summary["old_name"]
run.summary.update()

列名の変更が適用されるのは表のみです。チャートでは引き続き、メトリクスは元の名前で参照されます。

​

既存のrunの設定を更新する

この例では、設定項目の 1 つを更新します。

import wandb

api = wandb.Api()

run = api.run("<entity>/<project>/<run_id>")
run.config["key"] = updated_value
run.update()

​

システムリソースの使用量をCSVファイルにエクスポートする

以下のスニペットでは、システムリソースの使用量を検索し、その結果をCSVに保存します。

import wandb

with wandb.Api().run("<entity>/<project>/<run_id>") as run:

    system_metrics = run.history(stream="events")
    system_metrics.to_csv("sys_metrics.csv")

​

サンプリングされていないメトリクスデータを取得する

history からデータを取得する場合、デフォルトでは 500 ポイントにサンプリングされます。run.scan_history() を使用すると、ログされたすべてのデータポイントを取得できます。以下は、history にログされた loss の全データポイントをダウンロードする例です。

import wandb

api = wandb.Api()

run = api.run("<entity>/<project>/<run_id>")
history = run.scan_history()
losses = [row["loss"] for row in history]

​

history からページ単位でデータを取得する

バックエンドでのメトリクス取得が遅い場合や、API リクエストがタイムアウトする場合は、各リクエストがタイムアウトしないように、scan_history のページサイズを小さくしてみてください。デフォルトのページサイズは 500 なので、さまざまなサイズを試して、最も適した値を確認できます:

import wandb

api = wandb.Api()

run = api.run("<entity>/<project>/<run_id>")
run.scan_history(keys=sorted(cols), page_size=100)

​

プロジェクト内のすべての Runs のメトリクスを CSV ファイルにエクスポートする

このスクリプトはプロジェクト内の Runs を取得し、それらの名、設定、summary の統計を含む Runs のデータフレームと CSV を生成します。<entity> と <project> は、それぞれ W&B の entity とプロジェクトの名に置き換えてください。

import pandas as pd
import wandb

api = wandb.Api()
entity, project = "<entity>", "<project>"
runs = api.runs(entity + "/" + project)

summary_list, config_list, name_list = [], [], []
for run in runs:
    # .summary には出力のキーと値が含まれます
    #  たとえば accuracy などのメトリクスです。
    #  大きなファイルを除外するため、._json_dict を呼び出します
    summary_list.append(run.summary._json_dict)

    # .config にはハイパーパラメーターが含まれます。
    #  _ で始まる特殊な値は除外します。
    config_list.append({k: v for k, v in run.config.items() if not k.startswith("_")})

    # .name は run の人が読める名前です。
    name_list.append(run.name)

runs_df = pd.DataFrame(
    {"summary": summary_list, "config": config_list, "name": name_list}
)

runs_df.to_csv("project.csv")

​

run の開始時刻を取得する

このコード例では、run が作成された時刻を取得します。

import wandb

api = wandb.Api()

run = api.run("entity/project/run_id")
start_time = run.created_at

​

完了済みの run にファイルをアップロードする

以下のコードスニペットは、選択したファイルを完了済みの run にアップロードします。

import wandb

api = wandb.Api()

run = api.run("entity/project/run_id")
run.upload_file("file_name.extension")

​

run からファイルをダウンロードする

これは、cifar プロジェクトの run ID uxte44z7 に紐づくファイル “model-best.h5” を検索し、ローカルに保存します。

import wandb

api = wandb.Api()

run = api.run("<entity>/<project>/<run_id>")
run.file("model-best.h5").download()

​

run からすべてのファイルをダウンロードする

これにより、run に関連付けられたすべてのファイルを見つけてローカルに保存します。

import wandb

api = wandb.Api()

run = api.run("<entity>/<project>/<run_id>")
for file in run.files():
    file.download()

​

特定の sweep から run を取得する

このスニペットでは、特定の sweep に関連するすべての run をダウンロードします。

import wandb

api = wandb.Api()

sweep = api.sweep("<entity>/<project>/<sweep_id>")
sweep_runs = sweep.runs

​

sweep から最適な run を取得する

以下のスニペットは、指定した sweep から最適な run を取得します。

import wandb

api = wandb.Api()

sweep = api.sweep("<entity>/<project>/<sweep_id>")
best_run = sweep.best_run()

best_run は、sweep 設定の metric パラメーターで指定されたメトリクスが最も優れている run です。

​

sweep から最良のモデルファイルをダウンロードする

このスニペットでは、モデルファイルを model.h5 として保存した Runs を含む sweep から、検証精度が最も高いモデルファイルをダウンロードします。

import wandb

api = wandb.Api()

sweep = api.sweep("<entity>/<project>/<sweep_id>")
runs = sorted(sweep.runs, key=lambda run: run.summary.get("val_acc", 0), reverse=True)
val_acc = runs[0].summary.get("val_acc", 0)
print(f"Best run {runs[0].name} with {val_acc}% val accuracy")

runs[0].file("model.h5").download(replace=True)
print("Best model saved to model-best.h5")

​

run から指定した拡張子のファイルをすべて削除する

このスニペットでは、run から指定した拡張子のファイルをすべて削除します。

import wandb

api = wandb.Api()

run = api.run("<entity>/<project>/<run_id>")

extension = ".png"
files = run.files()
for file in files:
    if file.name.endswith(extension):
        file.delete()

​

システムメトリクスデータをダウンロードする

このスニペットは、run のシステムリソース消費に関するすべてのメトリクスを含むデータフレームを生成し、CSV に保存します。

import wandb

api = wandb.Api()

run = api.run("<entity>/<project>/<run_id>")
system_metrics = run.history(stream="events")
system_metrics.to_csv("sys_metrics.csv")

​

summaryメトリクスを更新する

辞書を渡してsummaryメトリクスを更新できます。

summary.update({"key": val})

​

run の実行に使用されたコマンドを取得する

各 run では、その run の起動に使用されたコマンドが run の概要ページに記録されます。API からこのコマンドを取得するには、次を実行します。

import wandb

api = wandb.Api()

run = api.run("<entity>/<project>/<run_id>")

meta = json.load(run.file("wandb-metadata.json").download())
program = ["python"] + [meta["program"]] + meta["args"]