スコアリングの概要

Weave では、Scorer が AI の出力を評価し、評価メトリクスを返します。Scorer は AI の出力を受け取って分析し、結果を辞書として返します。必要に応じて入力データを参照に使用することもでき、評価の説明や推論などの追加情報を出力することもできます。このガイドは、AI システムの出力の品質を測定したい開発者を対象としています。Weave の評価における Scorer の役割、独自の Scorer の作成方法、個々の Call に Scorer を適用する方法、得られたスコアの分析方法について説明します。

Python
TypeScript

評価時に、Scorer を weave.Evaluation オブジェクトに渡します。Weave は次の 2 つのタイプの Scorer をサポートしています。

関数ベースの Scorer: @weave.op でデコレートされた Python 関数です。
クラスベースの Scorer: weave.Scorer を継承した Python クラスで、より複雑な評価に使用します。

Scorer は辞書を返す必要があります。複数のメトリクスやネストされたメトリクスのほか、LLM 評価者が自身の推論について返すテキストなど、数値以外の値も返すことができます。

Scorer は、評価時に weave.Evaluation オブジェクトに渡す特別な Op です。

独自の Scorer を作成する

カスタム Scorer を使用すると、組み込みの Scorer では対応できない、ユースケース固有の評価基準を定義できます。以下のセクションでは、Scorer を定義する 2 つの方法 (関数として定義する方法と、より複雑なロジック向けにクラスとして定義する方法) について説明します。

すぐに使える Scorer このガイドではカスタム Scorer の作成方法を説明しますが、Weave には、すぐに使用できる事前定義済みScorerとローカル SLM Scorerも用意されています。主な例は次のとおりです。

関数ベースの Scorer

Python
TypeScript

関数ベースの Scorer は、@weave.op でデコレートされた、辞書を返す関数です。次のようなシンプルな評価に適しています。

import weave

@weave.op
def evaluate_uppercase(text: str) -> dict:
    return {"text_is_uppercase": text.isupper()}

my_eval = weave.Evaluation(
    dataset=[{"text": "HELLO WORLD"}],
    scorers=[evaluate_uppercase]
)

評価を実行すると、evaluate_uppercase はテキストがすべて大文字かどうかをチェックします。

関数ベースの Scorer は weave.op でラップされた関数で、modelOutput と、必要に応じて datasetRow を含むオブジェクトを受け取ります。次の例のようなシンプルな評価に適しています。

import * as weave from 'weave'

const evaluateUppercase = weave.op(
    ({modelOutput}) => modelOutput.toUpperCase() === modelOutput,
    {name: 'textIsUppercase'}
);

const myEval = new weave.Evaluation({
    dataset: [{text: 'HELLO WORLD'}],
    scorers: [evaluateUppercase],
})

クラスベースの Scorer

Python
TypeScript

Scorer の追加メタデータをトラッキングしたい場合、LLM 評価者でさまざまなプロンプトを試したい場合、複数の関数の Call を行いたい場合など、より高度な評価には Scorer クラスを使用します。要件:

weave.Scorer を継承します。
@weave.op でデコレートした score メソッドを定義します。
score メソッドは辞書を返す必要があります。

例:

import weave
from openai import OpenAI
from weave import Scorer

llm_client = OpenAI()

class SummarizationScorer(Scorer):
    model_id: str = "gpt-4o"
    system_prompt: str = "Evaluate whether the summary is good."

    @weave.op
    def some_complicated_preprocessing(self, text: str) -> str:
        processed_text = "Original text: \n" + text + "\n"
        return processed_text

    @weave.op
    def call_llm(self, summary: str, processed_text: str) -> dict:
        res = llm_client.chat.completions.create(
            messages=[
                {"role": "system", "content": self.system_prompt},
                {"role": "user", "content": (
                    f"Analyze how good the summary is compared to the original text."
                    f"Summary: {summary}\n{processed_text}"
                )}])
        return {"summary_quality": res}

    @weave.op
    def score(self, output: str, text: str) -> dict:
        """要約の品質をスコアリングします。

        Args:
            output: AI システムが生成した要約
            text: 要約対象の元のテキスト
        """
        processed_text = self.some_complicated_preprocessing(text)
        eval_result = self.call_llm(summary=output, processed_text=processed_text)
        return {"summary_quality": eval_result}

