deepeval

DeepEval

このスキルを使用すると、AI アプリケーションにエンドツーエンドの評価ループを追加できます。 アプリを計測し、データセットを選定または再利用し、コミットする pytest 評価スイートを作成して、評価を実行し、失敗をもとに改善します。

前提条件

Python 3.9+ と、対象プロジェクトでの pip install deepeval が必要です。メトリクスと合成データの生成には、モデルの認証情報が必要です。Confident AI のレポート、ホストされたトレース、オンライン評価には deepeval login が必要です。

ワークフローの概要

1. 対象アプリと既存の DeepEval の使用状況を確認します。
2. 必要な事前確認の質問をします。
3. 利用可能な場合は、既存のメトリクスとデータセットを再利用します。
4. ユーザーがデータセットを持っている場合はそれを使用し、持っていない場合は deepeval generate でゴールデンを生成します。
5. トレースを使った評価を行う場合は、deepeval-tracing スキルでアプリにトレース計測を追加します。
6. deepeval test run を実行します。
7. 指定された回数、デフォルトでは 5 回、反復します。

基本原則

1. エージェントなしでユーザーが再実行できる、最小限のコミット済み pytest 評価スイートを優先します。ゴールデンやテストを使い捨てスクリプトに隠さないでください。
2. 新しいものを導入する前に、既存の DeepEval メトリクス、しきい値、データセット、モデル設定を再利用します。
3. アプリに計測を追加できる場合は、トレースを使った単一ターン評価を優先します。フレームワーク統合や手動の @observe による計測は deepeval-tracing スキルが担当し、OpenTelemetry の生データのエクスポートは deepeval-otel スキルが担当します。
4. データセットの生成には deepeval generate を使用します。pytest 評価の実行には deepeval test run を使用します。デフォルトで生の pytest コマンドを使わないでください。
5. コミットする評価スイートでは、メトリクスを独立した metrics.py モジュールに配置します。
6. ユーザーがトレース、本番環境のモニタリング、オンライン評価、ダッシュボード、共有レポート、ホストされた結果について言及した場合は、トレースと Confident AI の利用を強く推奨します。
7. 意図的に反復します。評価を実行し、失敗とトレースを確認し、対象を絞ってアプリを変更してから、指定された回数だけ再実行します。

必須のワークフロー

1. アプリの種類と、DeepEval がすでに使用されているかをコードベースで確認します。
   • 分類の指針については、references/choose-use-case.md を読んでください。
   • 次の優先順位に従って、最上位のユースケースを 1 つ選びます。 チャットボット／マルチターンエージェント ＞ エージェント ＞ RAG。
   • アプリが RAG とエージェントの両方に該当する場合は、エージェントとして扱います。チャットボットにエージェントまたは RAG の動作が加わっている場合は、チャットボット／マルチターンエージェントとして扱います。
   • DeepEval がすでに導入されている場合、ユーザーが明示的に変更を求めない限り、既存のメトリクスとしきい値を維持します。
2. アプリケーションコードを編集する前に、初回ヒアリングの質問をします。
   • references/intake.md を読み、評価モデル、データセットの取得元、トレーシング、Confident AI の結果、反復回数について質問します。
3. テストの形式、メトリクス、成果物を選びます。
   • references/pytest-e2e-evals.md を読んでください。
   • references/metrics.md を読んでください。
   • 期待されるファイルの配置については、references/artifact-contracts.md を読んでください。
   • チャットボット／マルチターンエージェントには、templates/test_multi_turn_e2e.py を使用します。
   • トレーシングまたは対応するインテグレーションが利用可能な場合、エージェント、RAG、一般的な LLM のシングルターン評価には、templates/test_single_turn_tracing.py を使用します。
   • トレーシングを明示的に希望しない場合、またはインテグレーション／トレーシングの手段が実現できない場合に限り、templates/test_single_turn_no_tracing.py を使用します。
   • メトリクスのインスタンスは、評価ファイル内に直接記述せず、templates/metrics.py またはプロジェクトに既存のメトリクスモジュールに配置します。
