exploring-llm-evaluations

AI オブザーバビリティ評価の概要

保存済みのオフライン実験の比較、スコアラー履歴、外部で計算した結果のアップロードには、analyzing-offline-evaluations を使用してください。オフライン実験では、固定されたスコアラー設定を使用し、以下のオンライン評価とは別の結果 API を使用します。

PostHog の評価では、$ai_generation イベントをスコアリングします。評価には次の 3 種類があります。

• hog — ブール値、数値スコア、カテゴリ（および任意で N/A）を返す決定論的な Hog コードです。 客観的なルールベースのチェックに最適です。形式の検証（JSON の解析、スキーマとの一致）、長さの制限、キーワードの有無、正規表現パターン、構造的なアサーション、レイテンシのしきい値、コストの制限などに使用できます。安価で高速かつ再現性があり、実行ごとに LLM を呼び出しません。基準をコードで表現できる場合は、こちらを優先してください。
• llm_judge — 作成したプロンプトに基づいて、LLM が生成結果をスコアリングします。 トーン、有用性、ハルシネーションの検出、話題からの逸脱、指示への準拠など、主観的または曖昧なチェックに最適です。実行ごとに LLM の呼び出しが必要で、組織レベルで AI データ処理の承認が必要です。
• sentiment — 一致する各生成に含まれるユーザーメッセージからセンチメントを分類します。合否判定ではなく、センチメントラベルとスコアを返します。

すべての種類の結果は、$ai_evaluation イベントとして ClickHouse に保存されます。ブール値の評価（llm_judge と hog）では $ai_evaluation_result が設定されます。センチメント評価では、代わりに $ai_sentiment_* プロパティが設定されます。 hog と llm_judge は、output_type: "numeric" にも対応しています。 数値の実行結果は、生のスコアとして $ai_evaluation_numeric_result に保存されます。任意で $ai_evaluation_numeric_result_min と $ai_evaluation_numeric_result_max も保存できます。 これらの実行結果で $ai_evaluation_result が設定されることはありません。 スコアの解釈には output_config.passing_rule を使用します。gte はしきい値以上、lte はしきい値以下を意味します。 ルールを変更すると、過去のスコアも再解釈されます。保存済みのレポートには、生成時に使用したルールとメトリクスが保持されます。 合格ルールがない場合は、スコアの平均値と分布を確認してください。合格率とレポートは利用できません。

カテゴリ評価がプロジェクトで有効になっている場合、どちらのランタイムも output_type: "categorical" に対応しています。 設定された {key, label} ペアは output_config.options から、single または multiple の選択モードは selection_mode から確認できます。 結果はキーのリストとして $ai_evaluation_categorical_result に保存されます。単一選択ではキーが必ず 1 つ必要ですが、複数選択では [] も使用できます。 Hog は単一選択モードで、キーを表す文字列を 1 つ返すこともできます。 結果の評価には output_config.passing_rule.categories を使用します。結果が空でない場合、返されたすべてのキーが合格カテゴリである場合にのみ合格します。 空でないルールでは [] は不合格になります。空のルールでは [] だけが合格となり、複数選択モードでのみ使用できます。 ルールがない場合は、合格率ではなくカテゴリの出現頻度を確認してください。新しいレポートは利用できません。 ルールを編集すると過去の結果が再分類されますが、保存済みのレポートにはルールのスナップショットが保持されます。

このスキルでは、評価設定の一覧表示、詳細の確認、管理、特定の生成への実行、個々の結果の照会、最近の実行結果を定期的に要約する評価レポートの設定まで、ライフサイクル全体を扱います。

ツール

