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

MLFlow から データをインポートしたり、 W&B に保存した データの書き出しや更新を行ったりします

W&B Public APIを使用して、データの構成やエクスポートを行うことができます。

この機能には python>=3.8 が必要です。

​

MLFlow からのデータインポート

W&B は、Experiments 、Runs 、Artifacts 、メトリクス、その他のメタデータを含む MLFlow からのデータインポートをサポートしています。

依存関係のインストール:

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

W&B にログインします。以前にログインしたことがない場合は、プロンプトに従ってください。

wandb login

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

from wandb.apis.importers.mlflow import MlflowImporter

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

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

デフォルトでは、importer.collect_runs() は MLFlow サーバーからすべての Runs を収集します。特定のサブセットをアップロードしたい場合は、独自の Runs イテラブルを構築してインポーターに渡すことができます。

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 のインポートをスキップするには、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 を作成して結果をログ記録することで、分析結果を同期できます。例: wandb.init(job_type="analysis")
• 既存の Runs の更新: W&B Run に関連付けてログ記録されたデータを更新できます。例えば、アーキテクチャや当初ログ記録していなかったハイパーパラメータなどの追加情報を含めるために、一連の Runs の設定（config）を更新したい場合などです。

利用可能な関数の詳細については、生成されたリファレンスドキュメント を参照してください。

​

APIキーの作成

APIキーは、お使いのデバイスを W&B に対して認証します。

To create an API key, select the Personal API key or Service Account API key tab for details.

Personal API key

To create a personal API key owned by your user ID:

1. Log in to W&B, click your user profile icon, then click User Settings.
2. Click Create new API key.
3. Provide a descriptive name for your API key.
4. Click Create.
5. Copy the displayed API key immediately and store it securely.

Service account API key

To create an API key owned by a service account:

1. Navigate to the Service Accounts tab in your team or organization settings.
2. Find the service account in the list.
3. Click the action () menu, then click Create API key.
4. Provide a name for the API key, then click Create.
5. Copy the displayed API key immediately and store it securely.
6. Click Done.

You can create multiple API keys for a single service account to support different environments or workflows.

The full API key is only shown once at creation time. After you close the dialog, you cannot view the full API key again. Only the key ID (first part of the key) is visible in your settings. If you lose the full API key, you must create a new API key.

For secure storage options, see Store API keys securely.

​

Store and handle API keys securely

API keys provide access to your W&B account and should be protected like passwords. Follow these best practices:

​

Recommended storage methods

• Secrets manager: Use a dedicated secrets management system such as AWS Secrets Manager, HashiCorp Vault, Azure Key Vault, or Google Secret Manager.
• Password manager: Use a reputable password manager application.
• OS-level keychains: Store keys in macOS Keychain, Windows Credential Manager, or Linux secret service. Not suggested for production.

​

What to avoid

• Never commit API keys to version control systems such as Git.
• Do not store API keys in plain text configuration files.
• Do not pass API keys on the command line, because they will be visible in the output of OS commands like ps.
• Avoid sharing API keys through email, chat, or other unencrypted channels.
• Do not hard-code API keys in your source code.

If an API key is exposed, delete the API key from your W&B account immediately and contact support or your AISE.

​

Environment variables

When using API keys in your code, pass them through environment variables:

export WANDB_API_KEY="your-api-key-here"

This approach keeps keys out of your source code and makes it easier to rotate them when needed.

Avoid setting the environment variable in line with the command, because it will be visible in the output of OS commands like ps:

# Avoid this pattern, which can expose the API key in process managers
export WANDB_API_KEY="your-api-key-here" ./my-script.sh

​

SDK version compatibility

New API keys are longer than legacy keys. When authenticating with older versions of the wandb or weave SDKs, you may encounter an API key length error.

Solution: Update to a newer SDK version:

• wandb SDK v0.22.3+

  pip install --upgrade wandb==0.22.3
  

• weave SDK v0.52.17+

  pip install --upgrade weave==0.52.17
  

If you cannot upgrade the SDK immediately, set the API key using the WANDB_API_KEY environment variable as a workaround.

​

Run パスの確認

Public API を使用するには、多くの場合 <entity>/<project>/<run_id> という形式の Run パスが必要になります。アプリの UI で Run ページを開き、Overviewタブ をクリックして Run パスを取得してください。

