評価データのエクスポート

W&B Weave で評価を実行するチームは、Weave UI の外部で評価結果を必要とすることがよくあります。主なユースケースは次のとおりです。

カスタム分析や可視化のためにメトリクスをスプレッドシートやノートブックに取り込む。
評価結果を CI/CD パイプラインにフィードしてデプロイメントを制御する。
Looker などの BI ツールや、W&B seat を持っていないステークホルダー向けの社内ダッシュボードを通じて結果を共有する。
複数の project にわたるスコアを集計する自動レポートパイプラインを構築する。

v2 Evaluation REST API は、評価 run、予測、スコア、Scorer といった評価に特化した概念を提供します。その結果、汎用的な Calls API と比べて、型付きの Scorer の統計やデータセット入力を含む、よりリッチで構造化された出力が得られます。

使用する API エンドポイント

このページのスニペットでは、v2 Evaluation REST API の次のエンドポイントを使用します。

GET /v2/{entity}/{project}/evaluation_runs: project 内の評価 run を一覧表示します。評価 ref、モデル参照、または run ID によるフィルターを任意で指定できます。
GET /v2/{entity}/{project}/evaluation_runs/{evaluation_run_id}: 単一の評価 run を読み取り、モデル、評価 ref、ステータス、タイムスタンプ、サマリーを取得します。
POST /v2/{entity}/{project}/eval_results/query: 1 つ以上の評価について、グループ化された評価結果の行を取得します。行ごとの試行を、モデル出力、スコア、および任意で解決済みのデータセット行の入力とともに返します。リクエストに応じて、集計された Scorer の統計も返します。
GET /v2/{entity}/{project}/predictions/{prediction_id}: 個々の予測を、入力、出力、モデル参照とともに読み取ります。

認証には HTTP Basic を使用し、ユーザー名には api、パスワードには W&B APIキーを指定します。

前提条件

このページのサンプルはPythonを使用しますが、Evaluation REST APIは言語に依存しません：TypeScriptや任意のHTTPクライアントから同じエンドポイントを呼び出すことができます。開始する前に、以下を用意してください：

Python 3.7以降。
requests ライブラリ。pip install requests でインストールします。
APIキー。WANDB_API_KEY 環境変数として設定します。CoreWeave Forge UI でキーを取得してください。

認証を設定する

次のスニペットでは、このページ全体で使用するライブラリをインポートし、ベース URL、認証タプル、対象の entity と project を設定します。以降のすべての例では、これらの変数を再使用します。

import json
import os

import requests

TRACE_BASE = "https://trace.wandb.ai"
AUTH = ("api", os.environ["WANDB_API_KEY"])

entity = "my-team"
project = "my-project"

認証を設定すると、以下のセクションで説明する任意のエンドポイントを呼び出せます。

評価 run の一覧を取得する

エクスポートのワークフローでは、通常、最初に評価 run の一覧が必要です。他のエンドポイントで必要な evaluation_run_id の値を取得できるためです。project 内の最近の評価 run を取得し、各 run の ID やステータスなどの詳細を一覧表示します。

resp = requests.get(
    f"{TRACE_BASE}/v2/{entity}/{project}/evaluation_runs",
    auth=AUTH,
)
runs = [json.loads(line) for line in resp.text.strip().splitlines()]

for run in runs:
    print(run["evaluation_run_id"], run.get("status"))

単一の評価 run を読み取る

evaluation_run_id を取得したら、その run の完全なレコードを取得できます。モデル、評価 ref、ステータス、タイムスタンプなど、特定の評価 run の詳細を取得します。[EVALUATION_RUN_ID] を、取得する評価 run の ID に置き換えてください。

eval_run_id = "[EVALUATION_RUN_ID]"

resp = requests.get(
    f"{TRACE_BASE}/v2/{entity}/{project}/evaluation_runs/{eval_run_id}",
    auth=AUTH,
)
eval_run = resp.json()
print(eval_run["evaluation_run_id"], eval_run.get("status"), eval_run.get("model"))