ツール	目的
posthog:llma-evaluation-list	評価設定を一覧表示／検索します（名前、有効フラグで絞り込み）
posthog:llma-evaluation-get	UUIDで単一の評価設定を取得します
posthog:llma-evaluation-create	新しい llm_judge、hog、または sentiment の評価を作成します
posthog:llma-evaluation-update	既存の評価を更新します（名前、プロンプト、有効状態など）
posthog:llma-evaluation-delete	評価を論理削除します
posthog:llma-evaluation-run	特定の $ai_generation イベントに対して評価を実行します
posthog:llma-evaluation-test-hog	最近の生成を対象にHogソースをドライランします（保存しません）
posthog:llma-evaluation-report-list	評価に関連付けられたレポート設定を一覧表示します
posthog:llma-evaluation-report-create	評価に関するAIレポートをスケジュールします（メールまたはSlack）
posthog:llma-evaluation-report-run-list	過去のレポート実行と、送信されたレポートの内容を一覧表示します
posthog:execute-sql	$ai_evaluation イベントに対してアドホックなHogQLを実行します
posthog:query-llm-trace	評価のスコアリング対象となった基になる生成を詳しく調べます

すべての llma-evaluation-* ツールは products/ai_observability/mcp/tools.yaml で定義されています。

イベントスキーマ

評価を実行するたびに、$ai_evaluation イベントが出力されます。主なプロパティは次のとおりです。

プロパティ	意味
$ai_evaluation_id	評価設定の UUID
$ai_evaluation_name	人が読みやすい名前
$ai_target_event_id	採点対象の $ai_generation イベントの UUID
$ai_trace_id	親トレース ID（トレース UI に移動するためのもの）
$ai_evaluation_result_type	結果の種類：boolean、numeric、categorical、sentiment
$ai_evaluation_numeric_result	数値スコアの生値。合格ルールを使って合格または不合格に変換します
$ai_evaluation_categorical_result	カテゴリーキーのリスト。合格ルールを使って合格または不合格に変換します
$ai_evaluation_result	真偽値の生の結果。評価の出力設定を使って合格または不合格に変換します
$ai_evaluation_reasoning	自由記述の説明（LLM の評価者または Hog コードによって設定されます）
$ai_evaluation_applicable	評価器が生成を N/A と判断した場合は false
$ai_evaluation_skipped	実行を評価できず、結果が採点されなかった場合は true
$ai_sentiment_label	感情評価の場合：positive、neutral、negative
$ai_sentiment_score	最も有力な感情ラベルの信頼度スコア

まず $ai_evaluation_skipped を確認してください。スキップされた実行は合格率から除外され、N/A とは別に扱われます。 それ以外の場合、$ai_evaluation_applicable = false は、結果の値にかかわらず N/A を意味します。 N/A をサポートしない評価では、このプロパティが null になる場合があります。null は「該当する」として扱ってください。 真偽値評価では、output_config.true_is_failure: false の場合、true は合格に、false は不合格に変換されます。 true が評価器による問題の検出を意味する検出器スタイルの評価では、この値を true に設定してください。

失敗判定条件

イベントには合否ではなく、未加工の結果が保存されます。PostHog はイベントを読み取る際に、評価の現在の output_type と output_config を適用します。llma-evaluation-get が返す設定から <fail predicate> を組み立て、以下のクエリで失敗を 絞り込む場合は常に使用してください。

評価	<fail predicate>
boolean、true_is_failure が false または未設定	properties.$ai_evaluation_result = 'false'
boolean、true_is_failure: true（検出器）	properties.$ai_evaluation_result = 'true'
numeric、passing_rule がしきい値 T に対して gte	toFloat(properties.$ai_evaluation_numeric_result) < T
numeric、passing_rule がしきい値 T に対して lte	toFloat(properties.$ai_evaluation_numeric_result) > T
categorical、passing_rule.categories が [a,b]	NOT (notEmpty(<cats>) AND hasAll(['a', 'b'], <cats>))
categorical、passing_rule.categories が []	notEmpty(<cats>)
passing_rule のない numeric または categorical	なし。スコアまたはカテゴリを直接読み取ります。合否はありません

