mcpField
C
context-retrieval

context-retrieval

github.com/seb1nAgent 工作流232114 次安装11 周前更新
代码仓库

关于 context-retrieval

context-retrieval 是一项 Agent 技能，用于检索知识库内容，为回答提供事实依据。它涵盖从语义与关键词搜索到重排、引用和验证的 RAG 流程。

主要功能

  1. 01查询向量化与向量搜索
  2. 02语义、关键词及混合检索
  3. 03候选内容重排
  4. 04结合来源元数据组装上下文
  5. 05验证回答并添加引用

适用场景

  1. 01根据源文件回答代码库问题
  2. 02检索产品文档以处理支持问题
  3. 03为 RAG 回答构建带引用的上下文

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/seb1n/awesome-ai-agent-skills --skill context-retrieval

安装后在 Claude Code 中输入/context-retrieval确认已加载。

详细介绍

上下文检索

上下文检索是指从知识库中查找并汇集最相关的信息片段，为 AI Agent 的回答提供依据，确保内容准确且及时。这是检索增强生成（RAG）的核心，可确保生成的内容准确且可验证，而不是凭空编造。

工作流

  1. 嵌入查询：使用嵌入模型（例如 OpenAI 的 text-embedding-3-small、Cohere 的 embed-v3，或 bge-large 等开源模型）将用户的自然语言查询转换为稠密向量表示。嵌入向量能够捕捉查询的语义，以便与存储的文档进行比对。

  2. 搜索向量存储：将查询嵌入向量发送到向量数据库（Pinecone、Weaviate、Qdrant、Chroma 等），执行近似最近邻（ANN）搜索。请求排名前 k 的候选文本块，通常 k = 10–20，以便为重排器提供充足的材料。

  3. 重排结果：使用交叉编码器重排器（例如 Cohere Rerank、bge-reranker-large 或 ColBERT 模型）处理候选文本块。重排器会通过完整注意力机制，根据原始查询为每个文本块评分，其相关性评分比单独使用余弦相似度准确得多。保留排名前 n 的结果（通常 n = 3–5）。

  4. 组装上下文窗口：按相关性评分从高到低，将选定的文本块合并为一个上下文块。在每个文本块前添加来源元数据（文件路径、URL、页码），以便 Agent 引用来源。确保总 token 数量符合模型为提示词上下文部分分配的预算。

  5. 生成回答：将组装好的上下文与原始查询及系统指令一同传入大模型提示词，并在系统指令中告知模型只能依据所提供的上下文作答。这样可以让回答基于检索到的事实，减少幻觉。

  6. 验证并引用：生成回答后，核实答案引用的信息确实存在于检索到的文本块中。添加行内引用或参考资料部分，让用户能够将每项陈述追溯到来源文档。

核心概念

  • 语义搜索：使用向量嵌入按含义而非精确关键词匹配查找文档。擅长处理释义和同义词，但可能会漏掉精确的技术术语。
  • 关键词搜索（BM25）：传统的词频搜索，擅长精确匹配和稀有词。速度快、易于理解，但无法识别同义词。
  • 混合搜索：结合语义搜索和关键词搜索（例如，对 BM25 与余弦相似度评分进行加权融合），兼取两者之长。大多数生产级 RAG 系统都使用混合检索。
  • 分块策略：文档必须先拆分成文本块，再进行索引。常见策略包括固定大小的 token 窗口（256–512 个 token，重叠 50 个 token）、按句子边界拆分，以及递归字符拆分。较小的文本块可提高精确度；较大的文本块则能保留更多上下文。
  • 嵌入模型：嵌入模型的选择会影响检索质量。更大的模型（1024 维及以上）能捕捉更多细微差异，但存储和查询成本更高。选择前务必针对你的领域进行基准测试。

用法

要使用此技能，你需要一个已预先索引、文档嵌入向量存储在向量数据库中的知识库。输入自然语言查询。此技能会返回可直接用于组装提示词的检索上下文块，以及用于引用的来源元数据。