予測とスコアを取得する

スプレッドシートへのエクスポートや行単位の分析など、run の元データが必要な場合は、eval_results/query エンドポイントを使用して評価 run の行ごとの結果を取得します。各行には、データセット入力、モデル出力、個々の Scorer の結果が含まれます。行ごとの詳細をすべて取得するには、include_rows、include_raw_data_rows、resolve_row_refs を設定します。[EVALUATION_RUN_ID] を、クエリする評価 run の ID に置き換えてください。

eval_run_id = "[EVALUATION_RUN_ID]"

resp = requests.post(
    f"{TRACE_BASE}/v2/{entity}/{project}/eval_results/query",
    json={
        "evaluation_run_ids": [eval_run_id],
        "include_rows": True,
        "include_raw_data_rows": True,
        "resolve_row_refs": True,
    },
    auth=AUTH,
)
results = resp.json()

for row in results["rows"]:
    inputs = row.get("raw_data_row")
    for ev in row.get("evaluations", []):
        for trial in ev.get("trials", []):
            output = trial.get("model_output")
            scores = trial.get("scores", {})
            print("Input:", inputs)
            print("Output:", output)
            print("Scores:", scores)

集計スコアを取得する

ダッシュボードや CI/CD のゲート判定などで概要レベルのメトリクスのみが必要な場合は、行ごとのデータではなくサマリー統計をリクエストしてください。同じ eval_results/query エンドポイントで、行ごとのデータではなく集計された Scorer の統計を返すこともできます。include_summary を設定すると、二値 Scorer の合格率や連続値 Scorer の平均値など、サマリーレベルのメトリクスを取得できます。

resp = requests.post(
    f"{TRACE_BASE}/v2/{entity}/{project}/eval_results/query",
    json={
        "evaluation_run_ids": [eval_run_id],
        "include_summary": True,
        "include_rows": False,
    },
    auth=AUTH,
)
results = resp.json()

for ev in results["summary"]["evaluations"]:
    for stat in ev["scorer_stats"]:
        print(stat["scorer_key"], stat.get("value_type"), stat.get("pass_rate") or stat.get("numeric_mean"))

単一の予測を読み取る

予期しないスコアを調査する場合など、単一の行を個別に確認するには、ID を指定して予測を直接取得できます。入力、出力、モデル参照を含む、個々の予測の詳細をすべて取得します。[PREDICTION_ID] を取得したい予測の ID に置き換えてください。

prediction_id = "[PREDICTION_ID]"

resp = requests.get(
    f"{TRACE_BASE}/v2/{entity}/{project}/predictions/{prediction_id}",
    auth=AUTH,
)
prediction = resp.json()
print(prediction)

行のダイジェスト

各エンドポイントが返す生データに加えて、eval_results/query の応答には、run 間で行を関連付けるための追加の識別子が含まれます。eval_results/query エンドポイントの各結果行には row_digest が含まれます。これは、評価データセット内の特定の入力を、位置ではなく内容に基づいて一意に識別するコンテンツハッシュです。行のダイジェストは、次の用途に役立ちます。

評価間の比較: 同じデータセットで 2 つの異なるモデルを実行した場合、同じダイジェストを持つ行は同じ入力を表します。row_digest をキーに結合することで、まったく同じタスクに対する異なるモデルの性能を比較できます。
重複排除: 同じタスクが複数の評価スイートに含まれている場合、ダイジェストを使用してそのタスクを識別できます。
再現性: ダイジェストは内容に基づく識別子なので、誰かがデータセットの行を変更すると (指示文、評価基準、その他のフィールドを変更すると) 、新しいダイジェストが割り当てられます。2 つの評価 run が同一の入力を使用したか、異なるバージョンを使用したかを確認できます。

​使用する API エンドポイント

​前提条件

​認証を設定する

​評価 run の一覧を取得する

​単一の評価 run を読み取る

​予測とスコアを取得する

​集計スコアを取得する

​単一の予測を読み取る

​行のダイジェスト