1. 为什么知识获取管道是 AI Agent 的分水岭
做 AI Agent 开发的人，绕不开一个尴尬的现实：模型本身很聪明，但它对你私有的业务数据一无所知。你问它公司内部的报销流程，它要么胡编一个看起来很像样的答案，要么礼貌地告诉你它不知道。这不是模型能力问题，而是信息边界问题。知识获取管道要解决的，就是把这个边界打通——让 Agent 在回答问题之前，先去正确的地方找到正确的资料，再基于资料生成回答。
这套机制在行业里有个更通用的名字：RAG（Retrieval-Augmented Generation，检索增强生成）。名字听起来学术，拆开看其实很朴素：检索（Retrieval）负责找资料，增强（Augmented）负责把资料塞进上下文，生成（Generation）负责基于资料说话。三个环节串起来，就是一条完整的知识获取管道。
我在实际项目里踩过的最大坑，不是模型选得不对，而是管道设计得太随意。很多人一上来就调 API、切分文档、灌进向量库，跑通了 demo 就以为完事了。结果上线之后发现：检索命中率低得可怜，模型拿着不相关的片段硬编答案，用户问东它答西。RAG 的难点从来不在"能不能跑通"，而在"检索得准不准"。这也是为什么我把知识获取管道称为 AI Agent 的分水岭——管道设计得好，Agent 像个懂行的专家；设计得差，Agent 就是个会说话的搜索引擎，还经常搜错。
这篇文章面向的是已经了解 AI Agent 基本概念、准备动手搭建知识获取管道的开发者。无论你用 TypeScript 还是 Java，无论你选 LangChain 还是自己手写，底层的管道逻辑是相通的。我会从整体设计思路讲起，把每个环节的取舍逻辑、参数计算、实操细节都摊开说，最后附上我踩过的坑和排查技巧。读完你应该能独立设计一条可用的 RAG 管道，而不是照抄一个跑不通的 demo。
2. RAG 管道的整体设计与方案选型
2.1 一条完整管道的四个阶段
很多人把 RAG 理解成"向量检索 + 大模型"，这个理解太窄了。一条能上生产的知识获取管道，至少包含四个阶段：
- 数据接入与预处理：把 PDF、Markdown、网页、数据库记录等原始资料，转成干净的纯文本。这一步决定了后续所有环节的上限。
- 切分与向量化：把长文本切成合适大小的片段（chunk），用嵌入模型转成向量，存进向量数据库。
- 检索与重排：用户提问时，把问题也转成向量，从库里召回一批候选片段，再用重排模型精挑细选。
- 上下文组装与生成：把选中的片段拼进提示词，交给大模型生成最终答案。
这四个阶段里，预处理和切分是最容易被忽视、却最影响效果的环节。我见过太多项目，向量库选的是最贵的，模型用的是最强的，但文档切分一塌糊涂，检索出来的片段要么缺头少尾，要么把两个不相关的段落粘在一起。这种情况下，再好的模型也救不回来。
2.2 为什么选 TypeScript 作为实现语言
热词里出现了 TypeScript，这不是偶然。用 TypeScript 写 RAG 管道有几个实打实的好处：
第一，类型系统能在编译期拦住大量低级错误。RAG 管道里数据在多个环节之间流转，从原始文档到 chunk、到向量、到检索结果、到最终上下文，每一步的数据结构都不一样。用 TypeScript 定义好接口，字段名写错、类型对不上，编辑器立刻报红，不用等到运行时才发现。
第二，生态成熟。LangChain.js、LlamaIndex.TS 这些框架都提供了完整的 TypeScript 支持，向量库客户端（如 Pinecone、Qdrant、Chroma）也都有官方 TS SDK。你不需要为了用某个工具去切换语言。
第三，前后端统一。如果你的 Agent 有 Web 界面，用 TypeScript 可以前后端共享类型定义，检索结果的格式在两端完全一致，省掉大量对接成本。
注意：TypeScript 7.0 之后，
baseUrl和moduleResolution=node10这两个选项会被弃用。如果你现在还在用baseUrl做路径别名，建议尽早迁移到paths配合moduleResolution: "bundler"或"node16"，否则升级时会踩坑。
2.3 向量库选型的取舍逻辑
向量库的选择没有标准答案，取决于你的数据规模和部署环境。我把常见的几个选项列出来对比：
| 向量库 | 部署方式 | 适合规模 | 核心优势 | 注意事项 |
|---|---|---|---|---|
| Chroma | 本地/嵌入式 | 万级以下 | 零配置，适合原型 | 生产环境性能有限 |
| Qdrant | 自托管/云 | 百万级 | 过滤能力强，Rust 性能好 | 需要运维 |
| Pinecone | 纯云 | 千万级 | 免运维，扩展性好 | 有网络延迟和成本 |
| pgvector | 复用 PostgreSQL | 十万级 | 和业务数据同库 | 索引调优有门槛 |
我的建议是：原型阶段用 Chroma，快速验证管道逻辑；生产阶段根据数据量选 Qdrant 或 pgvector。如果你已经有 PostgreSQL，pgvector 是最省事的选择，因为不用额外维护一套存储系统。数据量超过千万再考虑专用云服务。
2.4 嵌入模型与重排模型的搭配
嵌入模型负责把文本转成向量，它的质量直接决定检索的召回率。重排模型负责对召回的候选做精排，决定最终的准确率。这两个模型是搭配使用的，不是二选一。
嵌入模型的选择上，我实测下来，多语言场景优先选支持中文的模型，纯英文场景可以用更轻量的。模型维度不是越高越好，768 维和 1536 维在实际检索效果上差距没有想象中大，但存储和计算成本差一倍。重排模型则建议一定要加，它能把检索准确率提升 10 到 20 个百分点，这个投入非常值。
3. 核心细节解析与实操要点
3.1 文档切分：RAG 效果的第一道关卡
切分（Chunking）是整条管道里最需要动脑子的环节。切得太粗，一个 chunk 里混了好几个主题，检索时噪声大；切得太细，一个完整的逻辑被拆散，模型拿到半截话也答不好。
我常用的策略是按语义结构切分，再按长度兜底。具体做法：
- 优先按文档的自然结构切，比如 Markdown 的标题层级、PDF 的段落、代码的函数边界。
- 如果某个自然段落超过阈值（我一般设 800 到 1000 字符），再按句子边界二次切分。
- 相邻 chunk 之间保留 10% 到 15% 的重叠（overlap），避免关键信息正好卡在边界上被切断。
为什么是 800 到 1000 字符？这是经验值。太短（比如 200 字符）会导致语义不完整，检索出来的片段信息量不足；太长（比如 2000 字符）会稀释关键信息，向量表示被无关内容拉偏。你可以根据自己文档的特点微调，但别偏离这个区间太远。
interface Chunk { id: string; content: string; metadata: { source: string; heading?: string; position: number; }; } function splitByHeading(text: string, maxLen = 900, overlap = 120): Chunk[] { const sections = text.split(/\n(?=#{1,3}\s)/); const chunks: Chunk[] = []; let position = 0; for (const section of sections) { if (section.length <= maxLen) { chunks.push(buildChunk(section, position++)); continue; } // 超长段落按句子边界二次切分 const sentences = section.split(/(?<=[。！？.!?])\s*/); let buffer = ""; for (const s of sentences) { if ((buffer + s).length > maxLen && buffer.length > 0) { chunks.push(buildChunk(buffer, position++)); buffer = buffer.slice(-overlap) + s; } else { buffer += s; } } if (buffer.trim()) chunks.push(buildChunk(buffer, position++)); } return chunks; }这段代码的关键在于buffer.slice(-overlap)——它保留了上一个 chunk 的尾部作为下一个 chunk 的开头，实现重叠。别小看这一行，它解决了很多"答案被切断"的问题。
3.2 元数据设计：被低估的检索加速器
很多人切完 chunk 只存文本和向量，元数据一概不管。这是个巨大的浪费。元数据是检索时做过滤和加权的重要依据。
我一般会给每个 chunk 挂上这些元数据：
source：来源文件路径或 URL，用于溯源。heading：所属章节标题，检索时可以按标题加权。position：在文档中的位置，用于判断上下文连续性。updatedAt：更新时间，用于时效性过滤。category：业务分类，用于按类别过滤。
有了这些元数据，检索时就能做混合检索：先用向量做语义召回，再用元数据做条件过滤。比如用户问"最新的报销政策"，你可以先按category=财务过滤，再按updatedAt排序，最后做语义匹配。这样检索出来的结果精准度会高很多。
3.3 检索策略：从单路召回走向混合检索
单一的向量检索有个天然缺陷：它对精确匹配不敏感。用户问一个具体的产品型号、一个专有名词，向量检索可能召回一堆语义相近但型号不对的片段。
解决办法是混合检索（Hybrid Search）：向量检索负责语义召回，关键词检索（BM25）负责精确匹配，两路结果融合后重排。这个组合在实际项目里效果提升非常明显，尤其是技术文档、产品手册这类包含大量专有名词的场景。
融合的算法我一般用RRF（Reciprocal Rank Fusion，倒数排名融合），它不需要归一化两路分数，直接按排名计算：
score(d) = Σ 1 / (k + rank_i(d))其中k通常取 60，rank_i(d)是文档 d 在第 i 路检索中的排名。这个公式的好处是：一个文档如果在两路检索里都排得靠前，它的融合分数会显著高于只在一路里靠前的文档。
3.4 重排：把准确率再拉高一截
召回阶段追求的是"不漏"，重排阶段追求的是"精准"。召回可能返回 20 到 50 个候选，重排模型逐个打分，选出最相关的 3 到 5 个送进上下文。
重排模型比嵌入模型重，但因为它只处理少量候选，整体延迟可控。我实测下来，加一层重排，检索准确率能提升 10 到 20 个百分点，而延迟只增加 100 到 300 毫秒。这个性价比非常高，强烈建议加上。
提示：重排模型的输入是"问题 + 候选片段"的配对，输出是相关性分数。它和嵌入模型的区别在于，嵌入模型是分别编码问题和文档，重排模型是联合编码，所以能捕捉更细粒度的交互信息。
4. 实操过程与核心环节实现
4.1 环境搭建与依赖安装
先把项目骨架搭起来。我用的是 Node.js 20 加 TypeScript 5，包管理用 pnpm。
mkdir rag-pipeline && cd rag-pipeline pnpm init pnpm add @langchain/core @langchain/openai chromadb pnpm add -D typescript tsx @types/node npx tsc --inittsconfig.json里重点配置这几项：
{ "compilerOptions": { "target": "ES2022", "module": "ESNext", "moduleResolution": "bundler", "strict": true, "esModuleInterop": true, "skipLibCheck": true, "paths": { "@/*": ["./src/*"] } } }注意这里用的是paths而不是baseUrl，因为前面提到baseUrl在 TypeScript 7.0 会被弃用。moduleResolution用bundler是为了兼容现代打包工具。
4.2 文档加载与清洗
加载环节要把各种格式的文档统一转成纯文本。PDF 用pdf-parse，Markdown 直接读，网页用cheerio提取正文。清洗的重点是去掉页眉页脚、多余空行、乱码字符。
import { readFile } from "fs/promises"; import pdf from "pdf-parse"; async function loadDocument(path: string): Promise<string> { if (path.endsWith(".pdf")) { const buffer = await readFile(path); const { text } = await pdf(buffer); return cleanText(text); } const raw = await readFile(path, "utf-8"); return cleanText(raw); } function cleanText(text: string): string { return text .replace(/\r\n/g, "\n") .replace(/\n{3,}/g, "\n\n") .replace(/[ \t]{2,}/g, " ") .replace(/第\s*\d+\s*页/g, "") .trim(); }清洗这一步看着简单，但它直接决定了切分的质量。如果页眉页脚没去掉，每个 chunk 里都混着"第 X 页"这种噪声，向量表示会被污染。
4.3 向量化与入库
切分完成后，批量调用嵌入模型生成向量，连同元数据一起写入向量库。这里要注意批量大小和并发控制，一次发太多请求会被限流，发太少又慢。
import { ChromaClient } from "chromadb"; import { OpenAIEmbeddings } from "@langchain/openai"; const BATCH_SIZE = 64; async function indexChunks(chunks: Chunk[]) { const client = new ChromaClient(); const collection = await client.getOrCreateCollection({ name: "knowledge" }); const embedder = new OpenAIEmbeddings({ model: "text-embedding-3-small" }); for (let i = 0; i < chunks.length; i += BATCH_SIZE) { const batch = chunks.slice(i, i + BATCH_SIZE); const vectors = await embedder.embedDocuments(batch.map(c => c.content)); await collection.add({ ids: batch.map(c => c.id), embeddings: vectors, documents: batch.map(c => c.content), metadatas: batch.map(c => c.metadata), }); console.log(`已入库 ${Math.min(i + BATCH_SIZE, chunks.length)}/${chunks.length}`); } }BATCH_SIZE设 64 是我实测下来比较稳的值。太小（比如 16）会导致请求次数过多，整体耗时翻倍；太大（比如 256）容易触发限流，反而更慢。
4.4 检索与上下文组装
检索环节把混合检索和重排串起来，最后组装成提示词。
async function retrieve(query: string, topK = 5) { const queryVector = await embedder.embedQuery(query); // 向量召回 const vectorResults = await collection.query({ queryEmbeddings: [queryVector], nResults: 20, }); // 关键词召回（BM25，这里用简化示意） const keywordResults = await bm25Search(query, 20); // RRF 融合 const fused = rrfFuse([vectorResults, keywordResults], 60); // 重排取前 topK const reranked = await rerank(query, fused.slice(0, 20)); return reranked.slice(0, topK); } function buildPrompt(query: string, contexts: string[]): string { const contextText = contexts .map((c, i) => `[片段 ${i + 1}]\n${c}`) .join("\n\n"); return `基于以下资料回答问题。如果资料中没有相关信息，请明确说明"资料中未提及"，不要编造。 资料： ${contextText} 问题：${query} 回答：`; }提示词里那句"如果资料中没有相关信息，请明确说明"非常关键。不加这句，模型会倾向于硬编答案；加了之后，它在资料不足时会老实说不知道，这比编一个错误答案要好得多。
4.5 参数计算：topK 和上下文长度怎么定
topK 和上下文长度不是拍脑袋定的，要算。假设你的嵌入模型上下文窗口是 8192 token，每个 chunk 平均 300 token，那么理论上最多能塞 27 个 chunk。但实际不能塞满，因为还要留空间给问题和回答。
我的计算方式是：
- 模型总窗口：8192 token
- 预留回答空间：1024 token
- 预留问题空间：256 token
- 可用上下文：8192 - 1024 - 256 = 6912 token
- 每个 chunk 300 token，则最多 23 个 chunk
但实际我一般只取 5 个 chunk。为什么？因为上下文不是越多越好。塞太多片段会引入噪声，模型反而抓不住重点。5 个精挑细选的片段，效果通常好于 20 个鱼龙混杂的片段。这就是重排的价值——它帮你从 20 个候选里选出最相关的 5 个。
5. 常见问题与排查技巧实录
5.1 检索命中率低的排查路径
检索命中率低是最常见的问题。我一般按这个顺序排查：
| 现象 | 可能原因 | 排查方法 | 解决方向 |
|---|---|---|---|
| 完全召不回相关片段 | 切分太粗或太细 | 打印 chunk 内容人工检查 | 调整切分粒度 |
| 召回了但排序靠后 | 缺少重排 | 看召回列表的排名 | 加重排模型 |
| 专有名词召不回 | 纯向量检索 | 测试关键词检索 | 上混合检索 |
| 语义相近但答非所问 | 嵌入模型不匹配 | 换模型对比 | 换多语言模型 |
| 时效性内容召不回 | 元数据缺失 | 检查 metadata | 加时间过滤 |
排查的第一步永远是把检索结果打印出来人工看。很多人跳过这一步直接调参数，结果越调越乱。你得先看到底召回了什么，才能判断问题出在哪。
5.2 模型编造答案的抑制方法
模型编造答案（幻觉）是 RAG 里最头疼的问题。我的经验是三道防线：
第一道，提示词约束。明确告诉模型"只基于资料回答，资料没有就说不知道"。这句话能挡掉大部分幻觉。
第二道，引用溯源。要求模型在回答里标注引用了哪个片段，这样你能快速验证答案是否有据可依。
第三道，相关性阈值。如果重排后的最高分低于某个阈值（比如 0.5），说明资料库里根本没有相关内容，这时候直接返回"未找到相关资料"，不要硬让模型答。
注意：阈值不能设太高，否则会把本来能答的问题也挡掉。我一般从 0.3 开始试，根据实际效果微调。
5.3 性能优化的几个实操技巧
RAG 管道的延迟主要花在三个地方：嵌入、检索、生成。优化要分而治之。
嵌入环节，把文档向量化做成离线批处理，不要每次查询都重新算。查询时的嵌入只算用户问题这一个，很快。
检索环节，向量库要建索引。Chroma 默认用的是暴力搜索，数据量大了会慢。Qdrant 和 pgvector 都支持 HNSW 索引，建好之后检索延迟能降一个数量级。
生成环节，流式输出。用户不需要等完整答案生成完才看到内容，流式返回能显著提升体感速度。
还有一个容易被忽视的点：缓存。相同或相似的问题，检索结果可以缓存。我用的是问题向量的余弦相似度做缓存键，相似度超过 0.95 就命中缓存，能省掉大量重复检索。
5.4 我踩过的三个坑
第一个坑：切分时把表格切散了。技术文档里经常有参数表格，按段落切分会把表格拆成好几块，检索时拿到半张表，模型根本看不懂。后来我专门给表格做了处理，把整张表作为一个 chunk，不参与二次切分。
第二个坑：元数据里的中文没做编码处理。有些向量库对中文元数据的支持不好，存进去取出来是乱码。解决办法是统一用 UTF-8，必要时对元数据做 Base64 编码。
第三个坑：重排模型和嵌入模型的语言不匹配。嵌入模型支持中文，重排模型只支持英文，结果重排阶段把中文片段全排到后面去了。这两个模型的语言支持必须一致，这是硬性要求。
6. 从基础 RAG 到 Agentic RAG 的演进方向
基础 RAG 跑通之后，你会发现它有个天花板：它只会被动检索，不会主动思考该检索什么。用户问一个复杂问题，基础 RAG 只会拿整个问题去检索一次，召回的内容往往不够全面。
这就是Agentic RAG要解决的问题。它把检索能力交给 Agent 来调度，Agent 可以：
- 拆解问题：把复杂问题拆成多个子问题，分别检索。
- 多轮检索：第一轮检索后，根据结果判断信息是否足够，不够就换个角度再检索。
- 选择工具：根据问题类型，决定是查向量库、查数据库还是调 API。
- 自我反思：检查检索到的内容是否真的回答了问题，不相关就重新检索。
实现 Agentic RAG 的关键是给 Agent 一套清晰的工具定义和决策逻辑。在 TypeScript 里，你可以用 LangChain 的 Agent 框架，把检索封装成一个 tool，让 Agent 自己决定什么时候调用、调用几次。
const retrievalTool = { name: "search_knowledge", description: "搜索内部知识库。当需要查询公司政策、产品文档、技术规范时使用。", schema: z.object({ query: z.string().describe("搜索关键词，应该具体明确"), category: z.string().optional().describe("限定搜索范围，如'财务'、'技术'"), }), async invoke({ query, category }) { return await retrieve(query, 5, category); }, };这个 tool 的定义里，description写得好不好，直接决定 Agent 会不会在正确的时机调用它。我一般会把"什么时候用"和"什么时候不用"都写清楚，减少误调用。
从基础 RAG 到 Agentic RAG，本质是从"一次检索"到"按需多次检索"的演进。这个演进带来的效果提升，在复杂问答场景里非常明显。但它也带来了新的挑战：检索次数变多，延迟和成本都会上升。所以我的建议是，先用基础 RAG 把管道跑稳，等遇到明确的瓶颈再上 Agentic RAG，不要一上来就追求最复杂的方案。
我个人在实际项目里的体会是，RAG 这条管道，80% 的效果来自 20% 的设计决策——切分策略、混合检索、重排这三件事做对了，效果就不会差。剩下的优化都是锦上添花。与其花时间调各种花哨的参数，不如先把这三件事做扎实。
