rag-retrieval

RAG 检索

构建生产级 RAG 系统的全面模式。每个类别都有位于 rules/ 中的独立规则文件，按需加载。

我们的内部阈值、融合排序以及延迟和质量预算见下文的内部标准。供应商文档仅提供链接，不重复陈述（参见上游覆盖范围（请勿重复陈述））。

快速参考

类别	规则	影响	使用场景
核心 RAG	4	CRITICAL	基础 RAG、引用、混合搜索、上下文管理
嵌入	3	HIGH	模型选择、分块、批处理／缓存优化
上下文检索	3	HIGH	前置上下文、混合 BM25+向量、流水线
HyDE	3	HIGH	词汇不匹配、假设文档生成
Agentic RAG	4	HIGH	Self-RAG、CRAG、知识图谱、自适应路由
多模态 RAG	3	MEDIUM	图像+文本检索、PDF 分块、跨模态搜索
查询分解	3	MEDIUM	多概念查询、并行检索、RRF 融合
重排序	3	MEDIUM	交叉编码器、大模型评分、信号组合
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	可组合的分解 → HyDE → 检索 → 重排序

嵌入

嵌入模型、分块策略和生产环境优化。

规则	文件	关键模式
模型与 API	rules/embeddings-models.md	模型选择、批处理 API、相似度
分块	rules/embeddings-chunking.md	按语义边界切分，512 个令牌为最佳长度
高级	rules/embeddings-advanced.md	Redis 缓存、Matryoshka 维度、批处理

上下文检索

Anthropic 的前置上下文技术——检索失败减少 67%。

规则	文件	关键模式
前置上下文	rules/contextual-prepend.md	大模型生成上下文 + 提示词缓存
混合搜索	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 秒 → 回退到直接嵌入

Agentic RAG

由大模型驱动决策的自我纠正检索。