示例

示例 1：为代码问题检索代码库上下文

查询：“身份验证中间件如何验证 JWT 令牌？”

检索到的分块（重排后）：

排名来源分数片段
1src/middleware/auth.ts:14-380.94export function validateToken(req, res, next) { const token = req.headers.authorization?.split(' ')[1]; if (!token) return res.status(401).json({ error: 'Missing token' }); try { const decoded = jwt.verify(token, process.env.JWT_SECRET); req.user = decoded; next(); } catch (e) { return res.status(403).json({ error: 'Invalid token' }); } }
2docs/auth-flow.md:8-220.87“JWT 使用 JWT_SECRET 环境变量，通过 HS256 签名。令牌 24 小时后过期。中间件从 Authorization 标头中提取令牌，验证签名，并将解码后的负载附加到 req.user。”
3tests/auth.test.ts:5-190.72涵盖有效令牌、过期令牌和格式错误令牌场景的测试用例。

组装后的提示词：

Answer the following question using ONLY the provided context. Cite file paths.

Context:
[1] src/middleware/auth.ts:14-38 — export function validateToken(req, res, next) { ... }
[2] docs/auth-flow.md:8-22 — The JWT is signed with HS256 using the JWT_SECRET env var...
[3] tests/auth.test.ts:5-19 — Test cases covering valid token, expired token...

Question: How does the authentication middleware validate JWT tokens?
示例 2：为支持问题检索产品文档

查询：“如果我无法再访问自己的邮箱，该如何重置密码？”

检索到的分块：

  1. help/account-recovery.md（分数 0.91）—“如果无法访问注册邮箱，请前往 Settings > Account > Identity Verification。系统会要求你使用电话号码或政府签发的身份证件验证身份。验证通过后，你可以设置新的邮箱并重置密码。”
  2. help/password-reset.md（分数 0.85）—“要重置密码，请在登录页面点击‘Forgot Password’。重置链接将发送到你的注册邮箱。该链接 1 小时后失效。”

生成的回答：“由于你无法再访问邮箱，请使用身份验证流程：前往 Settings > Account > Identity Verification，通过电话号码或政府签发的身份证件验证身份，更新邮箱地址，然后从登录页面重置密码。[来源：help/account-recovery.md、help/password-reset.md]”

最佳实践

  • 在生产环境中使用混合检索——结合 BM25 关键词搜索与语义向量搜索，效果始终优于单独使用任一种方法。
  • 始终进行重排——与仅依赖嵌入向量余弦相似度相比，对排名前 20 的结果使用交叉编码器重排器，可显著提高精确率。
  • 分块时使用重叠——在相邻分块之间保留 10–20% 的令牌重叠，避免关键内容被拆分到不同分块中。
  • 包含元数据——将文件路径、章节标题、时间戳和作者信息与嵌入向量一同存储，以便追踪和引用检索到的上下文。
  • 通过经验调整 top-k——检索比所需数量更多的候选结果（k = 15–20），然后让重排器筛选出最佳的 3–5 个结果。这样可以平衡召回率和精确率。
  • 定期进行基准测试——在来自目标领域的带标签评估集上，使用 Recall@k、MRR 和 NDCG 等指标衡量检索质量。

边缘情况

  • 未找到相关结果：当最高检索分数低于置信度阈值（例如 < 0.5）时，Agent 应承认信息不足，而不是捏造答案。
  • 来源相互矛盾：如果检索到的分块包含冲突信息，应呈现双方观点并指出差异，而不是悄然选择其中一方。
  • 内容陈旧或过时：数月前索引的文档可能已经过时。请在元数据中包含时间戳，并在分数接近时优先选择较新的分块。
  • 查询过短或过长：单词查询可能产生嘈杂的结果——可考虑扩展查询。超长查询可能适合拆分为多个子查询，再合并结果。
  • 多语言知识库：确保嵌入模型支持语料库中使用的语言，或在生成嵌入之前先进行翻译。

评论

支持 Markdown