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

1. 为什么知识获取管道是 AI Agent 的分水岭做 AI Agent 开发的人迟早会撞上一堵墙模型本身很聪明但它不知道你公司内部的 API 文档、不知道你上周刚改的产品规格、更不知道你私有的那套业务术语。你问它一个稍微偏门的问题它要么一本正经地胡说八道要么礼貌地告诉你“我无法回答”。这不是模型不行而是它的知识边界被训练数据锁死了。知识获取管道要解决的就是这件事。它的核心任务只有一句话在模型生成回答之前把“对的那几段资料”找出来塞进模型的上下文里。这套机制有个更正式的名字——检索增强生成RAGRetrieval-Augmented Generation。你可以把它理解成给模型配了一个随身图书馆管理员模型负责组织语言和推理管理员负责在你说出问题的瞬间从书架上抽出最相关的几页递过去。我见过太多团队在 Agent 项目上栽跟头不是栽在模型选型上而是栽在知识管道上。模型换了一茬又一茬从 GPT 到 Claude 再到各种开源模型但检索层始终是那套“把文档切碎、扔进向量库、余弦相似度搜一下”的粗糙做法。结果就是检索命中率hit rate上不去Agent 的回答质量就永远在及格线附近晃悠。RAG 做得好不好直接决定了你的 Agent 是“能用”还是“好用”。这篇文章面向的是正在用TypeScript从 0 到 1 搭建 AI Agent 的开发者尤其是那些已经跑通了对话链路、准备接入私有知识库的人。我会把 RAG 的基础管道拆开从文档摄入、切分策略、向量化、检索召回到最终拼装进 Prompt 的完整流程一步步讲清楚每个环节的取舍逻辑和实操细节。代码示例以 TypeScript 为主因为这是目前 Agent 开发中最主流、生态最成熟的工程语言之一。2. RAG 基础管道的整体设计与选型思路2.1 一条完整的知识获取管道长什么样很多人对 RAG 的理解停留在“向量搜索”这一步实际上一条完整的知识获取管道包含四个阶段每个阶段都有独立的工程决策摄入阶段Ingestion把各种格式的原始资料Markdown、PDF、网页、数据库记录读进来清洗掉噪音转成纯文本。这个阶段最容易被低估但实际项目中 60% 的脏活累活都在这里。切分阶段Chunking把长文档切成适合检索和塞进上下文的小块。切得好检索精准切得烂检索出来的东西驴唇不对马嘴。索引阶段Indexing把每个文本块转成向量存进向量数据库同时保留原始文本和元数据。向量化的质量取决于 Embedding 模型的选择。检索阶段Retrieval用户提问时把问题也转成向量在库里找最相似的 Top-K 个块再经过重排序Rerank和过滤最终拼装成上下文。这四个阶段串起来就是一条知识获取管道。管道这个词用得很准确——任何一段堵了整条链路的水流都会变小。2.2 为什么选 TypeScript 而不是 PythonPython 在 AI 领域确实是第一语言但 Agent 开发有个特殊性它最终要跑在应用层要和前端、后端服务、API 网关打交道。TypeScript 在这方面的工程优势非常明显。第一类型系统。RAG 管道里数据流转很复杂原始文档、切分后的块、向量、检索结果、重排序后的结果每一层的数据结构都不一样。用 TypeScript 把这些类型定义清楚编译期就能挡掉大量低级错误。我试过用 Python 写同样的管道运行到一半才发现某个字段名拼错了这种体验实在说不上好。第二生态统一。如果你的 Agent 前端是 React后端是 Node.js那整条链路用 TypeScript 可以共享类型定义和工具函数。一个Chunk接口从前端传到后端再传到向量库全程类型安全不需要在脑子里维护两套数据模型。第三异步处理天然契合。RAG 管道里大量操作是 I/O 密集型的读文件、调 Embedding API、查向量库。TypeScript 的async/await和Promise.all处理并发非常顺手批量向量化时能轻松把吞吐量拉上去。当然如果你团队里已经有成熟的 Python RAG 服务也没必要为了统一而重写。但如果是新项目我建议从 TypeScript 起步后期维护成本会低很多。2.3 向量库选型的三个关键维度向量数据库的选择直接决定了检索性能和运维复杂度。我按实际项目经验把常见选项列出来对比向量库部署方式适合场景注意事项内存向量库如内存索引进程内原型验证、小规模数据重启即丢不适合生产本地文件型嵌入式单机应用、桌面端 Agent并发写入能力弱服务型向量库独立部署中大型生产环境需要额外运维成本云托管向量服务SaaS快速上线、弹性扩容数据出域需评估选型的核心判断标准是三个数据规模、查询并发量、运维能力。数据量在几万条以下本地嵌入式方案完全够用上了百万级就必须考虑独立部署或云服务。另外要注意向量库的“相似度搜索”和传统数据库的“精确查询”是两回事前者是近似最近邻ANN搜索召回率和速度需要权衡。3. 文档摄入与切分管道里最容易被做烂的环节3.1 摄入阶段要处理的真实数据长什么样理想情况下你的知识库都是干净的 Markdown 文件。现实情况是PDF 扫描件、Word 文档、Confluence 页面、飞书文档、数据库里的工单记录什么都有。摄入阶段的任务就是把这些异构数据统一成纯文本。我处理过的一个典型场景是产品文档库里面有三种来源Markdown 写的 API 文档、PDF 格式的白皮书、以及从内部 Wiki 导出的 HTML。处理策略完全不同Markdown 文件最省事直接读进来但要注意去掉 YAML front matter 和代码块里的注释噪音。PDF 最麻烦需要先做文本提取扫描件还得走 OCR提取出来的文本经常有断行错乱、页眉页脚混入的问题。HTML 相对好处理用解析库提取正文去掉导航栏和广告区域即可。这里有个经验摄入阶段一定要保留元数据。每个文本块至少要记录来源文件、原始位置页码或段落号、更新时间。后面检索出问题时你能快速定位是哪个文件、哪一段出了问题。没有元数据的 RAG 系统调试起来就是盲人摸象。3.2 切分策略固定长度 vs 语义切分切分是 RAG 里最考验经验的一步。切得太碎每个块信息量不足检索出来答非所问切得太长一个块里混了好几个主题向量表示被稀释检索精度下降。最粗暴的做法是固定长度切分每 500 个字符切一刀重叠 50 个字符。这种做法实现简单但问题很明显——它会在句子中间切断把一个完整的语义单元劈成两半。我早期项目就吃过这个亏用户问“如何配置超时时间”检索出来的块前半段在讲超时配置后半段突然跳到日志格式因为切分点正好落在两个章节之间。更合理的做法是按语义边界切分。Markdown 按标题层级切每个二级标题下的内容作为一个块代码文档按函数或类切普通文本按段落切。这样每个块都是一个完整的语义单元向量表示更聚焦。但语义切分也有代价块的长度不均匀有的块只有两行有的块有上千字。这时候需要加一层长度约束超过阈值的长块再按句子边界二次切分过短的块和相邻块合并。我通常把目标块长度设在 300 到 800 个 token 之间这个范围在检索精度和上下文利用率之间比较平衡。interface Chunk { id: string; content: string; metadata: { source: string; section: string; position: number; updatedAt: string; }; } function splitBySemanticBoundary( text: string, maxTokens: number 800, minTokens: number 100 ): Chunk[] { // 先按标题和段落切分再对超长块做二次切分 const sections text.split(/\n(?#{1,3}\s)/); const chunks: Chunk[] []; for (const section of sections) { const tokens estimateTokens(section); if (tokens maxTokens) { chunks.push(createChunk(section)); } else { // 超长块按句子边界二次切分 const sentences section.split(/(?[。.!?])\s*/); let buffer ; for (const sentence of sentences) { if (estimateTokens(buffer sentence) maxTokens) { chunks.push(createChunk(buffer)); buffer sentence; } else { buffer sentence; } } if (buffer) chunks.push(createChunk(buffer)); } } // 合并过短的相邻块 return mergeShortChunks(chunks, minTokens); }这段代码的核心逻辑是“先粗后细”先按语义边界切再对不符合长度要求的块做二次处理。estimateTokens可以用简单的字符数除以 1.5 来近似也可以用 tokenizer 精确计算。生产环境建议用精确计算因为不同模型的 token 切分方式不一样近似值容易导致实际超出上下文限制。3.3 切分时容易踩的三个坑第一个坑忽略文档结构。很多团队的切分函数只接收纯文本把标题、列表、表格都当成普通段落处理。结果就是检索出来的块丢失了层级信息模型看到一段话却不知道它属于哪个章节。解决办法是在切分时保留标题路径比如把“## 配置说明 ### 超时设置”作为元数据附加到块上。第二个坑重叠区域设置不当。重叠是为了防止关键信息正好落在切分点上被切断但重叠太多会导致检索结果重复浪费上下文窗口。我的经验是重叠 10% 到 15% 比较合适也就是 500 字的块重叠 50 到 75 字。第三个坑不处理特殊内容。代码块、表格、公式这些内容如果被当普通文本切分语义会完全丢失。代码块应该整体保留表格应该转成结构化文本公式应该保留 LaTeX 原文。这些细节看起来琐碎但直接影响检索质量。4. 向量化与索引把文本变成可检索的数学对象4.1 Embedding 模型怎么选向量化的本质是把文本映射到一个高维空间语义相近的文本在空间里的距离也相近。这个映射函数就是 Embedding 模型。选模型时主要看三个指标语义区分度、维度、推理成本。语义区分度决定了模型能不能把“配置超时”和“设置超时时间”识别为相似同时把“配置超时”和“配置日志”区分开。这个指标没有统一标准最好的办法是拿你自己的业务数据做小规模测试准备 20 组问题-答案对看模型检索的命中率。维度影响存储成本和检索速度。高维向量如 1536 维表达能力更强但存储和计算开销也更大。低维向量如 384 维更轻量适合大规模数据。我的建议是数据量在十万条以下用高维模型上了百万条考虑低维模型或者做维度压缩。推理成本包括 API 调用费用和延迟。如果知识库更新频繁每次更新都要重新向量化成本会累积。这时候可以考虑本地部署 Embedding 模型虽然初始投入高但长期看更划算。4.2 批量向量化的并发控制向量化是 I/O 密集型操作调 API 时如果不做并发控制要么慢得让人抓狂要么触发限流被封。我的做法是用一个简单的并发池async function batchEmbed( chunks: Chunk[], concurrency: number 5 ): PromiseEmbeddedChunk[] { const results: EmbeddedChunk[] []; const queue [...chunks]; async function worker() { while (queue.length 0) { const chunk queue.shift()!; const vector await embedText(chunk.content); results.push({ ...chunk, vector }); } } const workers Array.from( { length: concurrency }, () worker() ); await Promise.all(workers); return results; }并发数设多少合适这取决于 Embedding 服务的限流策略。一般来说5 到 10 个并发是比较安全的起点。如果服务端支持批量接口一次传多个文本优先用批量接口比并发单条调用效率高得多。4.3 索引结构的选择与权衡向量索引的核心矛盾是检索速度和召回精度。精确检索暴力计算所有向量的相似度召回率最高但数据量大时慢得无法接受。近似检索ANN速度快但会漏掉一部分真正相似的向量。常见的 ANN 索引有基于树的、基于图的、基于量化的几大类。基于图的索引如 HNSW在召回率和速度之间平衡得比较好是目前的主流选择。它的原理是构建一个多层图结构检索时从顶层快速定位到目标区域再逐层细化。你可以把它想象成查字典先按拼音首字母找到大致范围再在这个范围里逐页翻找。索引参数需要根据数据规模调整。以 HNSW 为例M参数控制每个节点的连接数值越大召回率越高但内存占用也越大efConstruction控制构建时的搜索范围值越大索引质量越好但构建越慢。我的经验值是数据量在十万级M16、efConstruction200是个不错的起点。注意索引构建完成后如果数据有更新需要增量插入而不是重建整个索引。重建索引在大数据量下可能耗时数小时生产环境不可接受。5. 检索与重排序决定 Agent 回答质量的关键一步5.1 相似度搜索的基本流程检索阶段做的事情很直接把用户问题转成向量在索引里找最相似的 Top-K 个块。但“相似”的定义有讲究。常用的相似度度量有余弦相似度、欧氏距离、点积。余弦相似度只看向量方向不受长度影响适合文本检索欧氏距离看绝对距离对向量长度敏感点积则两者都考虑。大多数 Embedding 模型在训练时用的是余弦相似度所以检索时也优先用余弦相似度保持一致。如果你不确定模型用的是什么度量查一下模型文档或者用一组已知相似的文本对做测试看哪种度量给出的分数更合理。Top-K 的 K 值怎么定太小了可能漏掉关键信息太大了会引入噪音。我的经验是先取 K20 做粗排再用重排序模型精选出 3 到 5 个最相关的块。这样既保证了召回率又控制了上下文长度。5.2 重排序为什么必要向量检索有个天然缺陷它把文本压缩成一个固定长度的向量这个过程必然丢失信息。两个语义不同但用词相似的文本向量可能很接近两个语义相同但表述差异大的文本向量可能离得远。重排序模型Rerank就是为了修正这个问题。重排序模型通常是交叉编码器Cross-Encoder它把问题和候选块一起输入模型直接输出相关性分数。因为它是逐对计算的精度比向量检索高得多但速度慢所以只适合对少量候选做精排。async function retrieveWithRerank( query: string, topK: number 20, finalK: number 5 ): PromiseRetrievedChunk[] { // 第一阶段向量粗排 const queryVector await embedText(query); const candidates await vectorStore.search(queryVector, topK); // 第二阶段重排序精排 const reranked await rerankModel.score( query, candidates.map(c c.content) ); // 按分数排序取前 finalK 个 return reranked .sort((a, b) b.score - a.score) .slice(0, finalK) .map(r candidates[r.index]); }这套“粗排 精排”的两阶段架构是目前 RAG 系统的主流做法。粗排负责从海量数据中快速缩小范围精排负责在候选集里挑出真正相关的。两阶段配合既保证了速度又保证了精度。5.3 检索命中率的评估与调优检索命中率hit rate是衡量 RAG 系统质量的核心指标。它的定义是在测试问题集中正确文档出现在检索结果 Top-K 中的比例。比如你有 100 个测试问题检索 Top-5 中有 85 个问题找到了正确文档命中率就是 85%。提升命中率的手段有几个方向。优化切分策略是最直接的把块切得更符合语义边界向量表示就更准确。换更好的 Embedding 模型效果也很明显但成本会上升。加入关键词检索做混合搜索能弥补纯向量检索对专有名词不敏感的缺陷。调整重排序模型的权重让精排结果更符合业务预期。我通常的做法是先建一个 50 到 100 个问题的测试集覆盖常见查询和边界情况然后每次调整管道参数后跑一遍测试集看命中率的变化。没有测试集的调优就是瞎调你根本不知道改动是变好了还是变坏了。6. 常见问题与排查技巧实录6.1 检索结果不相关怎么办这是最常见的问题。排查思路按优先级排列第一步检查切分质量。把检索出来的块打印出来看内容是否完整、是否包含关键信息。如果块被切得支离破碎问题就出在切分阶段。第二步检查 Embedding 模型。用几个已知相似的文本对测试看模型给出的相似度分数是否合理。如果模型对明显相似的文本给出低分说明模型不适合你的领域数据。第三步检查查询改写。用户的问题往往很短比如“超时怎么配”而文档里写的是“配置请求超时时间”。这种表述差异会导致向量距离变远。解决办法是在检索前用 LLM 对查询做改写扩展生成几个语义相同但表述不同的查询分别检索后合并结果。第四步检查元数据过滤。如果你的知识库有多个来源检索时可能需要按来源过滤。比如用户问的是 API 文档的问题就不应该检索到产品白皮书的内容。6.2 上下文窗口不够用怎么办检索出来的块太多拼进 Prompt 后超出模型上下文限制这是很实际的问题。解决办法有三个减少检索块数。通过重排序精选出最相关的 3 到 5 个块而不是把 Top-20 全塞进去。压缩块内容。用 LLM 对检索结果做摘要只保留和问题相关的部分。这个操作有信息损失风险但对长文档场景很有效。分轮检索。先检索一批让模型判断信息是否足够不够再检索第二批。这种 Agentic RAG 的做法更智能但实现复杂度也更高。6.3 知识库更新后检索不到新内容这是索引更新机制的问题。如果你的管道是“全量重建索引”那更新后需要等重建完成才能检索到新内容。更好的做法是增量更新新文档单独向量化后插入索引旧文档如果修改了就删除旧向量再插入新向量。增量更新要注意向量 ID 的管理。每个块需要一个稳定的唯一 ID通常用“来源文件路径 块序号”的哈希值。这样更新时能准确找到要替换的旧向量。问题现象可能原因排查方法解决方向检索结果完全不相关切分粒度过粗或过细打印检索块内容调整切分策略相似问题检索结果差异大Embedding 模型区分度不足测试相似文本对分数更换或微调模型专有名词检索不到纯向量检索对低频词不敏感检查查询词是否在库中加入关键词混合检索新文档检索不到索引未更新检查索引更新时间实现增量更新机制检索速度慢索引参数不合理监控检索延迟调整 ANN 参数6.4 几个我踩过的坑坑一用生产数据做测试。早期我直接拿生产知识库调参结果每次改动都影响线上服务。后来学乖了建了一个独立的测试知识库用脱敏数据做调优确认效果后再同步到生产。坑二忽略 Embedding 模型的版本变化。Embedding 服务商升级模型版本后新旧向量不在同一个空间里混用会导致检索结果混乱。解决办法是记录每个向量用的模型版本升级时全量重新向量化。坑三元数据字段设计太随意。一开始我觉得元数据不重要随便存了几个字段。后来要做按来源过滤、按时间排序时发现字段不够用只能重建索引。建议一开始就把元数据设计好来源、章节、位置、时间、类型、标签这些字段后面都会用到。坑四不做检索日志。没有日志出了问题根本不知道用户搜了什么、检索到了什么、模型最终用了哪些块。后来我加了一个简单的日志表记录每次检索的查询、Top-K 结果和最终使用的块排查问题时效率提升了好几倍。7. 从基础 RAG 到 Agentic RAG 的演进方向基础 RAG 管道跑通之后你会发现它有几个天然局限检索是一次性的不会根据中间结果调整策略查询是原始的用户问题不会做改写和扩展检索结果直接拼进 Prompt不会做验证和补充。Agentic RAG就是针对这些局限的演进。它把检索过程变成一个 Agent 可以自主决策的循环Agent 先分析问题决定是否需要检索、检索什么、检索几次拿到结果后判断信息是否足够不够就换个查询再检索最后综合多轮检索的结果生成回答。这个演进方向对知识获取管道提出了新要求检索接口要支持多轮调用查询改写要能动态生成检索结果要能被 Agent 评估和筛选。TypeScript 在这方面的优势是类型系统能清晰定义 Agent 和检索层之间的接口契约让多轮交互的逻辑不容易出错。不过我要提醒一句不要一上来就做 Agentic RAG。基础 RAG 的每个环节都没调好加再多 Agent 逻辑也是白搭。先把切分、向量化、检索、重排序这条基础管道跑顺把命中率提上去再考虑加 Agent 决策层。我见过太多项目在基础管道还很粗糙的时候就急着上 Agentic 架构结果复杂度上去了效果反而更差。基础 RAG 的调优是个细活没有捷径。我的建议是先建测试集再调切分然后调 Embedding最后调重排序。每一步都用测试集验证效果确认有提升再进入下一步。这样虽然慢但每一步的收益都是可衡量、可复现的。