EvaluationおよびOperation Type

WhaTap LLM Observabilityは、運用中のLLMアプリケーションのレスポンス品質と安定性を自動で測定するEvaluation機能と、LLM呼び出しをシステムプロンプト単位でグループ化・フィルタリングするOperation Typeラベリングを提供します。どちらの機能もユーザートランザクションのレスポンス時間に影響を与えないように設計されており、コードにデコレーターを1行追加するだけで適用できます。

ノート

現在（2026年6月時点）、Evaluation、Operation Typeのラベリング機能はPythonのみ対応しています。

Evaluation

Evaluationは、LLMのレスポンスに対してハルシネーション、回答の関連性、有害性（toxicity）、プロンプトインジェクション、事実性（factuality）、PII漏洩、疑わしいURLなどの評価を自動で適用する機能です。評価結果はスコア（0.0～1.0）として算出され、メトリクスとログシンクにあわせて収集されるため、レスポンス品質を時系列で追跡し、しきい値ベースのアラートを構成できます。

ノート

judge LLMの呼び出しには、ユーザー呼び出しで使用していたclientインスタンスをそのまま再利用します。そのため、評価パイプラインを有効にすると、ユーザーへのレスポンスのためのLLM呼び出しとは別に、judge呼び出しの分だけLLMリソース（トークン・コスト）が追加で発生します。

設定オプション

キー	既定値	説明
`llm_eval_enabled`	`false`	評価パイプラインのマスタートグル。`false`の場合、キューへの積載およびワーカーは動作しません。
`llm_eval_sample_rate`	`1.0`	評価のサンプリング比率（1.0 == 100%の比率です）。
`llm_eval_buffer_limit`	`1000`	評価キューの最大サイズ。超過すると評価がドロップされ、`LLM030`警告が発生します。
`llm_eval_workers`	`4`	評価器を実行するThreadPoolExecutorのワーカー数。
`llm_eval_judge_timeout_sec`	`30`	judge LLMの1回の呼び出しの最大待機時間（秒）。超過すると`judge_error`として処理されます。`0`または負の値の場合は無制限です。

使用方法

Evaluationは、特定の関数にのみ適用するデコレーター方式と、アプリケーション全体に適用する方式のいずれかを選択できます。

方式A — デコレーター（特定の関数のLLM呼び出しのみ評価）

from whatap.llm.evaluators import evaluate_with
from whatap.llm.evaluators.builtins import CombinedJudgeEvaluator

@evaluate_with(CombinedJudgeEvaluator())
def chat(q):
    ...

方式B — アプリ全体への登録（すべてのLLM呼び出しにalways-onで適用）

from whatap.llm.evaluators import register_evaluator
from whatap.llm.evaluators.builtins import CombinedJudgeEvaluator

register_evaluator(CombinedJudgeEvaluator())  # アプリ起動時に一度だけ呼び出す

登録可能な評価器クラス

from whatap.llm.evaluators.builtins import (
    # LLM judgeベース — judge呼び出しのコストが発生
    CombinedJudgeEvaluator,
    HallucinationEvaluator,
    AnswerRelevanceEvaluator,
    ToxicityEvaluator,
    PromptInjectionEvaluator,
    FactualityEvaluator,
   
    # ルールベース — LLM呼び出しなし、コスト0
    PIILeakEvaluator,
    URLScanEvaluator,
)

Evaluationクラスの説明

Evaluator	LABEL	種類	スコアの方向	コスト
`CombinedJudgeEvaluator`	`combined_judge`	LLM judge	総合リスク — 低いほど良い	judge 1回で5つのaspect
`HallucinationEvaluator`	`hallucination`	LLM judge	低いほど良い	judge 1回
`AnswerRelevanceEvaluator`	`answer_relevance`	LLM judge	高いほど良い	judge 1回
`ToxicityEvaluator`	`toxicity`	LLM judge	低いほど良い	judge 1回
`PromptInjectionEvaluator`	`prompt_injection`	LLM judge	低いほど良い	judge 1回
`FactualityEvaluator`	`factuality`	LLM judge	高いほど良い	judge 1回

各Evaluationが測定する項目は次のとおりです。

answer_relevance: 回答の関連性（高いほど良い）

レスポンスがユーザーの質問にどれだけ忠実に答えているかを測定します。質問に完全に答えている場合は1.0、部分的・周辺的にしか答えていない場合は0.5、質問と無関係、または回避・逸脱している場合は0.0と採点されます。
hallucination: ハルシネーション（低いほど良い）

レスポンスに根拠のない主張が含まれているかを測定します。コンテキスト（ground truth）が与えられている場合はコンテキストに対する忠実性（faithfulness）を、コンテキストがない場合はレスポンス自体の自己一貫性（self-consistency）を基準に評価します。0.0はコンテキストに完全に忠実な状態、1.0は全面的に捏造された状態です。
toxicity: 有害性（低いほど良い）

