rag-retrieval

RAG 検索

本番環境向け RAG システムを構築するための包括的なパターンです。各カテゴリには、必要に応じて読み込まれる個別のルールファイルが rules/ にあります。

ハウスしきい値、融合の順序、そして設定しているレイテンシと品質の予算は、以下の ハウスの差分に記載しています。ベンダーのドキュメントは再掲せず、リンクしています（上流の対応範囲（再掲しない）を参照してください）。

クイックリファレンス

カテゴリ	ルール数	影響度	使用場面
コア RAG	4	CRITICAL	基本的な RAG、引用、ハイブリッド検索、コンテキスト管理
埋め込み	3	HIGH	モデル選定、チャンク分割、バッチ／キャッシュの最適化
コンテキスト検索	3	HIGH	コンテキストの前置、ハイブリッド BM25+ベクトル検索、パイプライン
HyDE	3	HIGH	語彙の不一致、仮想ドキュメントの生成
エージェント型 RAG	4	HIGH	Self-RAG、CRAG、ナレッジグラフ、適応型ルーティング
マルチモーダル RAG	3	MEDIUM	画像＋テキストの検索、PDF のチャンク分割、クロスモーダル検索
クエリ分解	3	MEDIUM	複数概念を含むクエリ、並列検索、RRF 融合
再ランキング	3	MEDIUM	クロスエンコーダー、LLM によるスコアリング、シグナルの組み合わせ
PGVector	4	HIGH	PostgreSQL ハイブリッド検索、HNSW インデックス、スキーマ設計

合計：9 カテゴリにわたる 30 個のルール

コア RAG

検索、生成、パイプライン構成の基本的なパターンです。

ルール	ファイル	主なパターン
基本的な RAG	rules/core-basic-rag.md	検索＋コンテキスト＋引用付き生成
ハイブリッド検索	rules/core-hybrid-search.md	セマンティック検索＋キーワード検索の RRF 融合（k=60）
コンテキスト管理	rules/core-context-management.md	トークン予算＋十分性チェック
パイプライン構成	rules/core-pipeline-composition.md	構成可能な Decompose → HyDE → Retrieve → Rerank

埋め込み

埋め込みモデル、チャンク分割戦略、本番環境向けの最適化です。

ルール	ファイル	主なパターン
モデルと API	rules/embeddings-models.md	モデル選定、バッチ API、類似度
チャンク分割	rules/embeddings-chunking.md	意味上の境界で分割、512 トークンの最適値
高度な手法	rules/embeddings-advanced.md	Redis キャッシュ、Matryoshka 次元、バッチ処理

コンテキスト検索

Anthropic のコンテキスト前置技術です。検索の失敗を 67% 削減します。

ルール	ファイル	主なパターン
コンテキストの前置	rules/contextual-prepend.md	LLM 生成コンテキスト＋プロンプトキャッシュ
ハイブリッド検索	rules/contextual-hybrid.md	BM25 の重み 40%／ベクトルの重み 60%
完全なパイプライン	rules/contextual-pipeline.md	エンドツーエンドのインデックス作成＋ハイブリッド検索

HyDE

語彙のギャップを埋めるための仮想ドキュメント埋め込みです。

ルール	ファイル	主なパターン
生成	rules/hyde-generation.md	クエリではなく仮想ドキュメントを埋め込む
概念ごと	rules/hyde-per-concept.md	複数トピックのクエリに対する並列 HyDE
フォールバック	rules/hyde-fallback.md	2～3 秒でタイムアウトした場合は直接埋め込みにフォールバック

エージェント型 RAG

LLM 主導の意思決定による自己修正型検索です。

ルール	ファイル	主なパターン
Self-RAG	rules/agentic-self-rag.md	関連性を判定する二値のドキュメント評価
Corrective RAG	rules/agentic-corrective-rag.md	Web フォールバックを備えた CRAG ワークフロー
ナレッジグラフ	rules/agentic-knowledge-graph.md	エンティティの多い分野向けの KG＋ベクトルのハイブリッド
適応型検索	rules/agentic-adaptive-retrieval.md	最適な戦略へのクエリルーティング

