Semantic、BM25 与 Hybrid Search

1. 为什么这组知识要一起学

本章把 Retrieval/RAG 当成独立的数据工程与搜索系统，而不是“接个向量数据库”。重点是从 ingestion 到 end-to-end grounding 的可测量链路。

这几个知识点处在同一条工程链上。如果只记单个名词，很容易在真实系统里把责任放错层：例如让模型管理程序事实、让数据库 transaction 承担外部 API 原子性，或把一个 provider SDK 的行为误认为 Agent 的通用规律。

2. Mental Model

Retrieval 负责从外部语料找到证据；RAG 是把 retrieval 结果纳入生成流程。Vector Store 只是其中一种索引/搜索实现。

Source → Ingestion → Normalize → Chunk → Index → Query → Rewrite/Filter → Retrieve → Rerank → Ground → Generate/Evaluate

3. 核心机制

Semantic Search

语义搜索适合同义表达和自然语言概念；精确错误码、函数名、ID 等场景需要 keyword/structured filter 补充。

Keyword / BM25 Search

BM25 等 lexical 方法直接利用词项匹配，对稀有术语、代码符号、产品名通常很强，且不依赖 embedding model。

Hybrid Search

Hybrid 把 lexical 与 semantic 候选/分数融合，目标是同时获得语义召回和精确词项召回；融合参数应通过 eval 调整。

4. 最小实现 / 伪代码

下面代码只表达边界和生命周期，不要求照抄到项目中：

class Retriever(Protocol):
    async def retrieve(self, query: RetrievalQuery) -> list[Evidence]: ...

@dataclass
class Evidence:
    text: str
    source_id: str
    score: float
    metadata: dict

真正实现时应把 I/O、状态持久化、错误翻译和策略注入拆成可测试组件，而不是把示例扩成一个巨型函数。

5. 在 Shadow Harness 中怎么落地

定义 Document、Chunk、Retriever、RetrievalQuery、RetrievalResult、Reranker；ContextManager 消费标准化结果，不直接依赖具体 vector DB。

建议为本章涉及的行为留下明确的 domain object、interface 和 trace event；只要一个关键行为只能通过读日志猜测，就说明 Runtime contract 仍不够清晰。

6. Production Engineering 检查项

• 区分 retrieval quality 与 generation quality
• 保留 doc/chunk provenance
• metadata filter 提前缩小候选
• rerank 只处理可控候选集

7. Failure Modes

7.1 chunk 破坏语义边界

当出现「chunk 破坏语义边界」时，从 ingestion→chunk→candidate retrieval→filter→rerank→grounding 分阶段跑离线样本，定位 recall 还是 ranking 问题。 这类问题通常需要修改 contract、policy、state 或 adapter，而不是只追加 Prompt。

7.2 Top-K 固定且不看预算

当出现「Top-K 固定且不看预算」时，从 ingestion→chunk→candidate retrieval→filter→rerank→grounding 分阶段跑离线样本，定位 recall 还是 ranking 问题。 这类问题通常需要修改 contract、policy、state 或 adapter，而不是只追加 Prompt。

7.3 embedding-only 对精确术语召回差

当出现「embedding-only 对精确术语召回差」时，从 ingestion→chunk→candidate retrieval→filter→rerank→grounding 分阶段跑离线样本，定位 recall 还是 ranking 问题。 这类问题通常需要修改 contract、policy、state 或 adapter，而不是只追加 Prompt。

7.4 检索失败被误判为模型幻觉

当出现「检索失败被误判为模型幻觉」时，从 ingestion→chunk→candidate retrieval→filter→rerank→grounding 分阶段跑离线样本，定位 recall 还是 ranking 问题。 这类问题通常需要修改 contract、policy、state 或 adapter，而不是只追加 Prompt。

8. Trade-offs

2-step 可控且 latency 稳定；Agentic RAG 灵活但调用数可变；Hybrid 用 validation/rewrite 换质量。

设计记录最好明确：当前约束是什么、备选方案有哪些、为什么现在选这个、未来什么条件出现时需要重构。 这样 ADR 才能随着模型和基础设施变化被重新审视。

9. Experiment / Evaluation

建立带 ground truth 的 query set，分别测 recall@k/MRR/nDCG，再测 end-to-end grounded answer success。

实验应固定数据集、版本和环境，至少记录 success、latency、token/cost、attempt/step 数以及失败类型；涉及随机模型时需要重复运行而不是只看一次结果。

10. 常见问题

基础：Semantic Search 最容易被误解的点是什么？

语义搜索适合同义表达和自然语言概念；精确错误码、函数名、ID 等场景需要 keyword/structured filter 补充。

机制：这些能力在一次 Run 的哪个生命周期阶段生效？

沿着 Source → Ingestion → Normalize → Chunk → Index → Query → Rewrite/Filter → Retrieve → Rerank → Ground → Generate/Evaluate 找位置，并明确它的输入、输出、持久化事实和失败传播。

工程：如果这一层失败，应该由谁恢复？

先区分 transient failure、invalid input、permission、semantic failure 与 irreversible side effect。恢复策略属于拥有该状态与副作用的 Runtime/adapter，而不是交给模型自由决定。

设计：规模扩大 10 倍后，哪个假设最先失效？

优先检查 context/token、并发/连接池、catalog 大小、持久化吞吐、trace 体积、身份与租户隔离。不要默认“多加机器”能解决语义和一致性问题。

11. Sources

• OpenAI API — Vector stores
• LangChain — Retrieval
• LangGraph — Agentic RAG
• LangChain — Cross encoder reranker

12. 本文结论

掌握本文的标准不是能背定义，而是能画出数据流、写出最小 contract、解释失败恢复，并用测试或 benchmark 证明设计没有只停留在概念层。