contextual-retrieval

用途

Contextual Retrieval 用于改进 RAG（检索增强生成）的检索质量。它解决的核心问题是：传统分块在把文档切成片段时会丢失文档级上下文。例如原文档是“ACME Q3 2024 Earnings Report...”，切出的片段是“Revenue increased 15% compared to the previous quarter.”。当用户查询“What was ACME's Q3 2024 revenue growth?”时，该片段既没有“ACME”也没有“Q3 2024”，检索就会失败。

主要能力

该技术的做法是在嵌入之前，为每个片段前置一段简短的情境说明，以保留文档级含义。情境化后的片段形如：“This chunk is from ACME Corp's Q3 2024 earnings report, specifically the revenue section. Revenue increased 15% compared to the previous quarter.”

它通常与混合搜索（BM25 + 向量）配合使用，并可进一步叠加重排序。据 Anthropic 研究，各阶段检索失败率为：传统嵌入 5.7%；加入情境化嵌入 3.5%；情境化 + BM25 混合 1.9%；情境化 + BM25 + 重排序 1.3%。完整流程可减少约 67% 的检索失败。

使用方式

实现分为几个环节。

情境生成：调用 Anthropic 客户端，用提示词要求模型针对给定片段输出 1-2 句简短情境说明，只返回情境本身。示例代码使用模型 claude-sonnet-4-5-20251101，max_tokens 为 150。生成后将情境前置到片段：f"{context}\n\n{chunk}"。

批量处理与缓存：处理同一文档的多个片段时，使用提示缓存（prompt caching）。把文档文本作为带 cache_control: {"type": "ephemeral"} 的文本块缓存，每个请求只变化片段部分，可显著降低成本。

混合搜索：使用 rank_bm25 的 BM25Okapi 对原始文本建立 BM25 索引，同时计算向量相似度，将两者归一化后加权合并。示例中 BM25 权重 0.4、向量权重 0.6，取 top_k。

完整流水线：定义 ContextualChunk 数据类（original、contextualized、embedding、doc_id、chunk_index），在 add_document 中依次完成分块、批量情境化、嵌入、存储、重建 BM25 索引；search 中对查询做嵌入，分别计算 BM25 与向量分数，归一化后按 0.4/0.6 合并返回 top-k。分块采用简单的按句切分。

优化建议：使用提示缓存可降低约 90% 成本（同一文档的多个片段）；可用 asyncio 信号量（示例为 10 并发）并行处理片段；情境质量要好，例如“This chunk is from the API authentication section of the FastAPI documentation.”，避免“This is a chunk from the document.”这类过于笼统的说明。

适用场景

文档含有重要元数据（日期、名称、版本）；片段脱离文档上下文后经常失去含义；检索质量至关重要（面向客户、合规场景）；索引阶段可以承担额外的 LLM 成本。

限制与不适用情况

片段本身已自包含（如问答对、定义）时无需使用；需要低延迟索引（高吞吐流式场景）时不适用；文档数量多且体积小、对成本敏感时也不适用。

关键决策

情境生成模型选用 Claude Sonnet，兼顾质量与成本；BM25/向量权重为 40%/60%，Anthropic 研究显示略微偏向向量为最优；片段情境长度为 1-2 句，既有足够上下文又不过度增加 token；提示缓存使用 ephemeral 缓存，处理同一文档多个片段时可降低约 90% 成本。

资源

Anthropic Blog: https://www.anthropic.com/news/contextual-retrieval Prompt Caching: https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching

技能介绍

用途