1. RAG 数据预处理的底层逻辑与整体设计1.1 为什么数据预处理是 RAG 系统的“隐形地基”很多人做 RAG 项目第一反应是去调 Embedding 模型、换向量数据库、折腾 Rerank 策略结果折腾一圈发现检索命中率还是上不去。我踩过这个坑之后才意识到RAG 系统的上限在数据进入向量库之前就已经被决定了。你喂给模型什么质量的文本块它就还你什么质量的检索结果这个道理跟做饭一样——食材没洗干净、切得乱七八糟后面火候掌握得再好也白搭。LangChain 把 RAG 的数据预处理拆成了两个核心环节Document Loader负责把各种格式的原始数据加载成统一的Document对象Text Splitter负责把这些长文档切成语义相对完整的小块。这两个环节看起来简单但实际项目里 80% 的检索效果问题都出在这里。我见过太多人直接用默认参数一把梭结果切出来的块要么把一句话拦腰截断要么一个块里塞了三四个不相关的主题检索的时候自然抓不住重点。这篇文章面向的是正在用 LangChain 搭建 RAG 知识库的开发者不管你是刚入门想搞清楚RecursiveCharacterTextSplitter到底怎么配参数还是已经跑通了流程但检索效果不理想想优化都能从这里找到可以直接抄作业的方案。我会把 Document Loader 的选型逻辑、Text Splitter 的参数计算、不同文档类型的切分策略以及实际项目中遇到的坑全部掰开揉碎讲清楚。1.2 Document Loader 与 Text Splitter 的职责边界先把这个流程的骨架理清楚。一个典型的 LangChain RAG 数据预处理管线是这样的from langchain_community.document_loaders import PyPDFLoader from langchain.text_splitter import RecursiveCharacterTextSplitter # 第一步加载 loader PyPDFLoader(技术文档.pdf) docs loader.load() # 第二步切分 splitter RecursiveCharacterTextSplitter( chunk_size500, chunk_overlap50, separators[\n\n, \n, 。, , , , , , ] ) chunks splitter.split_documents(docs)Document对象是 LangChain 里的基本数据单元它有两个核心字段page_content存文本内容metadata存元数据来源文件、页码、标题等。metadata 在后续检索过滤和溯源展示时非常关键但很多人在加载阶段就把 metadata 丢了后面想按来源筛选都没办法。Document Loader 的职责是“把异构数据变成同构 Document”Text Splitter 的职责是“把长 Document 变成适合检索的短块”。这两个环节的衔接点在于Loader 产出的 Document 质量直接决定了 Splitter 能切出什么效果。比如 PDF 加载时如果表格和正文混在一起没有正确解析Splitter 再厉害也切不出干净的语义块。1.3 方案选型的核心考量为什么不用固定长度切分新手最容易犯的错误就是用CharacterTextSplitter按固定字符数硬切。我早期也这么干过结果切出来的块经常是“前半句在讲 A 概念后半句突然跳到 B 概念”因为固定长度切分完全不考虑语义边界。LangChain 提供的RecursiveCharacterTextSplitter之所以成为默认推荐核心在于它的递归分隔符策略它维护一个分隔符优先级列表先尝试用最高优先级的分隔符比如段落标记\n\n切分如果切出来的块还是超过chunk_size就降级用下一级分隔符比如换行\n继续切直到块大小符合要求或者分隔符用尽。这个策略的巧妙之处在于它优先在语义边界处切分只有在不得已时才在句子内部切。对于中文文档你需要把中文标点加入分隔符列表否则默认的英文分隔符对中文几乎不起作用会导致大量块被硬切。注意中文场景下如果不自定义 separatorsRecursiveCharacterTextSplitter 会退化成按字符硬切效果和 CharacterTextSplitter 没区别。这是我在实际项目里验证过的很多人忽略了这一点。2. Document Loader 核心细节与实操要点2.1 常见文档格式的加载器选型对照LangChain 社区提供了上百种 Document Loader但实际项目里常用的就那么十几种。我整理了一份选型对照表覆盖了绝大多数场景文档格式推荐 Loader依赖库适用场景注意事项PDF文本型PyPDFLoaderpypdf电子版 PDF、报告扫描件无法提取文字PDF扫描型UnstructuredPDFLoaderunstructured扫描件、图片型 PDF需要 OCR 支持速度慢WordDocx2txtLoaderdocx2txt.docx 文档不支持 .doc 老格式MarkdownUnstructuredMarkdownLoaderunstructured技术文档、笔记会保留标题层级信息HTMLUnstructuredHTMLLoaderunstructured网页存档需要处理噪声标签CSVCSVLoader内置结构化表格每行变成一个 DocumentJSONJSONLoaderjq结构化数据需要指定 jq schema纯文本TextLoader内置.txt 文件需手动指定编码选型的核心原则是优先用能保留 metadata 和结构信息的 Loader。比如 Markdown 文档用UnstructuredMarkdownLoader比TextLoader好因为前者会把标题层级、代码块等结构信息保留在 metadata 里后续切分和检索时可以利用这些信息做过滤或加权。2.2 PDF 加载的深坑与解决方案PDF 是 RAG 项目里最常见的文档格式也是最容易出问题的。我用PyPDFLoader踩过的坑包括坑一中文乱码。某些 PDF 的字体编码特殊pypdf提取出来是乱码。解决方案是换用pdfplumber作为底层引擎from langchain_community.document_loaders import PDFPlumberLoader loader PDFPlumberLoader(中文文档.pdf) docs loader.load()pdfplumber对中文 PDF 的兼容性明显更好而且能提取表格结构。代价是速度比pypdf慢一些但对于中小规模知识库完全可以接受。坑二页眉页脚污染。很多 PDF 每页都有页眉页脚加载后这些内容会混入正文切分后变成噪声块。我的处理方式是在加载后做一次清洗import re def clean_document(doc): # 移除常见的页眉页脚模式 text doc.page_content text re.sub(r第\s*\d\s*页, , text) text re.sub(r^\s*\d\s*$, , text, flagsre.MULTILINE) doc.page_content text.strip() return doc docs [clean_document(d) for d in docs]坑三metadata 丢失。PyPDFLoader默认会把页码存在 metadata 里但如果你用loader.load()之后又做了自定义处理很容易把 metadata 弄丢。建议在加载后立刻检查 metadata 字段确认source和page都在。2.3 批量加载与目录遍历的工程化写法实际项目里不可能一个一个文件手动加载需要写一个通用的目录遍历加载器。我的做法是按文件扩展名分发到不同的 Loaderfrom pathlib import Path from langchain_community.document_loaders import ( PyPDFLoader, Docx2txtLoader, UnstructuredMarkdownLoader, TextLoader ) LOADER_MAP { .pdf: PyPDFLoader, .docx: Docx2txtLoader, .md: UnstructuredMarkdownLoader, .txt: TextLoader, } def load_directory(dir_path: str): all_docs [] for file_path in Path(dir_path).rglob(*): if file_path.suffix.lower() in LOADER_MAP: loader_cls LOADER_MAP[file_path.suffix.lower()] try: loader loader_cls(str(file_path)) docs loader.load() # 补充文件级 metadata for d in docs: d.metadata[file_name] file_path.name d.metadata[file_type] file_path.suffix.lower() all_docs.extend(docs) except Exception as e: print(f加载失败 {file_path}: {e}) return all_docs这段代码有几个工程化细节值得注意用rglob而不是glob可以递归遍历子目录每个文件加载失败时捕获异常继续处理避免一个坏文件导致整个流程中断补充 file_name 和 file_type 到 metadata方便后续按文件类型过滤检索。实操心得加载阶段一定要加日志和异常捕获。我遇到过一个大目录里混了一个加密 PDF没有异常处理的话整个加载流程直接崩掉排查了半天才发现是那个文件的问题。3. Text Splitter 参数计算与切分策略3.1 chunk_size 与 chunk_overlap 的计算逻辑chunk_size和chunk_overlap是 Text Splitter 最核心的两个参数但很多人是拍脑袋设的。我来说说我的计算逻辑。chunk_size 的确定要考虑三个因素Embedding 模型的最大输入长度、检索时的上下文窗口、以及语义完整性。以常用的text-embedding-ada-002为例最大输入是 8191 token但实际切分时远不需要这么大。我的经验值是300-800 字符中文或500-1500 字符英文。为什么是这个范围因为检索时你通常要返回 top-3 到 top-5 个块给 LLM如果每个块太大几个块加起来就超出了 LLM 的上下文窗口如果太小单个块的信息量不足以回答问题。300-800 字符大约对应 150-400 个中文 token这个粒度既能保证语义相对完整又不会占用太多上下文。chunk_overlap 的作用是防止语义在边界处丢失。比如一句话正好被切在两个块之间如果没有 overlap两个块都读不懂这句话。overlap 的典型值是chunk_size的 10%-20%。我一般设 50-100 字符。chunk_size 500 chunk_overlap int(chunk_size * 0.15) # 75 字符这里有个容易忽略的点overlap 不能太大。如果 overlap 接近 chunk_size 的一半会导致大量重复内容进入向量库检索时返回一堆相似块浪费上下文窗口。我试过 overlap200 配 chunk_size500结果检索出来的 top-5 块有一半内容是重复的。3.2 RecursiveCharacterTextSplitter 的分隔符优先级设计这是整个切分环节最关键的配置。默认的 separators 是[\n\n, \n, , ]这套配置对英文文档还行对中文文档基本废掉。我的中文场景配置是这样的separators [ \n\n, # 段落边界优先级最高 \n, # 行边界 。, # 中文句号 , # 中文感叹号 , # 中文问号 , # 中文分号 , # 中文逗号 , # 空格 , # 最后兜底按字符切 ]这个列表的顺序就是优先级。Splitter 会先用\n\n切如果某个片段还是超过 chunk_size就用\n继续切以此类推。把中文标点放在空格之前很重要因为中文文本里空格很少如果空格优先级高于中文标点会导致大量按空格切分的情况而中文句子内部通常没有空格最终还是会退化成按字符切。对于代码文档分隔符需要另外设计code_separators [ \nclass , # 类定义 \ndef , # 函数定义 \n\n, # 空行 \n, # 换行 , # 空格 , # 字符 ]这样能保证一个类或一个函数尽量不被切断检索代码时返回的块是完整的逻辑单元。3.3 不同文档类型的切分策略差异技术文档这类文档通常有清晰的标题层级我建议用MarkdownHeaderTextSplitter先按标题切再用RecursiveCharacterTextSplitter做二次切分。这样每个块的 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_content) # 二次切分 text_splitter RecursiveCharacterTextSplitter( chunk_size500, chunk_overlap75, separators[\n\n, \n, 。, , , , , , ] ) final_chunks text_splitter.split_documents(md_chunks)对话记录客服对话、会议记录这类数据按轮次切分比按字符切分更合理。可以自定义一个 Splitter以“说话人”作为分隔符。表格数据CSV 加载后每行是一个 Document通常不需要再切分。但如果某行内容特别长还是需要处理。我的做法是给 CSV 行设一个较大的 chunk_size比如 1000因为表格行的语义完整性比长度更重要。4. 实操全流程与关键环节实现4.1 从零搭建一个可复用的预处理管线我把整个预处理流程封装成了一个类方便在不同项目里复用from langchain_community.document_loaders import PyPDFLoader, Docx2txtLoader from langchain.text_splitter import RecursiveCharacterTextSplitter from langchain.schema import Document from pathlib import Path import re class RAGPreprocessor: def __init__(self, chunk_size500, chunk_overlap75): self.chunk_size chunk_size self.chunk_overlap chunk_overlap self.splitter RecursiveCharacterTextSplitter( chunk_sizechunk_size, chunk_overlapchunk_overlap, separators[\n\n, \n, 。, , , , , , ], length_functionlen, ) def load_file(self, file_path: str) - list[Document]: suffix Path(file_path).suffix.lower() if suffix .pdf: loader PyPDFLoader(file_path) elif suffix .docx: loader Docx2txtLoader(file_path) else: raise ValueError(f不支持的文件类型: {suffix}) docs loader.load() for d in docs: d.metadata[file_name] Path(file_path).name return docs def clean_text(self, text: str) - str: text re.sub(r\n{3,}, \n\n, text) # 合并多余空行 text re.sub(r[ \t]{2,}, , text) # 合并多余空格 return text.strip() def process(self, file_paths: list[str]) - list[Document]: all_chunks [] for fp in file_paths: docs self.load_file(fp) for d in docs: d.page_content self.clean_text(d.page_content) chunks self.splitter.split_documents(docs) # 过滤掉过短的块 chunks [c for c in chunks if len(c.page_content) 50] all_chunks.extend(chunks) return all_chunks这个类里有两个容易被忽略但很重要的细节清洗阶段合并多余空行和空格能显著减少噪声块过滤掉长度小于 50 字符的块这些块通常是页眉页脚残留或分隔符产生的碎片留在向量库里只会干扰检索。4.2 切分效果的验证与调优方法切完之后怎么知道效果好不好我的做法是抽样检查 检索验证两步走。抽样检查就是随机抽 10-20 个块人工看它们的语义完整性。重点看三类问题有没有块以半句话开头或结尾、有没有块包含多个不相关的主题、有没有块几乎全是空白或符号。检索验证是更客观的方法准备 10-20 个典型问题用切好的块建一个临时向量库跑一遍检索看 top-3 结果里有没有能回答问题的块。如果命中率低于 70%说明切分策略需要调整。我整理了一份调优对照表问题现象可能原因调整方向检索结果语义不完整chunk_size 太小增大到 600-800检索结果包含多个主题chunk_size 太大减小到 300-400边界处信息丢失chunk_overlap 太小增大到 chunk_size 的 20%检索结果大量重复chunk_overlap 太大减小到 chunk_size 的 10%中文句子被硬切separators 未配置中文标点加入中文标点代码块被切断separators 未适配代码用代码专用分隔符4.3 metadata 的保留与增强metadata 在 RAG 里的作用被严重低估了。除了基本的来源信息我还会在预处理阶段补充一些增强字段def enrich_metadata(chunks: list[Document]) - list[Document]: for i, chunk in enumerate(chunks): chunk.metadata[chunk_index] i chunk.metadata[char_count] len(chunk.page_content) # 提取块内第一个句子作为摘要 first_sentence chunk.page_content.split(。)[0][:50] chunk.metadata[summary] first_sentence return chunkschunk_index在需要按顺序拼接相邻块时很有用char_count可以用于检索后的过滤比如过滤掉过短的块summary可以在展示检索结果时作为预览。更进一步如果你的文档有明确的章节结构可以把章节标题也写入 metadatachunk.metadata[section] 第三章 数据预处理这样检索时可以按章节过滤比如用户问“第三章讲了什么”你可以直接过滤section包含“第三章”的块大幅提升检索精度。5. 常见问题与排查技巧实录5.1 加载阶段的典型故障排查问题一PDF 加载后内容为空。最常见的原因是 PDF 是扫描件文字以图片形式存在。排查方法是打开 PDF 试着选中文字如果选不中就是扫描件。解决方案是换用支持 OCR 的 Loader或者先用 OCR 工具把 PDF 转成文本再加载。问题二加载速度极慢。如果目录里有几百个 PDFPyPDFLoader逐个加载会很慢。我的优化方案是用多线程并行加载from concurrent.futures import ThreadPoolExecutor def parallel_load(file_paths, max_workers4): with ThreadPoolExecutor(max_workersmax_workers) as executor: results list(executor.map(load_single_file, file_paths)) return [doc for docs in results for doc in docs]注意max_workers不要设太大4-8 就够了太多反而会因为 IO 竞争变慢。问题三编码错误。文本文件加载时如果编码不是 UTF-8会报UnicodeDecodeError。解决方案是显式指定编码loader TextLoader(file.txt, encodinggbk)5.2 切分阶段的隐蔽陷阱陷阱一分隔符顺序错误导致切分粒度失控。我见过有人把空字符串放在分隔符列表的第一位结果 Splitter 直接按字符硬切所有语义边界都被忽略。空字符串必须放在最后一位它是兜底选项不是优先选项。陷阱二chunk_overlap 大于 chunk_size。这会导致无限循环或异常。LangChain 内部会做检查但有些自定义 Splitter 不一定。务必保证 overlap chunk_size我一般控制在 10%-20%。陷阱三中文标点全角和半角混用。中文文档里可能同时存在“。”和“.”、“”和“,”。如果 separators 里只配了全角标点半角标点处就不会被切分。我的做法是两种都加上separators [\n\n, \n, 。, ., , !, , ?, , ;, , ,, , ]陷阱四表格和正文混切。PDF 里的表格提取出来通常是一堆用空格或制表符分隔的文本和正文混在一起切分后表格数据会变成难以理解的碎片。我的处理方式是在加载阶段识别表格区域单独处理或者在切分后过滤掉包含大量制表符的块。5.3 检索效果不佳时的排查清单当 RAG 检索效果不理想时按这个顺序排查先看切分质量随机抽 20 个块人工判断语义完整性。如果块本身就不完整后面怎么调都没用。再看 metadata确认每个块都有 source 和 page 信息否则无法溯源。然后看 chunk_size用 3-5 个典型问题测试如果 top-3 里没有相关块尝试调整 chunk_size。最后看 overlap如果相关块存在但信息不完整增大 overlap。我整理了一份速查表症状排查方向快速验证方法检索不到相关块chunk_size 过大或过小用不同 size 建临时库对比检索到相关块但答非所问块内主题混杂检查块是否包含多个主题答案缺少细节overlap 不足增大 overlap 重新测试检索结果重复overlap 过大减小 overlap中文检索效果差separators 未适配检查分隔符列表特定文档检索差该文档加载质量差单独检查该文档的块避坑技巧每次调整参数后只改一个变量其他保持不变这样才能定位到是哪个参数影响了效果。我早期同时改 chunk_size 和 overlap结果效果变好了也不知道是哪个起了作用。5.4 性能优化的实战经验当文档量达到几千个文件时预处理会成为瓶颈。我的优化经验批量处理而非逐个处理。把文件列表分批每批 50-100 个处理完一批写入向量库一批避免内存爆掉。缓存加载结果。如果同一批文档需要反复调参测试把加载后的 Document 用 pickle 存到本地下次直接读缓存省去重复加载的时间。import pickle def cache_docs(docs, cache_path): with open(cache_path, wb) as f: pickle.dump(docs, f) def load_cached_docs(cache_path): with open(cache_path, rb) as f: return pickle.load(f)切分阶段用多进程。Text Splitter 是 CPU 密集型操作用multiprocessing可以显著加速。但要注意 Document 对象需要可序列化LangChain 的 Document 默认支持 pickle所以没问题。我在一个 3000 个 PDF 的项目里用上述优化把预处理时间从 40 分钟压到了 8 分钟左右。核心就是并行加载 缓存 分批处理这三板斧。6. 进阶话题从预处理角度突破 RAG 瓶颈6.1 语义切分的探索与取舍RecursiveCharacterTextSplitter是基于规则的切分它的局限在于不理解语义。比如一段话里前半部分讲 A后半部分讲 B但中间没有明显的标点边界规则切分就会把 A 和 B 切在同一个块里。语义切分Semantic Chunking的思路是用 Embedding 计算相邻句子的相似度在相似度骤降的地方切分。LangChain 提供了SemanticChunkerfrom langchain_experimental.text_splitter import SemanticChunker from langchain_openai import OpenAIEmbeddings semantic_splitter SemanticChunker( OpenAIEmbeddings(), breakpoint_threshold_typepercentile, breakpoint_threshold_amount95 )但语义切分有两个实际问题速度慢每个句子都要算 Embedding和块大小不可控可能切出很长的块。我的建议是对质量要求极高的核心知识库可以用但对大多数场景优化好的 RecursiveCharacterTextSplitter 已经够用了。投入产出比要算清楚。6.2 父子块策略与多向量检索的预处理配合父子块Parent-Child Chunking是解决“检索粒度”和“上下文完整性”矛盾的一个巧妙方案用小块做检索返回大块做上下文。预处理阶段需要同时生成小块和大块并建立映射关系。# 先切大块 parent_splitter RecursiveCharacterTextSplitter(chunk_size2000, chunk_overlap200) parents parent_splitter.split_documents(docs) # 每个大块再切小块 child_splitter RecursiveCharacterTextSplitter(chunk_size400, chunk_overlap50) for i, parent in enumerate(parents): children child_splitter.split_documents([parent]) for child in children: child.metadata[parent_id] i检索时用 child 块匹配返回对应的 parent 块给 LLM。这样既保证了检索精度小块语义集中又保证了上下文完整大块信息充足。这个策略在 LangChain 里对应ParentDocumentRetriever预处理阶段的核心工作就是正确建立 parent-child 映射。6.3 预处理质量对 Agentic RAG 的影响现在 Agentic RAG 很火Agent 会自主决定检索什么、检索几次、如何组合检索结果。但很多人忽略了一点Agentic RAG 对预处理质量的要求比普通 RAG 更高。因为 Agent 会做多轮检索和推理如果底层块质量差Agent 的每一轮检索都会引入噪声错误会累积放大。具体来说Agentic RAG 场景下预处理需要额外注意metadata 要更丰富Agent 需要根据 metadata 做过滤决策、块要更干净噪声块会误导 Agent 的判断、块之间的边界要更清晰Agent 需要准确判断哪些块是相关的。我在实际项目里的体会是把预处理做好之后Agentic RAG 的效果提升比换更贵的 LLM 还明显。最后分享一个我在多个项目里验证过的经验预处理阶段多花 1 小时调参后面能省 10 小时的检索调优。很多人急着跑通流程就往下走结果在检索环节反复折腾回头发现根因在预处理。把 Document Loader 的 metadata 保留好、把 Text Splitter 的分隔符配对、把 chunk_size 和 overlap 算清楚这三件事做到位RAG 系统的地基就稳了。
LangChain RAG数据预处理实战：Document Loader与Text Splitter参数调优指南
1. RAG 数据预处理的底层逻辑与整体设计1.1 为什么数据预处理是 RAG 系统的“隐形地基”很多人做 RAG 项目第一反应是去调 Embedding 模型、换向量数据库、折腾 Rerank 策略结果折腾一圈发现检索命中率还是上不去。我踩过这个坑之后才意识到RAG 系统的上限在数据进入向量库之前就已经被决定了。你喂给模型什么质量的文本块它就还你什么质量的检索结果这个道理跟做饭一样——食材没洗干净、切得乱七八糟后面火候掌握得再好也白搭。LangChain 把 RAG 的数据预处理拆成了两个核心环节Document Loader负责把各种格式的原始数据加载成统一的Document对象Text Splitter负责把这些长文档切成语义相对完整的小块。这两个环节看起来简单但实际项目里 80% 的检索效果问题都出在这里。我见过太多人直接用默认参数一把梭结果切出来的块要么把一句话拦腰截断要么一个块里塞了三四个不相关的主题检索的时候自然抓不住重点。这篇文章面向的是正在用 LangChain 搭建 RAG 知识库的开发者不管你是刚入门想搞清楚RecursiveCharacterTextSplitter到底怎么配参数还是已经跑通了流程但检索效果不理想想优化都能从这里找到可以直接抄作业的方案。我会把 Document Loader 的选型逻辑、Text Splitter 的参数计算、不同文档类型的切分策略以及实际项目中遇到的坑全部掰开揉碎讲清楚。1.2 Document Loader 与 Text Splitter 的职责边界先把这个流程的骨架理清楚。一个典型的 LangChain RAG 数据预处理管线是这样的from langchain_community.document_loaders import PyPDFLoader from langchain.text_splitter import RecursiveCharacterTextSplitter # 第一步加载 loader PyPDFLoader(技术文档.pdf) docs loader.load() # 第二步切分 splitter RecursiveCharacterTextSplitter( chunk_size500, chunk_overlap50, separators[\n\n, \n, 。, , , , , , ] ) chunks splitter.split_documents(docs)Document对象是 LangChain 里的基本数据单元它有两个核心字段page_content存文本内容metadata存元数据来源文件、页码、标题等。metadata 在后续检索过滤和溯源展示时非常关键但很多人在加载阶段就把 metadata 丢了后面想按来源筛选都没办法。Document Loader 的职责是“把异构数据变成同构 Document”Text Splitter 的职责是“把长 Document 变成适合检索的短块”。这两个环节的衔接点在于Loader 产出的 Document 质量直接决定了 Splitter 能切出什么效果。比如 PDF 加载时如果表格和正文混在一起没有正确解析Splitter 再厉害也切不出干净的语义块。1.3 方案选型的核心考量为什么不用固定长度切分新手最容易犯的错误就是用CharacterTextSplitter按固定字符数硬切。我早期也这么干过结果切出来的块经常是“前半句在讲 A 概念后半句突然跳到 B 概念”因为固定长度切分完全不考虑语义边界。LangChain 提供的RecursiveCharacterTextSplitter之所以成为默认推荐核心在于它的递归分隔符策略它维护一个分隔符优先级列表先尝试用最高优先级的分隔符比如段落标记\n\n切分如果切出来的块还是超过chunk_size就降级用下一级分隔符比如换行\n继续切直到块大小符合要求或者分隔符用尽。这个策略的巧妙之处在于它优先在语义边界处切分只有在不得已时才在句子内部切。对于中文文档你需要把中文标点加入分隔符列表否则默认的英文分隔符对中文几乎不起作用会导致大量块被硬切。注意中文场景下如果不自定义 separatorsRecursiveCharacterTextSplitter 会退化成按字符硬切效果和 CharacterTextSplitter 没区别。这是我在实际项目里验证过的很多人忽略了这一点。2. Document Loader 核心细节与实操要点2.1 常见文档格式的加载器选型对照LangChain 社区提供了上百种 Document Loader但实际项目里常用的就那么十几种。我整理了一份选型对照表覆盖了绝大多数场景文档格式推荐 Loader依赖库适用场景注意事项PDF文本型PyPDFLoaderpypdf电子版 PDF、报告扫描件无法提取文字PDF扫描型UnstructuredPDFLoaderunstructured扫描件、图片型 PDF需要 OCR 支持速度慢WordDocx2txtLoaderdocx2txt.docx 文档不支持 .doc 老格式MarkdownUnstructuredMarkdownLoaderunstructured技术文档、笔记会保留标题层级信息HTMLUnstructuredHTMLLoaderunstructured网页存档需要处理噪声标签CSVCSVLoader内置结构化表格每行变成一个 DocumentJSONJSONLoaderjq结构化数据需要指定 jq schema纯文本TextLoader内置.txt 文件需手动指定编码选型的核心原则是优先用能保留 metadata 和结构信息的 Loader。比如 Markdown 文档用UnstructuredMarkdownLoader比TextLoader好因为前者会把标题层级、代码块等结构信息保留在 metadata 里后续切分和检索时可以利用这些信息做过滤或加权。2.2 PDF 加载的深坑与解决方案PDF 是 RAG 项目里最常见的文档格式也是最容易出问题的。我用PyPDFLoader踩过的坑包括坑一中文乱码。某些 PDF 的字体编码特殊pypdf提取出来是乱码。解决方案是换用pdfplumber作为底层引擎from langchain_community.document_loaders import PDFPlumberLoader loader PDFPlumberLoader(中文文档.pdf) docs loader.load()pdfplumber对中文 PDF 的兼容性明显更好而且能提取表格结构。代价是速度比pypdf慢一些但对于中小规模知识库完全可以接受。坑二页眉页脚污染。很多 PDF 每页都有页眉页脚加载后这些内容会混入正文切分后变成噪声块。我的处理方式是在加载后做一次清洗import re def clean_document(doc): # 移除常见的页眉页脚模式 text doc.page_content text re.sub(r第\s*\d\s*页, , text) text re.sub(r^\s*\d\s*$, , text, flagsre.MULTILINE) doc.page_content text.strip() return doc docs [clean_document(d) for d in docs]坑三metadata 丢失。PyPDFLoader默认会把页码存在 metadata 里但如果你用loader.load()之后又做了自定义处理很容易把 metadata 弄丢。建议在加载后立刻检查 metadata 字段确认source和page都在。2.3 批量加载与目录遍历的工程化写法实际项目里不可能一个一个文件手动加载需要写一个通用的目录遍历加载器。我的做法是按文件扩展名分发到不同的 Loaderfrom pathlib import Path from langchain_community.document_loaders import ( PyPDFLoader, Docx2txtLoader, UnstructuredMarkdownLoader, TextLoader ) LOADER_MAP { .pdf: PyPDFLoader, .docx: Docx2txtLoader, .md: UnstructuredMarkdownLoader, .txt: TextLoader, } def load_directory(dir_path: str): all_docs [] for file_path in Path(dir_path).rglob(*): if file_path.suffix.lower() in LOADER_MAP: loader_cls LOADER_MAP[file_path.suffix.lower()] try: loader loader_cls(str(file_path)) docs loader.load() # 补充文件级 metadata for d in docs: d.metadata[file_name] file_path.name d.metadata[file_type] file_path.suffix.lower() all_docs.extend(docs) except Exception as e: print(f加载失败 {file_path}: {e}) return all_docs这段代码有几个工程化细节值得注意用rglob而不是glob可以递归遍历子目录每个文件加载失败时捕获异常继续处理避免一个坏文件导致整个流程中断补充 file_name 和 file_type 到 metadata方便后续按文件类型过滤检索。实操心得加载阶段一定要加日志和异常捕获。我遇到过一个大目录里混了一个加密 PDF没有异常处理的话整个加载流程直接崩掉排查了半天才发现是那个文件的问题。3. Text Splitter 参数计算与切分策略3.1 chunk_size 与 chunk_overlap 的计算逻辑chunk_size和chunk_overlap是 Text Splitter 最核心的两个参数但很多人是拍脑袋设的。我来说说我的计算逻辑。chunk_size 的确定要考虑三个因素Embedding 模型的最大输入长度、检索时的上下文窗口、以及语义完整性。以常用的text-embedding-ada-002为例最大输入是 8191 token但实际切分时远不需要这么大。我的经验值是300-800 字符中文或500-1500 字符英文。为什么是这个范围因为检索时你通常要返回 top-3 到 top-5 个块给 LLM如果每个块太大几个块加起来就超出了 LLM 的上下文窗口如果太小单个块的信息量不足以回答问题。300-800 字符大约对应 150-400 个中文 token这个粒度既能保证语义相对完整又不会占用太多上下文。chunk_overlap 的作用是防止语义在边界处丢失。比如一句话正好被切在两个块之间如果没有 overlap两个块都读不懂这句话。overlap 的典型值是chunk_size的 10%-20%。我一般设 50-100 字符。chunk_size 500 chunk_overlap int(chunk_size * 0.15) # 75 字符这里有个容易忽略的点overlap 不能太大。如果 overlap 接近 chunk_size 的一半会导致大量重复内容进入向量库检索时返回一堆相似块浪费上下文窗口。我试过 overlap200 配 chunk_size500结果检索出来的 top-5 块有一半内容是重复的。3.2 RecursiveCharacterTextSplitter 的分隔符优先级设计这是整个切分环节最关键的配置。默认的 separators 是[\n\n, \n, , ]这套配置对英文文档还行对中文文档基本废掉。我的中文场景配置是这样的separators [ \n\n, # 段落边界优先级最高 \n, # 行边界 。, # 中文句号 , # 中文感叹号 , # 中文问号 , # 中文分号 , # 中文逗号 , # 空格 , # 最后兜底按字符切 ]这个列表的顺序就是优先级。Splitter 会先用\n\n切如果某个片段还是超过 chunk_size就用\n继续切以此类推。把中文标点放在空格之前很重要因为中文文本里空格很少如果空格优先级高于中文标点会导致大量按空格切分的情况而中文句子内部通常没有空格最终还是会退化成按字符切。对于代码文档分隔符需要另外设计code_separators [ \nclass , # 类定义 \ndef , # 函数定义 \n\n, # 空行 \n, # 换行 , # 空格 , # 字符 ]这样能保证一个类或一个函数尽量不被切断检索代码时返回的块是完整的逻辑单元。3.3 不同文档类型的切分策略差异技术文档这类文档通常有清晰的标题层级我建议用MarkdownHeaderTextSplitter先按标题切再用RecursiveCharacterTextSplitter做二次切分。这样每个块的 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_content) # 二次切分 text_splitter RecursiveCharacterTextSplitter( chunk_size500, chunk_overlap75, separators[\n\n, \n, 。, , , , , , ] ) final_chunks text_splitter.split_documents(md_chunks)对话记录客服对话、会议记录这类数据按轮次切分比按字符切分更合理。可以自定义一个 Splitter以“说话人”作为分隔符。表格数据CSV 加载后每行是一个 Document通常不需要再切分。但如果某行内容特别长还是需要处理。我的做法是给 CSV 行设一个较大的 chunk_size比如 1000因为表格行的语义完整性比长度更重要。4. 实操全流程与关键环节实现4.1 从零搭建一个可复用的预处理管线我把整个预处理流程封装成了一个类方便在不同项目里复用from langchain_community.document_loaders import PyPDFLoader, Docx2txtLoader from langchain.text_splitter import RecursiveCharacterTextSplitter from langchain.schema import Document from pathlib import Path import re class RAGPreprocessor: def __init__(self, chunk_size500, chunk_overlap75): self.chunk_size chunk_size self.chunk_overlap chunk_overlap self.splitter RecursiveCharacterTextSplitter( chunk_sizechunk_size, chunk_overlapchunk_overlap, separators[\n\n, \n, 。, , , , , , ], length_functionlen, ) def load_file(self, file_path: str) - list[Document]: suffix Path(file_path).suffix.lower() if suffix .pdf: loader PyPDFLoader(file_path) elif suffix .docx: loader Docx2txtLoader(file_path) else: raise ValueError(f不支持的文件类型: {suffix}) docs loader.load() for d in docs: d.metadata[file_name] Path(file_path).name return docs def clean_text(self, text: str) - str: text re.sub(r\n{3,}, \n\n, text) # 合并多余空行 text re.sub(r[ \t]{2,}, , text) # 合并多余空格 return text.strip() def process(self, file_paths: list[str]) - list[Document]: all_chunks [] for fp in file_paths: docs self.load_file(fp) for d in docs: d.page_content self.clean_text(d.page_content) chunks self.splitter.split_documents(docs) # 过滤掉过短的块 chunks [c for c in chunks if len(c.page_content) 50] all_chunks.extend(chunks) return all_chunks这个类里有两个容易被忽略但很重要的细节清洗阶段合并多余空行和空格能显著减少噪声块过滤掉长度小于 50 字符的块这些块通常是页眉页脚残留或分隔符产生的碎片留在向量库里只会干扰检索。4.2 切分效果的验证与调优方法切完之后怎么知道效果好不好我的做法是抽样检查 检索验证两步走。抽样检查就是随机抽 10-20 个块人工看它们的语义完整性。重点看三类问题有没有块以半句话开头或结尾、有没有块包含多个不相关的主题、有没有块几乎全是空白或符号。检索验证是更客观的方法准备 10-20 个典型问题用切好的块建一个临时向量库跑一遍检索看 top-3 结果里有没有能回答问题的块。如果命中率低于 70%说明切分策略需要调整。我整理了一份调优对照表问题现象可能原因调整方向检索结果语义不完整chunk_size 太小增大到 600-800检索结果包含多个主题chunk_size 太大减小到 300-400边界处信息丢失chunk_overlap 太小增大到 chunk_size 的 20%检索结果大量重复chunk_overlap 太大减小到 chunk_size 的 10%中文句子被硬切separators 未配置中文标点加入中文标点代码块被切断separators 未适配代码用代码专用分隔符4.3 metadata 的保留与增强metadata 在 RAG 里的作用被严重低估了。除了基本的来源信息我还会在预处理阶段补充一些增强字段def enrich_metadata(chunks: list[Document]) - list[Document]: for i, chunk in enumerate(chunks): chunk.metadata[chunk_index] i chunk.metadata[char_count] len(chunk.page_content) # 提取块内第一个句子作为摘要 first_sentence chunk.page_content.split(。)[0][:50] chunk.metadata[summary] first_sentence return chunkschunk_index在需要按顺序拼接相邻块时很有用char_count可以用于检索后的过滤比如过滤掉过短的块summary可以在展示检索结果时作为预览。更进一步如果你的文档有明确的章节结构可以把章节标题也写入 metadatachunk.metadata[section] 第三章 数据预处理这样检索时可以按章节过滤比如用户问“第三章讲了什么”你可以直接过滤section包含“第三章”的块大幅提升检索精度。5. 常见问题与排查技巧实录5.1 加载阶段的典型故障排查问题一PDF 加载后内容为空。最常见的原因是 PDF 是扫描件文字以图片形式存在。排查方法是打开 PDF 试着选中文字如果选不中就是扫描件。解决方案是换用支持 OCR 的 Loader或者先用 OCR 工具把 PDF 转成文本再加载。问题二加载速度极慢。如果目录里有几百个 PDFPyPDFLoader逐个加载会很慢。我的优化方案是用多线程并行加载from concurrent.futures import ThreadPoolExecutor def parallel_load(file_paths, max_workers4): with ThreadPoolExecutor(max_workersmax_workers) as executor: results list(executor.map(load_single_file, file_paths)) return [doc for docs in results for doc in docs]注意max_workers不要设太大4-8 就够了太多反而会因为 IO 竞争变慢。问题三编码错误。文本文件加载时如果编码不是 UTF-8会报UnicodeDecodeError。解决方案是显式指定编码loader TextLoader(file.txt, encodinggbk)5.2 切分阶段的隐蔽陷阱陷阱一分隔符顺序错误导致切分粒度失控。我见过有人把空字符串放在分隔符列表的第一位结果 Splitter 直接按字符硬切所有语义边界都被忽略。空字符串必须放在最后一位它是兜底选项不是优先选项。陷阱二chunk_overlap 大于 chunk_size。这会导致无限循环或异常。LangChain 内部会做检查但有些自定义 Splitter 不一定。务必保证 overlap chunk_size我一般控制在 10%-20%。陷阱三中文标点全角和半角混用。中文文档里可能同时存在“。”和“.”、“”和“,”。如果 separators 里只配了全角标点半角标点处就不会被切分。我的做法是两种都加上separators [\n\n, \n, 。, ., , !, , ?, , ;, , ,, , ]陷阱四表格和正文混切。PDF 里的表格提取出来通常是一堆用空格或制表符分隔的文本和正文混在一起切分后表格数据会变成难以理解的碎片。我的处理方式是在加载阶段识别表格区域单独处理或者在切分后过滤掉包含大量制表符的块。5.3 检索效果不佳时的排查清单当 RAG 检索效果不理想时按这个顺序排查先看切分质量随机抽 20 个块人工判断语义完整性。如果块本身就不完整后面怎么调都没用。再看 metadata确认每个块都有 source 和 page 信息否则无法溯源。然后看 chunk_size用 3-5 个典型问题测试如果 top-3 里没有相关块尝试调整 chunk_size。最后看 overlap如果相关块存在但信息不完整增大 overlap。我整理了一份速查表症状排查方向快速验证方法检索不到相关块chunk_size 过大或过小用不同 size 建临时库对比检索到相关块但答非所问块内主题混杂检查块是否包含多个主题答案缺少细节overlap 不足增大 overlap 重新测试检索结果重复overlap 过大减小 overlap中文检索效果差separators 未适配检查分隔符列表特定文档检索差该文档加载质量差单独检查该文档的块避坑技巧每次调整参数后只改一个变量其他保持不变这样才能定位到是哪个参数影响了效果。我早期同时改 chunk_size 和 overlap结果效果变好了也不知道是哪个起了作用。5.4 性能优化的实战经验当文档量达到几千个文件时预处理会成为瓶颈。我的优化经验批量处理而非逐个处理。把文件列表分批每批 50-100 个处理完一批写入向量库一批避免内存爆掉。缓存加载结果。如果同一批文档需要反复调参测试把加载后的 Document 用 pickle 存到本地下次直接读缓存省去重复加载的时间。import pickle def cache_docs(docs, cache_path): with open(cache_path, wb) as f: pickle.dump(docs, f) def load_cached_docs(cache_path): with open(cache_path, rb) as f: return pickle.load(f)切分阶段用多进程。Text Splitter 是 CPU 密集型操作用multiprocessing可以显著加速。但要注意 Document 对象需要可序列化LangChain 的 Document 默认支持 pickle所以没问题。我在一个 3000 个 PDF 的项目里用上述优化把预处理时间从 40 分钟压到了 8 分钟左右。核心就是并行加载 缓存 分批处理这三板斧。6. 进阶话题从预处理角度突破 RAG 瓶颈6.1 语义切分的探索与取舍RecursiveCharacterTextSplitter是基于规则的切分它的局限在于不理解语义。比如一段话里前半部分讲 A后半部分讲 B但中间没有明显的标点边界规则切分就会把 A 和 B 切在同一个块里。语义切分Semantic Chunking的思路是用 Embedding 计算相邻句子的相似度在相似度骤降的地方切分。LangChain 提供了SemanticChunkerfrom langchain_experimental.text_splitter import SemanticChunker from langchain_openai import OpenAIEmbeddings semantic_splitter SemanticChunker( OpenAIEmbeddings(), breakpoint_threshold_typepercentile, breakpoint_threshold_amount95 )但语义切分有两个实际问题速度慢每个句子都要算 Embedding和块大小不可控可能切出很长的块。我的建议是对质量要求极高的核心知识库可以用但对大多数场景优化好的 RecursiveCharacterTextSplitter 已经够用了。投入产出比要算清楚。6.2 父子块策略与多向量检索的预处理配合父子块Parent-Child Chunking是解决“检索粒度”和“上下文完整性”矛盾的一个巧妙方案用小块做检索返回大块做上下文。预处理阶段需要同时生成小块和大块并建立映射关系。# 先切大块 parent_splitter RecursiveCharacterTextSplitter(chunk_size2000, chunk_overlap200) parents parent_splitter.split_documents(docs) # 每个大块再切小块 child_splitter RecursiveCharacterTextSplitter(chunk_size400, chunk_overlap50) for i, parent in enumerate(parents): children child_splitter.split_documents([parent]) for child in children: child.metadata[parent_id] i检索时用 child 块匹配返回对应的 parent 块给 LLM。这样既保证了检索精度小块语义集中又保证了上下文完整大块信息充足。这个策略在 LangChain 里对应ParentDocumentRetriever预处理阶段的核心工作就是正确建立 parent-child 映射。6.3 预处理质量对 Agentic RAG 的影响现在 Agentic RAG 很火Agent 会自主决定检索什么、检索几次、如何组合检索结果。但很多人忽略了一点Agentic RAG 对预处理质量的要求比普通 RAG 更高。因为 Agent 会做多轮检索和推理如果底层块质量差Agent 的每一轮检索都会引入噪声错误会累积放大。具体来说Agentic RAG 场景下预处理需要额外注意metadata 要更丰富Agent 需要根据 metadata 做过滤决策、块要更干净噪声块会误导 Agent 的判断、块之间的边界要更清晰Agent 需要准确判断哪些块是相关的。我在实际项目里的体会是把预处理做好之后Agentic RAG 的效果提升比换更贵的 LLM 还明显。最后分享一个我在多个项目里验证过的经验预处理阶段多花 1 小时调参后面能省 10 小时的检索调优。很多人急着跑通流程就往下走结果在检索环节反复折腾回头发现根因在预处理。把 Document Loader 的 metadata 保留好、把 Text Splitter 的分隔符配对、把 chunk_size 和 overlap 算清楚这三件事做到位RAG 系统的地基就稳了。
