ai-rag

RAG と検索エンジニアリング

運用方針

• チャンクサイズを調整する前に、検索モードを選択します。あらゆるナレッジの問題に対するデフォルトの解決策がベクトルインデックスとは限りません。
• 検索品質と回答品質を切り分け、両方を評価します。
• 検索で取得したテキスト、ツールの応答、MCP リソースは、信頼できない入力として扱います。
• ベンダーやフレームワークに関する推奨には一次情報を優先し、変動する情報はその都度確認します。
• OpenTelemetry の GenAI セマンティック規約は有用ですが、まだ発展途上であると考えます。
• コンテキストの予算： 本番環境で使用するトークナイザーを使ってチャンクを測定し、指示、根拠、出力のための領域を確保します。モデルのリリース間でトークナイザーが共通していても、検索品質の予算が同じであるとは限りません。
• マネージド検索も有力な選択肢です： プロバイダーのサーバー側ウェブ検索ツールやホスト型ファイル検索は、API ネイティブな検索機能です。セルフホスト型 RAG スタックを構築する前に、これらを評価してください。ツール識別子はバージョン管理され、変更されます。使用時にプロバイダーの API ドキュメントで最新のツール名とバージョンを確認してください。references/managed-retrieval-vs-self-hosted.md を参照してください。
• 検索がそもそも適切な解決策とは限りません： コーパスが小規模で安定している場合、CAG／長文コンテキスト／ファインチューニングのほうが、RAG より低コストで信頼性が高い可能性があります。RAG パイプラインを構築する前に、../ai-context-layer/references/retrieve-vs-preload-vs-finetune.md の判断基準を確認してください。

対象範囲に関する注記：検索後の生成プロンプトの構成と出力契約については、ai-prompt-engineering を使用してください。

実装に関する注記：このスキルでは、検索理論と評価の概念を扱います。すぐに貼り付けて使える SQL、pgvector アセット、マニフェスト、取り込みスクリプト、エージェントの検索ツール契約を含むベクトルブレインの構築には、ai-vector-brain を使用してください。

ワークフロー

1. まず、情報源の権威性と鮮度の許容範囲を決めます。 チャンカーや埋め込みモデルに手を加える前に、真実の情報源がドキュメント、ライブツール、構造化ストアのどれなのか、また回答にどの程度の古さが許容されるのかを決めます。この判断が、チャンクサイズではなくアーキテクチャを決定します。
2. 検索モードの判断を行います（下記の「検索選択フレームワーク」を参照）。system designを使って、鮮度、追跡可能性、レイテンシに照らし合わせ、選択したモードと代替案を記録します。
3. インデックス作成前にコーパスの契約を定義します。 テナント／ACL の範囲、ソース、鮮度、削除の伝播については、metadata schemaとindex configurationを使います。取り込み時には、実際のコーパスの形状に応じてbasic、code、またはlong-document chunkingを読み込みます。
4. インフラを追加する前に、語彙検索のベースラインとゴールデン評価を作成します。 golden retrieval casesとscripts/retrieval_eval.pyを使って、recall@k、MRR、nDCGを測定します。scripts/exact_search_baseline.pyは、ANNによる損失を確認するための網羅的なベクトル検索です。ハッシュ埋め込み器は、学習済み埋め込みのベンチマークではなく、語彙検索のスモークテスト用フィクスチャです。
5. 検索の各経路を振り分け、検索後のモードを選びます。 経路は、セマンティック、語彙（BM25 と完全一致を組み合わせ、ドキュメント、条項、チケットの ID を文字列で検索）、リレーショナル（グラフ走査）、構造化（「現行バージョン／所有者／承認者／有効性」の確認に使うレジストリ／SQL）です。出力モードは、引用付きの根拠を返す（重複排除＋再ランキング）、結果を計算する（集計、時間的述語）、または回答を合成する、のいずれかです。コンプライアンス対象／規制対象のコーパスでは、根拠と引用の裏付け確認をデフォルトとし、合成は呼び出し元のエージェントに任せます。利用者が根拠をもとに推論できない場合に限って変更し、その場合は引用の裏付けゲートを追加します。語彙検索のみの FTS5/BM25 アップグレード経路を含む詳細については、retrieval-choice-framework.mdを参照してください。
6. 測定で確認した失敗に対して、レイヤーを1つ追加します。 retrievalから始めます。語彙／セマンティック検索の取りこぼしにはhybrid search、ランキングの取りこぼしにはreranking、クエリの不一致にはquery rewritingを読み込みます。別の選択済みモードには、template indexのみを使用します。
7. 検索評価と回答評価は別々のゲートとして維持します。 context packingとgroundingを使って根拠 ID を保持し、その後、answer evaluationで忠実性と回答の差し控えを確認します。引用 ID のチェックで証明できるのは対象の存在までであり、主張が引用されたテキストから導かれることまでは証明できません。
8. スケールする前に計測機能を組み込みます。 根拠 ID、検索モードのトレース、信頼度スコアがエンドツーエンドで確認できるようにし、問題のある回答を特定の検索判断までさかのぼって追跡できるようにします（observability-tracing-contract.mdを参照）。
9. 評価セットは一度きりのレポートではなく、リグレッションゲートとして扱います。 チャンカー、埋め込みモデル、インデックス、再ランキング器を変更するたび、またベンダー（埋め込みモデル、再ランキング器、ベクトル DB）を切り替える前に、必ず再実行します。「動作している」RAG システムの品質が低下する最もよくある原因は、気付かないリグレッションです。

