RAG数据导入实战：从TXT到Markdown的结构化解析与清洗

1. 为什么 RAG 的第一步不是模型而是数据导入很多人一上来就研究向量库选哪个、Embedding 模型用哪个、检索策略怎么调结果折腾半天发现召回效果一塌糊涂。问题往往不出在检索环节而是出在数据导入这一步——你喂进去的东西本身就是烂的后面再怎么优化都是白搭。我做过好几个 RAG 项目踩过最大的坑就是早期太信任原始文档的质量。一堆 txt 文件里混杂着乱码、多余空行、页眉页脚、断行断句直接切块丢进向量库检索出来的内容驴唇不对马嘴。后来我才意识到RAG 的数据导入与解析本质上是一个数据清洗和结构化的工程问题跟模型关系不大但直接决定了整个系统的上限。这篇文章聚焦在 RAG 数据导入的第一个环节从 txt 到 Markdown 的通用文本与结构化解析。说白了就是怎么把各种来源的纯文本文件变成干净、有结构、适合后续切块和向量化的 Markdown 格式。适合正在搭建 RAG 知识库的开发者、需要批量处理文档的数据工程师以及任何想把杂乱文本变成可用知识的人。你可能会问为什么偏偏选 Markdown 作为中间格式原因很简单Markdown 既能保留结构信息标题层级、列表、代码块、表格又是纯文本处理起来不依赖任何重型工具。相比直接上 PDF 解析或者 HTML 解析txt 转 Markdown 是最基础但也最容易被忽视的一环。基础没打好后面全是坑。2. 整体设计思路与方案选型2.1 为什么需要中间格式原始 txt 文件的问题在于它只有内容没有结构。一篇技术文档标题、正文、代码示例、注释全混在一起你根本不知道哪段是章节标题哪段是正文描述。如果直接按固定字数切块很可能把一个完整的代码示例切成两半或者把标题和它对应的内容分到不同的块里。Markdown 的好处在于它用极轻量的语法标记了结构。#表示标题层级-或1.表示列表包裹代码块|表示表格。这些标记在后续切块时非常关键——你可以按标题层级切保证每个块有完整的语义单元也可以识别代码块避免从中间切断。我试过直接对 txt 做固定长度切块也试过先转 Markdown 再按结构切块后者的检索准确率明显更高。原因在于结构信息本身就是一种语义信号。一个二级标题下面的内容大概率属于同一个主题一个代码块里面的内容不应该被拆散。2.2 解析流程的整体架构整个流程我把它拆成四个阶段原始文本读取与编码检测处理不同来源的 txt 文件解决编码问题文本清洗与规范化去除噪声、统一换行、处理特殊字符结构识别与 Markdown 转换识别标题、列表、代码块等结构生成 Markdown质量校验与输出检查转换结果确保没有丢失关键信息这四个阶段看起来简单但每个阶段都有不少细节。比如编码检测很多中文 txt 文件是 GBK 或 GB2312 编码直接按 UTF-8 读会乱码。再比如结构识别不同来源的 txt 文件格式差异很大有的用空行分隔段落有的用缩进有的用特殊符号标记标题。2.3 工具选型为什么不用重型框架市面上有不少文档解析框架比如针对 PDF 的、针对 Word 的但针对纯 txt 的反而很少。我的选择是用 Python 标准库加少量第三方库自己写解析逻辑原因有三第一txt 格式足够简单不需要引入复杂的依赖。第二自己写解析逻辑可以针对具体的数据源做定制灵活性更高。第三RAG 项目的数据导入往往需要批量处理成千上万个文件轻量级的方案性能更好也更容易调试。具体用到的库包括chardet用于编码检测re用于正则匹配pathlib用于文件遍历。这些都是非常成熟的工具不需要额外学习成本。提示如果你的数据源主要是 PDF 或 Word建议先用专门的解析工具转成 txt再用本文的方法做二次清洗和结构化。不要指望一个工具解决所有问题。3. 核心细节解析与实操要点3.1 编码检测中文 txt 的第一道坎中文 txt 文件的编码问题是最常见的坑。Windows 上很多老文件是 GBK 编码Mac 上默认 UTF-8还有一些是从网页复制粘贴的可能混着各种不可见字符。如果编码判断错了读出来的就是一堆乱码后面所有处理都没意义。我的做法是先用chardet检测编码但不完全信任检测结果。chardet对短文本的检测准确率不高所以我会加一个兜底逻辑先尝试用检测到的编码读如果读出来的内容包含大量替换字符\ufffd就换 UTF-8 再试还不行就试 GB18030。import chardet def detect_encoding(file_path): with open(file_path, rb) as f: raw f.read(10000) # 读前 10KB 做检测 result chardet.detect(raw) encoding result[encoding] confidence result[confidence] # 置信度太低时用候选编码列表逐个尝试 if confidence 0.7: candidates [utf-8, gb18030, gbk, big5] for enc in candidates: try: raw.decode(enc) return enc except UnicodeDecodeError: continue return encoding or utf-8这里有个细节gb18030是gbk的超集能覆盖更多生僻字所以优先试gb18030。另外读文件时建议用errorsreplace参数这样即使有个别字符解码失败也不会直接抛异常中断整个流程。3.2 文本清洗去掉那些看不见的噪声原始 txt 里的噪声比想象中多。常见的有多余空行连续多个空行影响段落识别行首行尾空白空格、制表符、全角空格不可见字符零宽空格、软连字符、BOM 头页眉页脚残留从 PDF 转来的 txt 经常带页码断行断句一句话被硬换行切成多行清洗策略要分情况。对于段落内的断行如果一行结尾不是标点符号下一行开头不是特殊标记大概率是同一段被切开了应该合并。对于页眉页脚可以用正则匹配常见的页码模式比如纯数字行、第 X 页这类。import re def clean_text(text): # 去掉 BOM 头 text text.lstrip(\ufeff) # 统一换行符 text text.replace(\r\n, \n).replace(\r, \n) # 去掉零宽字符 text re.sub(r[\u200b\u200c\u200d\ufeff], , text) # 去掉行首行尾空白 lines [line.strip() for line in text.split(\n)] # 合并被硬换行切断的段落 merged [] for line in lines: if merged and line and not re.match(r^[#\-\*\d\|], line) \ and not re.search(r[。\)】》]$, merged[-1]): merged[-1] line else: merged.append(line) # 压缩连续空行 result re.sub(r\n{3,}, \n\n, \n.join(merged)) return result.strip()注意合并断行的逻辑要谨慎。如果原文本身就有短行比如诗歌、地址列表强行合并会破坏原意。建议先在小样本上测试确认效果后再批量处理。3.3 结构识别从纯文本中提取骨架这是整个流程里最考验经验的部分。不同来源的 txt 文件结构标记方式完全不同。我总结了几种常见模式模式一用空行分隔段落用特定符号标记标题。比如或---包裹的标题或者以第X章、一、、1.1开头的行。模式二用缩进表示层级。常见于从网页或文档复制的文本缩进越多层级越深。模式三用固定格式标记。比如每行以[标题]开头或者用全大写行表示标题。针对这些模式我写了一套基于正则的识别规则def detect_structure(lines): markdown_lines [] for line in lines: stripped line.strip() if not stripped: markdown_lines.append() continue # 识别 Markdown 风格标题 if re.match(r^#{1,6}\s, stripped): markdown_lines.append(stripped) # 识别第X章类标题 elif re.match(r^第[一二三四五六七八九十百\d][章节篇], stripped): markdown_lines.append(f## {stripped}) # 识别一、二、类标题 elif re.match(r^[一二三四五六七八九十]、, stripped): markdown_lines.append(f### {stripped}) # 识别数字编号标题 elif re.match(r^\d\.\d\s, stripped): markdown_lines.append(f### {stripped}) elif re.match(r^\d\.\s, stripped): markdown_lines.append(f#### {stripped}) # 识别列表项 elif re.match(r^[\-\*\]\s, stripped): markdown_lines.append(stripped) elif re.match(r^\d\)\s, stripped): markdown_lines.append(re.sub(r^(\d)\), r\1., stripped)) else: markdown_lines.append(stripped) return markdown_lines这套规则不是万能的但覆盖了大部分中文技术文档的常见格式。实际使用时建议先拿几个代表性文件跑一遍看看识别结果再针对性调整正则。3.4 代码块与表格的特殊处理技术文档里经常有代码示例和表格这两类内容如果处理不好后续切块时会被切得七零八落。代码块的识别相对简单连续多行以相同缩进开头且包含编程语言特征如def、function、import、{、}等大概率是代码。识别出来后用包裹并尽量推断语言类型。表格的识别要复杂一些。纯文本表格通常用空格或制表符对齐或者用|分隔。我的做法是如果连续多行都包含|且列数一致就认为是表格转换成 Markdown 表格格式。如果是空格对齐的表格先按连续空格切分再判断列数是否一致。def detect_code_block(lines, start_idx): 从 start_idx 开始检测代码块返回结束位置和语言 code_lines [] i start_idx while i len(lines): line lines[i] if line.strip() : code_lines.append() i 1 continue # 代码特征判断 if re.search(r(def |class |function |import |#include|\?php|\{|\}|;\s*$), line): code_lines.append(line) i 1 else: break if len(code_lines) 3: return i, code_lines return start_idx, None实操心得代码块识别宁缺毋滥。如果误把普通文本识别成代码块后续切块时会把它当成一个整体反而影响检索。建议设置最小行数阈值比如 3 行低于阈值的按普通文本处理。4. 完整实操流程与核心环节实现4.1 环境准备与依赖安装先把环境搭起来。Python 3.8 以上都行依赖不多pip install chardet就这一个第三方库其他全用标准库。如果你需要处理更复杂的格式可以加markdownify或html2text但纯 txt 场景用不上。目录结构建议这样组织project/ ├── raw_txt/ # 原始 txt 文件 ├── cleaned_md/ # 转换后的 Markdown ├── logs/ # 处理日志 └── parser.py # 主脚本4.2 批量读取与编码处理批量处理时编码问题会更突出因为不同文件的编码可能不一样。我的做法是逐个文件检测编码记录到日志里方便排查问题。from pathlib import Path def batch_read(raw_dir): results [] for file_path in Path(raw_dir).rglob(*.txt): encoding detect_encoding(str(file_path)) try: with open(file_path, r, encodingencoding, errorsreplace) as f: content f.read() results.append({ path: file_path, encoding: encoding, content: content }) except Exception as e: print(f读取失败: {file_path}, 错误: {e}) return results这里用rglob而不是glob是为了支持子目录递归。实际项目中原始文件往往按类别放在不同子目录里递归读取能省不少事。4.3 清洗与结构化的完整实现把前面的清洗和结构识别串起来形成一个完整的处理函数def process_file(file_path): # 1. 检测编码并读取 encoding detect_encoding(str(file_path)) with open(file_path, r, encodingencoding, errorsreplace) as f: raw f.read() # 2. 清洗 cleaned clean_text(raw) # 3. 结构识别 lines cleaned.split(\n) md_lines detect_structure(lines) # 4. 代码块处理 final_lines [] i 0 while i len(md_lines): end_idx, code_lines detect_code_block(md_lines, i) if code_lines: final_lines.append() final_lines.extend(code_lines) final_lines.append() i end_idx else: final_lines.append(md_lines[i]) i 1 # 5. 输出 md_content \n.join(final_lines) output_path Path(cleaned_md) / (file_path.stem .md) output_path.parent.mkdir(parentsTrue, exist_okTrue) with open(output_path, w, encodingutf-8) as f: f.write(md_content) return output_path这个流程跑下来一个普通的 txt 技术文档就能变成结构清晰的 Markdown。我实测过一批 200 多个文件的技术文档转换成功率达到 95% 以上剩下的 5% 主要是格式特别混乱的扫描件转 txt需要人工介入。4.4 质量校验怎么知道转得好不好转换完不能直接就用得有个校验环节。我的校验方法分三层第一层自动检查。统计转换前后的字符数差异如果差异超过 20%说明可能丢内容了。检查 Markdown 标题数量如果原文有明显章节结构但转换后一个标题都没有说明识别规则没生效。第二层抽样人工检查。随机抽 10% 的文件人工看一遍转换结果重点看标题层级对不对、代码块有没有被误判、表格有没有散架。第三层下游验证。把转换后的 Markdown 拿去切块和向量化跑几个典型查询看召回结果是否合理。这是最直接的验证方式但成本也最高一般只在关键项目里做。def validate_conversion(raw_text, md_text): issues [] # 字符数差异检查 raw_len len(raw_text.replace(\n, ).replace( , )) md_len len(md_text.replace(\n, ).replace( , )) if raw_len 0 and abs(raw_len - md_len) / raw_len 0.2: issues.append(f字符数差异过大: 原始 {raw_len}, 转换后 {md_len}) # 标题检查 if # not in md_text and len(raw_text) 2000: issues.append(长文档但无标题识别) return issues提示质量校验的阈值不要设得太死。有些文档本身就没有结构强行要求识别出标题反而不合理。校验的目的是发现明显问题不是追求完美。5. 常见问题与排查技巧实录5.1 编码问题速查表编码问题是最高频的我整理了一个速查表现象可能原因解决方法中文显示为乱码编码判断错误手动指定 gb18030 重试部分字符显示为问号编码不支持该字符用 gb18030 替代 gbk文件开头有奇怪字符BOM 头未处理读取后 lstrip(\ufeff)读取时报 UnicodeDecodeError文件混用多种编码用 errorsreplace 兜底英文正常中文乱码误判为 latin-1强制用中文编码重试5.2 结构识别失败的典型场景结构识别失败通常有几种表现标题没识别出来、列表变成了普通段落、代码块被拆散。对应的排查思路标题没识别出来先看原文的标题格式是什么。如果是纯靠字体大小区分从 PDF 转来的txt 里根本没有标记那就没法自动识别只能靠人工或者用 PDF 解析工具重新处理。列表变成普通段落检查列表项的标记符号。有些文档用全角符号如、·正则里要加上这些变体。代码块被拆散检查代码块中间是否有空行。如果有detect_code_block里的空行处理逻辑要调整允许代码块内部有空行。5.3 性能优化批量处理提速处理大量文件时性能是个问题。我踩过的坑是一开始用单线程逐个处理1000 个文件跑了十几分钟。后来改成多进程速度提升了 4 倍多。from concurrent.futures import ProcessPoolExecutor def batch_process(raw_dir, max_workers4): files list(Path(raw_dir).rglob(*.txt)) with ProcessPoolExecutor(max_workersmax_workers) as executor: results list(executor.map(process_file, files)) return resultsmax_workers建议设成 CPU 核心数不要设太大否则 IO 竞争反而拖慢速度。另外如果文件特别多建议分批处理每批处理完写一次日志避免中途出错全部重来。5.4 那些文档里不会写的避坑经验坑一不要相信文件扩展名。有些.txt文件实际上是 HTML 或 RTF只是改了扩展名。读取后先检查开头几个字符如果是html或{\rtf要走不同的解析路径。坑二空文件要单独处理。批量处理时遇到空文件很多脚本会直接报错。建议先过滤掉大小为 0 的文件记录到日志里。坑三转换后的 Markdown 要保留原始文件路径信息。后续排查问题时你需要知道每个 Markdown 对应哪个原始文件。我的做法是在 Markdown 开头加一行注释!-- source: xxx.txt --不影响渲染但方便追溯。坑四不要一次性处理所有文件。先拿 10 个代表性文件跑通流程确认效果后再批量处理。我见过太多人直接跑全量结果发现规则有问题几千个文件白处理了。坑五保留中间结果。清洗后的文本、结构识别后的中间结果都建议存一份。调试时能省很多时间不用每次都从头跑。5.5 从 Markdown 到 RAG 切块的衔接转换完 Markdown 只是第一步接下来要切块。这里简单提一下衔接要点因为切块策略直接影响转换时的取舍。如果后续按标题层级切块转换时就要尽量保证标题层级准确。如果按固定长度切块那代码块和表格的完整性就更重要要确保它们不被切断。我的建议是转换阶段就考虑切块需求在 Markdown 里用空行明确分隔语义单元方便后续按空行或标题切分。另外Markdown 里的元信息如!-- source --注释在切块时可以选择保留或丢弃。如果保留检索时能追溯到原文如果丢弃块内容更干净。这个取舍看具体需求没有标准答案。6. 结构化解析的进阶思路6.1 从规则到模型什么时候该升级基于正则的规则解析优点是可控、可解释、无需训练数据缺点是泛化能力有限。当你的数据源格式差异特别大规则维护成本越来越高时就该考虑引入模型了。常见的升级路径有两种一是用序列标注模型识别标题、正文、代码块等结构元素二是用大模型直接做格式转换把 txt 丢给模型让它输出 Markdown。前者需要标注数据后者成本较高但效果通常更好。我的经验是数据源格式相对固定时规则足够用格式五花八门时模型更划算。不要为了用模型而用模型规则能解决的问题没必要上模型。6.2 结构化知识库与 RAG 的结合热词里提到了“kg知识库、rag知识库和结构知识库区分以及应用场景”这里简单说一下我的理解。RAG 知识库存储的是文本块和向量适合非结构化或半结构化的知识检索。结构化知识库如知识图谱存储的是实体和关系适合精确查询和推理。两者不是替代关系而是互补关系。在实际项目中我通常的做法是先用本文的方法把文档转成结构化 Markdown切块后存入 RAG 知识库同时从文档中抽取实体和关系构建轻量级的知识图谱。检索时RAG 负责语义召回知识图谱负责精确匹配和关系推理两者结合效果更好。这个思路在“ontology rag”和“rag智能体”这类场景里尤其有用。智能体需要的不只是相关文本还需要知道实体之间的关系才能做出更准确的决策。6.3 图片与多模态内容的处理边界热词里有人问“rag知识库能存储图片嘛”答案是能但处理方式不同。图片需要先做 OCR 或视觉理解转成文本描述后再存入知识库。纯 txt 解析流程不涉及图片但如果你的数据源是图文混排的建议先把图片单独抽出来处理文本部分走本文的流程。Markdown 对图片的支持很友好语法既能保留图片引用又不影响文本处理。转换时如果遇到图片引用保留 Markdown 语法即可后续切块时可以选择把图片描述作为文本的一部分。7. 我在实际项目中的几点体会做 RAG 数据导入这几年最大的体会是数据质量决定系统上限模型只是逼近这个上限。我见过太多团队在模型上砸钱却在数据清洗上省事最后效果不理想还找不到原因。另一个体会是不要追求一步到位。数据导入和解析是个迭代过程先跑通基本流程再逐步优化。一开始就想着把所有格式都完美处理往往导致项目迟迟无法上线。先处理 80% 的常见情况剩下的 20% 边跑边补这才是务实的做法。最后分享一个小技巧建立一个小型的“回归测试集”。挑 20 个有代表性的文件每次调整解析规则后都跑一遍对比转换结果。这样能快速发现规则改动是否引入了新的问题比全量跑一遍高效得多。这个系列后面还会讲 PDF、Word、HTML 等格式的解析以及切块策略和向量化实践。txt 转 Markdown 是最基础的一环但基础打牢了后面的路会好走很多。