TypeScript 实战：从零搭建 RAG 知识获取管道，打通 AI Agent 私有知识瓶颈

1. 为什么知识获取管道是 AI Agent 的分水岭做 AI Agent 开发的人迟早会撞上一堵墙模型本身很聪明但它不知道你公司内部的业务规则、不知道你上周刚更新的产品文档、更不知道你私有的那套运维手册里写了什么。你问它一个非常具体的问题它要么一本正经地胡说八道要么给你一个“根据我的训练数据”这种让人血压升高的回答。这个问题的本质不是模型不够强而是它的知识边界被锁死在了训练截止的那一刻。知识获取管道就是用来打破这堵墙的。而RAG检索增强生成是目前最主流、最务实、也最容易落地的一条路径。它的核心思路用一句话就能说清楚在模型回答问题之前先去你的知识库里把相关内容找出来塞进模型的上下文里让它“看着材料答题”。这就像开卷考试和闭卷考试的区别——闭卷考的是记忆力开卷考的是检索和整合能力。我们做 Agent 的时候要的不是一个记忆力超群的模型而是一个能随时查阅资料、基于事实回答问题的助手。这一篇是“走进 AI Agent”系列的第四篇前面我们聊了 Agent 的基本架构、工具调用、记忆机制现在轮到知识获取管道了。为什么说它是分水岭因为在此之前你的 Agent 只是一个“会聊天的程序”在此之后它才真正具备了“基于私有知识做决策”的能力。这个能力一旦打通你能做的事情就完全不一样了——企业内部知识问答、客服工单自动回复、代码库语义搜索、合同条款比对这些场景全部依赖 RAG 管道。我选择用TypeScript来写这一篇的示例代码原因很直接Agent 开发的前端交互层、Node.js 服务层、甚至很多 Serverless 部署场景TypeScript 都是第一选择。而且 TypeScript 的类型系统能在你拼接 Prompt、处理检索结果、调用模型 API 的时候帮你挡掉大量低级错误。如果你之前用 Python 做 RAG思路完全一样只是换了个语言表达。这篇文章适合谁看如果你已经了解 AI Agent 的基本概念知道什么是 LLM、什么是 Prompt但还没动手搭过一套完整的 RAG 管道那这篇就是写给你的。如果你已经用过一些 RAG 框架但总觉得效果不稳定、检索命中率上不去这篇里的调优经验和踩坑记录也能帮你省不少时间。我会从零开始把知识获取管道的每一个环节拆开讲清楚包括文档加载、文本切分、向量化、存储、检索、重排序、Prompt 组装最后给出一个可以直接跑的 TypeScript 实现。注意RAG 不是银弹。它解决的是“模型不知道”的问题不解决“模型不理解”的问题。如果你的问题需要复杂推理RAG 只能提供素材推理还得靠模型本身或者 Agent 的规划能力。2. RAG 管道的整体架构与核心环节拆解2.1 从原始文档到可检索知识库的完整链路很多人第一次接触 RAG 的时候脑子里只有一个模糊的概念“把文档扔进去然后问问题”。但真正动手的时候会发现从“文档”到“能回答问题”之间有一条相当长的链路每一个环节都有坑。我把这条链路拆成六个核心阶段每个阶段都有明确的输入和输出。第一阶段是文档加载。你的知识可能散落在 PDF、Word、Markdown、HTML、数据库、甚至飞书文档和 Notion 页面里。加载器的任务就是把这些异构数据统一成纯文本或者结构化文本。这一步看起来简单但 PDF 里的表格、扫描件里的图片、HTML 里的导航栏噪音都会直接影响后续的检索质量。第二阶段是文本切分。你不能把一整本 200 页的手册直接塞给模型上下文窗口放不下而且检索精度会急剧下降。切分的目的是把长文档拆成语义完整的短片段每个片段大概几百个 token既能独立表达一个完整意思又不会太长导致检索时引入噪音。第三阶段是向量化。把每个文本片段通过 Embedding 模型转换成一个高维向量这个向量在数学空间里的位置代表了这段文字的语义。语义相近的文本向量距离就近。这是 RAG 能实现“语义检索”而不是“关键词匹配”的关键。第四阶段是存储与索引。向量需要存在一个专门的地方通常是向量数据库。除了向量本身还要存储原始文本、元数据来源、页码、时间等并且建立索引来加速检索。索引结构的选择直接影响检索速度和召回率。第五阶段是检索与重排序。用户提问后先把问题向量化然后在向量数据库里找最相似的 Top-K 个片段。但向量相似度高不代表真的相关所以通常还需要一个重排序环节用更精细的模型对这 K 个结果重新打分排序。第六阶段是Prompt 组装与生成。把检索到的片段按照一定策略拼接到 Prompt 里连同用户问题一起发给 LLM让它基于这些材料生成回答。这一步的 Prompt 模板设计非常讲究直接决定了模型会不会“跑偏”。这六个阶段串起来就是一条完整的知识获取管道。下面我会逐个拆解每个环节的技术选型、参数计算和实操要点。2.2 为什么选择 TypeScript 而不是 Python这个问题我被问过很多次。Python 在 AI 领域的生态确实更成熟LangChain、LlamaIndex 这些框架都是 Python 优先。但 TypeScript 在 Agent 开发中有几个不可替代的优势。首先是类型安全。RAG 管道里涉及大量的数据结构转换文档对象、切分后的片段、向量数组、检索结果、Prompt 模板。用 TypeScript 把这些类型定义清楚编译器会在你写代码的时候就告诉你哪里对不上而不是等到运行时才发现“哦这个字段名写错了”。我自己的经验是用 TypeScript 写 RAG 管道调试时间至少减少三分之一。其次是全栈统一。如果你的 Agent 最终要以 Web 应用的形式交付前端用 React 或 Vue后端用 Node.js那整个技术栈统一用 TypeScript代码复用和类型共享会非常顺畅。你可以在前端直接复用后端定义的检索结果类型不用手动维护两套接口定义。第三是部署轻量。Node.js 的 Serverless 部署体验比 Python 好很多冷启动更快依赖打包更简单。对于中小规模的 RAG 应用用 TypeScript 写一个 Edge Function 就能跑起来不需要维护复杂的 Python 环境。当然如果你要做模型微调、大规模数据处理、或者用一些只有 Python 才有的 NLP 工具那 Python 仍然是更好的选择。但对于大多数 Agent 应用的知识获取管道来说TypeScript 完全够用而且开发体验更好。2.3 核心参数速查切分长度、重叠窗口与 Top-K 的取值逻辑在动手写代码之前有几个核心参数必须先想清楚。这些参数没有“标准答案”但有明确的取值逻辑和调整方向。参数典型取值影响调整方向切分长度chunk size256-1024 token太短语义不完整太长引入噪音技术文档 512对话记录 256法律合同 1024重叠窗口overlapchunk size 的 10%-20%防止边界信息丢失一般设 50-100 tokenTop-K3-10太少可能漏掉关键信息太多引入噪音先用 5根据命中率调整相似度阈值0.7-0.8过滤掉不相关结果太高会漏太低会引入噪音重排序候选数Top-K 的 2-3 倍给重排序模型更多选择先检索 20 个重排后取 5 个切分长度的选择有一个很实用的判断标准一个 chunk 应该能独立回答一个完整的问题。比如你问“XX 功能的配置步骤是什么”那一个 chunk 就应该包含完整的配置步骤而不是被切成两半。对于技术文档512 token 通常能覆盖一个完整的小节对于法律合同条款往往很长可能需要 1024 token对于客服对话记录每轮对话很短256 token 就够了。重叠窗口的作用是防止关键信息刚好落在切分边界上被切断。比如一句话的前半段在 chunk A 的末尾后半段在 chunk B 的开头如果没有重叠两个 chunk 都读不懂这句话。设 10%-20% 的重叠能有效缓解这个问题但也会增加存储和检索的开销所以不要设太大。Top-K 的取值逻辑是宁可多召回不可漏召回。因为后续还有重排序环节可以过滤但如果在检索阶段就漏掉了相关片段后面再怎么重排也救不回来。所以第一轮检索可以取大一点比如 20 个然后用重排序模型精选出 5 个送给 LLM。3. 文档加载与文本切分的实操细节3.1 不同格式文档的加载策略与清洗要点文档加载是整条管道的入口入口没处理好后面全是白费功夫。我按常见格式分别说一下加载策略和清洗要点。Markdown 和纯文本是最简单的直接读文件内容就行。但要注意去掉 YAML front matter、HTML 注释、多余的空白行。Markdown 的标题层级信息很有价值可以在切分的时候利用标题作为 chunk 的元数据检索时能提供额外的上下文。PDF是最麻烦的。PDF 本质上是排版格式不是语义格式所以提取出来的文本经常是乱的。表格会变成一堆散乱的数字双栏排版会交错在一起页眉页脚会混入正文。我的经验是优先用基于布局分析的 PDF 解析库而不是简单的文本提取。如果 PDF 是扫描件还需要先做 OCR。清洗的时候要重点处理去掉重复的页眉页脚、修复断行、把表格转换成 Markdown 表格格式。HTML的噪音最多。导航栏、侧边栏、广告、评论区这些内容对知识问答毫无价值但如果不清理它们会被切分、向量化、检索出来严重干扰结果。用 Readability 类的库提取正文或者用 CSS 选择器精准定位内容区域。清洗后还要把 HTML 标签去掉保留纯文本。Word 文档相对好处理但要注意批注、修订记录、文本框里的内容。这些内容有时候是重要的补充信息有时候是废弃的草稿需要根据实际情况决定是否保留。数据库和 API返回的数据通常是结构化的加载的时候要考虑怎么把结构化数据“扁平化”成文本。比如一条用户记录可以拼接成“用户张三年龄 30 岁注册时间 2024 年 1 月最近一次登录是 2025 年 3 月”。这样向量化之后才能被语义检索到。实操心得文档加载阶段一定要保留元数据。来源文件名、页码、章节标题、更新时间这些信息在后续检索和 Prompt 组装时非常有用。比如你可以让模型在回答时标注“根据《XX 手册》第 3 章”这能大幅提升回答的可信度。3.2 文本切分的四种主流方法对比文本切分不是简单地按字数切不同的切分方法对检索质量影响巨大。我对比一下四种主流方法。固定长度切分是最简单的按 token 数或者字符数切每段固定长度加上重叠窗口。优点是实现简单、速度快、chunk 大小均匀。缺点是经常在句子中间切断语义不完整。适合对检索精度要求不高的场景或者作为 baseline 快速验证。递归字符切分是 LangChain 默认的方法它按照一组分隔符的优先级递归切分先按段落切如果段落太长就按句子切如果句子还太长就按逗号切最后才按字符切。这样能尽量保持语义边界。实现也不复杂是我最推荐的方法。语义切分是用 Embedding 模型判断相邻句子的语义相似度在相似度骤降的地方切分。这种方法切出来的 chunk 语义最完整但计算成本高因为要对每个句子做向量化。适合对质量要求极高的场景比如法律合同、医学文献。基于文档结构的切分是利用文档本身的层级结构来切分比如 Markdown 的标题、HTML 的 section、PDF 的章节。这种方法切出来的 chunk 天然带有层级上下文检索时可以附带父级标题信息。对于结构良好的技术文档这是效果最好的方法。实际项目中我通常用递归字符切分 文档结构信息的组合先按文档结构切出大块再用递归字符切分把大块切成合适大小的 chunk同时保留章节标题作为元数据。3.3 切分参数的实测调优记录我拿一份 200 页的技术产品手册做过一组对比实验固定其他条件只调整切分参数看检索命中率的变化。命中率的定义是对于 50 个测试问题检索结果中包含正确答案所在片段的比例。切分长度重叠窗口命中率平均检索耗时256062%45ms2565071%48ms512068%52ms51210083%56ms1024065%61%102420079%68ms从数据可以看出几个规律。第一有重叠比没重叠命中率明显更高512 长度加 100 重叠是这组实验的最优组合。第二切分长度不是越大越好1024 的命中率反而比 512 低因为 chunk 太长引入了噪音向量表示被稀释了。第三重叠窗口会增加检索耗时因为 chunk 数量变多了但增幅在可接受范围内。当然这只是一份文档的实验结果不同文档类型的最优参数可能不同。我的建议是先用 512/100 作为默认值然后拿一批真实问题做测试根据命中率微调。如果发现经常漏掉关键信息就增大重叠如果发现检索结果太杂就减小 chunk size。4. 向量化、存储与检索的工程实现4.1 Embedding 模型选型维度、成本与中文支持的权衡Embedding 模型的选择直接决定了检索质量的上限。选型的时候主要看四个维度向量维度、语义质量、中文支持、调用成本。向量维度影响存储成本和检索速度。维度越高表达能力越强但存储和计算开销也越大。常见的维度有 384、768、1024、1536、3072。对于大多数应用场景768 到 1536 维已经足够。除非你的知识库非常庞大且语义细微否则没必要追求最高维度。语义质量是最核心的指标通常看 MTEB 等基准测试的排名。但要注意基准测试的排名不一定完全对应你的实际场景。最好的方法是拿你自己的数据做小规模测试看检索命中率。中文支持是很多国内开发者容易忽略的点。有些 Embedding 模型在英文上表现很好但中文语义理解能力很弱。选型的时候一定要用中文问题测试。目前中文表现较好的模型有 BGE 系列、M3E 系列、以及一些多语言模型。调用成本包括 API 费用和延迟。如果知识库很大每次更新都要重新向量化成本会很高。这时候可以考虑本地部署 Embedding 模型虽然初始投入大但长期成本更低而且没有网络延迟。我的实际选择是中小规模知识库用 API 调用大规模或高频更新用本地部署。本地部署推荐用 ONNX Runtime 跑量化后的模型在 Node.js 里也能获得不错的推理速度。4.2 向量数据库的选型对比与 TypeScript 接入向量数据库的选择很多我列几个主流的从 TypeScript 接入的友好度、部署复杂度、功能完整度三个维度对比。数据库TypeScript 支持部署方式特点适用场景Pinecone官方 SDK全托管零运维性能好快速验证中小规模Weaviate官方 SDK自托管/云功能全支持混合检索中大规模需要混合检索Qdrant官方 SDK自托管/云性能强过滤功能好大规模需要复杂过滤Chroma社区 SDK自托管轻量易上手本地开发小规模pgvector通过 pg 客户端自托管和关系数据在一起已有 PostgreSQL 的项目如果你刚开始做 RAG我建议先用Chroma在本地跑通流程它的 API 非常简单几行代码就能建库、插入、查询。等验证了效果再根据规模迁移到 Qdrant 或 Pinecone。TypeScript 接入向量数据库的时候有几个工程细节要注意。第一是批量插入不要一条一条插要攒一批一起插能大幅提升速度。第二是索引配置大多数向量数据库支持 HNSW 或 IVF 索引建索引的时候要调参平衡检索速度和召回率。第三是元数据过滤检索的时候可以加过滤条件比如只搜某个来源的文档、只搜某个时间段的内容这能显著提升检索精度。4.3 检索策略纯向量检索、关键词检索与混合检索检索策略的选择是 RAG 效果的关键分水岭。很多人以为向量检索就是全部其实不然。纯向量检索适合语义匹配的场景。比如用户问“怎么配置超时时间”文档里写的是“timeout 参数设置方法”关键词不匹配但语义匹配向量检索能找出来。但向量检索的弱点是对于精确匹配的场景比如产品型号、错误码、人名它可能不如关键词检索。关键词检索BM25 等适合精确匹配的场景。用户搜“ERR_4032”关键词检索能精准找到包含这个错误码的文档。但它无法处理语义变体用户问“权限不足报错”文档写的是“访问被拒绝”关键词检索就找不到。混合检索是把两者结合起来各取所长。通常的做法是同时执行向量检索和关键词检索然后用 RRFReciprocal Rank Fusion等算法融合两路结果。混合检索的命中率通常比单一策略高 10%-20%是目前生产环境的主流选择。在 TypeScript 里实现混合检索你可以用向量数据库自带的混合检索功能比如 Weaviate 的 hybrid search也可以自己分别调用两路检索再融合。自己实现的好处是灵活可以控制两路的权重和融合算法。4.4 重排序让 Top-K 结果更精准的最后一道关卡检索出来的 Top-K 结果向量相似度高不代表真的相关。重排序就是用更精细的模型对这 K 个结果重新打分把真正相关的排到前面。重排序模型通常比 Embedding 模型更大、更慢但更准。它的输入是“问题 候选片段”输出是一个相关性分数。因为只对 K 个候选做计算所以即使模型很大总耗时也可控。常见的重排序方案有两种。一种是交叉编码器把问题和片段拼在一起输入模型输出相关性分数。精度高但速度慢。另一种是基于 LLM 的重排序让 LLM 对每个候选片段打分。灵活但成本高适合对精度要求极高的场景。我的实践经验是先用交叉编码器做重排序如果效果还不够再考虑 LLM 重排序。交叉编码器在大多数场景下已经能带来明显的提升而且延迟增加在可接受范围内。重排序的候选数一般是最终 Top-K 的 2-3 倍。比如你最终要 5 个片段送给 LLM那就先检索 15-20 个重排序后取前 5。这样既保证了召回率又保证了精度。5. 从零搭建 TypeScript RAG 管道的完整实操5.1 项目初始化与依赖安装先把项目骨架搭起来。我用的是 Node.js 20 TypeScript 5包管理用 pnpm。mkdir rag-pipeline cd rag-pipeline pnpm init pnpm add typescript tsx types/node pnpm add openai chromadb pnpm add -D types/node这里我用了openai包来调用 Embedding 和 LLM用chromadb作为本地向量数据库。如果你用其他模型服务把openai换成对应的 SDK 就行。初始化 TypeScript 配置npx tsc --init然后修改tsconfig.json重点设置这几个选项{ compilerOptions: { target: ES2022, module: ESNext, moduleResolution: bundler, strict: true, esModuleInterop: true, skipLibCheck: true, outDir: ./dist, rootDir: ./src }, include: [src/**/*] }注意TypeScript 7.0 之后moduleResolution: node10和baseUrl选项会被弃用新项目直接用bundler或node16避免以后迁移麻烦。5.2 文档加载与切分模块实现先定义核心类型// src/types.ts export interface Document { id: string; content: string; metadata: { source: string; title?: string; page?: number; updatedAt?: string; }; } export interface Chunk { id: string; documentId: string; content: string; metadata: Document[metadata] { chunkIndex: number; }; }然后是文档加载器这里以 Markdown 为例// src/loader.ts import fs from fs/promises; import path from path; import { Document } from ./types.js; export async function loadMarkdown(filePath: string): PromiseDocument { const content await fs.readFile(filePath, utf-8); const fileName path.basename(filePath, .md); // 去掉 YAML front matter const cleaned content.replace(/^---[\s\S]*?---\n/, ); return { id: fileName, content: cleaned, metadata: { source: filePath, title: fileName, updatedAt: new Date().toISOString(), }, }; }切分模块用递归字符切分保留章节标题作为元数据// src/splitter.ts import { Document, Chunk } from ./types.js; const DEFAULT_CHUNK_SIZE 512; const DEFAULT_OVERLAP 100; export function splitDocument( doc: Document, chunkSize DEFAULT_CHUNK_SIZE, overlap DEFAULT_OVERLAP ): Chunk[] { const chunks: Chunk[] []; const paragraphs doc.content.split(/\n\n/); let currentChunk ; let chunkIndex 0; let currentTitle doc.metadata.title || ; for (const para of paragraphs) { // 检测标题行更新当前章节标题 const titleMatch para.match(/^#{1,3}\s(.)/); if (titleMatch) { currentTitle titleMatch[1].trim(); } // 如果加入这段会超长先保存当前 chunk if (currentChunk.length para.length chunkSize currentChunk) { chunks.push({ id: ${doc.id}-${chunkIndex}, documentId: doc.id, content: currentChunk.trim(), metadata: { ...doc.metadata, title: currentTitle, chunkIndex, }, }); chunkIndex; // 保留重叠部分 const overlapText currentChunk.slice(-overlap); currentChunk overlapText \n\n para; } else { currentChunk (currentChunk ? \n\n : ) para; } } // 处理最后一个 chunk if (currentChunk.trim()) { chunks.push({ id: ${doc.id}-${chunkIndex}, documentId: doc.id, content: currentChunk.trim(), metadata: { ...doc.metadata, title: currentTitle, chunkIndex, }, }); } return chunks; }这段代码有几个关键点。第一按段落切分而不是按字符切分尽量保持语义完整。第二检测 Markdown 标题行把章节标题存到元数据里检索时可以用。第三重叠部分取上一个 chunk 的末尾拼到下一个 chunk 的开头。5.3 向量化与入库的完整代码向量化和入库的流程是把 chunk 内容批量发给 Embedding API拿到向量后连同原文和元数据一起存入向量数据库。// src/indexer.ts import OpenAI from openai; import { ChromaClient } from chromadb; import { Chunk } from ./types.js; const openai new OpenAI({ apiKey: process.env.OPENAI_API_KEY }); const chroma new ChromaClient({ path: http://localhost:8000 }); const COLLECTION_NAME knowledge_base; const BATCH_SIZE 20; export async function indexChunks(chunks: Chunk[]): Promisevoid { const collection await chroma.getOrCreateCollection({ name: COLLECTION_NAME, metadata: { hnsw:space: cosine }, }); // 分批处理避免单次请求过大 for (let i 0; i chunks.length; i BATCH_SIZE) { const batch chunks.slice(i, i BATCH_SIZE); const embeddings await openai.embeddings.create({ model: text-embedding-3-small, input: batch.map(c c.content), }); await collection.add({ ids: batch.map(c c.id), embeddings: embeddings.data.map(e e.embedding), documents: batch.map(c c.content), metadatas: batch.map(c ({ source: c.metadata.source, title: c.metadata.title || , chunkIndex: c.metadata.chunkIndex, })), }); console.log(已索引 ${Math.min(i BATCH_SIZE, chunks.length)} / ${chunks.length}); } }这里有几个工程细节值得展开。批量大小设 20 是一个经验值太小会导致请求次数多、速度慢太大可能触发 API 的 token 限制。距离度量用 cosine 余弦距离这是文本 Embedding 最常用的度量方式。元数据只存必要的字段因为元数据也会占用存储空间而且检索时可以用于过滤。5.4 检索、重排序与 Prompt 组装的串联检索模块负责把用户问题向量化在数据库里找相似片段然后重排序最后组装成 Prompt。// src/retriever.ts import OpenAI from openai; import { ChromaClient } from chromadb; const openai new OpenAI({ apiKey: process.env.OPENAI_API_KEY }); const chroma new ChromaClient({ path: http://localhost:8000 }); export interface RetrievedChunk { content: string; source: string; title: string; score: number; } export async function retrieve( query: string, topK 5, candidateK 20 ): PromiseRetrievedChunk[] { const collection await chroma.getCollection({ name: knowledge_base }); // 问题向量化 const queryEmbedding await openai.embeddings.create({ model: text-embedding-3-small, input: query, }); // 第一轮检索取较多候选 const results await collection.query({ queryEmbeddings: [queryEmbedding.data[0].embedding], nResults: candidateK, }); const candidates: RetrievedChunk[] results.documents[0].map((doc, i) ({ content: doc || , source: (results.metadatas[0][i]?.source as string) || , title: (results.metadatas[0][i]?.title as string) || , score: 1 - (results.distances?.[0]?.[i] || 0), })); // 简单重排序按相似度分数排序后取 Top-K // 生产环境建议接入交叉编码器做精细重排序 return candidates .sort((a, b) b.score - a.score) .slice(0, topK); }Prompt 组装模块把检索结果拼接成结构化的上下文// src/prompt.ts import { RetrievedChunk } from ./retriever.js; export function buildPrompt( query: string, chunks: RetrievedChunk[] ): string { const context chunks .map((c, i) { const source c.title ? 《${c.title}》 : c.source; return [片段 ${i 1}] 来源${source}\n${c.content}; }) .join(\n\n---\n\n); return 你是一个知识助手。请基于以下参考资料回答用户问题。 如果参考资料中没有相关信息请明确说明根据现有资料无法回答不要编造。 参考资料 ${context} 用户问题${query} 请给出准确、简洁的回答并在回答中标注信息来源。; }最后把所有模块串起来// src/main.ts import { loadMarkdown } from ./loader.js; import { splitDocument } from ./splitter.js; import { indexChunks } from ./indexer.js; import { retrieve } from ./retriever.js; import { buildPrompt } from ./prompt.js; import OpenAI from openai; const openai new OpenAI({ apiKey: process.env.OPENAI_API_KEY }); async function buildKnowledgeBase(filePaths: string[]) { for (const filePath of filePaths) { const doc await loadMarkdown(filePath); const chunks splitDocument(doc); await indexChunks(chunks); console.log(已处理 ${filePath}切分为 ${chunks.length} 个片段); } } async function ask(query: string) { const chunks await retrieve(query, 5, 20); const prompt buildPrompt(query, chunks); const response await openai.chat.completions.create({ model: gpt-4o-mini, messages: [{ role: user, content: prompt }], temperature: 0.1, }); return response.choices[0].message.content; } // 使用示例 await buildKnowledgeBase([./docs/manual.md, ./docs/faq.md]); const answer await ask(如何配置超时时间); console.log(answer);这套代码可以直接跑起来把docs目录换成你自己的文档就行。temperature设 0.1 是为了让回答更稳定、更贴近参考资料减少模型自由发挥的空间。6. 常见问题排查与效果调优实录6.1 检索命中率低的五个典型原因检索命中率低是 RAG 最常见的问题。我按排查优先级列一下典型原因和对策。原因一切分粒度不对。chunk 太大关键信息被淹没在大量无关文字里chunk 太小语义不完整。排查方法是把检索结果打印出来人工看是否包含答案。对策是调整 chunk size 和 overlap用第 3 节的方法做对比实验。原因二Embedding 模型不适合中文。有些模型英文很强但中文很弱导致中文问题的向量和中文文档的向量对不上。排查方法是用几个中文问题测试看检索结果是否相关。对策是换成中文表现更好的模型。原因三缺少重排序。纯向量检索的 Top-K 里可能混入了不相关的结果把真正相关的挤到了后面。排查方法是看 Top-20 里有没有正确答案如果有但 Top-5 里没有那就是重排序的问题。对策是加入重排序环节。原因四元数据过滤缺失。如果知识库里有多个来源的文档检索时没有按来源过滤可能搜到不相关来源的内容。对策是在检索时加上元数据过滤条件。原因五问题表述和文档表述差异太大。用户用口语提问文档用专业术语向量相似度可能不高。对策是加入查询改写环节用 LLM 把用户问题改写成更适合检索的形式。6.2 回答质量不稳定的排查思路检索没问题但回答质量不稳定通常是 Prompt 组装或模型调用的问题。问题一模型不按参考资料回答。明明检索到了正确内容模型却用自己的知识回答。对策是在 Prompt 里强调“必须基于以下参考资料回答”并且降低 temperature。如果还不行可以在 Prompt 里加入 few-shot 示例展示正确的回答格式。问题二模型编造信息。参考资料里没有的内容模型自己编了一个。对策是在 Prompt 里明确要求“如果资料中没有相关信息请说明无法回答”并且加入“不要编造”的指令。更严格的做法是让模型在回答时引用具体的片段编号方便人工核查。问题三回答太长或太短。对策是在 Prompt 里指定回答长度范围比如“用 2-3 句话回答”或“详细说明每个步骤”。问题四多个片段信息冲突。检索到的不同片段说法不一致模型不知道信哪个。对策是在 Prompt 里加入冲突处理指令比如“如果资料之间有冲突请指出冲突并说明”。6.3 性能优化从 3 秒到 300 毫秒的实操记录RAG 管道的延迟主要来自三个环节Embedding 调用、向量检索、LLM 生成。我记录了一次优化过程把端到端延迟从 3 秒降到了 300 毫秒不含 LLM 生成。优化项优化前优化后手段Embedding 调用800ms50ms本地部署量化模型 缓存向量检索200ms30ms调整 HNSW 索引参数重排序1500ms150ms换用更小的交叉编码器Prompt 组装50ms10ms减少字符串拼接开销网络传输500ms60ms服务同区域部署最大的优化来自 Embedding 的本地化和缓存。对于高频重复的问题Embedding 结果可以缓存直接命中缓存能省掉整个调用过程。向量检索的优化主要是调整 HNSW 的efSearch参数在召回率和速度之间找平衡。重排序换用更小的模型后精度略有下降但速度提升 10 倍整体性价比更高。实操心得不要过早优化。先把管道跑通确认效果达标再针对瓶颈环节优化。很多时候瓶颈不在你以为的地方用 profiling 工具测一下再动手。6.4 常见问题速查表现象可能原因排查方法解决方案检索不到相关内容切分粒度不对打印检索结果人工检查调整 chunk size 和 overlap检索结果不相关Embedding 模型不适合用中文问题测试换中文表现好的模型正确答案在 Top-20 但不在 Top-5缺少重排序对比重排序前后结果加入交叉编码器重排序模型不按资料回答Prompt 指令不明确检查 Prompt 模板强调基于资料回答降低 temperature模型编造信息缺少防幻觉指令测试无答案的问题加入“无法回答”指令和引用要求回答延迟高某个环节耗时过长分环节计时针对性优化加缓存多来源信息冲突缺少冲突处理构造冲突测试用例Prompt 中加入冲突处理指令7. 知识获取管道的扩展方向7.1 从基础 RAG 到 Agentic RAG 的演进路径基础 RAG 是“一次检索一次生成”但很多问题需要多轮检索、多步推理。Agentic RAG就是把检索能力交给 Agent 来规划Agent 可以先分析问题决定需要检索什么检索后评估结果是否充分不充分就换个查询再检索直到信息足够才生成回答。这种模式适合复杂问题比如“对比 A 产品和 B 产品在超时配置上的差异”需要分别检索两个产品的文档然后对比。基础 RAG 可能只检索到其中一个产品的信息而 Agentic RAG 会规划两次检索。实现 Agentic RAG 的关键是给 Agent 提供检索工具并设计好规划 Prompt。Agent 需要知道什么时候该检索、检索什么、检索几次。这比基础 RAG 复杂但能处理的问题类型也丰富得多。7.2 知识图谱与 RAG 的结合思路向量检索擅长语义匹配但不擅长关系推理。比如“A 的上级的上级是谁”这种问题向量检索很难直接回答。GraphRAG的思路是把知识构建成图结构实体是节点关系是边检索时沿着图遍历能找到向量检索找不到的关联信息。实际落地的时候通常是混合方案向量检索负责语义召回知识图谱负责关系推理两者结果融合后送给 LLM。构建知识图谱需要额外的实体抽取和关系抽取步骤成本较高适合实体关系密集的场景比如企业组织架构、产品依赖关系、法律条款引用网络。7.3 多模态知识库的展望现在的 RAG 主要处理文本但企业知识大量存在于图片、表格、PPT、视频里。多模态 RAG 是下一个方向用多模态 Embedding 模型把图片和文本映射到同一向量空间检索时可以跨模态匹配。比如用户问“那个架构图里数据库放在哪”系统能检索到架构图并理解图中的内容。目前多模态 RAG 还在早期阶段工具链不够成熟成本也较高。但对于设计文档、产品手册、培训材料这类图文混排的知识库多模态 RAG 的价值很大。我的建议是先把文本 RAG 做扎实等业务确实有需求了再考虑多模态扩展。我个人在实际操作中的体会是RAG 管道的效果 20% 靠模型80% 靠工程细节。切分策略、检索参数、Prompt 模板这些看起来不起眼的地方才是决定最终效果的关键。不要迷信“换个更强的模型就能解决问题”先把管道里的每个环节调到位效果自然就上来了。