opik-evaluate

評価 — 評価を構築して実行する

完了の定義： ユーザーのアプリ（またはプロンプト）を一連のケースで実行し、実際の失敗モードを対象とするスコアリングを行って作成した、スコア付きの Opik の実験、そのリンク、およびユーザーが次のアクションに活用できるスコアの概要があることです。評価を構築または実行できない場合は、最初に実際に発生したブロッカーで停止し、次のステップをちょうど1つ返してください。実行を伴わないデータセット、スコアのないジャッジ用プロンプト、文章だけの計画は成功ではありません。

運用方針：実際に起きている問題に基づいてケースを作り、ジャッジより先にコードでスコアを付け、失敗モードごとにジャッジを1つずつ使い、最初から最後まで一度だけ実行し、Opik からスコアを読み戻してください。アプリケーションコードは変更しません。 このスキルが書き込むファイルは、リポジトリ外に作成するランナーだけです。

入力

エントリーポイントは /opik-evaluate（このリポジトリのアプリを評価）、/opik-evaluate <what>（「RAG の回答」「返金フロー」など）、または /opik-evaluate <dataset-or-suite>（既存のケースで実行）です。その他は推測してください。以下は任意のオーバーライドとして扱います。

• ケースのソース（デフォルト：既存のスイート／データセット → 最近のトレース → 合成データ）・スコアリング（デフォルト：期待される出力がある場合はヒューリスティック、それ以外は失敗モードごとにジャッジを1つ）・アプローチ（デフォルト：エージェントにはテストスイート、組み込みメトリクスまたは厳密な一致が必要な場合はデータセット + evaluate()）・ジャッジモデル・サンプルサイズ（デフォルト：20〜50項目）。

確認を求めるのは、実際に発生していて推測では解決できないブロッカーがある場合だけです（ブロッカーを参照）。

アクティベーション — 対象範囲内の作業のみ

1. 評価対象を特定する

Opik に接続できることを確認します（~/.opik.config または OPIK_API_KEY。どちらもない場合 → ブロッカー）。評価対象のエントリーポイントを見つけます（トレースのルートスパンに名前が記録されている関数、またはユーザーが指定した関数）。既存の項目を確認し、作成する前に再利用します — client.get_test_suites(project_name=…)、client.get_datasets()。

評価がすでにありますか？ 最初に監査します（references/eval-audit.md）。未検証のジャッジ、エラー分析の欠如、見栄えだけのメトリクスを確認してください。最も重大な不足を修正してから実行します。

2. 失敗に基づいてケースを作る（エラー分析）

スコアラーを書く前に実際のトレースを読みます — client.search_traces(project_name=…, max_results=100)（エラー、スコアの低いもの、実行時間の長いものを優先）。問題の種類と発生頻度を分類します（references/error-analysis.md）。トレースがまだない場合は、ケースを生成し（references/generate-synthetic-data.md）、レポートにその旨を記載します。

3. 評価形式を選ぶ

状況	使用する形式
エージェント／チャットボットで、期待するのが動作（「Paris に言及する」「法律相談を断る」など）	テストスイート — 項目 + ジャッジでチェックする文字列アサーション。opik.run_tests()
期待される出力が厳密に決まっている場合、または組み込みメトリクス（Hallucination、AnswerRelevance、RAG の ContextPrecision／ContextRecall）を使う場合	データセット + evaluate() と scoring_metrics
テスト対象がコードではなくプロンプトのバージョン	サーバーサイド：client.rest_client.experiments.execute_experiment(...) — ランナー不要

エージェントにはテストスイートを優先してください。/opik-test と /opik-compare が操作するのはテストスイートです。

4. ケースを構築する

import opik
client = opik.Opik()

suite = client.get_or_create_test_suite(
    name="<project>-eval", project_name="<project>",
    global_assertions=["<one behavior every answer must show>"],   # optional
)
suite.insert([
    {"data": {"input": t.input, "source_trace_id": t.id}, "assertions": ["<what a correct output does>"]}
    for t in sampled_traces
])

データセットを使う場合は、client.get_or_create_dataset(name, project_name) の後に dataset.insert([{"input": …, "expected_output": …}]) を実行します。入力はそのまま保存し、ケースを本番環境までたどれるよう source_trace_id を保持します。

5. スコアリングを定義する