规则	文件	关键模式
Self-RAG	rules/agentic-self-rag.md	通过二元判断评估文档相关性
纠正式 RAG	rules/agentic-corrective-rag.md	带网页回退的 CRAG 工作流
知识图谱	rules/agentic-knowledge-graph.md	面向实体丰富领域的知识图谱 + 向量混合检索
自适应检索	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 个 token（典型值为 512）
混合权重	40% BM25 / 60% 向量
Top-k	3-10 个文档
温度	0.1-0.3（事实性任务）
上下文预算	4K-8K 个 token
重排序	检索 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；我们的提升因子及其顺序见[内部差异](#house-delta)和 rules/pgvector-metadata.md
Embedding 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. 查询与文档使用了不同的 Embedding 方式
6. Agentic RAG 中没有回退路径（工作流会卡住）
7. 无限改写循环（没有重试上限）
8. 使用了错误的相似度指标（余弦距离与欧几里得距离）
9. 没有缓存 Embedding（重复计算未变化的内容）
10. 多模态 RAG 中缺少图像说明文字（限制文本搜索）

评估

请参阅 test-cases.json，其中包含涵盖所有类别的 30 个测试用例。

此技能没有通过率、精确率、召回率或 MRR 下限。此处早先的措辞曾承诺这些数值；但它们从未经过测量，也没有记录在任何地方。因此这些指标保持未设置，而不是填入看似合理的数值，因为未经测量的阈值比缺失的阈值更糟：评审时人们会引用它，仿佛它有意义，而通过或失败的结果却没有站得住脚的依据。test-cases.json 是建立真实阈值的合适基础，对这 30 个用例进行基线测试，就能得出值得设为断言的数值。

此技能唯一明确规定的预算是延迟，详见内部差异。

相关技能

• ork:langgraph - LangGraph 工作流模式（适用于 Agentic RAG 工作流）
• ork:golden-dataset - 评估检索质量
• ork:llm-integration - 使用 nomic-embed-text 进行本地 Embedding
• ork:multimodal-llm - 用于多模态 RAG 的图像分析
• ork:database-patterns - 向量搜索的架构设计
• ork:performance - 缓存重复的 RAG 响应

能力详情

retrieval-patterns

关键词： 检索、上下文、分块、相关性、rag 解决的问题：

• 为 LLM 检索相关上下文
• 实现带引用的 RAG 流水线
• 优化检索质量

hybrid-search

关键词： 混合、bm25、向量、融合、rrf 解决的问题：

• 结合关键词搜索与语义搜索
• 实现倒数排名融合
• 平衡精确率与召回率

embeddings

关键词： 嵌入、文本转向量、向量化、分块、相似度 解决的问题：

• 将文本转换为向量嵌入
• 选择嵌入模型和维度
• 实现分块策略

contextual-retrieval

关键词： 上下文、anthropic、前置上下文、bm25 解决的问题：

• 在文本块前置上下文，以提升检索效果
• 将检索失败率降低 67%
• 实现混合 BM25+向量搜索

hyde

关键词： hyde、假设、词汇不匹配 解决的问题：

• 弥合语义搜索中的词汇差异
• 生成用于嵌入的假设文档
• 处理抽象或概念性查询

agentic-rag

关键词： self-rag、crag、纠错、自适应、评分 解决的问题：

• 构建自我纠错的 RAG 工作流
• 评估文档相关性
• 实现网页搜索回退机制

multimodal-rag

关键词： 多模态、图像、clip、视觉、pdf 解决的问题：

• 构建包含图像和文本的 RAG
• 跨模态搜索（文本 → 图像）
• 处理包含混合内容的 PDF

query-decomposition

关键词： 分解、多概念、复杂查询 解决的问题：

• 将复杂查询拆分为多个概念
• 针对每个概念并行检索
• 提高复合问题的覆盖率

reranking

关键词： 重排序、交叉编码器、精确率、评分 解决的问题：

• 提升检索后的搜索精确率
• 使用交叉编码器或 LLM 评估相关性
• 结合多种评分信号

pgvector-search

关键词： pgvector、postgresql、hnsw、tsvector、混合 解决的问题：

• 使用 PostgreSQL 实现生产环境中的混合搜索
• 选择 HNSW 或 IVFFlat 索引
• 基于 SQL 的 RRF 融合

---

House delta

此处直接内联，而不是放在 references/ 中：这项技能将其专属知识放在 rules/（32 个文件）中，且从未有过 references/ 目录，因此单独放在那里的 delta 文件会成为该目录唯一的文件。

嵌入模型选择、分块算法、向量索引调优、重排序器 API 和查询重写文献均属于 供应商和上游内容；各项内容的位置请参见 上游覆盖范围（不要重复陈述）。以下内容仅涉及 OrchestKit 新增、与之矛盾或必须警示的事项。

检索延迟预算：端到端 p95 低于 500ms

来源：checklists/rag-quality.md:57，这是此技能实际提出过的唯一检索预算。它涵盖 用户等待的整个流程（嵌入查询、搜索、重排序、组装上下文），而非孤立的某个阶段。 如果某个流程每个阶段都控制在 500ms 内，却因累计耗时而超标，就不符合此预算。

请测量 p95，而非平均值。检索延迟主要受尾部行为影响（索引分片冷启动、重排序器排队）， 平均值会掩盖用户实际抱怨的请求。

特定语料的调优结果不可迁移

融合权重、重排序深度和混合 alpha 都是语料的属性，而非技术本身的属性。对散文式 文档能提升召回率的权重，通常会降低代码或表格数据的召回率，因此在项目之间照搬数值 只会引入噪声，而非提供起点。应针对每个语料，使用该语料自己的评估集重新推导这些数值。

RRF 融合后再应用元数据加权，切勿提前加权

原因：加权因子会乘到已融合结果集的 RRF 分数上，然后重新排序；加权系数分别为：匹配章节标题 1.5x、匹配章节路径 1.15x，以及技术查询中的代码块 1.2x。在融合前对各方法的分数加权会破坏 RRF 所依赖的特性（它按排名融合，而非按分数融合），还会让单个强关键词命中超越两种方法都检索到的文档。正是这一顺序带来了 rules/pgvector-metadata.md 中归功于加权的 +6% MRR（内容提炼自已停用的 checklists/search-implementation-checklist.md 和 examples/examples/orchestkit-retrieval.md；没有可追溯的事故）。 上游：https://learn.microsoft.com/en-us/azure/search/index-add-scoring-profiles

停止将 RRF 获取倍数提高到 3x 以上

原因：在参考语料库上的实测通过率，1x 时为 87.2%，2x 时为 89.5%，3x 时为 91.1%，4x 时为 91.3%；因此，第四档倍数只提升了 0.2 个百分点，却让每种方法扫描的行数增加了三分之一。这就是 rules/core-hybrid-search.md 和 rules/pgvector-hybrid-search.md 中将 3x 硬编码为默认值的原因；只有在黄金测试集上的数据证明效果超过这条曲线时，才提高倍数（内容提炼自已停用的 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% 通过率和 0.777 总体 MRR（困难子集为 0.695），这样真正的回归才会触发阈值，而不是由有噪声的运行结果导致（内容提炼自已停用的 checklists/search-implementation-checklist.md 和 examples/examples/orchestkit-retrieval.md；没有可追溯的事故）。 上游：ork skill golden-dataset

分阶段断言搜索延迟，而不只断言端到端延迟

原因：集成测试分别断言向量搜索低于 100ms、关键词搜索低于 50ms、融合后的混合搜索低于 150ms；实测基准为 415 个块，P50 15ms / P95 32ms / P99 62ms。之所以分阶段断言，是因为单一的总延迟断言可能仍然通过，而某个阶段的延迟已悄然翻倍；这恰恰是索引不知不觉停止使用时的表现（内容提炼自已停用的 checklists/search-implementation-checklist.md 和 examples/examples/orchestkit-retrieval.md；没有可追溯的事故）。 上游：https://www.postgresql.org/docs/current/using-explain.html

调优索引前，先为嵌入调用预留预算

原因：在参考测量中，查询嵌入耗时 P50 为 8ms，而端到端搜索耗时为 15ms；相比之下，向量搜索耗时为 2ms，关键词搜索耗时为 3ms。查询嵌入也是吞吐量瓶颈，约为每秒 120 个请求。因此应优先缓存并批量处理嵌入，因为在这一瓶颈之下调优索引，只能让总耗时降低个位数百分比（内容提炼自已停用的 examples/examples/orchestkit-retrieval.md；没有可追溯的事故）。 上游：https://docs.voyageai.com/docs/embeddings