iterative-retrieval 快速入门

让 AI 在长文档/知识库问答中,不是”一次召回就答”,而是多轮迭代补充上下文。

这是什么?解决什么问题?

iterative-retrieval 是 affaan-m/everything-claude-code 仓库下的一个 Skill,核心场景是 RAG(Retrieval-Augmented Generation,检索增强生成)系统的信息检索阶段。

传统的 RAG 流程通常长这样:用户提问 → 一次性把问题扔给向量数据库 → 召回 top-K 文档片段 → 喂给 LLM 生成答案。这种”一次召回”模式有两个典型问题:

1. 召回不全:用户问”公司年假政策”,可能相关片段在”员工手册”和”考勤系统 FAQ”里都有,一次召回可能只命中一处。
2. 上下文不够:用户问”对比 2023 和 2024 年报”,需要召回两年的文档才能回答,一次召回很难凑齐。

iterative-retrieval 的解决思路是多轮迭代:第一轮召回最相关的 top-K,基于这一轮结果生成”补充查询”,再召回,如此往复 2-3 轮,直到召回的内容足够回答原始问题。

Skill 沉淀的典型模式包括:

• 多轮召回:每一轮基于前一轮结果生成新的查询。
• 相关性排序:多轮召回后,对所有片段去重 + 按相关性重新排序。
• 上下文压缩:用 LLM 把多轮召回的片段压缩成精炼上下文,避免塞爆 LLM 的 context window。
• Query Rewrite:对用户的原始问题做改写(扩展同义词、补全省略),提升召回率。

它适合的场景:企业知识库问答、客服机器人、技术文档问答、长 PDF/合同解析、研究报告综述。

准备工作

1. 一个支持 Skill 加载的 AI 编程助手(Claude Code)。
2. 你的项目里已经有一个向量数据库(Pinecone / Weaviate / Qdrant / pgvector / Chroma 等)。
3. 已经有一套 RAG 基础流水线(embeddings、向量检索)。
4. Clone 仓库:

   git clone https://github.com/affaan-m/everything-claude-code.git
   

5. 软链 Skill:

   ln -s everything-claude-code/skills/iterative-retrieval ~/.claude/skills/iterative-retrieval
   

3 步快速上手

第 1 步:安装 Skill

重启 AI 助手,Skill 生效。

第 2 步:验证安装

向 AI 发送请求:

“用 iterative-retrieval 给我设计一个三阶段检索流程:第一轮基于原始问题,第二轮基于答案假设,第三轮做交叉验证。”

如果 AI 输出的是分轮次的伪代码/架构图,每轮有明确的”输入 → 检索 → 输出”,说明 Skill 加载成功。

第 3 步:用 iterative-retrieval 跑第一个任务

让 AI 帮你用 Python + LangChain + Chroma 实现一个 3 轮迭代检索:

from langchain.embeddings import OpenAIEmbeddings
from langchain.vectorstores import Chroma
from langchain.llms import OpenAI

class IterativeRetriever:
    def __init__(self, vector_store: Chroma, llm):
        self.vs = vector_store
        self.llm = llm

    def retrieve(self, query: str, max_rounds: int = 3) -> list[str]:
        seen = set()
        all_docs = []
        current_query = query

        for round_idx in range(max_rounds):
            # 第 N 轮检索
            docs = self.vs.similarity_search(current_query, k=5)
            new_docs = [d for d in docs if d.page_content not in seen]
            for d in new_docs:
                seen.add(d.page_content)
            all_docs.extend(new_docs)

            # 如果召回的文档够多,提前结束
            if len(all_docs) >= 10:
                break

            # 基于已有结果生成"补充查询"
            context = "\n".join([d.page_content for d in new_docs[:3]])
            current_query = self.llm.predict(
                f"原始问题: {query}\n已检索到的内容摘要: {context}\n"
                f"请基于已检索内容,生成 1 个补充检索词,用于找到原始问题中可能遗漏的信息。"
                f"只返回补充检索词,不要解释。"
            )

        return all_docs

    def answer(self, query: str) -> str:
        docs = self.retrieve(query)
        context = "\n\n".join([d.page_content for d in docs])
        return self.llm.predict(
            f"基于以下资料回答问题。如果资料不足,请明确说明。\n\n"
            f"资料:\n{context}\n\n问题: {query}"
        )

使用:

embeddings = OpenAIEmbeddings()
vs = Chroma(persist_directory="./chroma_db", embedding_function=embeddings)
llm = OpenAI(temperature=0)

retriever = IterativeRetriever(vs, llm)
print(retriever.answer("公司年假政策是怎么规定的?包含哪些特殊情况?"))

第一轮召回”年假基础规则”,第二轮 LLM 自动生成补充词”年假特殊情况 / 病假 / 婚假”,第三轮召回到”特殊假期规则”,最终答案覆盖全面。

