スコアリングの概要

AI の出力を評価し、Weave Scorer を使って評価メトリクスを返します

Weave では、Scorer を使用して AI の出力を評価し、評価メトリクスを返します。Scorer は AI の出力を受け取り、それを分析して、結果を辞書形式で返します。必要に応じて入力データを参照情報として使用できるほか、評価の説明や推論などの追加情報を出力することもできます。

Python

Scorer は、評価時に weave.Evaluation オブジェクトに渡されます。Weave には 2 種類の Scorer があります。

1. 関数ベースの Scorer: @weave.op でデコレートされたシンプルな Python 関数。
2. クラスベースの Scorer: より複雑な評価向けに weave.Scorer を継承した Python クラス。

Scorer は辞書を返す必要があり、複数のメトリクスやネストされたメトリクスに加えて、LLM 評価器がその推論について返したテキストのような非数値の値も返せます。

TypeScript

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

​

独自のスコアラーを作成する

すぐに使えるスコアラー このガイドではカスタムスコアラーの作成方法を紹介しますが、Weave には、すぐに使用できるさまざまな組み込みスコアラーやローカル SLM スコアラーも用意されています。たとえば、次のようなものがあります。

• ハルシネーション検出
• 要約品質
• 埋め込み類似度
• 有害性検出 (ローカル)
• コンテキスト関連性スコアリング (ローカル)
• その他にもあります。

​

関数ベースのスコアラー

Python

これらは、辞書を返す @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 はテキストがすべて大文字かどうかを確認します。

TypeScript

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

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

より高度な評価、特に scorer の追加メタデータを保持したい場合、LLM 評価器に対して異なるプロンプトを試したい場合、または複数の関数呼び出しを行いたい場合は、Scorer クラスを使用できます。

要件:

1. weave.Scorer を継承します。
2. @weave.op でデコレートされた score メソッドを定義します。
3. 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

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

​

Scorersの仕組み

​

Scorer のキーワード引数

Python

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

• Input: “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 の引数やデータセット列を調整できない場合は、列マッピングを使用できます。詳しくは以下を参照してください。

• Output: 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)

TypeScript

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.op
def summarize_article(article: str, max_length: int) -> str:
    # ここにサマリー生成ロジックを記述
    return summary

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

Variable	Description
{article}	入力引数 article の値
{max_length}	入力引数 max_length の値
{inputs}	すべての入力引数を含む JSON 辞書
{output}	op が返す結果

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

このサマリーの品質を評価してください。

元の記事: {article}
サマリー: {output}
リクエストされた最大長: {max_length}

以下の基準に基づいて、サマリーを1〜10のスケールで評価してください:
- 正確性: 記事の内容を正確に表現しているか？
- 網羅性: 重要なポイントを網羅しているか？
- 簡潔性: 適切に簡潔にまとめられているか？

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

​

Scorer の最終集計

Python

評価時には、データセットの各行に対して Scorer が実行されます。評価の最終スコアを出すために、出力の戻り値のタイプに応じて auto_summarize が提供されています。

• 数値列では平均が計算されます
• 真偽値列では件数と割合が計算されます
• その他の列タイプは無視されます

Scorer クラスの summarize method をオーバーライドして、最終スコアを計算する独自の方法を指定できます。summarize function では、次の内容を想定しています。

• 1つのパラメーター score_rows: これは辞書のリストで、各辞書にはデータセットの1行に対して score method が返したスコアが含まれます。
• 集計したスコアを含む辞書を返す必要があります。

これが役立つ理由

データセットの最終的なスコア値を決める前に、すべての行をスコアリングする必要がある場合に役立ちます。

class MyBinaryScorer(Scorer):
    """
    完全な output が target と一致する場合は 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 の実装を確認してください。

TypeScript

評価時には、データセットの各行に対して Scorer が実行されます。最終スコアを出すために、出力タイプに応じて集計する内部の summarizeResults function を使用します。

• 数値列では平均が計算されます
• 真偽値列では件数と割合が計算されます
• その他の列タイプは無視されます

現時点では、カスタム集計はサポートしていません。

​

call に Scorer を適用する

Weave の op に Scorer を適用するには、オペレーションの結果とそのトラッキング情報の両方にアクセスできる .call() メソッドを使用する必要があります。これにより、Scorer の結果を Weave のデータベース内の特定の call に関連付けることができます。

.call() メソッドの使い方の詳細については、Ops の呼び出し ガイドを参照してください。

Python

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

# result と 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)
)

メモ:

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

Scorer をガードレールやモニターとして使用する方法について、本番環境でのベストプラクティスや完全な例を含むさらに詳しい情報は、Guardrails and Monitors guide を参照してください。

TypeScript

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

​

preprocess_model_input を使用する

preprocess_model_input パラメーターを使用すると、評価中にデータセットの各例がモデルに渡される前に変更できます。

使用方法と例については、評価前に preprocess_model_input を使用してデータセットの行を整形する を参照してください。

​

スコア分析

このセクションでは、特定の scorer が付けた単一の call、複数の call、またはすべての call のスコアを分析する方法を説明します。

​

単一のCallのスコアを分析する

​

単一Call API

単一のCallのcallsを取得するには、get_call methodを使用します。

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

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

# スコアを含むcallのフィードバックを取得する
feedback = list(call.feedback)

​

単一callのUI

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

​

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

​

複数のCalls API

複数のcallに対するcallsを取得するには、get_calls method を使用できます。

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

# 複数のcallsを取得 - 任意のフィルターを使用してフィードバックを含める
calls = client.get_calls(..., include_feedback=True)

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

​

複数の Calls の UI

複数の Calls の score は、トレース表の「Scores」列に表示されます。

​

特定の Scorer がスコア付けしたすべての Calls を分析する

​

ScorerごとのすべてのCall API

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

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

# スコアラーの任意のバージョンによってスコアリングされたすべての Call を取得するには、スコアラー名（通常はクラス名）を使用します
calls = client.get_calls(scored_by=["MyScorer"], include_feedback=True)

# 特定バージョンのスコアラーによってスコアリングされたすべての Call を取得するには、ref 全体を使用します
# ref はスコアラーオブジェクトから取得するか、UI で確認できます。
calls = client.get_calls(scored_by=[myScorer.ref.uri()], include_feedback=True)

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

​

Scorer ごとのすべての Calls を UI で確認する

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

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

デフォルトでは、選択した Scorer のバージョンが表示されます。バージョンのフィルターを解除すると、Scorer の任意のバージョンによってスコア付けされたすべての Calls を確認できます。