1. 为什么 RAG 的第一步不是模型而是数据导入很多人做 RAG 的第一反应是选模型、调参数、搭向量库结果跑出来的效果一塌糊涂回头一查问题全出在最不起眼的地方——数据导入和解析。我见过太多项目向量库搭得漂漂亮亮检索出来的内容却是断句错乱、表格散架、标题和正文混成一锅粥。模型再强也救不回来因为喂进去的本来就是垃圾。RAG 的全称是检索增强生成它的核心逻辑是“先检索、后生成”。检索的质量直接决定了生成的上限而检索的质量又完全依赖于数据导入阶段把原始文档切成了什么样、保留了多少结构信息。你可以把这一步理解成做菜前的备菜食材没洗干净、切得大小不一后面火候掌握得再好也白搭。这一篇聚焦的是最基础也最容易被忽视的一类数据纯文本 txt 和结构化 Markdown。别看它们格式简单真正要做好通用文本与结构化解析里面的门道比想象中多得多。适合正在搭建 RAG 知识库的开发者、需要批量处理文档的数据工程师以及任何想把散落文本变成可检索知识的人。读完你至少能搞清楚三件事txt 导入时怎么切才不丢语义、Markdown 的结构信息怎么提取成检索友好的格式、以及那些让人抓狂的解析坑怎么提前避开。2. 通用文本与结构化解析的整体设计思路2.1 先搞清楚你的数据到底长什么样动手写代码之前我强烈建议先做一件事把你手头所有待导入的文件列个清单按格式分类统计每种格式的数量和大致内容特征。这一步花不了半小时但能帮你省掉后面几天的返工。txt 文件看似统一实际上内部差异极大。有的是规规矩矩的段落文本每段之间有空行有的是从 PDF 复制出来的换行符乱插一句话被切成好几行还有的是日志或代码压根没有自然语言段落的概念。Markdown 相对规范但同样存在标题层级混乱、代码块和正文混排、表格格式不统一的问题。我的做法是建一张简单的分类表把文件按“结构清晰度”和“内容类型”两个维度打标。结构清晰度分三档有明确标题层级的、有段落但无层级的、完全无结构的。内容类型分叙述型、列表型、代码型、混合型。这张表直接决定了后面用什么解析策略。2.2 解析策略的选型逻辑解析策略的核心矛盾只有一个保留结构信息和保证切块语义完整这两件事经常打架。举个具体例子。一个 Markdown 文件里有个二级标题下面跟了五段正文然后是一个代码块。如果你按固定字数切很可能把标题和它下面的第一段切开检索时用户搜到那段正文却看不到它属于哪个主题上下文就丢了。如果你按标题切遇到超长章节又会导致单块过大超出嵌入模型的上下文窗口。我的选型逻辑是这样的优先按文档自身的结构标记切分结构标记不够用时再用语义或长度兜底。具体来说Markdown 按标题层级切txt 按空行和段落切切完之后再对超长块做二次分割。这个顺序不能反先结构后长度能最大程度保留原文的组织逻辑。为什么不用纯语义切分因为语义切分依赖模型判断句子相似度计算成本高而且对中文长文本的边界判断并不稳定。结构切分是确定性的速度快、结果可复现对于大多数场景已经够用。语义切分适合那种完全没有结构标记、段落也混乱的极端情况属于最后的手段。2.3 元数据设计别只存正文很多人导入数据时只存了文本内容和向量检索出来只有一段光秃秃的文字。这在简单问答里勉强能用但一旦用户问“这个结论出自哪份文档的哪个部分”你就抓瞎了。元数据至少应该包含这几项来源文件名、文件路径、文档标题、章节标题、块在文档中的序号、块的字符数、导入时间。如果文档有版本信息或作者信息也一并存上。这些字段在检索时可以用于过滤和排序在生成时可以拼进上下文让模型知道信息出处。我踩过的一个坑是早期没存章节标题结果检索出来的块虽然内容相关但模型不知道它属于哪个主题生成的回答经常张冠李戴。后来补上章节标题字段检索时把它拼在正文前面一起嵌入效果立竿见影。3. txt 文件解析的核心细节与实操要点3.1 编码识别第一步就能劝退一半人txt 文件最坑的地方不是内容是编码。你以为读出来是正常中文结果全是乱码或者读一半报错。中文 txt 常见的编码有 UTF-8、GBK、GB2312、GB18030还有带 BOM 的 UTF-8。不同来源的文件编码不一样批量处理时如果统一按 UTF-8 读遇到 GBK 文件直接抛异常。我的处理流程是这样的先用chardet或charset-normalizer做编码探测拿到置信度最高的候选编码然后尝试解码。如果解码失败或出现大量替换字符就换下一个候选编码重试。对于中文文本GB18030 是 GBK 和 GB2312 的超集优先用它兜底能覆盖绝大多数情况。import chardet def detect_and_read(file_path): with open(file_path, rb) as f: raw f.read() result chardet.detect(raw) encoding result[encoding] confidence result[confidence] # 置信度低时用 GB18030 兜底 if confidence 0.7: encoding gb18030 try: return raw.decode(encoding) except (UnicodeDecodeError, LookupError): return raw.decode(gb18030, errorsreplace)注意errorsreplace会把无法解码的字符替换成特殊符号虽然不报错但会丢信息。如果对数据完整性要求高应该记录下解码失败的片段人工检查后再决定处理方式。3.2 段落切分空行不是唯一标准txt 的段落切分最直觉的做法是按空行切。但实际文件里空行的形式五花八门有的是一个\n\n有的是\r\n\r\n有的中间夹了空格变成\n \n还有的用连续多个空行做分隔。更麻烦的是有些文件压根没有空行整篇就是一大坨。我的做法是先把所有换行符统一成\n然后用正则\n\s*\n匹配空行分隔。对于没有空行的文件退而求其次按单换行切但这时候要加一个判断如果相邻两行都很短且不以句号、问号、感叹号结尾很可能是同一段被硬换行切开了需要合并。import re def split_paragraphs(text): # 统一换行符 text text.replace(\r\n, \n).replace(\r, \n) # 按空行切分 paragraphs re.split(r\n\s*\n, text) # 过滤空段并去除首尾空白 paragraphs [p.strip() for p in paragraphs if p.strip()] return paragraphs这里有个经验切完之后不要急着嵌入先统计一下段落长度分布。如果发现大量段落只有几个字说明切得太碎如果有个别段落超过几千字说明切得太粗。根据分布情况调整切分参数比盲目调参有效得多。3.3 超长段落的二次分割按段落切完之后总会遇到一些超长段落比如一整章没有空行的内容。这时候需要二次分割。二次分割的策略有两种按句子边界切和按固定长度切。按句子边界切更符合语义但中文句子边界识别本身就有难度省略号、分号、引号内的句号都会干扰判断。我的做法是用一个相对宽松的句子分割规则把句号、问号、感叹号、分号、省略号都当作候选边界然后从候选边界中选一个最接近目标长度的位置切开。def split_long_paragraph(paragraph, max_len500, overlap50): if len(paragraph) max_len: return [paragraph] # 候选边界句末标点 boundaries [m.end() for m in re.finditer(r[。…], paragraph)] chunks [] start 0 while start len(paragraph): end start max_len if end len(paragraph): chunks.append(paragraph[start:]) break # 找最接近 end 的边界 candidates [b for b in boundaries if start b end] if candidates: end candidates[-1] chunks.append(paragraph[start:end]) start end - overlap return chunksoverlap参数的作用是让相邻块之间有重叠内容避免关键信息正好落在切割点上被切断。重叠长度一般设为目标块长度的 10% 到 20%太小起不到保护作用太大则会造成检索结果重复。4. Markdown 结构化解析的完整实操4.1 标题层级提取构建文档骨架Markdown 最大的价值在于它自带结构标记标题的#数量直接反映了层级关系。解析 Markdown 的第一步就是把标题树提取出来构建文档的骨架。我用markdown-it-py或mistune这类解析库把 Markdown 转成 AST然后遍历 AST 提取标题节点。每个标题节点记录三样东西层级、标题文本、在原文中的位置。有了这些信息就能把文档切成以标题为边界的块。from markdown_it import MarkdownIt def extract_headings(md_text): md MarkdownIt() tokens md.parse(md_text) headings [] for i, token in enumerate(tokens): if token.type heading_open: level int(token.tag[1]) # h1 - 1 # 下一个 token 是标题内容 content tokens[i 1].content headings.append({ level: level, text: content, line: token.map[0] if token.map else None }) return headings拿到标题列表后按行号把原文切成若干段每段归属于它前面最近的那个标题。这样每个块都带着自己的章节路径比如“第三章 3.2 节 具体小节”检索时把路径拼进上下文模型就能知道这段内容的来龙去脉。4.2 代码块与表格的特殊处理Markdown 里的代码块和表格是两类特殊内容不能和普通正文一样切。代码块的特点是内部换行有意义不能按空行或句子切。我的做法是把整个代码块作为一个独立的块不拆分。如果代码块特别长按函数或类定义切但这种情况比较少见。代码块的语言标记要保留检索时可以作为过滤条件。表格的处理更麻烦。Markdown 表格在 AST 里是一系列行节点直接按行切会破坏表头和数据行的对应关系。我的做法是把整个表格转成一个结构化的文本表示比如把表头和数据行拼成“列名值”的形式或者保留原始 Markdown 表格作为一个完整块。如果表格行数很多按行分组切但每组都要带上表头。def process_table(table_token): # 简化处理保留原始表格文本作为一个块 # 实际项目中可以转成更紧凑的表示 rows [] for child in table_token.children: if child.type tr: cells [c.content for c in child.children if c.type inline] rows.append( | .join(cells)) return \n.join(rows)提示表格转文本会丢失一些结构信息如果检索场景对表格数据精度要求高建议把表格单独存一份结构化数据检索时通过元数据关联回原表。4.3 列表与引用的处理列表和引用块在 Markdown 里也是结构化的但它们的边界不像标题那么清晰。有序列表和无序列表的每一项都是一个独立的语义单元但项与项之间又有关联。我的处理原则是短列表整体保留为一个块长列表按项切分但保留列表的上下文信息。具体来说如果一个列表总长度不超过目标块大小就整个保留如果超过就按列表项切但每个块前面加上列表所属的章节标题和列表的引导句。引用块的处理类似开头的连续行作为一个整体。引用块往往是重要的观点或结论检索价值高切分时要格外小心尽量不要在引用块内部切开。5. 从解析结果到可检索块的完整流程5.1 块大小与重叠参数的确定块大小是 RAG 里最关键的参数之一直接影响到检索精度和生成质量。块太小单块信息量不足检索出来答不完整块太大噪声多嵌入向量被稀释检索精度下降。我的经验值是中文文本每块 300 到 500 字英文文本每块 200 到 400 词。这个范围是基于嵌入模型的上下文窗口和实际检索效果反复测试出来的。当然这不是铁律具体要看你的文档类型和查询特点。技术文档可以小一点叙述性内容可以大一点。重叠长度设为目标块大小的 10% 到 15%。比如目标块 400 字重叠 40 到 60 字。重叠的作用是防止关键信息正好落在切割点被切断代价是存储和计算量增加。如果文档本身结构清晰、段落边界明确重叠可以设小甚至不设如果文档结构混乱重叠要设大一些。5.2 元数据拼装与嵌入准备每个块在嵌入之前要把元数据拼装好。我的做法是把章节路径和块正文拼成一个字符串再嵌入格式类似“文档标题 章节标题 小节标题\n\n正文内容”。这样嵌入向量里就包含了结构信息检索时用户搜章节相关的词也能命中。元数据字段建议用 JSON 存储和向量一起存入向量库。不同向量库对元数据的支持程度不一样选型时要确认它支持哪些字段类型和过滤操作。常见的过滤需求包括按来源文件过滤、按章节过滤、按时间过滤这些都要在元数据设计阶段考虑进去。def build_chunk(text, metadata): # 拼装嵌入文本 context_parts [] if metadata.get(doc_title): context_parts.append(metadata[doc_title]) if metadata.get(section_path): context_parts.append(metadata[section_path]) embed_text .join(context_parts) \n\n text return { text: text, embed_text: embed_text, metadata: metadata }5.3 批量导入的工程化处理单个文件解析好办成百上千个文件批量导入就需要工程化处理了。核心要解决三个问题并发控制、错误隔离、进度追踪。并发控制方面解析是 CPU 密集型操作嵌入是 IO 密集型操作两者要分开处理。解析可以用多进程并行嵌入用异步批量请求。并发数不要设太高解析并发建议不超过 CPU 核心数嵌入并发要看 API 的限流策略。错误隔离的意思是单个文件解析失败不能影响整批任务。我的做法是每个文件独立处理失败的文件记录到错误日志继续处理下一个。全部处理完后统一查看错误日志针对性地修复。进度追踪用简单的计数器加日志就够了每处理完一个文件打印一次进度。如果文件特别多可以加一个断点续传机制记录已处理的文件列表中断后从断点继续。6. 常见问题与排查技巧实录6.1 编码乱码问题速查现象可能原因解决方法中文显示为问号编码不匹配用 chardet 探测后按探测结果解码部分字符乱码混合编码按 GB18030 解码errors 设为 replace开头有奇怪字符UTF-8 BOM解码后用 lstrip(\ufeff) 去除读取报 UnicodeDecodeError二进制文件误判为文本检查文件头过滤非文本文件编码问题排查的核心思路是先确认文件真实编码再确认读取代码用的编码两者不一致就调整。如果实在搞不定用十六进制编辑器打开文件看前几个字节BOM 和编码特征一目了然。6.2 切块效果不理想的排查思路切块效果不好通常表现为检索出来的块答非所问、块内容不完整、块之间大量重复。排查时按这个顺序来先看块长度分布如果大量块过短或过长调整块大小参数。再看块边界随机抽几个块看切割点是否落在句子中间如果是调整切分规则。最后看重叠设置如果检索结果大量重复说明重叠过大或切分粒度过细。我遇到过一个典型案例某技术文档的 API 说明部分每个接口的参数列表被切成了好几块检索时只能命中部分参数。后来把参数列表整体保留为一个块问题解决。这说明对于结构化程度高的内容要优先保证结构完整性而不是机械地按长度切。6.3 Markdown 解析的典型坑Markdown 解析最常见的坑是嵌套结构处理不当。比如列表里嵌套代码块、引用里嵌套列表、表格单元格里有换行。这些嵌套结构在 AST 里表现为多层节点遍历时如果只处理顶层节点就会丢内容。另一个坑是 HTML 混排。很多 Markdown 文件里嵌了 HTML 标签标准 Markdown 解析器会把它们当普通文本处理导致标签暴露在正文里。解决办法是在解析前先用正则或 HTML 解析库把 HTML 标签清理掉或者配置解析器支持 HTML 渲染。还有一个坑是标题层级跳跃。有的文档从一级标题直接跳到三级标题中间没有二级。按标题切分时如果严格按层级匹配会漏掉内容。我的做法是不依赖层级连续性只按标题出现的位置切每个块记录它前面所有标题的路径不管层级是否连续。6.4 性能优化的几个实用技巧批量处理大文件时性能瓶颈通常在 IO 和嵌入请求上。IO 方面用内存映射或流式读取代替一次性读入能显著降低内存占用。嵌入方面批量请求比单条请求效率高得多但要注意 API 的批量大小限制。缓存也是个好办法。解析结果和嵌入向量都可以缓存重复处理同一文件时直接读缓存。缓存键用文件路径加修改时间文件没变就跳过重新解析。import hashlib import os def get_cache_key(file_path): mtime os.path.getmtime(file_path) raw f{file_path}:{mtime}.encode() return hashlib.md5(raw).hexdigest()这个缓存策略简单有效文件内容变了修改时间就变缓存自动失效。对于频繁更新的文档库能省下大量重复计算。7. 结构化解析的进阶思路7.1 从 Markdown 到知识图谱的映射Markdown 的标题层级天然就是一棵树这棵树可以直接映射成知识图谱的骨架。每个标题是一个节点标题下的内容是节点的属性标题之间的父子关系是图的边。有了这层映射检索时不仅能做向量相似度匹配还能做基于图结构的关联检索。比如用户问“第三章讲了什么”向量检索可能召回一堆零散的块但图结构检索可以直接定位到第三章节点把它下面的所有内容聚合起来。这种结构化检索和向量检索结合能显著提升复杂查询的召回质量。实现上可以在解析 Markdown 时同时输出两份数据一份是用于向量检索的文本块一份是用于图检索的节点和边。两份数据通过块 ID 关联检索时按需选用。7.2 多文档结构对齐当知识库里有多个文档时不同文档的章节结构可能不一致。有的用“第一章”有的用“1.”有的用“Part 1”。这种不一致会导致检索时无法跨文档聚合同一主题的内容。解决办法是建一个章节标题的归一化映射。把各种形式的标题统一成标准格式比如都转成“数字. 标题文本”的形式。归一化之后不同文档的同一主题章节就能对齐检索时可以跨文档召回。这个映射可以手工维护也可以用规则自动生成。规则包括提取标题中的数字、去除修饰词、统一标点符号。对于特别复杂的场景可以用小模型做标题分类但大多数情况下规则就够了。7.3 增量更新与版本管理知识库不是一次建好就完事的文档会更新新文档会加入。增量更新要解决两个问题怎么识别哪些文档变了怎么更新对应的块和向量。识别变更用文件修改时间加内容哈希就够了。更新时先删除旧文档对应的所有块和向量再重新解析导入。这里要注意块 ID 的生成策略如果块 ID 是基于内容哈希生成的内容没变的块 ID 不变可以跳过重新嵌入如果块 ID 是随机生成的每次更新都要全部重新嵌入。版本管理方面建议在元数据里记录文档版本号和导入时间。检索时可以按版本过滤确保用户拿到的是最新版本的内容。如果业务需要追溯历史版本可以把旧版本标记为归档而不是直接删除。8. 我在这套流程里踩过的坑和总结的经验先说一个最容易被忽视的点解析之前一定要做数据抽样检查。我早期做批量导入时直接写了个脚本跑全量结果跑完发现某类文件的解析全错了几千个块白嵌入。后来养成习惯先抽 10 个文件跑一遍人工检查解析结果确认没问题再跑全量。这十分钟的检查能省下几小时的返工。第二个经验是关于块大小的。网上很多教程给一个固定值比如 512 字符但实际项目里这个值要根据文档类型调。我的做法是先跑一遍统计检索命中率和答案完整率然后微调块大小再跑对比效果。一般调两三轮就能找到比较合适的值。别嫌麻烦这个参数对最终效果的影响比换模型还大。第三个经验是关于元数据的。早期我觉得元数据可有可无只存了正文和向量。后来发现检索结果没法溯源用户问“这个说法出自哪里”答不上来。补上元数据后不仅溯源问题解决了还能做按来源过滤、按时间排序这些实用功能。元数据的设计要在导入阶段就做好后期补代价很大。最后一个经验是关于错误处理的。批量导入时总会有各种意外文件损坏、编码异常、解析超时。我的做法是每个文件独立处理失败就记录到错误日志继续下一个全部跑完后统一处理错误日志。这样即使有少量文件失败也不影响整体进度。错误日志要记录足够的信息文件路径、错误类型、错误堆栈、处理到的步骤方便定位问题。这套流程跑通之后txt 和 Markdown 的导入基本就是流水线作业了。下一篇我会讲 PDF 和 Word 这类带复杂排版的文档怎么解析那才是真正的硬骨头。如果你现在手头正好有 Markdown 知识库要搭建议先把标题层级和代码块这两块处理好这两类内容在技术文档里占比最高处理好了效果提升最明显。