deepeval-tracing

DeepEval トレーシング

このスキルは、AI アプリケーション（LLM アプリ、エージェント、RAG パイプライン、チャットボット）に DeepEval のネイティブトレーシングを導入し、その実行を Confident AI の Observatory でスパンごとに確認できるようにするためのものです。作業内容は、対応するインテグレーションがあればそれを選び、なければ手動で @observe を使い、各スパンに意味のあるタイプを設定し、タグとメタデータを追加することです。

このスキルの範囲は、適切にフォーマットされたトレースの生成までです。評価メトリクスの追加と評価の実行は、deepeval スキルの担当です。

対象範囲：AI アプリケーションのみ

システムの AI 部分、つまりエージェントのループとプランニング、LLM 呼び出し、検索／ベクトル検索、ツール呼び出しのみを計測します。スパンタイプ（llm、retriever、tool、agent）は AI コンポーネントを表します。Web サーバー、CRUD バックエンド、インフラストラクチャなど、AI 以外のソフトウェアはトレースしないでください。対象に LLM、エージェント、検索、ツール呼び出しのいずれも含まれない場合、このスキルは適用されません。

deepeval スキルおよび deepeval-otel スキルとの使い分け

• このスキル（deepeval-tracing） — DeepEval SDK（@observe、フレームワークインテグレーション）を使ってアプリを計測し、トレースを Confident AI に送信します。
• deepeval スキル — pytest の評価スイートを構築します。データセット、メトリクス、トレース付き評価、deepeval test run、反復などが対象です。このスキルで計測したアプリに対して評価を実行します。
• deepeval-otel スキル — DeepEval SDK ではなく、ベンダーに依存しない OpenTelemetry SDK（Python 以外のアプリを含む、生の OTLP）を使って計測します。

これら 3 つのスキルは相互に補完し合います。このスキルと deepeval-otel のどちらを使うか迷った場合は、アプリが Python 製で DeepEval SDK を使いたいならこちらを、生の OpenTelemetry を使いたい場合やアプリが Python 製ではない場合は deepeval-otel を使ってください。

前提条件

• Python 製の AI アプリケーションと pip install deepeval。
• トレースを Confident AI に送信するには、deepeval login を実行するか、CONFIDENT_API_KEY をエクスポートしてください（CI および非対話型の実行ではこちらを推奨）。

ワークフロー

1. 対象が AI アプリケーション（LLM 呼び出し、エージェントのループ、検索、またはツール呼び出しを含む）であることを確認します。いずれも含まれない場合は、このスキルは適用されないため終了してください。
2. 使用中のフレームワーク、モデルプロバイダー、エージェント SDK、ベクトルデータベースを特定します。
3. references/integrations.md と、特定した内容に対応するインテグレーションのドキュメントを読みます。手動で計測するより、ネイティブインテグレーションを優先してください。
4. 適合するネイティブインテグレーションがない場合は、@observe を使って手動で計測します。references/tracing.md を読んでください。
5. 各スパンに意味のある type（llm、retriever、tool、agent）を設定し、入力と出力を記録します。
6. 失敗パターンの診断に役立つ場合は、トレースレベルのタグとメタデータを追加します。シークレット、認証情報、未加工の機微データは決してトレースしないでください。
7. deepeval login または CONFIDENT_API_KEY を確認し、Confident AI Observatory にトレースが表示されることを検証します。

基本原則

1. AI コンポーネントのみを計測します（llm、retriever、tool、agent スパン）。AI 以外のソフトウェアは決してトレースしないでください。
2. 手動の @observe より、対応済みのインテグレーションを優先してください。手動トレーシングは、未対応のフレームワークや、アプリが所有するラッパーの境界で使用する代替手段です。
3. トレーシングコードを書く前に、該当するインテグレーションのドキュメントを読んでください。
4. スパンには意味のあるタイプを設定してください。特別な理由がない限り、名前は関数名をデフォルトのまま使用します。
5. シークレット、認証情報、API キー、未加工の機微なユーザーデータは決してトレースしないでください。
6. このスキルの範囲はトレースの生成までです。メトリクスの追加と評価の実行は deepeval スキルの担当であり、生の OpenTelemetry のエクスポートは deepeval-otel の担当です。

参考資料

トピック	ファイル
手動計測：@observe、スパンタイプ、タグ、メタデータ	references/tracing.md
インテグレーションの選択ルールと、フレームワーク／モデル／ベクトル DB のドキュメント一覧	references/integrations.md