聊 RAG 的人很多但能从零到一亲手把整条链路跑通、过程中每一行代码都能解释清楚的其实没那么多。最近我集中折腾了一个知识库问答项目核心就是 RAG——检索增强生成目标是让大模型回答问题时基于内部文档而不是凭空瞎编。整个链路从文档解析、分块、向量化、索引存储到检索、重排、提示词构造、最终生成我完整跑了好几遍踩了不少坑也整理了一套最小可复现的实现。这篇文章就把这条链路逐段拆开讲配套代码一个函数一个函数地讲最后把高频问题排查清单也列出来。如果你是第一次接触 RAG想搞懂它和微调、长上下文有什么区别或者你已经跑过 demo 但效果不理想、不知道从哪里调起这篇应该都适合你。1. 先搞清楚 RAG 是干嘛的从上下文长尾问题说起1.1 为什么大模型需要“外挂知识库”大模型在训练阶段学到的知识是“截止型”的。一个最近发生的行业事件只要训练语料里没有模型只能靠内部关联瞎猜猜错就成了幻觉。同理企业内部的产品手册、技术方案、合同条款这些内容从来不在公开语料里模型不可能答好。这时候有两类思路一类是继续训练或微调把知识塞进参数另一类就是 RAG在问答时临时检索相关材料给模型看。我一开始也纠结过是不是要微调。后来项目里的说明书每周都在改如果用微调每次更新都要重训一遍成本完全扛不住。RAG 的好处恰恰在于知识不进参数只进索引。文档变了重新切分、向量化一遍就行不用动模型本身。这个“可随时更新”的特点在现实业务里几乎直接决定了技术选型。打个比方微调像是让一个学生考前把所有知识点背进脑子RAG 则是允许他开卷考试考场上翻目录找答案。开卷的优势是教材更新了不用重新背劣势是翻书要时间、也要翻得准。RAG 的工程难点基本都集中在“怎么翻得准、翻得快”。1.2 RAG、微调、长上下文怎么选很多人在规划知识问答系统时会在 RAG、微调、长上下文三条路线里来回摇摆。我一般用下面这张表来判断维度RAG微调长上下文知识更新成本只需重建索引需要重新训练每次请求重传全文可解释性可溯源到原文片段黑盒可溯源但成本高私有知识适配强中强计算成本低到中高中到高典型场景企业问答、客服风格迁移、能力增强单次需要整体理解超长文档选型的逻辑不复杂如果答案“能从某份文档里找到”优先 RAG如果想让模型整体学会某种表达风格、某个任务套路微调更合适如果单个样本内容特别长且必须全局理解长上下文可以作为补充但成本高而且长文本中间段的注意力衰减问题也得考虑。实际项目里常见的是混合方案RAG 为主对反复出错的高频 case 做小规模微调兜底。1.3 一条链路看全局从文档到回答RAG 完整的链路可以分为两大段索引构建段文档加载 → 清洗 → 分块 → 向量化 → 构建索引 问答推理段用户问题 → 向量化 → 召回候选 → 重排序 → 拼提示词 → 模型生成 → 返回答案这两段合在一起才是“完整链路”。只看生成端或者只看检索端都容易出偏。建索引就像给一本书做目录和书签检索环节就是你拿着问题去查目录找到相关页码再把几页内容抄给模型看。模型不需要背下全书只需要知道去哪一页找答案然后基于这几页内容组织回答。这条链路还有一个容易被忽视的属性每个环节的输出质量决定了下一个环节的上限。很多 demo 效果不好不是模型不行而是文档没切对或者检索回来的内容本身就不相关。带着这个“链路思维”去看后面的细节很多坑你就能提前预判。2. 文档进、向量出索引构建的四个关键环节2.1 文档清洗垃圾进垃圾出不管是 PDF 还是 Word原始文本通常带大量噪声页眉页脚、页码、超链接、表格里拆碎的字段。这些噪声如果直接进分块会产生两种坏结果一是向量被干扰检索时把页眉这种无关内容当成强相关片段召回二是分块会被噪声切断明明同一句话被截得上下文不连贯。我在项目里整理了一套清洗流程先去掉所有页眉页脚和页码再按章节标题切分最后用正则去掉连续空白和多余换行。清洗完的文档我会人工抽查十几个段落确认没有乱码和错位再进入下一步。很多人忽略这一步把脏数据直接喂给后面的流程结果反复调参都没好转其实问题在源头。清洗看起来不性感但它可能是性价比最高的环节。PDF 类文档还要额外留意表格。表格内容一旦被线性读取字段之间的关系就丢了。我的处理方法是把表格转成“字段名值”的文本结构比如“住宿上限450元/天”这样既能保留语义又方便后续检索。否则模型很容易把表头和数值拆到两个块里。2.2 分块策略chunk 大小为什么重要分块是 RAG 链路里影响最大、也最容易被低估的环节。chunk 太小一个完整业务逻辑散成好几片检索只能召回其中一片模型缺乏上下文chunk 太大向量被平均化一个几百字的片段里混了多个主题检索精度直线下降。我的经验是中文场景里 chunk_size 落在 256 到 1024 字之间overlap 取 chunk 的 10% 到 20%然后根据实际效果微调。overlap 的作用很微妙。它能避免一句话在边界处被切开后语义丢失让跨块的信息在每个块里都有完整表达。但 overlap 也会带来冗余重复片段被多次喂给模型既浪费 token 又可能造成干扰。要不要加、加多少取决于数据是不是有强上下文依赖。有条件的团队会把结构化文档按标题层级切而不是盲目固定长度这对质量提升非常明显。我在另一个项目里对比过固定长度分块和按标题分块。同样的问答集固定长度分块的召回准确率大概在七成按标题层级分块能到八成五以上。原因很直接业务文档天然围绕章节组织按标题切出来的块每个块的主题都相对纯净向量表达也更聚焦。2.3 向量化Embedding 选型分块之后的文本不是直接进模型的它要先变成向量。embedding 模型的质量直接决定“语义相近”能不能被数学上捕捉到。选型时我一般看三点第一对中文支持好不好很多英文模型跑中文检索分数虚高第二向量维度与检索库的配合维度越高单条占用的内存越大超大语料下索引成本成倍涨第三接口稳定性线上调用一定要有批量和重试机制。维度不是越高越好不要把模型能力简单等同于维度大小。一个针对垂直领域调优过的 768 维模型往往比一个 1536 维的通用模型在企业资料上更准。向量化之后一定要做归一化这样才能统一用内积或余弦相似度比较数值也稳定。否则不同文档向量模长不一致相似度计算会被模长干扰。这里还要提一个工程习惯把向量持久化缓存起来。同一段文本embedding 一次后就存下来下次直接读取。个人项目里很容易忽略这个点数据量一大每次重建索引都要重新调用 embedding时间和成本都很浪费。2.4 向量存储与索引小项目直接用内存里存列表、暴力比对就行响应几百毫秒完全能顶住。数据量大了就必须上近似最近邻索引原理是用聚类或图结构把搜索范围从全量缩小到局部。具体实现上大多数向量数据库默认支持图索引和倒排聚类两类方案。图索引的召回率更高但建索引慢、内存占用大聚类方案速度快但调参讲究。工程里容易被忽略的是元数据过滤。跟“先查目录再翻页”一个道理如果能先用时间、来源、文档类型把候选集缩小再在范围里做相似度检索查得快也更准。我遇到过不少项目几百万条文档全量暴力检索加一个分类过滤后速度提升了十几倍准确率也上去了因为排除了很多主题相近但归属错误的分块。还有一个细节索引要支持增量更新。文档不可能一次性全量灌完新文档进来、旧文档删除索引都要能灵活变动。做知识库维护的时候这个能力比性能更重要否则每次更新都要全量重建越到后面越痛苦。3. 提问进、答案出检索与增强生成的核心机制3.1 Query 处理别让用户口语直接撞文档书面语用户大多习惯用口语提问比如“报销单要怎么填”而文档里写的是“报销单填写规范”。这种表述差距会让向量检索召回率下降。处理办法有很多最简单的是把问题拆成关键词做一趟关键词召回再和向量召回合并进阶做法是 HyDE先让模型根据问题写一个假想的标准答案然后用这个答案去检索。因为“答案形态”和文档形态更接近检索往往更准代价是多一次大模型调用。还有一种思路是 query 改写用大模型把口语问题重写成适合检索的、带关键实体和限定条件的查询语句。这个需要在延迟和效果之间做取舍。实际项目里我在冷启动阶段先用关键词加向量双路召回积累一批 badcase 后再决定要不要上 HyDE 和改写避免动不动就堆大模型调用让链路变得又慢又贵。3.2 相似度怎么算向量建好后相似度计算是下个问题。常用三种余弦相似度、内积、欧氏距离。只要向量做过归一化余弦相似度和内积结果是等价的直接用内积最快。欧氏距离对向量模长敏感适合那些未归一化、模长本身包含信息的情形但一般 RAG 场景下语义相似用余弦更稳。相似度分数还有一个使用禁忌不要设死阈值。不同 embedding 模型的分数分布差异很大同样的“0.7”在模型 A 里可能已经是强相关在模型 B 里只是勉强沾边。所以我不会拍脑袋定“相似度必须大于 0.8”而是先把一批真实问题跑离线评测观察召回的分数分布再决定 TopK 取多少。这个习惯帮我少走了很多弯路。3.3 Rerank为什么不能直接喂 TopK检索返回的 TopK 只是“向量空间里距离最近”不代表语义上最优。向量检索阶段为了速度通常用的是双塔编码问题和文档各自编码交互信息少而重排阶段用交叉编码器把问题和一个候选片段拼起来同时送入模型做精细化打分相关性判断能力明显更强。一个典型的 RAG 系统里为了控制延迟向量检索取 Top50重排后只留 Top3 到 Top5 进入生成环节。增加重排是有成本的交叉编码比向量编码慢几十倍。但在知识密度高、容易混淆的资料库场景里重排带来的准确率提升非常明显。如果对延迟敏感可以做一个开关资料库规模小、主题单一可以省掉重排主题杂、易混重排基本是刚需。我现在的默认策略是只要有重排能力就一定开因为它把“最后那一点不准”堵住了。3.4 提示词构造给模型一份“开卷考试守则”检索质量再高最后模型也是从提示词里拿到材料的。提示词写得不好等于把开卷材料拍在学生脸上但没说清楚“答题只能依据材料”。至少要在系统提示词里写明你只能基于下面的资料回答如果资料里没有直接说不清楚不要编造回答要分点需要时引用资料编号。上下文拼装也有讲究。我会把重排后的片段按相关性从高到低排列用明确的编号分隔开并在最后提醒模型“以上资料可能部分不相关请忽略无关部分”。这个小动作看起来不起眼实测能明显减少模型把不相关内容硬编进答案的现象。再进一步要求模型输出答案时附上引用的片段编号后续人工溯源会轻松很多。这里还要注意 token 预算。检索回来的内容拼进提示词会占据上下文窗口。如果 TopK 取太多提示词太长不仅延迟增加模型还可能被大量低相关文本干扰。我的经验是先给模型 3 到 5 条高质量片段宁缺毋滥。开源大模型和商业 API 都遵循这个规律不是给得越多越好。4. 实战手写一个最小 RAG 系统逐行拆解4.1 环境准备与实验数据为了让你在无外部依赖的情况下跑通我用标准库加 numpy 自己写一个内存向量数据库embedding 和大模型都用占位函数演示。实际部署时把占位函数替换成任意 embedding 服务和模型 API 就可以。实验数据用一段虚构的差旅报销制度某公司差旅报销制度 一、适用对象本公司全体正式员工。 二、报销范围交通费、住宿费、市内交通费。 三、报销标准一线城市每日住宿上限450元其他城市上限350元。 四、申请流程员工出差前需在系统提交出差申请单出差结束后5个工作日内提交报销单附发票和行程单。 五、审批规则金额500元以内由部门负责人审批500至2000元由财务经理审批超过2000元需总经理审批。 六、特殊情况项目紧急出差可由部门主管事后补单补单需要在3日内完成。这段文本短但结构完整足够演示从加载到回答的全流程。真实项目里换成长文档逻辑不变。4.2 第一步文档加载、清洗与分块先看加载和清洗import re def load_document(path: str) - str: 从本地文件读取文本内容。 with open(path, r, encodingutf-8) as f: return f.read()load_document 的逻辑很简单打开文件、按 UTF-8 读入、返回字符串。真实场景里这里可能是 PDF 解析结果或者从接口拉回来的文本但接口形态可以保持统一不管来源最后都返回一个干净的长字符串。def clean_text(text: str) - str: text re.sub(r\s, , text) # 把连续空白替换为单个空格 text re.sub(r[ \t], , text) # 去掉多余空格和制表符 return text.strip() # 去掉首尾空白clean_text 用两步正则把文本里的换行、制表符、连续空格统一压成单个空格。为什么要这样因为分块时如果保留大量换行同一句话很容易被行边界切断而压成连续文本后块切分只按长度走块内语义完整性更好。代价是丢失了段落结构所以真实项目里如果文档有明确层级我会在清洗阶段保留“标题标记”这里为了演示简洁先全部压平。再看分块def chunk_text(text: str, chunk_size: int 200, overlap: int 20) - list[str]: chars list(text) chunks [] step chunk_size - overlap for i in range(0, len(chars), step): piece .join(chars[i:i chunk_size]) if len(piece) chunk_size // 2: chunks.append(piece) if i chunk_size len(chars): break return chunks这段有几个关键点。step 是 chunk_size 减 overlap也就是每次前进的步长。比如 chunk_size 200、overlap 20step 就是 180意味着每块和上一块有 20 个字符的重叠。为什么需要 overlap因为切分点落在哪一截很难控制如果不重叠一条完整句子可能被拦腰切断两边各剩一半检索时哪一半都答不完整。重叠的字符越多句子的完整性越有保障但冗余也越大。循环里先取chars[i:i chunk_size]然后判断len(piece) chunk_size // 2。这个判断是为了过滤尾部不足半个 chunk 的碎片。文本最后一段往往很短如果不足 chunk 的一半直接丢弃避免产生一堆检索价值低的噪声碎片。最后一个if用来在切完最后一块后退出循环防止因为步长小于块长导致的重复切分。4.3 第二步向量化与内存索引下面实现向量化。为了在无外部服务时能跑通我用一个确定性的哈希伪随机向量来模拟 embedding 输出import hashlib import numpy as np def embed_text(text: str) - np.ndarray: 将文本转为向量。真实场景请替换为实际 embedding 服务。 seed int(hashlib.md5(text.encode(utf-8)).hexdigest()[:8], 16) rng np.random.default_rng(seed) vec rng.normal(size16) return vec / np.linalg.norm(vec)这里解释一下为什么用哈希。embedding 的输入是文本正常情况下不同文本应该映射到不同向量而且语义接近的文本向量也应该接近。伪随机向量只能保证“不同文本不同向量”无法表达语义关系所以它只适合演示链路形态不适合真实使用。真实替换时这个函数内部调用你的 embedding 服务输入文本、返回几百维的向量数组即可。最后一行做了 L2 归一化把向量模长变成 1这样后面可以用内积直接当余弦相似度用。索引部分用一个极简的内存字典class MemoryVectorStore: def __init__(self): self.vectors [] self.chunks [] def add(self, vector: np.ndarray, chunk: str): self.vectors.append(vector) self.chunks.append(chunk) def search(self, query_vector: np.ndarray, top_k: int 5): scores [float(np.dot(query_vector, v)) for v in self.vectors] top_indices sorted(range(len(scores)), keylambda i: scores[i], reverseTrue)[:top_k] return [(self.chunks[i], scores[i]) for i in top_indices]MemoryVectorStore 只有三个方法。add 把向量和对应文本追加到列表里search 先算 query 和所有候选向量的内积再用sorted按分数降序取前 top_k 个索引最后返回文本和分数。这个实现是 O(n) 的暴力检索适合几百几千条数据数据量大了以后把这里换成真正的近似最近邻索引就可以接口可以保持不变。4.4 第三步检索后的简单重排向量检索返回的 TopK 可以直接用但我加了一个轻量重排函数用来演示“重排阶段”的思路def rerank(query: str, candidates: list[tuple[str, float]]) - list[str]: 轻量重排按查询关键词在片段中的命中数量排序。 def _score(candidate: str) - int: return sum(1 for token in query if token in candidate) return [c for c, _ in sorted(candidates, keylambda x: _score(x[0]), reverseTrue)]这个实现很朴素统计查询串里的每个字符在候选片段里出现多少次按命中数排序。真实场景中重排会用交叉编码模型但思路是一样的——从向量检索的粗排结果里用更精细的信号挑出真正相关的片段。为什么粗排之后还要挑一轮因为向量空间里的“近邻”不总等于语义上的“正确”尤其在文档主题接近的时候粗排 TopK 里可能混着好几篇没那么相关的文本轻量重排能先把明显不相关的压下去。4.5 第四步提示词构造与生成生成环节用一个占位函数代表大模型调用def generate(prompt: str, sources: list[str]) - str: 真实场景请替换为大模型接口调用。 return 实际部署时返回模型输出\n参考片段 .join(sources[:2])然后是主流程def answer_question(question: str, store: MemoryVectorStore, top_k: int 5, keep_n: int 3) - str: qv embed_text(question) # 查询向量化 candidates store.search(qv, top_ktop_k) # 召回候选 top_segments rerank(question, candidates)[:keep_n] # 重排后保留前 N 条 context \n\n.join(f[{i1}] {seg} for i, seg in enumerate(top_segments)) prompt ( 请只依据下面的资料回答\n context \n\n问题 question \n\n如果资料中没有答案请直接回答‘资料中未找到相关信息’。 ) return generate(prompt, sourcestop_segments)answer_question 是整条链路的收口。qv 得到查询向量store.search 做粗排召回rerank 重排然后[:keep_n]只取前三。这里 keep_n 是关键为什么只取 3 条因为喂给模型的片段越多噪声越多上下文越长生成质量和速度都受影响。拼 context 时给每个片段加编号方便模型引用。prompt 里那句“如果资料中没有答案请直接回答”是控制幻觉的关键一笔它给了模型一个优雅退出的出口比逼着它瞎编强得多。4.6 串联运行与结果观察这里把流程走一遍。假设已经读入文档、清洗、分块、向量化并 add 进 storetext load_document(sales_policy.txt) text clean_text(text) chunks chunk_text(text, chunk_size100, overlap15) store MemoryVectorStore() for c in chunks: store.add(embed_text(c), c) question 公司对差旅报销的审批规则是怎么样的 answer answer_question(question, store) print(answer)输出会分两部分先打印分块列表看看文本被切成了几块每块内容是否完整再打印答案。我建议第一次跑通时把 store 里的 chuncks 全部打印出来检查一遍。如果某块明显语义割裂就调整 chunk_size 和 overlap如果某块还带着页眉页脚就回到清洗环节。调试的顺序一定是“先看分块再看检索最后看生成”这个顺序能帮你快速定位问题到底出在哪一环。5. 实战中高频踩坑与排查手册5.1 检索结果不对先查这里现象可能原因处理办法检索返回空清洗过度、文本被清空打印清洗前后字符数确认内容还在向量维度不匹配不同来源的 embedding 模型混用统一模型统一维度重建索引检索结果全是噪声chunk 太大主题被平均缩小 chunk_size按标题层级切分同一问题结果不稳定向量未归一化统一归一化后再建索引TopK 相关但生成还是答错提示词缺少约束加上“只依据资料回答没有则拒绝回答”我踩过最典型的一个坑是某个文档用文本加载器读进来里面全是不可见字符清洗正则把正文也误杀了结果整个索引文件只有几条记录检索当然什么都找不到。从那以后我每次清洗完都会打印抽样文本确认“人眼看得懂、结构没乱”才继续。5.2 幻觉严重别急着换模型遇到模型胡说八道大部分人第一反应是换更强的模型。但我在项目里观察到的规律是幻觉和检索质量强相关。如果喂给模型的上下文里根本没有正确答案再强的模型也会强行编一段。所以排查顺序应该是先把这次回答对应的检索片段导出来看片段里有没有能支撑答案的内容。如果没有说明链路在检索阶段就断了换模型解决不了。其次是提示词约束。模型是生成式模型天生倾向“流畅地输出”。你在提示词里给了它一段资料但它不一定会严格限制自己的回答范围。写一句“如果资料中没有答案请直接回答‘资料中未找到相关信息’”比任何模型选型都更直接地降低幻觉。再进一步要求答案带引用编号用户能点开原文核对这既是体验设计也是事后审计的手段。5.3 延迟上来了怎么办RAG 在线链路里耗时大头通常不在模型生成而在检索和重排。优化思路有几个层次。第一离线把向量索引建好在线只做查询第二向量检索用近似最近邻索引第三重排只对 Top50 执行不要对全量候选执行第四加缓存同一个问题或近似问题直接命中缓存返回第五把 embedding 调用和检索并发执行。这些做完大部分项目的 P95 延迟都能砍掉一大截。还有一个容易忽略的点把用户问题里的高频停用词去掉比如“请问”“一下”“怎么”可以减少无效检索。不要小看这个操作它在低延迟场景下能显著降低候选数量而且往往提高准确率因为噪音更少了。5.4 从零到一过程中我建议的调试顺序一定要按顺序排查不然你会陷入“改改这里、试试那里”的泥潭。我现在的固定顺序是打印分块结果确认块长、块数和内容完整度。打印检索结果人工判断 Top5 里有没有正确答案。不经过检索直接把正确答案拼进提示词单独测试生成效果。最后再联调全链路观察端到端表现。这个顺序的核心思路是“单点验证”。检索不好就先解决检索生成不行就先单独验证生成。把复杂链路拆成独立的单点问题定位会快很多。很多项目跑不起来不是模型不够强而是中间某个环节“黑盒”了不敢去动它。我做这个项目最大的体会是RAG 的难点不在某个单一环节而在于链路思维。每个阶段的输出你都应该能看见、能检查、能单独评价。最后一个再分享一个小技巧上线前请把被测问题的检索片段全部导出人工扫一遍。如果检索本身质量不行后面怎么调生成都是白费力气。这个动作帮我把线上幻觉投诉直接降了一大半也是整个项目里我认为最值得推荐的一个习惯。