evaluation = weave.Evaluation(
    dataset=[{"text": "The quick brown fox jumps over the lazy dog."}],
    scorers=[summarization_scorer])

このクラスは、要約を元のテキストと比較して、その品質を評価します。

この機能は TypeScript ではまだ利用できません。

Scorer の仕組み

このセクションでは、Scorer が評価からデータを受け取る仕組み、データセットの列を Scorer の引数にマッピングする方法、スコアリングプロンプトで op の変数を参照する方法、および Weave が行ごとのスコアを集計して最終結果を算出する仕組みについて説明します。

Scorer のキーワード引数

Python
TypeScript

Scorer は、AI システムからの出力と、データセット行の入力データの両方にアクセスできます。

入力: データセット行のデータ (label 列や target 列など) を Scorer で使用したい場合は、Scorer の定義に label または target キーワード引数を追加して、そのデータを Scorer から利用できるようにします。

たとえば、データセットの label という列を使用する場合、Scorer 関数 (または score クラスメソッド) のパラメーターリストは次のようになります。

@weave.op
def my_custom_scorer(output: str, label: int) -> dict:
    ...

Weave の Evaluation を実行すると、AI システムの出力が output パラメーターに渡されます。また、Evaluation は Scorer のその他の引数名をデータセットの列名と自動的に照合しようとします。Scorer の引数やデータセットの列をカスタマイズできない場合は、列マッピングを使用できます。詳しくは次のセクションを参照してください。

出力: AI システムの出力にアクセスするには、Scorer 関数のシグネチャに output パラメーターを含めます。

`column_map` による列名のマッピング

score メソッドの引数名が、データセットの列名と一致しない場合があります。その場合は、column_map を使用して対応できます。クラスベースの Scorer を使用している場合は、Scorer クラスを初期化する際に、Scorer の column_map 属性に辞書を渡します。この辞書は、score メソッドの引数名をデータセットの列名に対応付けるもので、{scorer_keyword_argument: dataset_column_name} の順序で指定します。例:

import weave
from weave import Scorer

# 要約対象のニュース記事のデータセット
dataset = [
    {"news_article": "The news today was great...", "date": "2030-04-20", "source": "Bright Sky Network"},
    ...
]

# Scorer クラス
class SummarizationScorer(Scorer):

    @weave.op
    def score(self, output, text) -> dict:
        """
            output: LLM 要約システムが出力した要約
            text: 要約対象のテキスト
        """
        ...  # 要約の品質を評価する

# `text` 引数を `news_article` データ列にマッピングする列マッピングを指定して Scorer を作成する
scorer = SummarizationScorer(column_map={"text" : "news_article"})

これで、score メソッドの text 引数は、データセットの news_article 列からデータを受け取るようになります。メモ:

同じことを実現する別の方法として、Scorer をサブクラス化して score メソッドをオーバーロードし、列を明示的にマッピングすることもできます。

import weave
from weave import Scorer

class MySummarizationScorer(SummarizationScorer):

    @weave.op
    def score(self, output: str, news_article: str) -> dict:  # 型ヒントを追加
        # score メソッドをオーバーロードし、列を手動でマッピングする
        return super().score(output=output, text=news_article)

Scorer は、AI システムからの出力と、データセット行の内容の両方にアクセスできます。Scorer の定義に datasetRow キーワード引数を追加すると、データセット行の該当する列にアクセスできます。

const myScorer = weave.op(
    ({modelOutput, datasetRow}) => {
        return modelOutput * 2 === datasetRow.expectedOutputTimesTwo;
    },
    {name: 'myScorer'}
);

`columnMapping` による列名のマッピング

TypeScript では、この機能は個々の Scorer ではなく、Evaluation オブジェクトで提供されます。

datasetRow のキーが Scorer の命名と完全には一致しないものの、意味的には近い場合があります。その場合は、Evaluation の columnMapping オプションを使用して列をマッピングできます。マッピングは常に Scorer 側を基準に指定します。つまり、{scorer_key: dataset_column_name} の形式です。例:

const myScorer = weave.op(
    ({modelOutput, datasetRow}) => {
        return modelOutput * 2 === datasetRow.expectedOutputTimesTwo;
    },
    {name: 'myScorer'}
);