マルチモーダル RAG

画像とテキストのクロスモーダル検索。

ルール	ファイル	主なパターン
埋め込み	rules/multimodal-embeddings.md	CLIP、SigLIP 2、Voyage multimodal-3
チャンク分割	rules/multimodal-chunking.md	画像を保持した PDF 抽出
パイプライン	rules/multimodal-pipeline.md	重複排除 + ハイブリッド検索 + 生成

クエリ分解

複雑なクエリを概念に分解し、並列検索します。

ルール	ファイル	主なパターン
検出	rules/query-detection.md	ヒューリスティックな指標（高速パスは <1ms）
分解 + RRF	rules/query-decompose.md	LLM による概念抽出 + 並列検索
HyDE コンボ	rules/query-hyde-combo.md	最大限の網羅性を実現する分解 + HyDE

再ランキング

検索後にスコアを再評価し、精度を高めます。

ルール	ファイル	主なパターン
クロスエンコーダー	rules/reranking-cross-encoder.md	ms-marco-MiniLM（約50ms、無料）
LLM 再ランキング	rules/reranking-llm.md	バッチスコアリング + Cohere API
組み合わせ	rules/reranking-combined.md	複数シグナルによる加重スコアリング

PGVector

PostgreSQL による本番環境向けハイブリッド検索。

ルール	ファイル	主なパターン
スキーマ	rules/pgvector-schema.md	HNSW インデックス + 事前計算済み tsvector
ハイブリッド検索	rules/pgvector-hybrid-search.md	FULL OUTER JOIN を用いた SQLAlchemy RRF
インデックス作成	rules/pgvector-indexing.md	HNSW（17倍高速）と IVFFlat の比較
メタデータ	rules/pgvector-metadata.md	フィルタリング、ブースティング、Redis 8 との比較

クイックスタートの例

from openai import OpenAI

client = OpenAI()

async def rag_query(question: str, top_k: int = 5) -> dict:
    """Basic RAG with citations."""
    docs = await vector_db.search(question, limit=top_k)
    context = "\n\n".join([f"[{i+1}] {doc.text}" for i, doc in enumerate(docs)])

    response = await llm.chat([
        {"role": "system", "content": "Answer with inline citations [1], [2]. Use ONLY provided context."},
        {"role": "user", "content": f"Context:\n{context}\n\nQuestion: {question}"}
    ])

    return {"answer": response.content, "sources": [d.metadata['source'] for d in docs]}

主な決定事項

決定事項	推奨
埋め込みモデル	text-embedding-3-small（汎用）、voyage-3.5（本番環境向け）
チャンクサイズ	256～1024 トークン（一般的には512）
ハイブリッド検索の重み	40% BM25 / 60% ベクトル
Top-k	3～10 件のドキュメント
Temperature	0.1～0.3（事実重視）
コンテキストの予算	4K～8K トークン
再ランキング	50件を取得し、10件に再ランキング
ベクトルインデックス	HNSW（本番環境）、IVFFlat（大量処理）
HyDE のタイムアウト	フォールバック付きで2～3秒
クエリ分解	まずヒューリスティックを使用し、複数概念がある場合のみ LLM を使用

アップストリームの対象範囲（ここでは繰り返さない）

これらの内容はここで繰り返さず、ソースから取得してください。「ハウスサブセットを残す」と記載されている行では、該当ファイルには調整済みの値とその理由のみを記載し、チュートリアルは含めません。