4. データセットを準備します。
   • 既存のデータセットについては、references/datasets.md を読んでください。
   • 合成データについては、references/synthetic-data.md を読んでください。
   • まず、ユーザーがすでにデータセットを持っているかどうかを尋ねます。
   • データセットがない場合は、deepeval generate で生成します。ゴールデンデータを手作業で作成したり、捏造したりしないでください。
   • 利用可能なソースから最適な生成方法を選びます。ドキュメント／ナレッジベースを最初に検討し、次にエクスポート済みコンテキスト、既存のゴールデンデータの拡張、最後にゼロからの生成を検討します。
   • ユースケースを推測し、ドキュメント、コンテキスト、ゴールデンデータ、ゼロからの生成を含むすべての生成方法で、スタイリング用フラグをデフォルトで指定します。
   • 初回評価に役立つよう、生成するゴールデンデータは 30～50 件程度を目標にします。
   • ユーザーが現時点ではテスト用の QA ペアを明示的に求めている場合を除き、チャットボット／マルチターンエージェントのユースケースでは、マルチターンの会話形式のゴールデンデータを使用します。
   • ローカルデータセットまたは Confident AI データセットについては、references/datasets.md に従います。
5. アプリに計測を追加し、トレースを使用する評価形式を選びます。
   • deepeval-tracing スキル（フレームワークインテグレーションと手動の @observe）を使用して、トレーシング用の計測をアプリに追加します。
   • トレースを使用する評価形式とスパンメトリクスについては、references/traced-evals.md を読んでください。
   • pytest のトレース対応シングルターン評価では、Golden の入力を使ってトレース対象のアプリを実行し、assert_test(golden=golden, metrics=[...]) を呼び出します。
   • スクリプトベースのトレース対応シングルターン評価では、for golden in dataset.evals_iterator(metrics=[...]) を使用します。
   • トレース対応のシングルターン評価を、手作業で構築した LLMTestCase に置き換えないでください。
   • コンポーネント／スパンレベルのメトリクスは、診断に役立つ場合にのみ追加します。
6. pytest 評価スイートを作成します。
   • references/pytest-e2e-evals.md を読んでください。
   • アプリがトレースを生成するかどうかに応じて、トレーシング対応またはトレーシングなしのテンプレートから、シングルターン評価を 1 つ始めます。
   • コンポーネント／スパンのメトリクスを追加する場合は、シングルターンのトレーシングファイル内に記述し、インテグレーションでサポートされる next_*_span(metrics=[...]) または @observe(metrics=[...]) を使って、該当するスパンに関連付けます。
   • templates/ 内の最も近いテンプレートを起点にし、実行前にすべてのプレースホルダーを置き換えます。
7. 実行して反復します。
   • deepeval test run tests/evals/test_<app>.py を使用します。
   • データセットが複雑な場合は、--num-processes 5、--ignore-errors、--skip-on-missing-params、--identifier の使用を検討します。
   • 指定された反復回数については、references/iteration-loop.md に従います。

よく使うコマンド

キュレーション済みデータセットがない場合に限り、ドキュメントのみから単一ターンのゴールデンデータを初期生成します。

deepeval generate --method docs --variation single-turn --documents ./docs --output-dir ./tests/evals --file-name .dataset

評価スイートを実行します。

deepeval test run tests/evals/test_<app>.py --num-processes 5 --identifier "iterating-on-<purpose>-round-1"

Confident AI が有効な場合、最新のホスト型レポートを開きます。

deepeval view

参考資料

トピック	ファイル
インテークの質問と分岐	references/intake.md
ユースケースの選択	references/choose-use-case.md
データセットの読み込み	references/datasets.md
合成データの生成	references/synthetic-data.md
メトリクス	references/metrics.md
Pytest E2E 評価	references/pytest-e2e-evals.md
トレースされた評価とスパンメトリクス	references/traced-evals.md
Confident AI	references/confident-ai.md
データセットと評価成果物の契約	references/artifact-contracts.md
反復ループ	references/iteration-loop.md

テンプレート

アプリの種類	テンプレート
単一ターンのトレーシング	templates/test_single_turn_tracing.py
トレーシングなしの単一ターン	templates/test_single_turn_no_tracing.py
マルチターン E2E	templates/test_multi_turn_e2e.py
共有メトリクスリスト	templates/metrics.py