const myEval = new weave.Evaluation({
    dataset: [{expected: 2}],
    scorers: [myScorer],
    columnMapping: {expectedOutputTimesTwo: 'expected'}
});

スコアリングプロンプトで op の変数にアクセスする

LLM-as-a-judge scorer のスコアリングプロンプトでは、op の変数を参照できます。これらの値は、scorer の実行時に Weave によって自動的に抽出されます。たとえば、次のような関数があるとします。

@weave.op
def summarize_article(article: str, max_length: int) -> str:
    # ここに要約ロジックを記述します
    return summary

以下の変数を使用できます。

変数	説明
`{article}`	入力引数 `article` の値
`{max_length}`	入力引数 `max_length` の値
`{inputs}`	すべての入力引数を含む JSON 辞書
`{output}`	op から返された結果

スコアリングプロンプトの例:

この要約の品質を評価してください。

元の記事: {article}
要約: {output}
指定された最大長: {max_length}

以下の観点に基づいて、要約を 1〜10 の 10 段階で評価してください。
- 精度: 記事の内容を正確に表していますか？
- 網羅性: 要点を漏れなく押さえていますか？
- 簡潔性: 適度に簡潔にまとめられていますか？

評価とその理由を含む JSON オブジェクトを返してください。

Scorer の最終集計

Python
TypeScript

評価中、Weave はデータセットの各行に対して scorer を計算します。評価の最終スコアを算出するため、Weave は出力の戻り値の型に基づいて auto_summarize を実行します。Scorer クラスの summarize メソッドを上書きすると、最終スコアを独自の方法で計算できます。summarize 関数の仕様は次のとおりです。

単一のパラメーター score_rows を受け取ります。これは辞書のリストで、各辞書にはデータセットの 1 行に対して score メソッドが返したスコアが含まれます。
集計されたスコアを含む辞書を返します。

このメリットデータセット全体の最終スコアを決める前に、すべての行をスコアリングしておく必要がある場合に役立ちます。

class MyBinaryScorer(Scorer):
    """
    出力全体がターゲットと一致する場合は True、一致しない場合は False を返します
    """

    @weave.op
    def score(self, output, target):
        return {"match": output == target}

    def summarize(self, score_rows: list) -> dict:
        full_match = all(row["match"] for row in score_rows)
        return {"full_match": full_match}

この例の場合、デフォルトの auto_summarize は True の件数と割合を返します。

詳細については、CorrectnessLLMJudge の実装を参照してください。

評価中、Weave はデータセットの各行に対して scorer を計算します。最終スコアの算出には、出力のタイプに応じて集計を行う内部関数 summarizeResults が使用されます。Weave はカスタムの集計をサポートしていません。

Call に Scorer を適用する

Scorer は weave.Evaluation の一部として実行するだけでなく、個々の Call に直接適用することもできます。本番トラフィックをスコアリングしたい場合や、特定の Op の invocation に評価メトリクスを付与したい場合に便利です。 Weave Op に Scorer を適用するには、.call() メソッドを使用します。このメソッドを使うと、操作の結果とそのトラッキング情報の両方にアクセスできるため、Scorer の結果を Weave のデータベース内の特定の Call に関連付けることができます。 .call() メソッドの使用方法の詳細については、Op の呼び出しガイドを参照してください。

Python
TypeScript

基本的な例を次に示します。

# 結果と Call オブジェクトの両方を取得
result, call = generate_text.call("Say hello")

# Scorer を適用
score = await call.apply_scorer(MyScorer())

同じ Call に複数の Scorer を適用することもできます。

# 複数の Scorer を並列に適用
await asyncio.gather(
    call.apply_scorer(quality_scorer),
    call.apply_scorer(toxicity_scorer)
)

メモ:

Weave は Scorer の結果を自動的にデータベースに保存します。
Scorer は、メインの操作が完了した後に非同期で実行されます。
Scorer の結果は、UI で確認したり、API でクエリしたりできます。

本番環境でのベストプラクティスや完全な設定例など、Scorer をガードレールやモニターとして使用する方法の詳細については、ガードレールとモニターのガイドを参照してください。

This feature is not available in TypeScript yet.

`preprocess_model_input` を使用する

preprocess_model_input パラメーターを使用すると、評価時にデータセットのサンプルがモデルに渡される前に、そのサンプルを変更できます。使用方法とサンプルについては、評価前に preprocess_model_input を使用してデータセットの行をフォーマットするを参照してください。