<cats> は JSONExtract(ifNull(properties.$ai_evaluation_categorical_result, '[]'), 'Array(String)') です。 スキップされた実行でも result = false が保存されることがあるため、常に (isNull(properties.$ai_evaluation_skipped) OR properties.$ai_evaluation_skipped != 'true') を追加してください。Boolean プロパティ定義のないプロジェクトでは、これらのプロパティは文字列として読み取られます。そのため、裸の true または false との比較は失敗します。値は文字列 'true' および 'false' と比較してください。

ワークフロー：評価が失敗する理由を調査する

llm_judge と hog の評価では同じ手順を使用します。違いが関係するのは、評価器を修正する段階（プロンプトを編集するか、 Hog ソースを編集するか）だけです。センチメント評価では、合否フィルターではなくセンチメントラベルとスコアを使って調査してください。 以下のクエリでは、上の表にある評価の <fail predicate> を使用します。

ステップ 1 — 評価を見つける

posthog:llma-evaluation-list
{ "search": "hallucination", "enabled": true }

返された id、name、evaluation_type と、次のいずれかを確認してください。

• llm_judge の場合は evaluation_config.prompt
• hog 評価器の場合は evaluation_config.source

Hog 評価器が合格または失敗する理由の根拠となるのは Hog ソースです。生成に原因があると決めつける前に、ソースを 読んでください。

ステップ 2 — 合格、失敗、該当なしを分類する

posthog:execute-sql
SELECT
    countIf(properties.$ai_evaluation_applicable = 'false') AS na_count,
    countIf((isNull(properties.$ai_evaluation_applicable) OR properties.$ai_evaluation_applicable != 'false') AND NOT (<fail predicate>)) AS pass_count,
    countIf((isNull(properties.$ai_evaluation_applicable) OR properties.$ai_evaluation_applicable != 'false') AND (<fail predicate>)) AS fail_count
FROM events
WHERE event = '$ai_evaluation'
    AND properties.$ai_evaluation_id = '<evaluation_uuid>'
    AND (isNull(properties.$ai_evaluation_skipped) OR properties.$ai_evaluation_skipped != 'true')
    AND timestamp >= now() - INTERVAL 7 DAY

評価にすでにレポート設定がある場合は、llma-evaluation-report-list と llma-evaluation-report-run-list を使うと、過去の期間に AI が作成したレポートを確認できます。状況の変化を手早く把握できます。

ステップ 3 — 失敗した実行を読む

パターンが現れるのは推論テキストです。最近の失敗を取得して読みましょう。

posthog:execute-sql
SELECT
    properties.$ai_target_event_id AS generation_id,
    properties.$ai_trace_id AS trace_id,
    properties.$ai_evaluation_reasoning AS reasoning,
    timestamp
FROM events
WHERE event = '$ai_evaluation'
    AND properties.$ai_evaluation_id = '<evaluation_uuid>'
    AND (<fail predicate>)
    AND (isNull(properties.$ai_evaluation_applicable) OR properties.$ai_evaluation_applicable != 'false')
    AND (isNull(properties.$ai_evaluation_skipped) OR properties.$ai_evaluation_skipped != 'true')
    AND timestamp >= now() - INTERVAL 7 DAY
ORDER BY timestamp DESC
LIMIT 25

N/A ガード（IS NULL OR != false）は重要です。バックエンドが実行を分類するときに使うロジックと一致します。

ステップ 4 — 失敗した実行の例を詳しく調べる

ステップ 3 で見つけた、最も代表的な行を選び、元のトレースを取得します。

posthog:query-llm-trace
{ "traceId": "<trace_id>", "dateRange": {"date_from": "-30d"} }

（生成 ID しかない場合は、まず execute-sql で検索し、親トレース ID を見つけてください。）

ワークフロー：特定の生成に対して評価を実行する

ユーザーがトレースまたは生成の URL を貼り付け、「評価 X ならこれについてどう判断しますか？」と尋ねたときに使用します。

posthog:llma-evaluation-run
{
  "evaluationId": "<eval_uuid>",
  "target_event_id": "<generation_event_uuid>",
  "timestamp": "2026-04-01T19:39:20Z",
  "event": "$ai_generation"
}

