大多数接触过 RAG 的人第一次跑通 demo 时都会觉得挺顺利文档读进来切成碎片塞进向量库问一句就能答一句。但只要你把数据量从几页涨到几百份或者文档类型从干净的纯文本变成混杂的 PDF、网页、表格问题就接踵而至——答非所问、检索出来的片段缺上下文、甚至同一个问题两次回答完全对不上。我在几个项目里反复排查后发现根子大部分不在 embedding 模型也不在向量数据库而是在 LangChain RAG 数据预处理这一环Document Loader 加载得干不干净Text Splitter 切得合不合理直接决定了后续检索质量的上限。这篇文章就把这两个环节摊开讲透把我实际用过的加载器选型、切分参数调优、踩过的坑和一套能直接抄的预处理流程都写出来。1. 先把 RAG 的数据流画对Loader 与 Splitter 到底各管哪一段很多人对 RAG 的理解是从把文档丢进向量库开始的但实际上向量库只是中间站前面的工序才是决定检索效果的关键。一个标准 RAG 流水线可以拆成六步加载原始内容、切分成块、向量化、写入向量库、根据 query 检索、把检索结果交给大模型生成回答。其中前两步就是标题里说的数据预处理它们负责把任意乱七八糟的原始资料变成干净、有边界、适合向量化的文本单元。Document Loader 的职责是格式归一。它要把 PDF、Word、HTML、CSV、JSON、代码仓库这些东西统一读成 LangChain 里的 Document 对象。一个 Document 对象就两个核心部分page_content是真正的文本内容metadata是来源、页码、标题等附加信息。Loader 做得不好最常见的结果就是内容带乱码、表格丢了、HTML 里混了一堆导航菜单文本这些脏数据后面怎么切都救不回来。Text Splitter 的职责是粒度控制。它把可能长达几十页的 Document 切成适合向量化的小块还要尽量保证每块在语义上是完整的。切得太粗一块里塞了多个主题检索时命中一个关键词会带回大量噪声切得太碎一个完整知识点被拦腰截断检索得到的内容缺头少尾大模型就很容易基于残缺信息编造答案。Loader 和 Splitter 的工作顺序也不能乱。先 Loader 后 Splitter 是标准做法因为切分需要基于已经清洗过的完整文本边界进行反过来先切再清洗很难处理跨块的结构信息。我在项目里见过有人图省事直接用字符串的split(\n)来做加载切分结果遇到换行密集的 PDF 就碎成几千个垃圾块检索质量差到没法用。判断预处理是否合格我一般用三个标准第一加载后的文本是否保留了原始文档的核心结构和语义完整性第二切分出的每个 chunk 是否能在不依赖前后块的情况下独立读懂第三chunk 的粒度是否匹配 embedding 模型和大模型的输入窗口。这三点过了后面的向量化和检索才有意义。2. Document Loader 选型PDF、网页、表格、代码仓库各有各的脾气2.1 PDF纯文本提取和扫描件的分水岭PDF 是 RAG 项目里最常见的格式也是坑最多的格式。它不像 Word 或 Markdown 有稳定的文本结构解析质量全看加载器怎么处理。纯文字型 PDF 我优先用PyPDFLoader它不需要额外装系统依赖提取速度也快适合大部分由 Word 或 WPS 导出的文档。如果发现提取结果丢字、乱序可以换PyMuPDFLoader它基于 MuPDF 引擎对排版复杂的 PDF 还原度更高而且速度比 PyPDF2 快不少。遇到带复杂表格的 PDF我会用PDFPlumberLoader它能识别表格线并尽量保留行列结构但代价是慢几十页的文件要等好几秒。处理扫描版 PDF 是另一条路。扫描件本质是图片任何文本型加载器都读不出内容必须先 OCR。LangChain 生态里有RapidOCRLoader底层用 PaddleOCR对中文识别效果比较靠谱不想引入太重的依赖也可以先用PyMuPDFLoader把每页导出成图片再调用 OCR 接口识别最后自己拼成 Document。OCR 不是万能药公式、表格、带水印的文字都会降低准确率所以扫描件在进 RAG 前最好人工抽检几页。2.2 网页和 HTML抓回来只是开始抓网页做知识库最常见的错误是整页 HTML 直接当正文。真实网页里有导航、侧栏、广告、版权声明这些噪声进了向量库检索时很容易被命中然后大模型就拿一段关于我们来回答业务问题。用WebBaseLoader时我会指定bs_kwargs里的解析参数配合 BeautifulSoup 选择器把正文容器提取出来。比如很多技术文档站点的正文都在article或main标签里就按这个范围抓取。如果页面是前端渲染的内容靠 JavaScript 动态加载WebBaseLoader拿到的是空壳这时候要用PlaywrightURLLoader或SeleniumURLLoader先跑一遍浏览器再取内容。注意这类自动化抓取要控制频率和并发设置好超时重试别把对方服务器打挂。2.3 表格、CSV、JSON结构数据的压平技巧CSV 用CSVLoader就够重点是参数分隔符可能不只是逗号还有制表符或分号source_column指定哪一列作为 metadata 的来源方便以后追溯。加载后每一行是一个 Document列名和值会拼成自然语言文本比如name: 张三, age: 30这样做是为了让 embedding 能理解结构而不是把表格当成图片。JSON 用JSONLoader它支持用 jq 语法提取嵌套字段。比如一个接口返回的 JSON我只想取data.items[].title和data.items[].content就在jq_schema里写清楚映射关系。还有一个判断值得记住如果数据本身是严格的二维表且有明确的主外键关系它更适合直接走数据库查询而不是硬塞进 RAG。RAG 擅长的是非结构化文本结构数据硬转文本只会损失查询精度。2.4 代码仓库按文件粒度加载做代码相关的 RAGGitLoader很实用。它能把一个 Git 仓库克隆下来按文件逐个加载成 Documentmetadata 里会带上文件路径。加载时要过滤掉二进制文件、node_modules、.git这些无关目录否则索引会膨胀且检索全是噪声。代码类文档的切分策略和普通文本不同后文会单独说。2.5 加载完先做一次体检不管用哪种 Loader加载完我都建议先做一轮快速体检打印前几个 Document 的page_content前 200 个字符检查有没有乱码、空行异常、控制字符残留确认metadata里是否保留了source、page这类关键字段统计每个 Document 的平均长度判断有没有异常的空文件或超长文件。这一步花不了两分钟但能省掉后面大量排查时间。3. Text Splitter 不只是按字数切参数、边界与中文场景3.1 chunk_size 和 chunk_overlap 到底在调什么Text Splitter 的两个核心参数chunk_size和chunk_overlap很多人只是照抄默认值我觉得有必要把它们的含义说透。chunk_size决定每个块能装多少内容单位通常是字符数或 token 数。它影响两件事一是 embedding 的语义粒度块越大单块的语义越丰富但越模糊块越小单块语义越聚焦但越容易残缺。二是大模型生成时的上下文检索回来的块直接拼进 prompt块太大很快撑满上下文窗口块太小又要好几块才能凑够信息。chunk_overlap是相邻块之间的重叠部分目的是保留被切开内容的上下文衔接。比如一个长段落被切成两块第一块结尾已经提到了某个结论第二块开头是对结论的解释两块之间加一点重叠检索到第二块时就能带上第一块结尾的关键词避免上下文断裂。实际调参时我遵循一个经验先确定业务场景能接受的最大 token 数再反推 chunk_size。如果你的生成模型上下文是 8k检索要拼 5 个块那单块最好控制在 800 token 以内如果只需要拼 2 个块单块可以放到 1500 token。overlap 一般是 chunk_size 的 10%~20%太小起不到衔接作用太大又会导致重复内容过多、索引膨胀。3.2 四类 Splitter 的适用场景RecursiveCharacterTextSplitter是默认选择也是我用得最多的。它的切分逻辑是按一组分隔符递归降级先尝试按\n\n切切出来的块还太大再按\n切再不行就按句号、逗号、空格最后按字符硬切。这套逻辑保证了块尽可能落在语义边界上适合绝大多数散文、说明文类的技术文档。CharacterTextSplitter只按一个固定分隔符切适合结构化很强的文本比如日志文件、每行一条的数据记录。它的优点是可控缺点是遇到分隔符稀疏的长文本会直接暴力截断语义词会被从中间切开所以用之前要确认输入的格式。TokenTextSplitter按 token 边界切适合需要精确控制大模型输入窗口的场景。但 token 边界往往不在句子上切出来的块会语义破碎我不太建议单独用它更好的做法是先用RecursiveCharacterTextSplitter按语义切再检查每个块的 token 数是否超限。还有一类专门为结构化文档设计的MarkdownHeaderTextSplitter和HTMLHeaderTextSplitter。它们会保留标题层级比如把一个 Markdown 文档按##、###切块并把标题信息写进 metadata。这个对长文档特别有用检索到某个小节时可以知道它属于哪个大章节回答时能带上章节上下文大幅减少张冠李戴。LangChain 还提供了基于 embedding 相似度找断点的语义切分器SemanticChunker它通过计算相邻句子之间的向量相似度在相似度骤降的地方切块。效果在内容主题分明的文档上确实好但每一块都要调 embedding 接口成本比较高小项目可以先不碰。3.3 中文场景容易踩的三个坑中文 RAG 和英文 RAG 在切分上的差异经常被忽视。第一个是 token 估算不同。一个英文字符大约对应 0.25 个 token而一个汉字字符通常对应 0.6~1 个 token具体取决于分词器。如果你用英文场景习惯的chunk_size1000在中文文档上实际 token 可能多出一倍容易撑爆上下文。我的做法是中文场景chunk_size从 300~500 起步再根据 embedding 模型实际支持的最大输入调整。第二个是标点边界。英文按空格和句号切通常没问题中文的分隔符还要考虑顿号、分号、引号。在RecursiveCharacterTextSplitter的分隔符列表里我会把。、、放到\n后面排在空格前面这样中文长句不会被硬切在词语中间。第三个是代码和文档混合的情况。一份 API 文档里既有大段论述又有代码示例如果按纯文本切代码块很容易被拦腰砍断。处理这类内容我一般先用MarkdownHeaderTextSplitter保结构再对代码块单独设更大的chunk_size保证一个函数体尽量完整落在一个块里。4. 一次检索质量事故复盘chunk 太碎导致答案张冠李戴4.1 现象参数问题答成了另一个参数有次给一套网络设备用户手册做知识库文档总量不大但排版很密大量参数说明集中在一个大表格里。上线后测试时问连接超时默认值是多少系统返回的是会话保持最大连接数的内容两个词里都带连接但根本不是同一个东西。这种错误在检索结果里非常典型字面相似度高、语义完全错位。4.2 排查链路从检索结果倒查切分我排查这类问题有一套固定链路先不怀疑 embedding 模型而是从结果倒推数据预处理。第一步把 query 对应的检索结果直接打出来看向量库返回了哪几个 chunk每个 chunk 的完整内容是什么。这一步能立刻确认到底是没检索到还是检索到错的内容。第二步查看这几个 chunk 在原始文档中的位置。当时我查到的那个错误 chunk内容是一个表格行看起来是从一排参数定义里切出来的。问题就清楚了原始表格里参数名—默认值—说明是一行完整体切分时按行切却把行头和行尾拆到不同块导致检索到的块里只剩连接这个关键词和一部分说明真正的默认值在相邻块里。第三步检查切分参数。当时的配置是chunk_size200、chunk_overlap0。200 字符对中文来说最多容纳三五个短句表格行一长就被切成两半overlap 为 0 又让前后块彻底失去衔接。embedding 模型看到一个残缺块只能靠仅存的连接字样去找相似文本匹配到同样含连接的其他参数行也就不奇怪了。4.3 修复调整参数 换用 ParentDocumentRetriever第一轮修复很简单把chunk_size提到 500 字符chunk_overlap设为 60让表格行有更大概率完整落进同一块。效果有改善但表格行特别长时还是会断。真正解决这个问题的是换检索策略不再让检索结果直接暴露小块而是采用小块检索、大块返回的 ParentDocumentRetriever。做法是用较小的 chunk 做向量索引提高检索命中精度检索到小块后通过 docstore 找到它所属的更大的父块把父块内容返回给大模型。小块负责定位父块负责提供完整上下文。from langchain.retrievers import ParentDocumentRetriever from langchain_text_splitters import RecursiveCharacterTextSplitter from langchain.storage import InMemoryStore child_splitter RecursiveCharacterTextSplitter( chunk_size300, chunk_overlap40, separators[\n\n, \n, 。, , , , ] ) parent_splitter RecursiveCharacterTextSplitter( chunk_size1500, chunk_overlap100, separators[\n\n, \n, 。, , , , ] ) retriever ParentDocumentRetriever( vectorstorevectorstore, docstoreInMemoryStore(), child_splitterchild_splitter, parent_splitterparent_splitter, ) retriever.add_documents(docs)改完之后重新测试同一个 query命中块不再是孤立的表格行而是带完整参数名、默认值、说明的一整段内容回答正确。4.4 从这次事故里沉淀下来的三条经验第一检索质量问题先查 chunk再查 embedding顺序不能反。第二任何切分参数都要用真实数据长尾验证只看前几页没问题不代表几百页没问题。第三如果文档里有大量表格、代码块、列表等强结构内容单靠调 overlap 是打不赢的ParentDocumentRetriever 这种粗细结合的思路才是正路。5. 生产环境里那些文档不会写的事元数据、去重、失败续跑5.1 元数据要贯穿始终很多教程只讲加载和切分不讲 metadata但 metadata 在真实项目里几乎和正文一样重要。Loader 阶段我们已经得到了source文件路径或 URL、page页码等原始信息切分时这些信息会默认传递到每个子块上。我强烈建议在写向量库之前把最终要用的 metadata 字段列一个清单来源、标题、章节、文件 hash、更新时间。没有这些字段你以后会发现一个问题检索到了内容但根本不知道它来自哪份文档引用和溯源全部无从谈起。5.2 去重防止同一个内容被索引 N 遍RAG 项目做增量更新时最隐蔽的问题就是重复。同一个文件被重复加载、同一份文档在不同目录里存在多个版本都会让向量库中出现大量语义几乎相同的 chunk检索时它们会霸占 top-k 结果挤掉真正需要的其他内容。去重方案有两种粗粒度用文件级 hash加载前先算整个文件的 SHA-256如果库里已有相同 hash 就跳过细粒度用内容级去重对每个 chunk 做 hash只插入新 chunk。文件 hash 适合防止整份文件重复chunk hash 适合防止部分内容重复我建议两层都做。5.3 失败处理单文件出错不能拖垮整个流水线生产数据源的格式总是超出预期某个 PDF 加密了、某个 CSV 编码不是 UTF-8、某个网页超时了。如果 pipeline 碰到一个文件报错就整体中断几百份数据的任务很难跑完。我一般会在加载循环里做 try/except把失败的文件记录到日志列表跳过继续处理后续文件跑完再统一看错误报告。这样虽然会暂时漏掉部分文件但至少不会一次坏文件毁掉整次索引。5.4 增量更新用 hash 判断该更新谁处理增量数据时核心问题是怎么知道这个文件有没有变过。我用的是文件 hash 更新时间双重判断读文件时算 hash如果 hash 没变就跳过变了就删除旧 chunk 再写入新 chunk。删除旧 chunk 需要 docstore 里有稳定的文档 ID我习惯用文件路径 内容前 256 字符算一个 SHA-1 作为 doc_id这样同一个文件的不同版本能稳定对应到同一组 ID。import hashlib def doc_id(source: str, content: str) - str: return hashlib.sha1((source content[:256]).encode(utf-8)).hexdigest()5.5 性能与日志让每步耗时可见数据量大了以后预处理费的时间会显著增长尤其 OCR 和 embedding 两步。我会给每个加载阶段加进度条和耗时统计方便定位瓶颈。日志方面除了记录错误还要记录每个文件产出了多少 chunk、平均 chunk 长度这些指标能帮你发现有问题的文件——比如某个 PDF 解析后 chunk 数异常少大概率是加载时内容丢失了。6. 我目前最常使用的预处理配置与后续调优方向6.1 一套能直接复制的库函数下面这个函数是我做通用文档知识库时常用的预处理管线把加载、清洗、切分、去重、生成 doc_id 串在一起。参数固定成一组初始值实际项目再按数据特点微调。import hashlib from langchain_community.document_loaders import PyPDFLoader from langchain_text_splitters import RecursiveCharacterTextSplitter def preprocess_pdf(path: str): loader PyPDFLoader(path) docs loader.load() splitter RecursiveCharacterTextSplitter( chunk_size500, chunk_overlap60, separators[\n\n, \n, 。, , , , ], ) chunks splitter.split_documents(docs) for i, chunk in enumerate(chunks): uid hashlib.sha1( (path chunk.page_content).encode(utf-8) ).hexdigest() chunk.metadata[doc_id] uid chunk.metadata[chunk_index] i return chunks这套配置的适用条件是通用技术文档、中文为主、表格占比不高。如果你的文档是长访谈稿或法律条文chunk_size 可以再大一些如果是 API 参数手册建议配合 ParentDocumentRetriever 使用。6.2 调优一定要有评估集不要靠感觉回答变好了来调参。我建议从真实业务问题里收集 50~100 条 query每条标注出答案应该在哪个文档的哪个位置。然后跑批量检索统计两个指标hit ratetop-5 内是否包含正确答案所在 chunk和 MRR正确答案排在第几取倒数用这两个指标对比不同chunk_size、overlap和切分策略的效果。比如同样 100 条 querychunk_size 从 300 调到 600 时 hit rate 从 82% 涨到 90%那就是有效提升反过来降到 75%就说明切太粗了。6.3 长期维护的几点建议我现在做 RAG 项目会把数据预处理配置当代码一样管固定在一个配置文件里改动要记录原因。每次更新数据源除了跑索引还会跑一遍同样的评估集看指标有没有回退。数据源新增类型时先小批量试跑加载和切分人工检查 20~30 个 chunk 的质量确认没问题再全量执行。我个人最大的体会是RAG 系统的检索效果不是靠调一个模型就能突飞猛进的数据预处理的每个细节——加载器选择、分隔符顺序、chunk 粒度、元数据完整度——都是在默默决定回答质量的上限。把这层打扎实后面调 embedding、调 prompt 才真正有意义。