Summary

この文書の要点

どこが設計の難所か

検索品質を調整する業務では、クエリを入れて結果を見るだけでは判断材料が不足します。条件を少し変えた時の差、データセットの違い、候補の採用理由を残せないと、改善の議論が属人的になります。

探索処理は時間がかかることがあり、結果数も多くなります。すべてを同期APIで返すとタイムアウトやUI停止につながります。データセットの版が変わると同じ検索条件でも結果が変わる点も考慮が必要です。

探索型の検索ワークスペースでは、利用者は一度の検索で答えを得るのではなく、条件を変え、結果を比較し、気になる項目を残しながら進めます。単純な一覧APIでは、この試行錯誤の状態が画面に閉じて失われます。

設計では、データセット、シナリオ、検索実行、候補、評価結果を分けます。FastAPIは検索実行をジョブとして受け付け、結果を後から取得できるようにします。React側は条件編集と結果比較を分けた画面構成にします。

設計では、検索クエリ、フィルタ、ソート、結果、選択、注釈を分けます。React側は操作中のワークスペース状態を持ち、FastAPI側は検索実行の入力と結果概要を保存し、後から同じ検索を再現できるようにします。

APIには、データセット登録、検索実行作成、進捗取得、結果取得、評価メモ保存のエンドポイントを用意します。結果には、スコア、根拠、入力パラメータ、データセット版を含めます。

FastAPIでは、検索APIに`search_run_id`を返させ、条件、実行時刻、件数、使用したインデックスバージョンを保存します。React側はURLクエリに最低限の条件を載せ、重い選択状態やメモはワークスペースAPIへ保存します。

検証では、同じ条件で再実行した時の再現性、データセット変更時の差分、長時間実行のキャンセル、結果件数が多い時のページングを確認します。UIでは比較対象を見失わないかも重要です。

検証では、同じ条件で同じ結果が返るか、インデックス更新後に結果がどう変わるかを見ます。UIでは、戻る進む、URL共有、フィルタ解除、選択保持が自然に動くかをE2Eで確認します。

結果をすべて保存すると容量が増えます。保存期間や重要実行だけを残すルールが必要です。探索の自由度を高くしすぎると画面が複雑になるため、よく使うシナリオをテンプレート化すると扱いやすくなります。

検索実行を保存すると再現性は上がりますが、保存量とプライバシー管理が必要です。すべての検索を永続化するのではなく、共有や監査が必要な検索だけ保存するなど、用途に応じた線引きが必要です。

探索型検索では、結果そのものだけでなく、条件とデータの版を残すことが重要です。再現できる検索ワークスペースにすることで、改善判断をチームで共有できます。

探索型検索の価値は、結果を返す速さだけではありません。利用者がどう条件を変え、何を選び、どこで判断したかを支える設計にすると、検索画面が作業空間になります。