​

Run データのダウンロード

完了した Run またはアクティブな Run からデータをダウンロードします。一般的な用途としては、Jupyter Notebook でのカスタム分析用にデータフレームをダウンロードしたり、自動化された環境でカスタムロジックを使用したりすることが挙げられます。

import wandb

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

Run オブジェクトの最も一般的に使用される属性は以下の通りです：

属性	意味
run.config	トレーニング Run のハイパーパラメータや、データセット Artifact を作成する Run の前処理メソッドなど、Run の設定情報の辞書です。これらは Run の「入力」と考えてください。
run.history()	損失（loss）など、モデルのトレーニング中に変化する値を格納するための辞書のリストです。run.log() コマンドはこのオブジェクトに値を追加します。
run.summary	Run の結果を要約する情報の辞書です。精度（accuracy）や損失などのスカラー値、または大きなファイルが含まれます。デフォルトでは、run.log() はサマリーをログ記録された時系列データの最終値に設定します。サマリーの内容を直接設定することもできます。サマリーは Run の「出力」と考えてください。

過去の Runs のデータを修正または更新することも可能です。デフォルトでは、API オブジェクトの単一インスタンスがすべてのネットワークリクエストをキャッシュします。実行中のスクリプトでリアルタイムの情報が必要な場合は、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

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

​

サンプリング

デフォルトの history メソッドは、メトリクスを固定数にサンプリングします（デフォルトは 500 です。これは samples 引数で変更可能です）。大規模な Run のすべてのデータをエクスポートしたい場合は、run.scan_history() メソッドを使用できます。詳細は API リファレンス を参照してください。

​

複数の Runs へのクエリ

DataFrame と CSV

このサンプルスクリプトは、プロジェクト内の Runs を検索し、名前、config、サマリー統計を含む 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 には精度などのメトリクスの出力
    # キー/値が含まれます。
    # 大きなファイルを省くために ._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() を使用してプロジェクト内の Runs を横断的にクエリする方法も提供しています。最も一般的なユースケースは、カスタム分析のための Run データのエクスポートです。クエリインターフェースは 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 を指定します。また、config やサマリーの値でソートすることも可能です。例えば、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: 生成されたハッシュのままにしておきます。これはプロジェクト内の Runs 全体で一意である必要があります。
• Run 名: チャート上の異なるラインを区別できるように、短くて読みやすく、できれば一意なものにしてください。
• Run ノート: Run で何を行っているかの簡単な説明を入れるのに最適です。wandb.init(notes="ここにノートを記載") で設定できます。
• Run タグ: Run タグで動的に追跡し、UI のフィルタを使用して関心のある Runs だけに絞り込みます。スクリプトからタグを設定し、その後 UI（Runs テーブルと Run ページの Overview タブの両方）で編集できます。詳細な手順は こちら を参照してください。

​

Public API の例

​

matplotlib や seaborn で可視化するためのデータエクスポート

一般的なエクスポートパターンについては、API の例 を確認してください。また、カスタムプロットや展開された Runs テーブルのダウンロードボタンをクリックして、ブラウザから CSV をダウンロードすることもできます。

​

Run からのメトリクス読み取り

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

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 クエリ言語を使用してフィルタリングできます。

​

日付

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

​

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

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

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 つの Runs の比較

これは run1 と run2 で異なる config パラメータを出力します。

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 のメトリクス名の変更

この例では、テーブル内のサマリー列の名前を変更します。

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 の config 更新

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

import wandb

api = wandb.Api()

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

​

システムリソース消費量（System metrics）の 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")

​

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

ヒストリーからデータを取得する場合、デフォルトでは 500 ポイントにサンプリングされます。run.scan_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]

​

ヒストリーからのページ分割されたデータの取得

バックエンドでのメトリクス取得が遅い場合や 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 をプルし、その名前、config、サマリー統計を含むデータフレームと CSV を生成します。<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 には精度などのメトリクスの
    #  出力キー/値が含まれます。
    #  大きなファイルを省くために ._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 からの Runs 取得

このスニペットは、特定の Sweep に関連付けられたすべての Runs をダウンロードします。

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.update({"key": val})

​

Run を実行したコマンドの取得

各 Run は、その開始に使用されたコマンドを Run の Overview ページでキャプチャします。このコマンドを 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"]