1. 为什么知识获取管道是 AI Agent 的分水岭做 AI Agent 开发的人迟早会撞上一堵墙模型本身很聪明但你问它公司内部某个产品的退货政策它要么胡编要么说“我不知道”。这不是模型不行而是它的知识边界停在了训练数据截止的那一天。知识获取管道要解决的就是这个问题——让 Agent 在运行时能够从外部知识源拉取信息再基于这些信息生成回答。这条管道的核心实现方式就是RAG检索增强生成。名字听着唬人拆开看很朴素检索Retrieval负责从知识库里找到相关内容增强Augmented是把找到的内容塞进提示词生成Generation是让大模型基于这些内容组织回答。三步走没有魔法。我见过不少团队在 Agent 项目上卡住不是卡在工具调用也不是卡在多轮对话而是卡在知识获取这一环。因为工具调用有明确的 API 文档多轮对话有成熟的框架支持但知识获取涉及文档解析、切分策略、向量化、检索排序、上下文组装等一连串工程决策每一步都有坑。这篇文章面向的是正在用TypeScript搭建 AI Agent、准备接入 RAG 能力的开发者不管你用的是 LangChain.js、LlamaIndex.TS 还是自己手写管道下面的内容都能直接参考。我会从整体设计思路讲起然后拆解每个核心环节的实现细节再给出一套可运行的 TypeScript 实操方案最后把我在实际项目中踩过的坑整理成排查清单。读完你应该能独立搭起一条可用的知识获取管道并且知道每个参数为什么这么设。2. RAG 管道的整体设计与技术选型2.1 核心架构从文档到答案的完整链路一条完整的 RAG 管道可以拆成两个阶段离线索引阶段和在线查询阶段。离线阶段负责把原始文档变成可检索的向量索引在线阶段负责接收用户问题、检索相关内容、组装提示词、调用大模型生成回答。离线索引阶段的流程是文档加载 → 文本切分 → 向量化 → 存入向量数据库。在线查询阶段的流程是查询向量化 → 相似度检索 → 结果重排序 → 上下文组装 → 大模型生成。这两个阶段是解耦的。离线索引可以定时跑、增量跑在线查询要求低延迟。理解这个解耦关系很重要因为它决定了你的系统架构索引服务可以是一个独立的批处理任务查询服务是一个常驻的 API 服务两者通过向量数据库连接。为什么要把重排序单独拎出来因为向量检索的召回率虽然不错但精度往往不够。你检索 Top 10可能只有前 3 条真正相关。重排序模型Reranker会对这 10 条做更精细的相关性打分把真正有用的排到前面。这一步对最终回答质量的影响比你换一个更大的 Embedding 模型还要明显。2.2 技术选型为什么是 TypeScript 向量数据库选 TypeScript 做 RAG 管道最直接的理由是生态统一。如果你的 Agent 本身就用 TypeScript 写那知识获取管道用同一套语言类型定义可以共享部署可以合并调试不用来回切上下文。LangChain.js 和 LlamaIndex.TS 这两个框架已经把文档加载、切分、向量化、检索的抽象做得很完整了没必要自己从零造轮子。向量数据库的选择取决于你的规模。个人项目或小团队Chroma或LanceDB足够用它们支持本地文件存储不需要额外部署服务。中等规模可以考虑Qdrant或Weaviate支持分布式和更丰富的过滤条件。如果已经在用 PostgreSQLpgvector是最省事的选择不用引入新的基础设施。Embedding 模型方面OpenAI 的 text-embedding-3-small 性价比很高1536 维的向量每百万 token 成本很低。如果对中文支持要求高可以考虑 BGE 系列或 M3E 系列这些模型可以本地部署不依赖外部 API。选 Embedding 模型时要注意索引和查询必须用同一个模型换了模型就得重新索引全部文档这个成本要提前算进去。2.3 切分策略决定检索质量的关键决策文本切分是 RAG 管道里最容易被低估的环节。很多人随便按固定长度切结果检索出来的片段要么缺上下文要么包含大量无关内容。切分策略直接决定了检索质量的上限。常见的切分策略有三种。固定长度切分最简单按 token 数或字符数切设置一定的重叠区域。优点是实现简单缺点是可能把一句话或一个段落从中间切断。递归字符切分会按优先级尝试不同的分隔符段落、换行、句号、逗号尽量在语义边界处切分。这是 LangChain 的默认策略适合大多数场景。语义切分用 Embedding 模型判断相邻句子的语义相似度在语义变化处切分效果最好但计算成本最高。我的经验是递归字符切分 合理的重叠区域能覆盖 80% 的场景。chunk size 设在 500 到 1000 个 token 之间overlap 设在 chunk size 的 10% 到 20%。对于技术文档按标题层级切分效果更好对于对话记录按轮次切分更自然。没有万能参数需要根据你的文档特点做实验。3. 核心环节实现细节与实操要点3.1 文档加载与预处理脏数据是最大的敌人文档加载看起来简单实际上是最耗时的环节。你的知识源可能是 PDF、Word、Markdown、HTML、数据库记录每种格式的解析质量都不一样。PDF 尤其麻烦扫描版需要 OCR表格和图片需要特殊处理多栏排版可能被解析成乱序文本。预处理阶段要做的事情包括去除页眉页脚、合并断行、清理多余空白、统一标点符号、提取标题层级。这些操作看起来琐碎但直接影响后续切分的质量。我一般会写一个预处理管道把原始文档转成干净的 Markdown 格式保留标题层级和列表结构这样切分时可以利用这些结构信息。注意不要跳过预处理直接切分。我见过一个项目PDF 解析出来的文本每行都有页码和页眉切分后的 chunk 里全是噪声检索出来的内容根本没法用。花在预处理上的时间会在检索质量上加倍回报。对于结构化数据比如数据库表、Excel不要直接转成文本。更好的做法是把每一行转成一条自然语言描述比如“产品 X 的价格是 Y 元库存 Z 件”这样 Embedding 模型能更好地理解语义。3.2 向量化与索引构建批量处理和增量更新向量化就是把文本 chunk 转成高维向量。这个过程需要注意几个点。批量处理不要一条一条调 API把 chunk 攒成批次比如每批 100 条一起发送能显著降低网络开销和成本。错误重试API 调用可能失败要有重试机制并且记录失败的 chunk 以便后续补处理。并发控制并发太高会触发限流太低则索引速度慢一般设 5 到 10 个并发比较稳妥。增量更新是实际项目中必须考虑的问题。知识库不是一成不变的新文档要加进来旧文档要更新或删除。简单的做法是全量重建索引但文档多了之后耗时太长。更好的方案是给每个 chunk 记录来源文档 ID 和版本号更新时只重新处理变化的文档删除时按文档 ID 删除对应的所有向量。索引构建完成后建议做一次检索质量抽检准备一组典型问题看检索出来的 Top 5 结果是否相关。如果召回率明显偏低可能是切分粒度不对或 Embedding 模型不适合你的领域。3.3 检索策略从相似度搜索到混合检索基础的向量检索是计算查询向量和所有文档向量的余弦相似度返回 Top K 个最相似的。但纯向量检索有两个问题一是对关键词精确匹配不敏感比如产品型号“XR-2000”可能检索不到二是对短查询效果不稳定。混合检索能解决这个问题同时做向量检索和关键词检索BM25然后融合两路结果。融合算法常用 RRFReciprocal Rank Fusion它不依赖分数归一化直接按排名融合实现简单且效果稳定。元数据过滤是另一个实用技巧。如果你的 chunk 带有来源、日期、分类等元数据检索时可以加过滤条件比如只检索最近半年的文档或只检索某个产品线的文档。这能大幅缩小检索范围提升精度。重排序是检索流程的最后一步。用 Cross-Encoder 模型对检索结果重新打分把最相关的排到前面。重排序模型比 Embedding 模型慢但只对 Top 10 到 Top 20 的结果做重排延迟可以接受。实测下来加了重排序之后最终回答的准确率能提升 15% 到 30%。3.4 上下文组装把检索结果变成模型能用的提示词检索到相关 chunk 之后不能直接全部塞给模型。上下文窗口有限塞太多会挤占生成空间而且无关内容会干扰模型判断。组装上下文时要考虑数量一般 3 到 5 个 chunk 足够、顺序最相关的放最前面或最后面模型对首尾内容更敏感、格式给每个 chunk 标注来源方便模型引用和用户溯源。提示词模板也很关键。一个有效的模板会明确告诉模型只基于提供的上下文回答如果上下文没有相关信息就直说不知道不要编造。这能显著降低幻觉率。另外可以在提示词里要求模型引用来源比如“根据文档 A 的第 3 节”这样用户能验证回答的可靠性。4. TypeScript 实操从零搭建一条可用的 RAG 管道4.1 环境准备与依赖安装先建项目初始化 TypeScript 环境。我习惯用 pnpm速度快且节省磁盘空间。mkdir rag-pipeline cd rag-pipeline pnpm init pnpm add langchain langchain/openai langchain/community chromadb pnpm add -D typescript tsx types/node npx tsc --inittsconfig.json 需要调整几个选项。target 设为 ES2022module 设为 NodeNextmoduleResolution 也设为 NodeNextstrict 打开。这样能获得完整的类型检查和现代模块支持。{ compilerOptions: { target: ES2022, module: NodeNext, moduleResolution: NodeNext, strict: true, esModuleInterop: true, skipLibCheck: true, outDir: ./dist }, include: [src/**/*] }注意TypeScript 7.0 之后 moduleResolution 的 node10 选项会被移除新项目直接用 NodeNext 或 Bundler不要再用旧的 node 选项。4.2 文档加载与切分实现假设我们的知识源是一批 Markdown 文件。用 LangChain 的 DirectoryLoader 加载然后用 RecursiveCharacterTextSplitter 切分。import { DirectoryLoader } from langchain/document_loaders/fs/directory; import { TextLoader } from langchain/document_loaders/fs/text; import { RecursiveCharacterTextSplitter } from langchain/text_splitter; async function loadAndSplit() { const loader new DirectoryLoader(./docs, { .md: (path) new TextLoader(path), }); const docs await loader.load(); const splitter new RecursiveCharacterTextSplitter({ chunkSize: 800, chunkOverlap: 120, separators: [\n## , \n### , \n\n, \n, 。, ], }); const chunks await splitter.splitDocuments(docs); console.log(加载 ${docs.length} 个文档切分为 ${chunks.length} 个片段); return chunks; }这里的 separators 顺序很重要。优先按二级标题切再按三级标题再按段落最后才按句子和空格。这样能尽量保持语义完整性。chunkSize 设 800 是因为中文一个字符大约对应 1 到 2 个 token800 字符大概 1000 到 1600 token在 Embedding 模型的最佳处理范围内。4.3 向量化与存储用 OpenAI 的 Embedding 模型存到 Chroma。Chroma 支持本地持久化适合开发和小规模部署。import { OpenAIEmbeddings } from langchain/openai; import { Chroma } from langchain/community/vectorstores/chroma; async function buildIndex(chunks: any[]) { const embeddings new OpenAIEmbeddings({ modelName: text-embedding-3-small, batchSize: 100, }); const vectorStore await Chroma.fromDocuments(chunks, embeddings, { collectionName: knowledge-base, url: http://localhost:8000, }); console.log(索引构建完成); return vectorStore; }batchSize 设 100 是经验值。太小则请求次数多太大则单次请求可能超时。如果文档量很大建议分批处理每批完成后记录进度失败时可以从断点继续。4.4 检索与生成检索用相似度搜索加元数据过滤生成用 ChatOpenAI。import { ChatOpenAI } from langchain/openai; async function query(vectorStore: any, question: string) { const retriever vectorStore.asRetriever({ k: 5, searchType: similarity, }); const relevantDocs await retriever.invoke(question); const context relevantDocs .map((doc: any, i: number) [片段 ${i 1}]\n${doc.pageContent}) .join(\n\n); const prompt 你是一个知识助手。请仅基于以下上下文回答问题。 如果上下文没有相关信息请直接说根据现有资料无法回答。 上下文 ${context} 问题${question} 回答; const model new ChatOpenAI({ modelName: gpt-4o-mini, temperature: 0, }); const response await model.invoke(prompt); return { answer: response.content, sources: relevantDocs.map((d: any) d.metadata.source), }; }temperature 设 0 是为了让回答更稳定、更忠实于上下文。如果希望回答更自然可以设到 0.3 左右但不要太高否则容易偏离检索内容。4.5 完整流程串联把上面的步骤串起来形成一个可运行的脚本。async function main() { const chunks await loadAndSplit(); const vectorStore await buildIndex(chunks); const questions [ 产品的退货政策是什么, 如何联系技术支持, ]; for (const q of questions) { const result await query(vectorStore, q); console.log(问题${q}); console.log(回答${result.answer}); console.log(来源${result.sources.join(, )}); console.log(---); } } main().catch(console.error);跑通这个流程之后你就有了一个最小可用的 RAG 管道。接下来可以逐步优化加混合检索、加重排序、加缓存、加流式输出。5. 常见问题与排查技巧实录5.1 检索结果不相关怎么办这是最常见的问题。排查顺序是先看切分粒度是否合适再看 Embedding 模型是否适合你的领域最后看检索参数是否需要调整。如果 chunk 太大检索出来的内容包含太多无关信息如果 chunk 太小可能丢失关键上下文。一个实用的判断方法是随机抽 10 个 chunk看它们是否各自表达了一个完整的语义单元。如果不是调整 chunkSize 和 separators。Embedding 模型方面通用模型在专业领域医疗、法律、金融的表现可能不够好。可以考虑用领域数据微调 Embedding 模型或者换用在该领域表现更好的开源模型。5.2 模型回答包含幻觉怎么办幻觉通常来自两个原因检索结果不相关或者提示词没有约束好。先确认检索结果是否相关如果相关但模型还是编造就加强提示词的约束。明确要求模型“只基于上下文回答”、“不确定时说不确定”、“引用来源”。另一个技巧是在上下文里给每个片段编号要求模型在回答中标注引用了哪个片段。这样即使有幻觉也能通过来源追溯发现。5.3 索引更新后检索结果不一致这通常是因为增量更新时没有正确处理旧向量。如果文档更新了要先删除该文档对应的所有旧向量再插入新向量。如果只插入不删除检索时会同时召回新旧内容导致结果混乱。建议给每个 chunk 的 metadata 里记录docId和version更新时按docId删除旧版本再插入新版本。Chroma 和 Qdrant 都支持按 metadata 过滤删除。5.4 常见问题速查表问题现象可能原因排查方向检索结果完全不相关Embedding 模型不匹配检查索引和查询是否用同一模型检索结果缺少关键信息chunk 太小或切分位置不当增大 chunkSize调整 separators回答包含幻觉提示词约束不足加强提示词要求引用来源索引更新后结果混乱旧向量未删除按 docId 删除旧版本再插入检索延迟高向量库规模大或网络慢加缓存用本地向量库减少 Top K中文检索效果差Embedding 模型中文能力弱换用 BGE 或 M3E 等中文模型5.5 实操心得几个让我少走弯路的习惯第一个习惯是先做小规模实验再全量索引。拿 20 个文档跑通全流程验证检索质量再扩展到全量。全量索引一次可能几十分钟如果策略有问题返工成本很高。第二个习惯是记录每次检索的查询和结果。出问题时可以回溯看是查询本身的问题还是检索策略的问题。这些日志也是后续优化的重要依据。第三个习惯是给检索结果打分。可以人工标注一批查询-文档对的相关性算召回率和精确率。没有量化指标优化就是盲人摸象。第四个习惯是关注 token 成本。Embedding 和生成都按 token 计费索引几万文档的成本可能不低。批量处理、缓存查询向量、控制上下文长度都能有效降低成本。6. 从基础 RAG 到 Agentic RAG 的演进方向基础 RAG 跑通之后你会遇到更复杂的场景多跳问题需要多次检索、不同知识源需要路由、检索结果需要验证。这些场景催生了Agentic RAG——让 Agent 自主决定何时检索、检索什么、是否需要二次检索。实现 Agentic RAG 的思路是把检索封装成工具让 Agent 通过工具调用来获取知识。Agent 可以先分析问题判断需要哪些信息然后发起检索根据检索结果决定是直接回答还是继续检索。这比固定流程的 RAG 灵活得多但也更复杂需要处理好工具调用的错误和循环控制。另一个方向是GraphRAG用知识图谱组织文档内容检索时沿着图谱关系扩展能回答需要跨文档推理的问题。GraphRAG 的索引成本比向量索引高不少适合知识结构复杂、关系密集的场景。不管往哪个方向演进基础 RAG 管道都是地基。把文档加载、切分、向量化、检索、生成这五个环节做扎实后续加什么高级特性都有稳固的支撑。我在实际项目中的体会是与其追新概念不如先把基础管道的每个参数调到位把检索质量提上去。基础扎实了Agent 的知识获取能力自然就稳了。