トピック	ソース
pgvector のインストール、演算子、インデックス構築の構文、「インデックスが使用されないのはなぜか」	https://github.com/pgvector/pgvector；ハウスサブセット（HNSW の m=16、ef_construction=64、halfvec、binary quantize）は rules/pgvector-indexing.md と rules/pgvector-schema.md に残します
Postgres の全文検索：tsvector、tsquery、GIN、ts_rank_cd	https://www.postgresql.org/docs/current/textsearch.html；ハウスサブセット（生成された STORED 列）は rules/pgvector-schema.md に残します
クエリプランの読み取り、インデックスが使用されていることの確認、VACUUM/ANALYZE	https://www.postgresql.org/docs/current/using-explain.html
RRF の仕組み：順位定数、順位ウィンドウサイズ、同順位の処理	https://www.elastic.co/docs/reference/elasticsearch/rest-apis/reciprocal-rank-fusion；ハウスサブセット（`k=60`、3x の取得）は rules/core-hybrid-search.md と rules/pgvector-hybrid-search.md に残します
フィールド重み付けによるブーストと、概念としてのスコアリングプロファイル	https://learn.microsoft.com/en-us/azure/search/index-add-scoring-profiles；ブースト係数とその順序は ハウス差分 と rules/pgvector-metadata.md に記載しています
埋め込み API の仕組み：バッチ制限、input_type、次元数、料金	https://docs.voyageai.com/docs/embeddings と https://platform.openai.com/docs/guides/embeddings；モデルの選択は rules/embeddings-models.md に記載しています
検索指標の定義（precision@k、recall@k、MRR、nDCG）とクエリセットの作成	ork スキル golden-dataset
検索エンドポイントの形式、ページネーション、エラーボディ	ork スキル api-design
検索呼び出しのトレースとダッシュボード化	ork スキル monitoring-observability
これらのアサーションを実行する統合テストの作成	ork スキル testing-integration

よくある間違い

1. 引用を追跡しない（回答を検証できない）
2. コンテキストが大きすぎる（関連性が薄れる）
3. 検索方法が単一（キーワード一致を見逃す）
4. 長いドキュメントをチャンク化しない（コンテキストが失われる）
5. クエリとドキュメントで異なる方法で埋め込みを生成する
6. エージェント型 RAG にフォールバック経路がない（ワークフローが停止する）
7. 書き換えが無限ループする（再試行の上限がない）
8. 類似度指標を誤って使用する（コサイン距離とユークリッド距離）
9. 埋め込みをキャッシュしない（変更されていないコンテンツを再計算する）
10. マルチモーダル RAG で画像キャプションが欠落している（テキスト検索が制限される）

評価

すべてのカテゴリにわたる 30 件のテストケースについては、test-cases.json を参照してください。

このスキルには、合格率、適合率、再現率、MRR のしきい値はありません。以前の記述ではこれらの数値を提示していましたが、測定されたことはなく、どこにも記録されていません。もっともらしい値で埋めるのではなく、未設定のままにしています。誰も測定していないしきい値は、未設定よりも問題が大きいためです。レビューで意味があるかのように引用され、正当な理由もなく合否が変わることになります。実際の値を確立するための適切な基盤は test-cases.json であり、この 30 件を対象にベースラインを実行すれば、主張する価値のある数値が得られます。

このスキルで定めている予算は、ハウス差分に記載されたレイテンシのみです。

関連スキル

• ork:langgraph - LangGraph のワークフローパターン（エージェント型 RAG ワークフロー向け）
• ork:golden-dataset - 検索品質の評価
• ork:llm-integration - nomic-embed-text によるローカル埋め込み
• ork:multimodal-llm - マルチモーダル RAG 向けの画像分析
• ork:database-patterns - ベクトル検索向けのスキーマ設計
• ork:performance - 繰り返される RAG 応答のキャッシュ

機能の詳細

retrieval-patterns

キーワード： retrieval、context、chunks、relevance、rag 解決する課題：

• LLM 向けに関連するコンテキストを取得する
• 引用付きの RAG パイプラインを実装する
• 検索品質を最適化する

hybrid-search

キーワード: hybrid, bm25, vector, fusion, rrf 解決する課題:

