不少做智能体开发的朋友一开始都把重点放在“怎么让Agent会规划、会调用API”上结果真正落地时才发现最高频的需求反而是个看起来很朴素的问题让Agent去读取本地那一大堆目录里的文档基于真实资料回答而不是凭空发挥。我自己在给某跨平台系统搭知识问答模块时就把这套“CrewAI智能体 目录RAG搜索”的链路完整跑了一遍踩了一些坑也沉淀了一些方法。这篇就把从文件扫描、解析分块、向量化到封装成CrewAI工具、编排Agent和Task的全过程写清楚适合正在做智能体但又不知道怎么把本地文档变成可检索知识库的开发者参考。目录RAG搜索这件事本质上不是让Agent“更聪明”而是给它补上一条获取私有知识的通道先在文件系统层面按目录扫描出候选文档再通过检索把最相关的片段召回最后把片段塞进模型上下文让Agent有依据地作答。这个思路和纯联网搜索、纯整库投喂都不一样下面我会把每一层的选择和理由都拆开讲。1. 先搞清楚智能体为什么需要“目录级”RAG而不是直接整库投喂1.1 一次项目复盘整库投喂引发的连锁问题最早我实现过一个“把所有文档塞给模型”的版本想着反正模型上下文窗口大直接把一个目录下的所有Markdown、Word拼成一个超长字符串丢给Agent。结果实测下来问题非常典型一是token消耗高得离谱几十份文档动辄几十万字符接口直接报长度超限二是即便没超限模型在中部内容上的召回准确率也明显下降越是藏在长文中间的关键参数越容易被忽略三是修改任何一个文件都得重新拼一遍全量内容维护成本完全不可接受。这个教训让我意识到智能体需要的不是“把所有资料背下来”而是“在需要的时候能快速翻到正确的段落”。这正是RAG解决的事情检索发生在模型推理之前先把问题转化成向量或关键词查询从一个预先建好的索引里挑出TopN相关片段再把片段当作参考资料交给Agent。整个链路里真正决定最终答案质量的不是模型本身而是前面这几步检索环节有没有做扎实。1.2 目录RAG和传统RAG的差异点在哪里常规的RAG系统通常面向一个已经整理好的知识库比如一堆已经切好块的JSON文件、一个数据库表或者一个在线的向量数据集。但目录RAG的输入却是“一个‘活着’的文件夹”里面有不同格式、不同层级、不同命名习惯的文档可能还有嵌套子目录、临时文件、缓存文件。所以它比普通RAG多了一个关键前置步骤——文件系统层的感知与清洗。另一个差异是“来源路径”的重要性。网络搜索结果返回的是网页标题和摘要目录RAG返回的却应该是“哪个文件、哪个章节、哪个位置的内容”。当你在CrewAI里让Agent基于这些片段作答时来源路径不仅是可追溯的依据还能帮助Agent判断资料可信度。比如两份文档对同一参数的说法不一致Agent如果能看到路径里带着“_v2”“已废弃”之类的字眼就能给出更合理的回答。还有一个容易被忽略的点目录RAG天然是分级的。你可以让它在扫描时区分一级目录和二级子目录也可以把目录名、文件名当作独立特征参与检索。这比把所有文件一锅炖进同一个索引要精细得多。2. 文件系统层的准备扫描、过滤与元数据入库2.1 目录遍历程序的基本形态先把最基础的一步做对写一个能稳定遍历目录、识别合法文件、提取元数据的扫描器。我用的方案是Python的pathlib配合os.walk的替代rglob代码非常短但有几个细节必须注意。from pathlib import Path import hashlib ROOT Path(./documents) IGNORE_DIRS {.git, node_modules, __pycache__, .venv, .idea} EXTS {.pdf, .docx, .md, .txt, .html, .htm} def scan_files(root: Path): rows [] for p in sorted(root.rglob(*)): if not p.is_file(): continue if any(part in IGNORE_DIRS for part in p.parts): continue if p.suffix.lower() not in EXTS: continue stat p.stat() rows.append({ path: str(p.relative_to(root)), name: p.stem, ext: p.suffix.lower(), size: stat.st_size, mtime: stat.st_mtime, doc_id: hashlib.md5(str(p.resolve()).encode()).hexdigest()[:16], }) return rows files scan_files(ROOT) print(f共扫描到 {len(files)} 个文件)这里我用了p.resolve()来计算doc_id而不是直接拿相对路径因为不同挂载方式可能导致相对路径相同但文件不同而绝对路径能更好地唯一标识一个实体文件。sorted(rglob(*))的好处是让目录遍历结果稳定有序方便后续增量对比。2.2 文件名和目录路径本身就是检索特征很多人做目录RAG时只想着把正文抽出来做向量却把最重要的廉价信息丢掉了文件名和目录结构。比如文件叫接口说明_v2.pdf路径是docs/支付模块/接口说明_v2.pdf其中“支付模块”和“接口说明”两个词本身就是极强的语义标签。在后续检索时哪怕正文向量匹配不够精准单靠路径关键词都能把候选范围缩窄一大半。所以我建议在给每个文件入库时额外生成一个“路径文本”字段把它和正文块拼接后一起向量化。比如路径文本: documents/支付模块/接口说明_v2.pdf这样查询“支付模块的接口文档”时即使正文里没出现“支付模块”这四个字路径文本也能贡献匹配分数。这个做法成本极低但对召回率的提升非常明显。实测下来单纯靠文件名和目录层级就能解决掉一部分命名规范、缩写不统一的检索问题。2.3 增量更新的实现思路第一次建索引时可以全量扫描但之后如果每次启动都重新解析几百份文档那体验会非常糟糕。我对这个问题的解法很简单利用扫描时拿到的mtime修改时间。第一次全量建索引后把每个doc_id对应的mtime存下来后续启动时只对mtime比上次记录更新的文件重新解析和向量化其余文件直接沿用已有向量。def filter_updated(files, last_indexed): need_update [] for f in files: old_mtime last_indexed.get(f[doc_id], 0) if f[mtime] old_mtime: need_update.append(f) return need_update增量更新的好处不只是省时间更重要的是避免重复向量化导致的索引漂移。如果同一份文件的旧向量和新向量同时存在检索时会出现“同一个文档有两个互相矛盾的版本”这是非常隐蔽的坑。所以更新时一定要先把旧doc_id对应的向量删掉再插入新向量。3. 文档解析与分块把文件变成能被检索的片段3.1 不同格式的解析方案与选型扫描完成只是第一步真正的体力活是把每个文件里的正文提取出来。不同格式有不同的解析方案我按自己试过的稳定性整理了一张表文件格式推荐方案注意点PDFpdfplumber扫描版无文本层时只能跳过或做OCR先明确边界DOCXpython-docx能提取段落和表格但图片文字取不到Markdown直接读文件保留标题层级比较重要TXT直接读文件注意编码常见GBK/UTF-8混合HTMLBeautifulSoup去除标签提取正文时跳过script和style解析的最大原则是“容错优先”一个文件解析失败不应该中断整个流程而是记录到日志里继续处理下一个。我习惯把解析结果统一成一条条的Document记录每条记录至少包含doc_id、source文件路径、text提取的正文三个字段再进入分块环节。3.2 分块策略和中文token的换算分块大小直接决定检索粒度和上下文占用。分块太大每个块里杂音多检索命中率下降分块太小语义被切碎模型看到的上下文不完整。我试过256、512、768字符三档最终稳定在512字符加上64字符的重叠区间。CHUNK_SIZE 512 CHUNK_OVERLAP 64 def split_text(text: str, source: str, doc_id: str): chunks [] start 0 idx 0 while start len(text): end start CHUNK_SIZE chunks.append({ chunk_id: f{doc_id}:{idx}, source: source, text: text[start:end], chunk_index: idx, }) idx 1 if end len(text): break start end - CHUNK_OVERLAP return chunks为什么512合适因为中文场景下一个token大约对应0.5到0.7个汉字512字符换算成token大约是300到350左右。这个体积既能承载一个完整章节的语义又不会在多次召回后把模型上下文撑爆。重叠区间则保证了跨块边界的语义连续性——比如一句话刚好被切成两半时前后两块都保留了它的部分上下文。3.3 空文本与解析失败的处理解析环节真正让人头疼的坑有两个一是PDF看起来有内容但提取出来是空字符串典型的扫描版档案二是DOCX里全是图片和表格python-docx提取到的段落为空。这类文件如果直接丢弃会让后续检索出现盲区。我的处理方式是在文档记录里增加一个empty: True的标记并在日志中单独归类。如果某类文件数量不多就手动处理或者放置一个说明文件如果数量很大则需要考虑是否接入OCR管线。对于绝大多数项目而言先把“能解析的那部分”做扎实比一上来就追求100%全量解析更现实。这个优先级要记清楚。4. 向量化与检索召回从嵌入到TopN命中4.1 Embedding模型的选择逻辑分块完成后每个chunk都要被映射成向量。Embedding模型的选择是召回质量的第一个分水岭。我在这个项目里对比过本地开源模型和在线Embedding服务结论是如果文档以中文技术资料为主、并且对数据隐私有要求本地模型是首选如果追求最高精度、且文件规模不大、访问在线服务没有合规问题那在线服务的综合效果通常更好。选型时我给自己列了几个硬指标维度本地模型在线服务部署成本需要一定内存无部署负担隐私性数据不出内网数据离开本地要评估合规中文效果要看具体模型较稳定离线能力支持不支持成本和配额一次投入按量计费实测下来只要内存给到8GB以上本地模型跑一个几百份文档的目录完全没压力单次向量化的延时也在可接受范围内。关键是把模型加载成全局单例别在每次检索时重复加载模型那会慢到让人崩溃。4.2 向量存储与相似度计算向量存哪里同样是个需要权衡的问题。我分别试过几种方案得到的结论是方案适合规模部署复杂度备注自建numpy矩阵几千chunk最低直接加载到内存适合demo和中小目录ChromaDB万级chunk低功能完善支持过滤条件FAISS百万级chunk中高性能但需要额外管理索引文件我最终选择了“自建numpy 余弦相似度”作为主链路原因很简单目录RAG的chunk量级远没有达到需要专用向量库的规模先把核心逻辑跑通更重要。检索就是一次矩阵乘法import numpy as np embeddings np.array(all_embeddings) # shape: (n_chunks, dim) def search(query_vec: np.ndarray, top_k: int 5): scores embeddings query_vec / (np.linalg.norm(embeddings, axis1) * np.linalg.norm(query_vec) 1e-9) top_idx np.argsort(scores)[::-1][:top_k] return [(index_map[i], float(scores[i])) for i in top_idx]这段代码里加了一个1e-9的小常数防止除零细节虽小但关键时刻能救命。只要chunk总数在可接受范围内这种方式的检索耗时都在毫秒级完全够用。4.3 混合检索与重排序的加分项纯向量检索有个经典问题当查询里包含精确参数名、版本号、缩写时语义相近但字面不同的向量召回往往输给“字面完全一致”的关键词匹配。比如查“timeout默认值 5000ms”如果文档里只写了“超时时间: 5000毫秒”向量检索可能匹配不上“timeout”的词向量。我的解法是引入混合检索先用简单关键词计数或者BM25类方法跑一路“字面命中”再用向量跑一路“语义召回”最后把两路结果做并集或加权融合。这一步不需要引入额外框架用Python自带的difflib或者自己写一个词频打分都行。更重要的是在融合后加一个轻量重排序把来源路径中带“废弃”“old”的片段降权把带“v2”“final”的片段升权。这套组合拳比单独调向量检索的阈值有效得多。5. 在CrewAI里把搜索能力变成Agent工具5.1 用tool装饰器封装RAG搜索前面所有工作最终都要通过CrewAI的工具机制开放给Agent。CrewAI支持自定义工具最简洁的方式是用tool装饰器把一个普通函数变成Agent可调用的工具。from crewai.tools import tool tool(directory_rag_search) def directory_rag_search(query: str) - str: 在本地文档目录中执行RAG检索返回最相关的若干资料片段。 当需要回答依赖具体文档内容的问题时使用例如查找接口参数、配置项、设计说明和操作手册。 返回内容包含来源文件路径便于核对。 chunks retrieve(query, top_k5) return \n\n.join( f[来源: {c[source]}]\n{c[text]} for c in chunks )这里有一个特别重要的细节函数名和参数名都必须是英文但描述文字可以中文。CrewAI会把这段描述作为函数签名的辅助说明注入给模型的function calling上下文模型靠它来判断“什么时候该调用这个工具”。描述越是显式说明“什么场景下用、返回什么格式”Agent的调用率越高。不同版本CrewAI对自定义工具的实现方式略有差异旧版本可能需要继承BaseTool类并实现_run方法新版本则推荐装饰器写法。如果你从旧项目迁移先确认你正在用的CrewAI版本对应用哪种写法别因为版本差异在接入时卡住。5.2 Agent与Task编排的关键设定工具注册好之后就是Agent的定义。角色和目标描述同样要围绕“检索事实依据”来设定不能让Agent觉得自己什么都懂。from crewai import Agent, Task, Crew, Process searcher Agent( role本地资料检索专员, goal根据问题返回本地目录中最相关的文档片段并给出准确来源, backstory你负责检索和维护内部文档库严谨、克制优先引用原文档内容不确定时明确说明, tools[directory_rag_search], verboseTrue, ) search_task Task( description针对用户查询调用目录检索工具获取相关资料整理成带来源路径的摘要回答。若检索结果为空必须明确告知找不到不得编造。, expected_output一份包含来源文件路径和引用片段的回答, agentsearcher, ) crew Crew( agents[searcher], tasks[search_task], processProcess.sequential, ) result crew.kickoff(inputs{query: 支付模块接口的超时时间默认值是多少})Task描述里那句“不得编造”不是废话。实测中如果不加这个约束Agent在检索不到内容时很容易“脑补”一个答案而且语气非常自信。加了之后它至少会老实报告“未检索到相关文档”这已经算是一个可接受的行为了。如果业务场景更复杂可以让一个Agent专门负责检索资料另一个Agent负责阅读检索结果并撰写回复形成检索—写作的流水线。CrewAI的Process.sequential就能满足这种顺序执行前提是Task之间通过上下文传递内容这个需要在定义Task时把前一个Task的输出作为后一个Task的context参数接上。5.3 工具描述写不好Agent就不会用这是我踩过最深的一个坑单独拿出来说。第一次封装时我把工具描述写成了“搜索工具”结果Agent在遇到任何问题时都不调用它每次都直接给出“根据我的知识……”这种泛泛的答案。后来我在日志里看到工具调用次数为零才意识到问题出在描述对模型不友好。模型的function calling机制本质上是在读“说明书”说明书越具体模型越容易在正确时机触发工具。我现在的经验是描述里至少要包含三层信息工具的检索范围本地目录、适用场景查参数、查文档内容、返回内容格式带来源路径的片段。如果有必要还可以在描述里给出一个示例查询“例如查找接口超时时间、配置文件字段说明等”。这段示例文本能让模型对调用条件形成更清晰的理解。改完之后工具调用率从几乎为零提升到了稳定命中效果立竿见影。6. 实测复盘效果调优与踩坑记录6.1 从一次失败的检索测试说起搭建完成后我先做了一个针对某跨平台系统文档目录的测试目录里有约270份可解析文档涵盖设计说明、接口手册、会议纪要和运维记录。第一轮测试我选了一个自以为很简单的问题“登录模块的会话保持时间是多少”结果检索返回的前三名完全跑偏返回的是另一份文档里关于缓存过期时间的描述来源路径和问题毫无关系。排查后发现了两个原因一是该文档中“会话保持”和“过期时间”用了完全不同的措辞向量模型没有把它们关联起来二是那份干扰文档的chunk恰好同时命中了“时间”这个关键词。修复方式正是前面提到的混合检索让关键词匹配优先捕捉“会话保持”“过期时间”这样的精确字面再结合向量召回取并集。调完之后同一问题返回的前五个片段里正确来源排到了第二位Agent给出的答案也变成了“根据接口手册第X节会话保持时间为30分钟见docs/登录模块/会话说明.docx”符合预期。6.2 性能与预算怎么平衡性能瓶颈主要集中在解析和向量化阶段。实测全量解析270份文档耗时接近10分钟其中PDF占了大头。这个时间在首次建索引时可以接受但每次改动都全量重跑确实没有必要。增量更新机制在这里发挥了主要作用后续新增文件时只对变化的文件重新解析基本能做到秒级更新。token预算方面也要有一个明确的度量。512字符的chunk中文大约300多tokenTop5召回约1500到2000 token再加上来源路径分隔符整个工具返回结果在token层面完全可控。我把TopK固定在5而不是10正是因为Top10会把上下文翻倍而提升相对有限。如果你想走深度检索路线可以考虑先召回10个候选再用重排序模型压到3个而不是直接在上下文里塞10个原文块。6.3 我保留的几个经验习惯整理一下实践中沉淀下来的几个固定动作供参考。问题原因解决办法中文路径乱码或解析异常脚本或操作系统默认编码不一致使用pathlib统一路径处理读取文本时显式指定encoding必要时设置UTF-8环境变量增量更新后新旧版本冲突更新时没有删除旧的doc_id向量更新流程先按doc_id删除旧向量再插入新向量Agent不调用工具工具描述太泛模型识别不了触发场景重写描述补充适用条件和返回内容格式可加示例检索结果与答案不符缺少重排序或关键词通道引入混合检索按来源路径加权过滤另外一个偏经验的建议是向量化前可以先把文件名和目录层级作为路径文本拼到chunk里这个简单的操作能显著提高“文档级定位”的准确率。尤其是查询里带模块名、子系统名时路径文本往往提前命中让本来应该在第三第四位的内容升到第一位。最后再分享一个我在实际项目中坚持的做法做目录RAG时先把“检索能不能拿到正确来源”当作唯一的验收标准。也就是说不管模型回答得多漂亮只要来源路径对不上这一轮就算失败直到检索稳定性达到八成以上才开始盯回答措辞和风格。这个顺序帮我避开了大量“看起来能跑、实际一问细节就翻车”的假象。你现在如果正在做CrewAI智能体不妨也照着这个链路先跑一遍把扫描、分块、向量化和工具调用这四层底座打牢Agent的表现自然会跟上来。
不少做智能体开发的朋友一开始都把重点放在“怎么让Agent会规划、会调用API”上结果真正落地时才发现最高频的需求反而是个看起来很朴素的问题让Agent去读取本地那一大堆目录里的文档基于真实资料回答而不是凭空发挥。我自己在给某跨平台系统搭知识问答模块时就把这套“CrewAI智能体 目录RAG搜索”的链路完整跑了一遍踩了一些坑也沉淀了一些方法。这篇就把从文件扫描、解析分块、向量化到封装成CrewAI工具、编排Agent和Task的全过程写清楚适合正在做智能体但又不知道怎么把本地文档变成可检索知识库的开发者参考。目录RAG搜索这件事本质上不是让Agent“更聪明”而是给它补上一条获取私有知识的通道先在文件系统层面按目录扫描出候选文档再通过检索把最相关的片段召回最后把片段塞进模型上下文让Agent有依据地作答。这个思路和纯联网搜索、纯整库投喂都不一样下面我会把每一层的选择和理由都拆开讲。1. 先搞清楚智能体为什么需要“目录级”RAG而不是直接整库投喂1.1 一次项目复盘整库投喂引发的连锁问题最早我实现过一个“把所有文档塞给模型”的版本想着反正模型上下文窗口大直接把一个目录下的所有Markdown、Word拼成一个超长字符串丢给Agent。结果实测下来问题非常典型一是token消耗高得离谱几十份文档动辄几十万字符接口直接报长度超限二是即便没超限模型在中部内容上的召回准确率也明显下降越是藏在长文中间的关键参数越容易被忽略三是修改任何一个文件都得重新拼一遍全量内容维护成本完全不可接受。这个教训让我意识到智能体需要的不是“把所有资料背下来”而是“在需要的时候能快速翻到正确的段落”。这正是RAG解决的事情检索发生在模型推理之前先把问题转化成向量或关键词查询从一个预先建好的索引里挑出TopN相关片段再把片段当作参考资料交给Agent。整个链路里真正决定最终答案质量的不是模型本身而是前面这几步检索环节有没有做扎实。1.2 目录RAG和传统RAG的差异点在哪里常规的RAG系统通常面向一个已经整理好的知识库比如一堆已经切好块的JSON文件、一个数据库表或者一个在线的向量数据集。但目录RAG的输入却是“一个‘活着’的文件夹”里面有不同格式、不同层级、不同命名习惯的文档可能还有嵌套子目录、临时文件、缓存文件。所以它比普通RAG多了一个关键前置步骤——文件系统层的感知与清洗。另一个差异是“来源路径”的重要性。网络搜索结果返回的是网页标题和摘要目录RAG返回的却应该是“哪个文件、哪个章节、哪个位置的内容”。当你在CrewAI里让Agent基于这些片段作答时来源路径不仅是可追溯的依据还能帮助Agent判断资料可信度。比如两份文档对同一参数的说法不一致Agent如果能看到路径里带着“_v2”“已废弃”之类的字眼就能给出更合理的回答。还有一个容易被忽略的点目录RAG天然是分级的。你可以让它在扫描时区分一级目录和二级子目录也可以把目录名、文件名当作独立特征参与检索。这比把所有文件一锅炖进同一个索引要精细得多。2. 文件系统层的准备扫描、过滤与元数据入库2.1 目录遍历程序的基本形态先把最基础的一步做对写一个能稳定遍历目录、识别合法文件、提取元数据的扫描器。我用的方案是Python的pathlib配合os.walk的替代rglob代码非常短但有几个细节必须注意。from pathlib import Path import hashlib ROOT Path(./documents) IGNORE_DIRS {.git, node_modules, __pycache__, .venv, .idea} EXTS {.pdf, .docx, .md, .txt, .html, .htm} def scan_files(root: Path): rows [] for p in sorted(root.rglob(*)): if not p.is_file(): continue if any(part in IGNORE_DIRS for part in p.parts): continue if p.suffix.lower() not in EXTS: continue stat p.stat() rows.append({ path: str(p.relative_to(root)), name: p.stem, ext: p.suffix.lower(), size: stat.st_size, mtime: stat.st_mtime, doc_id: hashlib.md5(str(p.resolve()).encode()).hexdigest()[:16], }) return rows files scan_files(ROOT) print(f共扫描到 {len(files)} 个文件)这里我用了p.resolve()来计算doc_id而不是直接拿相对路径因为不同挂载方式可能导致相对路径相同但文件不同而绝对路径能更好地唯一标识一个实体文件。sorted(rglob(*))的好处是让目录遍历结果稳定有序方便后续增量对比。2.2 文件名和目录路径本身就是检索特征很多人做目录RAG时只想着把正文抽出来做向量却把最重要的廉价信息丢掉了文件名和目录结构。比如文件叫接口说明_v2.pdf路径是docs/支付模块/接口说明_v2.pdf其中“支付模块”和“接口说明”两个词本身就是极强的语义标签。在后续检索时哪怕正文向量匹配不够精准单靠路径关键词都能把候选范围缩窄一大半。所以我建议在给每个文件入库时额外生成一个“路径文本”字段把它和正文块拼接后一起向量化。比如路径文本: documents/支付模块/接口说明_v2.pdf这样查询“支付模块的接口文档”时即使正文里没出现“支付模块”这四个字路径文本也能贡献匹配分数。这个做法成本极低但对召回率的提升非常明显。实测下来单纯靠文件名和目录层级就能解决掉一部分命名规范、缩写不统一的检索问题。2.3 增量更新的实现思路第一次建索引时可以全量扫描但之后如果每次启动都重新解析几百份文档那体验会非常糟糕。我对这个问题的解法很简单利用扫描时拿到的mtime修改时间。第一次全量建索引后把每个doc_id对应的mtime存下来后续启动时只对mtime比上次记录更新的文件重新解析和向量化其余文件直接沿用已有向量。def filter_updated(files, last_indexed): need_update [] for f in files: old_mtime last_indexed.get(f[doc_id], 0) if f[mtime] old_mtime: need_update.append(f) return need_update增量更新的好处不只是省时间更重要的是避免重复向量化导致的索引漂移。如果同一份文件的旧向量和新向量同时存在检索时会出现“同一个文档有两个互相矛盾的版本”这是非常隐蔽的坑。所以更新时一定要先把旧doc_id对应的向量删掉再插入新向量。3. 文档解析与分块把文件变成能被检索的片段3.1 不同格式的解析方案与选型扫描完成只是第一步真正的体力活是把每个文件里的正文提取出来。不同格式有不同的解析方案我按自己试过的稳定性整理了一张表文件格式推荐方案注意点PDFpdfplumber扫描版无文本层时只能跳过或做OCR先明确边界DOCXpython-docx能提取段落和表格但图片文字取不到Markdown直接读文件保留标题层级比较重要TXT直接读文件注意编码常见GBK/UTF-8混合HTMLBeautifulSoup去除标签提取正文时跳过script和style解析的最大原则是“容错优先”一个文件解析失败不应该中断整个流程而是记录到日志里继续处理下一个。我习惯把解析结果统一成一条条的Document记录每条记录至少包含doc_id、source文件路径、text提取的正文三个字段再进入分块环节。3.2 分块策略和中文token的换算分块大小直接决定检索粒度和上下文占用。分块太大每个块里杂音多检索命中率下降分块太小语义被切碎模型看到的上下文不完整。我试过256、512、768字符三档最终稳定在512字符加上64字符的重叠区间。CHUNK_SIZE 512 CHUNK_OVERLAP 64 def split_text(text: str, source: str, doc_id: str): chunks [] start 0 idx 0 while start len(text): end start CHUNK_SIZE chunks.append({ chunk_id: f{doc_id}:{idx}, source: source, text: text[start:end], chunk_index: idx, }) idx 1 if end len(text): break start end - CHUNK_OVERLAP return chunks为什么512合适因为中文场景下一个token大约对应0.5到0.7个汉字512字符换算成token大约是300到350左右。这个体积既能承载一个完整章节的语义又不会在多次召回后把模型上下文撑爆。重叠区间则保证了跨块边界的语义连续性——比如一句话刚好被切成两半时前后两块都保留了它的部分上下文。3.3 空文本与解析失败的处理解析环节真正让人头疼的坑有两个一是PDF看起来有内容但提取出来是空字符串典型的扫描版档案二是DOCX里全是图片和表格python-docx提取到的段落为空。这类文件如果直接丢弃会让后续检索出现盲区。我的处理方式是在文档记录里增加一个empty: True的标记并在日志中单独归类。如果某类文件数量不多就手动处理或者放置一个说明文件如果数量很大则需要考虑是否接入OCR管线。对于绝大多数项目而言先把“能解析的那部分”做扎实比一上来就追求100%全量解析更现实。这个优先级要记清楚。4. 向量化与检索召回从嵌入到TopN命中4.1 Embedding模型的选择逻辑分块完成后每个chunk都要被映射成向量。Embedding模型的选择是召回质量的第一个分水岭。我在这个项目里对比过本地开源模型和在线Embedding服务结论是如果文档以中文技术资料为主、并且对数据隐私有要求本地模型是首选如果追求最高精度、且文件规模不大、访问在线服务没有合规问题那在线服务的综合效果通常更好。选型时我给自己列了几个硬指标维度本地模型在线服务部署成本需要一定内存无部署负担隐私性数据不出内网数据离开本地要评估合规中文效果要看具体模型较稳定离线能力支持不支持成本和配额一次投入按量计费实测下来只要内存给到8GB以上本地模型跑一个几百份文档的目录完全没压力单次向量化的延时也在可接受范围内。关键是把模型加载成全局单例别在每次检索时重复加载模型那会慢到让人崩溃。4.2 向量存储与相似度计算向量存哪里同样是个需要权衡的问题。我分别试过几种方案得到的结论是方案适合规模部署复杂度备注自建numpy矩阵几千chunk最低直接加载到内存适合demo和中小目录ChromaDB万级chunk低功能完善支持过滤条件FAISS百万级chunk中高性能但需要额外管理索引文件我最终选择了“自建numpy 余弦相似度”作为主链路原因很简单目录RAG的chunk量级远没有达到需要专用向量库的规模先把核心逻辑跑通更重要。检索就是一次矩阵乘法import numpy as np embeddings np.array(all_embeddings) # shape: (n_chunks, dim) def search(query_vec: np.ndarray, top_k: int 5): scores embeddings query_vec / (np.linalg.norm(embeddings, axis1) * np.linalg.norm(query_vec) 1e-9) top_idx np.argsort(scores)[::-1][:top_k] return [(index_map[i], float(scores[i])) for i in top_idx]这段代码里加了一个1e-9的小常数防止除零细节虽小但关键时刻能救命。只要chunk总数在可接受范围内这种方式的检索耗时都在毫秒级完全够用。4.3 混合检索与重排序的加分项纯向量检索有个经典问题当查询里包含精确参数名、版本号、缩写时语义相近但字面不同的向量召回往往输给“字面完全一致”的关键词匹配。比如查“timeout默认值 5000ms”如果文档里只写了“超时时间: 5000毫秒”向量检索可能匹配不上“timeout”的词向量。我的解法是引入混合检索先用简单关键词计数或者BM25类方法跑一路“字面命中”再用向量跑一路“语义召回”最后把两路结果做并集或加权融合。这一步不需要引入额外框架用Python自带的difflib或者自己写一个词频打分都行。更重要的是在融合后加一个轻量重排序把来源路径中带“废弃”“old”的片段降权把带“v2”“final”的片段升权。这套组合拳比单独调向量检索的阈值有效得多。5. 在CrewAI里把搜索能力变成Agent工具5.1 用tool装饰器封装RAG搜索前面所有工作最终都要通过CrewAI的工具机制开放给Agent。CrewAI支持自定义工具最简洁的方式是用tool装饰器把一个普通函数变成Agent可调用的工具。from crewai.tools import tool tool(directory_rag_search) def directory_rag_search(query: str) - str: 在本地文档目录中执行RAG检索返回最相关的若干资料片段。 当需要回答依赖具体文档内容的问题时使用例如查找接口参数、配置项、设计说明和操作手册。 返回内容包含来源文件路径便于核对。 chunks retrieve(query, top_k5) return \n\n.join( f[来源: {c[source]}]\n{c[text]} for c in chunks )这里有一个特别重要的细节函数名和参数名都必须是英文但描述文字可以中文。CrewAI会把这段描述作为函数签名的辅助说明注入给模型的function calling上下文模型靠它来判断“什么时候该调用这个工具”。描述越是显式说明“什么场景下用、返回什么格式”Agent的调用率越高。不同版本CrewAI对自定义工具的实现方式略有差异旧版本可能需要继承BaseTool类并实现_run方法新版本则推荐装饰器写法。如果你从旧项目迁移先确认你正在用的CrewAI版本对应用哪种写法别因为版本差异在接入时卡住。5.2 Agent与Task编排的关键设定工具注册好之后就是Agent的定义。角色和目标描述同样要围绕“检索事实依据”来设定不能让Agent觉得自己什么都懂。from crewai import Agent, Task, Crew, Process searcher Agent( role本地资料检索专员, goal根据问题返回本地目录中最相关的文档片段并给出准确来源, backstory你负责检索和维护内部文档库严谨、克制优先引用原文档内容不确定时明确说明, tools[directory_rag_search], verboseTrue, ) search_task Task( description针对用户查询调用目录检索工具获取相关资料整理成带来源路径的摘要回答。若检索结果为空必须明确告知找不到不得编造。, expected_output一份包含来源文件路径和引用片段的回答, agentsearcher, ) crew Crew( agents[searcher], tasks[search_task], processProcess.sequential, ) result crew.kickoff(inputs{query: 支付模块接口的超时时间默认值是多少})Task描述里那句“不得编造”不是废话。实测中如果不加这个约束Agent在检索不到内容时很容易“脑补”一个答案而且语气非常自信。加了之后它至少会老实报告“未检索到相关文档”这已经算是一个可接受的行为了。如果业务场景更复杂可以让一个Agent专门负责检索资料另一个Agent负责阅读检索结果并撰写回复形成检索—写作的流水线。CrewAI的Process.sequential就能满足这种顺序执行前提是Task之间通过上下文传递内容这个需要在定义Task时把前一个Task的输出作为后一个Task的context参数接上。5.3 工具描述写不好Agent就不会用这是我踩过最深的一个坑单独拿出来说。第一次封装时我把工具描述写成了“搜索工具”结果Agent在遇到任何问题时都不调用它每次都直接给出“根据我的知识……”这种泛泛的答案。后来我在日志里看到工具调用次数为零才意识到问题出在描述对模型不友好。模型的function calling机制本质上是在读“说明书”说明书越具体模型越容易在正确时机触发工具。我现在的经验是描述里至少要包含三层信息工具的检索范围本地目录、适用场景查参数、查文档内容、返回内容格式带来源路径的片段。如果有必要还可以在描述里给出一个示例查询“例如查找接口超时时间、配置文件字段说明等”。这段示例文本能让模型对调用条件形成更清晰的理解。改完之后工具调用率从几乎为零提升到了稳定命中效果立竿见影。6. 实测复盘效果调优与踩坑记录6.1 从一次失败的检索测试说起搭建完成后我先做了一个针对某跨平台系统文档目录的测试目录里有约270份可解析文档涵盖设计说明、接口手册、会议纪要和运维记录。第一轮测试我选了一个自以为很简单的问题“登录模块的会话保持时间是多少”结果检索返回的前三名完全跑偏返回的是另一份文档里关于缓存过期时间的描述来源路径和问题毫无关系。排查后发现了两个原因一是该文档中“会话保持”和“过期时间”用了完全不同的措辞向量模型没有把它们关联起来二是那份干扰文档的chunk恰好同时命中了“时间”这个关键词。修复方式正是前面提到的混合检索让关键词匹配优先捕捉“会话保持”“过期时间”这样的精确字面再结合向量召回取并集。调完之后同一问题返回的前五个片段里正确来源排到了第二位Agent给出的答案也变成了“根据接口手册第X节会话保持时间为30分钟见docs/登录模块/会话说明.docx”符合预期。6.2 性能与预算怎么平衡性能瓶颈主要集中在解析和向量化阶段。实测全量解析270份文档耗时接近10分钟其中PDF占了大头。这个时间在首次建索引时可以接受但每次改动都全量重跑确实没有必要。增量更新机制在这里发挥了主要作用后续新增文件时只对变化的文件重新解析基本能做到秒级更新。token预算方面也要有一个明确的度量。512字符的chunk中文大约300多tokenTop5召回约1500到2000 token再加上来源路径分隔符整个工具返回结果在token层面完全可控。我把TopK固定在5而不是10正是因为Top10会把上下文翻倍而提升相对有限。如果你想走深度检索路线可以考虑先召回10个候选再用重排序模型压到3个而不是直接在上下文里塞10个原文块。6.3 我保留的几个经验习惯整理一下实践中沉淀下来的几个固定动作供参考。问题原因解决办法中文路径乱码或解析异常脚本或操作系统默认编码不一致使用pathlib统一路径处理读取文本时显式指定encoding必要时设置UTF-8环境变量增量更新后新旧版本冲突更新时没有删除旧的doc_id向量更新流程先按doc_id删除旧向量再插入新向量Agent不调用工具工具描述太泛模型识别不了触发场景重写描述补充适用条件和返回内容格式可加示例检索结果与答案不符缺少重排序或关键词通道引入混合检索按来源路径加权过滤另外一个偏经验的建议是向量化前可以先把文件名和目录层级作为路径文本拼到chunk里这个简单的操作能显著提高“文档级定位”的准确率。尤其是查询里带模块名、子系统名时路径文本往往提前命中让本来应该在第三第四位的内容升到第一位。最后再分享一个我在实际项目中坚持的做法做目录RAG时先把“检索能不能拿到正确来源”当作唯一的验收标准。也就是说不管模型回答得多漂亮只要来源路径对不上这一轮就算失败直到检索稳定性达到八成以上才开始盯回答措辞和风格。这个顺序帮我避开了大量“看起来能跑、实际一问细节就翻车”的假象。你现在如果正在做CrewAI智能体不妨也照着这个链路先跑一遍把扫描、分块、向量化和工具调用这四层底座打牢Agent的表现自然会跟上来。
平方复杂度无法被常规优化消除｜TaoToken 统一 Key 通道实测)