対象イベントを ClickHouse で効率よく検索するには、timestamp が必要です。distinct_id が分かる場合は渡してください。検索がさらに速くなります。

ワークフロー：新しい評価器を作成してテストする

Hog 評価器（決定論的、コードベース）

評価基準がルールベースの場合は、まずこちらを使用してください。低コストで高速、かつ再現可能です。llma-evaluation-test-hog で保存せずにプロトタイプを作成します。

posthog:llma-evaluation-test-hog
{
  "source": "return event.properties.$ai_output_choices[1].content contains 'sorry';",
  "sample_count": 5,
  "allows_na": false
}

ハンドラーは、サンプリングされたユニットに対して、生のブール値、数値、またはカテゴリ値を返します。数値またはカテゴリ値のプレビューでは、保存済みの output_type と output_config を送信してください。null を許可する場合は、allows_na: true も含めます。期待どおりに動作するまでソースを調整してから、llma-evaluation-create で有効化します。

posthog:llma-evaluation-create
{
  "name": "Output is valid JSON",
  "description": "Fails when the assistant message can't be parsed as JSON",
  "evaluation_type": "hog",
  "evaluation_config": {
    "source": "let raw := event.properties.$ai_output_choices[1].content; try { jsonParseStr(raw); return true; } catch { return false; }"
  },
  "output_type": "boolean",
  "enabled": true
}

Hog 評価器はイベントとそのプロパティに全面的にアクセスできます。よくあるパターンには、スキーマ検証、長さやトークン数の上限チェック、正規表現による一致確認、ツール呼び出しの形式チェックなどがあります。決定論的なため、再実行しても結果を再現でき、差分も容易に確認できます。

LLM ジャッジ評価器（主観的、プロンプトベース）

評価基準が曖昧で、コードによるルールでは融通が利かない場合（口調、事実性、有用性、話題との関連性など）は、こちらを使用してください。LLM ジャッジには llma-evaluation-test-hog に相当するものはありません。一般的な手順は、enabled: false を指定して評価器を作成し、llma-evaluation-run で代表的な生成結果をいくつか手動で評価し、結果を確認して、llma-evaluation-update でプロンプトを調整することです。納得できたら、enabled: true に切り替えます。

posthog:llma-evaluation-create
{
  "name": "Response stays on-topic",
  "description": "LLM judge — fails if the assistant changes topic from the user's question",
  "evaluation_type": "llm_judge",
  "evaluation_config": {
    "prompt": "You are evaluating whether the assistant's reply stays on-topic relative to the user's most recent question. Return true if it does, false if the assistant changed the subject. Return N/A if the user did not actually ask a question."
  },
  "output_type": "boolean",
  "output_config": { "allows_na": true },
  "model_configuration": {
    "provider": "openai",
    "model": "gpt-5-mini"
  },
  "enabled": false
}

次に、既知の良好な生成結果と不良な生成結果に対してドライランを実行します。

posthog:llma-evaluation-run
{
  "evaluationId": "<new_eval_uuid>",
  "target_event_id": "<generation_uuid>",
  "timestamp": "2026-04-01T19:39:20Z"
}

LLM ジャッジを使用するには、組織による AI データ処理の承認が必要です。Hog 評価器には必要ありません。

ワークフロー：評価ライフサイクルの管理

操作	ツール
Hog 評価器を追加	llma-evaluation-create に evaluation_type: "hog" と evaluation_config.source を指定します
LLM ジャッジ評価器を追加	llma-evaluation-create に evaluation_type: "llm_judge"、evaluation_config.prompt、および model_configuration を指定します
ソースまたはプロンプトを調整	llma-evaluation-update（Hog の場合は evaluation_config.source、LLM ジャッジの場合は evaluation_config.prompt を編集します）
N/A の処理を切り替え	llma-evaluation-update に output_config.allows_na を指定します
失敗時の判定極性を設定	llma-evaluation-update に output_config.true_is_failure を指定します
一時的に無効化	llma-evaluation-update に enabled: false を指定します
削除	llma-evaluation-delete（PATCH {deleted: true} によるソフト削除）