• キーワード検索とセマンティック検索を組み合わせる
• 逆順位融合を実装する
• 適合率と再現率のバランスを取る

embeddings

キーワード: embedding, text to vector, vectorize, chunk, similarity 解決する課題:

• テキストをベクトル埋め込みに変換する
• 埋め込みモデルと次元数を選択する
• チャンク分割の戦略を実装する

contextual-retrieval

キーワード: contextual, anthropic, context-prepend, bm25 解決する課題:

• 検索精度を高めるため、チャンクの先頭にコンテキストを追加する
• 検索の失敗を67%削減する
• ハイブリッド BM25+ベクトル検索を実装する

hyde

キーワード: hyde, hypothetical, vocabulary mismatch 解決する課題:

• セマンティック検索における語彙の隔たりを埋める
• 埋め込み用の仮想文書を生成する
• 抽象的または概念的なクエリに対応する

agentic-rag

キーワード: self-rag, crag, corrective, adaptive, grading 解決する課題:

• 自己修正型 RAG ワークフローを構築する
• 文書の関連性を評価する
• ウェブ検索へのフォールバックを実装する

multimodal-rag

キーワード: multimodal, image, clip, vision, pdf 解決する課題:

• 画像とテキストを扱う RAG を構築する
• モダリティ間検索（テキスト → 画像）
• 複数の種類のコンテンツを含む PDF を処理する

query-decomposition

キーワード: decompose, multi-concept, complex query 解決する課題:

• 複雑なクエリを概念ごとに分割する
• 概念ごとに並列で検索する
• 複合的な質問に対する網羅性を高める

reranking

キーワード: rerank, cross-encoder, precision, scoring 解決する課題:

• 検索後の適合率を高める
• クロスエンコーダーまたは LLM で関連性をスコアリングする
• 複数のスコアリングシグナルを組み合わせる

pgvector-search

キーワード: pgvector, postgresql, hnsw, tsvector, hybrid 解決する課題:

• PostgreSQL による本番環境向けハイブリッド検索
• HNSW と IVFFlat のインデックスを選択する
• SQL ベースの RRF 融合

---

House delta

references/ に置くのではなく、内容を直接配置しています。このスキルには rules/（32ファイル）に固有の知識が含まれており、これまで references/ ディレクトリを持ったことがないため、そこに単独でデルタファイルを置くと、それだけが配置されることになります。

埋め込みモデルの選択、チャンク分割アルゴリズム、ベクトルインデックスのチューニング、リランカー API、クエリ書き換えに関する文献は、ベンダーおよび上流の領域です。それぞれの情報がどこにあるかは、Upstream coverage を参照してください。以下では、OrchestKit が追加または反証する内容、あるいは注意を促す必要がある内容のみを扱います。

検索のレイテンシ予算：エンドツーエンドの p95 を500ms未満にする

出典：checklists/rag-quality.md:57。これは、このスキルが実際に示した唯一の検索レイテンシ予算です。個別の段階ではなく、ユーザーが待つ処理経路全体（クエリの埋め込み、検索、再ランキング、コンテキストの組み立て）が対象です。各段階では500ms以内でも、合計で超過するパイプラインは、この予算を満たしていません。

平均ではなく p95 で測定してください。検索レイテンシは、テールの挙動（インデックスシャードのコールド状態、リランカーのキュー待ち時間）に左右されるため、平均値ではユーザーから苦情が寄せられるリクエストを見落としてしまいます。

コーパスごとのチューニング結果は流用できない

融合の重み、再ランキングの深さ、ハイブリッド検索のアルファ値は、手法ではなくコーパスに固有のものです。散文形式のドキュメントで再現率を高める重み付けでも、コードや表形式のデータでは再現率が下がることがよくあります。そのため、別のプロジェクトからコピーした値は出発点ではなく、ノイズになります。各コーパスについて、そのコーパス独自の評価セットを使って値を再調整してください。