1. まずコードを使います。 チェックが機械的に行える場合は、opik.evaluation.metrics の Equals、Contains、RegexMatch、IsJson、JsonSchemaMatch、LevenshteinRatio を使用します。
2. 次に、失敗モードごとにジャッジを1つ用意します。手順2で分類した項目を対象に、合格／不合格の二値判定を行います（references/write-judge-prompt.md）。スイートのアサーションとして使うか、データセット形式では GEval／カスタムの BaseMetric として使います。
3. RAG： 検索と生成を分けてスコアリングします（references/evaluate-rag.md）。
4. 重要な評価でジャッジを信頼する前に、人手でラベル付けした少数の例と照らして較正します（references/validate-evaluator.md）。正解率ではなく、TPR／TNR を確認してください。

6. 実行する

タスクアダプターを一時ファイルとしてリポジトリの外に書き出します（アプリのプロバイダー認証情報が必要です。認証情報がない場合 → ブロッカー）。書き込み、送信、または課金を伴う本番のエントリーポイントは実行しないでください。

# Test suite
results = opik.run_tests(test_suite=suite, task=lambda item: {"input": item["input"], "output": str(app(item["input"]))},
                         experiment_name="baseline-<sha>", model="<judge model>",
                         generate_report=False)   # default True writes opik_test_suite_reports/ into cwd — keep the repo clean
# Dataset
from opik.evaluation import evaluate
res = evaluate(dataset=dataset, task=task, scoring_metrics=[...], experiment_name="baseline-<sha>",
               scoring_key_mapping={"reference": "expected_output"})   # map dataset keys onto metric args

project_name は重要です。データセット、スイート、プロンプト、実験はプロジェクトごとに管理され、アプリで @track を使用している場合は、トレース対象のプロジェクトと一致させる必要があります。データセットまたはスイートの作成時に設定してください。evaluate() はデータセットのプロジェクトを引き継ぎます。また、独自の project_name キーワード引数は非推奨です（SDK が警告して無視します）。

評価者の認証情報の確認： LLM 評価者（スイートのアサーション、または LLM メトリクス）にプロバイダーキーが設定されていない場合、run_tests／evaluate は例外を発生させません。すべての項目のスコアが 0 になり、scoring_failed=True と「Missing credentials」という理由が設定されます。また、実験は作成されます。報告する前にこれを確認してください。これは結果ではなく、ブロッカーです（「評価者のプロバイダーキーを設定して再実行してください」）。

7. スコアを読み取る

exp = client.get_experiment_by_id(results.experiment_id)     # or res.experiment_id
items = exp.get_items()   # dataset_item_data, evaluation_task_output, feedback_scores [{name,value,reason}], assertion_results [{passed,reason}], trace_id
# aggregate: mean per score name; pass rate = items where every assertion passed / items with assertions

データセットの経路では、res.aggregate_evaluation_scores().aggregated_scores からメトリクスごとの統計を直接取得できます。最も悪い項目と、それぞれに該当した失敗モードを挙げてください。そこが実行可能な情報です。（get_experiment_by_name は非推奨です。get_experiments_by_name／get_experiment_by_id を使用してください。）

8. 報告する

実験へのリンク、スコア表、理由とともに最も悪い 3 項目、ケースの根拠（トレースまたは合成データ）、次のステップを 1 つ記載してください（出力を参照）。この実行がベースラインとなり、/opik-compare で比較されます。

ブロッカー

最初に該当したブロッカーで停止し、次のステップを厳密に 1 つだけ返してください。

• "opik configure を実行してから、/opik-evaluate を再実行してください。"
• "どの関数を評価すればよいですか？エントリーポイント（例：answer(question)）を教えてください。"
• "実行にはプロバイダーの認証情報が必要です。OPENAI_API_KEY（または該当するキー）を設定して再実行してください。"
• "トレースもケースもまだありません。想定される動作が分かればそれも添えて、入力例を 5～10 件提示するか、synthetic と指定してください。こちらで生成します。"

出力

ユーザー向け： 実験へのリンク、スコア表、理由付きの最悪項目、ケースの出所、次のステップを 1 つだけ記載した短いメッセージです。すべての項目をそのまま並べたダンプにはしないでください。

内部用（合成／評価向け）には、次の形式を 1 つ使用します。