llm_judge 評価には、組織レベルでの AI データ処理の承認（is_ai_data_processing_approved）が必要です。Hog 評価にはこの承認は不要です。Hog 評価は取り込みパイプライン上で通常のコードとして実行されます。

Hog と LLM judge を使い分けるタイミング

基本的には Hog を使いましょう。基準をコードで表現できない場合にのみ、LLM judge に切り替えます。

Hog を使う場合…	LLM judge を使う場合…
チェックが構造的な場合（JSON の解析、スキーマとの一致）	チェックが意味に関する場合（話題に沿っている、有用、事実に即している）
決定論的で再現可能な結果が必要な場合	多少の判断のばらつきを許容できる場合
基準の計算コストが低い場合	基準の判定にテキストの読解と理解が必要な場合
AI データ処理の承認を得られない場合	承認を得ており、基準が実際に曖昧な場合
厳格な上限（長さ、コストなど）を適用したい場合	品質の側面を評価したい場合
ミリ秒未満の評価を求める場合	数百ミリ秒と LLM のコストを許容できる場合

よくあるパターンは 組み合わせて使う ことです。Hog 評価器で明らかな形式や長さの違反を低コストで判定し、Hog のゲートを通過した生成結果に対してのみ、LLM judge 評価器を実行します（conditions 経由）。

調査パターン

診断方法は、評価器が hog か llm_judge かにかかわらず同じです。評価器自体ではなく、結果として生成された $ai_evaluation イベントを確認します。修正方法（Hog のソースを編集するか、プロンプトを編集するか）は異なりますが、診断方法は同じです。

「評価 X が突然以前より失敗するようになったのはなぜですか？」

1. llma-evaluation-list — 評価が引き続き有効で、変更されていないことを確認します（evaluation_config.source または evaluation_config.prompt を想定しているバージョンと比較します）

2. 直近の失敗した実行とその推論を読み（上記のステップ 3）、主な失敗パターンごとに分類します

3. 日ごとの失敗数を SQL で集計し、回帰が発生した期間を確認します。

   SELECT toDate(timestamp) AS day, count() AS fails
   FROM events
   WHERE event = '$ai_evaluation'
       AND properties.$ai_evaluation_id = '<uuid>'
       AND (<fail predicate>)
       AND (isNull(properties.$ai_evaluation_applicable) OR properties.$ai_evaluation_applicable != 'false')
       AND (isNull(properties.$ai_evaluation_skipped) OR properties.$ai_evaluation_skipped != 'true')
       AND timestamp >= now() - INTERVAL 30 DAY
   GROUP BY day
   ORDER BY day
   

4. query-llm-trace を使って、各パターンを代表するトレースを詳しく調べます

「成功と失敗は、同じ内容が根本原因ですか？」

1. ステップ 3 のクエリを使い、<fail predicate> を指定したものと、NOT (<fail predicate>) を指定したものの 2 つのサンプルを取得します
2. 成功した実行と失敗した実行で、似たような内容が記述されている場合：
   • llm_judge の場合：プロンプトまたは評価基準が曖昧である可能性があります。evaluation_config.prompt の表現を変え、llma-evaluation-update を使います
   • hog 評価器の場合：ルールの対象範囲が狭すぎるか広すぎる可能性があります。llma-evaluation-get でソースを読み、述語を絞り込み、修正を llma-evaluation-update で反映する前に、llma-evaluation-test-hog で再テストします

「コード変更後に Hog 評価器で回帰が発生しましたか？」

Hog 評価器は再現可能です。ソースに変更がなければ、同一の入力からは同一の出力が得られるはずです。Hog 評価器の失敗率が急上昇した場合：

