AI Agent 知识获取管道实战：TypeScript 实现 RAG 检索增强生成

1. 为什么知识获取管道是 AI Agent 落地的第一道坎做 AI Agent 开发的人绕不开一个尴尬的现实模型本身很聪明但它不知道你公司内部的业务规则、不知道你昨天刚更新的产品文档、更不知道你私有的那套数据表结构。你问它一个关于你自家系统的问题它要么一本正经地胡说八道要么礼貌地告诉你“我无法访问该信息”。这不是模型不行而是它的知识边界被训练数据锁死了。解决这个问题的核心手段就是RAGRetrieval-Augmented Generation检索增强生成。这个词这两年已经被说烂了但真正动手搭过一套能用的知识获取管道的人都知道坑远比想象中多。我见过太多团队兴冲冲地接了个向量数据库把文档一股脑塞进去结果上线后检索命中率惨不忍睹Agent 回答得驴唇不对马嘴最后项目不了了之。这一篇是“走进 AI Agent”系列的第四篇专门聊知识获取管道。我会用TypeScript作为主要实现语言因为它在 Agent 开发中的生态越来越成熟类型系统对复杂数据流的约束能力在实际工程里非常香。整篇内容会从 RAG 的基本原理讲起一路拆到文档切分、向量化、检索策略、重排序最后给出一个可以跑起来的最小实现。不管你是刚接触 RAG 的新手还是已经踩过一些坑的老手应该都能从中找到对自己有用的东西。提示这篇是基础篇重点在于把管道的每一段讲透而不是堆砌花哨的框架。理解了原理换任何语言、任何向量库都能快速迁移。2. RAG 到底在解决什么问题从模型的知识盲区说起2.1 大模型的三类知识缺陷要理解 RAG 的价值先得搞清楚大模型在知识层面到底缺什么。我把它们归为三类第一类是时效性缺失。模型的训练数据有截止日期之后发生的事情它一概不知。你问它某个产品上个月发布的新功能它只能靠猜。这在快速迭代的业务场景里是致命的。第二类是私有性缺失。你公司的内部文档、客户数据、业务规则这些从来没有出现在公开训练语料里模型自然不可能知道。而 Agent 要真正干活恰恰最依赖这些私有知识。第三类是精确性缺失。就算模型“大概知道”某个领域的知识它也可能记错细节。比如某个 API 的参数顺序、某个配置项的默认值模型很容易张冠李戴。这种错误在代码生成场景里尤其常见。RAG 的思路很直接既然模型不知道那我在它回答问题之前先把相关资料检索出来塞进它的上下文里让它“看着资料回答”。这就像开卷考试模型不需要把所有知识背下来只需要具备理解和推理能力资料由外部提供。2.2 RAG 与微调的分工边界很多人会问为什么不直接微调模型把知识灌进去这是个好问题但答案很明确——微调和 RAG 解决的是不同层面的问题。微调改变的是模型的“行为模式”和“表达风格”比如让它学会用某种特定的语气回答、遵循某种输出格式、掌握某个领域的推理范式。但微调很难可靠地注入事实性知识而且知识一旦更新就得重新训练成本极高。RAG 则专注于“事实供给”。知识存在外部随时可以更新检索到什么就回答什么模型本身不用动。对于绝大多数企业级 Agent 场景RAG 是性价比最高的知识注入方式。我的经验是先上 RAG只有当 RAG 解决不了行为层面的问题时才考虑微调。2.3 一条完整的知识获取管道长什么样RAG 不是一个单点技术而是一条管道。从原始文档到最终喂给模型的上下文中间要经过好几个环节。我把它拆成两大部分离线索引阶段文档加载 → 文本切分 → 向量化 → 存入向量库。这一步是提前做好的文档更新时重新跑。在线检索阶段用户提问 → 查询向量化 → 向量检索 → 重排序 → 组装上下文 → 喂给模型。这一步是每次请求实时执行的。管道里每一段都有讲究。切分粒度不对检索出来的片段要么太碎没上下文要么太长噪音多向量模型选错语义相似度算不准检索策略单一召回率上不去。后面我会逐段拆解。3. 文档切分决定检索质量的第一道分水岭3.1 为什么不能把整篇文档直接向量化新手最容易犯的错误就是把一整篇文档当成一个向量存进去。这么做的问题在于一篇几千字的文档向量化之后只有一个向量表示它压缩了太多信息。当你检索时这个向量和查询向量的相似度是一个“平均值”既不能精确匹配文档里的某个具体段落又会因为信息太杂导致相似度被稀释。打个比方这就像你把一本书的读后感写成一个词然后指望别人通过这个词找到书里某一页的具体内容。显然不现实。正确的做法是把文档切成合适大小的片段chunk每个片段单独向量化检索时精确命中相关片段。3.2 固定长度切分的陷阱与改进最朴素的切分方式是固定字符数比如每 500 字切一段。这种方式实现简单但问题很明显它会在句子中间、段落中间甚至代码块中间硬切导致语义断裂。我早期做的一个项目就吃过这个亏。当时用固定 500 字切分技术文档结果一个完整的函数定义被切成两半检索出来的片段只有函数签名没有函数体模型看了半天也答不对。后来改成按语义边界切分效果立刻好转。改进思路是优先按段落、标题、代码块等自然边界切分如果某个段落超过阈值再在段落内部按句子边界切。这样能最大程度保持语义完整性。3.3 重叠窗口一个容易被忽视的细节即使按语义边界切分相邻片段之间也可能存在上下文依赖。比如一个概念在片段 A 里定义在片段 B 里使用如果检索只命中 B模型就缺少定义信息。解决办法是设置重叠窗口overlap相邻片段之间保留一定量的重复内容。常见的做法是重叠 10% 到 20%。比如片段大小 500 字重叠 50 到 100 字。重叠不是越多越好。重叠太多会导致向量库里冗余内容增加检索时返回一堆高度相似的片段浪费上下文窗口。我一般从 15% 起步根据实际检索效果微调。3.4 用 TypeScript 实现一个语义感知的切分器下面是一个基于段落和句子边界的切分器实现核心逻辑是先按段落聚合超过阈值再按句子切同时保留重叠interface Chunk { content: string; index: number; metadata: Recordstring, unknown; } interface SplitOptions { maxChunkSize: number; overlapSize: number; } function splitText(text: string, options: SplitOptions): Chunk[] { const { maxChunkSize, overlapSize } options; const paragraphs text.split(/\n\s*\n/).filter((p) p.trim().length 0); const chunks: Chunk[] []; let buffer ; let index 0; const flush () { if (buffer.trim().length 0) return; chunks.push({ content: buffer.trim(), index: index, metadata: {}, }); // 保留尾部作为下一个片段的重叠部分 buffer buffer.slice(-overlapSize); }; for (const para of paragraphs) { if ((buffer para).length maxChunkSize) { buffer (buffer ? \n\n : ) para; } else { flush(); if (para.length maxChunkSize) { // 段落本身超长按句子切 const sentences para.split(/(?[。.!?])\s*/); for (const sentence of sentences) { if ((buffer sentence).length maxChunkSize) { flush(); } buffer sentence; } } else { buffer (buffer ? \n\n : ) para; } } } flush(); return chunks; }这段代码的关键点在于flush函数里保留了尾部重叠以及超长段落会降级到句子级切分。实际项目里你还可以根据文档类型做更细的处理比如 Markdown 按标题层级切、代码按函数切。注意切分粒度没有万能参数。技术文档适合 500 到 800 字对话记录适合 200 到 300 字法律合同可能要 1000 字以上。一定要拿真实数据测。4. 向量化与向量库选型语义检索的引擎4.1 向量化模型怎么选向量化模型embedding model负责把文本转成高维向量是语义检索的核心。选型时主要看三个维度语义表达能力、语言支持、成本与延迟。语义表达能力直接决定检索准确率。一般来说参数量更大的模型表达力更强但推理成本也更高。对于中文场景要特别关注模型在中文语义相似度任务上的表现不能只看英文 benchmark。我的建议是先用一个中等规模、支持多语言的模型起步比如常见的开源 embedding 模型跑通整条管道后再根据检索效果决定是否升级。不要一上来就追求最强模型因为瓶颈往往不在模型本身而在切分和检索策略。4.2 向量库的几种形态向量库负责存储向量并支持相似度检索。市面上的选择大致分三类类型代表适用场景注意事项专用向量库各类独立向量数据库大规模、高并发检索运维成本较高需独立部署传统数据库扩展关系库的向量插件中小规模、已有数据库性能受限于原数据库内存向量索引进程内索引库原型验证、小数据集数据量大时内存吃紧对于刚起步的项目我强烈建议先用内存向量索引跑通流程。数据量在几万条以内时内存索引的检索速度完全够用而且省去了部署和运维的麻烦。等数据量上来了、性能成为瓶颈了再迁移到专用向量库。4.3 相似度度量余弦还是点积向量检索常用的相似度度量有两种余弦相似度和点积。很多人纠结选哪个其实关键看向量是否归一化。如果向量已经归一化长度为 1那么余弦相似度和点积是等价的。大多数 embedding 模型输出的向量默认就是归一化的所以两者结果一样。如果没归一化余弦相似度只看向量方向点积还受向量长度影响。我的做法是统一做归一化然后用点积。因为点积计算更快而且归一化之后语义上等价于余弦。这个细节在数据量大时对性能有实际影响。4.4 用 TypeScript 封装一个向量化与检索模块下面是一个简化的向量化与内存检索实现重点展示接口设计和归一化处理interface VectorRecord { id: string; vector: number[]; content: string; metadata: Recordstring, unknown; } function normalize(vec: number[]): number[] { const norm Math.sqrt(vec.reduce((sum, v) sum v * v, 0)); if (norm 0) return vec; return vec.map((v) v / norm); } function dotProduct(a: number[], b: number[]): number { let sum 0; for (let i 0; i a.length; i) { sum a[i] * b[i]; } return sum; } class InMemoryVectorStore { private records: VectorRecord[] []; add(record: VectorRecord): void { this.records.push({ ...record, vector: normalize(record.vector), }); } search(queryVector: number[], topK: number): VectorRecord[] { const normalizedQuery normalize(queryVector); const scored this.records.map((record) ({ record, score: dotProduct(normalizedQuery, record.vector), })); scored.sort((a, b) b.score - a.score); return scored.slice(0, topK).map((item) item.record); } }这个实现虽然简单但把核心逻辑都覆盖了归一化、点积打分、排序取 TopK。生产环境里你会用现成的向量库但理解这层逻辑对排查问题很有帮助——当检索结果不对时你能判断是向量化的问题还是检索的问题。5. 检索策略从“能查到”到“查得准”5.1 纯向量检索的局限向量检索擅长语义匹配但有个明显短板对精确关键词不敏感。比如你搜一个产品型号“XR-2000”向量检索可能返回一堆语义相近但型号不同的文档因为它关注的是整体语义而不是精确的字符串匹配。这在技术文档、法律条文、产品手册等场景里是硬伤。用户搜的往往就是某个精确的术语或编号这时候纯向量检索会掉链子。5.2 混合检索向量加关键词解决办法是混合检索hybrid search同时跑向量检索和关键词检索比如 BM25然后把两路结果融合。向量检索负责语义召回关键词检索负责精确召回两者互补。融合策略常见的有两种加权求和和倒数排名融合RRF。加权求和需要调权重比较麻烦RRF 只看排名不看分数更鲁棒我个人更推荐。RRF 的公式很简单每个文档的最终得分等于它在各路结果中排名的倒数之和。排名越靠前贡献越大。这样即使两路检索的分数尺度不同也能公平融合。5.3 重排序检索质量的最后一道保险混合检索解决了召回问题但返回的 TopK 里仍然可能混有不太相关的片段。这时候就需要重排序rerank。重排序用一个更精细的模型通常是交叉编码器对查询和每个候选片段做深度匹配打分然后重新排序。它比向量检索慢但准确率高得多。所以典型做法是向量检索先召回 50 条重排序精选出 5 条喂给模型。这个“先粗筛后精排”的两阶段思路是工业界 RAG 系统的标配。粗筛保证召回率精排保证准确率各司其职。5.4 查询改写让用户的问题更好检索用户提问往往很口语化直接拿去检索效果不好。比如用户问“那个新功能怎么用”这里的“那个新功能”指代不明检索系统无从下手。查询改写query rewriting就是用模型把用户问题改写成更适合检索的形式。可以补充上下文、拆解多意图、生成多个查询变体。比如把“那个新功能怎么用”改写成“XX 产品新功能使用步骤”。这一步在 Agent 场景里尤其重要因为 Agent 往往要基于对话历史理解用户意图。把历史上下文和当前问题一起交给模型改写能显著提升检索命中率。6. 组装上下文把检索结果变成模型能用的输入6.1 上下文窗口的分配策略检索出一堆片段后不能无脑全塞给模型。模型的上下文窗口有限塞太多会挤占推理空间还会引入噪音。需要做上下文预算管理。我的做法是给不同来源分配配额检索片段占大头比如 60%系统提示词占一部分对话历史占一部分留一部分给模型输出。检索片段内部再按相关性排序优先放高分片段。6.2 片段去重与冲突处理检索结果里经常出现高度相似的片段尤其是设置了重叠窗口之后。这些重复内容浪费上下文需要去重。简单的做法是按内容相似度过滤保留得分最高的那条。更麻烦的是冲突处理不同片段对同一问题给出矛盾信息。这时候要么按来源可信度排序要么在提示词里明确告诉模型存在冲突让它自己判断。我倾向于后者因为模型在明确提示下通常能做出合理取舍。6.3 提示词模板的设计要点组装上下文时提示词模板的设计直接影响回答质量。几个关键点明确角色和任务告诉模型它是基于给定资料回答问题的助手。标注资料来源每个片段带上来源标识方便模型引用也方便你排查问题。约束回答边界明确要求模型只基于给定资料回答资料里没有就说不知道避免它自由发挥。给出输出格式如果需要结构化输出在模板里说清楚。一个常见的坑是提示词太啰嗦把模型绕晕。我的经验是简洁明确把关键约束说清楚就行不要写一大段。7. 一个可运行的最小 RAG 管道实现7.1 整体架构与数据流把前面几部分串起来一个最小可用的 RAG 管道包含这些模块文档加载器读取原始文档提取文本。切分器把文本切成片段。向量化器调用 embedding 模型生成向量。向量存储保存向量和原文。检索器查询向量化 相似度检索。上下文组装器拼接检索结果和提示词。生成器调用大模型生成回答。数据流是离线阶段跑 1 到 4在线阶段跑 5 到 7。7.2 关键代码骨架下面是管道主流程的 TypeScript 骨架展示各模块如何协作interface RagPipelineConfig { embeddingModel: EmbeddingModel; llm: LanguageModel; vectorStore: InMemoryVectorStore; splitOptions: SplitOptions; } class RagPipeline { constructor(private config: RagPipelineConfig) {} async indexDocument(text: string, metadata: Recordstring, unknown) { const chunks splitText(text, this.config.splitOptions); for (const chunk of chunks) { const vector await this.config.embeddingModel.embed(chunk.content); this.config.vectorStore.add({ id: ${metadata.docId}-${chunk.index}, vector, content: chunk.content, metadata: { ...metadata, ...chunk.metadata }, }); } } async query(question: string, topK 5): Promisestring { const queryVector await this.config.embeddingModel.embed(question); const results this.config.vectorStore.search(queryVector, topK); const context results .map((r, i) [片段${i 1}]\n${r.content}) .join(\n\n); const prompt this.buildPrompt(question, context); return this.config.llm.generate(prompt); } private buildPrompt(question: string, context: string): string { return [ 你是一个基于资料回答问题的助手。, 请只根据下面提供的资料回答问题资料中没有的信息不要编造。, , 资料, context, , 问题${question}, ].join(\n); } }这个骨架把核心流程都体现出来了。实际项目里embedding 调用要加批处理和缓存检索要加混合策略和重排序但骨架不变。7.3 跑通之后先测什么管道跑通不代表能用。我建议按这个顺序验证第一步测检索命中率。准备一批问题人工标注每个问题的正确答案在哪个片段然后看检索 TopK 里有没有命中。命中率低于 70% 就要回头调切分和向量模型。第二步测回答准确率。检索命中了但模型回答对不对这一步能暴露提示词和上下文组装的问题。第三步测边界情况。问一些资料里没有的问题看模型会不会编造。如果它开始胡说说明提示词的约束不够。这三步测下来基本能定位管道里最薄弱的环节。8. 那些文档里不会写的踩坑经验8.1 切分粒度调优的实战方法切分粒度是 RAG 里最需要反复调的参数。我的方法是固定其他变量只调切分用同一批测试问题对比不同粒度的命中率。具体操作准备 20 到 30 个覆盖不同文档区域的问题分别用 300、500、800 字三种粒度跑一遍记录命中率。通常你会发现某个粒度明显优于其他。然后再在这个粒度附近微调重叠比例。这个过程听起来笨但比拍脑袋定参数靠谱得多。我见过太多项目切分参数是随手写的上线后检索效果差还找不到原因。8.2 向量模型的“领域漂移”问题通用 embedding 模型在特定领域可能表现不佳。比如医疗、法律、金融这些专业领域术语密集通用模型可能分不清“心肌梗死”和“心绞痛”的语义差异。解决办法有两种一是换用领域微调过的 embedding 模型二是在检索时结合关键词检索兜底。我一般先用混合检索缓解如果还不够再考虑换模型。因为换模型意味着所有向量要重新生成成本不低。8.3 检索结果为空时的兜底策略用户问了一个资料里完全没有的问题检索返回空或者低分结果这时候怎么办直接让模型基于空上下文回答它大概率会编造。我的做法是设置一个相似度阈值低于阈值就判定为“无相关资料”然后返回一个标准回复比如“抱歉我目前没有找到相关信息”。这比让模型胡说八道强得多。阈值定多少要看你的向量模型和相似度度量方式建议用一批已知“无答案”的问题测出来。8.4 增量更新与索引重建文档会更新索引也要跟着更新。全量重建简单但慢增量更新快但复杂。我的建议是小规模数据直接全量重建简单可靠反正几分钟就跑完了。数据量大到全量重建影响服务时再考虑增量方案。增量更新的难点在于处理文档删除和修改需要维护文档 ID 到片段 ID 的映射复杂度不低。提示无论哪种方案都要保留原始文档和切分结果的对应关系否则出问题时你连哪个片段来自哪篇文档都查不到。9. 从基础 RAG 到 Agentic RAG 的演进方向基础 RAG 跑通之后你会发现它还是有点“死板”每次都是固定的检索一次、生成一次。而真实的 Agent 场景往往需要多轮检索、动态决策。这就是Agentic RAG的方向让 Agent 自己决定什么时候检索、检索什么、检索几次。比如 Agent 可以先检索一次发现信息不够再换个查询词检索第二次或者判断某个问题不需要检索直接回答。实现 Agentic RAG 的关键是把检索能力封装成 Agent 可以调用的工具然后让 Agent 通过推理决定调用时机。这比固定管道灵活得多但也对 Agent 的规划能力提出了更高要求。另一个方向是GraphRAG把知识组织成图结构检索时沿着图关系扩展能处理需要多跳推理的问题。比如“A 公司的 CEO 毕业于哪所大学”这种问题需要先找到 A 公司的 CEO再查他的教育背景单次向量检索很难搞定。这些进阶方向都建立在基础 RAG 之上。把这篇讲的管道每一段都理解透、调优好再去玩 Agentic RAG 和 GraphRAG会顺畅很多。我个人在实际项目里的体会是基础管道的质量决定了上层玩法的天花板切分和检索没做好再花哨的 Agent 架构也救不回来。