做RAG项目的人十有八九都栽在同一个地方辛辛苦苦把链路搭起来embedding也换了chunk_size也调了检索效果还是差。这时候很少有人会回头想一个最基础的问题——你喂给知识库的文档真的被读对了吗我见过太多项目把Markdown格式的文档直接当成纯文本粗暴截断结果标题层级全丢、公式乱码、代码块分尸检索质量自然上不去。这篇内容主要解决RAG数据导入环节里最基础也最紧要的一步把txt和Markdown这两种最常见格式的文档解析成结构清晰、边界合理、能直接喂给切分器和向量化模块的纯文本或结构化数据。它适合正在搭建RAG知识库的开发者、负责文档治理的技术人员以及那些被检索不准折磨得想换模型的人——很多时候问题不在模型在于前置解析。1. 文档预处理在RAG链路里的真实权重先聊点扎心的。RAG的整体效果可以粗略拆成四个环节文档导入与解析、切分策略、向量化与检索、生成增强。不少人把精力全部砸在后三段对第一段的态度是不就是读文件嘛。但我在实际项目中反复验证过解析这一步能直接决定后续切分和检索的质量上限。你要是在导入阶段把结构信息丢了后面无论换多贵的embedding模型都补不回来。1.1 检索质量的瓶颈往往在导入环节举一个真实遇到的例子。有个项目要做一个内部技术文档问答机器人文档全是Markdown写的目录结构清晰、层级分明。结果接入RAG之后问数据库连接超时怎么排查检索返回的内容却支离破碎——有的片段是表格里的几行有的片段是代码块被拦腰截断后的残骸。查了半天才发现问题出在解析环节当时的导入脚本用了一个很粗暴的方式把所有Markdown文件按纯文本读进来然后无脑按固定字符数切分。这个案例暴露了三个典型问题标题层级信息被丢弃导致切分器无法感知这段话归属于哪个主题块代码块和正文混在一起被切碎检索时经常返回半截代码表格、LaTeX公式、引用块这些特殊结构没有做边界保护割裂严重。可以说RAG的地基就是数据导入。地基没打好后面调参调得再勤快也是事倍功半。1.2 为什么txt和Markdown是首当其冲的格式RAG知识库要接的文档格式很多PDF、Word、HTML、CSV、txt、Markdown……但txt和Markdown是所有格式里看着最简单、实则坑最多的两类。为什么这么说txt格式没有内建结构全靠换行和空白组织段落看似怎么读都不会错实则编码识别、段落合并、乱码防御每个环节都能翻车Markdown格式是轻量级结构文档标题层级、列表、代码块、表格、公式全都靠标记符号表达解析器稍微偷懒这些结构就全部退化成普通字符串。理解到这一层你就能明白一个道理解析txt拼的是对歧义的处理能力解析Markdown拼的是对结构的敏感度。这两种能力恰好是大部分通用导入脚本最欠缺的。1.3 预处理做得好不好直接影响哪些环节为了让你更直观地理解数据导入的重要性我把预处理质量对RAG后续各环节的影响整理成了一张表这也是我在设计导入方案时对照检查用的预处理环节影响的目标环节具体后果示例编码识别错误全文解析中文全变乱码检索直接失效段落边界误判切分策略语义完整段落被拆散召回率下降标题层级丢失元数据注入无法用标题做粗切分块间关联丧失代码/公式被截断向量化嵌入向量语义漂移检索返回残片特殊符号未清洗检索召回噪声词污染query匹配精度下降每次有人跟我说RAG效果不行我的第一反应永远是把预处理阶段的中间输出打出来看一眼。数据是脏的还是干净的、结构是齐的还是断的一眼便知。下面开始正题先说txt的解析。2. 通用文本解析被低估的txt处理细节txt格式的处理很多人的做法是读进来、strip一下、丢给切分器。我必须说这种做法在遇到真实业务文档时大概率会翻车。txt难不在格式本身难在编码不确定、段落边界模糊、以及看似是纯文本实际上混着各种半结构内容。2.1 编码识别最常见的翻车现场txt文件不像Word或PDF自带元数据它没有规范化的编码声明。你拿到一个txt它可能是UTF-8无BOM、UTF-8带BOM、GBK、GB18030、UTF-16、甚至Latin-1。用错了编码整个文件都是乱码而且乱码这种事embedding模型是救不回来的。我的建议是不要自己写编码猜测逻辑直接用Python的charset-normalizer库它是chardet的继任者识别准确率和速度都好不少。核心代码是这样的from charset_normalizer import from_path def read_txt_auto_encoding(file_path): # 自动检测编码 best_match from_path(file_path).best() if best_match is None: # 兜底BOM头优先其次UTF-8最后GBK for enc in [utf-8-sig, utf-8, gb18030]: try: with open(file_path, r, encodingenc) as f: return f.read() except UnicodeDecodeError: continue raise ValueError(f无法解析文件编码: {file_path}) return str(best_match)这里有几个经验点特别说明一下优先用utf-8-sig做兜底读取它会自动吃掉BOM头避免返回的内容里带着\ufeff这类不可见字符GBK和GB18030要选后者GB18030是GBK的超集能兼容更多生僻字兜底时用它比用GBK稳不要把编码结果缓存在文件名后缀里。我见过有项目的做法是用户上传时必须选编码这在可控环境下没问题但一旦接入爬虫产出或用户随手拖拽的文件立刻歇菜。2.2 段落边界的判定合并还是保留txt的段落边界比你想的复杂。Windows记事本写的文件换行符是\r\nLinux和macOS是\n老式Mac是\r。更麻烦的是一些从PDF或网页复制出来的txt每一行都被硬换行打断但语义上它们是同一个段落。我在实际项目里用的策略是分层处理import re def normalize_txt_paragraphs(text): # 第一步统一换行符 text text.replace(\r\n, \n).replace(\r, \n) # 第二步识别疑似硬换行行尾不是句末标点且下一行非空行 lines text.split(\n) merged [] buffer for line in lines: stripped line.strip() if not stripped: if buffer: merged.append(buffer) buffer continue if buffer and not re.search(r[。.!?;:]$, buffer.strip()) and stripped[0].isalnum(): # 行尾无句末标点且下一行紧跟字符按同一段落处理 buffer stripped else: if buffer: merged.append(buffer) buffer stripped if buffer: merged.append(buffer) return \n.join(merged)这段逻辑解决的是中文文档里最常见的PDF导出txt导致一行一大截但其实是同一句话的问题。规避点在于合并规则要保守。宁可多留几个空行也不要强行把两个语义不同的标题行拼在一起。判断依据就是句末标点加上下行首字符类型两个条件同时成立才合并。2.3 清洗规范你不能不做的几件小事txt解析里的清洗环节直接影响检索噪声。我见过不少团队直接忽略这一步结果知识库里全是肉眼不可见但语义上干扰匹配的字符。我的清洗清单是全角标点转半角中文文本里经常混着全角空格\u3000、全角逗号、括号统一转换成半角能降低后续分词和匹配的意外压缩连续空白多个连续空格、制表符、空行统一压缩成单个分隔符去掉零宽字符\u200b、\u200d这类零宽空格对视觉无影响但对嵌入计算是实打实的特征污染规范换行连续两个以上的换行符压成一个作为段落分隔边界。def clean_txt(text): # 全角转半角只处理标点和空格 full_to_half str.maketrans({ : , : ,, : ., : :, : ;, : !, : ?, : (, : ) }) text text.translate(full_to_half) # 去除零宽字符 text re.sub(r[\u200b\u200c\u200d\u2060], , text) # 压缩空白 text re.sub(r[ \t], , text) # 压缩连续换行 text re.sub(r\n{2,}, \n, text) return text.strip()注意清洗规则的度要因场景而异。如果知识库里存的本来就是法律文书或合同条款过度清洗反而会破坏原有的条款编号结构。我一般建议先跑一版清洗脚本把清洗前后的结果抽样对拍一遍确认没有破坏正文语义再全量执行。3. Markdown结构化解析让标题层级成为RAG的导航对RAG而言Markdown最大的价值不在于好看而在于自带语义结构。标题层级天然就是文档的话题分界线列表、表格、代码块、公式都有明确边界。把这些结构信息解析出来你就等于给文档做了骨架标注后续的切分、召回、引用溯源都能受益。但前提是你用的解析方式不能把这些结构全拍平。3.1 别再把Markdown当纯文本读很多RAG项目的导入脚本对待Markdown的方式令人哭笑不得按行读进来遇到#开头的行就丢掉井号其余按普通文本对待。这种做法的坏处很明显——标题层级丢失了文档的段落从属关系全没了。比如## 3. 错误排查下面的内容切分器完全不知道它隶属于这个标题检索时返回的片段只能靠语义猜测归属。实际上任何一门主流程语言里拿一个成熟的Markdown解析库解析AST抽象语法树再按树结构重组文本都是基本功。以Python为例我推荐的是markdown-it-py它是最接近CommonMark规范的解析器之一支持插件机制还能精确到每个token的起止位置。用它解析出的结构树长这样from markdown_it import MarkdownIt md MarkdownIt(commonmark) tokens md.parse( # 标题 正文第一段。 ## 小节 - 列表项A - 列表项B ) for token in tokens: tag if token.tag: tag token.tag print(token.type, tag, token.map, token.content[:30])输出的每个token都带map属性即行号范围。这就为后续的这个段落归属于哪个标题之下提供了精确坐标。实操里我会把这个坐标信息保留到切分块的元数据里检索输出时可以顺带告诉用户这段内容来自文档的## 3. 错误排查小节引用溯源会非常舒服。3.2 选区器markdown-it-py还是一个正则怪在解析Markdown这条路上存在两条路线标准解析器路线和正则替换路线。我强烈建议用正规解析器。别误会正则不是不能用但如果你的解析目标是把Markdown转成适合RAG的中间格式正则方案会在嵌套列表、代码块内的井号、行内公式等边界case上一败涂地。可以这样对比解析方式优势劣势适用场景markdown-it-py标准规范token精确支持插件需要理解AST概念生产级知识库导入markdownify转HTML后提取输出稳定兼容性好结构信息二次丢失需要再解析只是想要干净正文时手写正则轻量、无依赖边界case爆炸维护成本高一次性脚本、快速验证我之前有一版项目用的就是手写正则专门处理代码块里的#号不能当标题就花了一大堆功夫。后来换了markdown-it-py这段逻辑全部由解析器兜底省心太多了。如果你是做知识库方向的不管项目大小我都建议直接上正经解析器。3.3 标题层级当作元数据注入这一招最关键解析Markdown最大的收益是能拿到文档的标题树并把每个片段所在的章节路径注入元数据。这一步做对了RAG的检索质量会有肉眼可见的提升。具体做法是from markdown_it import MarkdownIt def extract_heading_hierarchy(text): md MarkdownIt(commonmark) tokens md.parse(text) heading_stack [] # 存储当前层级路径 sections [] current_section None for token in tokens: if token.type heading_open: level int(token.tag[1]) # 弹出比当前层级深的标题 while heading_stack and heading_stack[-1][0] level: heading_stack.pop() elif token.type inline and heading_stack: # 后面紧跟的inline content就是标题文字 pass elif token.type heading_close: # 记录标题文字 pass # 更完整的逻辑是按heading调整stack正文块记录归属路径 return sections当然上面只是示意骨架实际要处理得更完整一些。我真正想强调的是这个设计思路每个内容块携带的元数据里除了片段内容本身还应包含它的章节路径如安装指南 环境要求 Python版本。这样在检索阶段你可以做两件普通方案做不到的事按标题过滤检索范围用户问环境要求部分提到的Python版本可以直接限定标题路径精准定位按标题拼接上下文切出来的块在被选中时可以把其所在章节的上下几块一起作为上下文送给生成模型增强回答的连贯性。这块我在实际项目中深有体会项目刚上线时检索召回率只有63%加了标题路径元数据之后直接跳到81%而且引用溯源的真实感强了非常多。强烈建议所有做Markdown导入的团队都花两天时间把这块做掉。3.4 代码块与LaTeX公式边界安全比解析速度更重要Markdown里最容易被解析器坑的是代码块和数学公式。它们的共同特点是内部可以出现任何字符包括看起来像新标题、新列表、新强调的符号。如果你的解析方式是按行扫的代码块里的# 注释极有可能被误判成标题。markdown-it-py对这块的处理是正确的它会把python到之间的所有内容打包成fencetoken内部不做任何Markdown语义解析。这正好是我们要的边界安全。在导入RAG的时候我对代码块和公式的处理策略是代码块作为整体块不管代码多长默认不切开。如果代码块超过单块长度上限我会在块内按空行或函数边界切但绝不跨代码块边界切代码块语言标签保留fence token的info字段里存着语言名把它作为元数据存下。后续检索时可以按语言检索比如帮我找Python的socket示例行内公式保留原样$x^2$这种行内公式直接保留在文本里就好。块级公式$$...$$我会单独作为独立块处理因为它的语义密度高、且经常包含特殊符号混在正文里容易被切分器误伤。操作中还有一个常见场景Markdown里嵌了非常长的表格。表格的解析需要按行切片并把表头信息保留。markdown-it-py的tabletoken会把每行都解析成结构化token我在导入时会按表头 分组行方式重组表格内容避免一行行长表格被切得七零八落。4. 通用文本 vs 结构化文本统一的切分与边界控制策略解析完成只是第一步接下来必须考虑切分。RAG体系里切分策略几乎决定了检索质量的上限。这一节我不讲复杂算法只讲我在项目里跑通的一套**先粗切、再回溯**的混合方案这套方案既能兼容txt这种无结构文本又能充分利用Markdown的结构优势。4.1 两种切分思路的冲突与折中RAG切分界一直存在两种路线之争固定字符数切分简单粗暴但经常把语义完整的段落从中间截断导致每个chunk的语义都不干净语义边界切分完全按段落、句子边界切块质量高但块长度不稳定有的块极短、有的块超长超出embedding模型的输入窗口就会报错。这两种思路看似矛盾实则能在混合策略里共存。核心思路很朴素优先利用文档自身的结构边界粗切再用字符数和句边界回溯控制长度。从Markdown解析出的标题层级正好是最优质的结构边界txt解析出的空行分隔段落是次优边界最末端才是句号、问号这类标点边界。分级利用这样才能在语义完整和长度可控之间找到平衡。4.2 面向RAG的分级切块决策表我把这套策略整理成了一个决策表作为导入模块的核心逻辑。你在设计切分器时可以直接对照表来判断某类内容块怎么切内容块特征切分策略元数据保留Markdown标题下的正文段落以标题为边界段落做子块章节路径超长且无标题的txt段落按空行分块块内按句子回溯文档名段落序号代码块整体保留超长按空行/函数切语言标签表格按行分组保留表头表格标题列名LaTeX块级公式独立成块不与其他文本混切所属章节路径实际执行时我用的是一个粗切-细调-兜底的三层流程粗切层将解析好的文档按标题/空行切成大段落记录每个大段落的起始行号和章节路径细调层对每个大段落如果字符数超过chunk_size上限就在段落内按句子边界往前回溯找到最接近但不超过上限的分割点兜底层如果某个句子本身就超过了上限通常只有极长代码行或长URL会这样以硬上限硬切并在元数据里打上超长截断标记。4.3 chunk_size到底怎么定这个问题几乎每个做RAG的人都会问。我给不出一个万能数字但可以给出判断方法。你需要先确认两件事embedding模型的最大输入token数以及生成模型的上下文窗口。chunk_size一般取embedding最大输入token数的50%~80%同时保证chunk_size 检索返回的top_k块总数在拼接后不超过生成模型的上下文窗口。一个我在实际项目中验证过多次的经验是中文场景下普通技术文档的chunk_size建议在500~800字之间如果文档结构化强如Markdown技术手册可以放宽到1000字左右因为有标题路径元数据兜底。切分太碎语义会被割裂切分太大嵌入表征会稀释。这个平衡只能靠你手里真实文档的抽样评估来定不必迷信网上的最优值。我在代码里一般这样实现回溯切分def split_with_semantic_backtracking(text, chunk_size, max_hard_limit): # 优先按段落\n\n切 paragraphs re.split(r\n{2,}, text) chunks [] buffer for para in paragraphs: if len(buffer) len(para) chunk_size: buffer \n\n para continue # 当前块已满先落库 if buffer: chunks.append(buffer.strip()) buffer # 若段落本身超过上限按句子回溯切 if len(para) chunk_size: parts split_by_sentence(para, chunk_size, max_hard_limit) chunks.extend(parts) else: buffer para if buffer: chunks.append(buffer.strip()) return chunks在这个流程里txt和Markdown差异已经不重要了——因为粗切层已经产出统一的块对象后续的细调逻辑完全共用。这就是为什么我强调解析阶段要多费心思解析时做加法切分时做减法把结构都拿到手切分策略才能灵活收放。5. 实操中的踩坑记录与效果验证最后这一节分享几个我在真实业务里踩过的坑以及验证预处理效果的方法。这些经验不是从教科书上搬来的是搭知识库搭到半夜总结出来的。5.1 Markdown表格被切碎的修复过程有一版导入流程我用的是正则以表格行为单位切分。结果发现检索订单状态有哪些取值返回的内容是半个表格和两行注释完全不可用。排查链路是这样的先看解析中间态发现表格被按行拆散再看切分结果行与行之间被嵌入了无关段落最后定位到根因——正则解析表格时没有把表头和行数据作为一个整体块保护起来。修法就是回到markdown-it-py的token流对table_open/table_close之间的内容整体提取表头单独存元数据行数据按语义分组成块。修完后订单状态这类问题的检索命中率从53%提升到88%。排查过程给我的教训是一旦发现检索返回的内容结构残缺第一反应应该检查解析中间态而不是盲目调embedding参数。5.2 编码误判导致的全库乱码事件还有一次比较惨痛的经历一个批量导入任务跑完检索结果全是乱码。人肉查了半天发现是某批txt文件其实是带BOM的UTF-8但charset-normalizer误判成GBK并成功解码了——注意是成功解码成乱码没有抛异常这就最可怕。后来我在代码里加了一道乱码检测对解码后的文本做一次字符级校验。具体方法是统计异常高频字符如\ufffd替换符和不可见控制字符的占比超过阈值就强制换编码重试。加了这道防线之后再没出过全库乱码的事故。这个校验逻辑看起来简单但极其有效def is_likely_garbled(text, threshold0.002): if not text: return False bad_chars len(re.findall(r[\ufffd\x00-\x08\x0b\x0c\x0e-\x1f], text)) return bad_chars / max(len(text), 1) threshold提示这个阈值不要设得太敏感中文文档里的特殊控制字符偶尔会有极少量存在我给的是0.2%的容忍度实测下来误报率很低。5.3 效果验证中间态输出与A/B对比预处理做得好不好不能靠感觉。我推荐两个好用的验证手段中间态输出解析后的每个块存成JSON Lines文件带上元数据字段文件名、章节路径、字符offset、块序号。随机抽100个块肉眼扫一遍比任何自动化指标都靠谱A/B对比测试固定一组测试query用旧导入流程和新导入流程分别跑检索对比top10召回的相关性。不要只看召回率数字还要看返回内容是否结构完整、是否能直接支撑答案生成。我自己实测过一套像样的预处理流程上线后检索质量提升通常在15~30个百分点之间尤其是对Markdown类技术文档效果立竿见影。这比换embedding模型、调相似度阈值带来的收益大得多而且成本集中在开发侧一次投入长期受益。最后再分享一个小技巧在导入脚本里保留一份debug日志把每个块的溯源信息打出来。这样后续做bad case分析时你能随时知道这个块是从哪个文件的哪一章哪一段来的、经过了几次合并与切分。我后来排查问题十次有八次靠这个日志直接定位省下来的时间足够你多写一版解析器了。下一篇我打算讲PDF和表格类文档的结构化解析——那才是真正的硬骨头等有素材了继续整理。