コードから評価データをログする

EvaluationLogger は、Python または TypeScript のコードから評価データを直接ログするための、柔軟で逐次的な方法を提供します。Weave の内部データ型について深い知識は不要です。ロガーをインスタンス化し、そのメソッド（log_prediction、log_score、log_summary）を使って評価ステップを記録するだけでかまいません。このアプローチは、ワークフローが複雑で、全体のデータセットやすべての scorer が最初から定義されていない場合に特に有用です。あらかじめ Dataset と Scorer オブジェクトのリストを定義する必要がある標準の Evaluation オブジェクトとは対照的に、EvaluationLogger を使うと、個々の予測とそれに関連するスコアを、利用可能になったタイミングで逐次ログできます。

より構造化された評価を使いたいですか？あらかじめ定義されたデータセットと scorer を備えた、より設計方針のはっきりした評価フレームワークを利用したい場合は、Weave の標準 Evaluation フレームワークを参照してください。EvaluationLogger は柔軟性を提供し、標準フレームワークは構造とガイダンスを提供します。

基本的なワークフロー

ロガーの初期化: EvaluationLogger のインスタンスを作成し、必要に応じて model と dataset に関するメタデータを指定します。指定しない場合はデフォルト値が使用されます。
LLM 呼び出し（例: OpenAI）におけるトークン使用量とコストを取得するには、任意の LLM 呼び出しより前に EvaluationLogger を初期化してください。先に LLM を呼び出してから予測結果をログに記録した場合、トークンとコストのデータは取得されません。
予測結果のログ: システムからの各入力／出力ペアに対して log_prediction を呼び出します。
スコアのログ: 返される ScoreLogger を使って、その予測に対して log_score を呼び出します。1 つの予測に対して複数のスコアを記録できます。
予測の完了: 予測のスコアをログしたら、必ず finish() を呼び出して予測を確定します。
サマリーのログ: すべての予測処理が完了したら、log_summary を呼び出してスコアを集計し、任意のカスタムメトリクスを追加します。

ある予測に対して finish() を呼び出した後は、それ以上スコアをログすることはできません。

ここで説明したワークフローを示す Python コードについては、Basic example を参照してください。

基本的な例

次の例では、既存のコードにそのまま組み込む形で EvaluationLogger を使用して、予測とスコアを記録する方法を示します。

Python
TypeScript

user_model モデル関数が定義され、入力のリストに適用されます。各サンプルについては次の処理を行います:

入力と出力は log_prediction を使ってログされます。
単純な正解度スコア (correctness_score) が log_score を使ってログされます。
finish() がその予測に対するログ処理を完了します。最後に、log_summary が集計メトリクスを記録し、Weave におけるスコアの自動要約をトリガーします。

import weave
from openai import OpenAI
from weave import EvaluationLogger

weave.init('your-team/your-project')

# トークントラッキングを確実にするため、モデルを呼び出す前にEvaluationLoggerを初期化する
eval_logger = EvaluationLogger(
    model="my_model",
    dataset="my_dataset"
)

# 入力データの例（任意のデータ構造を使用可能）
eval_samples = [
    {'inputs': {'a': 1, 'b': 2}, 'expected': 3},
    {'inputs': {'a': 2, 'b': 3}, 'expected': 5},
    {'inputs': {'a': 3, 'b': 4}, 'expected': 7},
]

# OpenAIを使用したモデルロジックの例
@weave.op
def user_model(a: int, b: int) -> int:
    oai = OpenAI()
    response = oai.chat.completions.create(
        messages=[{"role": "user", "content": f"What is {a}+{b}?"}],
        model="gpt-4o-mini"
    )
    # レスポンスを何らかの形で使用する（ここでは簡略化のためa + bを返す）
    return a + b

# サンプルを反復処理し、予測してログを記録する
for sample in eval_samples:
    inputs = sample["inputs"]
    model_output = user_model(**inputs) # 入力をkwargsとして渡す

    # 予測の入力と出力をログに記録する
    pred_logger = eval_logger.log_prediction(
        inputs=inputs,
        output=model_output
    )

    # この予測のスコアを計算してログに記録する
    expected = sample["expected"]
    correctness_score = model_output == expected
    pred_logger.log_score(
        scorer="correctness", # スコアラーの文字列名
        score=correctness_score
    )

    # この予測のログ記録を完了する
    pred_logger.finish()

# 評価全体の最終サマリーをログに記録する。
# Weaveは上記でログに記録された'correctness'スコアを自動集計する。
summary_stats = {"subjective_overall_score": 0.8}
eval_logger.log_summary(summary_stats)

