RAG项目做了大半年踩过最多的坑不在模型选型也不在向量库调参反而是最不起眼的“数据导入”环节。很多人把pdf、txt往切分器里一扔embedding完丢进向量库就以为万事大吉结果检索出来的片段要么语义断裂、要么结构错乱甚至连编码都是乱码。说白了RAG整个链路的数据质量上限在导入解析这一步就锁死了后面怎么调都只是补救。这篇文章是我自己项目里摸索出来的导入解析套路围绕“从txt到Markdown”这条主干线展开。注意不是说txt多么高级而是Markdown这种轻量结构化格式对RAG检索特别友好。我会把通用文本导入的完整思路、结构化转换的逻辑、切块策略和一系列工程化细节都摊开讲适合正在搭知识库、纠结“为什么检索效果这么差”的朋友也适合那些想把手头一堆txt资料系统化整理的开发者。1. RAG数据导入的核心矛盾文本不结构化检索就无从谈起先说一个很反直觉的结论在RAG里真正决定检索质量的不是向量模型也不是向量库而是你喂进去的文本长什么样。文本在进embedding之前如果是一团没有任何结构的字符流再强的向量模型也只能按字面相似度给你召回而召回的片段往往是霰弹枪式的——上下文是碎的逻辑是断的甚至一句话被从中间拦腰截断。我刚做RAG时犯过的错很典型把一堆txt直接读进来按固定字符数切块然后embedding。结果用户问“你们产品的退款政策是什么”系统召回的是几个混合了退款、发货、客服电话的碎片段落既没有标题引导也没有上下文衔接生成的答案自然东拼西凑。后来我才明白RAG检索系统设计里有一条隐藏的公式——检索上限 文本结构化程度 × 切块策略适配度。文本越结构化语义边界越清晰召回质量和生成质量就同步上去。那为什么选择Markdown作为中间格式因为Markdown有几个特性天然契合RAG第一轻量且无损。Markdown是纯文本不需要额外解析器就能被人和程序阅读也不会像docx或pdf那样需要依赖库才能抽取内容。第二结构语义自带。标题层级#到######、列表、表格、引用、代码块等元素定义了文本的层次和边界。切块时可以借助这些标记识别语义段落而不是靠字数硬切。第三生态兼容性极好。几乎所有RAG框架LangChain、LlamaIndex、Spring AI等和向量库工具都原生支持Markdown切分器比如LangChain的MarkdownHeaderTextSplitter。这意味着一次结构化解析后续的切分、清洗、检索链路全部顺了。再说一个容易被忽略的现实问题知识库里的txt文件往往是从别处导出的——可能是网页保存的读者模式文本可能是论文的纯文本版可能是日志导出也可能是一些老旧系统的数据导出。这类文本的问题不在于“有没有格式”而在于格式和信息是隐含的。标题用的是什么符号层级缩进靠空格还是Tab表格是纯文本对齐还是制表符分隔这些都需要解析时识别并统一。所以我把RAG数据导入总结为三步清洗原始文本 → 结构化成Markdown → 按语义切块。每一步都影响下游效果本文重点讲前两步——从txt到Markdown的“通用文本与结构化解”第三步切块策略放在后续文章里细说。2. txt文件的基础清洗你以为读进来就完了其实坑都在看不见的地方2.1 编码问题90%的txt解析翻车都栽在这里很多人读txt习惯直接open(file.txt)Python默认用UTF-8解码如果文件实际是GBK或者GB18030编码一读就是一个UnicodeDecodeError。即使不报错遇到某些边缘编码也很容易出现替换符乱码比如锟斤拷这类经典乱码。处理步骤我建议这样先做编码探测。用chardet或charset-normalizer检测文件实际编码推荐后者速度快、准确率更好。指定编码读取后再统一转成UTF-8。写回或入库时统一用UTF-8保存避免后续处理链路中编码混乱。这看起来是基础常识但实际项目里混着GBK、UTF-8、UTF-8-BOM的需求非常常见。如果是Windows记事本导出的txt还容易带BOM头不清理干净就会把\ufeff带到第一个标题或段落前面切块时也容易被忽略。from charset_normalizer import from_path def read_text_safe(path): best_match from_path(path).best() if best_match is None: raise ValueError(f无法检测文件编码: {path}) return str(best_match)2.2 噪音清理全角半角、空行、页眉页脚、自动换行读进来之后别急着做结构化。先做几件脏活去掉连续多余空行统一换行符为\n处理Windows记事本的\r\n。这一步虽然枯燥但能避免后续正则匹配时被坑。更头疼的是“软换行”。很多txt是网页或PDF直接另存的每行末尾都有换行但语义上根本不是一个段落。如果直接保留Markdown渲染后会出现大量孤行段落都被打断。常见的处理方法是把单独成行的短句按换行符合并成段落除非该行看起来是标题或列表项。这种启发式规则需要结合具体文本微调。页眉页脚也是一个隐藏问题。有些txt是从扫描件OCR出来的每一页底部都有页码、页眉有文档名。这些内容如果不识别并剔除它们会混在正文切块里污染语义。比较实用的做法是先统计高频短行像页码、版权声明、网址这类重复出现的行大概率就是页眉页脚可以建立黑名单后批量过滤。2.3 特殊字符与不可见符号看不见的脏数据最坑这一步容易被忽略但特别重要包括不间断空格\u00a0在网页文本里很常见看着像空格但split()不会切它零宽字符\u200b经常藏在粘贴的文本里检索时会造成莫名其妙的匹配失败各种引号、破折号的全角半角混用控制字符、乱码替换符\ufffd清洗时一键替换import re, unicodedata def clean_text(text: str) - str: # 统一换行符 text text.replace(\r\n, \n).replace(\r, \n) # 去除零宽字符和其他不可见控制符 text re.sub(r[\u200b-\u200d\u2060\ufeff], , text) # 不间断空格替换为普通空格 text text.replace(\u00a0, ) # 压缩连续空格和连续空行 text re.sub(r[ ]{2,}, , text) text re.sub(r\n{3,}, \n\n, text) # 按需做Unicode规范化 text unicodedata.normalize(NFKC, text) return text.strip()NFKC规范化会把全角字符转半角对中英文混排的文档尤其有益——检索时用户输入半角字符匹配全角原始文本才不会出问题。3. 把txt“翻译”成Markdown结构识别其实靠几组正则3.1 为什么不是先转HTML再转Markdown你可能想问为什么不直接上pandoc或者html2text这种现成工具我的回答是通用txt没有标准结构现成工具默认了“源文本具有某种结构”而txt恰恰是最不结构化的。pandoc处理markdown、html、latex都没问题但让它猜一堆古老txt哪些行是标题、哪些行是列表它做不到。而且它的输出不可控很多场景下需要写一堆filter去改默认规则维护成本反而更高。所以我的做法是手写一组轻量解析规则识别txt中常见的结构线索再映射成Markdown语法。这组规则按优先级逐层处理每个规则都是正则上下文判断的组合。3.2 标题识别的规则与优先级标题识别是结构化的核心也是最容易出问题的环节。我总结的启发式规则如下行文本很短比如少于30个字符且不与上下文构成句读关系行末没有句号、逗号等强标点或者即使有句号但两端都有空行行内包含章节编号模式如“第一章”“1.2”“3.1.2”“一”“Part II”等该行若被当前规则判定为标题它与上一行、下一行之间通常存在空行但某些OCR文本不遵循对应到正则我会构造一组模式逐一匹配title_patterns [ r^\s*第[一二三四五六七八九十百千万零][章节篇部分讲课]\s*.*$, r^\s*\d(\.\d){0,3}\s\S.*$, # 1.2.3 标题 r^\s*[一二三四五六七八九十]\s*\S.*$, r^\s*Part\s\S.*$, # Part I 等 r^\s*[①②③④⑤⑥⑦⑧⑨⑩]\s*\S.*$, # 带圈序号 ]对于匹配到的行根据其序号层级映射为对应Markdown标题级别。比如一级章“第一章”映射为#二级“1.2”映射为##三级“3.1.2”映射为###以此类推。这种映射不是绝对的要看实际文档的层级深度。有些文档一级标题是“一、”二级是“一”三级是“1.”层级结构隐藏在中文序号里需要单独写一套序号映射逻辑。这里要特别提醒一个容易踩的坑“数字顿号”不一定就是标题。很多正文会以“1.”“2.”开头列举观点如果整篇文本中没有其他标题特征这时把“1.”全判成标题就会给Markdown结构硬塞进一堆假标题。因此标题识别必须结合上下文一个有效技巧是统计全文的候选标题行数量如果候选标题占比过高比如超过总行数的20%就要降低标题匹配的阈值甚至回退为纯段落处理。这个“候选占比”的置信度判断比单纯的正则可靠得多。3.3 列表、表格、引用块的识别与转换识别完标题下一步是列表。txt中列表形态很自由常见的有- item或* item开头已经是Markdown兼容格式1. item数字序号列表1item、①item、a) item等哑铃式序号制表符或空格开头、视觉上缩进的伪列表我的转换策略简单直接凡是能识别为列表项的一律输出为Markdown的-无序列表或1.有序列表格式。因为对检索来说列表项往往构成一组紧密相关的语义集合保留它们的结构关系对召回后生成答案很有帮助。表格比列表复杂。纯文本表格常见的形态有两类一类是Markdown风格用|分隔另一类是普通文本对齐用多个空格分隔列网上常说的“ASCII表格”。前者直接保留即可后者需要按空格对齐规则去猜测列边界。说实话纯空格对齐的表格在RAG场景下不用太过纠结因为embedding模型对多列表格的语义理解非常有限把每行当成一个带分隔符的段落反而更利于检索。我的建议是检测到表格类文本时将列分隔符替换为|行首和行尾补齐|构成标准Markdown表格如果列对齐严重混乱就退化为“每行一个段落行内用分号分隔字段”。引用块的识别相对简单凡是行首出现、》、“ ”包裹的整段引文可以转换为Markdown引用块。但RAG场景下引用内容往往本身是知识正文的一部分强行变成引用块不一定有助于检索。我个人的经验是除非是明确的“观点引用”或“语录”否则保留为普通段落更好。3.4 代码块与特殊内容留给后续检索更多上下文txt里如果包含代码片段需要识别并包裹成Markdown代码块。判断方式连续若干行以空格或Tab缩进且包含语言关键词如def、import、function、class、SELECT、div等。不过要注意代码块内部不应再做标题、列表的二次解析否则会把代码里的注释误判成结构化元素。正确顺序是先隔离代码块再对剩下的文本做标题、列表、表格解析。另外URL、邮箱、ISBN等特殊格式建议在导入时统一做“实体保护”——也就是用占位符替换解析完成后再恢复。否则URL里的/、?、#符号可能会干扰Markdown标题和列表的解析尤其#这个字符在Markdown里是标题标记不处理会被误判。3.5 从txt到Markdown的完整转换流程我整理出一个可复用的转换流程顺序很重要不要乱读文件探测编码统一为UTF-8基础清洗去BOM、统一换行符、去零宽字符、压连续空行隔离代码块候选区域暂存并打标在全文中识别标题行按序号层级映射为Markdown标题识别列表项转换为-或1.格式识别表格|或空格对齐转换为Markdown表格识别引用、高亮、分割线等按需转换恢复代码块占位符二次清理去掉连续空行、统一列表与段落之间的空行这里有一步容易被遗漏标题识别完之后紧跟着标题的正文是否要“吸”到标题所在块我的答案是需要而且必须确保标题和其下正文在切块时属于同一语义块。这涉及Markdown解析后的节点归属问题在切块策略那篇文章我会专门展开。4. 结构化解之后的切块策略Markdown让切分从“盲切”变成“按语义切”4.1 为什么固定字符切块一定不是最优解很多人切块就用split(\n\n)或者按textwrap固定长度切。固定长度切块的致命问题是语义边界被无视。一个句子可能正好跨在切块边界上一个标题和它下面的内容可能被扔进两个不同的切块检索时标题丢失上下文就断了。这一类问题在RAG实际部署中非常常见。Markdown结构化之后切块可以遵循“语义边界优先”的原则。我现在的做法是用一个“目标块大小”比如800~1000 token作为参考值切块时优先在Markdown节点边界标题层级、段落、列表项、表格行切分如果某个节点内容超长再进一步按段落或句子级别的边界切分借助LangChain的递归切分器或MarkdownHeaderTextSplitter基本能实现。要注意的是标题层级本身也应该作为一个元数据字段随切块一起存入向量库这样检索时可以按标题维度过滤也方便生成引用来源。4.2 列表和表格怎么切才不会丢语义列表项是很好的切块边界但需要注意不要把单个列表项切走一半。我踩过一个具体问题某个FAQ的解答是一个带嵌套列表的Markdown段落嵌套层级很深按默认切分器切完后子项和父项被切到了不同块里检索答案时只能拿到一个不完整的步骤。解决办法是先合并列表组为整体若整体超长再按顶层列表项逐一切分并保留父级列表项文本作为切块前缀上下文。表格的切块策略也类似。对多行表格建议按行切分成多个语义单元但每行要携带表头和表名作为上下文前缀。这样召回“某指标的单位是什么”时能拿到带着表头字段的行切块而不是孤零零的一行数字。4.3 切块后要不要做清洗和meta标注清洗其实不只是导入阶段的事切块之后同样需要。我常用的一套清洗操作包括去掉切块首尾的空白和孤立标记符号如残留的#、|、-去掉纯目录行切块恰好命中目录页时对中文文本做简单的标点连接检查避免切块以冒号、逗号结尾同时每个切块建议在入库前附上meta信息。我项目里的切块meta至少包含五项source来源文件路径doc_type源文档类型txt/markdown/pdfchunk_title命中的标题层级路径比如“第2章/2.3节”chunk_index块序号token_count预估token数方便后续检索时判断负载这些meta在生成阶段用于回答溯源和引用定位非常值得在导入解析阶段就做好。5. 长文档处理和批处理管线的工程化细节5.1 长文件的拆分时机先整读再分层处理有些txt动辄几MB甚至几十MB整文件读入可能还好但等到embedding阶段内存会非常吃力。更好的做法是整文件拆成“逻辑切片单元”后再进入embedding而不是先切固定字节再解析。逻辑切片单元可以是一个章节、一个一级标题下的完整内容块。在生成Markdown时我用一个简单的“文档流式处理”思路按标题层级切分出各个章节块每个章节块内部再做细粒度的段落识别和列表识别。这样即使文档很大内存里始终只保留当前章节块和上下文映射表不会一次性把几百MB载入内存。5.2 批处理每个文件都要有独立的处理报告当知识库里躺着几千个txt时逐个文件处理容易出现“文件坏了”“编码探测失败”“标题识别率异常低”等问题。所以我在批处理管线里强制输出一份处理报告每个文件记录文件编码探测结果行数、字符数、清洗前后的字数变化识别出的标题数量与层级分布转换后Markdown的标题占比、列表项数量、疑似表格数量异常标记编码失败、乱码占比过高、空文件、标题识别率过低为什么要记录这些因为一旦检索质量出现问题你可以快速定位是哪个批次、哪个文件的清洗出了岔子而不是对着几千个文档大海捞针。我遇到过实际情况某批txt是从老系统导出的编码是GB2312但其中几百个文件存的是UTF-8混合编码导致批量导入时一半乱码。如果没有处理报告这个问题可能到上线后才发现。5.3 转换后的校验Markdown语法合法性和标题完整性Markdown转换完我建议做两道校验第一道是Markdown语法规范性校验——检查标题、列表、表格是否合法尤其注意标题行#后面是否有空格列表项是否统一用相同前缀表格分隔行是否合法。这些不影响大方向但会影响某些Markdown解析器的切分结果值得顺手做掉。第二道是标题树完整性校验——看看生成的结构里是否有“孤儿标题”比如出现###但没有对应的##父级。这类情况在转换软件生成的txt里很常见因为在生成过程中丢失了部分层级信息。如果发现大量孤儿标题检查标题识别规则是否把某些正文段落误判成了标题。这两道校验可以帮助你建立对导入管线的信心也能在人工抽查时快速筛出需要修正的异常文档。6. 一些个人总结的实用经验到这里从txt到Markdown的通用文本与结构化解基本讲完了。最后分享几条我在实际项目中反复验证过的经验希望能帮你少走弯路。第一不要把清洗和结构化分开做。很多人习惯先做一遍清洗隔几天再做结构化转换结果发现清洗后的文本丢失了换行信息、标题特征也变了。更好的做法是设计一个流水线式的处理函数清洗、识别、转换在一个流程里完成每一步都基于上一步的输出做增量判断。这样既方便调试也避免中间状态信息丢失。第二结构化转换的规则要永远保持“可回退”。也就是任何规则判断都要有“这条规则不生效”的默认路径。比如标题识别如果文档里的“第1章”只有孤零零一个而其它全是段落那这个“第1章”可能不是真标题。宁可漏判也不要多判——因为多余的假标题会给切块带来错误边界而漏判的真标题最多导致该块没有标题头部语义损失反而小。第三切块之前的“块大小”不要只看字符数还要看token数。中文的token和字数比例大约在1:1.5到1:2之间浮动不同embedding模型的tokenizer计数也不一样。我习惯在解析管线里预留一个token_estimator函数用目标向量模型的tokenizer做预统计这样切块大小更可控。第四人工抽检永远比自动化指标更有用。建议每处理几百个文档随机抽10~20个转换后的Markdown文件人工过一眼。重点看标题层级是否合理、列表是否被错误折叠、表格是否成功转换。你可以用任何支持Markdown预览的工具打开看起来不舒服的地方就是管线需要调的地方。自动化测试测的是规则覆盖率人工抽检测的是真实语义质量两者都不能缺。数据导入解析这件事确实琐碎但它是RAG项目里最值得花时间打磨的环节之一。处理得干净后面不管是检索调优、agent工具编排还是知识库运维都顺滑得多。文章里涉及的完整代码实践和一些边界case的处理方式篇幅所限没法全部展开。如果大家感兴趣我后续可以接着写切块策略和向量化存储的具体实践把整条链路真正串起来。