parallel-search-evaluation

並列検索の評価

ユーザーのワークロードを、再現可能なエンドツーエンドの比較に変換します。実装が求められている場合は実行可能なハーネスを、計画が求められている場合は実行可能な計画を提示します。別のハーネスを作成する前に、既存のハーネスを再利用してください。Parallel CLI の評価コマンドをでっち上げないでください。

ベンチマークを行わずに製品を選択する場合は choose-your-parallel-api を、既存の検索統合を置き換える場合は migrate-to-parallel を使用してください。このスキルを使って、結果の品質、コスト、レイテンシを測定します。

ワークロードから始める

リクエストを実装する前に、公開されている評価ガイド、検索のベストプラクティス、Extract のベストプラクティスを読みます。最新のモードと料金を確認し、価格やレイテンシの保証を埋め込むのではなく、ドキュメントの日付と設定を記録します。

アプリケーション、質問の種類、プロバイダー、既存のエージェント／モデル、検証済みの回答、品質・コスト・レイテンシの目標を明確にします。提供されたコードやデータからこれらを推測し、比較内容を左右する判断事項が不足している場合に限り質問します。認証情報やライブ実行の予算が未確定の間は、オフラインの成果物を準備します。有料の呼び出しには既存の認可を使用し、そうでない場合は実行前に対象範囲と支出上限を設定します。チャットでキーを求めないでください。

アプリケーションに合った製品を選択します。

アプリケーション	評価の境界
ユーザーがエージェントのループを管理する	Search + Extract（回答生成を含む）
1 回の呼び出しで引用付きの回答を返す	Responses API
スキーマに基づくエンリッチメントまたは非同期の調査	Task API

REST リクエストでは、Search の mode を必ず明示的に設定します。省略すると advanced が選択され、レイテンシと料金が変わります。ユーザーから指定がない場合、対話型ワークロードでは fast、より難しい調査では advanced から始め、次に関連する別のモードもテストします。評価ガイドでは引き続き basic が推奨されています。この相違点と選択理由を記録し、開始点としてそのまま引き継がないでください。言語サポートやエンドポイントの提供状況など、ワークロードの制約を守ります。Search MCP については、現在のルーティングと上書きルールを確認します。対応している場合は、認証済みの呼び出しでモードを固定します。匿名の呼び出しでは上書きが拒否されるため、実際にサーバーが選択したモードを記録するか、制御されたモード比較には認証を必須とします。比較の間はモデルを固定します。異なるモデルとモードの組み合わせは、別の実験として扱います。

比較を構築し、固定する

データセットレコード、実行マニフェスト、トレース、採点結果、レポートを作成する際は、references/eval-contract.md を使用します。このリファレンスは、このスキルのディレクトリを基準に解決してください。

1. 実際の本番環境で使われている質問と、独立して検証済みの回答を優先します。ドメイン、表現、鮮度、タスクの形式を一致させます。実行前に合成ラベルを確認します。質問 ID とデータセットのバージョンを固定し、パイロット質問と保留質問を分けます。公開ベンチマークはこのセットを補完するものとして扱い、回答キーの混入に対して一貫したポリシーを定める必要があります。
2. すべてのプロバイダーで、モデル、調査用プロンプト、予算、評価者、抽出ポリシーを一定に保ちます。選択したプロバイダーの検索ツールのみを公開します。各プロバイダーで文書化されているデフォルト設定とツール定義（説明を含む）を使用して開始します。設定を変更するのは、ワークロードまたはパイロットの根拠がある場合に限り、根拠と変更内容をマニフェストに記録します。任意の結果数上限や独自のツール説明は避けます。抽出がプロバイダーのスタックの一部として異なる場合は、その境界を開示します。正解と注釈をエージェントのプロンプト、クエリ生成、ツールメッセージに含めないでください。
3. モデルには、エンティティ、範囲、日付、情報源の要件など、関連するすべての制約を含めて情報ニーズ全体を言い換えた客観的な目的を記述させます。これに、それぞれ3～6語の焦点を絞ったキーワードクエリを組み合わせます。単純な事実の確認には1つ、より複雑な質問には有用な切り口を最大3つ使用します。目的とクエリで同じテキストを重複させたり、各クエリにタスク全体をコピーしたりしないでください。回答モデルのコンテキストには、結果のタイトル、URL、抜粋を保持します。新しい統合には /v1/search と /v1/extract を使用し、古いエンドポイントの名前を変更するのではなく、現在のリクエストスキーマを確認してください。
4. アプリケーションではマルチホップの検索＋抽出をデフォルトとし、明示的に1リクエストのベンチマークである場合に限り、シングルホップを使用します。実行前に、総呼び出し数、期限、再試行ポリシー、支出上限を固定します。質問、設定、反復ごとに新しいセッションを使用し、その試行に関連する検索と抽出の呼び出し間では同じセッションを再利用します。

