数据导入和解析这块，真是RAG项目里最容易被低估的环节。很多人一上来就调模型、选向量库、调相似度阈值，结果数据没洗干净，后期检索效果稀碎。我自己接手过好几个所谓“RAG效果不好”的项目，排查到最后，八成问题都出在解析环节——格式乱、编码错、标题层级丢了、表格被拆得七零八落。所以我想系统性写几篇关于RAG数据导入与解析的实战内容，这篇先讲最基础的：从txt到Markdown的通用文本处理和结构化解。
先说清楚这篇能解决什么问题。如果你正在搭RAG知识库，手里有大量txt、Markdown源码、导出的纯文本文档，希望能让向量化更精准、检索命中率更高，那么这篇非常适合你。我会从解析在RAG中的定位讲起，拆解文本清洗、txt转Markdown、目录批量导入、Markdown结构化解这几个环节，最后附上我实际踩坑的排查记录。全程给可复用的代码片段和参数选择逻辑。
1. 解析在RAG管线里的真实地位
1.1 为什么大家都低估了数据导入
RAG的完整链路一般是：导入文档 -> 解析 -> 分块 -> 向量化 -> 检索 -> 生成。绝大多数人花时间最多的是分块策略和向量库选型，但坦白讲，分块只是锦上添花，解析才是地基。地基歪了，后面再花哨都没用。
举个例子，一份PDF导出的txt文件，段落之间空行丢失，标题和正文连在一起。你拿正则做分块的脚本去处理，会发现标题被并进正文段落，切出来的块既没有语义边界，也没有层级标签。向量化之后，检索“如何配置XX参数”时，命中的可能是正文里的一句无关描述，因为这块文本漂浮在一堆相近的词汇里，没有标题给它提供上下文锚点。
我见过最离谱的一个项目，导入了几百份txt格式的技术文档，编码混着GBK和UTF-8，有的文件开头还有BOM头。向量化之后，第一轮检索测试就翻车了——问什么都匹配出一堆乱码和无关句。后来光清洗编码和字符就花了两天。所以解析这段路，你绕不开，也别想省。
1.2 “通用文本”和“结构化解”到底指什么
标题里写了“从 txt 到 Markdown 的通用文本与结构化解”，我先把这两个概念讲透。
所谓通用文本，指的是不依赖特定软件格式、拿文本编辑器就能打开的内容，比如纯txt、Markdown源文件、从其他格式导出的纯文本。这类内容没有PDF那种复杂的版面信息，也不像docx那样自带XML结构，所有的语义全靠字符本身表达：换行、空行、标题符号、列表符号、表格管道符。处理起来门槛低，但坑也藏在细节里。
而结构化解，是把这种扁平的字符流重新“翻译”成有层次的信息结构——让程序知道哪个是标题、哪个是正文段落、哪个是代码块、哪个是表格、列表嵌套了几层。这一步做完，后续的分块和向量化才能基于结构去设计策略，比如按标题边界切块、给块注入父标题、表格用特殊方式编码。可以说，结构化解是RAG数据预处理的分水岭，做了和没做，检索效果是两个档次。
2. 从 txt 开始的文本清洗：编码、BOM、乱码与断行
2.1 txt 文件的基础清洗流程
很多人觉得txt是最简单的格式，读进来切一切就行。实际上txt是所有格式里最“脏”的，因为没有格式规范约束，什么乱七八糟的字符都可能出现。我总结了一套基础清洗流程，每次读文件都跑一遍，省心很多。
第一步是编码检测。txt文件的编码五花八门：UTF-8、UTF-8 with BOM、GBK、GB2312、Latin-1、UTF-16。如果你用固定的编码打开，遇到不匹配就是乱码，而且这乱码在后续所有环节里都查不出来，因为它不会报错，只是“长得不对”。
我一般用chardet库做自动检测，然后统一转成UTF-8存储。这里有个经验：chardet在短文本上准确率不稳定，所以我会先读文件的前1万个字节做检测，而不是整个文件全读——速度快，准确率也够用。
第二步是处理BOM头。UTF-8 with BOM会在文件开头多出三个字节\xef\xbb\xbf，如果保留它，后续按Markdown解析时，第一个标题前面会莫名其妙多出不可见字符，影响匹配。这一步必须在编码转换时一并去掉。
第三步是清理控制字符和一些特殊不可见字符。比如\x00空字符、Windows换行的\r\n里的\r、零宽空格\u200b、不换行空格\u00a0。这些字符在纯文本里肉眼看不出来，但会让字符串匹配和接下来的Markdown解析出现偏差。
我直接给你一段能落地的清洗代码：
import re import chardet def clean_text(raw_bytes): # 1. 编码检测 detected = chardet.detect(raw_bytes[:10000]) enc = detected.get('encoding', 'utf-8') try: text = raw_bytes.decode(enc) except (UnicodeDecodeError, LookupError): text = raw_bytes.decode('utf-8', errors='replace') # 2. 去除BOM if text.startswith('\ufeff'): text = text[1:] # 3. 统一换行符 text = text.replace('\r\n', '\n').replace('\r', '\n') # 4. 清理控制字符（保留 \n 和 \t） text = ''.join(ch for ch in text if ch == '\n' or ch == '\t' or (ord(ch) >= 32 and ord(ch) != 127)) # 5. 清理特殊不可见字符 text = text.replace('\u200b', '').replace('\u00a0', ' ') return text这段代码我一直在用，几个细节说明一下：控制字符的过滤我保留了换行和制表符，其他都干掉；ord(ch) != 127是针对DEL字符的；零宽空格和不换行空格替换成空和普通空格。跑完这个清洗，文本才算真正干净了。
2.2 段落边界还原：什么时候该合并断行
txt文件一个经典的麻烦是“半行断行”。从PDF或网页导出的txt，经常出现一个段落被硬拆成好几行，每行末尾都有换行符。如果不做还原直接交给后续解析，你会得到一大堆只有半句话的散块，检索效果自然好不了。
判断是否该合并，我用的规则很简单：一行文本结尾如果不是句号、问号、感叹号、冒号、分号等终止符，且下一行不是空行、不是列表、不是标题，就把它和下一行合并。再加一个保护条件：如果本行字符数少于某个阈值（比如20个字符），大概率是断行，也合并。实现起来就是遍历行列表，做一次归并。
def merge_lines(lines): merged = [] buffer = '' for line in lines: stripped = line.strip() if not stripped: if buffer: merged.append(buffer) buffer = '' merged.append('') continue if not buffer: buffer = stripped elif is_incomplete_line(buffer) or is_incomplete_line(stripped): buffer += ' ' + stripped else: merged.append(buffer) buffer = stripped if buffer: merged.append(buffer) return merged def is_incomplete_line(line): if len(line) < 20: return True if not line[-1] in '。！？；：?;!': return True return False这套逻辑虽然不是100%完美，但实测在大多数场景下能把断行问题处理掉八成以上。剩下的特殊情况，比如代码段里的换行，后面讲Markdown结构化解的时候会有更精细的处理方式，这里别一刀切。
2.3 txt 转 Markdown 的转换策略
清洗完的txt，先别急着向量化。我强烈建议先把它们转成Markdown格式，原因有三：
第一，Markdown是纯文本，后续结构化解不依赖任何二进制格式，好调试好排查。第二，Markdown的标题、列表、代码块语法本身就是天然的结构信息，可以被解析器识别出来。第三，目前RAG生态里主流的分块工具和解析库对Markdown的支持远好于纯txt，很多框架原生的文档加载器就是按Markdown结构来切块的。
从txt转Markdown，核心动作是识别标题和列表。常见的规则是：
- 行首是“第X章”“第X节”“X. X”这类模式，转成#级标题；
- 行首是“一、”“1.”“- ”等，转成对应的有序或无序列表；
- 但这里我建议克制一点，除了可以明确识别为标题的行，不要乱加#；没有把握的内容一律保留为普通段落。过度转换的副作用比不转换更严重。
我自己常用一个保守策略：
def txt_to_markdown(text): lines = text.split('\n') md_lines = [] for idx, line in enumerate(lines): stripped = line.strip() if not stripped: md_lines.append('') continue if re.match(r'^第[一二三四五六七八九十百0-9]+[章节部分篇]', stripped): md_lines.append('# ' + stripped) elif re.match(r'^\d+[\.、]', stripped): md_lines.append(stripped) elif re.match(r'^[-*•] ', stripped): md_lines.append('- ' + stripped[2:].strip()) elif re.match(r'^[一二三四五六七八九十]+、', stripped): md_lines.append(stripped) else: md_lines.append(stripped) return '\n'.join(md_lines)注意：这个转换只负责“粗加工”，后续的Markdown解析节点树才是真正的精细结构化解。这里定了调子，后面才有东西可解析。
3. 从单文件到多文件：批量导入的工程化设计
3.1 目录扫描与文件过滤
真实项目里的文档不可能只有一两份，动辄几百上千份。这时候就不能单文件管线一条路走到黑，得把导入过程工程化。
我的做法是先建一个“导入清单”：扫描指定目录下的所有文件，按扩展名过滤，按大小排序，跳过隐藏文件、临时文件（比如以~$开头或者以.tmp结尾的）。这样处理的目的很直接：避免把系统垃圾文件带进知识库，同时控制导入顺序和总量。
扫描这里有个小细节要注意：os.walk遍历目录时，默认会跟随符号链接，需要留意避免循环或者重复导入。另外权限问题也很现实，某些目录会抛PermissionError，所以要捕获异常并把失败的路径记下来生成日志，而不是让整个导入流程中断。
3.2 增量导入与去重
RAG知识库一个常被忽略的需求是去重和增量更新。同样的文档反复导入，会让向量库堆满重复向量，检索时同一信息占据多个相似结果，非常浪费。
我习惯用“文件哈希 + 元数据库”的方案：对每个文件算SHA-256哈希，存到一个状态文件或SQLite里。导入前先比对哈希，如果哈希已存在且大小没变、修改时间没变，就跳过。如果内容变了，则覆盖式重新解析。这个方案简单可靠，比用文件名和大小做判断稳妥多了——同名文件被替换内容的情况太常见了。
import hashlib import os import json def file_signature(path): h = hashlib.sha256() with open(path, 'rb') as f: for chunk in iter(lambda: f.read(8192), b''): h.update(chunk) size = os.path.getsize(path) mtime = os.path.getmtime(path) return {'hash': h.hexdigest(), 'size': size, 'mtime': mtime} def should_process(path, state_store): path = os.path.abspath(path) sig = file_signature(path) prev = state_store.get(path) return prev != sig, sig增量的好处是后续你更新了几份文档，只要跑一次增量导入，就能把变化的部分同步到知识库里，不需要重新处理全部历史文件。对于长期维护的RAG项目，这个设计必不可少。
3.3 多格式扩展：txt、md、docx、pdf 的导入器设计
虽然本文聚焦txt和Markdown，但实际项目里你一定会遇到docx和PDF。我建议从一开始就把导入器设计成“插件式”，以方便后续按需扩展。做法是定义一个统一的解析器接口，返回规范化后的Markdown文本：
class DocumentParser: def can_parse(self, filename): ... def parse_to_markdown(self, filepath): ...txt和md用上一节的方法实现；docx可以用pandoc命令行做批量转换，也可以直接在Python里读docx的XML提取段落；PDF则根据情况选文本抽取或OCR。关键是让高层管线只认“Markdown字符串”这一个数据形态，其他格式的差异全被挡在解析器内部。这样后续的所有清洗、结构化解、分块逻辑都可以复用。
从工程角度看，统一输出Markdown还有个好处：你可以随时把中间产物导出成文件看一眼，排查问题非常直观。我每次解析完一批文档，都会挑几份导出一次intermediate_markdown目录，肉眼检查标题、列表、表格是否解析正确。这一步省下来的排查时间远超转换成本。
4. Markdown 结构化解：把扁平文本还原成语义树
4.1 为什么要做“语义树”而不只是字符串切片
Markdown结构化解，核心是把一段Markdown文本解析成一颗节点树。每个节点有类型（标题、段落、代码块、表格、列表项、引用块），有层级（标题级别），有内容，还有父子关系。
这层结构在RAG里的价值非常大。举个例子，如果按固定字符数分块，一个长章节的中间段，光秃秃没有任何上下文信息，向量化后检索“如何解决XX问题”时，这个段落可能被召回，但模型只能看到孤零零的几十个字，很难准确回答。而如果分块时把该章节的标题连同父级标题一起注入进去，语义完整性就会好很多。
另外，结构化解还有个更实用的价值：它可以帮你精准排除不需要向量化的内容。比如代码块、表格里的原始数据，这些内容混入普通分块常常会拉低检索质量。你可以根据节点类型灵活决定哪些进知识库，哪些单独处理，哪些直接丢弃。
4.2 Markdown 解析器的关键节点设计
我常用的解析思路是逐行扫描，配合一个简单的状态机。Markdown虽然语法复杂，但常见场景其实就那几种：标题、段落、代码块、引用、列表、表格、分隔线。核心的状态就是“是否在代码块内”“是否在列表内”“是否在表格内”。
这里给出一个节点对象的设计，我实际项目里就是直接拿它来用的：
from dataclasses import dataclass, field from typing import List, Optional @dataclass class MDNode: type: str # heading / paragraph / code / table / list / quote / hr level: int = 0 # 标题层级或列表嵌套层级 content: str = '' children: List['MDNode'] = field(default_factory=list) parent: Optional['MDNode'] = None meta: dict = field(default_factory=dict)解析时遇到#开头的行就创建一个heading节点，遇到\``开头的行就进入代码块模式，遇到|开头的连续行就尝试收集表格。每个普通段落行，如果当前没有处于任何特殊状态，就累积成一个paragraph节点。
代码块的识别要谨慎：\```标记和普通的三个反引号要区分上下文。我的处理逻辑是，一旦遇到以三个反引号开头的行，就切换代码块状态，在状态内所有行都原样保留，直到遇到下一个三个反引号的行。这样能保住代码里的换行和缩进。
4.3 表格与嵌套列表：最容易把结构搞坏的两种格式
先讲表格。Markdown表格的原始语法是管道符分隔，表格内容里如果还含有管道符，或单元格里换行，解析器就很容易识别失败。更麻烦的是表格转成纯文本后，向量化会把整个表格当成一大段连续的字符串，列语义完全丢失。
我处理表格的策略是“结构化抽取”而不是“文本截取”：解析时把表格按行按列拆开，存成二维列表放进节点的meta字段，同时把表格转成一个带语义描述的文本表示。比如：
| 参数名 | 类型 | 默认值 | |--------|------|--------| | timeout | int | 30 |我会把表格的“语义文本”生成成类似“表格：参数名-类型-默认值；第一行：timeout-int-30”的文本块。这样向量化之后，模型检索到表格时能知道每个单元格对应的列名，而不是一坨管道符和横线。实际测试下来，表格的检索命中率提升非常明显。
嵌套列表的问题则在于多层缩进。很多Markdown文档里列表项嵌套三层以上，缩进用空格和Tab混用。解析时如果只认固定缩进宽度，嵌套关系就会丢失。我的解法是记录每个列表项前的缩进字符数，转换为层级：缩进2格为一级，4格为二级。遇到混用空格和Tab的，先统一把Tab替换成4个空格再计算缩进。
4.4 从语义树到分块策略的衔接
有了节点树，分块就不是对纯文本做滑动窗口，而是对树做“结构性切割”。我常用的策略有两个，这里分享出来。
第一是“标题链注入”：遍历节点树，为每个叶子节点生成时把它的所有父级标题拼成前缀。这样每个分块都自带从顶层到当前的上下文，不依赖任何外部回溯逻辑。第二是“边界优先切割”：优先在标题节点处切块，其次在列表和段落边界切，实在超过块长度上限才考虑硬切。这样分出来的块语义上是一个完整的叙事单元。
具体实现上，我在做深度优先遍历时维护一个“当前标题栈”。递归进入子节点时压栈，退出时弹栈。每遇到段落节点，就输出标题栈加上段落内容作为一个待向量化的块。这样每个块都携带了从一级标题到当前小节的全部上下文。这个方案是我个人最推荐的一个做法，逻辑简单，效果稳定。
下面的伪代码展示了这个过程：
def walk(node, headers, chunks): if node.type == 'heading': headers.append(node.content) elif node.type == 'paragraph': prefix = ' > '.join(headers) chunks.append(prefix + '\n' + node.content) for child in node.children: walk(child, headers, chunks) if node.type == 'heading': headers.pop()注意：上面的代码省去了“块长度上限”和“重复标题导致块过长”的处理，真实项目里要加一个max_chunk_chars判断，超长就按句子边界二次切割。
5. 常见问题与排查技巧实录
5.1 乱码问题：明明打开看好好的，导入知识库就花了
这种情况十有八九是编码检测环节出了问题。我的排查顺序是：先用文本编辑器十六进制看文件开头是不是有BOM；再用file命令看系统识别出的编码；最后用chardet重检。如果你看到文本里有大量“�”替换字符，说明解码用的是errors='replace'，数据已经在导入时被不可逆地破坏了，只能回头重读原始文件。
经验之谈：不要过分信任chardet的结果，尤其是对接近纯中文的短文本，GBK和UTF-8经常被误判。我后来改进的办法是，先用UTF-8严格解码，失败后再退回GBK严格解码，两者都失败才用errors='replace'。这样比单纯依赖chardet稳妥很多。
5.2 标题层级混乱：Markdown 解析出来全是 H1
很多从txt转过来的文档，原作者写标题时就随手多打几个#，或者一律用#开头。结果解析出来的文档树几乎每个节点都是顶层标题，标题栈一直只有一个元素，层级完全没有区分度。
我的处理方法是在解析前加一道“标题归一化”流程：统计全文各级标题的数量，如果某个级别数量异常多，比如H1有几十个、H2一个都没有，就自动做降级调整——把连续出现的多个同级标题按顺序映射到不同层级。这属于启发式规则，效果不是100%，但对很多从网页复制来的文本效果很好。
5.3 表格被拆碎：向量库里全是“|”符号
如果你在检索结果里经常看到一坨|和---混在一起的文本，多半是表格文本化时没有按行处理，直接把Markdown原文喂给了后续流程。这个问题我在早期项目里踩过坑，后来才彻底改用4.3节的结构化表格抽取。
排查方法是随机选一个含表格的文档，看看生成的块内容里有没有表格语义文本的格式。如果没有，就要检查解析器是否漏了表格分支。不要小看这个问题，在技术类文档里，表格往往是信息密度最高的区域，处理不好，检索质量直接腰斩。
5.4 增量导入失效：改了文档，知识库里还是旧内容
增量导入的一个隐蔽坑是“修改时间未变但内容变了”。很多网盘同步工具和Git checkout会保留原文件的mtime，导致按mtime做判断的增量逻辑失效。所以我在3.2节里强调的是“哈希优先，mtime辅助”，哈希变了就重新解析，哪怕mtime没变。这样牺牲一点计算量，换来的是可靠性。
另外，增量导入后别忘清理向量库里对应的旧向量。只做“新增”不做“替换”，会让同一个知识点出现在两个版本的分块里，检索时互相打架，回答质量也会被稀释。
6. 实操过程中的几个重要提醒
解析环节做多了，我发现有几个原则特别值得拿出来单独强调。
第一，清洗要克制。不要为了让数据“更干净”就把所有非字母数字的字符都删掉。中英文混排的文档里，标点符号是语义的一部分，过度清洗会让句子的自然边界消失，反而伤害分块质量。
第二，转换要可审计。每一轮处理（清洗、合并断行、转Markdown、结构化解）都最好能生成中间文件或日志。一旦后续检索效果不对，能快速定位是哪一层出的问题。我见过太多项目，解析环境一团黑，输出只有向量库里的几百条记录，出了问题根本无从下手。
第三，结构化程度要跟下游策略匹配。如果你的分块策略就是简单按字符数硬切，那做一大套语义树纯属浪费，直接给解析器加一层“标题前缀注入”就够了。反过来，如果你要按主题聚合文档片段，语义树的收益会非常明显。先想清楚下游要什么，再决定预处理做到什么深度。
第四，别忘了源头文档的形态。博客导出的HTML转txt，和你手敲的txt，清洗策略完全不一样。前者要处理HTML标签残留、空格实体、无序列表符号，后者只要处理编码和断行。批量导入时，建议把文件先按来源分组，每组采用不同的解析配置。一个统一的解析器走天下，对于真实项目来说太容易出问题了。
7. 结尾：分享几个我常用的检查技巧
文章最后，我再分享几个实际干活时常用的小技巧，对排查解析问题很有帮助。
一个是“抽样十份”原则。批量解析完，别急着向量化，随机挑十份文件，打开转换后的Markdown中间文件，人工确认标题识别、段落边界、表格区域是否正确。十份里有超过两份有问题，就先回头调解析器，不要继续往下走。这个检查一次能帮你避免后面数小时的无效向量化。
另一个是给标题注入做一个“标题栈快照”。分块完成后，把每个块的标题前缀抽出来打印一下，你会看到非常直观的文档结构脉络。这一步在调试时特别有用：如果你发现某个块的标题链是“H1 > H3 > H3”，大概率是源文档的标题层级本身就乱，可能需要回到归一化那一步处理。
还有一个是从“检索验证”倒推解析质量的做法。我在做完一批导入后，会拿20个和文档强相关的问题做召回测试，看检索结果的前三名里有没有明显不相关的块。如果有，点开那个块的完整内容，基本就能看出是解析还是分块的问题。把这一步固化到每次导入的验收流程里，RAG系统的稳定性会明显提升。
解析这块活儿，看似基础，实际上是最能拉开项目差距的地方。下一篇我会继续讲其他格式的解析，以及结构化数据进RAG的一些实战细节。先把txt和Markdown这条线走稳，后面再聊别的就顺畅很多。