クイックリファレンス

必要なもの	推奨される方法	適している場合	避ける場合
小規模なコーパスがコンテキストに収まる	長文コンテキストプロンプトまたは軽量検索	更新頻度が低く、監査の負担も小さい	コーパスが大規模、頻繁に変化する、または引用の正確さが重要
プロバイダー管理の検索	プロバイダーのウェブ検索サーバーツール（現在のバージョン付きツール ID を確認）またはホスト型ファイル検索	引用付きの最新ウェブデータが必要で、すぐに開始でき、運用するインフラがない	データレジデンシーの制御、ランキング内部のカスタマイズ、またはプロバイダーのデフォルト設定を超えるコーパスの分離が必要
プロバイダー管理のファイル／ドキュメント検索	OpenAI file-search（Responses API）	標準的なドキュメント／Q&Aで、インフラへの意欲が限られている	カスタムランキング、厳格なデータレジデンシー制御、または高度な検索調整が必要
AWS 上でのプロバイダー管理ドキュメント検索	AWS Bedrock Knowledge Bases	AWS ネイティブで、IAM／データレジデンシー制御を備えたマネージドの取り込み＋埋め込み＋検索を利用したい → references/aws-bedrock-knowledge-bases.md	クラウドをまたいだポータビリティやランキング内部のカスタマイズが必要
信頼できる情報源がツール／API	ツール優先または MCP 検索	データが SQL、CRM、チケット管理、SaaS API、または社内ツールにある	実際には、大規模な文章コーパスに対するセマンティック検索が必要
ウェブサイトまたは調査データの取り込み	まずクロール／抽出し、その後インデックス化	情報源がウェブサイト、レポート、または広範なウェブ調査から始まる	維持管理される検索システムではなく、単発のブラウジングだけが必要
ドキュメント全体またはテーマに関する質問	RAPTOR スタイルの要約ツリー（再帰的なクラスタリング＋要約、複数のレベルにわたる検索）	長いドキュメントや複数のセクションにわたる統合が必要で、エンティティグラフが存在しない → references/retrieval-patterns.md §6	質問が文章単位の検索である、またはツリーを再構築するより速くコーパスが変化する
正確な結合または集計	SQL／グラフ検索	質問にフィルター、結合、件数、または関係のたどりが必要	自然言語によるコーパス検索が主な課題
標準的なナレッジ検索	ハイブリッド検索＋再ランキング	語彙検索とセマンティック検索が混在するクエリで、高い再現率と制御可能なレイテンシが必要	よりシンプルなホスト型またはツール優先の選択肢ですでに解決できる
生成されたリポジトリ／コンテキストハブのコーパス	グラフ境界付きハイブリッド（グラフスコープ、ベクトル検索、再ランキング）	既存のナレッジ／コードグラフを備えた、複数リポジトリのコンパイル済みコンテキストハブ	コーパスにグラフがない、またはシンプルなセマンティック検索ですでに評価に合格している
高精度検索	レイトインタラクション／マルチベクトル検索	重複に近いドキュメント、微妙な表現の違い、PDF ページ、多言語での高精度が重要	レイテンシ予算が厳しく、BM25＋密ベクトル検索＋再ランキングですでに十分
PDF、表、図表	マルチモーダルドキュメント検索	OCR では構造が失われる、またはレイアウトの意味が重要	プレーンテキスト抽出ですでに高品質
本番環境対応の証明	ゴールデン評価＋正確なベースライン＋トレース	アーキテクチャを説明するだけでなく、品質を証明する必要がある	永続的なコーパスを伴わない単発の探索的調査