スコア分析

Scorer の実行後は、モデルの動作を把握したりバージョンを比較したりするために、生成されたスコアを確認したい場面がよくあります。以下のセクションでは、API と Weights & Biases UI を使用して、単一の Call、複数の Call、および特定の Scorer でスコア付けされたすべての Call のスコアを分析する方法について説明します。

個々の Call のスコアを分析する

単一 Call 用の API

単一の Call を取得するには、get_call メソッドを使用します。

client = weave.init("my-project")

# 単一の Call を取得する
call = client.get_call("call-uuid-here")

# スコアが格納されている Call のフィードバックを取得する
feedback = list(call.feedback)

単一の Call の UI

Call details パネルの Scores タブには、個々の Call のスコアが表示されます。

複数の Call のスコアを分析する

複数の Call 用の API

複数の Call を取得するには、get_calls メソッドを使用します。

client = weave.init("my-project")

# 複数の Call を取得します。必要に応じて任意のフィルターを使用し、フィードバックも含めます
calls = client.get_calls(..., include_feedback=True)

# 各 Call を順に処理し、スコアを含むフィードバックにアクセスします
for call in calls:
    feedback = list(call.feedback)

複数の Call の UI

Traces の表では、複数の Call のスコアが Scores 列に表示されます。

特定の Scorer でスコア付けされたすべての Call を分析する

Scorer 別の全 Call を取得する API

特定の Scorer でスコア付けされたすべての Call を取得するには、get_calls メソッドを使用します。

client = weave.init("my-project")

# Scorer のバージョンを問わず、その Scorer でスコア付けされたすべての Call を取得するには、Scorer 名（通常はクラス名）を使用します
calls = client.get_calls(scored_by=["MyScorer"], include_feedback=True)

# Scorer の特定のバージョンでスコア付けされたすべての Call を取得するには、完全な ref を使用します
# ref は Scorer オブジェクトまたは UI で取得できます。
calls = client.get_calls(scored_by=[myScorer.ref.uri()], include_feedback=True)

# Call を反復処理して、スコアを含むフィードバックにアクセスします
for call in calls:
    feedback = list(call.feedback)

UI で Scorer ごとのすべての Call を表示する

最後に、特定の Scorer によってスコア付けされたすべての Call を確認するには、UI の Scorers タブにアクセスし、Programmatic Scorer タブを選択します。対象の Scorer をクリックすると、Scorer の詳細ページが開きます。

次に、Scores の下にある View Traces ボタンをクリックします。その Scorer によってスコア付けされたすべての Call が表示されます。

デフォルトでは、選択した Scorer のバージョンでフィルターされています。バージョンのフィルターを削除すると、Scorer のいずれかのバージョンによってスコア付けされたすべての Call を表示できます。

​独自の Scorer を作成する

​関数ベースの Scorer

​クラスベースの Scorer

​Scorer の仕組み

​Scorer のキーワード引数

​column_map による列名のマッピング

​columnMapping による列名のマッピング

​スコアリング プロンプトで op の変数にアクセスする

​Scorer の最終集計

​Call に Scorer を適用する

​preprocess_model_input を使用する

​スコア分析

​個々の Call のスコアを分析する

​単一 Call 用の API

​単一の Call の UI

​複数の Call のスコアを分析する

​複数の Call 用の API

​複数の Call の UI

​特定の Scorer でスコア付けされたすべての Call を分析する

​Scorer 別の全 Call を取得する API

​UI で Scorer ごとのすべての Call を表示する

独自の Scorer を作成する

関数ベースの Scorer

クラスベースの Scorer

Scorer の仕組み

Scorer のキーワード引数

`column_map` による列名のマッピング

`columnMapping` による列名のマッピング

スコアリングプロンプトで op の変数にアクセスする

Scorer の最終集計

Call に Scorer を適用する

`preprocess_model_input` を使用する

スコア分析

個々の Call のスコアを分析する

単一 Call 用の API

単一の Call の UI

複数の Call のスコアを分析する

複数の Call 用の API

複数の Call の UI

特定の Scorer でスコア付けされたすべての Call を分析する

Scorer 別の全 Call を取得する API

UI で Scorer ごとのすべての Call を表示する