print("評価のログ記録が完了しました。Weave UIで結果を確認してください。")

TypeScript SDK は 2 つの API パターンを提供します:

Fire-and-forget API（ほとんどのケースで推奨）: 同期コード内でノンブロッキングにログを記録するために、await なしで logPrediction() を使用する
Awaitable API: 先に進む前に処理の完了を保証したい場合に、await 付きで logPredictionAsync() を使用する

次のような場合は fire-and-forget の利用を推奨します:

高スループット: 各ロギング処理を待たずに、複数の予測を並列に処理できる
コード変更の最小化: 既存の async/await フローを組み替えることなく評価ロギングを追加できる
シンプルさ: ほとんどの評価シナリオでボイラープレートが少なく、構文が簡潔になる

fire-and-forget パターンは安全です。logSummary() が結果を集約する前に、保留中のすべての処理が完了するまで自動的に待機するためです。次の例では、fire-and-forget パターンを使ってモデルの予測を評価します。評価ロガーをセットアップし、3 つのテストサンプルに対して簡単なモデルを実行し、その後 await を使わずに予測をログに記録します。

import weave, {EvaluationLogger} from 'weave';
import OpenAI from 'openai';

await weave.init('your-team/your-project');

// トークントラッキングを確実にするため、モデルを呼び出す前にEvaluationLoggerを初期化する
const evalLogger = new EvaluationLogger({
  name: 'my-eval',
  model: 'my_model',
  dataset: 'my_dataset'
});

// 入力データの例
const evalSamples = [
  {inputs: {a: 1, b: 2}, expected: 3},
  {inputs: {a: 2, b: 3}, expected: 5},
  {inputs: {a: 3, b: 4}, expected: 7},
];

// OpenAIを使用したモデルロジックの例
const userModel = weave.op(async function userModel(a: number, b: number): Promise<number> {
  const oai = new OpenAI();
  const response = await oai.chat.completions.create({
    messages: [{role: 'user', content: `What is ${a}+${b}?`}],
    model: 'gpt-4o-mini'
  });
  return a + b;
});

// サンプルを反復処理し、fire-and-forgetパターンで予測・ログを記録する
for (const sample of evalSamples) {
  const {inputs} = sample;
  const modelOutput = await userModel(inputs.a, inputs.b);

  // Fire-and-forget: logPredictionにawaitは不要
  const scoreLogger = evalLogger.logPrediction(inputs, modelOutput);

  // この予測のスコアを計算してログに記録する
  const correctnessScore = modelOutput === sample.expected;

  // Fire-and-forget: logScoreにawaitは不要
  scoreLogger.logScore('correctness', correctnessScore);

  // Fire-and-forget: finishにawaitは不要
  scoreLogger.finish();
}

// logSummaryは内部ですべての保留中の操作が完了するまで待機する
const summaryStats = {subjective_overall_score: 0.8};
await evalLogger.logSummary(summaryStats);

console.log('評価ログが完了しました。Weave UIで結果を確認してください。');

エラー処理や順序依存のある処理を管理するなど、各操作が完了してから次に進む必要がある場合は、await 対応の API を使用します。次の例では、await なしで logPrediction() を呼び出すのではなく、await を付けて logPredictionAsync() を呼び出すことで、各操作が次の処理に進む前に完了することを保証しています。

// logPrediction の代わりに logPredictionAsync を使用する
const scoreLogger = await evalLogger.logPredictionAsync(inputs, modelOutput);

// 各操作を await する
await scoreLogger.logScore('correctness', correctnessScore);
await scoreLogger.finish();

高度な使い方

EvaluationLogger は、基本的なワークフローを超えて、より複雑な評価シナリオに対応するための柔軟なパターンを提供します。このセクションでは、自動的なリソース管理のためのコンテキストマネージャの利用、モデルの実行とロギングの分離、リッチなメディアデータの扱い、複数のモデル評価を横並びで比較するといった高度な手法を説明します。

コンテキストマネージャーの使用

EvaluationLogger は、予測とスコアの両方に対してコンテキストマネージャー（with 文）をサポートします。これにより、コードをよりクリーンに保ち、自動的なリソースクリーンアップを行い、LLM ジャッジ呼び出しのような入れ子の処理をより適切に追跡できます。このコンテキストで with 文を使うことで、次のような利点があります:

コンテキスト終了時の finish() の自動呼び出し
入れ子になった LLM 呼び出しに対するトークン／コストのより正確な追跡
予測コンテキスト内で、モデル実行後に出力を設定できること

