搞RAG这么长时间我越来越觉得一个朴素的真理知识库的效果上限在数据导入那一刻就已经定死了。很多人兴冲冲搭好向量数据库、调好Prompt模板满心期待AI能精准回答业务问题结果检索回来的全是被切得七零八落的文本碎片模型再聪明也只能“戴着镣铐跳舞”。问题出在哪十有八九不在模型侧而在源头——喂进去的文本本身就没处理好。这篇是我“RAG数据导入与解析”系列的第一篇不聊多炫酷的框架只聊最基础也最关键的一环怎么把txt这类通用文本干净利落地解析成Markdown再按结构切块让检索真正有据可依。内容适合正在搭建RAG知识库的开发者、做文档问答产品的同学以及刚接触文本预处理的初学者。1. 先想清楚RAG 的数据导入到底在解决什么问题1.1 解析质量决定了检索质量的上限RAG的核心流程说白了就三步把文档切块、把块向量化、把检索结果喂给大模型。但很多人忽略了一个前提——切块之前你得先让程序“看懂”文档。我在实际项目里见过太多这样的情况一个PDF转出来的txt段落之间夹着页码、页眉、页脚表格变成了乱序数字标题和正文糊在一起。这种脏文本丢给切片器后果就是一个语义完整的段落被拦腰截断嵌入向量时信息丢失目录、页码混进正文检索时频繁命中无关片段原本的层级结构被抹平回答问题时“只见树木不见森林”。为什么强调解析质量决定检索质量的上限因为向量检索本质上是在“文本块”上做相似度匹配块的边界是否贴合语义直接决定了命中率。如果你把三个不同主题的内容揉进同一个chunk那么不管embedding模型多强它都很难准确表达这个chunk的语义反过来如果你把一个完整观点切断成两个chunk那么检索时可能只召回一半生成时就会胡编。所以说解析质量就是RAG工程的第一道生死线这一关过不去后面调什么都像在沙滩上盖楼。1.2 为什么偏偏选中 txt 和 Markdown 当中间格式这背后其实是工程上“先统一、再处理”的思路。真实业务场景里数据源千奇百怪Word、PDF、HTML、扫描件、Excel、JSON每一种都有自己的一套解析方案和坑。如果每接一种格式就写一套定制逻辑维护成本会爆炸。我的做法是把所有来源先统一成两种中间格式——纯文本txt和结构化的Markdown。纯文本用于通用清洗与初步切分Markdown用于恢复层级结构和语义信息。这样做有几个实打实的好处解析链路解耦PDF解析、OCR、网页抓取的结果全部先落到txt后续流程只认txt换数据源时无需改动核心管线Markdown是“半结构化”的文本可以表达标题层级、列表、表格、代码块但又没有XML/JSON那么严格的语法负担对LLM和传统NLP工具都友好生态成熟txt和Markdown几乎是所有编程语言、所有文本处理库都原生支持的格式处理成本最低。有人会问为什么不直接用JSON或数据库存结构化数据答案很简单RAG检索需要的是“语义粒度”的信息单元而结构化数据库擅长的是字段精确匹配两者定位不同。Markdown正好卡在中间——既有结构又能保持文本的连续性和语义完整性。这也解释了为什么现在很多RAG框架的文档解析器都选择Markdown作为标准中间格式它不是最炫的但一定是最稳的。1.3 一条主流方案的完整链路在进入细节之前先把整条链路画个轮廓免得后面陷进细节里出不来。我目前在生产环境跑得比较稳的一条路径是原始文档 → 内容抽取PDF/Word/HTML等 → 统一转出txt → 文本清洗与编码修复 → 规则启发式识别结构 → 转成Markdown → 按语义切分chunk → 附加metadata → embedding → 写入向量库。这条链路里真正决定效果差异的是中间的“文本清洗”和“结构识别”两个环节。前者决定文本干不干净后者决定结构准不准。很多团队把时间花在对比embedding模型、调向量库参数上却忽略了这两个基础环节结果自然是事倍功半。后面所有实操都围绕这两个环节展开先把基础打牢再谈上层优化。2. txt 通用文本预处理一半时间都在跟“脏数据”搏斗2.1 编码识别与统一第一个拦路虎txt是“通用”但“通用”的代价是它自身不携带编码信息。现实世界里你拿到的txt可能是UTF-8、GBK、GB18030、BIG5、Latin-1甚至部分日文Shift-JIS。如果直接用错误编码读取轻则个别字符变成“锟斤拷”GBK转UTF-8的经典事故重则整篇乱码无法使用。这个坑几乎每个做文本处理的人都踩过区别只是踩得深不深。我在处理时用的套路是三步走先探测、再转码、最后验证。探测编码阶段文件不大的时候用chardet或charset-normalizer这类库做统计推断文件多的时候我会先用file命令或读取文件前几百字节的BOM标记做快速预判减少全量探测的开销。需要注意chardet对短文本、混合编码文本的准确率并不高所以关键文件我会追加“抽样人工复核”。统一转成UTF-8是后续所有处理的大前提前端展示、embedding模型、JSON传输基本都以UTF-8为准。转码之后做一轮规则检查例如统计UFFFD替换字符的数量、扫描是否残留“锟斤拷”“烫烫烫”这类典型乱码特征发现问题就回到探测环节重新处理。注意不要盲信所有txt都能无损转成UTF-8。如果原始文件本身是GBK且包含少量非法字节转码会出现内容丢失。实际操作中我会对关键文档保留一份原始副本并在metadata里记录原始编码方便追溯。2.2 清洗规则哪些字符该删哪些该留清洗不是把所有“看起来奇怪的字符”都删掉而是有策略地处理。我在实践中总结了一组优先级排序的规则不可见控制字符如\x00、\x1A直接删掉它们通常是二进制文件误当文本解析的产物零宽字符Zero Width Space、Zero Width Joiner等视场景处理多数场景删掉但如果要保留某些阿拉伯文或复杂排版语义就不能一刀切重复的空格和空行压缩为单个但要注意Markdown里的多空格可能有语义比如表格对齐、行首缩进所以这个规则要放在“转Markdown之前”短暂使用。页码、页眉页脚这类“重复噪声”要判断来源。如果文本里出现大量类似“第 12 页 / 共 34 页”的规律性片段我会用正则做模式匹配删除而不是死记硬背具体内容。OCR产生的“疑似错字”比如l和1混用只能靠词典和上下文校正规则引擎只能处理最明显的case。清洗的尺度需要根据下游用途调整。如果下游是给LLM做RAG我倾向于“保守清洗”——只删确定无用的控制字符和明显噪声尽量保留原始措辞。为什么因为大模型对原文的措辞、标点和语序很敏感过度清洗会导致检索时query和文档的措辞距离被拉大降低召回率。这个反直觉的结论是我在多个项目里验证过的常规的“清洗得越干净越好”在RAG场景下并不总是成立。2.3 段落边界与文本块的切分策略清洗之后最大的难点是“怎么切”。规则切分和语义切分我之前都试过现在生产环境用的是“层级回退”策略。第一遍先用换行符和空行作为硬边界把文本切成“物理段落”。这一步不追求语义完整只求把明显分开的内容切干净。第二遍对特别长的物理段落比如一段超过800字再用句号、问号、感叹号配合启发式规则做软切分。第三遍如果段落还很短比如只有一句话就把相邻段落合并直到块长度落在目标区间。这里有个重要的经验切分粒度要和下游embedding模型的最大输入长度对齐。我之前吃过亏用支持512 token的模型却把chunk切成2000字结果向量化时长文本被截断检索质量大幅下降后来改成“模型上限的80%作为目标长度”才稳定。还有一点值得强调段落边界不是一个绝对的“正确”答案而是一个需要根据业务调参的变量。我的建议是先用一套保守默认值跑通全链路再按检索效果迭代而不是一上来就追求完美切分。3. 从 txt 到 Markdown把“扁平”文本升级为“结构化”文本3.1 不要小看 Markdown 的结构化价值很多人觉得Markdown只是写博客用的没什么技术含量。但放在RAG场景里Markdown的价值其实被严重低估了。我举个实际例子一份产品使用手册txt形式下是“3.5 配置网络设置”后面跟着一段说明文字。程序看起来它和其他正文没有任何区别——就是个普通段落。但一旦转成Markdown这个标题就变成了### 3.5 配置网络设置它给下游传递了两个关键信息第一这段文本是某个层级的标题第二它后面所有的正文都归属于这个标题之下。这两个信息对RAG的意义是巨大的搜索时如果用户问“怎么配置网络”系统可以优先在标题里匹配命中率明显更高切块时标题可以当作天然的边界锚点避免把一个主题下的内容切割到两个chunk里回答时可以把“标题路径”比如 文档 → 第三章 → 3.5节拼进metadata模型回答问题后可以顺带告诉用户“答案出自文档第三章3.5节”这种溯源能力在知识库场景里几乎是刚需。所以从txt到Markdown本质上是“把扁平文本恢复出它的骨架”。这套骨架就是后续所有检索策略的地基。没有它你的知识库就是一堆没有目录的散页有了它每段文本都知道自己属于哪里。3.2 标题层级重建从“看起来像标题”到“真是标题”这是整个解析流程里最考验经验的一步。txt文件里通常没有H1/H2这种概念标题只是“看起来像标题”的一行文字。要把它识别成“真是标题”我一般组合使用三组信号。视觉信号行首是否有#、Chapter、第X章、3.5这类模式该行是否短于某个长度阈值比如少于50字该行末尾是否没有句号。上下文信号该行后面是否紧跟一段正文该行前后是否有空行在整个文档里这个模式是否重复出现且层级递增。统计信号同一文档里格式相似的“疑似标题”是否成簇出现成簇则可信度更高。识别之后还有个关键操作标题编号级别的推断。我遇到过不少txt把1.2.3当成一个标题但前面的1.2和1都丢失了。这时我会用“前缀路径补齐”逻辑根据当前编号的前缀自动把缺失的父级标题补出来。比如文本里只有一个3.5 配置网络设置我会在它的metadata里同时记录父级路径文档 → 3 → 3.5这样检索时依然能定位到准确章节。这个补齐逻辑在实战里非常有用尤其是处理从网页或PDF转出来的碎片化txt时几乎每次都能捞回丢失的层级信息。3.3 列表、表格、代码块的识别与保留Markdown不仅仅是标题它还承担了列表、表格、代码块这些语义容器的表达。这部分不做你得到的依旧是“换了样式却没有灵魂”的文本。我的处理原则是“能识别成结构元素的优先识别不要一律当普通文本”。列表文本里以-、*、1.、1)开头的行如果连续两行以上我会合并成一个列表块保留有序/无序属性。这个在切块时很重要因为列表天然是“逐项独立语义”适合作为微检索单元。表格txt里的表格通常表现为“竖线分隔的行”或“对齐空格列”。竖线分隔的比较容易转成Markdown表格对齐空格列的我会先用启发式规则做列对齐检测再生成表格。表格列数超过6列或单元格内容超过100字时我会考虑切块时拆成多行因为太宽的表格embedding效果极差强制整表嵌入只会拉低检索精度。代码块以缩进或反引号包裹的连续文本我会统一转成markdown代码块并加注语言类型如果能推断。代码块在检索时有独特的价值但也要注意代码块往往很长单个chunk可能装不下我会额外做“按函数/按逻辑行切分”。这里的实操心得是识别结构元素时一定要在生成Markdown的同时输出一份“结构元数据”。比如识别出一个表格就在metadata里记录“这是一个表格行数6列数4”而不是等到检索时再回头猜。我把这种做法叫“解析时顺手打标”后续能省很多事。3.4 metadata 的顺带抽取顺着上面的思路我会在转Markdown的阶段同步抽取几类常用的metadata而不是等切块之后再做。原因很简单某些结构信息比如标题路径、表格行列数一旦失去了原始上下文后续很难再找回来。常见metadata包括文档级的来源文件名、来源URL、文档类型、创建时间、处理时间、语言结构级的标题路径如文档/3/3.5、所在章节层级、是否为列表/表格/代码块内容级的关键词、首次出现的自定义标签、标题文本本身。抽取metadata的原则是“宁可多存不要少存”。向量检索的metadata往往用于做过滤filter多几个字段就能多做几种查询维度。我之前在知识库里加了“文档类型”这个filter后来做按照资料类型筛选的问答功能时几乎零成本就实现了。还有一个容易被忽略的点metadata里存标题路径不只是为了过滤更是为了在生成回答时把引用来源展示给用户。这个功能在文档问答、客服知识库、企业内网搜索里都是标配提前存好路径字段后面做UI展示时直接取用不用再回头解析文本。4. 实操落地搭一条可复制的 txt → Markdown → Chunk 流水线4.1 工具选型为什么我选这套组合这几年RAG工具链的更新速度非常快从LangChain、LlamaIndex到Spring AI、LangChain4j各有拥趸。我的选择原则是核心解析环节不依赖重量级框架尽量用轻量组件自己拼。原因很实际框架层封装度高方便是方便但一旦遇到“独特格式的数据源”或者“性能瓶颈”封装的抽象反而会变成障碍。我在生产环境里的解析链路用到的核心组件如下语言与运行时Python 3.10配合Pydantic做数据结构校验编码探测charset-normalizer比chardet在短文本上更稳文本切分与清洗纯Python 正则没有引入超大的NLP库因为清洗规则高度定制通用库反而帮不上忙结构识别自研的轻量规则引擎大概400行代码专门处理标题层级、列表、表格、代码块Markdown生成自己拼字符串不用现成库因为要做自定义的结构打标向量化与检索视项目而定常用Ollama本地embedding或OpenAI的text-embedding-3-small配合ChromaDB/PostgreSQL pgvector做向量存储。这套组合的优点是每个环节都能独立测试、独立替换。缺点是“看起来很土”没有一行的框架魔法。但实测下来生产环境稳定性和排障体验远好于一个大型框架的黑盒。如果你团队里有人特别执着于LangChain的那套抽象我不反对但至少解析环节建议自己控制这是整个RAG管线里最需要“手感和经验”的部分。4.2 核心代码骨架与关键参数下面这个骨架是我从生产代码里简化出来的删掉了业务定制部分保留了最核心的流程。它完成了“txt读入 → 清洗 → 转Markdown → 语义切块”的全过程import re from pathlib import Path def read_txt_auto_encoding(path: str) - str: 读取txt并自动处理编码返回UTF-8文本。 import charset_normalizer raw Path(path).read_bytes() match charset_normalizer.from_bytes(raw).best() return str(match) def clean_text(text: str) - str: 保守清洗去除控制字符和明显噪声不做过激的改写。 # 去掉控制字符保留换行和制表符 text .join(ch for ch in text if ch \n or ch \t or ord(ch) 32) # 去除常见的OCR页眉页脚噪声按需定制 text re.sub(r第\s*\d\s*页\s*(/.*)?, , text) # 压缩连续空行为标准段落分隔 text re.sub(r\n{3,}, \n\n, text).strip() return text def detect_title_level(line: str) - int | None: 判断一行是否为标题返回层级不是标题返回None。 if len(line) 60 or line.endswith(。): return None patterns [ (r^#{1,6}\s, 1), # 手动Markdown标题 (r^\d(\.\d)*\.?\s, 2), # 1.2.3 格式编号 (r^第[一二三四五六七八九十百千0-9][章节部分]?\s*, 3), # 第X章 ] for pattern, level in patterns: if re.match(pattern, line): return level return None def txt_to_markdown(text: str) - str: 把清洗后的txt转成Markdown重点恢复标题层级。 lines text.split(\n) out [] for line in lines: level detect_title_level(line.strip()) if level: out.append(f{# * (level 1)} {line.strip()}) else: out.append(line) return \n.join(out) def semantic_chunking(md: str, min_len200, max_len800, overlap50): 按标题段落边界切块返回chunk列表和标题路径。 chunks [] current [] current_path [] title_pattern re.compile(r^(#)\s(.*)) for line in md.split(\n): m title_pattern.match(line) if m: # 标题作为天然边界先落盘当前内容 if current: chunks.append(( .join(current_path), \n.join(current))) current [] level len(m.group(1)) title m.group(2) current_path current_path[:level - 1] [title] else: current.append(line) if current: chunks.append(( .join(current_path), \n.join(current))) return chunks这段代码里min_len、max_len、overlap三个参数的取值逻辑是max_len设置为你所用embedding模型最大token数对应的中文字数。以text-embedding-3-small为例它的上下文是8191 token但为了节省成本和保证精度我通常把chunk上限设在1500~2000字之间。overlap设成max_len的10%~20%保证跨chunk的语义衔接检索时若首尾相关两个chunk都能被召回。4.3 chunk 大小、重叠与 embedding 的配合这里给出一组我在中文知识库项目里实测过比较稳的起步参数你可以按自己的模型调整参数起步值说明chunk_min_len200字低于这个长度的chunk通常信息量不足检索时容易被噪声淹没chunk_max_len1500字中文约等于1000~1100 token留出余量给overlapchunk_overlap150字约为max_len的10%兼顾召回精度标题路径metadata必存检索时可用于过滤、展示给用户做溯源实际项目的调参过程我通常这样迭代先固定一组chunk参数跑20条测试问题统计“检索召回质量”和“生成答案质量”再逐步微调。这里有一个反直觉的经验chunk太短低于200字往往比chunk太长超过2500字对检索质量的伤害更大。因为太短意味着每个chunk的语义信息不够embedding向量区分度差而太长的chunk虽然语义混杂但至少能保证关键词命中——所以宁长勿短是多数场景下的安全牌。当然如果你的业务是“精确引用”比如合同条款问答短chunk反而更合适这个需要结合场景判断。4.4 与向量库、知识库衔接的注意事项解析和切块完成后要写入向量库之前我建议做三件小事。第一空chunk过滤清洗后可能产生大量空白段落、纯标点段落直接过滤掉不要让embedding API为它们付钱也别让它们污染向量库。第二数据去重同一份文档多次导入时先按文本hash去重避免知识库里出现两份相同内容检索时重复命中浪费上下文窗口。第三性能估算embedding有速率限制和成本导入前先统计总字数按1500字/条估算出API调用次数避开业务高峰期批量导入。还有一个小建议向量库不是万能的写入之前先把“标题路径chunk正文”存一份到普通数据库或本地文件方便日后人工审查切片效果。检索效果差的时候能直接回查到底是哪个环节出了问题而不是对着向量库一顿瞎调。这个习惯救过我很多次强烈建议保留。5. 常见问题与排查技巧实录5.1 乱码、错位、合并过度的排查我在实际项目中遇到的第一个高频问题就是乱码。排查思路很简单拿到txt先看前几百字节的十六进制或直接打印前几行判断是什么编码特征。如果显示鋦熕...这类典型GBK乱码直接转码即可如果显示????那多半是原始文件就已经损坏了别在解析层死磕。还有一种情况是“混合编码”比如一个txt大部分是UTF-8但中间夹了一段GBK编码的文本这种情况最麻烦我目前的方案是分段探测编码、分段转码实测能救回来七八成的内容剩下的只能人工处理。第二个高频问题是“合并过度”——两个本应分开的段落被同一个循环合并成了一个chunk。这个通常是清洗阶段空行压缩太激进了把段落边界给压没了。解决方式是把空行压缩规则从\n{3,}改为\n{2,}并且保留至少一个空行作为硬边界切块逻辑里也用“空行优先”原则。还有一个容易忽略的场景Windows环境下txt的换行是\r\n如果清洗逻辑里只处理\n残留的\r会干扰段落识别建议在读取统一转为\n。5.2 表格和代码块被切碎的解决表格在txt里被切碎是我踩过最多的坑之一。文本解析时表格行和普通段落混在一起语义切分很容易把一行表头切到上一个chunk、把剩余数据行切到下一个chunk。我的处理办法是解析阶段识别出表格块之后给整个表格打上is_tableTrue的标记切块阶段对表格块做单独处理——要么整表作为一个chunk表格少于30行时要么按行拆成多个chunk并保留相同的表头路径。代码块同理而且代码块还有缩进问题。如果一行代码开头有两四个空格很多清洗规则会把它误判成“普通缩进段落”然后压缩掉。我的建议是代码块识别要早于清洗一旦识别为代码块进入“隔离通道”不再执行针对普通文本的清洗规则。代码块的另一个坑是“反引号包裹不完整”txt里常有三行代码只配一个反引号的情况生成Markdown后语法不对下游解析器可能把整个后续内容都当成代码块。这种情况我会做“反引号数量奇偶检测”奇数个反引号时自动补一个。5.3 小标题、编号、特殊符号的处理有些txt的“标题”有瑕疵比如1.2.3 这是一个标题。末尾带句号或者3.5.后面没有标题文字。这两种情况如果硬套标题识别规则要么识别不了要么识别出一个空标题。我的处理是两级兜底第一级识别时允许标题行以句号结束但对句号数量做限制最多1个第二级识别出空标题时用「上一个非空标题 _继承」来填充路径保证链路不中断。特殊符号方面Markdown本身有转义需求。正文里如果出现#、*、|、反引号这些Markdown保留字符直接写入会干扰解析所以生成Markdown时需要对它们做转义除非本身处于代码块的隔离通道内。这个细节特别容易忽略但忽略之后你写的Markdown很可能是“无效Markdown”下游解析器会崩。我踩过一次很惨的一篇讲Shell命令的文档里面全是美元符号和反引号没转义直接扔给Markdown解析器结果整个文档结构都乱了。5.4 效率与成本控制最后聊一下工程效率。我见过不少团队在处理几千个txt时直接用一个for循环逐文件处理跑了几个小时才完成。其实这里有很多优化空间。并发处理解析过程是CPU密集型可以用多进程multiprocessing按文件粒度并行一般8~16进程效果最好我实测在16核机器上开12个进程吞吐量能提升七八倍。缓存中间结果清洗后的txt缓存一份Markdown缓存一份。后续如果只是调chunk参数就不用重新走全量解析直接读缓存改切块即可。Embedding批量调用API通常支持batch把chunk攒成一批再发请求吞吐量能提高一截还能降低被限流的概率。增量更新如果文档库是增量更新的维护一个“文件路径hash”的索引只对新文件和hash变化的文件执行全链路解析其余直接跳过。这套优化做完同样的数据量处理时间可以从几小时降到十几分钟非常划算。尤其是增量更新这一点在知识库持续运转的场景下几乎是必须的不然每次加几个文档就要全量重刷一遍成本完全不可接受。写到这里内容已经覆盖了从txt到Markdown再到chunk的全链路。按我自己的经验数据导入这块内容放在整个RAG工程里往往是最枯燥、最不“性感”的部分但它又是决定最终效果的最关键变量。可以说你愿意花多少精力在数据清洗和结构化上你的RAG就能回馈你多少检索精度。这个系列后续如果继续写我会挑几个有意思的深水区展开表格型文档的专门解析、带OCR的扫描件处理以及多级目录体系下的切片策略。希望这次分享的内容能帮你少踩几个坑。