1. 为什么数据预处理才是 RAG 系统的隐形地基做过 RAG 项目的人大概都有过这种体验模型选了半天向量库调了又调检索策略换了好几轮结果回答质量还是上不去。最后回头一查问题出在最不起眼的地方——文档加载和切分。我见过太多团队把 80% 的精力花在检索和生成上却只给数据预处理留了不到 20% 的时间然后困惑于为什么 hit rate 始终卡在及格线附近。RAG 的本质是先找对再答好。检索增强生成这条链路里LLM 再强如果喂给它的上下文本身就是残缺的、错位的、语义断裂的那它只能基于垃圾给出垃圾。Document Loader 和 Text Splitter 这两个环节决定了进入向量库的知识单元长什么样。单元切得好检索时一找一个准切得烂要么召回一堆无关片段要么把完整答案拦腰截断。这篇内容适合正在搭 RAG 知识库的开发者、做 langchain 入门实践的同学以及那些已经跑通流程但效果不理想的团队。我会把 Document Loader 和 Text Splitter 这两块拆开揉碎讲清楚每个选择背后的逻辑给出可以直接抄的配置也把踩过的坑一并倒出来。全文围绕 LangChain 生态展开但思路对 langchain4j、自研 RAG 流程同样适用。2. Document Loader 深度拆解把各种格式的文档变成统一文本2.1 Document Loader 到底在解决什么问题原始文档的形态五花八门PDF、Word、Markdown、HTML、CSV、数据库记录、甚至 Notion 页面和飞书文档。LLM 和向量模型只认纯文本所以 Loader 的核心任务就一句话——把异构数据源统一成 LangChain 的Document对象。这个对象只有两个关键字段page_content文本内容和metadata元数据。别小看 metadata后面做过滤检索、溯源引用、权限控制全靠它。很多人第一次用PyPDFLoader加载 PDF发现出来的文本顺序全乱了表格变成一堆散落的数字。这不是 LangChain 的锅而是 PDF 本身的存储方式决定的——PDF 记录的是每个字符的坐标位置不是阅读顺序。Loader 只能按坐标去猜猜错了就乱。理解这一点你就知道为什么有些格式必须换工具、有些场景必须做后处理。2.2 常见 Loader 选型对照与实操要点不同格式对应不同 Loader选错了轻则丢内容重则整个知识库报废。下面这张表是我在实际项目里反复验证过的选型参考。文档类型推荐 Loader关键参数适用场景与注意点纯文本/MarkdownTextLoaderencoding、autodetect_encoding最简单注意编码中文务必显式指定 utf-8PDF文本型PyPDFLoaderextract_images逐页加载metadata 带页码适合溯源PDF扫描/复杂版式UnstructuredPDFLoadermode、strategy依赖 unstructured 库能处理表格但慢WordDocx2txtLoader无轻量但丢失样式和表格结构HTMLUnstructuredHTMLLoadermode自动去标签保留段落结构CSVCSVLoadersource_column每行一个 Document适合结构化问答网页WebBaseLoaderbs_kwargs可指定 CSS 选择器只抓正文目录批量DirectoryLoaderglob、loader_cls配合上面任意 Loader 批量处理选型的第一原则是能用结构化 Loader 就别用通用 Loader。比如 CSV 就用CSVLoader别先转成文本再加载那样会丢掉列名这个天然的语义标签。第二原则是metadata 能多带就多带。文件名、页码、章节标题、创建时间这些在检索过滤时都是宝贝。from langchain_community.document_loaders import PyPDFLoader, DirectoryLoader # 单个 PDF保留页码 metadata loader PyPDFLoader(manual.pdf) docs loader.load() print(docs[0].metadata) # {source: manual.pdf, page: 0} # 批量加载整个目录的 PDF dir_loader DirectoryLoader( ./docs, glob**/*.pdf, loader_clsPyPDFLoader, show_progressTrue, use_multithreadingTrue ) all_docs dir_loader.load()注意DirectoryLoader的use_multithreadingTrue在加载大量文件时能显著提速但如果你的 Loader 本身不是线程安全的部分自定义 Loader 会出问题建议先小批量测试。2.3 加载环节最容易踩的三个坑第一个坑是编码问题。中文文档用TextLoader不指定encodingutf-8加载出来全是乱码而且不报错等到检索时才发现向量全是噪声。我的习惯是永远显式写编码并且开启autodetect_encodingTrue兜底。第二个坑是PDF 分页与语义割裂。PyPDFLoader按页切但一个完整的论述可能跨页。如果你后面不再做合并处理检索时可能只召回半句话。解决办法是在切分阶段用较大的 chunk 或者做跨页合并这个后面会讲。第三个坑是metadata 丢失。自定义 Loader 时很多人只填page_content忘了metadata结果检索出来的片段无法溯源用户问这个结论哪来的你答不上来。记住metadata 是 RAG 可解释性的命根子。3. Text Splitter 核心原理切分策略决定检索上限3.1 为什么不能直接把整篇文档塞进向量库有人会想我把整篇文档作为一个 Document 存进去不就行了理论上可以实际上灾难。原因有三第一嵌入模型有 token 上限超长文本会被截断截断的部分等于没存第二就算模型支持长文本把整篇文档压成一个向量语义被平均化了检索时精度极低——你搜第三章的某个细节它可能因为整篇文档的主题而匹配不上第三LLM 的上下文窗口有限检索回来一大坨无关内容既浪费 token 又干扰生成。所以切分的本质是在语义完整性和检索精度之间找平衡。切得太碎语义不完整检索到的片段答非所问切得太大噪声多精度下降。这个平衡点没有标准答案取决于你的文档类型和查询模式。3.2 RecursiveCharacterTextSplitter 的工作机制LangChain 里最常用的就是RecursiveCharacterTextSplitter它的设计思路非常聪明——按优先级依次尝试分隔符直到每块都小于 chunk_size。默认分隔符顺序是[\n\n, \n, , ]也就是先按段落切段落还太大就按行切行还太大就按空格切最后按字符硬切。这个递归的过程保证了尽可能在语义边界处切分。段落边界 行边界 词边界 字符边界优先级从高到低。对于中文默认分隔符不太够用因为中文没有空格分词句子以标点结尾。所以中文场景我一般会自定义分隔符。from langchain.text_splitter import RecursiveCharacterTextSplitter splitter RecursiveCharacterTextSplitter( chunk_size500, chunk_overlap50, separators[\n\n, \n, 。, , , , , , ], length_functionlen, is_separator_regexFalse ) chunks splitter.split_documents(docs)这里几个参数值得掰开说。chunk_size500是字符数不是 token 数中文一个字算一个字符500 字大概对应 300-400 token是个比较稳妥的值。chunk_overlap50是相邻块的重叠字符数目的是防止关键信息正好卡在切分点上被切断——重叠让边界信息在两块里都出现检索时至少有一块能命中。separators里我把中文标点加进去了让切分尽量落在句子边界。3.3 chunk_size 与 chunk_overlap 的取值逻辑这两个参数是 Text Splitter 的灵魂取值没有万能公式但有一套推导逻辑。chunk_size的确定要考虑三个约束嵌入模型的最大输入长度、LLM 上下文窗口、以及你期望的检索粒度。假设你用某个嵌入模型最大支持 512 token那 chunk_size 换算成中文大概 350-400 字比较安全留出余量。如果你期望检索粒度是一个段落能回答一个问题那 chunk_size 就设成典型段落的长度。chunk_overlap一般是 chunk_size 的 10%-20%。太小起不到防切断作用太大则冗余严重、存储和检索成本上升。我实测下来 15% 左右是个甜点区。但有个例外如果你的文档信息密度极高比如法律条文、API 文档重叠比例可以提到 25%因为每个字都可能是关键。文档类型建议 chunk_size建议 overlap理由通用文章/博客500-80050-100段落完整语义自洽技术文档/API300-50050-80信息密度高需精确匹配法律/合同400-600100-150条款不能断重叠要足对话记录200-40030-50单轮对话短切太大会混入无关轮次书籍/长文800-1200100-200上下文依赖强块要大提示这些值是起点不是终点。真正靠谱的做法是准备一批真实查询用不同参数跑检索看 hit rate 和 MRR 指标用数据说话。4. 从加载到切分的完整实操流程4.1 搭建一个可复用的预处理管道把 Loader 和 Splitter 串起来形成一个标准管道是工程化的第一步。我习惯把它写成一个函数输入是文件路径或目录输出是切好的 chunk 列表中间带上完整的 metadata。from langchain_community.document_loaders import PyPDFLoader, TextLoader, DirectoryLoader from langchain.text_splitter import RecursiveCharacterTextSplitter def build_chunks(source_path, is_dirFalse): # 1. 加载 if is_dir: loader DirectoryLoader( source_path, glob**/*.pdf, loader_clsPyPDFLoader, show_progressTrue ) else: loader PyPDFLoader(source_path) docs loader.load() # 2. 清洗去掉多余空白和页眉页脚噪声 for doc in docs: doc.page_content .join(doc.page_content.split()) # 3. 切分 splitter RecursiveCharacterTextSplitter( chunk_size500, chunk_overlap75, separators[\n\n, \n, 。, , , , , , ], length_functionlen ) chunks splitter.split_documents(docs) # 4. 补充 metadata给每个 chunk 加序号方便溯源 for i, chunk in enumerate(chunks): chunk.metadata[chunk_id] i chunk.metadata[chunk_size] len(chunk.page_content) return chunks这段代码里有几个细节值得说。清洗那一步用 .join(text.split())是个小技巧它能一次性把连续空白、换行、制表符都规整成单个空格同时去掉首尾空白。对于 PDF 提取出来的文本这一步能去掉大量无意义的换行噪声。补充chunk_id是为了后续做引用溯源用户看到答案时能定位到具体是第几块。4.2 中文文档的分隔符调优实战中文切分是很多人的痛点。默认分隔符对中文不友好导致切出来的块经常在句子中间断开。我做过一组对比测试用同一篇 8000 字的技术文章分别用默认分隔符和中文优化分隔符切分然后跑 20 个真实查询看召回质量。分隔符配置平均块长句子完整率检索命中率默认[\n\n,\n, ,]48062%65%中文优化加标点49591%84%中文优化 段落优先51094%88%差距非常明显。句子完整率从 62% 提到 94%命中率跟着涨了 20 多个点。原因很简单句子完整的块语义自洽向量表达准确被切断的块语义残缺向量漂移检索自然不准。中文分隔符的顺序也有讲究。我一般用[\n\n, \n, 。, , , , , , ]。段落和换行优先然后是句末标点句号、感叹号、问号再是分号、逗号最后才是空格和字符。这个顺序保证了切分点尽可能落在语义边界上。4.3 特殊场景的切分策略表格数据表格被切碎是灾难。如果文档里有表格建议先用UnstructuredPDFLoader的modeelements把表格单独提取出来作为一个完整的 Document 存不要参与常规切分。或者把表格转成 Markdown 格式用MarkdownHeaderTextSplitter按标题切。代码文档代码块不能按标点切否则函数被拦腰截断。LangChain 提供了Language枚举可以按编程语言的语法结构切分。from langchain.text_splitter import RecursiveCharacterTextSplitter, Language code_splitter RecursiveCharacterTextSplitter.from_language( languageLanguage.PYTHON, chunk_size800, chunk_overlap100 )Markdown 文档用MarkdownHeaderTextSplitter按标题层级切能保留章节结构metadata 里带上标题路径检索时可以做层级过滤。from langchain.text_splitter import MarkdownHeaderTextSplitter headers_to_split_on [ (#, h1), (##, h2), (###, h3), ] md_splitter MarkdownHeaderTextSplitter(headers_to_split_onheaders_to_split_on) md_chunks md_splitter.split_text(markdown_text)这样切出来的每个 chunk 的 metadata 里都有h1、h2、h3字段检索时可以精确到某个章节下的内容对结构化文档的问答效果提升巨大。5. 常见问题与排查技巧实录5.1 检索效果差的排查顺序当 RAG 效果不理想时别急着换模型按这个顺序排查预处理环节先看加载是否完整随机抽几个 Document对比原文看有没有丢内容、乱码、顺序错乱。再看切分是否合理随机抽几个 chunk读一遍看语义是否完整、有没有在句子中间断开。然后看 metadata 是否齐全能不能溯源到具体文件和位置。最后才看检索和生成。我遇到过最典型的一个案例某团队反馈检索命中率只有 40%排查发现他们的 PDF 是双栏排版PyPDFLoader按坐标提取时把左右两栏的文字交错混在一起出来的文本根本读不通。换成UnstructuredPDFLoader并指定strategyhi_res后命中率直接到 80%。5.2 高频问题速查表问题现象可能原因排查与解决加载出来是乱码编码未指定显式设encodingutf-8开autodetect_encodingPDF 文本顺序错乱多栏/复杂版式换UnstructuredPDFLoader用 hi_res 策略检索召回无关内容chunk 太大语义被平均减小 chunk_size提高切分精度答案被截断chunk 太小或切分点不当增大 chunk_size 和 overlap表格内容检索不到表格被切碎表格单独提取转 Markdown 存中文切分在句中断开分隔符不含中文标点自定义 separators 加中文标点无法溯源metadata 缺失加载时保留 source、page切分时加 chunk_id检索慢chunk 数量过多适当增大 chunk_size减少总块数5.3 几个反直觉的实操心得心得一不是所有文档都值得进知识库。我见过有人把整个公司网盘都灌进去结果检索质量一塌糊涂。预处理的第一步其实是筛选——哪些文档是真正会被查询的哪些是噪声。宁可少而精不要多而杂。心得二overlap 不是越大越好。有人觉得重叠多保险设成 chunk_size 的 50%结果存储翻倍、检索时同一内容反复出现、LLM 被重复信息干扰。15% 左右足够特殊场景最多 25%。心得三切分后要做一次体检。写个脚本统计 chunk 长度的分布如果出现大量极短50 字或极长chunk_size的块说明分隔符或参数有问题。健康的分布应该是集中在 chunk_size 附近两端少。import numpy as np lengths [len(c.page_content) for c in chunks] print(f平均长度: {np.mean(lengths):.0f}) print(f中位数: {np.median(lengths):.0f}) print(f最短: {min(lengths)}, 最长: {max(lengths)}) print(f过短块(50): {sum(1 for l in lengths if l 50)})心得四metadata 里的 source 字段要规范。别用绝对路径用相对路径或文档 ID否则换台机器就失效。如果做多租户metadata 里一定要带租户 ID检索时做过滤避免越权。6. 进阶方向让预处理更聪明6.1 语义切分与自适应策略RecursiveCharacterTextSplitter是基于规则的它不知道语义。进阶做法是用嵌入模型计算相邻句子的相似度在相似度骤降的地方切分这叫语义切分。LangChain 里有SemanticChunker可以试。代价是慢因为要对每个句子做嵌入适合文档量不大但对质量要求极高的场景。另一个方向是自适应 chunk_size。不同章节的信息密度不同统一 chunk_size 未必最优。可以根据段落长度动态调整短段落合并长段落细分。6.2 预处理与检索策略的联动切分策略要和检索策略配套设计。如果你用Parent Document Retriever小块检索、大块返回那切分时要同时生成小块和大块两套小块用于精确匹配大块用于提供上下文。如果你用Multi-Vector Retriever那每个 chunk 除了原文向量还要生成摘要向量、假设问题向量等多个表示。from langchain.retrievers import ParentDocumentRetriever from langchain.storage import InMemoryStore from langchain_community.vectorstores import Chroma # 小块用于检索大块用于生成 child_splitter RecursiveCharacterTextSplitter(chunk_size200) parent_splitter RecursiveCharacterTextSplitter(chunk_size1000) retriever ParentDocumentRetriever( vectorstorevectorstore, docstoreInMemoryStore(), child_splitterchild_splitter, parent_splitterparent_splitter ) retriever.add_documents(docs)这种模式下预处理阶段就要把两套切分都做好metadata 里建立父子关联。检索时用小块精准命中返回时用大块提供完整上下文兼顾精度和完整性。6.3 增量更新与版本管理知识库不是一次性的文档会更新。预处理管道要支持增量新文档加载切分入库修改的文档先删旧 chunk 再入新 chunk删除的文档清理对应向量。metadata 里带上文档版本号和更新时间方便做增量判断。这块做不好知识库会越来越脏检索质量随时间衰减。我个人的做法是给每个文档算一个内容哈希存进 metadata。更新时对比哈希变了才重新处理没变就跳过。这样大批量文档更新时能省下大量重复计算。预处理这两个环节看起来简单实际上决定了整个 RAG 系统的天花板。Loader 决定你能拿到什么Splitter 决定你怎么组织。把这两步做扎实后面的检索和生成才有发挥空间。我踩过的坑基本都写在上面了参数和代码可以直接拿去改但记住——没有万能配置只有针对你数据的配置。先跑通再体检最后用真实查询调优这个顺序别乱。