Python
TypeScript

import openai
import weave

weave.init("nested-evaluation-example")
oai = openai.OpenAI()

# ロガーを初期化
ev = weave.EvaluationLogger(
    model="gpt-4o-mini",
    dataset="joke_dataset"
)

user_prompt = "Tell me a joke"

# 予測でコンテキストマネージャーを使用 - finish() を呼ぶ必要はない
with ev.log_prediction(inputs={"user_prompt": user_prompt}) as pred:
    # コンテキスト内でモデルを呼び出す
    result = oai.chat.completions.create(
        model="gpt-4o-mini",
        messages=[{"role": "user", "content": user_prompt}],
    )

    # モデル呼び出し後に出力を設定
    pred.output = result.choices[0].message.content

    # シンプルなスコアを記録
    pred.log_score("correctness", 1.0)
    pred.log_score("ambiguity", 0.3)
    
    # LLM 呼び出しが必要なスコアにはネストしたコンテキストマネージャーを使用
    with pred.log_score("llm_judge") as score:
        judge_result = oai.chat.completions.create(
            model="gpt-4o-mini",
            messages=[
                {"role": "system", "content": "Rate how funny the joke is from 1-5"},
                {"role": "user", "content": pred.output},
            ],
        )
        # 計算後にスコア値を設定
        score.value = judge_result.choices[0].message.content

# 'with' ブロックを抜けると finish() が自動的に呼ばれる

ev.log_summary({"avg_score": 1.0})

このパターンにより、すべての入れ子になった処理が追跡されて親の予測にひも付けられるため、Weave UI で正確なトークン使用量とコストデータを確認できます。

TypeScript には、コンテキストマネージャー用の Python の with 文パターンはありません。その代わりに、明示的に finish() を呼び出す fire-and-forget パターンを使用します。次の例では、予測を記録し、シンプルなスコアと LLM ジャッジスコアを追加し、その後 finish() で予測を確定します。

import weave from 'weave';
import OpenAI from 'openai';
import {EvaluationLogger} from 'weave/evaluationLogger';

await weave.init('your-team/your-project');
const oai = new OpenAI();

// ロガーを初期化
const ev = new EvaluationLogger({
  name: 'joke-eval',
  model: 'gpt-4o-mini',
  dataset: 'joke_dataset',
});

const userPrompt = 'Tell me a joke';

// モデル出力を取得
const result = await oai.chat.completions.create({
  model: 'gpt-4o-mini',
  messages: [{role: 'user', content: userPrompt}],
});

const modelOutput = result.choices[0].message.content;

// 出力付きで予測を記録
const pred = ev.logPrediction({user_prompt: userPrompt}, modelOutput);

// シンプルなスコアを記録
pred.logScore('correctness', 1.0);
pred.logScore('ambiguity', 0.3);

// LLM ジャッジスコアでは、呼び出しを行い、その結果を記録
const judgeResult = await oai.chat.completions.create({
  model: 'gpt-4o-mini',
  messages: [
    {role: 'system', content: 'Rate how funny the joke is from 1-5'},
    {role: 'user', content: modelOutput || ''},
  ],
});
pred.logScore('llm_judge', judgeResult.choices[0].message.content);

// スコア付けが完了したら、明示的に finish() を呼び出す
pred.finish();

await ev.logSummary({avg_score: 1.0});

TypeScript ではコンテキストマネージャーによる自動クリーンアップはありませんが、logSummary() は結果を集計する前に未完了の予測を自動的にすべて完了させます。finish() を明示的に呼び出したくない場合は、この挙動に依存しても構いません。

ログに記録する前に出力を取得する

まずモデルの出力を計算し、その後で予測値とスコアを別々にログに記録できます。これにより、評価ロジックとロギングロジックをより明確に分離できます。

Python
TypeScript

# トークン追跡のために、モデルを呼び出す前に EvaluationLogger を初期化する
ev = EvaluationLogger(
    model="example_model",
    dataset="example_dataset"
)

# モデルの出力（例: OpenAI コール）は、トークン追跡のためにロガー初期化の後で実行する必要がある
outputs = [your_output_generator(**inputs) for inputs in your_dataset]
preds = [ev.log_prediction(inputs, output) for inputs, output in zip(your_dataset, outputs)]
for pred, output in zip(preds, outputs):
    pred.log_score(scorer="greater_than_5_scorer", score=output > 5)
    pred.log_score(scorer="greater_than_7_scorer", score=output > 7)
    pred.finish()

ev.log_summary()

