1. 为什么 RAG 的第一步不是模型而是数据导入很多人一上来就急着选向量库、调 embedding 模型、研究 rerank 策略结果跑出来的效果一塌糊涂回头一查发现是原始文档根本没解析干净。我见过太多这样的案例PDF 里的表格被拆成了乱码Markdown 的标题层级全丢了txt 文件里一段话被硬生生切成了三截。RAG 的上限在数据导入阶段就已经被锁死了后面再怎么调优都是在烂地基上盖楼。这一篇聚焦的是最基础但也最容易被忽视的一环通用文本与结构化数据的导入和解析。具体来说就是从纯文本txt到 Markdown 这类带结构标记的文档怎么把它们干净、完整、有结构地送进后续的处理管线。适合正在搭建 RAG 知识库的工程师、需要做文档结构化解析的数据从业者以及任何想把散落文本变成可检索知识的人。先说一个核心判断RAG 的数据导入不是“读文件”而是“重建文档的语义结构”。一个 txt 文件丢进去你拿到的不应该是一坨字符串而应该是带有标题、段落、列表、代码块等语义标签的结构化对象。这个认知差异直接决定了你后面 chunk 的质量和检索的命中率。2. 数据导入的整体设计与格式选型思路2.1 为什么选 Markdown 作为中间格式在动手写代码之前先想清楚一个问题为什么要把各种格式统一转成 Markdown而不是直接转成纯文本或者 JSON纯文本的问题是丢失了结构信息。一篇技术文档里H2 标题和正文段落如果都变成一样的纯文本行后续做 chunk 切分时就没有任何依据来判断哪里是语义边界。你只能按固定字数硬切切出来的 chunk 大概率是半句话开头、半句话结尾检索时匹配到的内容支离破碎。JSON 的问题是过度结构化。把文档转成嵌套 JSON 当然可以保留层级但 JSON 本身对人类不友好调试时看起来费劲而且不同来源的文档结构差异很大很难设计一个通用的 JSON schema 来覆盖所有情况。Markdown 刚好卡在中间它保留了足够的结构标记标题、列表、代码块、引用同时又是纯文本人眼可读程序好处理。更重要的是几乎所有主流文档格式都能比较自然地映射到 Markdown 的语法体系。Word 的标题对应#加粗对应**表格对应|代码块对应 。这种映射关系是直觉性的不需要额外学习成本。还有一个实际考量现在很多 RAG 框架和向量库对 Markdown 的支持是最好的。按标题层级做 chunk 切分、按代码块做特殊处理、按列表做语义合并这些操作在 Markdown 上都有成熟的解析库可用。你换成自定义 JSON 格式这些轮子都得自己造。2.2 解析管线的分层设计整个导入解析流程我习惯分成三层第一层是格式识别与路由。拿到一个文件先判断它是什么格式。txt、md、html、pdf、docx 各有各的解析器不能混在一起处理。这一步的关键是准确识别尤其是那些扩展名和实际内容不一致的情况比如一个.txt文件里装的其实是 HTML 片段。第二层是内容提取与清洗。把原始内容从文件容器里抽出来去掉无关的页眉页脚、导航栏、广告文本处理编码问题统一换行符。这一步的目标是拿到“干净的原始文本”。第三层是结构化转换。把干净文本按照语义规则转成 Markdown识别标题、段落、列表、代码块、表格等元素建立层级关系。这一步的输出才是后续 chunk 切分的输入。三层分开的好处是每层可以独立调试。解析结果不对时你能快速定位是格式识别错了、清洗没做干净还是结构化规则有问题。如果三层揉在一起写出了问题只能从头到尾排查效率极低。2.3 编码问题的预处理策略编码是 txt 导入时最常见的坑。中文文档尤其容易出问题GBK、GB2312、UTF-8 混着来读出来全是乱码。我的做法是在读取阶段就做编码探测而不是假设所有文件都是 UTF-8。具体来说先用二进制模式读入前几 KB 的字节用编码检测库判断最可能的编码然后用该编码读取全文。如果检测置信度低就按优先级依次尝试 UTF-8、GBK、GB18030、Latin-1哪个能成功解码且不报错就用哪个。这里有个细节不要用errorsignore来强行解码。忽略错误字节看起来能跑通但会静默丢失内容后面发现文档缺了一段话根本查不到原因。正确的做法是让解码失败暴露出来然后针对性处理。注意有些 txt 文件开头带有 BOM字节顺序标记UTF-8 BOM 是\xef\xbb\xbf。读取时如果不处理第一个字符会变成不可见的零宽字符导致后续的标题识别、关键词匹配全部失效。读取后第一件事就是检查并剥离 BOM。3. 核心细节解析与实操要点3.1 txt 文件的段落识别逻辑txt 文件最大的问题是它没有任何显式结构标记。你拿到手的是一堆用换行符分隔的文本行但哪些行构成一个段落、哪些行是标题、哪些行是列表项全靠推断。我用的段落识别规则是这样的连续的非空行如果满足以下任一条件就合并为一个段落——行尾没有句号、问号、感叹号等结束标点下一行以逗号、分号开头两行之间的缩进差异小于 2 个空格。反之如果一行以结束标点结尾且下一行有更大的缩进或者以特定标记开头如数字加顿号、短横线就认为段落在此处断开。标题识别更依赖启发式规则。常见的模式包括行长度较短通常少于 40 个字符、独立成行、前后有空行、以数字编号开头如“一、”“1.”“1.1”、或者全部是大写/加粗样式在纯文本中表现为特殊符号包裹。这些规则单独用都不靠谱但组合起来投票准确率能到可接受的水平。实际操作中我会先把所有候选标题行标记出来然后人工抽查一批调整规则阈值。这个过程不需要全量标注抽 50 到 100 个样本就能把规则调到比较稳的状态。3.2 Markdown 结构解析的关键点Markdown 看起来简单但解析起来有不少细节要注意。最核心的是标题层级树的构建。一个 Markdown 文档里的标题不是平级的#是一级##是二级###是三级它们构成一棵树。解析时必须把这棵树建出来而不是简单地把所有标题行提取成一个列表。因为后续 chunk 切分时你需要知道每个段落属于哪个章节这样才能在 chunk 的元数据里带上章节路径信息。构建标题树的基本逻辑是维护一个栈遇到新标题时如果它的级别比栈顶高直接入栈如果级别相同弹出栈顶再入栈如果级别更低持续弹出直到找到合适的父节点。这样每个标题节点都能正确挂到它的父节点下面。另一个容易忽略的点是代码块内的内容不能被当作 Markdown 语法解析。代码块里出现#开头的行那是代码注释不是标题。解析时必须先识别代码块的起止标记三个反引号或三个波浪线在代码块范围内的内容原样保留不做任何语法解析。表格解析也是重灾区。Markdown 表格用|分隔单元格但单元格内容里如果本身包含|就需要转义。解析时要正确处理转义字符否则表格列数会对不上。还有表格的对齐标记行|---|---|这行是格式声明不是数据解析时要单独处理。3.3 特殊元素的处理策略数学公式是技术文档里常见的元素。Markdown 里数学公式用$...$表示行内公式$$...$$表示块级公式。解析时要把公式内容完整保留不能因为里面包含特殊字符就做转义或清洗。后续 chunk 切分时公式通常要和它前后的解释文字放在同一个 chunk 里否则检索到公式但看不到解释等于没用。图片引用的处理要分情况。如果 RAG 系统只处理文本图片引用可以保留为 Markdown 语法但提取 alt 文本作为补充信息。如果系统支持多模态就需要把图片下载下来单独存储在 Markdown 里保留引用路径后续做图文关联。这里的关键是图片路径要转成相对于知识库根目录的路径不能用原始文档里的绝对路径或网络 URL否则迁移时会全部失效。链接的处理有个取舍保留原始 URL 还是只保留链接文本我的经验是两者都保留但在 chunk 元数据里把 URL 单独存一份。这样检索时可以用链接文本做语义匹配同时保留 URL 供溯源使用。列表的解析要注意嵌套层级。Markdown 用缩进表示列表嵌套但缩进用几个空格、用 Tab 还是空格混用不同编辑器写出来的文档差异很大。解析时要先把 Tab 统一转成空格然后按缩进宽度推断嵌套层级。有序列表和无序列表的标记也要正确识别-、*、都是无序列表标记1.、1)、(1)都是有序列表标记。3.4 元数据提取与附加解析完内容结构后还要提取和附加元数据。这些元数据在后续检索和排序时非常有用。基础元数据包括文件名、文件路径、文件大小、修改时间、编码格式、原始格式类型。这些信息在导入时就能拿到直接附加到每个 chunk 上。内容元数据包括标题层级路径如“第一章 1.2 节 1.2.3 小节”、段落序号、是否包含代码、是否包含公式、字符数、词数。这些需要在解析过程中动态生成。还有一个容易被忽视的元数据是文档摘要。在导入阶段用轻量模型对整篇文档生成一个摘要附加到每个 chunk 上可以在检索时提供全局上下文。这个做法在长文档场景下效果提升明显因为单个 chunk 往往只反映局部信息有了文档摘要模型能更好地判断这个 chunk 在整体中的位置。4. 实操过程与核心环节实现4.1 环境准备与依赖安装先搭好基础环境。Python 3.9 以上版本核心依赖包括pip install chardet markdown-it-py beautifulsoup4 lxml python-frontmatterchardet用于编码检测markdown-it-py是 Markdown 解析器beautifulsoup4和lxml处理 HTML 转换python-frontmatter解析 Markdown 的 YAML 前置元数据。如果你要处理 PDF 和 Word还需要额外安装pip install pdfplumber python-docxpdfplumber在表格提取方面比 PyPDF2 强不少python-docx是 Word 文档的标准处理库。4.2 txt 文件解析的完整实现先定义一个通用的文件读取函数处理编码探测和 BOM 剥离import chardet def read_text_file(filepath): with open(filepath, rb) as f: raw f.read() # 剥离 BOM if raw.startswith(b\xef\xbb\xbf): raw raw[3:] encoding utf-8 else: detected chardet.detect(raw[:10000]) encoding detected[encoding] or utf-8 confidence detected[confidence] # 置信度低时按优先级尝试 if confidence 0.7: for enc in [utf-8, gb18030, gbk, latin-1]: try: raw.decode(enc) encoding enc break except UnicodeDecodeError: continue return raw.decode(encoding)这个函数的关键点是先剥离 BOM再做编码检测置信度低时按优先级回退。gb18030排在gbk前面是因为它是超集能覆盖更多字符。接下来是段落识别和结构化转换import re def txt_to_markdown(text): lines text.split(\n) result [] current_para [] for i, line in enumerate(lines): stripped line.strip() # 空行段落边界 if not stripped: if current_para: result.append( .join(current_para)) result.append() current_para [] continue # 标题检测 if is_heading(stripped, lines, i): if current_para: result.append( .join(current_para)) result.append() current_para [] level detect_heading_level(stripped) result.append(# * level stripped) result.append() continue # 列表项检测 if re.match(r^[\-\*\]\s, stripped) or re.match(r^\d[\.\)]\s, stripped): if current_para: result.append( .join(current_para)) result.append() current_para [] result.append(stripped) continue # 普通文本行 current_para.append(stripped) if current_para: result.append( .join(current_para)) return \n.join(result)标题检测函数用多规则投票def is_heading(line, all_lines, index): # 规则1长度短 if len(line) 50: return False # 规则2前后有空行 prev_empty index 0 or not all_lines[index-1].strip() next_empty index len(all_lines)-1 or not all_lines[index1].strip() if not (prev_empty and next_empty): return False # 规则3以编号开头 if re.match(r^[一二三四五六七八九十][、\.], line): return True if re.match(r^\d(\.\d)*[\.\s], line): return True # 规则4全大写或特殊标记 if line.isupper() and len(line) 3: return True return False这套规则不是完美的但覆盖了大多数中文技术文档的标题模式。实际使用时我会先跑一批样本看误判和漏判的情况再针对性调整。4.3 Markdown 解析与标题树构建Markdown 解析用markdown-it-py它能输出 token 流比直接正则匹配靠谱得多from markdown_it import MarkdownIt def parse_markdown(text): md MarkdownIt() tokens md.parse(text) structure [] heading_stack [] for token in tokens: if token.type heading_open: level int(token.tag[1]) # 弹出栈中级别 当前级别的标题 while heading_stack and heading_stack[-1][level] level: heading_stack.pop() node { level: level, title: , path: [h[title] for h in heading_stack], content: [] } heading_stack.append(node) structure.append(node) elif token.type inline and heading_stack: if heading_stack[-1][title] : heading_stack[-1][title] token.content else: heading_stack[-1][content].append(token.content) return structure这段代码的核心是heading_stack的维护。每次遇到新标题先把栈里级别大于等于它的都弹出去剩下的栈顶就是它的父节点。这样构建出来的path字段就是完整的标题层级路径比如[第一章, 1.2 数据导入, 1.2.3 编码处理]。代码块的处理需要单独判断。markdown-it-py会把代码块解析成fence类型的 token里面的内容不会被当作 Markdown 语法解析这正是我们想要的行为。但要注意fencetoken 的content字段包含代码原文info字段包含语言标识这两个都要保留。4.4 结构化输出的组织方式解析完的文档不能直接丢给向量库需要组织成统一的中间格式。我用的结构是这样的{ doc_id: unique_hash, source: 原始文件路径, format: markdown, metadata: { title: 文档标题, created_at: 创建时间, modified_at: 修改时间, encoding: utf-8, char_count: 12345, summary: 文档摘要 }, sections: [ { path: [第一章, 1.2 节], level: 2, content: 章节正文..., metadata: { has_code: True, has_formula: False, char_count: 2345 } } ] }sections是按标题层级切分后的章节列表每个章节包含路径、级别、正文和元数据。这个结构的好处是后续做 chunk 切分时可以直接按 section 来切每个 chunk 天然带有章节路径信息检索时能提供更好的上下文。对于没有标题的纯文本整个文档作为一个 sectionpath为空列表。对于标题层级很深的文档可以设置一个最大深度超过深度的标题不再单独成 section而是合并到父 section 的内容里。4.5 批量导入与增量更新实际项目中文档不是一次性导入的而是持续增加的。所以导入管线要支持增量更新。我的做法是给每个文档计算一个内容哈希比如 SHA-256存储在元数据里。每次导入时先计算当前文件的哈希和已存储的对比。如果哈希相同跳过如果不同删除旧版本导入新版本。这样既避免了重复导入又能自动处理文档更新。批量导入时要注意内存控制。不要一次性把所有文件读进内存而是用生成器逐个处理处理完一个释放一个。对于大文件可以分块读取边读边解析避免内存峰值过高。提示增量更新时删除旧版本和导入新版本要放在同一个事务里。如果先删后导中间失败会导致文档丢失如果先导后删中间失败会导致重复。用事务保证原子性或者用版本号标记查询时只取最新版本。5. 常见问题与排查技巧实录5.1 编码乱码问题速查编码问题是最常见的表现是中文显示为乱码或者问号。排查思路如下现象可能原因解决方法中文全是问号用 Latin-1 解码了 UTF-8检测编码用 UTF-8 重新读取中文部分乱码混合编码部分内容用了不同编码分段检测逐段解码开头有不可见字符BOM 未剥离读取后检查并剥离 BOM换行符异常Windows/Unix 换行符混用统一替换\r\n为\n实测下来chardet对中文编码的检测准确率在 85% 左右剩下的 15% 需要靠回退策略兜底。如果文档来源可控最好在导入前统一转成 UTF-8从源头消除问题。5.2 标题识别误判的调整方法标题识别误判有两种把正文误判为标题或者把标题漏判为正文。误判为标题的典型情况是短行被当成标题。比如“如下所示”这种短句前后有空行长度也短容易被误判。解决方法是在规则里加一条标题行不应以冒号、逗号、分号结尾。另外标题行通常不包含句号如果一行以句号结尾基本可以排除是标题。漏判标题的典型情况是标题行前后没有空行。有些文档写得很紧凑标题和正文之间没有空行分隔。这种情况下前后空行的规则就不适用了。解决方法是增加基于内容的规则如果一行以编号开头且长度短即使前后没有空行也判定为标题。调整规则时建议准备一个包含 50 到 100 个样本的测试集每次调整后跑一遍看准确率和召回率的变化。不要凭感觉调要有数据支撑。5.3 Markdown 解析的边界情况Markdown 解析有几个边界情况容易出问题嵌套列表的缩进不一致。有的文档用 2 个空格缩进有的用 4 个有的用 Tab。解析前先统一Tab 转 4 个空格然后把所有缩进规范化为 2 的倍数。这样嵌套层级判断才准确。代码块未闭合。如果文档里有一个 开头但没有对应的结尾解析器会把后面所有内容都当成代码。处理方法是解析前先检查代码块标记的数量如果是奇数在文档末尾补一个闭合标记。表格列数不一致。Markdown 表格要求每行列数相同但实际文档里经常有某行多一列或少一列的情况。解析时以表头行的列数为准数据行不足的补空超出的截断。HTML 标签混入。有些 Markdown 文档里混了 HTML 标签比如br、div。markdown-it-py默认会保留这些标签如果后续处理不需要 HTML可以在解析配置里开启htmlFalse让解析器把 HTML 标签当纯文本处理。5.4 性能优化与批量处理技巧文档数量多的时候解析性能会成为瓶颈。几个优化点并行处理。解析是 CPU 密集型任务用多进程并行能显著提速。Python 的multiprocessing.Pool就够用进程数设为 CPU 核心数。注意不要用多线程GIL 会限制性能。缓存解析结果。如果同一批文档需要多次解析比如调参时把解析结果缓存到磁盘下次直接读缓存。缓存 key 用文件哈希文件没变就直接用缓存。惰性解析。不是所有文档都需要立即解析。可以先只提取元数据文件名、大小、修改时间实际内容等到需要时再解析。这样导入阶段很快解析开销分摊到查询时。大文件分块读取。超过 10MB 的文本文件不要一次性读入内存。用readline()逐行读边读边处理内存占用能控制在常数级别。5.5 结构化质量的验证方法解析完的文档怎么验证质量我通常做三个检查完整性检查。对比原始文档和解析后的字符数差异超过 5% 就要排查。常见原因是编码问题导致字符丢失或者解析规则把某些内容过滤掉了。结构合理性检查。看标题层级是否连续有没有从 H1 直接跳到 H3 的情况。看章节路径是否完整有没有空标题。看代码块是否成对出现。抽样人工检查。随机抽 10 到 20 个文档人工看解析结果是否符合预期。重点关注表格、代码块、公式这些复杂元素。人工检查发现的模式化问题反过来优化解析规则。注意不要追求 100% 的解析准确率。实际项目中80% 到 90% 的准确率通常就够用了剩下的边缘情况可以在检索层做补偿。把大量时间花在优化最后 10% 的边缘情况上投入产出比很低。6. 从解析到 chunk 的衔接要点解析只是第一步解析结果最终要喂给 chunk 切分。这里有几个衔接要点直接影响最终效果。章节路径要传递到 chunk 元数据。每个 chunk 都应该知道自己属于哪个章节这样检索时可以把章节路径作为上下文一起返回。实现上就是在切分时把当前 section 的path字段复制到每个 chunk 的元数据里。代码块和公式不要被切断。按字符数切分时如果切分点落在代码块或公式中间会破坏语义。解决方法是切分前先标记这些特殊区域切分时避开这些区域或者把整个代码块/公式作为一个不可分割的单元。段落边界优先于字符数。切分时优先在段落边界切其次在句子边界切最后才按字符数硬切。这样切出来的 chunk 语义完整性更好。实现上可以先按段落分组累积到接近目标字符数时切一刀而不是严格按字符数切。重叠区域的设计。相邻 chunk 之间保留一定重叠通常 10% 到 20%可以避免关键信息刚好落在切分点上被割裂。但重叠不宜过大否则检索时会返回大量重复内容浪费上下文窗口。元数据要精简。每个 chunk 都带元数据元数据太大会显著增加存储和传输开销。只保留对检索有用的字段章节路径、文档 ID、段落序号、是否包含代码/公式。其他信息放在文档级别不要重复到每个 chunk。这套导入解析管线我在多个项目中用过从几千篇文档到几十万篇文档都跑过。核心经验就一条解析阶段多花一小时后面调优能省一天。数据质量是 RAG 效果的天花板这个天花板在导入阶段就定下来了。后面几篇我会继续聊 PDF、Word、HTML 这些格式的解析以及 chunk 切分的具体策略感兴趣可以接着看。