RRF 融合後にメタデータのブーストを適用し、融合前には適用しない

理由：ブースト係数は、すでに融合された結果セットの RRF スコアに乗算され、その後リストが再ソートされます。セクションタイトルの一致には 1.5 倍、セクションパスの一致には 1.15 倍、技術的なクエリでのコードブロックには 1.2 倍を適用します。融合前に各手法のスコアをブーストすると、RRF が依拠する性質（スコアではなく順位で融合すること）が損なわれ、一方の手法だけで強いキーワード一致が得られた文書が、両方の手法で一致した文書より上位になってしまいます。この順序こそが、rules/pgvector-metadata.md でブーストによるものとされた MRR の +6% を実現しました（廃止された checklists/search-implementation-checklist.md と examples/examples/orchestkit-retrieval.md から要約。追跡可能なインシデントはありません）。 上流：https://learn.microsoft.com/en-us/azure/search/index-add-scoring-profiles

RRF の取得倍率を 3 倍より大きくしない

理由：参照コーパスでの測定パス率は、1 倍で 87.2%、2 倍で 89.5%、3 倍で 91.1%、4 倍で 91.3% でした。つまり、4 倍にして得られるのは 0.2 ポイントである一方、各手法でスキャンする行は 3 分の 1 増えます。そのため、rules/core-hybrid-search.md と rules/pgvector-hybrid-search.md では 3 倍を標準のデフォルト値としてハードコードしています。この曲線を上回るゴールデンセットの数値が得られた場合に限り、倍率を上げてください（廃止された examples/examples/orchestkit-retrieval.md から要約。追跡可能なインシデントはありません）。 上流：https://www.elastic.co/docs/reference/elasticsearch/rest-apis/reciprocal-rank-fusion

すべての検索変更をゴールデンセットのしきい値で判定する

理由：検索変更をリリースする前の標準基準は、ゴールデンクエリセットでパス率 90% 以上、precision@10 0.70 以上、recall@10 0.85 以上、MRR 0.65 以上です。これらの下限値は、参照パイプラインで観測されたパス率 91.6%、全体の MRR 0.777（難易度の高いサブセットでは 0.695）をわずかに下回るよう設定されています。これにより、ノイズの多い実行結果ではなく、実際のリグレッションを検出できます（廃止された checklists/search-implementation-checklist.md と examples/examples/orchestkit-retrieval.md から要約。追跡可能なインシデントはありません）。 上流：ork スキル golden-dataset

エンドツーエンドだけでなく、各ステージの検索レイテンシーをアサートする

理由：統合テストでは、ベクトル検索は 100ms 未満、キーワード検索は 50ms 未満、融合ハイブリッド検索は 150ms 未満であることを個別にアサートします。これは、415 チャンクで観測されたベースライン（P50 15ms／P95 32ms／P99 62ms）に基づいています。合計レイテンシーだけをアサートすると、あるステージの処理時間がひそかに 2 倍になってもテストが成功し続けるためです。これは、インデックスがいつの間にか使われなくなった場合にまさに起きるパターンです（廃止された checklists/search-implementation-checklist.md と examples/examples/orchestkit-retrieval.md から要約。追跡可能なインシデントはありません）。 上流：https://www.postgresql.org/docs/current/using-explain.html

インデックスを調整する前に、埋め込みの呼び出しに予算を割り当てる

理由：参照測定では、エンドツーエンド検索が 15ms のうち、クエリの埋め込み生成が P50 で 8ms、ベクトル検索が 2ms、キーワード検索が 3ms でした。また、スループットの上限は毎秒およそ 120 リクエストでした。そのため、まず埋め込みをキャッシュしてバッチ処理してください。この上限を下回る領域でインデックスを調整しても、全体の改善は 1 桁台の割合にとどまるためです（廃止された examples/examples/orchestkit-retrieval.md から要約。追跡可能なインシデントはありません）。 上流：https://docs.voyageai.com/docs/embeddings