fire-and-forget パターンは、複数の予測を並列処理する場合に特に有効です。次の例では、EvaluationLogger のインスタンスを複数同時に作成することで、評価をバッチ的に並列処理します。

// トークン追跡のために、モデルを呼び出す前に EvaluationLogger を初期化する
const ev = new EvaluationLogger({
  name: 'parallel-eval',
  model: 'example_model',
  dataset: 'example_dataset'
});

// OpenAI コールなどのモデル出力は、トークン追跡のためにロガー初期化の後で実行する必要がある
const outputs = await Promise.all(
  yourDataset.map(inputs => yourOutputGenerator(inputs))
);

// fire-and-forget: await せずにすべての予測を処理する
const preds = yourDataset.map((inputs, i) =>
  ev.logPrediction(inputs, outputs[i])
);

preds.forEach((pred, i) => {
  const output = outputs[i];
  // fire-and-forget: await は不要
  pred.logScore('greater_than_5_scorer', output > 5);
  pred.logScore('greater_than_7_scorer', output > 7);
  pred.finish();
});

// logSummary は未完了のすべての処理が終わるまで待機する
await ev.logSummary();

fire-and-forget パターンを使うことで、利用可能な計算リソースが許す限り、多数の評価を並列に処理できます。

リッチメディアをログに記録する

入力、出力、およびスコアには、画像、動画、音声、構造化テーブルなどのリッチメディアを含めることができます。log_prediction や log_score メソッドに dict またはメディアオブジェクトを渡すだけです。

Python
TypeScript

import io
import wave
import struct
from PIL import Image
import random
from typing import Any
import weave

def generate_random_audio_wave_read(duration=2, sample_rate=44100):
    n_samples = duration * sample_rate
    amplitude = 32767  # 16-bit max amplitude

    buffer = io.BytesIO()

    # Write wave data to the buffer
    with wave.open(buffer, 'wb') as wf:
        wf.setnchannels(1)
        wf.setsampwidth(2)  # 16-bit
        wf.setframerate(sample_rate)

        for _ in range(n_samples):
            sample = random.randint(-amplitude, amplitude)
            wf.writeframes(struct.pack('<h', sample))

    # Rewind the buffer to the beginning so we can read from it
    buffer.seek(0)

    # Return a Wave_read object
    return wave.open(buffer, 'rb')

rich_media_dataset = [
    {
        'image': Image.new(
            "RGB",
            (100, 100),
            color=(
                random.randint(0, 255),
                random.randint(0, 255),
                random.randint(0, 255),
            ),
        ),
        "audio": generate_random_audio_wave_read(),
    }
    for _ in range(5)
]

@weave.op
def your_output_generator(image: Image.Image, audio) -> dict[str, Any]:
    return {
        "result": random.randint(0, 10),
        "image": image,
        "audio": audio,
    }

ev = EvaluationLogger(model="example_model", dataset="example_dataset")

for inputs in rich_media_dataset:
    output = your_output_generator(**inputs)
    pred = ev.log_prediction(inputs, output)
    pred.log_score(scorer="greater_than_5_scorer", score=output["result"] > 5)
    pred.log_score(scorer="greater_than_7_scorer", score=output["result"] > 7)

ev.log_summary()

TypeScript SDK では、weaveImage と weaveAudio 関数を使って画像と音声をログとして記録できます。次の例では、画像ファイルと音声ファイルを読み込み、それらをモデルで処理し、結果とスコアをログに記録します。

import weave, {EvaluationLogger} from 'weave';
import * as fs from 'fs';

await weave.init('your-team/your-project');

// Load images and audio from files
const richMediaDataset = [
  {
    image: weave.weaveImage({data: fs.readFileSync('sample1.png')}),
    audio: weave.weaveAudio({data: fs.readFileSync('sample1.wav')}),
  },
  {
    image: weave.weaveImage({data: fs.readFileSync('sample2.png')}),
    audio: weave.weaveAudio({data: fs.readFileSync('sample2.wav')}),
  },
];

// Model that processes media and returns results
const yourOutputGenerator = weave.op(
  async (inputs: {image: any; audio: any}) => {
    const result = Math.floor(Math.random() * 10);
    return {
      result,
      image: inputs.image,
      audio: inputs.audio,
    };
  },
  {name: 'yourOutputGenerator'}
);

const ev = new EvaluationLogger({
  name: 'rich-media-eval',
  model: 'example_model',
  dataset: 'example_dataset',
});