• status：evaluated | blocked
• shape：test_suite | dataset | server_side
• cases：name、id、count、source（traces | provided | synthetic | existing）
• scoring：{name, kind: heuristic|judge|assertion, failure_mode} のリスト
• experiment：id、name、url、project
• scores：{metric, value} のリスト（合格率を含む）
• worst：{dataset_item_id, input, score_or_assertion, reason, trace_url} のリスト
• next_step：厳密に 1 つ

不変条件：evaluated には experiment.url と空ではない scores が含まれます。scoring の各評価者には failure_mode が 1 つ指定されます。blocked には next_step が厳密に 1 つ含まれます。どの経路でもコードベースに変更を加えません。

例

トレースからエージェントを評価。 /opik-evaluate。100 件のトレースを読み、30％で返金期間を誤り、10％でポリシーを捏造していることを確認します。トレースから 40 件の項目を集めたスイート support-bot-eval を作成し、「返金期間を 5～7 営業日と回答する」「ドキュメントにないポリシーを捏造しない」というアサーションを設定します。ランナーを構築し、run_tests を実行すると 27/40。結果を読み返すと、最も問題のある項目はすべて返金に関するアサーションに該当しています。→ evaluated；次のステップ = 「/opik-test は不要です。スイートはすでにあるので、retrieve() を修正して /opik-compare support-bot-eval を実行します」

RAG、データセットパス。 /opik-evaluate the RAG answers。input、expected_output、context を含むデータセットを用意し、ContextPrecision、ContextRecall、Hallucination を使って evaluate() を実行します。Recall が 0.61 で、ここが弱い段階です。→ evaluated；次のステップ = 「top-k を増やす／リトリーバーを修正してから、/opik-compare を実行します」

プロンプトのみ。 対象はライブラリ内のプロンプトバージョンです。バリアントを指定して execute_experiment を実行し、項目が埋まるまでポーリングしてから結果を読み返します。→ shape: server_side を含む evaluated

ブロック。 リポジトリからエントリーポイントを推測できません。→ blocked：「どの関数を評価すればよいですか？」

主な原則

• 評価器より先にエラー分析を行う。 まずトレースを読まずにスコアラーを書いてはいけません。
• LLM の評価者より先にコードチェックを行う。 機械的にチェックできる場合は、ヒューリスティックな指標を使います。
• 二値の合否判定にし、評価者ごとに失敗モードを 1 つにする。 全体的な評価者では、実行可能な判断を得られません。
• 評価者をゲートとして使う前に、人間のラベルで必ず検証する（TPR/TNR）。
• オブジェクトを作成する際は、必ず project_name を渡す。 get_or_create_dataset、get_or_create_test_suite、create_prompt に渡します。evaluate() と run_tests() はデータセット／スイートから継承します（evaluate(project_name=…) キーワード引数は非推奨です）。
• 結果は標準出力ではなく Opik から読み取る — そうすることで、後から /opik-compare で同じ数値を読み取れます。

アンチパターン

トレースを 1 件も読まずに評価者を作ること、「品質 1～10」の評価者、Equals でチェックできるものを評価者で採点すること、実行を伴わないデータセット、最悪のケースを示さずに集計値だけを報告すること、ランナーをリポジトリに書き込むこと、評価を通すためにアプリのコードを編集すること、project_name を省略すること、非推奨の get_experiment_by_name を使うこと。

参考資料

このスキル内の参考資料にある方法論：references/eval-audit.md（既存のパイプラインを監査）、references/error-analysis.md（トレースから失敗を分類）、references/generate-synthetic-data.md（次元に基づく入力を生成）、references/write-judge-prompt.md（二値の評価者）、references/validate-evaluator.md（TPR/TNR の調整）、references/evaluate-rag.md（検索と生成）。

SDK の詳細は、このスキルと併せてインストールされる opik スキルにあります。このファイルからの相対パスは、../opik/references/evaluation-test-suites.md（スイート、run_tests、結果）、../opik/references/evaluation-datasets.md（evaluate()、60 以上の指標、OQL、トレースからのデータセット作成）、../opik/references/production.md（search_traces）です。ホストによってスキルの配置が異なる場合は、opik スキルの references/ ディレクトリを探してください。

opik スキルがインストールされていない場合は、レポートでその旨を伝え、記憶に頼らず https://www.comet.com/docs/opik/ を参照してください。