> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coreweave.com/llms.txt
> Use this file to discover all available pages before exploring further.
# スコアリングの概要
> Weave Scorer で AI の出力を評価し、評価メトリクスを返します
Weave では、Scorer が AI の出力を評価し、評価メトリクスを返します。Scorer は AI の出力を受け取って分析し、結果を辞書として返します。必要に応じて入力データを参照に使用することもでき、評価の説明や推論などの追加情報を出力することもできます。
このガイドは、AI システムの出力の品質を測定したい開発者を対象としています。Weave の評価における Scorer の役割、独自の Scorer の作成方法、個々の Call に Scorer を適用する方法、得られたスコアの分析方法について説明します。
評価時に、Scorer を `weave.Evaluation` オブジェクトに渡します。Weave は次の 2 つのタイプの Scorer をサポートしています。
1. **関数ベースの Scorer:** `@weave.op` でデコレートされた Python 関数です。
2. **クラスベースの Scorer:** `weave.Scorer` を継承した Python クラスで、より複雑な評価に使用します。
Scorer は辞書を返す必要があります。複数のメトリクスやネストされたメトリクスのほか、LLM 評価者が自身の推論について返すテキストなど、数値以外の値も返すことができます。
Scorer は、評価時に `weave.Evaluation` オブジェクトに渡す特別な Op です。
独自の Scorer を作成する
カスタム Scorer を使用すると、組み込みの Scorer では対応できない、ユースケース固有の評価基準を定義できます。以下のセクションでは、Scorer を定義する 2 つの方法 (関数として定義する方法と、より複雑なロジック向けにクラスとして定義する方法) について説明します。
**すぐに使える Scorer**
このガイドではカスタム Scorer の作成方法を説明しますが、Weave には、すぐに使用できる[事前定義済みScorer](/ja/products/wandb/weave/guides/evaluation/builtin_scorers)と[ローカル SLM Scorer](/ja/products/wandb/weave/guides/evaluation/weave_local_scorers)も用意されています。主な例は次のとおりです。
* [ハルシネーション検出](/ja/products/wandb/weave/guides/evaluation/builtin_scorers#hallucinationfreescorer)
* [要約の品質](/ja/products/wandb/weave/guides/evaluation/builtin_scorers#summarizationscorer)
* [埋め込みの類似度](/ja/products/wandb/weave/guides/evaluation/builtin_scorers#embeddingsimilarityscorer)
* [有害性検出 (ローカル) ](/ja/products/wandb/weave/guides/evaluation/weave_local_scorers#weavetoxicityscorerv1)
* [コンテキスト関連性のスコアリング (ローカル) ](/ja/products/wandb/weave/guides/evaluation/weave_local_scorers#weavecontextrelevancescorerv1)
関数ベースの Scorer
関数ベースの Scorer は、`@weave.op` でデコレートされた、辞書を返す関数です。次のようなシンプルな評価に適しています。
```python lines theme={"system"}
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` を含むオブジェクトを受け取ります。次の例のようなシンプルな評価に適しています。
```typescript lines theme={"system"}
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
Scorer の追加メタデータをトラッキングしたい場合、LLM 評価者でさまざまなプロンプトを試したい場合、複数の関数の Call を行いたい場合など、より高度な評価には `Scorer` クラスを使用します。
**要件:**
1. `weave.Scorer` を継承します。
2. `@weave.op` でデコレートした `score` メソッドを定義します。
3. `score` メソッドは辞書を返す必要があります。
例:
```python lines {7} theme={"system"}
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])
```
このクラスは、要約を元のテキストと比較して、その品質を評価します。
```plaintext theme={"system"}
この機能は TypeScript ではまだ利用できません。
```
Scorer の仕組み
このセクションでは、Scorer が評価からデータを受け取る仕組み、データセットの列を Scorer の引数にマッピングする方法、スコアリング プロンプトで op の変数を参照する方法、および Weave が行ごとのスコアを集計して最終結果を算出する仕組みについて説明します。
Scorer のキーワード引数
Scorer は、AI システムからの出力と、データセット行の入力データの両方にアクセスできます。
* **入力:** データセット行のデータ (`label` 列や `target` 列など) を Scorer で使用したい場合は、Scorer の定義に `label` または `target` キーワード引数を追加して、そのデータを Scorer から利用できるようにします。
たとえば、データセットの `label` という列を使用する場合、Scorer 関数 (または `score` クラスメソッド) のパラメーターリストは次のようになります。
```python lines theme={"system"}
@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}` の順序で指定します。
例:
```python lines theme={"system"}
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` メソッドをオーバーロードし、列を明示的にマッピングすることもできます。
```python lines theme={"system"}
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` キーワード引数を追加すると、データセット行の該当する列にアクセスできます。
```typescript twoslash lines theme={"system"}
// @noErrors
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}` の形式です。
例:
```typescript twoslash lines theme={"system"}
// @noErrors
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 によって自動的に抽出されます。
たとえば、次のような関数があるとします。
```python theme={"system"}
@weave.op
def summarize_article(article: str, max_length: int) -> str:
# ここに要約ロジックを記述します
return summary
```
以下の変数を使用できます。
| 変数 | 説明 |
| - | - |
| `{article}` | 入力引数 `article` の値 |
| `{max_length}` | 入力引数 `max_length` の値 |
| `{inputs}` | すべての入力引数を含む JSON 辞書 |
| `{output}` | op から返された結果 |
スコアリング プロンプトの例:
```text theme={"system"}
この要約の品質を評価してください。
元の記事: {article}
要約: {output}
指定された最大長: {max_length}
以下の観点に基づいて、要約を 1〜10 の 10 段階で評価してください。
- 精度: 記事の内容を正確に表していますか？
- 網羅性: 要点を漏れなく押さえていますか？
- 簡潔性: 適度に簡潔にまとめられていますか？
評価とその理由を含む JSON オブジェクトを返してください。
```
Scorer の最終集計
評価中、Weave はデータセットの各行に対して scorer を計算します。評価の最終スコアを算出するため、Weave は出力の戻り値の型に基づいて `auto_summarize` を実行します。
`Scorer` クラスの `summarize` メソッドを上書きすると、最終スコアを独自の方法で計算できます。`summarize` 関数の仕様は次のとおりです。
* 単一のパラメーター `score_rows` を受け取ります。これは辞書のリストで、各辞書にはデータセットの 1 行に対して `score` メソッドが返したスコアが含まれます。
* 集計されたスコアを含む辞書を返します。
**このメリット**
データセット全体の最終スコアを決める前に、すべての行をスコアリングしておく必要がある場合に役立ちます。
```python lines theme={"system"}
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](/ja/products/wandb/weave/tutorial-rag#optional-defining-a-scorer-class) の実装を参照してください。
評価中、Weave はデータセットの各行に対して scorer を計算します。最終スコアの算出には、出力のタイプに応じて集計を行う内部関数 `summarizeResults` が使用されます。
Weave はカスタムの集計をサポートしていません。
Call に Scorer を適用する
Scorer は `weave.Evaluation` の一部として実行するだけでなく、個々の Call に直接適用することもできます。本番トラフィックをスコアリングしたい場合や、特定の Op の invocation に評価メトリクスを付与したい場合に便利です。
Weave Op に Scorer を適用するには、`.call()` メソッドを使用します。このメソッドを使うと、操作の結果とそのトラッキング情報の両方にアクセスできるため、Scorer の結果を Weave のデータベース内の特定の Call に関連付けることができます。
`.call()` メソッドの使用方法の詳細については、[Op の呼び出し](/ja/products/wandb/weave/guides/tracking/tracing#getting-a-handle-to-the-call-object-during-execution)ガイドを参照してください。
基本的な例を次に示します。
```python lines theme={"system"}
# 結果と Call オブジェクトの両方を取得
result, call = generate_text.call("Say hello")
# Scorer を適用
score = await call.apply_scorer(MyScorer())
```
同じ Call に複数の Scorer を適用することもできます。
```python lines theme={"system"}
# 複数の Scorer を並列に適用
await asyncio.gather(
call.apply_scorer(quality_scorer),
call.apply_scorer(toxicity_scorer)
)
```
**メモ:**
* Weave は Scorer の結果を自動的にデータベースに保存します。
* Scorer は、メインの操作が完了した後に非同期で実行されます。
* Scorer の結果は、UI で確認したり、API でクエリしたりできます。
本番環境でのベストプラクティスや完全な設定例など、Scorer をガードレールやモニターとして使用する方法の詳細については、[ガードレールとモニターのガイド](/ja/products/wandb/weave/guides/evaluation/monitors)を参照してください。
```plaintext theme={"system"}
This feature is not available in TypeScript yet.
```
`preprocess_model_input` パラメーターを使用すると、評価時にデータセットのサンプルがモデルに渡される前に、そのサンプルを変更できます。
`preprocess_model_input` 関数が変換するのは、Weave がモデルの予測関数に渡す入力のみです。
Scorer 関数には、前処理が一切適用されていない元のデータセットのサンプルが常に渡されます。
使用方法とサンプルについては、[評価前に `preprocess_model_input` を使用してデータセットの行をフォーマットする](/ja/products/wandb/weave/guides/core-types/evaluations#using-preprocess_model_input-to-format-dataset-rows-before-evaluating)を参照してください。
スコア分析
Scorer の実行後は、モデルの動作を把握したりバージョンを比較したりするために、生成されたスコアを確認したい場面がよくあります。以下のセクションでは、API と Weights & Biases UI を使用して、単一の Call、複数の Call、および特定の Scorer でスコア付けされたすべての Call のスコアを分析する方法について説明します。
個々の Call のスコアを分析する
単一 Call 用の API
単一の Call を取得するには、`get_call` メソッドを使用します。
```python lines theme={"system"}
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` メソッドを使用します。
```python lines theme={"system"}
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` メソッドを使用します。
```python lines theme={"system"}
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 を表示できます。
## Related topics
- [評価の概要](/ja/products/wandb/weave/guides/core-types/evaluations.md)