1. llma-evaluation-get — 現在のソースと updated_at を記録します
2. 上記のステップ 4 の SQL クエリを使って、直近の失敗した実行を抜き取り確認します
3. それらと完全に同じ生成結果に対して、対象を絞り込むように conditions フィルターを変更してから、llma-evaluation-test-hog でソースを再実行します
4. テスト結果が実行時の結果と一致する場合、変更されたのは評価器ではなく 生成結果 です（モデルのアップグレード、上流のプロンプト変更など）。生成元を調査します
5. 結果が異なる場合、評価器が編集されています。アクティビティログでソースフィールドの git 履歴を確認します

「この評価器は、どのような生成結果を N/A としてスキップしますか？」

posthog:execute-sql
SELECT
    properties.$ai_target_event_id AS generation_id,
    properties.$ai_trace_id AS trace_id,
    properties.$ai_evaluation_reasoning AS reasoning,
    timestamp
FROM events
WHERE event = '$ai_evaluation'
    AND properties.$ai_evaluation_id = '<evaluation_uuid>'
    AND properties.$ai_evaluation_applicable = 'false'
    AND timestamp >= now() - INTERVAL 7 DAY
ORDER BY timestamp DESC
LIMIT 25

該当する実行の推論を読み、N/A のロジックが適切に機能しているかを確認します。スコアを付けるべきと思われる実行がある場合：

• llm_judge の場合：プロンプト内の適用条件の指示が広すぎます。対象を絞ります
• output_config.allows_na: true の hog 評価器の場合：ソースが null（または N/A を示す値）を安易に返しすぎています。前提条件を厳しくします

「この単一の生成結果を今すぐ評価する」

トレースの生成 ID とタイムスタンプを指定して llma-evaluation-run を実行します。スポットチェックや、評価をより大きなエージェントのループに組み込む場合に便利です。

UI リンクの作成

• 評価一覧：https://app.posthog.com/ai-evals/evaluations
• 個別の評価：https://app.posthog.com/ai-evals/evaluations/<evaluation_id>
• 元の生成結果／トレース：exploring-llm-traces スキルの URL 規則を参照してください

ユーザーが UI で確認できるよう、関連するリンクを必ず提示してください。

ヒント

• 評価レポートは llma-evaluation-report-create で評価ごとに設定します。毎日または毎週の頻度にするには frequency: "scheduled" と rrule を、指定数の新しい結果が蓄積した時点で一度実行するには frequency: "every_n" と trigger_threshold を指定します。delivery_targets を使ってメールまたは Slack に配信できます
• llma-evaluation-report-generate は次のトリガーを待たずに、設定済みのレポートをすぐに実行します。llma-evaluation-report-run-list は、過去の実行と配信されたレポートの内容を返します
• llma-evaluation-list でサポートされていない詳細な絞り込み（作成者やモデル構成による絞り込みなど）が必要な場合は、evaluations Postgres テーブルまたは $ai_evaluation ClickHouse イベントに対して execute-sql を使用してください
• ユーザーに失敗パターンを示す際は、パターンを視覚的に検証できるよう、トレースへのリンクを例として 1～2 件必ず含めてください
• llma-evaluation-* ツールでは、読み取り用ツールに evaluation:read、変更用ツールに evaluation:write を使用します。ただし、llma-evaluation-config-get と llma-evaluation-judge-models は llm_analytics:read を使用します
• Hog 評価器は再現性があります。リグレッションが疑われる場合は、問題のある生成結果に対して疑わしいソースを指定して llma-evaluation-test-hog を実行するのが、評価器と生成結果の作成元のどちらに変更があるかを特定する最も速い方法です
• LLM ジャッジ評価器は、再実行のたびに非決定的な結果になります。プロンプトとモデルを固定しても 1～5% のばらつきがあると想定してください。失敗率の小さなリグレッションを調査する場合は、Hog を優先するか、model_configuration で決定的なプロバイダー／シードを固定してください

関連スキル

• creating-online-evaluations — 評価を一から作成します
• exploring-ai-failures — 実際に観測された失敗モードをもとに、次の評価を設計します