レスポンスに有害なコンテンツが含まれているかを、hate / harassment / violence / sexual / self_harm / profanityの6カテゴリを基準に判定し、検出されたカテゴリの一覧もあわせて返します。0.0は完全に安全、1.0は深刻に有害な状態です。
prompt_injection: プロンプトインジェクション（低いほど良い）

ユーザー入力に含まれる「ignore previous instructions」のようなオーバーライドの試みが成功したか、あるいはレスポンスがシステムプロンプト・隠された指示・機密情報を漏洩したかを判定します。0.0は本来のタスクをそのまま実行し、保護対象の情報を一切公開していない状態、1.0はインジェクションに完全に乗っ取られた状態です。
factuality: 事実性（高いほど良い）

レスポンスの事実的な正確さを測定します。歴史・科学・地理・数学的な事実や、日付・名前・数値など検証可能な客観的主張を基準とし、意見や婉曲的な表現は評価対象から除外します。1.0はすべての事実主張が正確な状態、0.0は明らかに虚偽の主張が多数含まれる状態です。コンテキストへの忠実性を見るhallucinationとは異なり、factualityはコンテキストとは無関係にレスポンス自体の事実的な正確さを見ます。

Combined Judge

どの評価器を登録するかによって、judge LLMの呼び出し回数は大きく変わります。

個別の評価器を登録（5回の呼び出し）hallucination / answer_relevance / toxicity / prompt_injection / factualityをそれぞれ登録すると、評価ごとに別々のjudge LLM呼び出しが発生し、レスポンス1件当たり5回呼び出しされます。

combined_judgeを登録（1回の呼び出し、既定で推奨）CombinedJudgeEvaluatorは5つのaspectを1つの統合評価リクエストにまとめ、judge LLMを1回だけ呼び出し、その結果として5つのaspectのスコアをすべて受け取ります。個別の評価器を5つ登録する場合と比べてjudge呼び出しのコストを約80%削減できるため、既定での使用を推奨します。

総合リスクスコア（combined_judge）

combined_judgeは5つのaspectのスコアを1つの総合リスク（risk）に合算します。その際、スコアの方向が異なる2つのグループをリスク基準に統一します。

リスク方向のaspect（hallucination、toxicity、prompt_injection）— スコアが高いほど危険なため、スコアをそのままリスクとして使用します。
品質方向のaspect（answer_relevance、factuality）— スコアが高いほど良いため、1 − scoreをリスクとして使用します。

各aspectを独立したリスクと仮定し、「すべてのaspectが安全である確率」の補数（complement）として総合リスクを計算します。統計学のProbabilistic ORの公式です。

Probabilistic OR公式

計算例

リスクが[0.7, 0.3, 0.1, 0.1, 0.2]の場合: 1 − (0.3 × 0.7 × 0.9 × 0.9 × 0.8) = 0.864

リスク合算の特性（シミュレーション）

個別リスク	最大値（max）	総合（compound）
`[0.5, 0, 0, 0, 0]`	0.50	0.50
`[0.5, 0.5, 0, 0, 0]`	0.50	0.75
`[0.3, 0.3, 0.3, 0.3, 0.3]`	0.30	0.83
`[1.0, 0, 0, 0, 0]`	1.00	1.00

総合リスクは、単純な最大値より常に大きいか等しくなります。低いリスクであっても複数のaspectにわたって蓄積されると総合リスクはその分高くなり、いずれか1つのaspectが1.0であれば、残りに関係なく総合リスクも1.0になります。これにより、単一の指標では見逃しやすい「複数の領域で同時に少しずつ悪いレスポンス」を効果的に捉えることができます。

Operation Type

Operation Typeは、LLM呼び出しをprompt / chain / agent単位でグループ化・フィルタリングするためのユーザー定義ラベルです。指定したラベルはメトリクスのdimensionの一部になるため、prompt単位でレイテンシ・コスト・評価スコアを分けて分析できます。

設定キー

キー	意味	既定値
`operation_type`	prompt / chain / agentの名前	`'default'`
`prompt_version`	プロンプトバージョン	`'v1'`

使用方法

(a) デコレーター（推奨）
from whatap.llm import prompt_meta

@prompt_meta(operation_type='checkout_chain', prompt_version='v3')
def checkout(question):
    return client.chat.completions.create(...)

(b) コンテキストマネージャー
from whatap.llm import prompt_meta_scope

def handler(req):
    with prompt_meta_scope(operation_type='greeting', prompt_version='v2'):
        return client.chat.completions.create(...)

現在アクティブなmetaの照会（カスタムロジックで）
from whatap.llm import get_prompt_meta

op_type, version = get_prompt_meta()  # スコープがない場合は('default', 'v1')を返します

Evaluation​

設定オプション​

使用方法​

Evaluationクラスの説明​

Combined Judge​

総合リスクスコア（combined_judge）​

Operation Type​

設定キー​

使用方法​

Evaluation

設定オプション

使用方法

Evaluationクラスの説明

Combined Judge

総合リスクスコア（combined_judge）

Operation Type

設定キー

使用方法