検索方法の選択フレームワーク

Need external knowledge?
  ├─ No -> Use direct prompting / standard prompt engineering
  └─ Yes
      ├─ Data already lives behind tools, APIs, SQL, or SaaS?
      │   └─ Start with tool-first or MCP retrieval
      │
      ├─ Corpus fits comfortably in model context and changes slowly?
      │   └─ Try long-context or hosted file search before custom indexing
      │
      ├─ Need joins, counts, or relationship traversal?
      │   └─ Use SQL, graph, or graph+vector hybrid retrieval
      │       (paradigm choice: see ../software-database-design/SKILL.md#technology-selection)
      │
      ├─ Need fresh web data or provider-managed file search without self-hosting?
      │   └─ Evaluate managed retrieval first: provider web-search server tools,
      │      hosted file-search, or other provider-native tools before building a custom stack
      │      (see references/managed-retrieval-vs-self-hosted.md for decision criteria)
      │
      ├─ Need retrieval over prose or mixed documents?
      │   └─ Use sparse+dense hybrid as the default baseline
      │
      ├─ Retrieval misses subtle matches or page-level structure?
      │   └─ Add late interaction, multivector, or multimodal retrieval
      │
      ├─ Precision still poor?
      │   └─ Add reranking, filters, query rewriting, and stronger evals
      │
      └─ Same queries keep re-running synthesis? Need a reviewable knowledge asset?
          └─ Switch from retrieval to knowledge compilation (P7 in ai-context-layer)
              Route to ai-context-layer/references/knowledge-compilation-and-wiki-pattern.md
              Blocks A15 (RAG re-run per turn instead of compiled knowledge)

コアコンセプト

• 権威ある情報源：真実の根拠を、取得したドキュメント、ライブツール、構造化データベース、またはそれらの組み合わせのいずれにするかを定義します。
• ACL 不変条件（このスキルが管理します）：候補生成時点で、呼び出し元の ACL／テナントのスコープを適用します。フュージョン、リランカー、あらゆるキャッシュより前に適用してください。リランカーの後や生成後にフィルタリングしてはいけません。リランカー後のフィルターでは、認可されていないテキストがリランカー、レスポンスキャッシュ、サードパーティ製リランカー API に渡るうえ、スコープを考慮せずに top-k が選ばれているため、再現率が気付かないうちに低下します。このスキルおよび ai-vector-brain のすべての検索パイプライン図、SQL の例、チェックリストに、候補生成時点またはそれ以前の ACL フィルターを必ず示してください。
• 信頼境界：取得したチャンク、アップロードされたファイル、MCP リソース、ツールの結果、ウェブページは、検証されるまでは信頼できないものとして扱います。
• 鮮度モデル：許容する古さ、無効化のトリガー、削除の伝播ルールを設定します。
• 生成コンテキストコーパス：複数リポジトリ／コンテキストをコンパイルしたハブも有効なコーパスです。グラフで範囲を限定した構築方法については、../ai-vector-brain/references/dev-context-hub-vector-recipe.md を参照してください。
• エビデンス契約：安定したエビデンス ID、ソースメタデータ、後から引用を検証するのに十分なコンテキストを返します。
• 2 つの評価軸：検索の関連性と回答の忠実性は別のシステムであり、それぞれ個別に測定する必要があります。

このスキルを使用しない場合

必要なこと	参照先
エンドユーザー向けの製品またはサイト内検索（エンジンの選択、ファセット、オートコンプリート、マーチャンダイジング、再インデックス、検索分析）	../software-search/SKILL.md
LLM が管理する INDEX.md で検索評価に合格する個人用メモコレクション	../docs-notes-retrieval/SKILL.md
そのまま貼り付けて使える SQL、DDL、pgvector インデックス、バックエンドのローダースクリプト	../ai-vector-brain/SKILL.md
リポジトリ／ドキュメント／コンプライアンス向けのベクトルブレインをエンドツーエンドで構築する	../ai-vector-brain/SKILL.md
アプリのコンテキストアーキテクチャ、メモリのライフサイクル、グラウンディングの境界	../ai-context-layer/SKILL.md
エージェントのトポロジーとツールのオーケストレーション	../ai-agents/SKILL.md
ボットの UX、会話フロー、エスカレーション	../ai-bot-builder/SKILL.md
オンデバイスの iOS 検索・スティッチングコンポーザー（Apple Foundation Models、@Generable、クラウドを使用せずローカルチャンクを検索）	../software-ios-ai-engine/SKILL.md
このスキルと ai-context-layer、ai-vector-brain を組み合わせて構成する、自然な会話を実現するエンドツーエンドの iOS インターフェース。Path A（Foundation Models）と Path B（ベクトル DB のみ）	../software-ios-ai-engine/references/composition-with-rag-context-vector.md
オンデバイスモデルの有無を問わない、クロスプラットフォームの自然な会話（iOS／Android／ウェブ／Telegram・Discord・WhatsApp・Slack のボット／音声／バックエンド）	../ai-context-layer/references/conversational-surfaces-cross-platform.md

検索エラーの切り分けゲート

チャンク化、埋め込み、リランキング、または生成器を変更する前に、失敗をコーパスの欠落、取り込み時の損失、候補の見落とし、ランキングの見落とし、コンテキストのパッキングによる損失、引用の不一致、回答生成エラーに分類します。生成器をオラクルエビデンスで一度実行し、検索を正解エビデンス ID に対して実行します。オラクルコンテキストでも失敗する場合は、回答契約またはモデルの経路を修正します。正解エビデンスが候補セットに入らない場合は、取り込みまたは検索を修正します。測定された損失を担当する段階だけを調整し、直前の段階は比較対象として維持してください。

既知の落とし穴

• 検索が適切なアーキテクチャかどうかを判断する前に、チャンクサイズ、埋め込みモデル、再ランカーを調整する
• 別のモデルで測定したチャンクサイズやトークン予算のヒューリスティックを、再測定せずに流用する
• 反復型／エージェント型のマルチホップ検索が、あらゆるクエリ分布を改善すると決めつける。ループのオーバーヘッドを加える前に、同じマルチホップ事例で固定検索のベースラインと比較する
• 対象のデータベースが必要な拡張機能、テキスト検索設定、生成列、インデックス演算子をサポートしているか確認する前に、ベクトル／全文検索への移行を実施する
• DDL、検索関数の変更、大量のコンテンツ投入を1つのマイグレーションにまとめ、検索機能の障害によってコーパスを安全に展開できなくする
• 長期ロードマップに含まれているというだけで、小規模かつ正常に動作している字句検索コーパスを埋め込みや検索インフラに移行する
• 合成したレポートや要約を、権威ある一次証拠であるかのように再インデックスする
• ライセンス条件（オープンウェイトの再ランカーの多くは非商用ライセンスで提供されています）や所有権の安定性を確認せず、リーダーボードのスナップショットだけで埋め込みモデルや再ランカーのベンダーを選ぶ。再ランカー／埋め込みモデルのベンダーは買収による統合が進んでいるため、再インデックスを多用する依存関係を構築する前に、ベンダー変更後もモデルのロードマップとサポートの確約が維持されることを確認する
• 検索再現率の問題と回答の忠実性の問題を、1つの指標として扱う
• ACL、データの所在、新鮮さ、削除のセマンティクスが処理されていると思い込み、ホスト型検索のデフォルト設定に頼る
• 候補生成時（フュージョン前）ではなく、再ランカー適用後や生成後にACL／テナント範囲でフィルタリングする — Core Concepts の ACL 不変条件を参照
• 出所と信頼境界を正規化せずに、ツールの出力、クロールしたページ、アップロードされたファイル、MCP リソースを混在させる

よくあるアンチパターン

以下の各アンチパターンの根本原因分析の詳細については、references/quick-start-guide.md を参照してください。

• ベクトルデータベースを先に導入し、信頼できる情報源のモデルを後回しにする（../ai-context-layer/references/anti-patterns-catalog.md の A2）
• 単純な検索タスクにエージェント型の検索ループを使う
• 変更可能なコーパスに対する新鮮さや無効化のモデルがない
• 証拠 ID の検証なしに引用を整形する（A13 — 出所情報を任意のメタデータとして扱う）
• テナント間または機密度の異なるデータをまとめてインデックスし、後から検索時フィルタリングを追加する（A10）
• コンパイル済みナレッジではなく、ターンごとに RAG を再実行する（A15） — 対処法：ナレッジコンパイルに切り替える（../ai-context-layer/references/knowledge-compilation-and-wiki-pattern.md の P7）

ベンダー推奨プロトコル

ユーザーから「最適な」ツール、モデル、フレームワークを尋ねられた場合：

1. data/sources.json を読み、add_as_web_search: true とマークされた情報源から確認を始めます。
2. 現行の一次資料、リリースノート、公式ベンチマークに照らして主張を検証します。
3. 長期的に有効な指針を優先します。検索方式の選択、運用上のトレードオフ、統合上の制約、評価計画、ロールバック計画などです。
4. ライブブラウジングを利用できない場合は、ランキング、価格、ベンチマークに関する主張が未検証であることを明記します。

調査・取り込みパイプライン

クロール／抽出（Firecrawl 形式）、調査ループ（GPT Researcher 形式）、定期的なデータパイプライン（dlt 形式）、CLI 評価ワークフロー（simonw/llm 形式）については、references/research-and-ingestion-patterns.md を参照してください。基本原則：クロール／抽出とランク付け／検索を分離し、生データの取得物とチャンクを別々の成果物として保持します。

スクリプト

check_sources.py — sources.json を検証 · retrieval_eval.py — recall@k/MRR/nDCG · check_citation_support.py — エビデンス ID の検証 · generate_synthetic_rag_testset.py — テストセットのひな形 · late_interaction_eval.py — ColBERT/ColPali のオフライン評価（推論ランナーなし） · exact_search_baseline.py — 正確なコサイン類似度／内積のベースライン · hybrid_rrf_demo.py — BM25（k1/b）+ ベクトル + RRF のスモークテスト

ナビゲーション

参考資料（このスキル）

アーキテクチャと選択： retrieval-choice-framework.md · managed-retrieval-vs-self-hosted.md · pipeline-architecture.md · aws-bedrock-knowledge-bases.md

コーパスとチャンク分割： chunking-strategies.md · chunking-patterns.md · index-selection-guide.md · embedding-model-guide.md · research-and-ingestion-patterns.md · pdf-heavy-retrieval-playbook.md

検索パターン： retrieval-patterns.md · vector-search-patterns.md · hybrid-fusion-patterns.md · bm25-tuning.md · graph-rag-patterns.md · contextual-retrieval-guide.md · advanced-rag-patterns.md · agentic-rag-patterns.md

ランキングとクエリ： ranking-pipeline-guide.md · query-rewriting-patterns.md · backend-comparison-fixtures.md

グラウンディングと評価： grounding-checklists.md · confidence-scoring.md · abstention-recipe.md · rag-evaluation-guide.md

運用とデバッグ： observability-tracing-contract.md · retrieval-debugging-runbook.md · rag-troubleshooting.md · rag-caching-patterns.md · multilingual-domain-patterns.md · security-red-team-cases.md

プロダクト検索の評価、ランキング学習、クリックモデル、検索 SLO は software-search にあります：search-evaluation-guide.md（nDCG/MRR の判定済みセット。検索評価にも再利用可能） · learning-to-rank-pipeline.md · click-models-and-bias-correction.md · user-feedback-learning.md · distributed-search-slos.md · search-debugging.md

オンボーディング： quick-start-guide.md - ワークフロー、テンプレートの完全なインデックス、詳細なアンチパターン · wiki-grounded-retrieval.md

テンプレート（このスキル）

評価データ：バックエンド比較テンプレート · 正解データの検索予測例 · セキュリティレッドチームのケース · RAG テストセット · 検索テストセット · 検索評価テンプレート

ランキング：ランキングパイプライン · リランカーの設定

検索バリエーション：グラフ＋ベクトル · マルチモーダル文書 · マルチベクトル · ツール優先

検索インデックスの設定：BM25 · HNSW · ハイブリッド検索 · IVF

スキル間の参照

• ../ai-context-layer/references/anti-patterns-catalog.md - このスキル全体で参照される A2、A10、A13、A15 のアンチパターン
• ../ai-context-layer/references/retrieve-vs-preload-vs-finetune.md - 判断基準：RAG、長文コンテキスト、ファインチューニングの比較
• ../ai-context-layer/references/knowledge-compilation-and-wiki-pattern.md - コンパイル済みナレッジ向けの P7 パターン（A15 の修正）
• ../ai-vector-brain/references/dev-context-hub-vector-recipe.md - 生成コンテキストコーパス向けのグラフ境界付き構築パス
• ../software-ios-ai-engine/references/composition-with-rag-context-vector.md - iOS の対話型 RAG 構成

外部ソース

• data/sources.json - ライブ検証用の一次ソースカタログ

関連スキル

実行前に適用可否を確認してください：各基盤スキルには When to Apply / When to Skip セクションがあります。

• ai-evals - 忠実度／回答評価における LLM ジャッジのバイアス制御と再現性
• ai-prompt-engineering - 検索結果に基づくプロンプト契約と構造化出力
• ai-agents - エージェントのオーケストレーションとツールのワークフロー
• ai-mlops - デプロイ、モニタリング、ガバナンス
• ai-llm-inference - レイテンシ、バッチ処理、キャッシュ、コスト管理
• docs-notes-retrieval - 検索用のローカルノート保管庫およびノートブックのエクスポートパッケージ化
• foundations-information-theory - チャンクのスコアリング、MMR の多様性、ドリフト検出におけるエントロピー、相互情報量、KL ダイバージェンス

学習ループ

以前の判断や落とし穴が参考になる場合は、learnings.consolidated.md があれば参照してください。必要な履歴を確認する場合、または利用可能な代替手段としてのみ learnings.md を使用してください。それ以外の場合は、どちらも参照しないでください。適用後、agents-skills-feedback-loop/scripts/append_learning.py を使用して、日付入りの箇条書きを 1 つ learnings.md に追記してください。SKILL.md 自体は変更しないでください。