Summary
この文書の要点
- 同期APIに文書取り込みとインデックス更新を詰め込まない。
- 検索結果、プロンプト、回答、引用を監査できる形で保存する。
- 回答ログにはプロンプト全文だけでなく、検索候補、採用根拠、生成設定を分けて残す。
- 取り込み、検索、生成、評価を別ユースケースとして実装し、失敗箇所を切り分ける。
どこが設計の難所か
FastAPIでRAGを実装すると、最初は`/chat`に処理を集めたくなります。短期的には動きますが、検索品質の調査、回答失敗の再現、文書更新後の再インデックス、権限別検索を入れる段階で見通しが悪くなります。
RAGは通常のCRUD APIより処理時間が長く、外部AI APIの遅延や失敗にも影響されます。さらに、回答に使った根拠を後から説明できなければ、業務利用では問題の切り分けが難しくなります。
RAG APIの難しさは、外部AI APIの呼び出しではなく、質問から回答までの途中状態が多いことにあります。チャンクが作られた時点、埋め込みが更新された時点、検索順位が決まった時点、プロンプトが組み立てられた時点を保存しないと、誤回答の再現ができません。
境界をどう切るか
取り込みAPI、検索API、回答生成API、評価APIを分けます。チャット用エンドポイントは検索と生成をまとめても構いませんが、内部では検索サービスと生成サービスを分離し、それぞれの入力と出力をログに残します。
FastAPIではエンドポイントを薄く保ち、文書取り込み、検索、回答生成、評価をサービス層に分けます。PostgreSQLは単なる保存先ではなく、チャンク、embedding_version、検索実行、回答実行を結び付ける監査用の背骨として使います。
実装で効く細部
PostgreSQLには、文書、チャンク、埋め込みメタデータ、質問ログ、検索候補、回答ログを別テーブルとして持たせます。FastAPIでは依存性注入でDBセッション、AIクライアント、検索サービスを渡し、テスト時に差し替えられるようにします。
テーブル設計では、`documents`、`chunks`、`embedding_runs`、`search_runs`、`answer_runs`を分けると、再実行と比較がしやすくなります。APIレスポンスには回答本文だけを返しても、内部ログには検索top-k、除外理由、プロンプトテンプレートIDを残します。
- 取り込みジョブは同期レスポンスで完了させず、状態をqueued、processing、indexed、failedで管理する。
- 検索結果のスコア、chunk_id、document_idを保存し、後から同じ候補で生成だけを再実行できるようにする。
- 外部AI APIのタイムアウトは検索失敗と区別し、HTTPステータスと内部エラーコードを分ける。
壊れ方を観測する
検証では、APIレスポンスだけでなく、検索候補の再現性、引用IDの保存、タイムアウト時の扱いを確認します。Docker ComposeでPostgreSQLとAPIを起動し、代表質問を流してログの整合性まで見ると、運用時の調査がしやすくなります。
検証では、APIの200応答だけでなく、DBに残ったsearch_runとanswer_runの整合性を見ます。代表質問を流した後に、引用IDが実在するか、プロンプトに入ったチャンクとレスポンスの引用が一致するかをテストすると、運用時の調査がかなり楽になります。
捨てた選択肢とトレードオフ
責務を分けるとファイル数やテーブル数は増えます。小さな試作では過剰に見えることもあります。ただし、本番で品質を改善し続けるには、どの段階で失敗したのかを分けて観測できる設計が必要です。
ログを細かく残すほど保存量と個人情報管理の負荷が増えます。回答改善に必要な情報と、保存すべきでない入力内容を分け、保持期間やマスキングを設計に入れる必要があります。
現場に残す判断軸
RAG APIの設計では、回答を返すことだけでなく、なぜその回答になったかを後から追えることが重要です。FastAPIとPostgreSQLの構成でも、責務とログを分けるだけで改善の足場ができます。
RAG APIは、良い回答を返すだけでは不十分です。なぜその回答になったかをPostgreSQL上で追えるようにすると、FastAPIの薄いAPI層と改善しやすい検索生成基盤を両立できます。
