尧图网页设计 
1. 为什么数据导入是 RAG 系统的第一道生死关做过 RAG 项目的人都有一个共识检索效果差八成不是模型的问题而是数据没处理好。我见过太多团队花大力气调 embedding 模型、换向量库、优化 prompt结果回头一看原始文档里全是乱码、断行、页眉页脚混在一起切出来的 chunk 语义支离破碎再好的模型也救不回来。这一篇聚焦的是 RAG 数据管道最前端、也最容易被忽视的一环从纯文本 txt 到结构化 Markdown 的通用文本解析与结构化处理。说白了就是把各种来源的原始文本变成 LangChain 的 Document 对象能干净吃进去、后续切分和向量化都省心的格式。为什么单独把 txt 和 Markdown 拎出来讲因为它们是 RAG 知识库里占比最大、最基础、也最看起来简单的两类数据。很多人觉得 txt 直接读进来不就行了Markdown 不就是带符号的文本吗恰恰是这种轻视导致后面 chunk 质量崩盘。txt 没有结构信息Markdown 有结构但容易被粗暴地当纯文本处理两者的处理策略完全不同。这篇文章适合谁看正在搭建 RAG 知识库、用 LangChain 做 Document Loader、被 chunk 质量困扰的开发者也适合刚入门 LangChain、想搞清楚 Document 对象到底长什么样的新手。我会把 Loader 的选型逻辑、Document 对象的内部结构、Markdown 结构保留的实操细节、以及一堆踩过的坑全部摊开讲清楚。核心关键词先摆出来RAG、LangChain、Document、Loader、Markdown。这五个词贯穿全文理解了它们之间的关系你就理解了 RAG 数据导入的骨架。2. 整体设计思路Loader 到底在解决什么问题2.1 Document 对象是整个 RAG 的数据原子在 LangChain 的世界里不管你的数据来自 txt、PDF、网页还是数据库最终都要变成统一的Document对象。这个对象结构极其简单就两个核心字段page_content字符串存实际文本内容metadata字典存来源、页码、标题、时间等附加信息别小看这个设计。metadata是后面做元数据过滤检索、溯源引用、去重的命根子。我见过有人把所有内容塞进page_contentmetadata 留空结果检索出来无法告诉用户这段话来自哪个文件第几页产品体验直接掉一个档次。所以数据导入阶段的第一原则能往 metadata 里塞的结构化信息绝不留在正文里。文件路径、标题层级、章节编号、原始行号这些都是 metadata 的好素材。2.2 为什么 Loader 要分这么多种LangChain 的 Loader 生态非常庞大TextLoader、UnstructuredMarkdownLoader、MarkdownHeaderTextSplitter、DirectoryLoader……新手容易懵读个文件而已至于吗至于。因为不同格式的结构信息密度完全不同数据格式结构信息处理难点推荐策略纯 txt几乎为零段落边界模糊、编码混乱按空行/规则切分补 metadataMarkdown标题层级、列表、代码块符号干扰、层级丢失按标题切分保留层级到 metadataPDF版面、表格、图片提取质量差、乱序专用解析器 后处理HTMLDOM 树噪声多、正文提取正文抽取 清洗txt 和 Markdown 是这条流水线的起点把它们处理干净后面的 PDF、HTML 才有参照标准。这就是为什么我把它们放在全攻略的第一篇。2.3 通用文本解析的核心矛盾这里有个绕不开的矛盾保留结构 vs 保证语义连续。举个真实例子。一份 Markdown 文档标题是## 3. 部署流程下面跟着三段正文。如果你按标题切分标题会单独成为一个 chunk正文成为另一个 chunk。检索时用户问部署流程是什么标题 chunk 命中了但正文 chunk 可能因为不含部署流程这个词而没命中结果召回的是一句光秃秃的标题。反过来如果你不切分整篇塞进去chunk 太大embedding 被稀释检索精度又下降。我的经验是标题信息要下沉到正文 chunk 的 metadata 里而不是让标题单独成块。这样既保留了结构又保证了语义连续。具体怎么做第 4 节会给出完整代码。3. 核心细节解析txt 与 Markdown 的处理要点3.1 纯文本 txt 的隐藏陷阱txt 看起来最简单实际上坑最多。我按踩坑频率排个序编码问题。中文 txt 常见 GBK、GB2312、UTF-8 三种编码混用。直接open(file)用默认编码读遇到 GBK 文件就是一堆乱码。稳妥做法是用chardet探测编码或者强制指定encodingutf-8并配合errorsignore兜底。但errorsignore会静默丢字符生产环境我更推荐先探测再读。换行符混乱。Windows 的\r\n、Linux 的\n、老 Mac 的\r三种混在一起。LangChain 的TextLoader默认会做一定处理但如果你自己写读取逻辑记得统一成\n。段落边界模糊。txt 没有标题概念段落之间可能用空行分隔也可能用两个空格甚至直接连着写。这时候需要一套启发式规则连续空行视为段落分隔行首缩进视为新段落等等。页眉页脚残留。从 PDF 转出来的 txt每页顶部底部都有重复的页码、文档名。这些噪声如果不清理会污染每一个 chunk。我的做法是统计高频重复行出现次数超过总行数 30% 的短行直接判定为页眉页脚删除。3.2 Markdown 的结构价值被严重低估Markdown 是 RAG 知识库的理想公民因为它自带层级结构。#到######六级标题天然就是文档的目录树。但很多人用TextLoader直接读 Markdown把##这些符号当普通字符处理结构信息全丢了暴殄天物。正确的做法是用MarkdownHeaderTextSplitter它专门识别标题行把标题内容提取出来放进 metadata。比如from langchain_text_splitters import MarkdownHeaderTextSplitter headers_to_split_on [ (#, h1), (##, h2), (###, h3), ] splitter MarkdownHeaderTextSplitter(headers_to_split_onheaders_to_split_on) chunks splitter.split_text(markdown_text)切出来的每个 chunkmetadata 里会带上h1、h2、h3的值。检索时你就能知道这段内容属于哪个章节溯源和过滤都方便。但这里有个细节MarkdownHeaderTextSplitter默认不保留标题行本身在正文里标题只进 metadata。如果你希望正文里也带上标题有时候对 embedding 有帮助需要额外处理。我一般会在 chunk 的page_content前面手动拼上标题路径比如部署流程 环境准备\n\n正文内容...这样 embedding 时标题语义也能参与计算。3.3 代码块和表格的特殊处理Markdown 里的代码块 包裹和表格是切分的雷区。如果按标题切分时一个代码块正好跨在两个标题之间切完代码就断了语义全毁。我的处理策略是切分前先把代码块和表格替换成占位符切分后再还原。这样切分器不会在代码块内部断开。占位符用类似__CODE_BLOCK_0__的形式还原时按索引替换回去。表格同理。Markdown 表格对 embedding 其实不太友好因为|符号和空格会干扰语义。如果表格内容重要我建议把表格转成自然语言描述比如字段 A 的值为 X字段 B 的值为 Y这样检索效果更好。这一步可以用 LLM 辅助完成但要注意成本和一致性。3.4 metadata 设计的最佳实践metadata 不是随便塞的要有规划。我通常按这几类组织来源类source文件路径、file_name、file_type结构类h1、h2、h3、section_path标题路径拼接位置类start_index、chunk_index、page如果有业务类category、author、update_time注意metadata 的 key 尽量用英文小写下划线避免中文和特殊字符因为部分向量库对 metadata 字段名有兼容性要求。还有一个容易被忽略的点metadata 会占用存储空间。如果每个 chunk 都塞一大堆 metadata向量库体积会膨胀。我的经验是只保留检索和展示真正用得到的字段其余的在入库前裁掉。4. 实操过程从 txt 到 Markdown 的完整流水线4.1 环境准备与依赖安装先把依赖装齐。LangChain 的包拆分比较细别装错pip install langchain langchain-community langchain-text-splitters pip install chardetlangchain-text-splitters是独立包MarkdownHeaderTextSplitter在这里面不在langchain主包里。这个坑我踩过import 报错找半天。4.2 通用文本读取器一个能打的 txt LoaderLangChain 自带的TextLoader够用但不够好编码和清洗能力弱。我一般自己封装一个import chardet from langchain_core.documents import Document def detect_encoding(file_path): with open(file_path, rb) as f: raw f.read(10000) return chardet.detect(raw)[encoding] def load_txt(file_path): encoding detect_encoding(file_path) or utf-8 with open(file_path, r, encodingencoding, errorsreplace) as f: text f.read() # 统一换行符 text text.replace(\r\n, \n).replace(\r, \n) # 清理多余空行 lines [line.rstrip() for line in text.split(\n)] cleaned \n.join(lines) return Document( page_contentcleaned, metadata{source: file_path, file_type: txt, encoding: encoding} )这里errorsreplace比ignore好因为replace会用标记出问题字符方便你事后排查而ignore是静默丢弃出了问题都不知道。4.3 页眉页脚清洗的启发式算法针对 PDF 转 txt 的噪声我写了个简单的频次统计清洗from collections import Counter def remove_headers_footers(text, threshold0.3): lines text.split(\n) total len(lines) # 只统计短行页眉页脚通常很短 short_lines [l.strip() for l in lines if 0 len(l.strip()) 50] counter Counter(short_lines) noise {line for line, cnt in counter.items() if cnt / total threshold} cleaned [l for l in lines if l.strip() not in noise] return \n.join(cleaned)阈值 0.3 是我实测下来比较稳的值。太低会误删正常重复内容比如列表项太高又清不干净。你可以根据文档特点微调。4.4 Markdown 结构化切分完整实现这是本篇的核心。完整流程分四步读文件、保护代码块、按标题切分、还原并补 metadata。import re from langchain_text_splitters import MarkdownHeaderTextSplitter def protect_code_blocks(text): blocks [] def replacer(match): blocks.append(match.group(0)) return f__CODE_BLOCK_{len(blocks)-1}__ protected re.sub(r[\s\S]*?, replacer, text) return protected, blocks def restore_code_blocks(text, blocks): for i, block in enumerate(blocks): text text.replace(f__CODE_BLOCK_{i}__, block) return text def load_markdown(file_path): with open(file_path, r, encodingutf-8) as f: raw f.read() protected, blocks protect_code_blocks(raw) headers_to_split_on [(#, h1), (##, h2), (###, h3)] splitter MarkdownHeaderTextSplitter( headers_to_split_onheaders_to_split_on, strip_headersFalse # 保留标题在正文里 ) chunks splitter.split_text(protected) docs [] for i, chunk in enumerate(chunks): content restore_code_blocks(chunk.page_content, blocks) meta dict(chunk.metadata) # 拼接标题路径方便检索 path_parts [meta.get(k, ) for k in [h1, h2, h3] if meta.get(k)] meta[section_path] .join(path_parts) meta[source] file_path meta[chunk_index] i docs.append(Document(page_contentcontent, metadatameta)) return docsstrip_headersFalse这个参数很关键。设为True时标题只进 metadata正文里没有设为False时标题保留在正文开头。我倾向False因为标题词往往和正文语义强相关保留能提升检索命中率。4.5 批量处理目录DirectoryLoader 的正确用法单个文件处理完实际项目都是整个目录批量跑。LangChain 的DirectoryLoader可以配合自定义 loaderfrom langchain_community.document_loaders import DirectoryLoader loader DirectoryLoader( ./docs, glob**/*.md, loader_clsTextLoader, # 这里换成你的自定义 loader show_progressTrue, use_multithreadingTrue ) docs loader.load()但DirectoryLoader的loader_cls要求是类而不是函数所以自定义 loader 得封装成类。另外use_multithreadingTrue在文件多的时候能明显提速但要注意你的 loader 是否线程安全。4.6 参数选择背后的计算逻辑有人问 chunk_size 到底设多少。这不是拍脑袋定的要结合 embedding 模型的上下文窗口和你的检索粒度需求。假设你用某常见 embedding 模型最大输入 512 token。中文大致 1 个汉字 ≈ 1.5 token那么 512 token ≈ 340 个汉字。如果你希望每个 chunk 语义完整chunk_size 设 300 汉字左右比较合适留出余量。overlap 一般设 chunk_size 的 10%~20%我常用 50 汉字保证跨 chunk 的语义衔接。但注意Markdown 按标题切分时chunk_size 往往不是硬约束。因为标题切分是结构优先一个章节可能很长超过 chunk_size 还得二次切分。这时候我会对超长 chunk 再用RecursiveCharacterTextSplitter切一刀分隔符优先级设为[\n\n, \n, 。, , , ]中文标点一定要加进去。5. 常见问题与排查技巧实录5.1 中文乱码排查速查表现象可能原因排查方法解决全是问号编码不匹配chardet 探测指定正确 encoding部分乱码混合编码分段探测分块读取分别解码方框字符字体缺失检查终端字体换 UTF-8 环境字符丢失errorsignore改 replace 观察定位问题字符5.2 Markdown 切分后 chunk 过碎的解决MarkdownHeaderTextSplitter有个已知问题如果文档标题层级很深、很密集切出来的 chunk 会非常碎一个 chunk 可能就一两句话。这种碎 chunk 对检索是灾难因为语义信息太少。我的解法是后合并切分后遍历 chunks如果某个 chunk 的正文长度小于阈值比如 100 字就把它合并到前一个 chunk 里。合并时保留各自的 metadata或者取父级标题作为合并后的 section_path。def merge_small_chunks(docs, min_len100): merged [] for doc in docs: if merged and len(doc.page_content) min_len: prev merged[-1] prev.page_content \n\n doc.page_content else: merged.append(doc) return merged5.3 代码块被切断的定位方法如果发现检索出来的代码不完整先检查是不是切分时断的。定位方法在切分前给每个代码块打上唯一标记切分后检查标记是否成对出现。如果某个标记只有开头没有结尾说明代码块被切断了需要调整保护逻辑。5.4 metadata 丢失的常见原因metadata 丢失通常有三个原因一是切分器不传递 metadata部分 splitter 默认丢弃二是合并 chunk 时没合并 metadata三是序列化到向量库时字段类型不支持。排查时先在内存里打印 chunk.metadata确认切分阶段没丢再查入库阶段。实操心得我习惯在流水线每个环节后都加一个体检步骤统计 chunk 数量、平均长度、metadata 字段完整率。这三个指标一异常立刻能定位到是哪一步出的问题。5.5 性能优化大文件怎么处理几 MB 的 txt 直接读没问题但几百 MB 的日志文件直接read()会爆内存。这时候要流式读取按行处理边读边切。LangChain 的 Loader 大多是一次性加载大文件场景建议自己写生成器用yield逐块产出 Document配合向量库的批量写入接口内存占用能降一个数量级。6. 结构化数据的延伸思考6.1 从 Markdown 到知识图谱的桥梁Markdown 的标题层级本质上是一棵树这棵树和知识图谱的 ontology 有天然对应关系。#是根节点##是子节点正文是叶子节点的属性。如果你后续想做 GraphRAG 或者 ontology RAGMarkdown 解析阶段就应该把这棵树显式建出来存成(父节点, 关系, 子节点)的三元组。这样从文档到图谱的转换就是顺水推舟不用回头重新解析。6.2 结构化知识库与 RAG 知识库的分工热词里提到rag知识库和结构知识库区分以及应用场景这里顺带说清楚。RAG 知识库擅长处理非结构化、语义模糊的查询比如帮我找找关于部署的注意事项结构化知识库比如关系型数据库、图数据库擅长精确查询和聚合比如统计所有标记为高优先级的任务数量。两者不是替代关系而是互补。实际项目里我常用混合检索先用结构化过滤缩小范围再用 RAG 做语义召回效果比纯 RAG 好很多。6.3 图片和表格在 RAG 里的处理边界rag知识库能存储图片嘛这个问题问的人很多。答案是向量库本身存的是文本向量图片要么转成文字描述用多模态模型生成 caption要么用多模态 embedding 单独建索引。Markdown 里的图片链接alt 文本是宝贵的语义信息解析时一定要提取出来放进 metadata 或正文。表格则建议转成自然语言前面提过不再赘述。6.4 后续扩展方向这套 txt 和 Markdown 的处理框架稍加改造就能扩展到 HTML、PDF、Word。核心思路不变先提取结构再保护特殊块最后按结构切分并补 metadata。下一篇我会讲 PDF 和 HTML 的解析那才是真正的硬骨头版面分析、表格提取、多栏排版坑比 txt 多十倍。最后分享一个我压箱底的小技巧建立一套文档解析的回归测试集。挑 10 份有代表性的文档人工标注出理想的 chunk 切分结果每次改解析逻辑就跑一遍对比。这样能避免改好一个坏一片的尴尬。我靠这套测试集把 chunk 质量的返工率降了大半。数据导入这活儿慢就是快前期多花时间打磨解析器后面检索和生成环节能省下无数调试时间。 RAG数据导入第一关：从txt到Markdown的LangChain Document解析实战
1. 为什么数据导入是 RAG 系统的第一道生死关做过 RAG 项目的人都有一个共识检索效果差八成不是模型的问题而是数据没处理好。我见过太多团队花大力气调 embedding 模型、换向量库、优化 prompt结果回头一看原始文档里全是乱码、断行、页眉页脚混在一起切出来的 chunk 语义支离破碎再好的模型也救不回来。这一篇聚焦的是 RAG 数据管道最前端、也最容易被忽视的一环从纯文本 txt 到结构化 Markdown 的通用文本解析与结构化处理。说白了就是把各种来源的原始文本变成 LangChain 的 Document 对象能干净吃进去、后续切分和向量化都省心的格式。为什么单独把 txt 和 Markdown 拎出来讲因为它们是 RAG 知识库里占比最大、最基础、也最看起来简单的两类数据。很多人觉得 txt 直接读进来不就行了Markdown 不就是带符号的文本吗恰恰是这种轻视导致后面 chunk 质量崩盘。txt 没有结构信息Markdown 有结构但容易被粗暴地当纯文本处理两者的处理策略完全不同。这篇文章适合谁看正在搭建 RAG 知识库、用 LangChain 做 Document Loader、被 chunk 质量困扰的开发者也适合刚入门 LangChain、想搞清楚 Document 对象到底长什么样的新手。我会把 Loader 的选型逻辑、Document 对象的内部结构、Markdown 结构保留的实操细节、以及一堆踩过的坑全部摊开讲清楚。核心关键词先摆出来RAG、LangChain、Document、Loader、Markdown。这五个词贯穿全文理解了它们之间的关系你就理解了 RAG 数据导入的骨架。2. 整体设计思路Loader 到底在解决什么问题2.1 Document 对象是整个 RAG 的数据原子在 LangChain 的世界里不管你的数据来自 txt、PDF、网页还是数据库最终都要变成统一的Document对象。这个对象结构极其简单就两个核心字段page_content字符串存实际文本内容metadata字典存来源、页码、标题、时间等附加信息别小看这个设计。metadata是后面做元数据过滤检索、溯源引用、去重的命根子。我见过有人把所有内容塞进page_contentmetadata 留空结果检索出来无法告诉用户这段话来自哪个文件第几页产品体验直接掉一个档次。所以数据导入阶段的第一原则能往 metadata 里塞的结构化信息绝不留在正文里。文件路径、标题层级、章节编号、原始行号这些都是 metadata 的好素材。2.2 为什么 Loader 要分这么多种LangChain 的 Loader 生态非常庞大TextLoader、UnstructuredMarkdownLoader、MarkdownHeaderTextSplitter、DirectoryLoader……新手容易懵读个文件而已至于吗至于。因为不同格式的结构信息密度完全不同数据格式结构信息处理难点推荐策略纯 txt几乎为零段落边界模糊、编码混乱按空行/规则切分补 metadataMarkdown标题层级、列表、代码块符号干扰、层级丢失按标题切分保留层级到 metadataPDF版面、表格、图片提取质量差、乱序专用解析器 后处理HTMLDOM 树噪声多、正文提取正文抽取 清洗txt 和 Markdown 是这条流水线的起点把它们处理干净后面的 PDF、HTML 才有参照标准。这就是为什么我把它们放在全攻略的第一篇。2.3 通用文本解析的核心矛盾这里有个绕不开的矛盾保留结构 vs 保证语义连续。举个真实例子。一份 Markdown 文档标题是## 3. 部署流程下面跟着三段正文。如果你按标题切分标题会单独成为一个 chunk正文成为另一个 chunk。检索时用户问部署流程是什么标题 chunk 命中了但正文 chunk 可能因为不含部署流程这个词而没命中结果召回的是一句光秃秃的标题。反过来如果你不切分整篇塞进去chunk 太大embedding 被稀释检索精度又下降。我的经验是标题信息要下沉到正文 chunk 的 metadata 里而不是让标题单独成块。这样既保留了结构又保证了语义连续。具体怎么做第 4 节会给出完整代码。3. 核心细节解析txt 与 Markdown 的处理要点3.1 纯文本 txt 的隐藏陷阱txt 看起来最简单实际上坑最多。我按踩坑频率排个序编码问题。中文 txt 常见 GBK、GB2312、UTF-8 三种编码混用。直接open(file)用默认编码读遇到 GBK 文件就是一堆乱码。稳妥做法是用chardet探测编码或者强制指定encodingutf-8并配合errorsignore兜底。但errorsignore会静默丢字符生产环境我更推荐先探测再读。换行符混乱。Windows 的\r\n、Linux 的\n、老 Mac 的\r三种混在一起。LangChain 的TextLoader默认会做一定处理但如果你自己写读取逻辑记得统一成\n。段落边界模糊。txt 没有标题概念段落之间可能用空行分隔也可能用两个空格甚至直接连着写。这时候需要一套启发式规则连续空行视为段落分隔行首缩进视为新段落等等。页眉页脚残留。从 PDF 转出来的 txt每页顶部底部都有重复的页码、文档名。这些噪声如果不清理会污染每一个 chunk。我的做法是统计高频重复行出现次数超过总行数 30% 的短行直接判定为页眉页脚删除。3.2 Markdown 的结构价值被严重低估Markdown 是 RAG 知识库的理想公民因为它自带层级结构。#到######六级标题天然就是文档的目录树。但很多人用TextLoader直接读 Markdown把##这些符号当普通字符处理结构信息全丢了暴殄天物。正确的做法是用MarkdownHeaderTextSplitter它专门识别标题行把标题内容提取出来放进 metadata。比如from langchain_text_splitters import MarkdownHeaderTextSplitter headers_to_split_on [ (#, h1), (##, h2), (###, h3), ] splitter MarkdownHeaderTextSplitter(headers_to_split_onheaders_to_split_on) chunks splitter.split_text(markdown_text)切出来的每个 chunkmetadata 里会带上h1、h2、h3的值。检索时你就能知道这段内容属于哪个章节溯源和过滤都方便。但这里有个细节MarkdownHeaderTextSplitter默认不保留标题行本身在正文里标题只进 metadata。如果你希望正文里也带上标题有时候对 embedding 有帮助需要额外处理。我一般会在 chunk 的page_content前面手动拼上标题路径比如部署流程 环境准备\n\n正文内容...这样 embedding 时标题语义也能参与计算。3.3 代码块和表格的特殊处理Markdown 里的代码块 包裹和表格是切分的雷区。如果按标题切分时一个代码块正好跨在两个标题之间切完代码就断了语义全毁。我的处理策略是切分前先把代码块和表格替换成占位符切分后再还原。这样切分器不会在代码块内部断开。占位符用类似__CODE_BLOCK_0__的形式还原时按索引替换回去。表格同理。Markdown 表格对 embedding 其实不太友好因为|符号和空格会干扰语义。如果表格内容重要我建议把表格转成自然语言描述比如字段 A 的值为 X字段 B 的值为 Y这样检索效果更好。这一步可以用 LLM 辅助完成但要注意成本和一致性。3.4 metadata 设计的最佳实践metadata 不是随便塞的要有规划。我通常按这几类组织来源类source文件路径、file_name、file_type结构类h1、h2、h3、section_path标题路径拼接位置类start_index、chunk_index、page如果有业务类category、author、update_time注意metadata 的 key 尽量用英文小写下划线避免中文和特殊字符因为部分向量库对 metadata 字段名有兼容性要求。还有一个容易被忽略的点metadata 会占用存储空间。如果每个 chunk 都塞一大堆 metadata向量库体积会膨胀。我的经验是只保留检索和展示真正用得到的字段其余的在入库前裁掉。4. 实操过程从 txt 到 Markdown 的完整流水线4.1 环境准备与依赖安装先把依赖装齐。LangChain 的包拆分比较细别装错pip install langchain langchain-community langchain-text-splitters pip install chardetlangchain-text-splitters是独立包MarkdownHeaderTextSplitter在这里面不在langchain主包里。这个坑我踩过import 报错找半天。4.2 通用文本读取器一个能打的 txt LoaderLangChain 自带的TextLoader够用但不够好编码和清洗能力弱。我一般自己封装一个import chardet from langchain_core.documents import Document def detect_encoding(file_path): with open(file_path, rb) as f: raw f.read(10000) return chardet.detect(raw)[encoding] def load_txt(file_path): encoding detect_encoding(file_path) or utf-8 with open(file_path, r, encodingencoding, errorsreplace) as f: text f.read() # 统一换行符 text text.replace(\r\n, \n).replace(\r, \n) # 清理多余空行 lines [line.rstrip() for line in text.split(\n)] cleaned \n.join(lines) return Document( page_contentcleaned, metadata{source: file_path, file_type: txt, encoding: encoding} )这里errorsreplace比ignore好因为replace会用标记出问题字符方便你事后排查而ignore是静默丢弃出了问题都不知道。4.3 页眉页脚清洗的启发式算法针对 PDF 转 txt 的噪声我写了个简单的频次统计清洗from collections import Counter def remove_headers_footers(text, threshold0.3): lines text.split(\n) total len(lines) # 只统计短行页眉页脚通常很短 short_lines [l.strip() for l in lines if 0 len(l.strip()) 50] counter Counter(short_lines) noise {line for line, cnt in counter.items() if cnt / total threshold} cleaned [l for l in lines if l.strip() not in noise] return \n.join(cleaned)阈值 0.3 是我实测下来比较稳的值。太低会误删正常重复内容比如列表项太高又清不干净。你可以根据文档特点微调。4.4 Markdown 结构化切分完整实现这是本篇的核心。完整流程分四步读文件、保护代码块、按标题切分、还原并补 metadata。import re from langchain_text_splitters import MarkdownHeaderTextSplitter def protect_code_blocks(text): blocks [] def replacer(match): blocks.append(match.group(0)) return f__CODE_BLOCK_{len(blocks)-1}__ protected re.sub(r[\s\S]*?, replacer, text) return protected, blocks def restore_code_blocks(text, blocks): for i, block in enumerate(blocks): text text.replace(f__CODE_BLOCK_{i}__, block) return text def load_markdown(file_path): with open(file_path, r, encodingutf-8) as f: raw f.read() protected, blocks protect_code_blocks(raw) headers_to_split_on [(#, h1), (##, h2), (###, h3)] splitter MarkdownHeaderTextSplitter( headers_to_split_onheaders_to_split_on, strip_headersFalse # 保留标题在正文里 ) chunks splitter.split_text(protected) docs [] for i, chunk in enumerate(chunks): content restore_code_blocks(chunk.page_content, blocks) meta dict(chunk.metadata) # 拼接标题路径方便检索 path_parts [meta.get(k, ) for k in [h1, h2, h3] if meta.get(k)] meta[section_path] .join(path_parts) meta[source] file_path meta[chunk_index] i docs.append(Document(page_contentcontent, metadatameta)) return docsstrip_headersFalse这个参数很关键。设为True时标题只进 metadata正文里没有设为False时标题保留在正文开头。我倾向False因为标题词往往和正文语义强相关保留能提升检索命中率。4.5 批量处理目录DirectoryLoader 的正确用法单个文件处理完实际项目都是整个目录批量跑。LangChain 的DirectoryLoader可以配合自定义 loaderfrom langchain_community.document_loaders import DirectoryLoader loader DirectoryLoader( ./docs, glob**/*.md, loader_clsTextLoader, # 这里换成你的自定义 loader show_progressTrue, use_multithreadingTrue ) docs loader.load()但DirectoryLoader的loader_cls要求是类而不是函数所以自定义 loader 得封装成类。另外use_multithreadingTrue在文件多的时候能明显提速但要注意你的 loader 是否线程安全。4.6 参数选择背后的计算逻辑有人问 chunk_size 到底设多少。这不是拍脑袋定的要结合 embedding 模型的上下文窗口和你的检索粒度需求。假设你用某常见 embedding 模型最大输入 512 token。中文大致 1 个汉字 ≈ 1.5 token那么 512 token ≈ 340 个汉字。如果你希望每个 chunk 语义完整chunk_size 设 300 汉字左右比较合适留出余量。overlap 一般设 chunk_size 的 10%~20%我常用 50 汉字保证跨 chunk 的语义衔接。但注意Markdown 按标题切分时chunk_size 往往不是硬约束。因为标题切分是结构优先一个章节可能很长超过 chunk_size 还得二次切分。这时候我会对超长 chunk 再用RecursiveCharacterTextSplitter切一刀分隔符优先级设为[\n\n, \n, 。, , , ]中文标点一定要加进去。5. 常见问题与排查技巧实录5.1 中文乱码排查速查表现象可能原因排查方法解决全是问号编码不匹配chardet 探测指定正确 encoding部分乱码混合编码分段探测分块读取分别解码方框字符字体缺失检查终端字体换 UTF-8 环境字符丢失errorsignore改 replace 观察定位问题字符5.2 Markdown 切分后 chunk 过碎的解决MarkdownHeaderTextSplitter有个已知问题如果文档标题层级很深、很密集切出来的 chunk 会非常碎一个 chunk 可能就一两句话。这种碎 chunk 对检索是灾难因为语义信息太少。我的解法是后合并切分后遍历 chunks如果某个 chunk 的正文长度小于阈值比如 100 字就把它合并到前一个 chunk 里。合并时保留各自的 metadata或者取父级标题作为合并后的 section_path。def merge_small_chunks(docs, min_len100): merged [] for doc in docs: if merged and len(doc.page_content) min_len: prev merged[-1] prev.page_content \n\n doc.page_content else: merged.append(doc) return merged5.3 代码块被切断的定位方法如果发现检索出来的代码不完整先检查是不是切分时断的。定位方法在切分前给每个代码块打上唯一标记切分后检查标记是否成对出现。如果某个标记只有开头没有结尾说明代码块被切断了需要调整保护逻辑。5.4 metadata 丢失的常见原因metadata 丢失通常有三个原因一是切分器不传递 metadata部分 splitter 默认丢弃二是合并 chunk 时没合并 metadata三是序列化到向量库时字段类型不支持。排查时先在内存里打印 chunk.metadata确认切分阶段没丢再查入库阶段。实操心得我习惯在流水线每个环节后都加一个体检步骤统计 chunk 数量、平均长度、metadata 字段完整率。这三个指标一异常立刻能定位到是哪一步出的问题。5.5 性能优化大文件怎么处理几 MB 的 txt 直接读没问题但几百 MB 的日志文件直接read()会爆内存。这时候要流式读取按行处理边读边切。LangChain 的 Loader 大多是一次性加载大文件场景建议自己写生成器用yield逐块产出 Document配合向量库的批量写入接口内存占用能降一个数量级。6. 结构化数据的延伸思考6.1 从 Markdown 到知识图谱的桥梁Markdown 的标题层级本质上是一棵树这棵树和知识图谱的 ontology 有天然对应关系。#是根节点##是子节点正文是叶子节点的属性。如果你后续想做 GraphRAG 或者 ontology RAGMarkdown 解析阶段就应该把这棵树显式建出来存成(父节点, 关系, 子节点)的三元组。这样从文档到图谱的转换就是顺水推舟不用回头重新解析。6.2 结构化知识库与 RAG 知识库的分工热词里提到rag知识库和结构知识库区分以及应用场景这里顺带说清楚。RAG 知识库擅长处理非结构化、语义模糊的查询比如帮我找找关于部署的注意事项结构化知识库比如关系型数据库、图数据库擅长精确查询和聚合比如统计所有标记为高优先级的任务数量。两者不是替代关系而是互补。实际项目里我常用混合检索先用结构化过滤缩小范围再用 RAG 做语义召回效果比纯 RAG 好很多。6.3 图片和表格在 RAG 里的处理边界rag知识库能存储图片嘛这个问题问的人很多。答案是向量库本身存的是文本向量图片要么转成文字描述用多模态模型生成 caption要么用多模态 embedding 单独建索引。Markdown 里的图片链接alt 文本是宝贵的语义信息解析时一定要提取出来放进 metadata 或正文。表格则建议转成自然语言前面提过不再赘述。6.4 后续扩展方向这套 txt 和 Markdown 的处理框架稍加改造就能扩展到 HTML、PDF、Word。核心思路不变先提取结构再保护特殊块最后按结构切分并补 metadata。下一篇我会讲 PDF 和 HTML 的解析那才是真正的硬骨头版面分析、表格提取、多栏排版坑比 txt 多十倍。最后分享一个我压箱底的小技巧建立一套文档解析的回归测试集。挑 10 份有代表性的文档人工标注出理想的 chunk 切分结果每次改解析逻辑就跑一遍对比。这样能避免改好一个坏一片的尴尬。我靠这套测试集把 chunk 质量的返工率降了大半。数据导入这活儿慢就是快前期多花时间打磨解析器后面检索和生成环节能省下无数调试时间。