常见踩坑

1. 轮次太多反而拖慢。3 轮以上收益递减,延迟线性增加,Skill 建议 2-3 轮。
2. 补充查询脱离原始问题。LLM 生成的补充词越来越偏,最终召回到不相关内容。Skill 建议给补充词加”必须与原始问题相关”的约束。
3. 不去重。多轮召回会有大量重复片段,LLM 上下文被塞垃圾,Skill 强调用 seen 集合去重。
4. 没设最小召回阈值。有时候第二轮、第三轮召回不到新内容,应该提前结束,而不是”凑够 3 轮”。
5. context 长度爆掉。多轮召回 50 个文档片段,LLM 上下文超 200k token。Skill 建议用 LLM 压缩 + 截断。
6. embedding 模型不适配。中文场景用 OpenAI text-embedding-3-small 召回率不如 bge-large-zh,Skill 提醒选对模型。

初级用法

用法 1:企业知识库问答。员工问”报销流程”,多轮召回”报销系统文档""财务 FAQ""员工手册”三处的内容,合并后回答。

用法 2:技术文档问答。用户问”如何在 FastAPI 里配置 CORS”,多轮召回”FastAPI 文档""CORS 规范""项目里的 CORS 配置”。

用法 3:长 PDF 解析。把几百页的合同 / 年报切块入库,用户问跨章节的对比问题,多轮召回凑齐上下文。

高级玩法

玩法 1:HyDE(Hypothetical Document Embeddings)。让 LLM 先”想象”一个理想答案,把这个答案作为检索词,通常比用户原始问题召回率更高。

玩法 2:Re-ranking。第一轮召回 50 个粗排,第二轮用更贵的 cross-encoder reranker 模型精排到 top-5,精度提升 30%+。

玩法 3:GraphRAG 联动。用知识图谱做”实体关系”扩展,基于图遍历做多跳检索,弥补纯向量召回的”语义不精准”问题。

小技巧

1. chunk 不要太大。Embedding 模型对 512 token 内的文本最有效,超过 1024 token 召回率会掉。
2. 保留 chunk 的 metadata。文档来源、章节、更新时间,多轮召回后做来源标注,方便用户验证。
3. 查询改写用小模型。不需要 GPT-4 写补充词,gpt-4o-mini / claude-haiku 就够,省成本。
4. 监控召回率。准备一个”已知答案”的测试集,跑不同轮次的检索,看几轮后召回率饱和。
5. 加缓存。相同 query 直接返回缓存答案,Skill 建议加 Redis/SQLite 缓存层,延迟从 3s 降到 50ms。

常见问题 FAQ

Q1: 这个 Skill 跟 iterative-retrieval 有什么关系?必须装吗?

A: Skill 是给 AI Agent 用的”技能包”,能告诉 Agent 怎么按特定规范工作。不是必须装——如果你的项目规模小、要求不高,不装也能用。但装上能让 Agent 输出的质量更高、更符合最佳实践,推荐装。

Q2: 这个 Skill 适合哪些 AI Agent?Cursor?Claude Code?其他?

A: iterative-retrieval 来自 community,主要面向支持 Skill 机制的 Agent。常见兼容 Agent 包括 Claude Code、Cursor、OpenCode、Windsurf 等。具体兼容性请查 Skill 官方文档。

Q3: 装了这个 Skill 后,会拖慢 Agent 响应吗?

A: 会的——Skill 通常会增加 prompt 长度,导致响应变慢、token 消耗增加。但质量提升明显。建议:1) 只装项目必需的 Skill;2) 用 Skill 启动/加载/卸载机制按需加载;3) 定期清理不用的 Skill。

Q4: 怎么验证 Skill 装对了?

A: 在 Agent 中输入”列出已加载的 Skill”或类似命令。如果 Skill 出现在列表里,说明装对了。然后用 Skill 跑一个相关任务,看输出是否符合 Skill 规范。

Q5: 这个 Skill 有许可证吗?能商用吗?

A: 取决于 iterative-retrieval 的许可证。常见许可证包括 MIT(完全自由)、Apache-2.0(自由但有专利条款)、源可用(可看不能用)、GPL(强开源)。商用前请查仓库 LICENSE 文件。

参考链接

• iterative-retrieval 仓库:https://github.com/affaan-m/everything-claude-code
• LangChain Retrieval 文档:https://python.langchain.com/docs/modules/data_connection/
• HyDE 论文:https://arxiv.org/abs/2212.10496
• bge 中文 embedding:https://huggingface.co/BAAI/bge-large-zh-v1.5
• Cohere Rerank:https://docs.cohere.com/docs/reranking

本文基于官方文档和公开资料整理，AI辅助生成，MagicNetWorld 尚未完成独立实测。如有错误或过时信息，请通过 contact@magicnetworld.com 反馈。