RAG数据预处理：纯Python实现TXT转结构化Markdown，提升检索召回率

如果你做过 RAG检索增强生成项目一定遇到过这种窘境数据拿到手是几百个 txt 文件没有标题层级没有段落标记甚至连编码都不统一。把这种文本丢给 LangChain 或者 LlamaIndex切出来的 chunk 经常是断句错乱、语义截断检索召回效果惨不忍睹。我最初做本地知识库时也被这个问题折磨得够呛后来把所有文本统一清洗并转成 Markdown 结构之后再灌入索引召回质量直接上了一个台阶。这个系列打算把 RAG 数据导入与解析的完整思路拆开讲透。第一篇先聊最基础的场景如何把随手可得的 txt转成干净、可复用、能被 RAG 管线正确识别的 Markdown。整个过程不依赖昂贵工具纯 Python 就能搞定适合零基础想要上手 RAG、正在纠结数据预处理的读者也适合已经跑通 demo、但检索效果不理想想回头优化数据管线的同学。这篇文章会给出完整代码、选型理由、实操步骤和踩坑记录你可以直接照着抄。1. 先想清楚RAG 到底需要什么样的输入文本1.1 纯文本在 RAG 流程里的三个死穴很多教程都在讲向量检索 LLM 生成的框架却很少提一个根本问题向量检索的质量上限由输入文本的结构决定。纯 txt 文件在 RAG 管线里有三个典型死穴第一没有语义边界。一整本小说或者几十页的说明文档可能从头到尾没有空行as 一个字符串送进去。固定窗口切分时词与词之间、段落与段落之间的天然语义边界被无视常常出现上句讲配置下句讲报错被硬生生拼进同一个 chunk 的情形。第二无法精确引用。RAG 生成答案时需要给出依据纯 txt 没有任何定位锚点你只能把一大段文本作为引用返还给用户。用户看到的是几百字甚至上千字的证据体验很差。第三元数据缺失。来源、标题、日期、标签、所属章节这些信息在纯文本里完全没地方放。可 RAG 恰恰极度依赖元数据做过滤比如只检索某个时间段、只检索某个章节丢失元数据等于丢失了检索侧最有效的武器。我在项目里吃过这个亏。最初把一份运维手册的 txt 直接切分灌库用户问如何配置反向代理系统检索出来的 chunk 混着安装步骤、负载均衡说明和日志格式介绍。后来我把每章的标题变成 Markdown 二级标题把章节归属作为 filter 字段同样的查询召回前几位的 chunk 几乎全部命中目标章节。1.2 Markdown 为什么是结构化文本的黄金标准有人问为什么不直接用 HTML 或者 JSONHTML 体积膨胀标签噪声大embedding 时会浪费 tokenJSON 需要严格的 schema不适合人类日常写作。Markdown 恰好卡在中间它轻量到几乎不占 token同时用#、##、-、等约定俗成的符号给文本注入了层级和语义。更关键的是整个 RAG 生态已经默认支持 Markdown。LangChain 有MarkdownHeaderTextSplitterLlamaIndex 有MarkdownNodeParserObsidian、Notion 导出的知识库原生就是 Markdown。你的文本一旦变成 Markdown等于同时获得了人类可读和机器可解析两个属性。还有一个很多人忽略的点现代 LLM 对 Markdown 语法的理解力远比纯文本强。生成回答时模型会更准确地引用二级标题对应的段落而不是像对纯文本那样只做字面匹配。我在多个数据集上对比过同样的文档Markdown 化之后端到端回答的准确率平均提升 5%~10%尤其涉及列表、步骤类问题时提升更明显。2. 通用文本转换管线设计四个阶段与工具选型2.1 从 txt 到 Markdown 的四阶段管线我把整个转换过程拆成四个阶段每个阶段职责单一方便单独调试编码识别与标准化先把文件读成统一的 UTF-8 字符串处理乱码、BOM、全角符号、Windows 换行。文本清洗压缩多余空行、去首尾空白、规整缩进、过滤零宽字符。结构嗅探与转化根据行首特征识别标题、列表、引用、代码块、表格逐行转成 Markdown 语法。元数据装配生成 YAML front matter写入标题、来源、日期、标签为后续 RAG 检索做准备。这个设计的关键在于逐行扫描。它比整篇正则替换更可控也更容易解释哪一行变成了什么为什么变一清二楚。日志一打问题就定位了。2.2 工具选型哪些轮子值得捡工具层面我不建议上来就上重型框架先用轻量 Python 库就能完成 90% 的工作。编码识别chardet。虽然它不是 100% 准确但对付中文 txt 常见的 UTF-8、GBK、GB2312 绰绰有余。实测 500M 以内文件chardet.detect()速度可以接受。文本清洗标准库re、unicodedata足够。不要为了清洗引入 pandas那是杀鸡用牛刀。HTML 转 Markdown如果你手里有的是 HTML 而不是 txt直接用markdownify它能把标签树还原成 Markdown 语法省一大段解析功夫。通用文档转换pandoc是格式转换界的瑞士军刀。txt 转 Markdown 这种简单场景不需要它但如果你未来需要处理 docx、epub、LaTeX 混排建议装一个。分块LangChain 的MarkdownHeaderTextSplitter是我的首选LlamaIndex 的MarkdownNodeParser也是同思路的等价物。别被五花八门的工具名劝退。核心逻辑只有一句话读进来是字符串写出去也是字符串中间靠规则组织。2.3 为什么要在灌入 RAG 之前先做结构化这个顺序问题是我踩过坑之后才想明白的。以前我图省事直接把 txt 切片丢给 embedding以为靠向量检索的模糊匹配就能补救结构缺失。事实证明向量相似度对语义连贯的完整段落更敏感对半截句子拼接的碎片很迟钝。也就是说坏结构会被 embedding 进一步放大缺陷而不是掩盖缺陷。正确的顺序一定是先结构化再切分最后 embedding。结构化让切分有依据切分让 embedding 有语义完整性。这也是这篇文章标题强调结构化解的原因——它解决的不仅是格式美观问题而是直接决定了 RAG 检索质量的下限。3. 实操完整流程编码识别、清洗、逐行转换、元数据生成3.1 第一步编码识别与统一读入中文 txt 最常见的三类编码是 UTF-8、GBK、GB2312。还有一个坑带 BOM 的 UTF-8头部会多出\ufeff不处理的话第一个标题会莫名其妙多出几个不可见字符。import chardet from pathlib import Path def read_text_file(path: Path) - str: raw path.read_bytes() # 采样前 4096 字节做编码检测足以覆盖绝大多数场景 guess chardet.detect(raw[:4096]) encoding guess.get(encoding) or utf-8 try: text raw.decode(encoding) except UnicodeDecodeError: # 兜底fallback 到 utf-8 的 errorsreplace text raw.decode(utf-8, errorsreplace) # 统一换行消除 Windows / Mac / Linux 差异 text text.replace(\r\n, \n).replace(\r, \n) # 去掉 BOM text text.lstrip(\ufeff) return text这里注意 chardet 对很短的文本可能误判。实测七八个字符的短文本它可能把 GBK 内容识别为 ISO-8859-1。所以一个更稳健的做法是若检测结果是 ISO 系编码且原文包含中文字符则强制尝试 GBK 再试 UTF-8。def robust_decode(raw: bytes) - str: guess chardet.detect(raw[:4096]) enc guess.get(encoding, ).lower() candidates [enc, utf-8, gbk, gb2312] if iso in enc else [enc, gbk] for e in candidates: if e ascii: continue try: return raw.decode(e), e except (UnicodeDecodeError, LookupError): continue return raw.decode(utf-8, errorsreplace), utf-8(replace)经验之谈不要依赖文件后缀或平台提示判断编码。我在整理客户资料时拿到的 txt明明是 Windows 记事本另存的 UTF-8却带 GBK 之名的后缀用上面这种候选列表逐一尝试的方式最稳。3.2 第二步文本清洗的标准化操作清洗是性价比最高的环节但它不应该是简单的strip()。真正的坑都在细节里全角空格\u3000在中文排版中很常见但 embedding 模型不一定认识会变成真空格直接替换为普通空格。零宽字符\u200b、\u200c、\u200d在一些从网页复制来的文本里隐藏极深肉眼看不见却会让 chunk 检索时匹配不到关键词。连续空行超过一个统一压缩成两个换行保证段边界干净。行尾残留的\t会污染 Markdown 表格识别提前替换为四个空格或直接删除。import re import unicodedata def clean_text(text: str) - str: # 常见全角转半角 text text.replace(\u3000, ) # 去零宽字符 text re.sub(r[\u200b\u200c\u200d\ufeff], , text) # 行尾空白处理 lines [line.rstrip() for line in text.split(\n)] # 压缩连续空行 clean_lines [] blank 0 for line in lines: if not line.strip(): blank 1 if blank 1: clean_lines.append() else: blank 0 clean_lines.append(line) return \n.join(clean_lines).strip()这块我还建议顺手用unicodedata.normalize(NFKC, text)收一下全角字母和数字因为它会把这类全角 ASCII 外壳变为普通 ASCII对后续正则匹配极有帮助。不过要注意NFKC 会改变部分字符语义比如把连接号变成-如果文档里以数据表格为主建议先跑小样本确认。3.3 第三步逐行扫描识别并转换 Markdown 语法这是整个转换管线最核心的部分。我采用的思路是状态机 行级正则记住当前是否处于代码块遇到不同模式的行做相应转发。HEADING_ZH re.compile(r^\s*(第[一二三四五六七八九十百千万零〇\d][章节卷部回][篇].*)\s*$) HEADING_NUM re.compile(r^\s*(\d{1,3}[\s、.]\s*\S.*)$) HEADING_MD re.compile(r^\s*(#{1,6})\s(.)$) LIST_MARK re.compile(r^\s*([-*•]|\d{1,3}[.、)])\s) QUOTE_MARK re.compile(r^\s*()\s*(.*)$) CODE_MARK re.compile(r^\s*(|~~~))逐行转换的主逻辑def txt_to_markdown(text: str) - str: lines clean_text(text).split(\n) out [] in_code False for i, line in enumerate(lines): stripped line.strip() # 代码块状态切换 if CODE_MARK.match(stripped) and not in_code: in_code True out.append(line) continue if CODE_MARK.match(stripped) and in_code: in_code False out.append(line) continue if in_code: out.append(line) continue # 保留原有 Markdown 标题 m HEADING_MD.match(line) if m and not LIST_MARK.match(line): out.append(line) continue # 中文章节标题 - 二级标题 if HEADING_ZH.match(stripped): out.append(f## {stripped}) continue # 数字/中文序号标题 - 三级标题 if HEADING_NUM.match(stripped): out.append(f### {stripped}) continue # 有序/无序列表 if LIST_MARK.match(stripped): # 统一为 Markdown 有序/无序语法 if re.match(r^\s*\d, stripped): out.append(re.sub(r^(\s*)\d([.、)]), r\1-, stripped)) else: out.append(re.sub(r^(\s*)[-*•]\s, r\1- , stripped)) continue # 引用 q QUOTE_MARK.match(line) if q and q.group(2): out.append(f {q.group(2)}) continue out.append(line) return \n\n.join(out)上述代码有几个细节值得单独说明。首先是中文标题识别的优先级。中文文档经常出现第1章 概述一、背景1.1 目标这种多样化的标题格式规则里要让中文章节词和数字序号的匹配在列表匹配之前否则1、xxx会被当成有序列表而不是标题。我测试过几百份文档第...章规则和数字.规则的正确率比较高但1.1 目标这种二级编号建议单独处理因为它既可能是小标题也可能真的是列表项。稳妥做法是设置一个上下文阈值如果后面跟的行是空行且下一行开头是普通文字则判为标题否则判为列表。其次是保留格式 vs 统一语法。原始 txt 里可能已经有手写的-列表、引用转换时要避免二次包裹。上面的代码通过先匹配HEADING_MD和QUOTE_MARK并通过非列表标记条件排除误判已经做了设计。最后是表格识别。txt 的表格通常是竖线分隔或Tab 分隔纯文本。逐行转换时如果检测到连续多行包含|或\t我可以将它们合并为一个 Markdown 表格块并在表头下面插入分隔行。这一步需要跨行状态属于加分项详见后面踩坑实录中的折中方案。3.4 第四步生成 YAML Front Matter 元数据RAG 检索侧最喜欢 属性能过滤。给每篇文章生成 front matter 之后切分出来的每个 chunk 都会带上来自 header 的元数据这是 LangChain 和 LlamaIndex 的原始支持能力。import datetime def make_front_matter(title: str, source: str, tags: list[str] | None None) - str: tags tags or [] date datetime.date.today().isoformat() fm [ ---, ftitle: \{title}\, fsource: \{source}\, fdate: \{date}\, ftags: {tags}, ---, , ] return \n.join(fm)生成之后我通常把文件保存为.md并建立原始 txt 路径 - Markdown 路径的映射 JSON。这样后续如果源文件更新可以只重跑增量转换不重灌整个库。这里有个很实用的技巧文件名如果包含有意义的信息比如2025-Q1-运维手册.txt优先从文件名提取日期和分类作为元数据的一部分。这比让大模型阅读全文然后总结元数据省钱且稳定。反正我实测让 LLM 给几百个文件逐个打标签账单和耗时都不可控。4. 进阶解析Markdown 结构如何驱动 RAG 分块4.1 为什么按 Markdown 标题切分比按字数硬切更合理RAG 分块有两个目标语义完整和大小可控。纯文本按字数硬切语义完整纯粹靠运气而 Markdown 天然标注了边界——标题到下一标题之间的内容大概率是一个完整的主题段落。按这个边界切每个 chunk 内部聚焦同一主题embedding 的向量空间里分布更紧凑检索时命中率自然高。我举一个具体例子。一份 20 页的《产品发布会 FAQ》按 500 字硬切会出现“问题 8 的答案被切成两半”的情况按##标题切每个问答自动成为独立 chunk一问一答结构完整用户问退款政策时检索到的 chunk 精确对应该章节而不是前后混入其他问题。当然标题切分也有副作用某些标题下内容特别长比如一个章节几千字超过模型上下文窗口。这时就需要标题切 段续切两级策略。4.2 可靠的二级切分MarkdownHeaderTextSplitter 与递归字符切分组合LangChain 的MarkdownHeaderTextSplitter会保留标题层级并把标题附加到每个 chunk 的元数据中。配合RecursiveCharacterTextSplitter处理超长章节是我最常用的组合。from langchain.text_splitter import MarkdownHeaderTextSplitter from langchain.text_splitter import RecursiveCharacterTextSplitter headers_to_split_on [ (#, H1), (##, H2), (###, H3), ] md_splitter MarkdownHeaderTextSplitter(headers_to_split_on, strip_headersFalse) sections md_splitter.split_text(md_text) text_splitter RecursiveCharacterTextSplitter( chunk_size800, chunk_overlap80, separators[\n\n, \n, 。, , , , ], ) final_chunks [] for section in sections: content section.page_content if len(content) 800: final_chunks.append(section) else: split_parts text_splitter.split_text(content) for part in split_parts: final_chunks.append(splitter.create_documents([part]))这段代码的用意是“先按结构尊重语义再按长度兜底”。注意strip_headersFalse要保留标题让标题文字参与 embedding检索时能借标题提升权重如果你想让标题只作为过滤标签不开任何向量化可以改为True。还有一个偏门但好用的设置RecursiveCharacterTextSplitter的 separators 我特意放进了中文句号、分号和逗号。这样即使被迫切超长段落也优先在句子边界切而不是在词中间生切。实测这个细节能显著减少 chunk 内句子被拦腰截断的问题。4.3 图片与多模态RAG 知识库到底能不能存图片这个话题热搜里反复出现现实中我也经常被问到。先说结论传统文本 RAG 不直接存图片但可以间接存。做法有三种成本依次升高如果图片里是文字用 OCR如 PaddleOCR、Tesseract提取文本把提取结果作为该段落的正文图片路径作为元数据附件。如果图片承载的是视觉信息比如产品外观图、报表趋势图可以借助多模态模型如 GPT-4V、Qwen-VL生成一句描述把描述文本嵌入向量库。检索时用户问按钮长什么样命中的是描述文本。如果知识库规模小还可以把图片路径保留在 Markdown 里在前端回答时展示图片链接但 embedding 不处理图片本身。实操上我在 Markdown 转换管线里会对这类语法做保留同时对图片文件名做一次脏数据清洗路径分隔符、空格转短横线确保 RAG 应用渲染图片时不断链。4.4 结构化知识库ontology / 知识图谱和普通 RAG 的区别热搜里有不少人在问ontology RAG“知识图谱 RAG 和文本 RAG 的区别”。简单说普通 RAG 是无结构向量检索适合开放式问答结构化知识库基于图谱三元组适合精确关系查询。比如某员工在哪个部门这种问题向量检索可能答出模糊结果图谱直接边遍历即可精确定位。但引入图谱也有代价你需要构建实体、关系、属性清洗成本极高。我的经验是——如果你的数据主要是文档、手册、PDF老老实实做好 Markdown 结构化就够用了只有当数据里有明显实体间关系如下单门店、会员等级、商品类目时才值得考虑并行建一个知识图谱。这两种方案不互斥甚至可以在 RAG 路由里按查询类型分流。5. 踩坑实录txt 转 Markdown 的常见问题与排查思路5.1 编码乱码看似乱码其实是多字节分割我在处理一批来自老系统的 txt 时发现chardet把 GBK 识别成了 ISO-8859-1解出来满屏西文字符。原因不是 chardet 不行而是文件头部几十字节可能是纯 ASCII比如文件名注释采样让它被误导。解决思路是把采样窗口拉大到全部文本或者直接使用前面的“候选编码逐一尝试”方案。记住一个原则中文环境下解码失败的兜底顺序永远是 UTF-8 → GBK → GB18030。5.2 正则回溯灾难看似匹配很慢其实是量词地狱我早期用过一个匹配“任意标题行”的正则^\s*(.{0,50}?)(第.{0,30}章).*$处理大文件时性能惨不忍睹几兆文本卡了几十秒。后来排查发现是嵌套量词.和.*的组合引发灾难性回溯。改进办法是尽量用字符类限制范围[^\n]{0,50}而不是.*并且对标题规则用前缀锚点优先的简单正则不要搞复杂捕获组。正则写得越简单越不容易出事。5.3 空行压缩误伤代码块清洗阶段把连续空行压缩到只剩一个看起来没问题但代码块里的空 Python 函数、空 JSON 对象常靠空行分隔逻辑。如果清洗先于代码块识别执行代码里的空行就被吞了。实操时我调整了顺序先做代码块保护找出代码块范围并缓存再做空行压缩最后还原代码块。保护机制很简单给每行加一个CODE_LINE_$i占位符即可。5.4 表格识别竖线文本的误伤有些纯文本为了对齐会使用大量竖线|画表格边框逐行判断时容易错把普通段落里的竖线当作表格。有一个稳妥的启发式规则只有当连续 3 行以上满足每行都含|且按|切分后各列长度基本一致时才判定为表格块。判定成功后手动补上表头分隔行而不是依赖原始文本自带的分隔行。这样即使原始 txt 表格格式稀烂转出来的 Markdown 表格也是合规的RAG 解析时不会崩。def is_table_block(lines) - bool: if len(lines) 3: return False col_counts set() for line in lines: if | not in line: return False parts [p.strip() for p in line.split(|) if p.strip()] col_counts.add(len(parts)) return len(col_counts) 15.5 长文档内存占用过大一个 200MB 的 txt如果用read_bytes()全量读入Python 进程内存会直接飙到 1GB 以上。处理超大文件时我改成流式读取每次读入一行或一个块边清洗边转换边写临时文件。转换完整文件后再用统一的 shell 命令合并临时文件。虽然代码复杂了一些但内存占用从几百 MB 降到几十 MB对于批量处理几百个文件的项目来说这个优化是必须的。6. 实战心得与后续扩展方向跑完这个 txt 转 Markdown 管线我最深的一个体会是RAG 项目的成败一半在数据导入一半在检索策略而这两个环节之间的连接点就是文本的结构化程度。不要指望一个稀烂的纯文本经过魔法般的 embedding 能变出高质量检索。先花时间把数据变成有结构、有元数据、有清晰边界的 Markdown后续所有环节都会变得轻松。如果你现在手头没有 Markdown 知识库建议立刻把现有的 txt 文档套用上面的流程跑一遍哪怕不灌入向量库只生成结构化 Markdown 文件也会给你后续的各种处理带来极大便利。我至今还在迭代这套小工具已经把它做成了一个简单的命令行脚本支持批量目录、增量更新、错误报告输出。下一步我打算在这个基础上加一个标题树预览功能可视化每个 Markdown 文档的层级结构方便人工校验转换质量。这个系列后续还会聊 HTML/PDF 转 Markdown、表格数据的处理、以及如何给 Markdown 设计一套适合 RAG 的 chunking 策略。这些都是我在实际项目里踩过坑之后沉淀下来的一手经验。希望这一篇能帮你把数据导入这一步走稳给后面所有环节打个好底子。