for (const inputs of richMediaDataset) {
  const output = await yourOutputGenerator(inputs);

  // Log prediction with rich media in both inputs and outputs
  const pred = ev.logPrediction(inputs, output);
  pred.logScore('greater_than_5_scorer', output.result > 5);
  pred.logScore('greater_than_7_scorer', output.result > 7);
  pred.finish();
}

await ev.logSummary();

複数の評価を記録して比較する

EvaluationLogger を使用すると、複数の評価を記録して比較できます。

以下のコードサンプルを実行します。
Weave UI で Evals タブに移動します。
比較したい eval を選択します。
Compare ボタンをクリックします。Compare ビューでは次のことができます：
- 追加・削除する Evals を選択する
- 表示・非表示にするメトリクスを選択する
- 特定の例をページ送りしながら、同じ入力・同じデータセットに対して異なるモデルがどのような結果を出したかを確認する
比較の詳細については、Comparisons を参照してください。

Python
TypeScript

import weave

models = [
    "model1",
    "model2",
     {"name": "model3", "metadata": {"coolness": 9001}}
]

for model in models:
    # トークンを記録するために、モデル呼び出しの前に EvalLogger を初期化する必要があります
    ev = EvaluationLogger(
        name="comparison-eval",
        model=model, 
        dataset="example_dataset",
        scorers=["greater_than_3_scorer", "greater_than_5_scorer", "greater_than_7_scorer"],
        eval_attributes={"experiment_id": "exp_123"}
    )
    for inputs in your_dataset:
        output = your_output_generator(**inputs)
        pred = ev.log_prediction(inputs=inputs, output=output)
        pred.log_score(scorer="greater_than_3_scorer", score=output > 3)
        pred.log_score(scorer="greater_than_5_scorer", score=output > 5)
        pred.log_score(scorer="greater_than_7_scorer", score=output > 7)
        pred.finish()

    ev.log_summary()

import weave from 'weave';
import {EvaluationLogger} from 'weave/evaluationLogger';
import {WeaveObject} from 'weave/weaveObject';

await weave.init('your-team/your-project');

const models = [
  'model1',
  'model2',
  new WeaveObject({name: 'model3', metadata: {coolness: 9001}})
];

for (const model of models) {
  // トークンを記録するために、モデル呼び出しの前に EvalLogger を初期化する必要があります
  const ev = new EvaluationLogger({
    name: 'comparison-eval',
    model: model,
    dataset: 'example_dataset',
    description: 'Model comparison evaluation',
    scorers: ['greater_than_3_scorer', 'greater_than_5_scorer', 'greater_than_7_scorer'],
    attributes: {experiment_id: 'exp_123'}
  });

  for (const inputs of yourDataset) {
    const output = await yourOutputGenerator(inputs);

    // クリーンで効率的なロギングのための「投げっぱなし」パターン
    const pred = ev.logPrediction(inputs, output);
    pred.logScore('greater_than_3_scorer', output > 3);
    pred.logScore('greater_than_5_scorer', output > 5);
    pred.logScore('greater_than_7_scorer', output > 7);
    pred.finish();
  }

  await ev.logSummary();
}

使用上のヒント

Python
TypeScript

各予測の後はすぐに finish() を呼び出してください。
単一の予測に紐づかないメトリクス（例: 全体のレイテンシー）を記録するには log_summary を使用します。
リッチメディアのロギングは定性的な分析に適しています。

自動完了の挙動: 明確さのため、各予測で明示的に finish() を呼び出すことを推奨しますが、logSummary() は未完了の予測を自動的に完了します。ただし、一度スクリプト内で finish() を呼び出すと、それ以降スコアを記録することはできません。
設定オプション: Weave UI で評価を整理およびフィルタリングするために、name、description、dataset、model、scorers、attributes などの設定オプションを使用してください。

はじめに

ガイド

クックブック

リファレンス

詳細とサポート

オープンソース

コミュニティ

基本的なワークフロー

基本的な例

高度な使い方

コンテキストマネージャーの使用

ログに記録する前に出力を取得する

リッチメディアをログに記録する

複数の評価を記録して比較する

使用上のヒント

はじめに

ガイド

クックブック

リファレンス

詳細とサポート

オープンソース

コミュニティ

​基本的なワークフロー

​基本的な例

​高度な使い方

​コンテキストマネージャーの使用

​ログに記録する前に出力を取得する

​リッチメディアをログに記録する

​複数の評価を記録して比較する

​使用上のヒント

基本的なワークフロー

基本的な例

高度な使い方

コンテキストマネージャーの使用

ログに記録する前に出力を取得する

リッチメディアをログに記録する

複数の評価を記録して比較する

使用上のヒント