コストをそろえた比較を推奨します。対応している範囲で、結果数、ページあたりのコンテンツ量、製品プラン、推論レベルをそろえ、検索／抽出／モデルの入力・出力トークンを含む総コストを考慮します。ベースラインには文書化されたデフォルト設定を使用します。コストをそろえるために設定を上書きする場合は、その理由を記録し、別の設定として扱う必要があります。要求した結果数と実際の結果数、コンテンツ量、残る不一致、そろえられない設定を報告します。API 呼び出し数が同じだからといってコストも同じとみなしたり、実現していないコストの同等性を示唆したりしないでください。

設定	実行者の動作
シングルホップ	検索 API リクエストを正確に1回だけ許可し、抽出は行いません。最終回答ではツールを無効にします。同時リクエストも含め、コード内で上限を適用します。1つのリクエスト内に複数のキーワードクエリがあっても、1回の呼び出しとして数えます。
マルチホップ	検索＋抽出を公開し、総予算の範囲内で証拠に基づく追加検索を許可します。同じターンから独立して実行できる呼び出しは並行してディスパッチします。ディスパッチ前に予算を確保し、結果は元の呼び出し ID に対応させて返し、兄弟リクエストが失敗しても成功した結果は保持します。

すべてのプロバイダーと設定で同じ調査用プロンプトを使用し、ツールの利用可否と実行者の予算は別々に変更します。公開ベンチマークでは、ガイドの調査用プロンプトと、利用可能な場合は公式の採点ツールを使用します。出力形式の上書きを記録し、ベンチマークのプロトコルを変更した場合は、調整済み評価として明記します。

パイロットの実施、評価、解釈

小規模で固定したパイロットを調査します。クエリの品質、警告、抜粋の提供、ツールの制限、同時実行性、トレースの完全性を確認します。統合上の不具合を修正し、影響を受ける設定で再実行します。採点対象の実行中に調整してはいけません。保留した質問を評価する前に、設定を固定します。各設定を少なくとも3回実行し、ばらつきを報告します。

すべての失敗について、影響を受けた試行 ID と影響を添えてユーザーに報告します。対象となる失敗には、レート制限、HTTP エラー、タイムアウト、部分的な結果、トークンの切り詰め、結果の欠落、エンドポイントのフォールバック（/v1 → /v1beta を含む）があります。再試行が成功した場合も、各発生を記録します。フォールバックを黙って行ってはいけません。また、Parallel 側の失敗を検索ミスとして数えてはいけません。実行中に失敗を明示し、最終レポートに件数とトレースへの参照を含めます。部分的な成功と、宣言した採点の分母を保持します。

タスクの形式に応じて最終回答を評価します。事実の正確性と引用による裏付け、リストの適合率と再現率、構造化フィールドの正確性、または明示的なリサーチ評価基準を用います。評価者には推論を求めます。カスタム評価基準では、確信に満ちた誤情報より、検索できなかったことを正直に認める回答を高く評価します。評価対象の試行の少なくとも10％を人手で確認し、成功と失敗の両方を対象にします。引用の監査は、公式ベンチマークのスコアとは分けて扱います。

トレースに基づいて失敗を分類します。検索呼び出しがない、十分な証拠があるのに統合に失敗した、プロバイダーエラー、妥当なクエリでも検索できなかった、のいずれかです。抜粋の欠落やその他のハーネスの不具合を検索品質の問題として扱ってはいけません。アカウントのレート制限とプロバイダーの能力を区別します。

宣言した採点ポリシーに従い、失敗とタイムアウトを主要な結果に含めます。再試行の回数に上限を設け、その時間とコストをすべて含めます。Search／Extract／モデルの料金、トークン数、呼び出し回数、予算超過、検索レイテンシーとエンドツーエンドレイテンシーの p50／p95／p99 を報告します。クエリの再構成と回答の生成を含め、タスク全体を実時間で計測します。同時実行した呼び出しの所要時間を合計してはいけません。解決済みタスクあたりのコストには、失敗した試行での支出も含めます。解決したタスクがない場合は、未定義として報告します。

再現可能な設定、データセットとトレースの保存場所、評価の根拠、失敗の内訳、品質とコスト／レイテンシーの比較を提示します。測定したパレートフロンティア上にあり、ユーザーの目標を満たす設定を、不確実性とワークロード別の結果を添えて推奨します。呼び出しを実行していない場合は、成果物を未実行の計画またはハーネスとして明記し、今後必要な作業を示します。

結果を踏まえ、観測された失敗やボトルネックに関連するフォローアップ設定を2～3件提案します。検索ミスが多い場合はadvanced、抜粋が不十分な場合はExtract の使用を有効にするか増やす、レイテンシーが高い場合はfast、モデルのトークンコストが高い場合はコンテンツ予算を小さくします。比較ごとに変更する要素は1つだけにし、根拠を記録して、新しい固定済みマニフェストを使用します。これらは提案として提示し、自動的に実行してはいけません。ユーザーが認可された範囲と支出内で依頼した場合に限り、実行します。