Langfuseのスコア機能入門

Langfuseのスコア機能の紹介です。

Langfuseのスコア機能

Langfuse には「スコア」という概念があり、次の 3 種類¹のスコアを扱うことができます。

• 数値スコア（Numeric）
• カテゴリスコア（Categorical）
• 二値スコア（Binary）

これらのスコアはTraceやObservationに付与でき、LangfuseのDashboard²やScoreAnalytics³を用いた可視化・分析に利用できます。

スコアの付与は、人間による評価（Human Annotaion機能⁴）やLLMによる評価（LLM as a Judge機能⁵）の結果として付与されます。

スコア分析機能は、2025年11月初旬のLaunchWeekで発表された新機能です。まだ私自身も十分に触れていないため詳細は把握できていませんが、スコアをつけるだけで有益なインサイトが得られるのであれば非常に嬉しいアップデートです。

https://langfuse.com/changelog/2025-11-07-score-analytics-multi-score-comparison

スコアの作成

スコアはLangfuse UIの[Settings] -> [Score/Evaluation]から作成することができます。

例として以下のようなカテゴリスコアを作成してみます。

• Name: Smaple
• Data type: CATEGORICAL
• Value: foo/var

スコアは削除ができず、アーカイブのみ可能な点には注意が必要です。LagnfuseのUIをよく見ると下記の記載があり、運用時には慎重に命名規則を設計する必要がありそうです。

Please note that all score configs are immutable.

スコアの付与

スコアの付与方法は複数あります。

• LLM as a Judgeを利用して付与する方法
• Human Annotationを利用して人間に付与させる方法
• Tracing画面から付与する方法
• Langfuse SDKを利用して付与する方法

などなど。

ここでは、説明が簡単な（１）Tracing画面から付与する方法と、（２）Langfuse SDKを利用してスコアを付与する方法を紹介します。

（１）Tracing画面から付与する方法

Tracing画面からスコアを付与したいトレースまたはObservationを選択し、[Annotate]を押下します。

Selectから先ほど作成したSmapleを選ぶと、下記のような画面になり、fooまたはvarを選択できるUIが表示されます。

fooまたはvarを選択しスコアを付与すると、付与したトレース（またはObservation）にスコアが表示されます。下記はトレースにfooのスコアを付与した場合の画像です。スコアを変更したい場合は[Annotate]から付与したいスコアの値を再度選択すること変更できます。

（２）Langfuse SDKを利用して付与する方法

ドキュメントでは3種類の方法が紹介されています。

まずは、紐づけたいトレースまたはObservationなどのIDを指定してスコアを付与する方法です。この場合、IDさえ分かっていれば良いので、実際のトレースやObseravationを生成しているLLMアプリケーションとは非同期でスコアを付与できます。

langfuse.create_score(
    name="correctness",
    value=0.9,
    trace_id="trace_id_here",
    observation_id="observation_id_here", # optional
    session_id="session_id_here", # optional, Id of the session the score relates to
    data_type="NUMERIC", # optional, inferred if not provided
    comment="Factually correct", # optional
)

次にコンテキスト経由でスコアを付与する方法です。この場合、トレースやObservationの生成と同じタイミングでスコアを付与する必要があります。

# Method 2: Score current span/generation (within context)
with langfuse.start_as_current_observation(as_type="span", name="my-operation") as span:
    # Score the current span
    span.score(
        name="correctness",
        value=0.9,
        data_type="NUMERIC",
        comment="Factually correct"
    )
 
    # Score the trace
    span.score_trace(
        name="overall_quality",
        value=0.95,
        data_type="NUMERIC"
    )
 
 
# Method 3: Score via the current context
with langfuse.start_as_current_observation(as_type="span", name="my-operation"):
    # Score the current span
    langfuse.score_current_span(
        name="correctness",
        value=0.9,
        data_type="NUMERIC",
        comment="Factually correct"
    )
 
    # Score the trace
    langfuse.score_current_trace(
        name="overall_quality",
        value=0.95,
        data_type="NUMERIC"
    )

Dashbordを利用したスコアの可視化

スコアはDashboard機能を利用することで、さまざまな可視化が可能です。まず、Dashboards画面から[New dashboard]を押下し新しいDashboardを作成しましょう。

Dashboardを作成したら、[Dashborads]->[Add widget]->[Create New Widget]で下記のように設定して[Save Widget]を押下してください。

• View: Scores Categorical
• Metrics: Count
• Dimension1: Name
• Dimension2: String Value
• Chart Type: Pivot Table

すると下記のようなWidgetが作成されます。事前に幾つかのTraceにfoo/varのスコアを付与していたため、その集計結果が反映されています。この３時間でfooの値をもつスコアが4個、varの値を持つスコアが3個発生したことが分かります。

今回はトレースやObservationの話が中心になっていますが、プロンプトにもスコア情報は連携されます。正確には、プロンプトから生成したObservationにスコアが付与されると、プロンプトにもスコア情報が連携され、プロンプトを評価する際の尺度として利用できます。

1. https://langfuse.com/docs/evaluation/evaluation-methods/custom-scores#inferred-score-properties ↩

2. https://langfuse.com/docs/metrics/features/custom-dashboards ↩

3. https://langfuse.com/docs/evaluation/evaluation-methods/score-analytics ↩

4. https://langfuse.com/docs/evaluation/evaluation-methods/annotation ↩

5. https://langfuse.com/docs/evaluation/evaluation-methods/llm-as-a-judge ↩