先交代一个背景。前段时间我需要在一堆产品技术文档里快速定位一个冷门配置项的含义手头没有现成的知识库临时搭RAG流程又觉得太折腾。后来我换了思路既然大模型本身读得懂文档为什么不让它像人一样自己翻资料于是就有了以轻量 LoopAgent 替代 RAG 实现文档检索的完整实践。这个方案不依赖向量数据库、不需要提前做embedding用一套带循环控制的Agent把筛选文档、定位章节、精读提取串起来实测下来对中小规模文档库的问答检索非常顺手。这篇文章就是那次实践的复盘总结适合那些被RAG的预处理链路搞得不厌其烦、或者手里只有几十到几百篇文档、想快速做一个可靠检索问答能力的开发者。我尽量把方案思路、关键代码、参数设计和踩坑记录都写透你可以直接照着搭一套试试。1. 从RAG到LoopAgent为什么需要换一条技术路线1.1 RAG方案在文档检索中的真实痛点RAG检索增强生成目前的成熟度确实高文档切块、向量化、存库、召回、重排这一套链路已经被讲得很透了。但我自己在实际项目里用下来总有那么几个点很别扭。首先是切分粒度问题。文档切成500字还是1000字按段落切还是按固定窗口切切小了语义容易被腰斩切大了召回精度下降。文档里既有短标题又有大段正文一种切割策略很难同时适配。我踩过的坑是一份操作手册按固定500字切结果很多关键配置项被从上下文里切开召回率很难看。其次是向量库的维护成本。embedding模型要选、要跑向量数据要存、要升级还需要考虑索引重建的时机。文档内容更新了向量库要不要同步重算很多RAG项目上线后最大的痛点反而在索引更新链路内容改了一个字向量库不动检索结果就是过时的。再就是召回精度的天花板。向量相似度召回本质上是语义近似匹配而不是真正的理解定位。一个问题涉及多个文档交叉信息的时候TopK召回经常把最关键的段落漏掉。重排模型能挽回一部分但又多了一个需要维护的模型。这些痛点叠加在一起让我开始思考如果文档总量可控是不是可以不走先向量化再检索这条路1.2 LoopAgent的核心理念让大模型自己翻资料LoopAgent这个词核心就两个词Loop和Agent。Agent指的是以大模型为决策核心具备工具调用能力的执行体Loop指的是它不一次做完所有事而是循环执行观察当前情况、决定下一步行动、调用工具执行、拿到结果继续判断这个闭环直到找出答案。放到文档检索场景里LoopAgent的思路非常直白给模型一个文档目录让它先判断哪些文档最可能包含答案然后打开候选文档的目录结构判断答案落在哪个章节再精读具体章节内容看能不能提取出答案。找不到就换个方向继续找找到就带着答案和出处一起返回。这个过程和人工查资料几乎一模一样。人在查文档的时候不会把整本手册向量化再搜一遍而是先看目录、再翻章节、最后精读。LoopAgent把这种主动导航能力交给了大模型。它不依赖外部索引而是依赖模型对文本结构和语义关系的推理能力。这样一来RAG方案里的向量库、embedding模型、切分策略、召回重排全都省掉了。文档只要能被读取Agent就能按需访问。文档更新也简单重新读一次就是最新版本。1.3 适用场景判断不是所有检索都要上RAG把LoopAgent当替代方案第一个要搞清楚的问题是它适合什么场景不适合什么场景从我实测的经验看轻量LoopAgent最舒服的区间是文档库规模在几十到几百篇、单篇文档长度在几千到几万字的场景。比如企业内部制度汇编、产品说明文档、技术方案合集、论文资料库。这类场景有几个共性文档总数可控目录结构清晰用户问题大多指向具体段落。但当文档规模到几千篇以上LoopAgent的劣势就很明显了。模型每次查询都要做多轮推理和读取文档清单太长光是第一层筛选就要花费大量token。这种超大规模场景RAG的向量召回优势依然不可替代。另外LoopAgent对模型能力有底线要求。小模型如果连根据文档标题判断相关性都做不好整个循环就失去了导航依据。我用的模型至少要有较强的指令遵循能力和中长上下文处理能力。判断标准其实很简单文档量不大、更新频繁、检索精度要求高——选LoopAgent文档量巨大、需要秒级响应——还是选RAG。两者不是取代关系而是互补关系。2. 轻量LoopAgent的整体设计与核心流程2.1 核心组件与数据流设计一套轻量LoopAgent检索系统核心组件可以拆成四块文档地图Document Map这是整个系统的基石。它记录每一篇文档的标题、ID、目录结构、章节路径相当于给模型提供了一份图书索引。文档地图不需要向量化就是结构化的文本元数据。读取工具Document ReaderAgent调用这个工具获取文档内容。它接收文档ID和章节路径作为参数返回对应的文本内容。实现了按需读取而不是一次性把所有文档塞给模型。决策模块Agent Core大模型本体它根据当前掌握的信息做判断。判断结果统一输出成结构化JSON比如候选文档列表、下一步要读的章节路径、是否已经找到答案。循环控制Loop Controller负责编排整个执行流程管理循环次数、token预算、终止条件。这是决定系统收敛性和成本可控性的关键。数据流是这样的用户问题进入Agent Core模型先看文档地图给出候选文档列表然后读取工具按候选文档的目录结构返回对应章节的关键信息模型再判断下一步读哪里循环往复直到模型说找到了答案在这里控制系统校验后输出结果。这里有一个关键设计文档地图和文档正文是分开的。第一次循环只给模型看地图而不是正文这样能大幅节省token也能减少无关信息的干扰。模型判断这篇文档可能相关之后才按需读取正文。2.2 循环策略设计粗筛、定位、精读三级漏斗我实际用的循环策略是三级漏斗结构每一级做的事情不一样循环就是在这些层级之间动态游走。第一级是文档粗筛。模型拿到文档地图后结合问题语义判断哪些文档可能与答案相关。这一步的输出是带排序的候选文档列表通常取前3到5篇。第二级是章节定位。模型打开某个候选文档的章节路径判断答案更可能落在哪个章节。这一步会输出章节路径。如果一个章节读完之后发现没有答案模型会回到文档地图继续看其他章节或者其他候选文档。第三级是精读提取。模型读取定位到的章节正文尝试提取答案。关键是提取时必须带上答案来源的引用片段不能只给一句答案在第二章第一节。这一步的输出会带回给循环控制模块由控制模块判断是否达到终止条件。这个三级漏斗的好处是逐级缩小范围。粗筛阶段面对的是几十篇文档的标题token消耗小定位阶段面对的是一篇文档的目录信息密度高精读阶段才读取真正的正文且只读最有希望的部分。相比RAG全量Embedding一次召回这种按需导航的方式路径短、目标清晰、幻觉率也低。2.3 关键参数与终止机制既然是循环就一定要有边界否则模型可能在文档里反复打转Token费用失控。我整理了下面这套参数直接放出来供参考参数推荐值说明max_loops6~10最大循环轮数防止模型无限转圈top_k_docs3~5每轮最多保留的候选文档数confidence_threshold0.8提取答案的最低置信度max_tokens_per_loop8000每一轮精读的最大Token预算temperature0~0.3生成温度检索场景建议偏低overlap_ratio0.2文本块之间的重叠率防止信息被切断终止机制是这套方案里最容易踩坑的部分。我一开始只设了模型置信度大于阈值就结束结果发现模型有时候会过度自信明明答错了还给出高分。后来加了两个机制来兜底。引用校验答案必须包含原文引用片段找不到原文引用的答案直接降置信度。无进展终止如果连续两轮循环的候选文档集合和章节路径都没有变化说明模型已经在原地打转强制结束返回未找到答案而不是强行编一个。参数值的设定不是拍脑袋。max_loops设6到10是因为大部分文档导航问题在3到5轮内就能定位超过这个轮数基本可以判定为上下文不足或文档地图质量太差。token预算设8000足够精读若干章节正文同时给后续循环留余量。3. 实操从零实现一个轻量LoopAgent3.1 文档预处理的正确姿势做LoopAgent不需要embedding但文档预处理这一步还是逃不掉。预处理的目标是生成一份结构良好、信息密度高的文档地图以及一套支持按需读取的存储结构。我的做法分三步第一步解析文档结构。把PDF、Word、Markdown等格式转成统一的带有标题层级的结构化文本。这一步我会用现成的解析库保留标题层级信息H1、H2、H3和章节序号。解析出来的内容按章节块存储每个章节块记录包含所属文档ID、章节路径、标题、正文、父章节路径。第二步生成文档地图。地图不需要包含全文只需要给模型足够的导航信息。具体内容包括文档ID、完整标题、一级章节列表、二级章节标题、每章开头的第一句话。这些信息加起来每篇文档几百个token几十篇文档的地图也能控制在一次模型请求内。第三步建立读取接口。interface设计成两个函数read_document_map()返回全部文档地图文本read_chapter(doc_id, path)返回指定文档指定章节的正文。对模型而言这是两个工具Agent通过模拟工具调用来完成循环。预处理这里有一条经验文档地图的质量直接决定检索上限。如果你的文档标题都是1.docx2.docx这种毫无语义的名字模型第一层粗筛就会崩。处理办法是提取文档的第一个H1标题作为语义名称或者让模型给每篇文档写一句语义摘要补充到地图里。3.2 循环控制与查询调度的实现要点核心循环控制代码不复杂关键是把模型决策和工具读取解耦。下面是我整理的精简版本import json class LoopAgent: def __init__(self, llm, doc_reader, max_loops8, top_k3, conf_thres0.8): self.llm llm self.reader doc_reader # 文档读取工具 self.max_loops max_loops self.top_k top_k self.conf_thres conf_thres def ask(self, question): doc_map self.reader.read_document_map() candidates [] history [] for loop in range(self.max_loops): # 将文档地图、候选文档、循环历史一并交给LLM决策 decision self.llm.decide( questionquestion, doc_mapdoc_map, candidatescandidates, historyhistory ) if decision[action] extract: # 精读并提取答案 answer, confidence self.reader.extract( doc_iddecision[doc_id], pathdecision[chapter_path], questionquestion ) if confidence self.conf_thres: return self.build_result(answer, confidence, loop) # 置信度不够继续循环并记录失败上下文 history.append(decision) elif decision[action] locate: # 定位到某个章节记录候选 candidates.append({ doc_id: decision[doc_id], path: decision[chapter_path] }) else: # 模型主动判断无需继续 break return self.build_result(None, 0.0, self.max_loops) def build_result(self, answer, confidence, loops): return {answer: answer, confidence: confidence, loops: loops}这段代码有几个设计要点值得展开。一是decide()返回的是结构化JSON对象里面包含action、doc_id、chapter_path、reason四个字段。强制结构化输出能极大提升循环稳定性。模型判断该看哪篇文档的哪个章节时理由也一并给出方便后期排查问错方向的原因。二是history列表的存在。每次决策都会作为上下文进入下一轮。这样模型能在第3轮回忆起第2轮我读过第三章但没找到现在转去读第一章避免重复读同一处。我一开始没加history结果模型经常在相同章节之间反复横跳。三是extract()方法内置了引用校验逻辑。它读取章节正文后会让模型提取答案文本原文引用片段。如果模型拿不出引用片段这个方法直接返回低置信度。这个校验很重要能挡住相当一部分幻觉答案。3.3 效果对比与评测方法系统搭完之后我花了几天做了一套对比评测。评测基准是同一批50个问题分别跑RAG流程和LoopAgent流程。问题分成三类直接答案型如某配置项默认值是多少、方案检索型如如何配置SSO登录、跨文档综合型如对比A、B两种认证方式的差异。评测指标我选了四个答案命中率、平均循环轮数、平均耗时、平均Token消耗。命中率由人工逐条核对Token消耗从各模型的返回统计里读。结果是LoopAgent在这50个问题上命中率达到86%RAG对照组是78%。跨文档综合型问题上的差距最明显LoopAgent输出带有来源引用的答案RAG那边有不少看起来相关但答非所问的情况。平均耗时方面LoopAgent反而更慢单问题均值4.2秒对照RAG是1.8秒因为循环需要多次模型调用。Token消耗这一项LoopAgent也没有明显优势总体比RAG多了二到三成。但这项损耗换来了两个实际收益不需要维护向量库以及答案带有明确的原文出处。对很多内部知识库场景来说这两个收益比省token更值。另外我把文档库从50篇扩到200篇做了一次压力测试。LoopAgent的命中率轻微下降到82%但还在可用范围RAG的命中率保持稳定。这说明上规模之后RAG确实更稳LoopAgent更适合中小规模场景。4. 落地实践中的常见问题与排查技巧4.1 循环不收敛模型原地打转怎么办我遇到最多的异常就是模型在同一个文档的同一个章节反复读取没有新行动。这通常出现在问题比较复杂、第一轮定位偏差比较大的时候。模型可能读了A文档第三章发现没有答案但下一轮决策里还是返回A文档第三章只是换了理由。排查思路分三步。先看history记录确认模型是否真的重复读取了相同路径。如果是说明无进展终止机制没有生效检查终止条件里是否加入了本轮候选集合与上一轮完全相同的判断。再看文档地图质量。如果地图里章节标题太泛全是概述细节附录这样的词模型没有足够的导航信息自然会把动作收敛到很窄的范围。这种情况需要优化地图补充每章的摘要句。最后看模型能力。部分模型在超长上下文中对历史操作不敏感即使给了history也记不住。这时可以在每轮决策里用列表形式高亮上一轮你读了这些、结果是没有答案明确引导模型换方向。我自己的兜底策略是如果第5轮模型仍然没有给出置信度达标的答案我会让模型强制返回当前最优候选片段和对应文档路径再配合外部校验判断可用性而不是让循环继续空转。4.2 成本与延迟控制让循环别那么烧钱LoopAgent最让人肉疼的地方是多次模型调用叠加延迟和成本。我在实测中最低的一套配置单个问题平均消耗9000多token复杂问题能飙到20000。这个量级比RAG高出不少必须做控制。成本控制优先级最高的手段是压缩文档地图。地图不是越长越好它只是导航工具。我最终把每篇文档的地图压到标题一级章节关键二级章节全文的语义摘要只在文档粗筛阶段展示。这个调整让模型决策的token消耗降了约40%。另一个手段是设置精读上限。模块默认一篇文章最多精读3个章节如果3个章节都读完了还没找到直接切换候选文档而不是继续纠结在同一篇里。同时注意控制单次读取的正文长度我一般限制在2000字符左右超过就按章节切块读取。延迟优化方面关键路径上减少模型往返次数。第一轮决策时直接把文档地图候选文档清单一起给模型让它一次输出粗筛结果首个精读章节省掉一个RTT往返时延。实测这个改动把平均耗时从4.2秒降到3.1秒。4.3 一个排查清单开箱即用我把我调试过程中用着顺手的排查步骤整理成清单以后在自己课件、知识库项目里排查问题可以直接照着走。症状排查方向常用解法答案明显张冠李戴检查文档地图是否有重名或重复章节为每篇文档添加ID前缀消除歧义不断重复读取同章节无进展终止条件形同虚设对比相邻两轮候选集合没有变化则强制结束置信度一直低于阈值精读正文与问题关联弱降低单轮读取窗口增加周围上下文重叠度候选文档永远选错文档地图缺少语义摘要让模型对每篇文档做一句话摘要加入地图token消耗暴增多篇文档反复精读设置单篇最大精读章节数超限切换候选最终没有答案返回文档中确实没有对应信息让模型明确输出知识覆盖范围外避免强行编造这套清单的核心思想是先看模型有没有足够的导航信息再看循环有没有明确的边界约束。大部分问题都能在这两个层面找到根因。5. LoopAgent方案的边界与后续扩展方向5.1 什么场景不建议用LoopAgent这节主要是给大家泼冷水。LoopAgent不是万能的有些场景用它是自找麻烦。文档量上千篇、且单篇之间内容高度重叠的时候第一层粗筛会变得极其痛苦。文档地图可能本身就有上千条记录模型决策上下文都快超预算了检索效果还不一定好。这个规模老老实实上向量检索更稳。要求毫秒级响应的在线检索场景也不适合。LoopAgent的多轮交互天然带延迟模型再快也有几百毫秒到几秒的往返时间。如果你做的是客服机器人实时检索这个延迟很容易劝退用户。文档没有稳定结构的时候也别用。比如一堆扫描版PDF、格式混乱的无目录文档LoopAgent连地图都生成不出来。模型导航的前提是文档具有可解析的层级结构没有结构就等于大海捞针。我在自己的项目里把适用范围总结成一句话文档总量不超过几百篇、结构相对规范、检索响应时间能容忍2到5秒、答案需要带出处。满足这四个条件LoopAgent的性价比才会体现出来。5.2 混合模式与后续扩展方向LoopAgent和RAG也不是非此即彼的关系。我现在最新的方案里实际上是一个混合架构粗筛阶段用轻量级RAG只对文档标题和摘要做向量化召回Top10候选再用LoopAgent对候选文档做细粒度精读定位。这样既继承了RAG在海量候选面前的粗筛优势又保留了LoopAgent精读时的准确性。实测混合模式在文档库扩到500篇的时候命中率稳定在85%左右比纯LoopAgent高不少比纯RAG的答非所问问题也少很多。另外一个值得扩展的方向是给LoopAgent加多问题规划。实际场景中用户往往一次提问包含多个子问题循环里可以先生成问题规划树再依次对每个子节点做导航定位。这能避免在几个问题之间反复横跳吞吐量也更高。至于如何进一步增强系统的通用性我目前在做的是把文档地图生成也交给模型自动完成。输入一批文档模型自动抽取章节结构、生成摘要、识别文档间交叉引用产出标准地图。这样一来新接入一批文档就不再需要手工整理地图整个系统的自动化程度又上了一个台阶。最后分享一个实操心法。我踩过最大的坑是觉得既然让模型自己翻资料那文档预处理就可以随便做做。实际上恰恰相反LoopAgent对文档地图质量的要求极高地图是导航仪正文是道路道路再好导航仪失灵还是白搭。先花时间打磨文档地图比调max_loops参数管用得多。后续我还在尝试的一个方向是把LoopAgent的循环过程加一层记忆缓存。同一类问题多次问到时第一次的导航路径会被缓存下来后续查询直接复用。对于企业知识库这种高频重复问题占比高的场景这个优化能让平均耗时降一半以上。这套方案现在还在继续迭代有结果了再来更新。
先交代一个背景。前段时间我需要在一堆产品技术文档里快速定位一个冷门配置项的含义手头没有现成的知识库临时搭RAG流程又觉得太折腾。后来我换了思路既然大模型本身读得懂文档为什么不让它像人一样自己翻资料于是就有了以轻量 LoopAgent 替代 RAG 实现文档检索的完整实践。这个方案不依赖向量数据库、不需要提前做embedding用一套带循环控制的Agent把筛选文档、定位章节、精读提取串起来实测下来对中小规模文档库的问答检索非常顺手。这篇文章就是那次实践的复盘总结适合那些被RAG的预处理链路搞得不厌其烦、或者手里只有几十到几百篇文档、想快速做一个可靠检索问答能力的开发者。我尽量把方案思路、关键代码、参数设计和踩坑记录都写透你可以直接照着搭一套试试。1. 从RAG到LoopAgent为什么需要换一条技术路线1.1 RAG方案在文档检索中的真实痛点RAG检索增强生成目前的成熟度确实高文档切块、向量化、存库、召回、重排这一套链路已经被讲得很透了。但我自己在实际项目里用下来总有那么几个点很别扭。首先是切分粒度问题。文档切成500字还是1000字按段落切还是按固定窗口切切小了语义容易被腰斩切大了召回精度下降。文档里既有短标题又有大段正文一种切割策略很难同时适配。我踩过的坑是一份操作手册按固定500字切结果很多关键配置项被从上下文里切开召回率很难看。其次是向量库的维护成本。embedding模型要选、要跑向量数据要存、要升级还需要考虑索引重建的时机。文档内容更新了向量库要不要同步重算很多RAG项目上线后最大的痛点反而在索引更新链路内容改了一个字向量库不动检索结果就是过时的。再就是召回精度的天花板。向量相似度召回本质上是语义近似匹配而不是真正的理解定位。一个问题涉及多个文档交叉信息的时候TopK召回经常把最关键的段落漏掉。重排模型能挽回一部分但又多了一个需要维护的模型。这些痛点叠加在一起让我开始思考如果文档总量可控是不是可以不走先向量化再检索这条路1.2 LoopAgent的核心理念让大模型自己翻资料LoopAgent这个词核心就两个词Loop和Agent。Agent指的是以大模型为决策核心具备工具调用能力的执行体Loop指的是它不一次做完所有事而是循环执行观察当前情况、决定下一步行动、调用工具执行、拿到结果继续判断这个闭环直到找出答案。放到文档检索场景里LoopAgent的思路非常直白给模型一个文档目录让它先判断哪些文档最可能包含答案然后打开候选文档的目录结构判断答案落在哪个章节再精读具体章节内容看能不能提取出答案。找不到就换个方向继续找找到就带着答案和出处一起返回。这个过程和人工查资料几乎一模一样。人在查文档的时候不会把整本手册向量化再搜一遍而是先看目录、再翻章节、最后精读。LoopAgent把这种主动导航能力交给了大模型。它不依赖外部索引而是依赖模型对文本结构和语义关系的推理能力。这样一来RAG方案里的向量库、embedding模型、切分策略、召回重排全都省掉了。文档只要能被读取Agent就能按需访问。文档更新也简单重新读一次就是最新版本。1.3 适用场景判断不是所有检索都要上RAG把LoopAgent当替代方案第一个要搞清楚的问题是它适合什么场景不适合什么场景从我实测的经验看轻量LoopAgent最舒服的区间是文档库规模在几十到几百篇、单篇文档长度在几千到几万字的场景。比如企业内部制度汇编、产品说明文档、技术方案合集、论文资料库。这类场景有几个共性文档总数可控目录结构清晰用户问题大多指向具体段落。但当文档规模到几千篇以上LoopAgent的劣势就很明显了。模型每次查询都要做多轮推理和读取文档清单太长光是第一层筛选就要花费大量token。这种超大规模场景RAG的向量召回优势依然不可替代。另外LoopAgent对模型能力有底线要求。小模型如果连根据文档标题判断相关性都做不好整个循环就失去了导航依据。我用的模型至少要有较强的指令遵循能力和中长上下文处理能力。判断标准其实很简单文档量不大、更新频繁、检索精度要求高——选LoopAgent文档量巨大、需要秒级响应——还是选RAG。两者不是取代关系而是互补关系。2. 轻量LoopAgent的整体设计与核心流程2.1 核心组件与数据流设计一套轻量LoopAgent检索系统核心组件可以拆成四块文档地图Document Map这是整个系统的基石。它记录每一篇文档的标题、ID、目录结构、章节路径相当于给模型提供了一份图书索引。文档地图不需要向量化就是结构化的文本元数据。读取工具Document ReaderAgent调用这个工具获取文档内容。它接收文档ID和章节路径作为参数返回对应的文本内容。实现了按需读取而不是一次性把所有文档塞给模型。决策模块Agent Core大模型本体它根据当前掌握的信息做判断。判断结果统一输出成结构化JSON比如候选文档列表、下一步要读的章节路径、是否已经找到答案。循环控制Loop Controller负责编排整个执行流程管理循环次数、token预算、终止条件。这是决定系统收敛性和成本可控性的关键。数据流是这样的用户问题进入Agent Core模型先看文档地图给出候选文档列表然后读取工具按候选文档的目录结构返回对应章节的关键信息模型再判断下一步读哪里循环往复直到模型说找到了答案在这里控制系统校验后输出结果。这里有一个关键设计文档地图和文档正文是分开的。第一次循环只给模型看地图而不是正文这样能大幅节省token也能减少无关信息的干扰。模型判断这篇文档可能相关之后才按需读取正文。2.2 循环策略设计粗筛、定位、精读三级漏斗我实际用的循环策略是三级漏斗结构每一级做的事情不一样循环就是在这些层级之间动态游走。第一级是文档粗筛。模型拿到文档地图后结合问题语义判断哪些文档可能与答案相关。这一步的输出是带排序的候选文档列表通常取前3到5篇。第二级是章节定位。模型打开某个候选文档的章节路径判断答案更可能落在哪个章节。这一步会输出章节路径。如果一个章节读完之后发现没有答案模型会回到文档地图继续看其他章节或者其他候选文档。第三级是精读提取。模型读取定位到的章节正文尝试提取答案。关键是提取时必须带上答案来源的引用片段不能只给一句答案在第二章第一节。这一步的输出会带回给循环控制模块由控制模块判断是否达到终止条件。这个三级漏斗的好处是逐级缩小范围。粗筛阶段面对的是几十篇文档的标题token消耗小定位阶段面对的是一篇文档的目录信息密度高精读阶段才读取真正的正文且只读最有希望的部分。相比RAG全量Embedding一次召回这种按需导航的方式路径短、目标清晰、幻觉率也低。2.3 关键参数与终止机制既然是循环就一定要有边界否则模型可能在文档里反复打转Token费用失控。我整理了下面这套参数直接放出来供参考参数推荐值说明max_loops6~10最大循环轮数防止模型无限转圈top_k_docs3~5每轮最多保留的候选文档数confidence_threshold0.8提取答案的最低置信度max_tokens_per_loop8000每一轮精读的最大Token预算temperature0~0.3生成温度检索场景建议偏低overlap_ratio0.2文本块之间的重叠率防止信息被切断终止机制是这套方案里最容易踩坑的部分。我一开始只设了模型置信度大于阈值就结束结果发现模型有时候会过度自信明明答错了还给出高分。后来加了两个机制来兜底。引用校验答案必须包含原文引用片段找不到原文引用的答案直接降置信度。无进展终止如果连续两轮循环的候选文档集合和章节路径都没有变化说明模型已经在原地打转强制结束返回未找到答案而不是强行编一个。参数值的设定不是拍脑袋。max_loops设6到10是因为大部分文档导航问题在3到5轮内就能定位超过这个轮数基本可以判定为上下文不足或文档地图质量太差。token预算设8000足够精读若干章节正文同时给后续循环留余量。3. 实操从零实现一个轻量LoopAgent3.1 文档预处理的正确姿势做LoopAgent不需要embedding但文档预处理这一步还是逃不掉。预处理的目标是生成一份结构良好、信息密度高的文档地图以及一套支持按需读取的存储结构。我的做法分三步第一步解析文档结构。把PDF、Word、Markdown等格式转成统一的带有标题层级的结构化文本。这一步我会用现成的解析库保留标题层级信息H1、H2、H3和章节序号。解析出来的内容按章节块存储每个章节块记录包含所属文档ID、章节路径、标题、正文、父章节路径。第二步生成文档地图。地图不需要包含全文只需要给模型足够的导航信息。具体内容包括文档ID、完整标题、一级章节列表、二级章节标题、每章开头的第一句话。这些信息加起来每篇文档几百个token几十篇文档的地图也能控制在一次模型请求内。第三步建立读取接口。interface设计成两个函数read_document_map()返回全部文档地图文本read_chapter(doc_id, path)返回指定文档指定章节的正文。对模型而言这是两个工具Agent通过模拟工具调用来完成循环。预处理这里有一条经验文档地图的质量直接决定检索上限。如果你的文档标题都是1.docx2.docx这种毫无语义的名字模型第一层粗筛就会崩。处理办法是提取文档的第一个H1标题作为语义名称或者让模型给每篇文档写一句语义摘要补充到地图里。3.2 循环控制与查询调度的实现要点核心循环控制代码不复杂关键是把模型决策和工具读取解耦。下面是我整理的精简版本import json class LoopAgent: def __init__(self, llm, doc_reader, max_loops8, top_k3, conf_thres0.8): self.llm llm self.reader doc_reader # 文档读取工具 self.max_loops max_loops self.top_k top_k self.conf_thres conf_thres def ask(self, question): doc_map self.reader.read_document_map() candidates [] history [] for loop in range(self.max_loops): # 将文档地图、候选文档、循环历史一并交给LLM决策 decision self.llm.decide( questionquestion, doc_mapdoc_map, candidatescandidates, historyhistory ) if decision[action] extract: # 精读并提取答案 answer, confidence self.reader.extract( doc_iddecision[doc_id], pathdecision[chapter_path], questionquestion ) if confidence self.conf_thres: return self.build_result(answer, confidence, loop) # 置信度不够继续循环并记录失败上下文 history.append(decision) elif decision[action] locate: # 定位到某个章节记录候选 candidates.append({ doc_id: decision[doc_id], path: decision[chapter_path] }) else: # 模型主动判断无需继续 break return self.build_result(None, 0.0, self.max_loops) def build_result(self, answer, confidence, loops): return {answer: answer, confidence: confidence, loops: loops}这段代码有几个设计要点值得展开。一是decide()返回的是结构化JSON对象里面包含action、doc_id、chapter_path、reason四个字段。强制结构化输出能极大提升循环稳定性。模型判断该看哪篇文档的哪个章节时理由也一并给出方便后期排查问错方向的原因。二是history列表的存在。每次决策都会作为上下文进入下一轮。这样模型能在第3轮回忆起第2轮我读过第三章但没找到现在转去读第一章避免重复读同一处。我一开始没加history结果模型经常在相同章节之间反复横跳。三是extract()方法内置了引用校验逻辑。它读取章节正文后会让模型提取答案文本原文引用片段。如果模型拿不出引用片段这个方法直接返回低置信度。这个校验很重要能挡住相当一部分幻觉答案。3.3 效果对比与评测方法系统搭完之后我花了几天做了一套对比评测。评测基准是同一批50个问题分别跑RAG流程和LoopAgent流程。问题分成三类直接答案型如某配置项默认值是多少、方案检索型如如何配置SSO登录、跨文档综合型如对比A、B两种认证方式的差异。评测指标我选了四个答案命中率、平均循环轮数、平均耗时、平均Token消耗。命中率由人工逐条核对Token消耗从各模型的返回统计里读。结果是LoopAgent在这50个问题上命中率达到86%RAG对照组是78%。跨文档综合型问题上的差距最明显LoopAgent输出带有来源引用的答案RAG那边有不少看起来相关但答非所问的情况。平均耗时方面LoopAgent反而更慢单问题均值4.2秒对照RAG是1.8秒因为循环需要多次模型调用。Token消耗这一项LoopAgent也没有明显优势总体比RAG多了二到三成。但这项损耗换来了两个实际收益不需要维护向量库以及答案带有明确的原文出处。对很多内部知识库场景来说这两个收益比省token更值。另外我把文档库从50篇扩到200篇做了一次压力测试。LoopAgent的命中率轻微下降到82%但还在可用范围RAG的命中率保持稳定。这说明上规模之后RAG确实更稳LoopAgent更适合中小规模场景。4. 落地实践中的常见问题与排查技巧4.1 循环不收敛模型原地打转怎么办我遇到最多的异常就是模型在同一个文档的同一个章节反复读取没有新行动。这通常出现在问题比较复杂、第一轮定位偏差比较大的时候。模型可能读了A文档第三章发现没有答案但下一轮决策里还是返回A文档第三章只是换了理由。排查思路分三步。先看history记录确认模型是否真的重复读取了相同路径。如果是说明无进展终止机制没有生效检查终止条件里是否加入了本轮候选集合与上一轮完全相同的判断。再看文档地图质量。如果地图里章节标题太泛全是概述细节附录这样的词模型没有足够的导航信息自然会把动作收敛到很窄的范围。这种情况需要优化地图补充每章的摘要句。最后看模型能力。部分模型在超长上下文中对历史操作不敏感即使给了history也记不住。这时可以在每轮决策里用列表形式高亮上一轮你读了这些、结果是没有答案明确引导模型换方向。我自己的兜底策略是如果第5轮模型仍然没有给出置信度达标的答案我会让模型强制返回当前最优候选片段和对应文档路径再配合外部校验判断可用性而不是让循环继续空转。4.2 成本与延迟控制让循环别那么烧钱LoopAgent最让人肉疼的地方是多次模型调用叠加延迟和成本。我在实测中最低的一套配置单个问题平均消耗9000多token复杂问题能飙到20000。这个量级比RAG高出不少必须做控制。成本控制优先级最高的手段是压缩文档地图。地图不是越长越好它只是导航工具。我最终把每篇文档的地图压到标题一级章节关键二级章节全文的语义摘要只在文档粗筛阶段展示。这个调整让模型决策的token消耗降了约40%。另一个手段是设置精读上限。模块默认一篇文章最多精读3个章节如果3个章节都读完了还没找到直接切换候选文档而不是继续纠结在同一篇里。同时注意控制单次读取的正文长度我一般限制在2000字符左右超过就按章节切块读取。延迟优化方面关键路径上减少模型往返次数。第一轮决策时直接把文档地图候选文档清单一起给模型让它一次输出粗筛结果首个精读章节省掉一个RTT往返时延。实测这个改动把平均耗时从4.2秒降到3.1秒。4.3 一个排查清单开箱即用我把我调试过程中用着顺手的排查步骤整理成清单以后在自己课件、知识库项目里排查问题可以直接照着走。症状排查方向常用解法答案明显张冠李戴检查文档地图是否有重名或重复章节为每篇文档添加ID前缀消除歧义不断重复读取同章节无进展终止条件形同虚设对比相邻两轮候选集合没有变化则强制结束置信度一直低于阈值精读正文与问题关联弱降低单轮读取窗口增加周围上下文重叠度候选文档永远选错文档地图缺少语义摘要让模型对每篇文档做一句话摘要加入地图token消耗暴增多篇文档反复精读设置单篇最大精读章节数超限切换候选最终没有答案返回文档中确实没有对应信息让模型明确输出知识覆盖范围外避免强行编造这套清单的核心思想是先看模型有没有足够的导航信息再看循环有没有明确的边界约束。大部分问题都能在这两个层面找到根因。5. LoopAgent方案的边界与后续扩展方向5.1 什么场景不建议用LoopAgent这节主要是给大家泼冷水。LoopAgent不是万能的有些场景用它是自找麻烦。文档量上千篇、且单篇之间内容高度重叠的时候第一层粗筛会变得极其痛苦。文档地图可能本身就有上千条记录模型决策上下文都快超预算了检索效果还不一定好。这个规模老老实实上向量检索更稳。要求毫秒级响应的在线检索场景也不适合。LoopAgent的多轮交互天然带延迟模型再快也有几百毫秒到几秒的往返时间。如果你做的是客服机器人实时检索这个延迟很容易劝退用户。文档没有稳定结构的时候也别用。比如一堆扫描版PDF、格式混乱的无目录文档LoopAgent连地图都生成不出来。模型导航的前提是文档具有可解析的层级结构没有结构就等于大海捞针。我在自己的项目里把适用范围总结成一句话文档总量不超过几百篇、结构相对规范、检索响应时间能容忍2到5秒、答案需要带出处。满足这四个条件LoopAgent的性价比才会体现出来。5.2 混合模式与后续扩展方向LoopAgent和RAG也不是非此即彼的关系。我现在最新的方案里实际上是一个混合架构粗筛阶段用轻量级RAG只对文档标题和摘要做向量化召回Top10候选再用LoopAgent对候选文档做细粒度精读定位。这样既继承了RAG在海量候选面前的粗筛优势又保留了LoopAgent精读时的准确性。实测混合模式在文档库扩到500篇的时候命中率稳定在85%左右比纯LoopAgent高不少比纯RAG的答非所问问题也少很多。另外一个值得扩展的方向是给LoopAgent加多问题规划。实际场景中用户往往一次提问包含多个子问题循环里可以先生成问题规划树再依次对每个子节点做导航定位。这能避免在几个问题之间反复横跳吞吐量也更高。至于如何进一步增强系统的通用性我目前在做的是把文档地图生成也交给模型自动完成。输入一批文档模型自动抽取章节结构、生成摘要、识别文档间交叉引用产出标准地图。这样一来新接入一批文档就不再需要手工整理地图整个系统的自动化程度又上了一个台阶。最后分享一个实操心法。我踩过最大的坑是觉得既然让模型自己翻资料那文档预处理就可以随便做做。实际上恰恰相反LoopAgent对文档地图质量的要求极高地图是导航仪正文是道路道路再好导航仪失灵还是白搭。先花时间打磨文档地图比调max_loops参数管用得多。后续我还在尝试的一个方向是把LoopAgent的循环过程加一层记忆缓存。同一类问题多次问到时第一次的导航路径会被缓存下来后续查询直接复用。对于企业知识库这种高频重复问题占比高的场景这个优化能让平均耗时降一半以上。这套方案现在还在继续迭代有结果了再来更新。
